Context7 ctx7 CLI 完全指南：检索库文档、管理 AI 技能与 MCP 配置（基于官方 Agent Skill 与源码）

本文以 Context7 仓库中为 AI 编码代理编写的官方技能定义 skills/context7-cli/SKILL.md 为核心，系统讲解 ctx7 CLI 的三大能力——两阶段库文档检索、AI 编码技能（Skills）管理、以及为编辑器/Agent 一键配置 Context7 MCP。文中所有命令与参数均以该技能文档及其引用子文档为基准，并结合 packages/cli 下的真实源码实现做了原理级补充，帮助你在自己的 AI 编码工作流中稳定、高效地使用 Context7。

一、ctx7 CLI 的定位：一个面向 Agent 的"技能"入口

skills/context7-cli/SKILL.md 并非普通的 README，而是一份标准的 Agent Skill 文件：头部是 YAML frontmatter，用来告诉 AI 代理"什么场景下应该激活本技能"。其 description 字段明确列出了激活条件——当用户提到 "ctx7" 或 "context7"、需要某个库的最新文档、想安装/搜索/生成技能，或需要为 AI 编码代理配置 Context7 时，该技能即被触发（见 SKILL.md）。

技能正文将 ctx7 CLI 的职责归纳为三件事，并各自链接到一份引用子文档：

• 文档检索（references/docs.md）——获取任意库的最新文档。适用于写代码、核对 API 签名、或你的训练数据可能已过时的场景；
• 技能管理（references/skills.md）——安装、搜索、推荐、列出、移除和生成 AI 编码技能；
• 环境配置（references/setup.md）——为 Claude Code / Cursor / OpenCode 等代理配置 Context7 MCP。

从源码结构看，CLI 包 packages/cli（npm 包名 ctx7，当前版本 0.5.9，要求 Node.js >= 18，基于 commander 构建命令、tsup 打包）与这份技能文档完全对应：入口文件 packages/cli/src/index.ts 依次注册了 skill（含别名）、auth、setup、remove、docs、upgrade 六组命令。值得注意的是，入口还内置了两个全局机制：

• --base-url <url> 全局选项，可通过 preAction hook 同时改写 API 基址与认证基址（index.ts），方便对接自托管的 Context7 环境；
• 每次执行命令前会触发 maybeShowUpgradeNotice 升级提示检查（index.ts）。

二、安装与调用方式

技能文档要求在执行任何命令前先确保 CLI 为最新版：

npm install -g ctx7@latest

或者不安装、直接用 npx 运行：

npx ctx7@latest <command>

这也是仓库内置的 find-docs 技能（ctx7 setup --cli 模式会写入的技能，见 skills/find-docs/SKILL.md）所推荐的方式——让 Agent 始终以 npx ctx7@latest 调用，避免全局版本过期。两种调用方式在能力上完全等价，区别只是是否需要裸的 ctx7 命令。

三、文档检索：两阶段工作流

这是 ctx7 CLI 的核心场景。整体流程固定为两步：先用 ctx7 library 把库名解析为 Context7 库 ID，再用 ctx7 docs 凭 ID 拉取文档。

# Step 1: resolve library ID
ctx7 library <name> <query>
# Step 2: fetch docs
ctx7 docs <libraryId> <query>

一个关键例外：如果用户已经给出形如 /org/project 或 /org/project/version 的库 ID，可以直接跳过第一步。

3.1 Step 1：用 ctx7 library 解析库

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 中包含 API 密钥、密码、凭据、个人数据或专有代码等敏感信息。

每条搜索结果包含以下字段：

字段	含义
Library ID	Context7 兼容标识符，格式 /org/project
Name	库/包名称
Description	简短摘要
Code Snippets	可用代码示例数量
Source Reputation	权威度指示（High / Medium / Low / Unknown）
Benchmark Score	质量分（100 为最高）
Versions	可用版本列表（如有）；若用户指定了版本，可用 /org/project/version 形式引用

源码中可以看到 Source Reputation 是如何算出来的：在 packages/cli/src/commands/docs.ts 中，trustScore 为 undefined 或小于 0 时显示 Unknown，>= 7 为 High，>= 4 为 Medium，其余为 Low。

官方给出的选择流程（供 Agent 或人遵循）：

1. 分析 query，理解用户到底想找哪个库；
2. 按以下优先级选最相关的匹配：名称相似度（精确匹配优先）、描述与 query 意图的相关性、文档覆盖度（Code Snippets 越多越好）、来源信誉（High/Medium 更权威）、Benchmark 分数（越高越好）；
3. 存在多个好候选时，说明后仍选最相关的一个继续；
4. 没有好候选时，明确告知并建议改进 query；
5. query 有歧义时，先向用户确认，而不是拍脑袋猜。

此外还有一条硬性约束：每个问题最多调用 ctx7 library 3 次，3 次后仍找不到就用手上最好的结果。

支持版本化 ID——从 ctx7 library 输出的 Versions 中选最接近用户所指版本的一个：

# 通用（最新索引版本）
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"

--json 可输出结构化 JSON 供脚本处理：

ctx7 library react "How to use hooks for state management" --json | jq '.[0].id'

源码里还有两处细节值得了解（见 packages/cli/src/commands/docs.ts）：

• 若 teamspace 配置了库过滤策略，结果会附带一条提示，说明当前列表只包含通过团队质量阈值/屏蔽策略的库，并引导去 dashboard 的策略页调整；
• TTY 环境下，输出末尾会自动打印一行"Quick command"，即 ctx7 docs "<top1.id>" "<your question>"，方便直接进入第二步。

3.2 Step 2：用 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"

同样地，每个问题最多调用 3 次 ctx7 docs。

如何写好 query：具体、带上相关细节，但一条 query 只问一个主题——如果问题跨多个概念，就为每个概念单独执行一次 ctx7 docs，除非问题本身就在问这些概念如何交互。文档给出的对照表：

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

模糊的单词 query 只会返回泛泛的结果；多主题 query 会稀释排序，导致每个主题都拿不到深度内容。

输出包含两类内容：code snippets（带标题、带语言标签的代码块）和 info snippets（带面包屑上下文的散文解释）。源码中 docs.ts 的渲染逻辑印证了这一点：先按 codeTitle + codeDescription 打印标题，再逐个输出 ```language 包裹的代码块；随后打印 breadcrumb 加正文的 info snippets。--json 模式则原样输出 codeSnippets / infoSnippets 结构化数据。

管道与脚本集成：非 TTY 环境下 CLI 输出自动变干净（无 spinner、无颜色），因此可以安全地管道处理：

ctx7 docs /facebook/react "How to use hooks for state management" --json

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"

源码中的健壮性细节（packages/cli/src/commands/docs.ts）：

• docs 命令会先用 recoverLibraryId() 恢复被 Git Bash（Windows）改写成 Windows 路径的 /owner/repo 参数；
• 随后用正则 /^\/[^/]+\/[^/]/ 校验 ID 格式，不合法时给出明确的错误提示（"Expected format: /owner/repo or /owner/repo/version"），在 Windows 上还会额外提示用双斜杠 //facebook/react 规避路径转换；
• 若服务端返回 redirect（库 ID 变更），CLI 会打印新 ID 并直接给出可复制的 ctx7 docs "<newId>" "<query>" 命令，而不是静默失败。

3.3 文档命令的认证

文档命令无需登录即可使用。需要更高限流时可二选一：

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

# 方式 B：OAuth 登录
ctx7 login

四、技能管理：ctx7 skills 全家桶

"Skills" 是 Context7 注册表中的 Markdown 文件，教 AI 编码代理针对特定库或任务的最佳实践、模式和工作流。技能文档给出的 Quick Reference 覆盖了 install / search / suggest / list / remove / generate 六类操作。

4.1 Install：从任意仓库安装技能

仓库格式固定为 /owner/repo：

ctx7 skills install /anthropics/skills           # 交互式——从列表中选择
ctx7 skills install /anthropics/skills pdf       # 按名称安装指定技能
ctx7 skills install /anthropics/skills --all     # 不提示，全部安装

可用 flag 指定目标 IDE：

ctx7 skills install /anthropics/skills pdf --claude     # 仅 Claude Code
ctx7 skills install /anthropics/skills pdf --cursor      # 仅 Cursor
ctx7 skills install /anthropics/skills pdf --universal   # 通用（.agents/skills/）
ctx7 skills install /anthropics/skills --all --global   # 所有技能 + 全局安装

别名：ctx7 si /anthropics/skills pdf。

4.2 Search / Suggest：找技能与自动推荐

按关键词全注册表搜索，输出带安装量与信任分的交互列表，选中即可安装：

ctx7 skills search pdf
ctx7 skills search typescript testing
ctx7 skills search react nextjs

别名：ctx7 ss pdf。

suggest 会自动检测项目依赖并推荐相关技能：

ctx7 skills suggest           # 扫描当前项目，装到项目级
ctx7 skills suggest --global  # 推荐结果装到全局
ctx7 skills suggest --claude  # 仅面向 Claude Code

它读取的依赖清单包括 package.json、requirements.txt、pyproject.toml、Cargo.toml、go.mod、Gemfile；检测不到任何依赖时，会退化为建议使用 ctx7 skills search。别名：ctx7 ssg。

4.3 Generate：AI 生成自定义技能（需登录）

ctx7 skills generate
ctx7 skills generate --claude   # 直接装到 Claude Code
ctx7 skills generate --global   # 装到全局技能目录

交互流程五步：

1. 描述你想要的专业领域（如 "OAuth authentication with NextAuth.js"）；
2. 从搜索结果中选择相关库；
3. 回答 3 个澄清问题以聚焦技能内容；
4. 审阅生成结果，可要求修改；
5. 选择安装位置。

额度限制：免费账户 6 次/周，Pro 账户 10 次/周。别名：ctx7 skills gen、ctx7 skills g。

4.4 List / Remove / Info

ctx7 skills list                    # 当前项目（所有检测到的 IDE）
ctx7 skills list --claude           # 仅 Claude Code
ctx7 skills list --global           # 全局技能
ctx7 skills list --global --claude  # 全局的 Claude Code 技能

ctx7 skills remove pdf              # 按名称卸载
ctx7 skills remove pdf --claude     # 仅从 Claude Code 卸载
ctx7 skills remove pdf --global     # 从全局卸载
# 别名：ctx7 skills rm、ctx7 skills delete

ctx7 skills info /anthropics/skills # 不安装，先浏览仓库中所有技能

info 的输出展示每个技能的名称、描述、URL，以及可直接复制的快速安装命令——适合先预览再决定安装。

4.5 IDE 目标 flag 一览

所有 skills 命令都支持以下 flag 来指定目标 AI 编码助手：

Flag	目录	使用者
--universal	.agents/skills/	Amp、Codex、Gemini CLI、OpenCode、GitHub Copilot
--claude	.claude/skills/	Claude Code
--cursor	.cursor/skills/	Cursor
--antigravity	.agent/skills/	Antigravity

不带 flag 时，CLI 会以交互方式让你选择一个或多个目标。任意 flag 再加 --global 即可安装到用户主目录（全局）而非当前项目。

五、ctx7 setup：为 Agent 配置 Context7

ctx7 setup 是一条一次性命令，首次运行会提示选择接入模式，两种模式的本质区别在于 Agent 通过什么方式获取文档上下文：

• MCP server 模式——把 Context7 MCP server 注册进代理配置，Agent 通过 MCP 协议原生调用工具；
• CLI + Skills 模式——不依赖 MCP，而是安装一个 find-docs 技能，引导 Agent 直接调用 ctx7 library / ctx7 docs 命令。

命令与 flag 全表（见 references/setup.md）：

ctx7 setup                     # 交互式——先选模式，再选 Agent/安装位置
ctx7 setup --mcp               # 跳过提示，使用 MCP server 模式
ctx7 setup --cli               # 跳过提示，使用 CLI + Skills 模式

# MCP 模式——指定目标 Agent
ctx7 setup --claude            # 仅 Claude Code
ctx7 setup --cursor            # 仅 Cursor
ctx7 setup --opencode          # 仅 OpenCode

# CLI + Skills 模式——指定安装位置
ctx7 setup --cli --claude      # Claude Code（~/.claude/skills）
ctx7 setup --cli --cursor      # Cursor（~/.cursor/skills）
ctx7 setup --cli --universal   # 通用（~/.agents/skills）
ctx7 setup --cli --antigravity # Antigravity（~/.config/agent/skills）

ctx7 setup --project           # 配置到当前项目而非全局
ctx7 setup --yes               # 跳过确认提示

认证选项：

ctx7 setup --api-key YOUR_KEY  # 使用已有 API key（MCP 与 CLI + Skills 两种模式都支持）
ctx7 setup --oauth             # 使用 OAuth endpoint（仅 MCP 模式，由 IDE 负责认证流程）

若不传 --api-key 或 --oauth，setup 会打开浏览器走 OAuth 登录；且 MCP 模式在登录成功后还会额外生成一把新的 API key。--oauth 是 MCP 模式专用的。

两种模式分别写入什么：

• MCP 模式：在 Agent 配置文件中写入 MCP server 条目（Claude 为 .mcp.json，Cursor 为 .cursor/mcp.json，OpenCode 为 .opencode.json）；写入一份 Context7 rule 文件，指示 Agent 用 Context7 查库文档；在 Agent 技能目录写入 context7-mcp 技能。
• CLI + Skills 模式：在所选 Agent 的技能目录写入 find-docs 技能，引导 Agent 使用 ctx7 library 与 ctx7 docs 命令——这正是仓库中 skills/find-docs/SKILL.md 描述的同一套两阶段工作流。

源码印证（packages/cli/src/commands/setup.ts）：setup 命令实际支持的 Agent flag 比文档更多——除 --claude / --cursor / --antigravity / --opencode 外，还支持 --codex 和 --gemini；另有 --stdio flag，用于把 MCP server 配置为本地 stdio 进程（默认是 HTTP 传输）。认证解析逻辑（setup.ts）也印证了文档描述：传了 --api-key 直接使用该 key；传了 --oauth 走 OAuth；否则先复用已有 token 或触发登录，然后 POST 到 /api/dashboard/api-keys 生成一把名为 ctx7-cli-<随机hex> 的新 API key 写入配置。

六、认证体系：login / logout / whoami 与 API key

ctx7 login               # 打开浏览器进行 OAuth
ctx7 login --no-browser  # 不打开浏览器，只打印 URL
ctx7 logout              # 清除已存储的 token
ctx7 whoami              # 显示当前登录状态（名称 + 邮箱）

各命令对登录的要求并不一致，这是使用 ctx7 时最容易被问到的边界：

• 绝大多数命令无需登录即可运行；
• skills generate 始终需要登录；
• ctx7 setup 需要登录，除非传了 --api-key 或 --oauth；
• 登录还能解锁 docs 系列命令的更高限流。

也可以完全绕过交互式登录，直接用环境变量注入 API key：

export CONTEXT7_API_KEY=your_key

实现细节（packages/cli/src/commands/auth.ts）：CLI 的登录走的是 RFC 8628 Device Authorization Grant 流程——先调用 startDeviceAuthorization 换取一次性 user code 与验证链接，在 boxen 框中打印（即使存在 verification_uri_complete 也同时展示裸 verification_uri 供屏幕阅读器/手动输入场景使用），再轮询 pollDeviceToken 直到浏览器端授权完成。这意味着在无法弹浏览器或跨设备的环境（如 SSH 终端）中，--no-browser 打印 URL 后到另一台设备完成授权即可。

七、常见错误与避坑清单

官方技能文档列出的 Common Mistakes，基本都对应源码中的真实校验逻辑：

• 库 ID 必须带 / 前缀——是 /facebook/react 而不是 facebook/react。源码里 docs.ts 的正则校验失败时会直接报 Invalid library ID；
• 必须先跑 ctx7 library——ctx7 docs react "hooks" 这种写法在缺少合法 ID 时必然失败；
• 技能仓库格式是 /owner/repo——例如 ctx7 skills install /anthropics/skills；
• skills generate 需要登录——先执行 ctx7 login；
• 每个问题各最多 3 次 ctx7 library / ctx7 docs 调用，拿不到理想结果就用已有最佳结果，避免死循环刷接口；
• query 中不要携带敏感信息（API key、密码、凭据、个人数据、专有代码）。

八、命令速查表

汇总技能文档 Quick Reference 与仓库源码中的全部命令：

# 文档检索
ctx7 library <name> <query>           # Step 1：解析库 ID（query 必填）
ctx7 docs <libraryId> <query>          # Step 2：拉取文档（ID 格式 /org/project[/version]）

# 技能管理
ctx7 skills install /owner/repo       # 从仓库安装（交互式选择）
ctx7 skills install /owner/repo name  # 安装指定技能
ctx7 skills search <keywords>         # 搜索注册表
ctx7 skills suggest                   # 按项目依赖自动推荐
ctx7 skills list                      # 列出已安装技能
ctx7 skills remove <name>             # 卸载技能
ctx7 skills generate                  # AI 生成自定义技能（需登录，Free 6 次/周 / Pro 10 次/周）
ctx7 skills info /owner/repo          # 预览仓库中的技能（不安装）

# 配置与认证
ctx7 setup                            # 配置 Context7 MCP（交互式）
ctx7 setup --mcp | --cli              # 直接指定模式
ctx7 setup --api-key KEY | --oauth    # 认证方式
ctx7 remove --cursor [--all|--cli]    # 移除已写入的 Context7 配置
ctx7 login [--no-browser]             # OAuth 登录（RFC 8628 设备授权）
ctx7 logout                           # 清除 token
ctx7 whoami                           # 查看登录状态

全局选项方面，从入口源码（packages/cli/src/index.ts）可确认：--version 查看版本（当前 0.5.9）、--base-url <url> 切换服务基址，且每次执行都会检查并提示可用升级。

九、小结

ctx7 CLI 是 Context7 面向终端和 AI 编码代理的统一入口：library + docs 两阶段命令解决"训练数据过期"这一 LLM 使用文档的根本痛点；skills 子命令组把"教 Agent 最佳实践"这件事做成了可搜索、可安装、可生成的包管理体验；setup 则用一条命令完成 MCP 或 CLI 两种接入方式的落地。配合本文源码级补充（信誉分映射、ID 校验与 Git Bash 兼容、设备授权登录、API key 自动生成），你可以完整理解每个命令背后的行为边界，并在自己的 Claude Code / Cursor / OpenCode / Codex / Gemini 工作流中放心复用这套流程。