Context7 pi 扩展实战：为 pi coding agent 接入 resolve-library-id 与 query-docs 实时文档工具

本文基于 Context7 官方仓库中的 packages/pi/README.md 及配套源码，讲解 @upstash/context7-pi 扩展如何为 pi coding agent 注入实时库文档能力：通过 resolve-library-id 和 query-docs 两个 LLM 可调用的工具、一个引导 agent 用法的 context7-docs skill，以及一个手动查询的 /c7-docs 斜杠命令。读完后你将掌握该扩展的安装、认证配置、四个组件的工作原理，以及工具参数（query、libraryName、libraryId）在源码层面的确切语义与底层 HTTP 调用链。

扩展是什么：给 pi 装上"实时文档检索器"

@upstash/context7-pi 是 Context7 面向 pi coding agent 的官方扩展（包版本 0.1.2，见 package.json）。它解决的核心问题是：LLM 的训练数据往往滞后于库的 API 变更，agent 回答库相关问题时容易引用过时签名或配置。该扩展通过两个 LLM-callable 工具把 Context7 托管的最新文档接入 agent 的工具循环：

• resolve-library-id —— 把包名或产品名解析为 Context7 库 ID（例如 Next.js → /vercel/next.js）。agent 应当优先调用它。
• query-docs —— 针对已解析的库 ID 拉取文档与代码示例。
• context7-docs skill —— 指导 agent 在用户询问任何库、框架、SDK、API、CLI 工具或云服务的场景下主动使用上述工具。
• /c7-docs <library> <question> —— 斜杠命令，一次执行"解析 + 查询"完整流程，用于手动查询。

从源码结构看，整个扩展在 package.json 的 pi 字段中声明了三个挂载点：extensions（指向 ./extensions）、skills（指向 ./skills）、prompts（指向 ./prompts），分别对应工具注册、skill 文件和斜杠命令模板。

安装：一条命令完成接入

安装方式来自官方 README，在 pi 环境中直接执行：

pi install npm:@upstash/context7-pi

files 字段限定了发布产物范围：extensions、lib、skills、prompts、LICENSE、README.md，即扩展是自包含的，没有额外的 Context7 运行时依赖（peer 依赖仅为 @earendil-works/pi-coding-agent 和 typebox）。

认证：IP 限流免配置，API Key 提升配额

扩展支持两种运行模式，均无需修改代码：

1. 零配置模式：不设置任何凭据即可使用，受 IP 维度的速率限制约束，适合先试用。
2. API Key 模式：在 context7.com/dashboard 生成免费 key 后，通过环境变量导出：

export CONTEXT7_API_KEY=ctx7sk_...

建议写入 shell profile，这样 pi 启动时自动继承该变量。

源码层面的处理在 lib/api.ts：authHeaders() 读取 process.env.CONTEXT7_API_KEY，存在时附加 Authorization: Bearer <key> 请求头，否则返回空对象——这正是"零配置可用"的实现。错误处理同样区分两种模式（lib/api.ts）：

HTTP 状态	无 Key 时的错误提示	有 Key 时的错误提示
429	提示到 context7.com/dashboard 创建免费 key	提示升级套餐（context7.com/plans）
404	库 ID 不存在，请更换 library ID	同左
401	（Key 无效）API key 应以 ctx7sk 前缀开头	同左
其他	返回 Request failed with status <code>	同左

组件一：工具注册入口

extensions/context7.ts 只有 10 行，展示了 pi 扩展的最小形态：

function context7(pi: ExtensionAPI): void {
  pi.registerTool(resolveLibraryIdTool);
  pi.registerTool(queryDocsTool);
}
export default context7;

pi 加载扩展后调用该默认导出，两个工具即进入 agent 的工具列表。测试文件 tests/extension.test.ts 用一个伪造的 ExtensionAPI 验证了恰好注册了 query-docs 和 resolve-library-id 这两个名字，并断言各自的参数 schema 键名——resolve-library-id 为 query + libraryName，query-docs 为 libraryId + query；另有一个 live 用例真实调用 Context7 API 验证返回文本。

组件二：resolve-library-id 工具

实现位于 lib/tools/resolve-library-id.ts。工具用 TypeBox 定义参数 schema：

const Params = Type.Object({
  query: Type.String({ description: RESOLVE_LIBRARY_ID_QUERY_DESCRIPTION }),
  libraryName: Type.String({ description: RESOLVE_LIBRARY_ID_LIBRARY_NAME_DESCRIPTION }),
});

两个参数的语义（定义在 lib/prompts.ts）：

• query：用户要在该库文档中查什么，用于给候选库按相关性排序；会被发送到 Context7 API，因此描述中明确要求不要包含 API key、密码、个人数据或专有代码。
• libraryName：待检索的库名，要求使用官方规范写法——例如 Next.js 而非 nextjs、Customer.io 而非 customerio、Three.js 而非 threejs。

执行逻辑分两支：调用 searchLibraries(query, libraryName) 后，若无结果则返回错误信息（如 No libraries found matching the provided name.）；有结果则把候选列表格式化为文本返回，形如：

Available Libraries:

- Title: ...
- Context7-compatible library ID: /org/project
- Description: ...
- Code Snippets: 123
- Source Reputation: High
- Benchmark Score: 95

格式化规则在 lib/format.ts 中，值得注意的是 Source Reputation 的换算：trustScore 缺失或小于 0 记为 Unknown，>= 7 为 High，>= 4 为 Medium，其余为 Low。若团队启用了 teamspace 库过滤，输出开头还会追加一条 searchFilterApplied 提示。

工具描述本身（lib/prompts.ts）内嵌了给 LLM 的使用纪律：除用户直接给出 /org/project 或 /org/project/version 形式的库 ID 外，必须先调用本工具再调用 query-docs；每个问题最多调用 3 次；选择库时按名称匹配度、描述相关性、Code Snippet 覆盖数、Source Reputation 与 Benchmark Score 综合权衡。

组件三：query-docs 工具

实现位于 lib/tools/query-docs.ts，参数同样用 TypeBox 定义：

• libraryId：精确的 Context7 库 ID，例如 /mongodb/docs、/vercel/next.js，也可带版本，如 /vercel/next.js/v14.3.0-canary.87。
• query：限定在单一概念的查询描述。描述中给出了正反例——好的是 "How to set up authentication with JWT in Express.js"，太模糊的如 "auth"，太宽的如 "routing and auth and caching in Next.js"；若问题横跨多个独立概念，应分多次调用而不合并（除非问题是关于这些概念如何交互）。这条约束在 CHANGELOG 0.1.1 中被统一应用到 MCP、CLI、pi 和 AI SDK 各端。

执行时调用 fetchLibraryContext(query, libraryId)（lib/api.ts）请求 https://context7.com/api/v2/context。有一个值得注意的边界：当响应体为空时（库不存在或文档未 finalized），返回一段引导性错误文本，提示用 resolve-library-id 重新解析合法 ID——这条错误路径直接写进了用户可见的输出。

所有结果经 lib/result.ts 的 toToolResult 封装为 pi 的 AgentToolResult（content: [{ type: "text", text }]）交回 agent。

组件四：context7-docs skill——教 agent "何时该查文档"

工具注册后还需要引导 agent 主动使用，这正是 skills/context7-docs/SKILL.md 的职责。frontmatter 中的 description 明确了两条强规则：

• 用户询问任何具体库时都应触发，包括 React、Next.js、Prisma、Express、Tailwind、Django、Spring Boot 这类"你本该很熟"的库——因为训练数据可能不反映最近的 API 变更或版本更新；
• "Use even when you think you know the answer"，且优先于网络搜索查库文档。

Skill 正文定义了标准工作流：

1. 解析：带库名和查询意图调用 resolve-library-id，从返回的候选中挑选最佳匹配（优先官方来源、名称匹配、高 benchmark 分）；
2. 查询：带所选库 ID 和单一概念查询调用 query-docs，多概念问题分次调用；
3. 作答：引用所用库 ID，代码示例尽量逐字引用。

若用户直接给出 /org/project 或 /org/project/version 形式的 ID，则跳过第 1 步直接调用 query-docs。约束部分重申：每工具每问题不超过 3 次调用；query 参数不得携带密钥、凭据、个人数据或专有代码。

组件五：/c7-docs 斜杠命令

prompts/c7-docs.md 通过 frontmatter 声明 argument-hint: <library> <question>，正文是带占位符的提示词模板：

Look up documentation for `$1` using Context7.

1. Determine what to look up in the library's documentation from `${@:2}`.
2. Call the `resolve-library-id` tool with `libraryName="$1"` and what to look up as `query` ...
3. Call the `query-docs` tool with the selected library ID and what to look up as `query`.
4. Summarize the answer for the user with code examples from the returned snippets. Cite the Context7 library ID you used.

其中 $1 是库名、${@:2} 是剩余参数拼接出的查询问题。若 $1 已经是 /org/project 或 /org/project/version 格式，模板指示跳过解析步骤直接查询——与 skill 的跳过逻辑保持一致。

典型用法

安装完成后，直接以自然语言提问，agent 会自动调用工具链：

how do I configure caching in Next.js 16?

手动触发完整流程则使用斜杠命令：

/c7-docs next.js Cache Components

其执行链路为：pi 展开 /c7-docs 模板 → agent 以 libraryName="next.js"、query="Cache Components" 调用 resolve-library-id → 从候选中选定库 ID → 以该 ID 调用 query-docs → 汇总文档片段并引用库 ID 作答。

底层 API 与一致性设计

两个工具最终都落在 lib/api.ts 的两个函数上：

• searchLibraries → GET https://context7.com/api/v2/libs/search?query=...&libraryName=...，返回 JSON（SearchResponse，结构定义在 lib/types.ts：包含 id、title、description、totalSnippets、trustScore、benchmarkScore、versions 等字段）；
• fetchLibraryContext → GET https://context7.com/api/v2/context?query=...&libraryId=...，直接返回纯文本文档内容。

源码注释点明了该包的一致性策略：api.ts、types.ts、format.ts 以及工具描述均逐字取自 @upstash/context7-mcp（lib/api.ts、lib/prompts.ts 顶部注释），目的是让 pi 客户端与 MCP 客户端拿到完全相同的 LLM 指令和输出格式。与 MCP 版的差异也被刻意保持最小：不处理代理/CA 证书（pi 自己控制 HTTP 运行时）、不做每请求客户端上下文透传（走环境变量）。

小结

@upstash/context7-pi 用一条 pi install 命令为 pi coding agent 补齐了实时文档能力：两个工具（resolve-library-id、query-docs）负责"解析 ID → 拉取文档"的检索链路，context7-docs skill 负责让 agent 知道何时该用，/c7-docs 命令提供手动入口；认证上零配置即可试用，设置 CONTEXT7_API_KEY 获得更高配额。其"与 MCP 包逐字对齐"的实现策略也值得参考——同一套工具指令在不同客户端间保持一致，是降低 LLM 行为差异的务实做法。相关代码可进一步在 packages/pi 目录下查阅。