feat(retrieval): add structural path constraints and hints extraction

Add optional path_constraint field to SubQuery to store structural
path constraints extracted from queries (e.g. "3.2", "Chapter 5").

Add resolved_path_hints field to PipelineContext to store node IDs
extracted from structural queries.

Implement Chinese number parsing utility function to convert
Chinese numerals to integers (e.g. "三" → 3, "二十一" → 21).

Add extract_structure_hints method to recognize and map various
structural patterns including:
- Chinese chapter/section patterns: "第X章", "第X节", "第一章"
- English section numbers: "Section 3.2", "section 4.1.2"
- Chapter references: "Chapter 5", "chapter 10"
- Bare section numbers: "3.2.1", "2.1"
- Table/Figure references: "表3", "Table 5", "图2", "Figure 4"

Integrate structure hints into search stage by injecting them as
high-priority search cues with confidence score of 1.0.

Update all relevant initialization code to include the new fields
in tests and implementation.

Author: zTgx

rust/src/retrieval/decompose.rs

@@ -64,6 +64,10 @@ pub struct SubQuery {
     pub depends_on: Vec<usize>,
     /// Type of sub-query.
     pub query_type: SubQueryType,
+    /// Optional structural path constraint extracted from the query
+    /// (e.g. "3.2", "Chapter 5"). When set, the search should start
+    /// from the corresponding tree node instead of searching broadly.
+    pub path_constraint: Option<String>,
 }
 
 /// Complexity level for a sub-query.
@@ -130,6 +134,7 @@ impl DecompositionResult {
                 priority: 0,
                 depends_on: vec![],
                 query_type: SubQueryType::Fact,
+                path_constraint: None,
             }],
             was_decomposed: false,
             reason: reason.to_string(),
@@ -338,6 +343,7 @@ impl QueryDecomposer {
                     priority: i as u8,
                     depends_on: vec![],
                     query_type: self.detect_query_type(part),
+                    path_constraint: None,
                 });
             }
         }
@@ -359,6 +365,7 @@ impl QueryDecomposer {
                                     vec![]
                                 },
                                 query_type: self.detect_query_type(part),
+                                path_constraint: None,
                             });
                         }
                         break;
@@ -666,13 +673,15 @@ mod tests {
                 depends_on: vec![],
                 query_type: SubQueryType::Fact,
                 complexity: SubQueryComplexity::Simple,
+                path_constraint: None,
             },
             SubQuery {
                 text: "Second".to_string(),
                 priority: 1,
                 depends_on: vec![0],
                 query_type: SubQueryType::Fact,
                 complexity: SubQueryComplexity::Simple,
+                path_constraint: None,
             },
         ];
         result.was_decomposed = true;
@@ -711,6 +720,7 @@ mod tests {
                     depends_on: vec![],
                     query_type: SubQueryType::Fact,
                     complexity: SubQueryComplexity::Simple,
+                    path_constraint: None,
                 },
                 content: "Answer 1".to_string(),
                 score: 0.9,
@@ -723,6 +733,7 @@ mod tests {
                     depends_on: vec![0],
                     query_type: SubQueryType::Fact,
                     complexity: SubQueryComplexity::Simple,
+                    path_constraint: None,
                 },
                 content: "Answer 2".to_string(),
                 score: 0.8,

rust/src/retrieval/pipeline/context.rs

@@ -11,8 +11,8 @@ use std::sync::Arc;
 use std::time::Instant;
 
 use crate::document::{DocumentTree, NodeId, RetrievalIndex};
-use crate::retrieval::pilot::Pilot;
 use crate::retrieval::pipeline::budget::RetrievalBudgetController;
+use crate::retrieval::pilot::Pilot;
 use crate::retrieval::types::{
     NavigationDecision, QueryComplexity, ReasoningChain, ReasoningStep, RetrieveOptions,
     RetrieveResponse, SearchPath, StageName, StrategyPreference, SufficiencyLevel,
@@ -212,6 +212,9 @@ pub struct PipelineContext {
     pub keywords: Vec<String>,
     /// Target sections from ToC matching.
     pub target_sections: Vec<String>,
+    /// Resolved structural path hints — node IDs extracted from the query
+    /// (e.g. "第3章" → NodeId of Chapter 3). Search should start from these nodes.
+    pub resolved_path_hints: Vec<(String, NodeId)>,
     /// Decomposed sub-queries (if query was decomposed).
     pub decomposition: Option<crate::retrieval::decompose::DecompositionResult>,
 
@@ -275,6 +278,7 @@ impl PipelineContext {
             complexity: None,
             keywords: Vec::new(),
             target_sections: Vec::new(),
+            resolved_path_hints: Vec::new(),
             decomposition: None,
             selected_strategy: None,
             selected_algorithm: None,

rust/src/retrieval/stages/analyze.rs

@@ -12,7 +12,7 @@
 use async_trait::async_trait;
 use tracing::info;
 
-use crate::document::{DocumentTree, TocView};
+use crate::document::{DocumentTree, NodeId, TocView};
 use crate::retrieval::complexity::ComplexityDetector;
 use crate::retrieval::decompose::{DecompositionConfig, QueryDecomposer};
 use crate::retrieval::pipeline::{FailurePolicy, PipelineContext, RetrievalStage, StageOutcome};
@@ -29,6 +29,56 @@ use crate::llm::LlmClient;
 ///
 /// # Example
 ///
+/// Convert Chinese number string to integer (e.g. "三" → 3, "二十一" → 21).
+fn chinese_num_to_int(s: &str) -> Option<usize> {
+    let chars: Vec<char> = s.chars().collect();
+    if chars.is_empty() {
+        return None;
+    }
+    // If purely digits, parse directly
+    if chars.iter().all(|c| c.is_ascii_digit()) {
+        return s.parse().ok();
+    }
+    let map = |c: char| -> usize {
+        match c {
+            '一' => 1, '二' => 2, '三' => 3, '四' => 4, '五' => 5,
+            '六' => 6, '七' => 7, '八' => 8, '九' => 9, '十' => 10,
+            '百' => 100,
+            _ => 0,
+        }
+    };
+    // Simple two-pass: handle 十/百 as positional
+    let mut total: usize = 0;
+    let mut current: usize = 0;
+    for &c in &chars {
+        let v = map(c);
+        if v == 0 {
+            continue;
+        }
+        if v >= 10 {
+            // Positional multiplier
+            let base = if current == 0 { 1 } else { current };
+            total += base * v;
+            current = 0;
+        } else {
+            current = v;
+        }
+    }
+    total += current;
+    if total > 0 { Some(total) } else { None }
+}
+
+/// Analyze Stage - analyzes queries for retrieval planning.
+///
+/// This stage:
+/// 1. Detects query complexity (Simple/Medium/Complex)
+/// 2. Extracts keywords for matching
+/// 3. Matches target sections from ToC
+/// 4. Extracts structural path hints (Section 3.2, 第3章, etc.)
+/// 5. Decomposes complex queries into sub-queries (if enabled)
+///
+/// # Example
+///
 /// ```rust,ignore
 /// let stage = AnalyzeStage::new()
 ///     .with_toc_matching(true)
@@ -145,6 +195,87 @@ impl AnalyzeStage {
             .collect()
     }
 
+    /// Extract structural path hints from the query.
+    ///
+    /// Recognizes patterns like:
+    /// - "第3章", "第2节", "第一章" (Chinese chapter/section)
+    /// - "Section 3.2", "section 4.1.2" (English section numbers)
+    /// - "Chapter 5", "chapter 10" (English chapter)
+    /// - "3.2.1", "2.1" (bare section numbers)
+    /// - "表3", "Table 5", "图2", "Figure 4" (table/figure references)
+    ///
+    /// Maps them to tree NodeIds via `find_by_structure()`.
+    fn extract_structure_hints(&self, query: &str, tree: &DocumentTree) -> Vec<(String, NodeId)> {
+        let mut hints = Vec::new();
+
+        // Chinese patterns: 第X章, 第X节, 第X部分
+        for cap in regex::Regex::new(r"第([一二三四五六七八九十百\d]+)[章节部分]")
+            .unwrap()
+            .captures_iter(query)
+        {
+            let num = chinese_num_to_int(&cap[1]).unwrap_or(0);
+            if num > 0 {
+                if let Some(node_id) = tree.find_by_structure(&num.to_string()) {
+                    hints.push((cap[0].to_string(), node_id));
+                }
+            }
+        }
+
+        // "Section X.Y.Z" or "section X.Y"
+        for cap in regex::Regex::new(r"(?i)section\s+(\d+(?:\.\d+)*)")
+            .unwrap()
+            .captures_iter(query)
+        {
+            if let Some(node_id) = tree.find_by_structure(&cap[1]) {
+                hints.push((cap[0].to_string(), node_id));
+            }
+        }
+
+        // "Chapter X"
+        for cap in regex::Regex::new(r"(?i)chapter\s+(\d+)")
+            .unwrap()
+            .captures_iter(query)
+        {
+            if let Some(node_id) = tree.find_by_structure(&cap[1]) {
+                hints.push((cap[0].to_string(), node_id));
+            }
+        }
+
+        // Bare section numbers: "3.2.1", "2.1"
+        for cap in regex::Regex::new(r"(?<!\w)(\d+\.\d+(?:\.\d+)*)")
+            .unwrap()
+            .captures_iter(query)
+        {
+            if let Some(node_id) = tree.find_by_structure(&cap[1]) {
+                hints.push((cap[0].to_string(), node_id));
+            }
+        }
+
+        // Table/Figure references
+        for cap in regex::Regex::new(r"(?:表|(?i)table)\s*(\d+)")
+            .unwrap()
+            .captures_iter(query)
+        {
+            if let Some(node_id) = tree.find_by_structure(&format!("table {}", &cap[1])) {
+                hints.push((cap[0].to_string(), node_id));
+            }
+        }
+        for cap in regex::Regex::new(r"(?:图|(?i)figure)\s*(\d+)")
+            .unwrap()
+            .captures_iter(query)
+        {
+            if let Some(node_id) = tree.find_by_structure(&format!("figure {}", &cap[1])) {
+                hints.push((cap[0].to_string(), node_id));
+            }
+        }
+
+        // Deduplicate by NodeId
+        let mut seen = std::collections::HashSet::new();
+        hints.retain(|(_, nid)| seen.insert(*nid));
+
+        hints
+    }
+
     /// Match target sections from ToC.
     fn match_toc_sections(&self, query: &str, tree: &DocumentTree) -> Vec<String> {
         if !self.enable_toc_matching {
@@ -232,6 +363,16 @@ impl RetrievalStage for AnalyzeStage {
             info!("Target sections: {:?}", ctx.target_sections);
         }
 
+        // 3.5 Extract structural path hints
+        ctx.resolved_path_hints = self.extract_structure_hints(&ctx.query, &ctx.tree);
+        if !ctx.resolved_path_hints.is_empty() {
+            info!(
+                "Resolved {} structure hints: {:?}",
+                ctx.resolved_path_hints.len(),
+                ctx.resolved_path_hints.iter().map(|(s, _)| s).collect::<Vec<_>>()
+            );
+        }
+
         // 4. Decompose query if enabled and complex enough
         if self.enable_decomposition {
             if let Some(ref decomposer) = self.query_decomposer {
@@ -279,6 +420,12 @@ impl RetrievalStage for AnalyzeStage {
         if !ctx.target_sections.is_empty() {
             reasoning_parts.push(format!("Target sections: {:?}", ctx.target_sections));
         }
+        if !ctx.resolved_path_hints.is_empty() {
+            reasoning_parts.push(format!(
+                "Structure hints: {:?}",
+                ctx.resolved_path_hints.iter().map(|(s, _)| s).collect::<Vec<_>>()
+            ));
+        }
         if let Some(ref decomp) = ctx.decomposition {
             if decomp.was_decomposed {
                 reasoning_parts.push(format!(

rust/src/retrieval/stages/search.rs

@@ -383,13 +383,26 @@ impl RetrievalStage for SearchStage {
             .map(|nodes| nodes.to_vec())
             .unwrap_or_else(|| ctx.tree.children(ctx.tree.root()));
 
-        let cues = self
+        let mut cues = self
             .toc_navigator
             .locate(&ctx.query, &ctx.tree, &top_level_nodes)
             .await;
 
         debug!("ToCNavigator returned {} cues", cues.len());
 
+        // Inject structure hints from Analyze stage as high-priority cues
+        if !ctx.resolved_path_hints.is_empty() {
+            for (hint_text, node_id) in &ctx.resolved_path_hints {
+                if ctx.tree.get(*node_id).is_some() {
+                    info!("Injecting structure hint '{}' as search cue", hint_text);
+                    cues.push(SearchCue {
+                        root: *node_id,
+                        confidence: 1.0, // Direct match from query structure
+                    });
+                }
+            }
+        }
+
         // === Resolve queries (decomposed or original) ===
         let queries = Self::resolve_queries(ctx);