godgrep

godgrep 是一个按意图路由代码库搜索任务的技能，目标是在本地代码库搜索中，把不同类型的问题分派给最合适的搜索工具，而不是用同一种方式处理所有检索。

一、用途 当需要在代码库中查找代码模式、追踪某个功能如何端到端实现、查找符号与用法，或定位某个概念相关代码时，godgrep 提供了一套工具选择与路由规则，帮助选择合适的检索方式。

二、主要能力与工具路由 技能给出了“意图 → 主工具 → 备选”的路由表：

1. 关键词/符号搜索（已知确切标识符）：主用 mcp__plugin_ora_fff__grep，也可考虑用 LSP 查找定义。
2. 多模式 OR —— 同一标识符的命名变体：主用 mcp__plugin_ora_fff__multi_grep，也可用多次串行的 mcp__plugin_ora_fff__grep 调用。
3. 文件发现（按文件名）：主用 mcp__plugin_ora_fff__find_files，也可用 mcp__plugin_ora_fff__grep 做内容匹配。
4. 概念类问题（“X 怎么工作”“Y 在哪里处理”，尚无标识符）：主用 mcp__plugin_ora_morph__codebase_search；仅当 morph 未命中时，退回 find_files + fff__grep + Read。
5. 端到端追踪功能：先用 mcp__plugin_ora_morph__codebase_search 建立初始地图，再用 mcp__plugin_ora_fff__grep 核实具体调用点。
6. 查找 X 的所有用法：优先 LSP find-references，其次 mcp__plugin_ora_fff__grep。
7. 查找特定符号：优先 LSP go-to-definition，其次 mcp__plugin_ora_fff__grep。
8. 结构化代码模式：使用 ast-grep，回退方案为 mcp__plugin_ora_fff__grep。
9. 不在 git 索引内或兜底：使用 shell grep / find，且在 fff 之后作为最后手段。
10. Git 历史/blame：使用 Bash（git log/blame）。

三、语义搜索（Morph codebase_search）使用方式 mcp__plugin_ora_morph__codebase_search 会运行一个 Morph WarpGrep 子智能体，并行执行 grep 与读文件，返回综合答案。当问题形如“X 怎么工作”“Y 在哪里处理”“什么把 Z 串起来”“找出所有做 W 的地方”时，应优先使用它。一次 morph 调用在这些问题形态上胜过 4–8 轮 fff__grep + Read。适用条件：问题是概念性/语义性的、需要“查找与 X 相关的代码”，且没有单一确切标识符可 grep。当有具体标识符时不要用它——fff__grep 更快、更彻底，且一次调用即返回精确的 file:line 命中。若问题是单一宽泛概念，一次 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 它，Read 命中的头部结果，并顺藤摸瓜跟随引用。multi_grep 用于同一标识符的命名变体（例如 ['ActorAuth', 'PopulatedActorAuth', 'actor_auth']），而不是用来猜测功能的词汇表。 关于 Morph 的引用：morph 的 file:line 引用指向真实代码位置，但其综合结论（该代码做什么、如何契合问题）可能出错。当答案很关键时，应 Read 所引用的位置，在转述前确认 morph 的解释。

五、ast-grep：结构化搜索 使用抽象语法树（AST）模式进行结构化代码搜索，按结构而非文本匹配代码。 模式搜索： 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 如何解释你的模式）。

关键规则：

1. 关系规则（inside、has）中始终使用 stopBy: end，否则搜索会在遇到第一个不匹配节点时停止，而不会遍历整个子树： has: pattern: await $EXPR stopBy: end # required for deep traversal
2. 在 shell 中转义元变量：双引号字符串中使用 $VAR，或单引号字符串中使用 '$VAR'。
3. 从简单开始（先用 pattern），仅在需要时添加 kind 与关系规则。
4. 使用 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。

六、适用场景 已知确切标识符的关键词/符号检索、按文件名查找文件、多命名变体的 OR 检索、概念性/语义性问题、端到端功能追踪、查找符号与用法、结构化代码模式匹配、非 git 索引内容兜底搜索、Git 历史与 blame 查询。

七、限制与注意事项 不要用长 OR 模式做功能词猜测；有具体标识符时应优先 fff__grep 而非 morph；morph 的结论需通过阅读引用位置核实；ast-grep 在文本匹配足够时不建议使用；关系规则缺少 stopBy: end 会导致遍历不完整。资料未提供关于收费、价格、平台或效果的信息。