Context7 find-docs 技能详解：让 AI 编码助手用 CLI 两步查准任意库的最新文档

Context7 仓库中的 skills/find-docs/SKILL.md 是一份面向 AI Agent 的"技能文件"（Skill），核心目标只有一件：当用户询问任何库、框架、SDK、CLI 工具或云服务的 API 语法、配置项、版本迁移等问题时，引导 Agent 通过 Context7 CLI（ctx7）的两步命令——先 library 解析库 ID、再 docs 查询文档——获取经过索引的最新文档与代码示例，而不是依赖可能已经过时的模型训练数据。读完本文，你能完整掌握该技能定义的两步工作流、查询措辞规范、版本化库 ID 的用法、认证与配额错误的处置策略，并理解 ctx7 library 与 ctx7 docs 两条命令在 CLI 源码 中的真实实现与底层 API 调用链。

技能定位：为什么 Agent 需要专门查文档，而不是直接回答

find-docs/SKILL.md 的 frontmatter 中，name 为 find-docs，description 字段定义了技能的触发条件与使用边界。这是 LLM Agent 判断"该不该用这个技能"的依据，其要点如下：

• 触发范围：只要用户询问某个具体的库、框架、SDK、CLI 工具或云服务，就应使用此技能——即便是 React、Next.js、Prisma、Express、Tailwind、Django、Spring Boot 这类广为人知的技术也要查，因为模型训练数据未必反映最近的 API 变更或版本更新。
• 明确列举的适用场景：API 语法问题、配置选项、版本迁移问题、提及库名的 "how do I" 问题、涉及库特定行为的调试、安装/搭建步骤、CLI 工具用法。
• 强制性约束：文档明确要求"即使用户认为你已知答案，也不要用训练数据回答 API 细节、函数签名或配置选项，这些经常过时；对于库文档和 API 细节，优先使用此技能而非联网搜索"。

技能正文开篇同样强调：使用 Context7 CLI 检索当前文档与代码示例。整个技能文件不包含任何项目内部链接，其全部内容都是"给 Agent 的操作规程"，因此理解它的关键是把它翻译成一条可执行、可验证的命令序列——这正是下两节要做的事。

运行方式：npx 优先，可选全局安装

技能文件规定所有命令都以 npx ctx7@latest 形式运行，这样每次执行都使用最新版 CLI，无需全局安装：

npx ctx7@latest library <name> "<query>"
npx ctx7@latest docs <libraryId> "<query>"

如果偏好裸的 ctx7 命令，可以全局安装：

npm install -g ctx7@latest

这里有一个容易忽略的细节：技能文件有意将 npx 方式放在最前面、把全局安装作为可选项。这不是随意排版——仓库中专门有一条对齐测试 find-docs-skill-alignment.test.ts 用断言锁定这一点：

• uses npx ctx7@latest as the canonical invocation style：技能文本必须包含 npx ctx7@latest library 与 npx ctx7@latest docs，且不允许出现行首裸 ctx7 library 的写法；
• documents official library naming guidance：技能必须包含官方式命名的指导语（"Next.js" not "nextjs"）；
• does not recommend global install as the primary workflow：通过索引比较，确保 npm install -g ctx7@latest 出现在 npx ctx7@latest 之后，即全局安装绝不能作为主工作流。

也就是说，这份技能文件与 CLI 的行为是"测试驱动的"：修改技能文案时如果偏离了既定口径，CI 会直接失败。当前仓库中 CLI 包名为 ctx7（见 package.json，当前版本 0.5.9），命令名与 npx ctx7@latest 中的包名一致。

两步工作流总览：先解析 ID，再查文档

技能定义了一个严格的两步流程：

# Step 1: Resolve library ID
npx ctx7@latest library <name> "<query>"

# Step 2: Query documentation
npx ctx7@latest docs <libraryId> "<query>"

两条硬性规则：

1. 必须先用 library 换取合法库 ID——除非用户显式给出了形如 /org/project 或 /org/project/version 的库 ID；
2. 每个问题的命令总次数不得超过 3 次。如果 3 次尝试后仍找不到所需内容，就基于已有最佳结果作答。这条规则防止 Agent 在检索上无限打转，把上下文和配额烧光。

从源码看，这两条命令分别注册在 registerDocsCommands：library 命令接受 <name>（必选）与 [query]（可选），docs 命令接受 <libraryId> 与 <query>（两者都必选），二者都支持 --json 选项以 JSON 格式输出，方便脚本或 Agent 解析。CLI 的注册入口在 index.ts，ctx7 这个命令名在 program.name("ctx7") 处定义，--help 的帮助文本里也内置了 npx ctx7 library react "how to use hooks" 和 npx ctx7 docs /facebook/react "useEffect examples" 两个示例，与技能文件的口径一致。

Step 1：ctx7 library 把库名解析成 ID

library 命令把一个包名/产品名解析为 Context7 兼容的库 ID，并返回匹配到的候选列表。技能文件给出的示例：

npx ctx7@latest library React "How to clean up useEffect with async operations"
npx ctx7@latest library "Next.js" "How to set up app router with middleware"
npx ctx7@latest library Prisma "How to define one-to-many relations with cascade delete"

命名与 query 参数

• 使用官方写法，保留标点："Next.js" 而不是 "nextjs"、"Customer.io" 而不是 "customerio"、"Three.js" 而不是 "threejs"。如果结果不对，先尝试 next.js 这类变体拼写，再考虑改写 query。
• query 参数必须传：它直接影响结果排序。应基于用户意图来构造 query，当多个库名相近时它起到消歧作用。注意 library 命令中 query 是 [query] 可选位置参数（见 docs.ts），但技能层面要求始终传递。
• query 中不得包含任何敏感信息：API 密钥、密码、凭据、个人数据或专有代码。

结果字段与源码实现

每条搜索结果输出的字段，与 docs.ts 中的 formatLibraryResult 逐行对应：

• Library ID — Context7 兼容标识符，格式为 /org/project；
• Name — 库或包名称；
• Description — 简短摘要（有值才显示）；
• Code Snippets — 可用代码示例数量（对应 totalSnippets，非零才显示）；
• Source Reputation — 权威度指示（High、Medium、Low 或 Unknown）；
• Benchmark Score — 质量分（100 为最高，大于 0 才显示）；
• Versions — 可用版本列表（如有）。用户若在提问中指定了版本，应从该列表中取一个。

其中 Source Reputation 不是自由文本，而是由数值 trustScore 分档而来。getReputationLabel 的映射规则是：

trustScore	标签
undefined 或 < 0	Unknown
>= 7	High
>= 4	Medium
其余	Low

这些字段的类型定义在 types.ts 的 LibrarySearchResult 接口中：id、title、description、branch、totalSnippets、totalTokens?、stars?、trustScore?、benchmarkScore?、versions?。也就是说，CLI 终端展示的是该接口字段的"人类可读子集"；如果加了 --json，Agent 拿到的是完整 JSON。

在 resolveLibrary 中可以看到请求细节：GET {baseUrl}/api/v2/libs/search?libraryName=<name>&query=<query>，请求头通过 getAuthHeaders 附加 X-Context7-Source: cli、X-Context7-Client-IDE: ctx7-cli、X-Context7-Client-Version、X-Context7-Transport: cli 四个标识头，以及可选的 Authorization: Bearer <token>。默认 baseUrl 为 Context7 官方服务，且 CLI 全局支持 --base-url <url> 选项覆盖（见 index.ts），这意味着私有化部署的 Context7 实例也能被同一套技能命令覆盖。

另外，当团队的 teamspace 配置了库过滤策略时，LibrarySearchResponse.searchFilterApplied 为真，CLI 会额外打印一条警告，提示结果已被过滤、可去 teamspace 策略设置中调整质量阈值与屏蔽列表（见 docs.ts）。

选择流程（Selection process）

拿到候选列表后，技能规定了 Agent 的选择算法：

1. 分析 query，理解用户到底要找哪个库/包；
2. 按以下维度选出最相关的一个：名称相似度（精确匹配优先）、描述与查询意图的相关度、文档覆盖度（优先 Code Snippets 数量多的）、Source Reputation（High/Medium 更可信）、Benchmark Score（越高越好）；
3. 多个都好时，说明情况但仍以最相关的一个继续；
4. 没有好匹配时，明确告知用户，并给出改进查询的建议；
5. 查询本身有歧义时，先向用户确认，再带着最佳猜测继续。

版本化库 ID

如果用户提到特定版本，应使用版本化的库 ID（/org/project/version 形式）：

# General (latest indexed)
npx ctx7@latest docs /vercel/next.js "How to set up app router"

# Version-specific
npx ctx7@latest docs /vercel/next.js/v14.3.0-canary.87 "How to set up app router"

可用版本列在 library 命令输出的 Versions 字段里（对应 versions: string[]），取与用户所指最接近的一个即可。

Step 2：ctx7 docs 用 ID 查询文档

拿到库 ID 后进入第二步。技能文件示例：

npx ctx7@latest docs /facebook/react "How to clean up useEffect with async operations"
npx ctx7@latest docs /vercel/next.js "How to add authentication middleware to app router"
npx ctx7@latest docs /prisma/prisma "How to define one-to-many relations with cascade delete"

库 ID 的格式校验与 Windows/Git Bash 陷阱

docs 命令对 ID 有严格的前置校验（见 queryCommand）：

• 必须以 / 开头，且匹配正则 ^\/[^/]+\/[^/]+（即至少 /owner/repo 两段）；
• 不合法时直接报错并提示 Expected format: /owner/repo or /owner/repo/version (e.g., /facebook/react)，同时建议运行 ctx7 library <name> 找正确 ID。

一个值得注意的实现细节：在 Windows 的 Git Bash 下，/owner/repo 这种以单斜杠开头的参数会被 MSYS 路径转换改写成 C:/Program Files/Git/owner/repo。CLI 因此内置了 recoverLibraryId：如果输入是 //owner/repo（Git Bash 的转义写法）则折叠为 /owner/repo；如果是被改写成盘符路径的形式（含 Scoop 安装的 apps/git/<version>|current 变体），则剥离 Git 安装目录前缀、还原出 /owner/repo[/version] 尾部。错误提示里也给了对应建议：Git Bash 用户可以直接用双斜杠 ctx7 docs "//facebook/react" "<question>" 规避。

怎么写好 query

技能文件对 query 质量的要求，与 docs 命令参数描述（"Single-topic question... run a separate query per distinct concept, unless asking how they interact"）完全一致：

• 具体、包含相关细节，但每条 query 只覆盖一个主题。问题跨多个独立概念时，为每个概念各跑一次 docs，除非问题本身是"这些概念如何交互"；
• 描述"要在文档里查什么"，而不是"要完成什么任务"。模糊的单词 query 返回泛化结果，多主题 query 会稀释排序、让每个主题都只得到浅层结果；
• query 中同样禁止敏感信息。

技能给出的好/坏对照表：

Quality	Example
Good	"How to set up authentication with JWT in Express.js"
Good	"React useEffect cleanup function with async operations"
Bad (too vague)	"auth"
Bad (too vague)	"hooks"
Bad (too broad)	"routing and auth and caching in Next.js"

输出结构：code snippets 与 info snippets

技能文件指出，输出包含两类内容：code snippets（带标题、语言标签代码块）和 info snippets（带面包屑语境的散文解释）。这与 CLI 的输出逻辑和数据结构一一对应：

• --json 模式下，返回 ContextResponse 结构：codeSnippets: CodeSnippet[] 与 infoSnippets: InfoSnippet[]。其中 CodeSnippet 含 codeTitle、codeDescription、codeLanguage、codeTokens、codeId、pageTitle、codeList: {language, code}[]；InfoSnippet 含 breadcrumb?、content、contentTokens；
• 默认文本模式下，queryCommand 先遍历 codeSnippets：加粗打印 codeTitle、灰色打印 codeDescription，再为 codeList 中每段代码输出 ```language 围栏代码块；随后遍历 infoSnippets，加粗打印 breadcrumb 面包屑并输出正文；
• 两类都为空时，CLI 只打印 No documentation found for: "<query>" 警告。

底层请求见 getLibraryContext：GET {baseUrl}/api/v2/context?libraryId=<id>&query=<query>&type=json|txt，其中 type 由 --json 决定。如果库 ID 已被重命名/迁移，API 返回 301 加 redirectUrl，CLI 会打印 "Library has been redirected"、新 ID 和一条可直接复制重跑的 ctx7 docs "<newId>" "<query>" 命令（见 docs.ts）——Agent 遇到重定向时按此提示换 ID 重试即可，不占额外排错成本。

认证：免登录可用，登录可提额

技能文件的 Authentication 一节说明：library 和 docs 无需认证即可使用；需要更高频率限制时有两种方式：

# Option A: environment variable
export CONTEXT7_API_KEY=your_key

# Option B: OAuth login
npx ctx7@latest login

源码印证了这一点：getAuthHeaders 中，process.env.CONTEXT7_API_KEY 存在时优先用它作 Bearer token，否则回退到 getValidAccessToken() 提供的 OAuth 访问令牌；两者都没有时请求不带 Authorization 头，命令仍可匿名执行。CLI 的完整认证命令族还包括 ctx7 whoami（查看登录状态）与 ctx7 logout（登出），见 packages/cli/README.md 的 Authentication 小节。

错误处理：配额耗尽时的标准动作

技能文件对配额错误（"Monthly quota reached" 或 "quota exceeded"）给出了三步标准处置：

1. 明确告知用户 Context7 配额已用尽；
2. 建议其通过 npx ctx7@latest login 认证以获取更高限额；
3. 如果用户不能或不愿认证，则用训练知识作答，并明确标注该答案可能过时。

关键禁令：不允许静默回退到训练数据——必须始终告诉用户"为什么这次没有使用 Context7"。这一条与技能的整体精神一致：技能存在的意义就是"比训练数据更新"，静默回退等于无声地放弃了这个价值。

从源码结构看，配额类错误最终会以 API 的 error/message 字段形式冒泡到 CLI 的错误分支（process.exitCode = 1 + 红色错误日志），Agent 只能靠错误文本中的配额关键词来识别，因此技能文件才把"看到什么字样 → 做什么动作"写成了显式规则。

常见错误清单（Common Mistakes）

技能文件最后沉淀的五条常见错误，值得逐条对照执行：

错误	正确做法
库 ID 缺 / 前缀（facebook/react）	/facebook/react；源码校验见上文正则
跳过 library 直接跑 docs react "hooks"	无合法 ID 时 docs 会失败，先 npx ctx7@latest library 解析 ID
query 用单词（"hooks"）	用描述性 query："React useEffect cleanup function"
一条 query 塞多主题（"routing and auth and caching"）	每个概念单独一次 docs，除非问的是概念间交互
query 里带敏感信息（API key、密码、凭据）	只写技术意图，不含任何凭据与专有代码

小结

find-docs 技能把"查文档"这件对 LLM 来说最容易翻车的事，收敛成了两条可复制的命令、一套 query 书写规范和一个 3 次调用的上限约束；而 Context7 CLI 侧的 docs.ts、api.ts、library-id.ts 与 types.ts 则保证了这套规范有真实的实现支撑——包括结果字段的来源、ID 校验、Git Bash 兼容、重定向提示与 JSON 输出。对维护该技能的团队来说，find-docs-skill-alignment.test.ts 是最后一道防线：技能文案一旦偏离 npx ctx7@latest 调用风格或官方命名口径，测试即失败。