用途
github-codebase-search 用于对公开 GitHub 仓库进行语义搜索，无需在本地克隆代码。它由 MorphLLM 驱动，后者是一个经过强化学习训练的子代理，会针对 GitHub API 并行执行 grep 与读取调用，从而以自然语言回答关于代码的问题。
它主要面向以下场景：
- 理解某个库或框架内部是如何工作的（例如“Next.js 如何解析 middleware？”）。
- 调查开源依赖中的上游缺陷或行为。
- 从知名仓库的参考实现中学习。
- 追踪一个你尚未在本地克隆的仓库中的代码路径。
- 探索某个开源项目的结构或架构。
主要能力
- 以自然语言问题为输入，对指定 GitHub 仓库执行语义搜索。
- 搜索代理会根据你的问题自行规划搜索策略，因此自然语言问题比关键词更有效。
- 支持通过 owner/repo 形式或完整 GitHub URL 指定仓库。
- 支持指定分支（--branch）。
- 支持调整超时（--timeout），默认超时为 120 秒，大型仓库可提高到 180 或更高。
- 输出会列出相关文件及其内容，例如：
Morph Fast Context subagent performed search on repository:
Relevant context found:
- src/routes/middleware.ts:*
- src/core/router.ts:50-120
Here is the content of files:
<file path="src/routes/middleware.ts">
1| import { NextRequest } from 'next/server';
2| export function middleware(request: NextRequest) {
...
</file>
<file path="src/core/router.ts">
50| function resolveMiddleware(chain: MiddlewareChain) {
...
120| }
</file>
如果文件路径不正确，可能会看到 Error: File not found，此时应使用更具体的查询重试。
使用方式
需要设置 MORPH_API_KEY 环境变量。
不要阅读脚本源码，直接运行脚本，并使用 --help 查看用法。
运行一次语义搜索：
python3 scripts/github-codebase-search.py search "<natural language query>" --repo <owner/repo>
参数说明：
- query — 关于代码的自然语言问题。
- --repo — owner/repo 格式的 GitHub 仓库（例如 vercel/next.js）。
- --url — 替代方式，完整的 GitHub URL（例如 https://github.com/vercel/next.js）。
必须提供 --repo 或 --url 之一。
示例：
# Search by owner/repo
python3 scripts/github-codebase-search.py search "how does the router resolve middleware" --repo vercel/next.js
# Search by GitHub URL
python3 scripts/github-codebase-search.py search "how does the router resolve middleware" --url https://github.com/vercel/next.js
# Search a specific branch
python3 scripts/github-codebase-search.py search "how are migrations handled" --repo prisma/prisma --branch main
# Increase timeout for large repos
python3 scripts/github-codebase-search.py search "trace the build pipeline" --repo facebook/react --timeout 180
完整用法可运行：
python3 scripts/github-codebase-search.py --help
适用场景与选择规则
判断规则：
- 代码在 GitHub 上且未在本地克隆？使用 github-codebase-search。
- 代码在本地仓库？使用 codebase-search。
任务与工具对应示例：
- “Next.js 如何解析 API 路由？”使用 github-codebase-search。
- “我们的 auth middleware 如何工作？”使用 codebase-search。
- “Prisma 内部如何处理迁移？”使用 github-codebase-search。
- “我们的数据库中配置在哪里？”使用 codebase-search。
- “React 的 reconciler 如何处理 fibers？”使用 github-codebase-search。
- “React 文档对 useEffect 怎么说？”使用 context7。
限制
不要在以下情况使用：
- 关于本地代码库的问题——应使用 codebase-search。
- 私有仓库（需要 GitHub API 访问权限）。
- 简单文档查找——应使用 context7。
- 简单 GitHub 界面浏览（查看 README、issue、PR）。
编写查询的建议
- 把查询写成自然语言问题。例如“How does the router resolve middleware chains?”比“router middleware”效果好得多，因为搜索代理会根据你的问题自行规划策略。
- 明确你想知道什么。“How does Prisma handle relation loading in findMany?”优于“Prisma relations”。
- 提供 owner/repo 或 URL，工具需要知道要搜索哪个 GitHub 仓库。
- 默认超时为 120 秒，大型仓库可用 --timeout 180 或更高值增加。