Context7 pi 扩展：context7-docs 技能如何让 AI 编码代理自动检索最新库文档
【免费下载链接】context7Context7 Platform -- Up-to-date code documentation for LLMs and AI code editors项目地址: https://gitcode.com/gh_mirrors/co/context7
本文以packages/pi包中的 context7-docs 技能 为主体，完整拆解这项技能如何教会 pi coding agent 在正确的时机调用resolve-library-id与query-docs两个工具，走通"解析库 ID → 查询文档 → 引用作答"的三步工作流。读完后你将理解技能声明文件（Skill）的 frontmatter 设计、工具的参数契约与约束规则，并能直接安装、配置并验证这套文档检索能力。
1. 技能是什么：SKILL.md 的声明式契约
pi 扩展通过 context7.ts 扩展入口 向 pi 注册了两个 LLM 可调用的工具：
function context7(pi: ExtensionAPI): void { pi.registerTool(resolveLibraryIdTool); pi.registerTool(queryDocsTool); }但"工具被注册"不等于"agent 会主动用"。SKILL.md 的作用正是补齐这一环：它的 YAML frontmatter 定义了技能名称context7-docs和一段触发式description，核心策略写得很直白——只要用户提到某个具体库，即使模型自认为知道答案，也应优先调用技能而非依赖训练数据，因为训练数据中的 API 细节、函数签名和配置项经常已经过时。
description中还明确了"必须使用"的场景清单，可直接作为行为基线参考：
- API 语法类问题（"Prisma 的
findMany带关联查询的语法是什么？"） - 配置项问题（"Next.js 16 怎么配置缓存？"）
- 版本迁移问题（"Tailwind v4 在 Vite 中的安装方式变了"）
- "how do I" 类且提及库名的问题
- 涉及库特定行为的调试问题
- 安装/搭建步骤与 CLI 工具用法
文档同时给出了四个典型触发示例，覆盖不同生态：Next.js 16 缓存配置、PrismafindMany关联查询、Tailwind v4 + Vite 安装、@upstash/ratelimit限流。这个设计思路是：用描述中的"宁可错用、不可漏用"倾向，对抗 LLM 对陈旧知识的过度自信。
2. 两个工具：技能依赖的能力底座
技能文档中提到的两个工具，其实现分别位于 resolve-library-id.ts 和 query-docs.ts，参数用 typebox 声明，与 MCP 版保持逐字一致（见 prompts.ts 头部注释）。
2.1 resolve-library-id：把库名解析为 Context7 ID
| 参数 | 类型 | 说明 |
|---|---|---|
query | string | 要在这座库的文档中查找的内容。用于按"用户想完成什么"给结果排序，会发送到 Context7 API，禁止包含 API key、密码、凭证、个人数据或专有代码 |
libraryName | string | 要搜索的库名。要求使用官方完整拼写，如Next.js而非nextjs、Three.js而非threejs |
从 prompts.ts 中的工具描述可以看到，该工具的调用规则是强制性的：除非用户已在查询中显式给出/org/project或/org/project/version格式的 ID，否则必须先调用它获取合法 ID。每个结果包含：Library ID、名称、描述、代码片段数量（Code Snippets）、来源信誉（Source Reputation：High/Medium/Low/Unknown）、基准分（Benchmark Score，100 为最高分）、可用版本列表。若用户提供了版本，应从版本列表中选用对应值，拼成/org/project/version格式。
2.2 query-docs：按 ID 拉取文档片段
| 参数 | 类型 | 说明 |
|---|---|---|
libraryId | string | 精确的 Context7 库 ID，例如/mongodb/docs、/vercel/next.js，或带版本/vercel/next.js/v14.3.0-canary.87；来自resolve-library-id的返回或用户直接提供 |
query | string | 要查找的内容，限定为单一概念。要具体，一个查询只覆盖一个主题 |
query参数的描述（prompts.ts L59-L60）给出了明确的正反例：
- 好：
How to set up authentication with JWT in Express.js、React useEffect cleanup function examples - 坏（太模糊）：
auth、hooks - 坏（太宽泛）：
routing and auth and caching in Next.js
规则是：用户问题跨多个独立概念时，每个概念单独发起一次调用（使用相同 libraryId）；只有当问题问的是"这些概念如何交互"时才合并。这与技能文档 Workflow 第 2 步的表述完全对应。
3. 三步工作流：从技能指令到工具调用链
技能文档的 Workflow 一节定义了完整流程，与源码调用链一一对应：
第 1 步 解析库 ID。调用resolve-library-id，传入库名和查找意图。工具内部走 api.ts 中的 searchLibraries，请求https://context7.com/api/v2/libs/search，以 query 参数携带query和libraryName。返回结果经过 formatSearchResults 格式化后输出，多条结果之间以----------分隔。挑选最佳匹配时的优先级：官方来源、名称匹配度、高基准分。
格式化逻辑中有一处值得注意的映射（format.ts L6-L13）：来源信誉由数值trustScore分档——>= 7显示为 High，>= 4显示为 Medium，其余为 Low，缺失或负值为 Unknown。另外若响应中searchFilterApplied为 true，输出顶部会追加一条提示：结果已被 teamspace 的库过滤器裁剪，可到 Context7 dashboard 的 policies 页调整阈值。
第 2 步 查询文档。调用query-docs，内部走 fetchLibraryContext，请求https://context7.com/api/v2/context，返回文档片段与代码示例。源码中还有一个防御性分支：若服务端返回空文本，会返回明确指引——"这可能因为使用了非法的 Context7 库 ID，请改用resolve-library-id重新解析"。
第 3 步 作答。引用所使用的库 ID，并在相关处逐字引用代码示例。
技能文档还定义了一条快捷路径：若用户直接提供/org/project或/org/project/version格式的 ID，跳过第 1 步，直接调用query-docs。这一规则同样写进了两个工具自身的 description 中，形成技能、工具描述、用户输入三处一致的约束。
4. 约束规则：调用配额、数据安全与认证
技能文档的 Constraints 一节列出了三条硬性规则，它们与源码实现相互印证：
1）每问不超过 3 次调用。"Do not call either tool more than 3 times per question." 这一配额同时写在技能文件和两个工具的描述里（prompts.ts L40、L54），并在 resolve-library-id 描述中补充了兜底策略："如果 3 次后仍未找到，就用手上最好的结果"。这是对 agent 循环调用的成本保护。
2）query参数不得携带敏感信息。API key、密码、凭证、个人数据、专有代码都不能作为query传入，因为该参数会被发送到 Context7 API。两个工具的参数描述中都重复了这条数据安全声明。
3）认证使用CONTEXT7_API_KEY环境变量。从 api.ts 的 authHeaders 可以看到实现：读取该环境变量，存在则附加Authorization: Bearer <key>头，不存在则裸奔（依赖 IP 级限流试运行）。出错时 parseErrorResponse 会给出针对性提示：
- 401：API key 无效，提示 key 应以
ctx7sk前缀开头； - 429：限流或配额用尽，区分有无 key 分别建议升级套餐或到 Context7 官方 dashboard 创建免费 key；
- 404：库不存在，建议换一个 library ID。
技能文档要求：当请求因认证失败报错时，到 Context7 官方 dashboard 获取 key。
5. 安装、认证与验证
结合 packages/pi 的 README，这套能力的落地步骤如下：
安装扩展（同时带来两个工具、本技能以及手动检索命令）：
pi install npm:@upstash/context7-pi配置认证（可选但建议）。不配置时扩展按 IP 限流工作，适合试用；需要更高配额时：
export CONTEXT7_API_KEY=ctx7sk_...建议写入 shell profile，使 pi 启动时即可读取。
验证工作流。安装后直接用自然语言提问即可触发技能：
how do I configure caching in Next.js 16?也可以不依赖 agent 自动触发，用扩展附带的/c7-docs斜杠命令手动执行"解析 + 查询"组合流程：
/c7-docs next.js Cache Components观察 agent 行为时，可对照本文第 3 节的三步检查：先出现resolve-library-id调用（返回 ID 形如/vercel/next.js），再出现query-docs调用，最终答案中引用库 ID 并给出代码示例。
6. 小结
context7-docs 技能 是 pi 扩展中"让 agent 主动查文档"的行为层设计：frontmatter 中的触发式描述解决"何时用"，三步工作流解决"怎么用"，Constraints 解决"用得有多克制"。而技能所依赖的两个工具，其参数契约、信誉分档（trustScore → High/Medium/Low）、错误语义（401/404/429 与ctx7sk前缀提示）都可以在 lib/tools 与 lib/api.ts 中逐行对照。理解这条"技能描述 → 工具注册 → API 调用"的链路，也就掌握了给 LLM 编码代理外挂实时文档能力的一套可复制模式。
【免费下载链接】context7Context7 Platform -- Up-to-date code documentation for LLMs and AI code editors项目地址: https://gitcode.com/gh_mirrors/co/context7
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
