用途
codebase-search 是一个语义化本地搜索工具，由 MorphLLM（一个经强化学习训练的 subagent）驱动。它运行约 15-30 次内部 grep 与读取操作，用来回答关于任意项目文件的自然语言问题，覆盖代码、配置、文档、markdown、YAML、JSON 以及其他文本文件。
与简单的 grep 不同，它理解查询意图，并能追踪跨文件的流程。
使用前需要设置 MORPH_API_KEY 环境变量。
适用场景
- 理解某个功能如何跨多个文件工作（例如“auth 中间件是如何校验 token 的？”）
- 端到端追踪数据流（例如“当用户点击结账时会发生什么？”）
- 探索不熟悉的项目，不知道应该 grep 什么内容
- 回答架构性问题（例如“数据库层是如何组织的？”）
- 调试连接关系不明显的跨文件交互
- 在非代码文件中查找信息——配置、文档、markdown、YAML、JSON（例如“插件钩子是如何配置的？”）
不适用场景
- 简单的关键词或符号搜索（例如查找 handleSubmit 的所有使用处）——应使用 Grep
- 按名称或模式查找文件——应使用 Glob
- 查阅库文档——应使用 context7
- 与当前代码库无关的问题
选择规则
- 你能自己写出 grep 模式吗？能，就用 Grep——它更快。
- 因为问题偏概念性而写不出模式？那就用 codebase-search。
| 任务 | 工具 |
|---|---|
| 查找 AuthService 的所有 import | Grep |
| AuthService 是如何校验 token 的？ | codebase-search |
| 查找名为 *.config.ts 的文件 | Glob |
| 配置系统是如何组织的？ | codebase-search |
| 查找 TODO 注释 | Grep |
| 支付流程中还有什么未完成？ | codebase-search |
使用方式
不要阅读脚本源代码。直接运行脚本，并用 --help 查看用法。
运行语义搜索：
python3 scripts/codebase-search.py search "<自然语言查询>" [repo_path]
- query — 关于代码的自然语言问题
- repo_path — 仓库根路径（默认为当前目录）
示例：
# 搜索当前仓库
python3 scripts/codebase-search.py search "how does the authentication flow work"
# 搜索指定仓库
python3 scripts/codebase-search.py search "how are database migrations handled" /path/to/repo
# 搜索包含 node_modules
python3 scripts/codebase-search.py search "how does the router resolve paths" --search-type node_modules
# 为大型代码库增加超时时间
python3 scripts/codebase-search.py search "trace the payment processing pipeline" --timeout 180
运行 python3 scripts/codebase-search.py --help 查看完整用法。
示例输出
Morph Fast Context subagent 在仓库上执行了搜索，输出相关上下文文件列表及文件内容（包含文件路径与逐行内容），例如：
Relevant context found:
- plugins/ora/agents/ariadne.md:*
- plugins/ora/agents/clio.md:*
- plugins/ora/agents/metis.md:*
Here is the content of files:
<file path="plugins/ora/agents/ariadne.md">
1| ---
2| name: Ariadne
3| description: |
4| Use this agent to explore and understand codebases...
...
35| tools: ["Read", "Glob", "Grep", "LSP", "Bash"]
36| skills:
37| - codebase-search
38| ---
</file>
输出会列出找到的相关文件及其完整内容。直接使用这些结果——不要用 Grep/Read 重新搜索相同文件。
规则
- 将查询写成自然语言问题——“How does the auth middleware validate JWT tokens?” 比 “auth JWT” 效果好得多，因为 codebase search 是一个经强化学习训练的 agent，会根据你的问题自行规划搜索策略。
- 具体说明你想知道什么——“What happens when a user submits the settings form?” 优于 “settings form”。你提供的上下文越多，它就越能精准地定位内部搜索。
- 用于理解，而非查找——如果你已经知道符号或关键词，Grep 更快。codebase-search 的优势在于你不知道该找什么的时候。
- 默认超时为 120 秒——codebase search 会运行多次内部操作。对于大型代码库，用 --timeout 180 或更高来增加超时。