Context7 CLI 文档命令实战：用 ctx7 library 与 ctx7 docs 两步获取任意库的最新文档

本篇指南聚焦 Context7 仓库中 skills/context7-cli 技能里的文档命令参考（docs.md），完整讲解 ctx7 library 与 ctx7 docs 组成的两步工作流：如何把库名解析为 Context7 库 ID、如何用该 ID 检索带代码示例的最新文档，并结合 CLI 源码 深入解析结果字段、查询书写规范、JSON/管道输出与认证机制的底层实现，读完即可在终端、脚本或 Agent 中稳定复用这套文档检索流程。

工作流总览：先解析库 ID，再查询文档

Context7 为 LLM 和 AI 代码编辑器提供"随时保持最新"的库文档。CLI 的文档功能采用固定的两步工作流：

1. Step 1（解析库）：ctx7 library <name> "<query>" 把包名/产品名解析为 Context7 兼容的库 ID，并返回匹配列表；
2. Step 2（查询文档）：ctx7 docs <libraryId> "<query>" 用库 ID 拉取最新的文档片段与代码示例。

一个关键前提：如果用户已经提供了 /org/project 或 /org/project/version 格式的库 ID，可以跳过 Step 1，直接传给 ctx7 docs。从源码看，ctx7 docs 在执行前会用正则校验 ID 格式（见下文），非法 ID 会立即报错并提示先运行 ctx7 library，这正是在 commands/docs.ts 中实现的。

CLI 本身可通过 npm install -g ctx7@latest 全局安装，也可用 npx ctx7@latest <command> 免安装直接运行（见 packages/cli/README.md）。执行命令前建议先升级到最新版，保证命令与本文档描述的行为一致。

Step 1：用 ctx7 library 解析库

ctx7 library 把一个包名或产品名解析为 Context7 兼容的库 ID，并返回匹配到的候选库列表：

ctx7 library react "How to clean up useEffect with async operations"
ctx7 library nextjs "How to set up app router with middleware"
ctx7 library prisma "How to define one-to-many relations with cascade delete"

query 参数：必填且直接影响排序

第二个参数 query 描述"要在这个库里查什么"，它直接参与结果排序。应当根据用户意图构造 query，这样当多个库名称相似时可以帮助消歧。同时注意：query 中不要包含任何敏感或机密信息，例如 API key、密码、凭据、个人数据或专有代码——查询会发送到服务端。

从源码看，query 会作为 query 查询参数随 libraryName 一起发送到搜索接口：utils/api.ts 中的 resolveLibrary 构造 GET /api/v2/libs/search?libraryName=...&query=... 请求。也就是说，query 不仅影响展示，而是真正参与后端检索的输入。

结果字段

每个结果包含以下字段（对应 types.ts 中的 LibrarySearchResult 接口）：

字段	说明
Library ID	Context7 兼容标识符，格式为 /org/project
Name	库或包名（源码中为 title）
Description	简短描述
Code Snippets	可用代码示例数量（totalSnippets）
Source Reputation	来源权威性指示，取值 High / Medium / Low / Unknown
Benchmark Score	质量分，100 为最高分
Versions	可用版本列表（如有）。若用户在提问中指定了版本，应选用其中之一，格式为 /org/project/version

Source Reputation 的判定逻辑可以直接从源码确认：commands/docs.ts 中的 getReputationLabel 把后端的 trustScore 数值映射为标签——trustScore >= 7 显示 High，>= 4 显示 Medium，其余非负值显示 Low，undefined 或负值显示 Unknown。而 Benchmark Score 只在大于 0 时才会打印（commands/docs.ts）。

排序提示（Quick command）：在交互式 TTY 下，CLI 会额外输出一行快捷命令，直接把排名第一的候选 ID 拼好供你复制执行，例如 ctx7 docs "/facebook/react" "<your question>"（commands/docs.ts）。

另外，如果当前账号所在 teamspace 配置了库过滤器，后端只返回符合过滤条件的库，CLI 会打印一条警告，提示结果受 teamspace 的库过滤器约束（commands/docs.ts 对应 searchFilterApplied 标志）。

候选库的选择流程

拿到候选列表后，按以下流程挑选：

1. 分析 query，理解用户到底要找哪个库/包；
2. 综合以下维度选出最相关的匹配：
   • 名称与 query 的相似度（精确匹配优先）；
   • 描述与 query 意图的相关性；
   • 文档覆盖度（Code Snippets 数量越多越好）；
   • Source Reputation（High / Medium 更权威）；
   • Benchmark Score（越高越好，满分 100）。
3. 若存在多个都不错的候选，明确告知用户，然后继续采用最相关的那一个；
4. 若没有好的匹配，明确说明，并建议用户细化查询；
5. 对含糊的查询，先请求澄清，不要贸然"猜一个就干"。

调用次数约束：每个问题最多调用 ctx7 library 3 次。 3 次之后仍找不到想要的，就使用手头最好的结果，避免无效请求消耗配额。

版本化库 ID

当用户提到具体版本时，使用版本化的库 ID。可用版本列表由 ctx7 library 的输出给出，选与用户指定最接近的一个：

# 通用（最新已索引版本）
ctx7 docs /vercel/next.js "How to set up app router"

# 指定版本
ctx7 docs /vercel/next.js/v14.3.0-canary.87 "How to set up app router"

补充：/owner/repo/<version> 与 /owner/repo@<version> 两种版本写法在后端 API 中都被支持（见 docs/api-guide.mdx 的 "Library ID format" 一节）。CLI 侧对 ID 的本地校验只强制前缀格式 /org/repo（commands/docs.ts），版本段原样透传给 API。

JSON 输出与脚本化

加 --json 可输出结构化 JSON，便于脚本提取 ID：

# 输出为 JSON 以便脚本处理
ctx7 library react "How to use hooks for state management" --json | jq '.[0].id'

源码上，--json 时直接打印 JSON.stringify(results, null, 2)（commands/docs.ts），即 JSON 根节点就是结果数组，所以 .[0].id 能直接取到排名第一的 ID。

Step 2：用 ctx7 docs 查询文档

ctx7 docs 针对已解析出的库拉取最新文档与代码示例。除了用户显式提供了 /org/project 或 /org/project/version 格式的 ID 外，必须先调用 ctx7 library 拿到精确的库 ID——直接把库名传给 ctx7 docs 会失败：

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

调用次数约束：每个问题最多调用 ctx7 docs 3 次。 超出后应基于已有信息作答。

库 ID 格式校验与 Windows Git Bash 兼容

ctx7 docs 在发请求前会本地校验 ID：必须形如 /owner/repo（开头斜杠 + 至少两级路径），否则报错并提示先运行 ctx7 library <name>（commands/docs.ts）。

针对 Windows 上 Git Bash 会把 /owner/repo 参数改写成 Git 安装目录下的 Windows 路径这一坑，CLI 内置了自动恢复逻辑 utils/library-id.ts：

• 常规 ID（以单个 / 开头）原样通过；
• 双斜杠写法 //facebook/react 是 Git Bash 的转义约定，会被折叠回 /facebook/react；
• 被改写成 C:/Program Files/Git/facebook/react（含反斜杠、PortableGit、Scoop 版本化安装路径等形式）的输入，会被识别并还原为 /facebook/react。

library-id.test.ts 覆盖了大量用例，包括保留版本段（D:/Scoop/apps/git/2.54.0.windows.1/vercel/next.js → /vercel/next.js）、不把类似版本的 owner 误当 Scoop 版本、以及不触碰非 Windows 路径等。因此报错提示中还专门给出建议：在 Git Bash 中可以给 ID 加一个前导斜杠（ctx7 docs "//facebook/react" "..."）跳过路径转换，CLI 会自动折叠。

如何写好查询

query 直接决定结果质量。要具体、带上相关细节，但每个 query 只讲一个主题——如果问题横跨多个不同概念，应为每个概念单独运行一次 ctx7 docs，除非问题本身就是问这些概念之间如何交互。同样，query 中不得包含 API key、密码、凭据、个人数据或专有代码。

质量	示例
好	"How to set up authentication with JWT in Express.js"
好	"React useEffect cleanup function with async operations"
差（太模糊）	"auth"
差（太模糊）	"hooks"
差（太宽泛）	"routing and auth and caching in Next.js"

原因：尽可能在 query 中描述"要在该库文档里查什么"——模糊的单词查询只会返回泛泛结果，多主题混合查询会稀释排序，让每个主题都只拿到浅层结果。

输出内容结构：代码片段 + 信息片段

ctx7 docs 的输出包含两类内容：

• 代码片段（code snippets）：带标题、带语言标记的代码块；
• 信息片段（info snippets）：带面包屑上下文（breadcrumb）的说明性文字。

从源码可确认两者在 ContextResponse 类型中的结构（types.ts）：codeSnippets 每项含 codeTitle、codeDescription 和带 language/code 的 codeList；infoSnippets 每项含可选的 breadcrumb 与 content。CLI 的文本渲染逻辑（commands/docs.ts）正是"先加粗打印片段标题，再依次打印 ```language 代码块，最后打印面包屑 + 正文"。

两种典型用法：

# 输出为结构化 JSON
ctx7 docs /facebook/react "How to use hooks for state management" --json

# 管道给其他工具——非 TTY 时输出干净（无 spinner 和颜色）
ctx7 docs /facebook/react "How to use hooks for state management" | head -50
ctx7 docs /vercel/next.js "How to add middleware for route protection" | grep -A5 "middleware"

非 TTY 检测是管道友好的关键：源码在模块加载时读取 process.stdout.isTTY（commands/docs.ts），非 TTY 时不启动 ora spinner、改用纯文本日志，因此管道、重定向、CI 环境中拿到的都是干净可解析的输出。

库重定向（301）处理：若库 ID 已被重命名/迁移，后端返回 301 与 redirectUrl，getLibraryContext（utils/api.ts）会将其转换为带 redirectUrl 的错误响应，CLI 随即提示 "Library has been redirected" 并直接打印新 ID 和可复制的重新执行命令（commands/docs.ts）——此时只需按提示用新 ID 重跑即可。

空结果：当两类片段都为空时，CLI 会打印 No documentation found for: "<query>" 警告（commands/docs.ts），通常意味着该库没有覆盖这个主题，可换更具体或换一个措辞再试。

认证与速率限制

文档命令无需登录即可工作。需要更高速率限制时，有两种方式（见 skills/context7-cli/SKILL.md 与 docs.md）：

# 方式 A：环境变量
export CONTEXT7_API_KEY=your_key

# 方式 B：OAuth 登录
ctx7 login

两条路径在源码中如何生效，可以直接在 utils/api.ts 的 getAuthHeaders 中确认：

• 环境变量 CONTEXT7_API_KEY 优先——设置后直接以 Authorization: Bearer <apiKey> 发出；
• 否则使用本地存储的 OAuth access token；
• 每个请求还会带上 X-Context7-Source: cli、X-Context7-Client-IDE: ctx7-cli、客户端版本与传输类型等标识头。

关于 ctx7 login 的实现细节（utils/auth.ts）：登录走 RFC 8628 设备授权流（/api/oauth/device/code 发起、/api/oauth/device/token 轮询，网络抖动与 5xx 均按瞬态错误继续轮询）；access token 过期（提前 60 秒判定）会自动用 refresh token 刷新，且遵循 RFC 6749 §6 保留原有 refresh_token；凭据文件以 0o600 权限写入并强制收紧权限，ctx7 logout 会同时清理新路径与旧路径的凭据文件。

速率限制方面，参考 docs/api-guide.mdx：未带 API key 时为低速率限制；带 API key 时按套餐获得更高额度。超限返回 429，并携带 Retry-After、RateLimit-Limit、RateLimit-Remaining、RateLimit-Reset 响应头。因此在前文"每问最多 3 次 ctx7 library / 3 次 ctx7 docs"的约束之外，脚本化场景还应按 429 响应做退避重试；文档更新频率不高，脚本中缓存结果数小时至数天也是推荐做法。

命令速查与相关资源

命令	作用
ctx7 library <name> "<query>"	解析库名 → 库 ID（Step 1）
ctx7 library <name> "<query>" --json	同上，JSON 输出便于脚本取 .[0].id
ctx7 docs <libraryId> "<query>"	查询库文档（Step 2）
ctx7 docs <libraryId> "<query>" --json	JSON 输出 codeSnippets / infoSnippets
ctx7 docs /owner/repo/<version> "<query>"	查询指定版本的文档
ctx7 login / ctx7 whoami / ctx7 logout	登录（提升速率限制）/ 查看状态 / 登出

延伸阅读与佐证路径：

• 技能入口与整体命令面：skills/context7-cli/SKILL.md
• 文档命令实现：packages/cli/src/commands/docs.ts
• API 调用与鉴权头构造：packages/cli/src/utils/api.ts
• 库 ID 校验与 Git Bash 恢复：packages/cli/src/utils/library-id.ts、packages/cli/src/tests/library-id.test.ts
• 数据结构定义：packages/cli/src/types.ts
• 后端 API 全貌（端点、库 ID 格式、限流与错误码）：docs/api-guide.mdx
• 相关技能参考：skills.md（技能管理）、setup.md（MCP 配置）

适用前提小结：以上行为基于当前仓库中 packages/cli 的源码与 skills/context7-cli 技能文档；ctx7 library 的 query 参数参与后端排序、非 TTY 下输出干净、Git Bash ID 自动恢复等细节均以仓库当前实现为准。执行时建议使用最新的 CLI 版本（npm install -g ctx7@latest 或 npx ctx7@latest），并遵守每问各 3 次调用的节制原则。