Context7 ctx7 CLI 文档查询规则详解：AI 编码代理获取最新库文档的四步工作流与源码实现

本文以 rules/context7-cli.md 规则文件为核心，系统讲解 Context7 项目中"AI 代理如何通过 ctx7 CLI 查询最新库文档"这一工作流的完整规范：何时触发、如何解析库 ID、如何选取结果、如何拉取文档，以及强制约束与配额错误的处理方式，并结合 CLI 源码 与 API 层实现 说明规则背后实际的命令行为与调用链路，帮助读者既能在项目中直接套用该规则，也能理解每一条约束的工程依据。

一、规则文件的定位：让 AI 代理优先查文档，而不是凭训练数据回答

rules/context7-cli.md 是一份面向 AI 编码代理（如 Claude Code、Cursor 等）的规则（rule）文件，它与面向 MCP 通道的 rules/context7-mcp.md 是姊妹篇：前者驱动代理通过终端命令 npx ctx7@latest 查询文档，后者驱动代理通过 MCP 的 resolve-library-id / query-docs 工具查询文档。两者共享同一套"先解析、后查询"的心智模型。

规则开篇即给出触发条件与核心理由：

• 触发范围：只要用户询问任何库、框架、SDK、API、CLI 工具或云服务——包括 React、Next.js、Prisma、Express、Tailwind、Django、Spring Boot 这类广为人知的库——都应当使用 ctx7 CLI 获取当前文档。覆盖的问题类型包括：API 语法、配置项、版本迁移、库专属调试、安装说明和 CLI 工具用法。
• 核心理由：即使用户（或模型）"认为自己知道答案"，也应当先查文档——因为训练数据可能没有反映最近的变更。规则明确将 ctx7 的优先级置于网络搜索之上（用于库文档场景时）。
• 排除场景：以下任务不应使用该规则——重构、从零写脚本、调试业务逻辑、代码审查、通用编程概念。这条排除清单把规则的作用边界牢牢钉在"第三方库文档"上，避免代理在无关场景下浪费配额。

从仓库结构看，这条规则与 skills/find-docs/SKILL.md（完整技能文档）和 skills/context7-cli/SKILL.md（CLI 总览技能）构成同一工作流的"轻量规则版 + 完整技能版"关系，规则文件是精简后的行为约束，技能文件则包含更详尽的字段说明与错误处理章节。

二、标准四步工作流

规则文件的核心是四步流程，以下完整继承并逐步展开。

步骤 1：解析库 —— ctx7 library

npx ctx7@latest library <name> "<what to look up>"

• 库名必须使用官方名称与正确标点：例如 "Next.js" 而非 "nextjs"、"Customer.io" 而非 "customerio"、"Three.js" 而非 "threejs"。
• 第二个参数 <what to look up> 描述要查找的内容，它会直接影响服务端对结果的排序，在库名有歧义或多个同名包时尤其有用。

步骤 2：挑选最佳匹配

library 命令返回一组候选，库 ID 格式为 /org/project。规则给出的选取优先级是：

1. 名称精确匹配；
2. 描述与查询的相关性；
3. 代码片段数量（code snippet count，越多说明文档覆盖越广）；
4. 来源可信度（Source Reputation，优先 High / Medium）；
5. 基准分数（Benchmark Score，越高越好）。

如果结果不满意，规则建议尝试替代名称或改写查询（例如把 "nextjs" 换成 "next.js"，或重新表述问题），而不是放弃流程。

步骤 3：拉取文档 —— ctx7 docs

npx ctx7@latest docs <libraryId> "<what to look up>"

关键约束：

• 每个独立概念单独执行一次 docs 命令。如果问题横跨多个主题（例如路由、鉴权、缓存三者都问），就拆成多次调用，除非问题本身就是"这些概念如何交互"。原因是：把多个主题合并在一条查询里会稀释排序信号，导致每个主题都只返回浅层结果。
• 查询要具体：描述"要查什么"，而不是单个模糊词。具体而详细的查询比单个词返回的结果质量好得多。

步骤 4：基于拉取到的文档作答

最终回答必须建立在第 3 步实际返回的文档内容之上，而不是模型记忆。

三、强制约束与最佳实践

规则文件中用大写 MUST、Do not 标出的硬约束值得逐条对照实现来理解：

约束	内容	工程依据
必须先调 library	除非用户直接给出 /org/project 格式的 ID，否则必须先运行 library 拿到有效 ID	源码中 docs 命令对 ID 做正则校验，裸库名（如 react）会被直接拒绝，见下文源码分析
命令次数上限	每个问题最多运行 3 条命令，超出后用现有最佳结果作答	控制配额消耗，规则与 skills/find-docs/SKILL.md 中的 "Do not run these commands more than 3 times per question" 一致
查询内容安全	查询中不得包含敏感信息（API key、密码、凭据等）	查询会作为请求参数发送到服务端（见 packages/cli/src/utils/api.ts 中的 URLSearchParams 拼接）
配额错误处理	若命令因配额错误失败：告知用户，建议 npx ctx7@latest login 或设置 CONTEXT7_API_KEY 环境变量以获得更高限额；不得静默回退到训练数据	环境变量 CONTEXT7_API_KEY 在 API 层被直接读取并注入 Authorization: Bearer 请求头，见 packages/cli/src/utils/api.ts#L274-L279

四、版本专属 ID

规则特别指出：当需要特定版本的文档时，使用 library 输出中的 /org/project/version 格式 ID：

# 版本专属 ID 示例
npx ctx7@latest docs /vercel/next.js/v14.3.0 "How to set up app router"

可用版本列表随 library 命令的输出返回。从源码看，docs.ts 中的 ID 校验正则 /^\/[^/]+\/[^/]/ 同时接受 /owner/repo 和 /owner/repo/version 两种形态，因此版本专属 ID 在 CLI 侧是合法的一等输入，而不仅仅是文档约定。

五、源码级解析：规则约束如何落在实现里

5.1 docs 命令的 ID 校验与 Git Bash 修复

规则中"必须先调 library 拿 ID"这条强制约束，在 packages/cli/src/commands/docs.ts 中得到了硬性执行：

// Git Bash on Windows rewrites "/owner/repo" into a Windows path; recover it.
libraryId = recoverLibraryId(libraryId);

if (!libraryId.startsWith("/") || !/^\/[^/]+\/[^/]/.test(libraryId)) {
  log.error(`Invalid library ID: "${libraryId}"`);
  log.info(`Expected format: /owner/repo or /owner/repo/version (e.g., /facebook/react)`);
  ...
  process.exitCode = 1;
  return;
}

也就是说，直接执行 ctx7 docs react "hooks" 必然失败，错误信息还会提示"先运行 ctx7 library <name> 找到正确 ID"——这正是规则文件反复强调该顺序的原因。

更有趣的是前置的 recoverLibraryId 调用。packages/cli/src/utils/library-id.ts 专门处理 Windows 上 Git Bash 的参数改写问题：Git Bash 会把形如 /facebook/react 的以斜杠开头的参数改写为 C:/Program Files/Git/facebook/react 这样的 Windows 路径。该函数会识别盘符路径并剥离 Git 安装目录前缀，恢复出 /facebook/react；对于 Scoop 安装的 Git（路径含 apps/git/<version> 或 current 连接点）也有专门匹配。CLI 甚至在 Windows 平台上提示用户可以用双斜杠 //facebook/react 作为跳过路径转换的写法。这个细节解释了为什么规则文件要求使用 npx ctx7@latest 而非裸 ctx7——保证拿到的是包含这些修复逻辑的最新版本。

5.2 library / docs 背后的 API 调用链

packages/cli/src/utils/api.ts 展示了两条命令对应的服务端端点：

• resolveLibrary（L283-L310）：GET /api/v2/libs/search?libraryName=...&query=...。query 参数只有在提供时才附加——这与规则中"总是传递 query 参数"的建议呼应：带上意图描述能让服务端按相关性排序。
• getLibraryContext（L316-L361）：GET /api/v2/context?libraryId=...&query=...&type=txt|json。非 TTY 场景下（如代理通过 shell 调用、输出被管道转发），CLI 默认请求 type=txt 的干净文本输出，不带 spinner 和颜色；--json 则输出结构化 JSON 供脚本解析。

认证方面，getAuthHeaders 统一构造请求头：先检查环境变量 CONTEXT7_API_KEY（export CONTEXT7_API_KEY=your_key 即可完全跳过交互式登录，适合 CI 或脚本场景），否则使用本地存储的 OAuth 访问令牌；两者都未配置时无认证头，命令仍然可以运行，只是限额较低。这解释了规则中"大多数命令无需登录即可工作，登录用于更高限额"的说法，以及配额错误时建议 login 或 CONTEXT7_API_KEY 两条路径的出处。

5.3 选取指标的展示逻辑

规则中列举的选取指标（代码片段数、来源可信度、基准分数）在 docs.ts#L14-L44 的 formatLibraryResult 中有直接对应：totalSnippets 输出为 "Code Snippets"，trustScore 经 getReputationLabel 映射为 High / Medium / Low / Unknown（映射规则：≥7 为 High，≥4 为 Medium，其余为 Low），benchmarkScore 输出为 0–100 的 "Benchmark Score"，versions 列出可用版本 ID。也就是说，规则给代理的选取标准与 CLI 在终端呈现的字段是一一对应的，代理可以直接基于命令输出完成判断，无需额外信息。

5.4 规则与技能文件的一致性由测试保证

规则文件不是孤立的静态文本。packages/cli/src/tests/find-docs-skill-alignment.test.ts 专门校验 skills/find-docs/SKILL.md 与 rules/context7-cli.md 的措辞对齐：例如两者都必须使用 npx ctx7@latest 作为规范调用形式、都必须包含 "Next.js" not "nextjs" 的官方命名指引、且技能文件中不得把全局安装 npm install -g 推荐为主流程（必须出现在 npx 示例之后）。从这套测试看，仓库把"规则文件 ↔ 技能文件 ↔ 推荐调用方式"的一致性当作可回归验证的工程要求来维护——阅读规则文件时，可以放心认为其指令与仓库当前 CLI 的实际行为是同步的。

六、端到端示例：把规则跑通

以"在 Express.js 中如何配置 JWT 鉴权"为例，完整套用规则的四步工作流：

# 步骤 1：解析库（官方名 + 具体意图作为 query）
npx ctx7@latest library "Express.js" "How to set up authentication with JWT"

# 步骤 2：从输出中按 名称匹配/描述相关性/片段数/可信度/基准分数 选最佳匹配
#         （例如得到 /expressjs/express 或对应组织的 ID，并留意 Versions 行）

# 步骤 3：用 ID + 单一主题查询拉取文档
npx ctx7@latest docs /expressjs/express "How to set up authentication with JWT"

# 若问题同时涉及"中间件顺序"与"错误处理"，则每个主题单独执行一次 docs 命令，
# 且同一问题累计不超过 3 条命令

若第 3 步返回配额类错误（如 "Monthly quota reached"），按规则处理：告知用户配额已用尽，建议执行 npx ctx7@latest login 完成 OAuth 登录，或设置 CONTEXT7_API_KEY 环境变量提高限额；在未获得授权前不要静默改用训练数据作答，而要向用户说明 Context7 未被使用的原因。

补充几条来自 docs/clients/cli.mdx 的实操细节：ctx7 library 与 ctx7 docs 都支持 --json 输出（如 ctx7 library react "..." --json | jq '.[0].id' 可直接取第一个结果的 ID 供脚本续用）；输出在非 TTY 下自动退化为无颜色、无 spinner 的纯文本，方便被 head、grep 等管道工具处理；CLI 要求 Node.js 18 或更高版本。

七、小结与延伸阅读

rules/context7-cli.md 把"AI 代理如何查最新库文档"压缩成了一组可执行的行为约束：明确的触发/排除边界、library → 挑选 → docs → 作答 的四步流程、"先解析后查询、每概念一命令、每问题最多三命令、查询不带敏感信息"的硬性纪律，以及配额错误的显式处理路径。结合 packages/cli/src/commands/docs.ts 的 ID 正则校验、packages/cli/src/utils/api.ts 的 API 端点与认证头构造、packages/cli/src/utils/library-id.ts 的 Windows 路径修复，可以看到每一条规则都对应着可验证的实现细节。

如需进一步深入，可参考仓库内以下文件：

• rules/context7-mcp.md：同一工作流的 MCP 工具版规则（resolve-library-id + query-docs）；
• skills/find-docs/SKILL.md：该工作流的完整技能文档，含查询质量示例表与错误处理章节；
• skills/context7-cli/SKILL.md：ctx7 CLI 全功能速查（文档查询、技能管理、setup 配置）；
• docs/clients/cli.mdx：ctx7 CLI 的完整官方文档，覆盖安装、setup/remove 配置、认证与遥测；
• packages/cli/README.md：CLI 包说明。