数据截至 (上游 commit 5284672feb57)
分发即产品:Skills / Plugins / Rules 与两种交付模式
30 秒导读: 前面几章讲的是 Context7 的「引擎」——SDK、MCP 服务器、CLI(见 01/02/03/04)。 这一章讲的是「包装与投放」:仓库里
packages/之外那一大堆.md/.json文件,它们本身不跑逻辑,而是被投递到各家编码代理里的说明书。它们的唯一使命,是让 Claude Code / Cursor / Codex / Copilot / Gemini 这些 agent 在写代码时默认想到「先去查最新文档」——查的动作,要么落成一条 CLI 命令,要么落成一次 MCP 工具调用。
1. 这是什么(零基础也能懂)
一句话定义: 这一章的主角是 Context7 的分发物(distribution artifacts)——一批面向 AI 的说明文件,复制到不同编码代理约定的目录里,就能把「用 Context7 查文档」变成那个 agent 的默认习惯。
先破一个误解: 很多人以为 Context7 的产品是 mcp.context7.com 那个后端。其实后端是私有的、不在这个仓库里(README 明说仓库只含 MCP 服务器源码,解析/爬取引擎不公开)。这个开源仓库里真正被当成产品反复打磨的,恰恰是本章这些说明文件。
为什么它们重要 —— 「货架战争」: 模型训练数据会过期,写代码时经常「记错 API」。Context7 要解决这个,但前提是 agent 得先想起来用它。所以真正的产品问题不是「怎么查文档」,而是:
怎么让每一家 agent、在每一次该查文档的时候,都自动触发去查?
答案就是:把「触发说明」做成各家 agent 认得的格式(Claude 认 Skill、Cursor 认 .mdc Rule、大家都认 MCP……),一份份塞进它们的配置目录。谁占住了这块「货架」,谁就赢。
用起来什么样: 用户其实只敲一条命令,剩下的分发全自动完成:
npx ctx7 setup # 交互式:先问你选哪种模式,再问装到哪个 agent
它会问你两个问题——用哪种交付模式(下一节的两条路线),以及装给哪个 agent——然后把对应的分发物落到该 agent 的正确目录(这一步的执行器是 packages/cli/src/setup/agents.ts,见 03 章)。
一句话直觉: 把这些文件想成塞进各家便利店货架的产品说明卡。产品(查最新文档的能力)是同一个,但每家店(agent)货架规格不同,于是同一句话被翻译成 Skill、Rule、Command、Plugin、MCP 配置等十几种包装,一份份摆进去。
本节不出现底层代码。目标:明白「Context7 的产品 = 让 agent 默认想到去查文档」这件事,是靠一堆分发文件、而不是靠那个后端实现的。
2. 顶层全景(分发物怎么摆放)
先看这张图怎么读: 从上到下是「一句触发意图」如何被复制成越来越多的包装形态,最终落到各家 agent。左半边是 CLI + Skills 路线,右半边是 MCP 路线(§3 详解)。
「该查文档时就去查最新文档」 ← 同一个意图
│
┌───────────────────┴───────────────────┐
│ │
CLI + Skills 路线 MCP 路线
(装一个技能/规则, (注册一个 MCP 服务器,
让 agent 去跑 ctx7 命令) agent 原生调两个工具)
│ │
┌─────────┼──────────┐ ┌──────────┼───────────┐
│ │ │ │ │ │
skills/ rules/ (无需 skills/ rules/ plugins/
find-docs context7- MCP) context7-mcp context7-mcp 各家封装
SKILL.md cli.md SKILL.md .mdc (claude/codex/
context7- copilot/cursor)
cli/ + .mcp.json
└───────────────┬─────────────────────────┘
│
交付载体(把上面这些打包/投放)
┌─────────────┬──────────────┬───────────────┬───── ────────┐
.claude-plugin/ .agents/ gemini- plugins/ i18n/ + public/
marketplace.json plugins/ extension.json context7-power (多语言 README
(Claude 市场) marketplace (Gemini CLI (Amp「Power」) + 图标素材)
(Codex 市场) 扩展清单)
各类分发物一句话职责:
| 分发物 | 路线 | 干什么 | 位置 |
|---|---|---|---|
skills/find-docs | CLI+Skills | 教 agent 用 npx ctx7 命令查文档 | skills/find-docs/SKILL.md |
skills/context7-cli | CLI+Skills | 完整 ctx7 CLI 说明书(文档+技能管理+setup) | skills/context7-cli/SKILL.md + references/ |
skills/context7-mcp | MCP | 教 agent 调 MCP 的两个工具 | skills/context7-mcp/SKILL.md |
rules/context7-cli.md | CLI+Skills | 贴进 CLAUDE.md / 规则文件的短规则(CLI 版) | rules/context7-cli.md |
rules/context7-mcp.md | MCP | 同上,MCP 版 | rules/context7-mcp.md |
plugins/<agent>/context7 | 多为 MCP | 各家 agent 的整包插件(含 agent/command/skill/MCP 配置) | `plugins/claude |
plugins/context7-power | MCP | Amp 的「Power」封装 | plugins/context7-power/POWER.md |
.claude-plugin/ .agents/ .github/plugin/ | — | 各家「插件市场」清单,指向 plugins/ | 仓库根 |
gemini-extension.json | MCP | Gemini CLI 扩展清单(直接内联 MCP 配置) | 仓库根 |
i18n/ public/ | — | 15 种语言 README + 品牌图标(投放的「门面」) | 仓库根 |
主线走一遍(高层): 用户跑 ctx7 setup → 选模式 + 选 agent → agents.ts 把上表对应的文件写到该 agent 的目录 → 之后该 agent 每次遇到库相关问题,就被这些说明触发去查文档。分发物是「静态说明」,setup 命令是「投放机」。
3. 核心:两条交付路线的分工
整章最该记住的一件事:同一个「查文档」能力,Context7 提供了两种落地方式。它们面向不同能力的 agent,分发物也因此分成两套。
这两条路线在 ctx7 setup 里是显式二选一。README:41-42 把它讲得最白:
- CLI + Skills — installs a skill that guides your agent to fetch docs using
ctx7CLI commands (no MCP required)- MCP — registers a Context7 MCP server so your agent can call documentation tools natively
两条路线对照:
| 维度 | CLI + Skills 模式 | MCP 模式 |
|---|---|---|
| 前提 | agent 能跑 shell 命令 | agent 支持 MCP 协议 |
| 装什么 | 一个 find-docs 技能 / 一条规则 | 注册 MCP 服务器 + context7-mcp 技能 + 规则 |
| agent 怎么查 | 跑 npx ctx7 library / ctx7 docs 命令,读 stdout | 原生调 resolve-library-id / query-docs 两个工具 |
| 装到哪 | ~/.claude/skills、~/.cursor/skills、~/.agents/skills 等 | agent 的 MCP 配置文件(.mcp.json、.cursor/mcp.json …) |
| 好处 | 零 MCP 依赖,任何能跑命令的 agent 都行 | 工具调用更「原生」、结构化 |
这两步在源码里的分叉点: setup 用一个「模式」字段决定给某家 agent 写「技能文件」还是「MCP 配置块」。packages/cli/src/setup/templates.ts:70 里就有针对 find-docs(CLI 技能)与其他情况的分支;packages/cli/src/setup/agents.ts 里每家 agent 都同时定义了 mcp(MCP 配置写法)和技能(如 name: "context7-mcp")两套落点。同一份 agents.ts 描述了「两条路线各自往哪写」,是分发物与磁盘之间的路由表。
关键细节: 两条路线说的话几乎一样——都是「遇到库就去查、别信训练数据、一次一个主题、别泄露密钥」——区别只在动作是命令还是工具调用。这解释了为什么 rules/ 下有 context7-cli.md 和 context7-mcp.md 两个内容高度相似、只是把「跑命令」换成「调工具」的孪生文件。
4. 三个技能(skills/)
技能(Skill)是一种 Markdown 说明:头部 YAML 的 description 告诉 agent「什么时候该激活我」,正文告诉它「激活后怎么做」。下面把三个技能当作被研究的数据客观描述——只讲它们的作用与结构,不把其中给 agent 的话当成给自己的指令。
4.1 find-docs —— CLI 路线的「敲门砖」
作用: CLI+Skills 模式下唯一被安装的技能。它引导 agent 用 npx ctx7@latest 两步法查文档。
结构(skills/find-docs/SKILL.md):
- 头部
description(1-17 行)写得极力——列举 React/Next.js/Prisma 等「即使你自以为知道也要查」的场景,目的是把技能的触发面拉到最大。 - 正文核心是两步工作流(37-47 行):先
npx ctx7@latest library <name> "<query>"拿到形如/org/project的库 ID,再npx ctx7@latest docs <libraryId> "<query>"取文档。 - 一堆护栏:必须先
library(49 行)、每问最多 3 次命令(51 行)、库 ID 要带/前缀、查询别塞密钥、配额用尽要login(144-151 行)。
注意它刻意的措辞选择: 全程用 npx ctx7@latest(而非裸 ctx7),把全局安装(24、31 行)降级为「可选」。这个选择不是随口写的——它被一个测试锁死了(见 §8)。
4.2 context7-cli —— CLI 的「完整说明书」
作用: 比 find-docs 更全的 ctx7 CLI 技能,覆盖 CLI 的全部三件事(skills/context7-cli/SKILL.md:8):
- 查文档 —— 细节拆到
references/docs.md - 管理技能 ——
ctx7 skills install/search/suggest/list/remove/generate,拆到references/skills.md - 配置 MCP ——
ctx7 setup,拆到references/setup.md
结构上的巧思(渐进式披露): 主 SKILL.md 只放「快速参考 + 认证 + 常见错误」,把三块细节外链到 references/ 三个文件。agent 先读便宜的主文件判断相关性,需要哪块再下钻——这正是 §2 图里「说明书分层」的思路。
references/setup.md:5-8 值得一提,因为它就是 §3 两条路线的权威原文:setup 首次运行会问你选 MCP server 还是 CLI + Skills,并在文末(37-44 行)分别列出两种模式各自「会往磁盘写什么」。
4.3 context7-mcp —— MCP 路线的技能
作用: MCP 模式下安装的技能。它不教命令,而是教 agent 调 MCP 的两个工具。
结构(skills/context7-mcp/SKILL.md): 四步——resolve-library-id(拿 ID)→ 选最佳匹配 → query-docs(取文档)→ 融入回答。护栏和 CLI 版同构:一次一个主题、多概念拆多次调用、认版本。
一个重要事实: 这份 context7-mcp/SKILL.md 会被原样复制进各家插件——plugins/claude、plugins/cursor、plugins/codex、plugins/copilot 下的 skills/context7-mcp/SKILL.md 与它逐字节相同(实测四份 diff 无差异)。也就是说,它是 MCP 路线的单一事实源,插件只是它的搬运容器。
5. 规则(rules/)—— 贴进 CLAUDE.md / Cursor Rules 的短文本
作用: 规则(Rule)比技能更轻——它不是独立文件夹,而是**一段可以直接粘进 agent「常驻上下文」**的文字(比如 Claude 的 CLAUDE.md、Cursor 的 Rules)。README:85-99 专门有「Add a Rule」小节教手动添加。
仓库提供两份孪生规则,对应两条路线:
| 文件 | 面向 | 第一句话(意图) |
|---|---|---|
rules/context7-cli.md | 能跑命令的 agent | 「用 ctx7 CLI 查当前文档」 |
rules/context7-mcp.md | 支持 MCP 的 agent | 「用 Context7 MCP 查当前文档」 |
它们几乎是同一段话的两个版本。 两者开头都是同一句「遇到 library/framework/SDK…就去查,即使你以为知道」,都有同一句「不要用于重构/从零写脚本/调业务逻辑/代码审查/通用编程概念」。唯一实质差异在「怎么查」那步:CLI 版写命令(rules/context7-cli.md:7-10),MCP 版写工具名(rules/context7-mcp.md:7-10 的 resolve-library-id / query-docs)。
Cursor 的规则是特殊格式: plugins/cursor/context7/rules/use-context7.mdc 是 Cursor 专用的 .mdc 格式,头部带 alwaysApply: true(2-4 行)——意思是「每次对话都常驻生效」,不用等触发。它比 rules/ 里那两份更「省」:只说「拿不准库 API 时去查」,细节让 agent 去看 context7-docs-lookup 技能。
6. 插件(plugins/)—— 各家 agent 的整包封装
作用: 插件(Plugin)是把「MCP 配置 + 技能 + 命令 + 子 agent」打成一整包,让用户在某家 agent 的插件市场里一键装齐。仓库为四家主流 agent 各准备了一包。
四家插件的「零件清单」(注意各家目录约定不同):
| Agent | 插件目录 | 含哪些零件 | 清单文件 |
|---|---|---|---|
| Claude Code | plugins/claude/context7/ | agent + command + skill + MCP | .claude-plugin/plugin.json |
| Codex | plugins/codex/context7/ | skill + MCP(无 agent/command) | .codex-plugin/plugin.json |
| Copilot | plugins/copilot/context7/ | agent + command + skill + MCP | plugin.json(根级) |
| Cursor | plugins/cursor/context7/ | agent + rule(.mdc)+ skill + MCP | .cursor/plugin.json |
三种可复用零件,值得单独看:
-
子 agent
docs-researcher(plugins/claude/context7/agents/docs-researcher.md)—— 一个「轻量文档研究员」子 agent,model: sonnet(4 行),专门在不污染主对话上下文的前提下去查文档、回一个精炼答案。Copilot 版是同一份内容、换成.agent.md后缀且去掉model字段(plugins/copilot/context7/agents/docs-researcher.agent.md)。 -
斜杠命令
/context7:docs(plugins/claude/context7/commands/docs.md)—— 头部argument-hint: <library> [query](3 行),让用户直接敲/context7:docs react hooks触发查询。逻辑:库名以/开头就当 ID 直接用,否则先resolve-library-id(29-33 行)。 -
MCP 配置块 —— 各家写法各不相同,这正是「同一产品、多种货架规格」的最好例证:
| 插件 | MCP 传输方式 | 关键写法 |
|---|---|---|
plugins/claude/.mcp.json | HTTP | "type":"http" + url + CONTEXT7_API_KEY header |
plugins/cursor/context7/mcp.json | HTTP | 裸 url(无 type) |
plugins/context7-power/mcp.json | HTTP | 最简:只有 url |
gemini-extension.json(根级) | stdio | command:"npx" + @upstash/context7-mcp + --api-key |
context7-power —— Amp 的「Power」封装: plugins/context7-power/POWER.md 是给 Amp(它把插件叫「Power」)的一份说明。头部是 YAML frontmatter(name/displayName/keywords…),正文结构和 context7-mcp 技能几乎一样(四步 + 最佳实践),只是术语从「Skill」换成「Power」。同一套话术的又一次换皮。
7. 交付载体:市场清单 / 扩展 / 门面
上面那些零件要能「被发现、被安装」,还需要一层投放清单。它们本身不含 AI 指令,是纯粹的元数据。
三个「插件市场」清单,各指向对应的 plugins/ 子目录:
| 清单 | 面向的市场 | 指向 |
|---|---|---|
.claude-plugin/marketplace.json | Claude Code 市场 | ./plugins/claude/context7(version 1.0.2) |
.agents/plugins/marketplace.json | Codex 市场 | ./plugins/codex/context7(带 policy/category) |
.github/plugin/marketplace.json | Copilot CLI 市场 | ./plugins/copilot/context7 |
Gemini 走「扩展」而非「市场」: gemini-extension.json(仓库根)是 Gemini CLI 的扩展清单,它不指向 plugins/,而是直接内联 MCP 配置(mcpServers.context7 用 stdio 跑 @upstash/context7-mcp)和一个 CONTEXT7_API_KEY 设置项。它是自包含的,setup 里 Gemini 也被当成一等目标(agents.ts:14-21 的 SETUP_AGENT_NAMES 含 gemini: "Gemini CLI")。
门面:多语言 README 与图标:
i18n/下有 15 种语言的 README(README.zh-CN.md、README.ja.md、README.ar.md…)。这是把「分发即产品」推向全球开发者的门面——同一个「让 agent 查最新文档」的卖点,翻成 15 种语言摆上货架。public/下是品牌素材(context7-icon-green.svg、cover.png、icon.png等),被各家plugin.json的logo/brandColor字段引用(如plugins/cursor/context7/.cursor/plugin.json:11引context7-icon-green.svg、primaryColor:"#059669")。统一的绿色视觉,是这块货架的「招牌」。
8. 对齐约束:技能内容必须跟 CLI 行为一致
分 发物是静态文本,而 CLI 是会演进的代码。风险是:CLI 改了行为,技能里的说明却没跟着改,agent 就会照着过时说明去敲一条已经失效的命令。仓库用单元测试把两者钉在一起。
测试一:find-docs 技能必须跟 CLI 规则同款(packages/cli/src/__tests__/find-docs-skill-alignment.test.ts)——它直接读磁盘上的 skills/find-docs/SKILL.md 和 rules/context7-cli.md,断言三件事:
| 断言(测试用例) | 钉住的约束 | 位置 |
|---|---|---|
技能里出现 npx ctx7@latest library/docs,且没有裸 ctx7 library 开头 | 规范调用风格必须是 npx ctx7@latest | 11-17 行 |
技能和规则都含 "Next.js" not "nextjs",技能含 library "Next.js" | 官方库名写法(带标点)两处一致 | 19-26 行 |
npx ctx7@latest 出现的位置早于 npm install -g | 全局安装不能被写成首选工作流 | 28-34 行 |
这解释了 §4.1 的措辞选择: find-docs 全程用 npx ctx7@latest、把全局安装放到后面,不是文笔偏好,而是被这三条断言强制的。改文档时若违反,CI 直接红。
测试二:skills list 的输出契约(packages/cli/src/__tests__/skill-list.test.ts)——它在临时目录里造出 .agents/skills/find-docs 和 .cursor/skills/cursor-helper 两个技能,跑 ctx7 skills list --json,断言输出把它们分别标成 source: "universal" 和 source: "cursor"(47-68 行)。这钉住的是**「 技能装在哪个目录 → 归属哪个 agent」的映射**,正是 §2 里各家目录约定的机器化保证。
一句话: 这两个测试让「分发物」和「CLI 实际行为」不能各说各话——文档漂移会被当成 bug 拦下。这是「分发即产品」能长期成立的工程底座。
9. 边界与局限(诚实)
- 后端不在本仓库。 这些分发物最终都指向
mcp.context7.com或ctx7CLI,而真正干活的解析/爬取引擎是私有的(README:136 明说)。本章能讲清「怎么投放、投放了什么」,但讲不了「文档质量怎么来的」——那在仓库之外。 - 分发物是「说明」不是「保证」。 技能/规则只能提高 agent 想起查文档的概率,不能强制。Cursor 的
alwaysApply: true是最强的一档,但多数技能仍靠description里的关键词去「诱发」激活。 - 孪生文件的维护负担。 CLI 版/MCP 版规则、四份复制的
context7-mcp技能、五种写法的 MCP 配置——同一句话散落在十几处。§8 的测试只覆盖了 find-docs 与 CLI 规则的对齐,其余副本的一致性没有测试兜底(inferred:仓库里只找到这两个对齐测试)。 - 各家目录/清单格式必须手工跟上。 每当某家 agent 改了插件目录约定或 MCP 配置 schema,
agents.ts和对应清单都得手动改——这是「占满每一块货架」策略天然的边际成本。
10. 代码地图(导航索引)
| 主题 | 文件路径 | 关键符号 / 锚点 |
|---|---|---|
| 两种交付模式的权威说明 | skills/context7-cli/references/setup.md | 「MCP server」/「CLI + Skills」(5-8 行、37-44 行) |
| CLI 敲门砖技能 | skills/find-docs/SKILL.md | 两步法 npx ctx7@latest library/docs |
| CLI 完整说明书 | skills/context7-cli/SKILL.md + references/{docs,skills,setup}.md | 「三件事」(8 行) |
| MCP 技能(单一事实源) | skills/context7-mcp/SKILL.md | resolve-library-id / query-docs 四步 |
| 孪生规则文本 | rules/context7-cli.md、rules/context7-mcp.md | 首句「遇到 library 就去查」+「Do not use for」 |
| Cursor 常驻规则 | plugins/cursor/context7/rules/use-context7.mdc | alwaysApply: true |
| 子 agent | plugins/claude/context7/agents/docs-researcher.md | model: sonnet |
| 斜杠命令 | plugins/claude/context7/commands/docs.md | argument-hint: <library> [query] |
| Amp Power 封装 | plugins/context7-power/POWER.md | frontmatter name: "context7" |
| 各家 MCP 配置写法 | plugins/*/context7/*.mcp.json、gemini-extension.json | mcpServers.context7(http vs stdio) |
| 三个市场清单 | .claude-plugin/marketplace.json、.agents/plugins/marketplace.json、.github/plugin/marketplace.json | plugins[].source |
| 投放执行器(见 03 章) | packages/cli/src/setup/agents.ts | SETUP_AGENT_NAMES、RuleType、各 agent 的 mcp 块 |
| 模式分支 | packages/cli/src/setup/templates.ts:70 | skillName !== "find-docs" 分支 |
| 对齐约束(技能↔CLI) | packages/cli/src/__tests__/find-docs-skill-alignment.test.ts | 三个 test(...) |
| 目录归属契约 | packages/cli/src/__tests__/skill-list.test.ts | `source: "universal" |
与同组其它章的关系: 本章是货架最外层——回指 03 章 的
ctx7 setup/agents.ts(把本章分发物落地的执行器),依赖 02 章 的resolve-library-id/query-docs(MCP 路线调用的两个工具),复用 04 章 的提示词设计(本章各技能/规则里那套「一次一主题、别信训练数据」话术的同源)。想先理解 Context7 全貌,回 index。