godgrep

godgrep

根据意图将代码库搜索任务路由到合适的工具。

工具路由

意图	主要工具	也可考虑
关键词／符号搜索（已知确切标识符）	mcp__plugin_ora_fff__grep	使用 LSP 查找定义
多模式 OR 搜索——同一标识符的命名变体	mcp__plugin_ora_fff__multi_grep	依次调用 mcp__plugin_ora_fff__grep
文件发现（按名称）	mcp__plugin_ora_fff__find_files	使用 mcp__plugin_ora_fff__grep 匹配内容
概念／“X 如何运作”／“Y 在哪里处理”（尚无标识符）	mcp__plugin_ora_morph__codebase_search	仅当 morph 未找到结果时，才回退到 find_files + fff__grep + Read
端到端追踪某项功能	使用 mcp__plugin_ora_morph__codebase_search 绘制初始图谱	使用 mcp__plugin_ora_fff__grep 验证特定调用位置
查找 X 的所有用法	LSP 查找引用	mcp__plugin_ora_fff__grep
查找特定符号	LSP 跳转到定义	mcp__plugin_ora_fff__grep
结构化代码模式	ast-grep	回退时使用 mcp__plugin_ora_fff__grep
Git 索引之外／回退	shell grep / find	最后手段，在 fff 之后使用
Git 历史／追责	Bash（git log/blame）	—

当问题涉及单个宽泛概念时，一次 mcp__plugin_ora_morph__codebase_search 调用即可替代多角度并行搜索。只有当任务包含多个相互独立、基于标识符的搜索时（例如“一次查找 X 的调用方和 Y 的定义”），才拆分为 2-3 个并行角度。

反模式：针对功能进行大范围 OR-grep

不要用一个很长的 OR 模式枚举某项功能的各种猜测——这样会漏掉同义词，输出也会被噪声淹没：

# Shotgun-grep — fragile, no signal
grep -r "FreeGift|ProgressBar|GiftModal|BuyXGetY|percentOff|fixedOff|salepify"
grep -r "appUpdate|checkAppUpdate|versionCheck|setAppUpdateHandler|needUpdate"

改为：先浏览 README／目录结构，了解该功能的实际名称，选取一个具体词语进行 grep，阅读最匹配的结果，然后沿着引用继续查找。multi_grep 用于同一标识符的命名变体（例如 ['ActorAuth', 'PopulatedActorAuth', 'actor_auth']），而不是用来猜测某项功能的词汇。

Morph codebase_search——语义／概念查询的默认选择

mcp__plugin_ora_morph__codebase_search 会运行 Morph WarpGrep 子 Agent，并行执行 grep 和读取文件，然后返回综合答案。遇到如下问题时，优先使用它：“X 是如何工作的”“Y 在哪里处理”“什么将 Z 连接起来”“找出所有执行 W 的位置”。对于这类问题，一次 morph 调用胜过 4-8 次 fff__grep + Read 操作。

• 适用场景：问题属于概念／语义类，或是“查找与 X 相关的代码”，且没有可用于 grep 的单一确切标识符。原因：morph 会并行执行调用 Agent 原本需要串行完成的 grep + 读取 + 总结流程，大幅减少延迟和交互轮数。
• 不适用场景：已有具体标识符——fff__grep 更快、更全面，而且一次调用就能返回精确的 file:line 命中结果。
• 相信引用，核实结论——morph 的 file:line 引用指向真实代码位置，但它的综合分析（代码的作用，以及代码如何契合问题）可能有误。答案至关重要时，请 Read 引用的位置，并在转述前确认 morph 的解读。

ast-grep

使用抽象语法树模式进行结构化代码搜索。按代码结构匹配，而非搜索文本。

模式搜索

ast-grep run --pattern '<pattern>' --lang <lang> <path>

# Find all console.log calls
ast-grep run --pattern 'console.log($ARG)' --lang javascript .

# Find class declarations
ast-grep run --pattern 'class $NAME' --lang python /path/to/project

复杂规则

内联 YAML（快速迭代，无需临时文件）：

ast-grep scan --inline-rules "<yaml>" <path>

# Find async functions containing await
ast-grep scan --inline-rules "id: async-await
language: javascript
rule:
  kind: function_declaration
  has:
    pattern: await \$EXPR
    stopBy: end" /path/to/project

规则文件（复杂规则的推荐方式）：

# Write rule to a temp file, then scan
ast-grep scan --rule /tmp/my_rule.yml /path/to/project

AST 检查

ast-grep run --pattern '<code>' --lang <lang> --debug-query=cst

规则无法匹配时，使用 --debug-query=cst 输出具体语法树，并查找正确的 kind 值。可用格式：cst（所有节点）、ast（仅命名节点）、pattern（ast-grep 对模式的解析方式）。

关键规则

• 关系规则（inside、has）始终使用 stopBy: end——否则，搜索会在第一个不匹配的节点处停止，而不会遍历整个子树：

has:
  pattern: await $EXPR
  stopBy: end # required for deep traversal

• 在 Shell 中转义元变量：在双引号字符串中使用 \$VAR，或在单引号字符串中使用 '$VAR'
• 从简单的模式开始；仅在需要时添加 kind 和关系规则
• 使用 all／any／not 组合复杂的结构化查询

参考：完整指南见 references/ast-grep/ast-grep.md，YAML 规则语法见 references/ast-grep/rule_reference.md。

---

如果 mcp__plugin_ora_fff__grep／mcp__plugin_ora_fff__find_files／LSP 足以满足需求，就不要使用 ast-grep——它速度较慢，也会消耗更多资源。只有当搜索需要理解代码结构，而不只是搜索文本时，才升级使用 ast-grep。