Back to Details

search-hierarchy

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Search Tool Hierarchy

搜索工具层级体系

Use the most token-efficient search tool for each query type.
根据查询类型选用最具Token效率的搜索工具。

Decision Tree

决策树

Query Type?
├── STRUCTURAL (code patterns)
│   → AST-grep (~50 tokens output)
│   Examples: "def foo", "class Bar", "import X", "@decorator"
│
├── SEMANTIC (conceptual questions)
│   → LEANN (~100 tokens if path-only)
│   Examples: "how does auth work", "find error handling patterns"
│
├── LITERAL (exact identifiers)
│   → Grep (variable output)
│   Examples: "TemporalMemory", "check_evocation", regex patterns
│
└── FULL CONTEXT (need complete understanding)
    → Read (1500+ tokens)
    Last resort after finding the right file
Query Type?
├── STRUCTURAL (code patterns)
│   → AST-grep (~50 tokens output)
│   Examples: "def foo", "class Bar", "import X", "@decorator"
│
├── SEMANTIC (conceptual questions)
│   → LEANN (~100 tokens if path-only)
│   Examples: "how does auth work", "find error handling patterns"
│
├── LITERAL (exact identifiers)
│   → Grep (variable output)
│   Examples: "TemporalMemory", "check_evocation", regex patterns
│
└── FULL CONTEXT (need complete understanding)
    → Read (1500+ tokens)
    Last resort after finding the right file

Token Efficiency Comparison

Token效率对比

ToolOutput SizeBest For
AST-grep~50 tokensFunction/class definitions, imports, decorators
LEANN~100 tokensConceptual questions, architecture, patterns
Grep~200-2000Exact identifiers, regex, file paths
Read~1500+Full understanding after finding the file
工具输出大小适用场景
AST-grep~50 tokens函数/类定义、导入语句、装饰器
LEANN~100 tokens概念性问题、架构、模式
Grep~200-2000精确标识符、正则表达式、文件路径
Read~1500+找到目标文件后全面理解内容

Hook Enforcement

钩子强制机制

The 
grep-to-leann.sh
hook automatically:
  1. Detects query type (structural/semantic/literal)
  2. Blocks and suggests AST-grep for structural queries
  3. Blocks and suggests LEANN for semantic queries
  4. Allows literal patterns through to Grep
grep-to-leann.sh
钩子会自动：
  1. 检测查询类型（结构型/语义型/字面型）
  2. 拦截结构型查询并推荐使用AST-grep
  3. 拦截语义型查询并推荐使用LEANN
  4. 允许字面型模式通过Grep执行

DO

建议做法

  • Start with AST-grep for code structure questions
  • Use LEANN for "how does X work" questions
  • Use Grep only for exact identifier matches
  • Read files only after finding them via search
  • 针对代码结构问题，优先使用AST-grep
  • 针对"X如何工作"类问题，使用LEANN
  • 仅在匹配精确标识符时使用Grep
  • 仅在通过搜索找到目标文件后再读取文件内容

DON'T

禁止做法

  • Use Grep for conceptual questions (returns nothing)
  • Read files before knowing which ones are relevant
  • Use Read when AST-grep would give file:line
  • Ignore hook suggestions
  • 针对概念性问题使用Grep（不会返回有效结果）
  • 在确定相关文件前就读取文件
  • 当AST-grep可以返回文件:行号时使用Read
  • 忽略钩子的建议

Examples

示例

bash
undefined
bash
undefined

STRUCTURAL → AST-grep

STRUCTURAL → AST-grep

ast-grep --pattern "async def $FUNC($$$):" --lang python
ast-grep --pattern "async def $FUNC($$$):" --lang python

SEMANTIC → LEANN

SEMANTIC → LEANN

leann search opc-dev "how does authentication work" --top-k 3
leann search opc-dev "how does authentication work" --top-k 3

LITERAL → Grep

LITERAL → Grep

Grep pattern="check_evocation" path=opc/scripts
Grep pattern="check_evocation" path=opc/scripts

FULL CONTEXT → Read (after finding file)

FULL CONTEXT → Read (after finding file)

Read file_path=opc/scripts/z3_erotetic.py
undefined
Read file_path=opc/scripts/z3_erotetic.py
undefined

Optimal Flow

最优流程

1. AST-grep: "Find async functions" → 3 file:line matches
2. Read: Top match only → Full understanding
3. Skip: 4 irrelevant files → 6000 tokens saved
1. AST-grep: "Find async functions" → 3个file:line匹配结果
2. Read: 仅读取排名靠前的匹配文件 → 全面理解内容
3. 跳过: 4个无关文件 → 节省6000+ Tokens