godfetch

godfetch

统一的外部研究——通过单个技能查询库文档、搜索任意 git 仓库中的源代码，并检查软件包版本。

路由

意图	首选工具	备用工具
库文档、API 参考	llms-probe → WebFetch llms.txt	如果未发布 llms.txt，则使用 context7
更新日志、重大变更	llms-probe → WebFetch llms.txt	使用 gh api contents 获取 CHANGELOG.md
跨仓库代码搜索（精确标识符）	Sourcegraph MCP keyword_search	gh search code，然后使用 git-clone 跟进
GitHub 托管依赖中的语义／概念查询（“X 在库 Y 中如何工作”）	mcp__plugin_ora_morph__github_codebase_search	如果问题持续扩展到多个文件，则使用 git-clone
跨多个托管平台或 GitLab／Bitbucket 仓库的概念查询	Sourcegraph MCP nls_search，并提供 2-5 个提取的关键词	选定字面术语后使用 keyword_search
深入研究已知仓库（3 个以上文件）	git-clone + shell 工具	对于一次性读取，使用 Sourcegraph read_file
GitHub Issues	gh issue view <N>	使用 gh search issues 查找
GitHub PR	gh pr view <N>	使用 gh search prs 查找
GitHub Releases（版本、日期、说明）	gh release view <tag> --repo owner/repo	使用 gh release list --repo owner/repo 浏览
单个文件（已知仓库 + 路径）	Sourcegraph MCP read_file	gh api repos/.../contents/<path>（仅限 GitHub）
符号导航（定义、引用）	Sourcegraph go_to_definition / find_references	git-clone + ast-grep
跨仓库 Git 历史／差异搜索	Sourcegraph commit_search / diff_search / compare_revisions	gh api /repos/.../commits
软件包版本、弃用信息	deps-dev	使用 npm view 获取仅限 npm 的元数据
npm 软件包信息（非版本）	npm view <pkg>（Bash）	WebSearch 了解社区评价
通用网页查询	WebSearch → WebFetch	—
比较／决策	针对每个库使用 llms-probe + WebSearch	使用 context7 获取其他片段

对于混合请求，并行启动所有相关工具。Probe 和 clone 都受 I/O 限制——在后台启动它们，同时运行 WebFetch／context7／WebSearch，以掩盖延迟。

GitHub 访问规则

不要对 github.com 或 raw.githubusercontent.com URL 使用 WebFetch，请使用正确的工具：

GitHub 内容	使用	切勿使用
源代码（探索）	git-clone + shell 工具	通过 gh api contents 浏览文件
源文件（已知路径）	gh api repos/.../contents/<path>	WebFetch raw.githubusercontent.com
Issue	gh issue view <N> --repo owner/repo	WebFetch github.com/.../issues/N
Pull request	gh pr view <N> --repo owner/repo	WebFetch github.com/.../pull/N
Issue/PR 搜索	gh search issues "q" --repo ...	WebFetch github.com/issues?q=...
Release（版本、日期、说明）	gh release view/list --repo owner/repo 或 gh api repos/.../releases	WebFetch github.com/.../releases — HTML 上的相对时间戳会被误当成训练时期的年份
CHANGELOG.md	gh api repos/.../contents/CHANGELOG.md	WebFetch blob/ 或 raw URL

搜索规范

• 通过 deps-dev 查询版本：检查最新版本、弃用情况或比较已安装版本与最新版本时，始终优先使用 deps-dev。只有在 deps-dev 出错或软件包为私有时，才使用 npm view 或 WebSearch。
• 先查 llms.txt，context7 作为后备：查询库文档时，先针对文档域名运行 scripts/llms-probe.sh，再考虑使用 context7。作者发布的 llms.txt 没有社区整理滞后，也没有可能产生幻觉的增强层。仅当探测结果为空时，才使用 context7。

llms.txt — 作者权威的库文档

许多文档网站会发布 llms.txt（文档页面 URL 的 Markdown 索引）和 llms-full.txt（拼接而成的完整内容）。这些内容由作者发布——没有增强层，也没有社区整理滞后——因此能准确反映当前部署的文档版本。若可用，优先使用它们，而不是 context7。

第 1 步：探测是否可用

bash scripts/llms-probe.sh <docs-domain>

对找到的文件输出 TSV kind \t url \t size。探测根路径和常见的嵌套路径（/docs/、/en/），跟随重定向并去重。如果未找到任何文件，则返回非零退出码。

kind	含义
index	llms.txt — 文档页面 URL 的 Markdown 列表
full	llms-full.txt — 拼接而成的完整文档语料

当 CDN 移除了 Content-Length 和 Content-Range 两个标头时，大小会显示为 ?（Vercel 在 react.dev 上会这样做）——将 ? 视为未知，并优先选择 index 路径。

步骤 2：根据现有内容获取

检测结果	操作
llms-full.txt ≤ ~500 KB	直接使用 WebFetch 获取 — 一次往返即可拿到完整语料
llms-full.txt > ~500 KB 或大小为 ?	先使用 WebFetch 获取 llms.txt，选出相关章节链接，再获取这些内容
只有索引（没有完整文件）	使用 WebFetch 获取索引，然后获取各个页面链接
探测失败	改用 context7（下一节）

对于多章节获取，请并行发起页面 WebFetch 调用。

已知发布方

已确认可用（2026 年 4 月）：React（react.dev）、Next.js（nextjs.org，内容位于 /docs/ 下）、Vercel、Anthropic（docs.anthropic.com → platform.claude.com）、Cloudflare（docs.cloudflare.com → developers.cloudflare.com）、Supabase、Drizzle（orm.drizzle.team）、Hono（hono.dev）、Zod（zod.dev）、Expo（docs.expo.dev）、tRPC（trpc.io）、shadcn/ui（ui.shadcn.com）。大多数由 Mintlify 和 GitBook 托管的文档会自动发布。

Tailwind、大多数 1.0 版之前的库，以及许多社区软件包不会发布 — 这些直接使用 context7。

规则

• 先探测再判断。 各项目的采用情况不一，路径也各不相同（根路径、/docs/ 或重定向）。始终运行 llms-probe.sh 并根据 TSV 采取行动 — 不要硬编码 URL。
• 获取完整文件前先检查大小。 Cloudflare 的 llms-full.txt 约为 46 MB，Supabase 报告的大小为 ?（分块）。盲目获取其中任一文件都会撑爆上下文窗口。500 KB 阈值仅供参考 — 请根据剩余上下文预算调整。
• 大型语料采用索引 → 页面链路。 将 llms.txt 视为路由表：解析章节标题，只获取与问题匹配的页面 URL。

context7 — 库文档（备用方案）

当 llms-probe.sh 未返回结果时，使用 context7 — 这表示该库未发布 llms.txt，或者其文档域名无法访问。其覆盖范围通过社区整理的索引涵盖约 33K 个库；代价是增加了一层可能引入错误的内容，而作者发布的 llms.txt 不存在此问题。

通过官方 ctx7 CLI 使用两步工作流。需要先运行一次 bunx ctx7@latest login（无需 API 密钥环境变量）。

步骤 1：解析库 ID

bunx ctx7@latest library <name> [query]

列出库候选项及其 Context7 ID（例如 /websites/react_dev）、可信度分数和代码片段数量。可选的 [query] 会根据相关性重新排列结果 — 如果已知主题，请务必传入。添加 --json 可获取机器可读输出。

步骤 2：获取文档

bunx ctx7@latest docs <libraryId> "<query>"

返回按相关性排序的 Markdown 代码片段。添加 --json 可获取结构化输出。如果第一个答案内容浅显或偏离主题，请使用 --research 重试 — 它会启动沙箱化 Agent，读取源代码仓库并进行实时网页搜索，但成本较高。

规则：

• 一次性设置：bunx ctx7@latest login（交互式）。使用 bunx ctx7@latest whoami 验证。
• 始终先解析库 ID — ID 无法猜测。
• 编写具体的查询 — "useState hook with objects" 比 "hooks" 更好。两个命令都会根据查询进行相关性排序。
• 仅在默认答案不足时使用 --research 重试，不要默认启用 — 它速度更慢、成本更高。

参考：references/context7.md

Sourcegraph — 跨仓库搜索与代码导航（MCP）

Sourcegraph 公共实例通过 https://sourcegraph.com/.api/mcp 提供 HTTP MCP 服务，包含 13+ 个用于跨仓库搜索、代码导航和 git 历史记录的工具。已配置在 ora 插件的 .mcp.json 中 — Clio 可自动使用这些工具。

索引涵盖 GitHub、GitLab 和 Bitbucket 上 2M+ 个开源仓库。跨仓库查询只需亚秒级，无需本地克隆开销。

按用途分类的工具：

意图	工具
按确切标识符搜索（AND）	keyword_search — 字面匹配，要求包含所有词项。筛选条件：repo:、file:、lang:、rev:
按概念搜索／词汇未知	nls_search — OR 逻辑 + 词干提取（handler 可匹配 handle）。不使用语义嵌入
读取单个文件	read_file — 上限 128KB；repo、path，以及可选的 revision / startLine / endLine
列出目录	list_files
查找代码库	list_repos
符号导航	go_to_definition、find_references
Git 历史记录／差异	commit_search、diff_search、compare_revisions
查找贡献者	get_contributor_repos
基于代码库进行 AI 综合分析	deepsearch — 开销较大；会启动子 Agent

规则：

• 根据已知信息选择 keyword_search 还是 nls_search。 明确的标识符（函数／类／常量名称、错误字符串、字面短语）→ keyword_search。词汇未知／概念性查询（“X 如何工作”“跨库模式”）→ nls_search。原因：keyword_search 使用 AND + 字面匹配，缺少一个词项就会导致结果为空；nls_search 使用 OR + 词干提取，召回范围更广，但排名噪声也更多。
• 使用 nls_search 前先提取关键词。 去掉疑问词（how、what、where、does、is）和冠词。传入 2-5 个有意义的名词／动词，而非完整句子。例如：“how does the router match incoming requests” → router match request handler。原因：工具会对每个词项进行词干提取和 OR 匹配，因此自然语言中的填充词会稀释信号。
• 使用 repo:^...$ 锚点限定范围，避免匹配到分叉仓库。repo:foo/bar 也会匹配 foo/bar-fork；repo:^github\.com/foo/bar$ 则不会。
• 模式：搜索 → 验证路径 → read_file。 如果搜索结果标注为 repo@revision（例如 github.com/foo/bar@abc123），请拆分后分别将 repo 和 revision 传给 read_file。省略 revision 会静默地读取默认分支的 HEAD，返回的内容可能不同。
• 并行执行互不依赖的搜索。 比较 3 个代码库 → 在一条消息中发起 3 次 keyword_search/nls_search 调用，而非依次执行。
• 发现与取证——查找“符合……的代码库”时使用 keyword_search / nls_search；在单个代码库的 5 个以上文件中追踪流程时使用 git-clone。
• 索引延迟——最近约 24 小时内发布的代码可能尚未建立索引。对于刚发布的版本，可改用 git-clone --refresh。
• 代码库未建立索引 = 回退方案——如果 read_file 返回 null 仓库，请改用 git-clone 或 gh api contents。
• deepsearch 开销较大——会启动 AI 子 Agent。仅当 keyword_search + read_file 无法综合得出答案，并且目标涉及多个代码库或非 GitHub 主机时才使用。仅针对 GitHub 的综合分析，请改用 mcp__plugin_ora_morph__github_codebase_search——开销更低，也适用于相同任务。
• 套餐等级注意事项——Sourcegraph 文档指出，MCP 访问属于 Enterprise 套餐的一部分；尚未验证公开的 sourcegraph.com MCP 端点在免费套餐中的行为。如果首次工具调用返回 401/403，请改用 git-clone。

参考：Sourcegraph MCP 文档

Morph github_codebase_search — GitHub 托管语义查询的默认选择

mcp__plugin_ora_morph__github_codebase_search 会针对目标公开 GitHub 仓库运行 Morph 的 WarpGrep 子 Agent，并返回带有文件:行号引用的综合答案。遇到以下问题时，优先使用它：“库 X 如何实现 Y”“软件包 Z 在哪里处理情况 W”“仓库 R 中功能 V 的数据流是什么”——一次 Morph 调用即可替代克隆、搜索再阅读的循环。

• **适用场景：**目标仓库位于 GitHub，且问题是概念性或语义性的（“如何”“在哪里”“什么将 X 连接到 Y”）。原因：Morph 会并行处理逐个文件的搜索、阅读和综合，否则调用方只能串行完成这些工作。

• **以下情况优先使用 Sourcegraph：**目标位于 GitLab/Bitbucket、跨多个仓库进行横向搜索、带筛选条件的精确标识符查询（repo:、lang:、rev:）、Git 历史记录/差异。

• **以下情况优先使用 git-clone：**需要在同一仓库中深入探索 3 个或更多文件、执行 ast-grep 结构查询，或问题不断延伸（“现在告诉我在哪里调用了它，再给我看看相关测试”）。

• 相信引用，核实结论——Morph 的 file:line 引用指向目标仓库中的真实位置，但其综合分析（代码的_作用_以及它如何回答问题）可能有误。答案至关重要时，请通过 gh api repos/.../contents/<path> 或 git-clone + Read 抽查核实。

git-clone — 源代码探索

将任意公开 Git 仓库浅克隆到本地缓存，并使用 shell 工具探索工作树。缓存位于 ~/.cache/clio-repos/，并会在不同会话间复用。

bash scripts/git-clone.sh <repo> [--branch X] [--refresh]

脚本会输出缓存克隆的绝对路径。对同一仓库的后续调用会立即返回缓存路径（不会重新克隆）。

仓库参数格式：

• owner/repo — GitHub 快捷格式（例如 vercel/next.js）
• 完整 HTTPS URL — 适用于任何主机（https://gitlab.com/...、https://gitlab.jmango360.com/...）
• SSH 格式 — git@host:path（需要配置 SSH 密钥）

**并行处理：**克隆受 I/O 限制（小型/中型仓库需 1–3 秒）。研究主题同时需要文档和源代码时，可并行启动克隆以及 llms-probe/context7/WebSearch；文档返回时，克隆通常已准备好供探索。

规则：

• 不要阅读脚本源代码。使用 --help 查看用法。
• 默认缓存目录为 ~/.cache/clio-repos/；需要时使用 --cache-dir 覆盖。
• 缓存会复用——只有需要最新提交时才传入 --refresh。
• 对于按确切路径获取单个文件的情况，优先使用 gh api repos/.../contents/<path>——无需承担克隆开销。

deps-dev — 软件包版本

查询公共注册表中的最新稳定版本。无需 API 密钥。

python3 scripts/get-versions.py <system> <pkg1> [pkg2] ...

支持的生态系统：

生态系统	系统 ID	示例
npm	npm	express、@types/node
PyPI	pypi	requests、django
Go	go	github.com/gin-gonic/gin
Cargo	cargo	serde、tokio
Maven	maven	org.springframework:spring-core
NuGet	nuget	Newtonsoft.Json
RubyGems	rubygems	rails、sidekiq

输出：包含 package、version、published、status 列的 TSV。

规则：

• 不要阅读脚本源代码。直接运行或使用 --help。
• 尽可能批量查询——一次调用中传入多个软件包名称。
• 标记已弃用的软件包——如果状态为 deprecated，请建议替代方案。

参考：references/deps-dev.md