@upstash/context7-pi 版本演进解析：pi 编程代理接入 Context7 文档检索的 0.1.0 至 0.1.2 变更全解

2026-09-04 17:15:35作者：幸俭卉

本文基于 Context7 官方 pi 编程代理扩展包的变更记录（packages/pi/CHANGELOG.md），逐一解读 @upstash/context7-pi 从 0.1.0 首发到 0.1.2 的全部三次发布：首发版本注册了 resolve-library-id 与 query-docs 两个 LLM 可调用工具、context7-docs 技能与 /c7-docs 斜杠命令，而 0.1.1 与 0.1.2 则分别围绕"单次查询限定单一概念"和"查询提示词改进"对工具的提示词与调用行为做了打磨。读完后你将了解每个版本变更的实际含义、对应的源码实现位置，以及这些变更如何与 MCP、CLI、AI SDK 等其他 Context7 客户端保持一致。

0.1.0：首发版本——为 pi 编程代理补齐实时文档能力

0.1.0 是 @upstash/context7-pi 的初始发布（变更条目 f91b40c），其定位为 pi 编程代理（pi coding agent）的官方 Context7 扩展。根据 packages/pi/CHANGELOG.md 的 0.1.0 条目，该版本一次性交付了四块能力：

注册两个工具：resolve-library-id（把包名/产品名解析为 Context7 库 ID）和 query-docs（按库 ID 拉取文档与代码示例）；
附带 context7-docs 技能：教会代理在用户询问任何库、框架、SDK、API、CLI 工具或云服务时主动调用上述工具；
暴露 /c7-docs 斜杠命令：支持手动一键完成"解析库 ID + 查询文档"的完整流程；
与 MCP 客户端完全对齐：wire format（线协议）、错误消息、工具描述均逐字（verbatim）从 @upstash/context7-mcp 复制，保证 pi 与 MCP 客户端给 LLM 的指令和输出完全一致；
自包含设计：不依赖 Context7 运行时（无 Context7 runtime dependencies），开箱即用即受 IP 限流约束，设置 CONTEXT7_API_KEY 可切换到更高配额档位。

安装方式只有一条命令：

pi install npm:@upstash/context7-pi

扩展注册入口：两个工具的挂载点

从源码结构看，扩展的注册逻辑极为精简。extensions/context7.ts 中的 context7 默认导出函数接收 pi 的 ExtensionAPI 实例，只做两件事：

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

测试用例 tests/extension.test.ts 通过一个只实现了 registerTool 的 mock ExtensionAPI 来验证注册行为：断言最终恰好注册了 query-docs 与 resolve-library-id 两个工具，并校验各自的参数 schema——resolve-library-id 拥有 query + libraryName 两个参数，query-docs 拥有 libraryId + query 两个参数。这组测试正是 0.1.0 "注册两个工具"这一变更承诺的可执行验证。

自包含 API 客户端与逐字对齐的错误消息

0.1.0 强调的"自包含"在 lib/api.ts 的头部注释中得到印证：该文件"改编自 @upstash/context7-mcp（packages/mcp/src/lib/api.ts），为 pi 做了最小化裁剪"——去掉了 MCP 版本中的代理/CA 证书处理（pi 自行控制 HTTP 运行时）和逐请求 client context，但刻意保持 wire format 与错误消息与 MCP 版本对齐。

具体实现上，api.ts 封装了两个 HTTP 端点：

searchLibraries(query, libraryName) 请求 https://context7.com/api/v2/libs/search，供 resolve-library-id 使用，返回匹配库列表；
fetchLibraryContext(query, libraryId) 请求 https://context7.com/api/v2/context，供 query-docs 使用，返回文档文本。

鉴权逻辑体现在 authHeaders() 中：若环境变量 CONTEXT7_API_KEY 存在，则在请求头附加 Authorization: Bearer <key>；否则不带鉴权头——这正是 CHANGELOG 中"开箱即用受 IP 限流、设置 API key 可升级配额"这句话的实现依据。

错误处理同样逐字对齐 MCP 版本，parseErrorResponse 按状态码返回 LLM 可直接消费的提示：

429：限流或配额超限；有 key 时提示升级套餐，无 key 时提示到 Context7 控制台创建免费 key；
404：库不存在，建议更换库 ID；
401：API key 无效，并提示 key 应以 ctx7sk 前缀开头；
其他状态码：返回通用的 Request failed with status <n> 消息。

当 fetchLibraryContext 成功但响应为空时，lib/api.ts 会返回一条引导性提示，告诉 LLM 应改用 resolve-library-id 重新获取有效库 ID——这条消息同样是从 MCP 侧复制而来的。

0.1.1（commit 33229cb）：query-docs 的"单一概念"查询约束

0.1.1 的变更（条目 33229cb）聚焦于 query-docs 工具 query 参数的描述文案。变更原文：

Clarify the query-docs query description so it asks for a single concept per query. When a question spans multiple distinct topics, callers are now told to make a separate query per concept instead of combining them (unless the question is about how the concepts interact), which avoids diluted, shallow results. Applied consistently across the MCP server, CLI, pi, and AI SDK tools.

这条变更的核心动机是结果质量：当用户一个问题横跨多个互不相关的主题时，把多个主题塞进同一个 query 会稀释 Context7 服务端的检索排序信号，导致每个主题都只能拿到浅层结果。因此新文案明确要求：每个 query 只限定一个概念；跨多主题时应按概念拆分、对每个概念各发一次查询，唯一例外是问题本身在询问概念之间的交互方式。

在 lib/prompts.ts 中，这条约束固化在 QUERY_DOCS_QUERY_DESCRIPTION 常量里，并被 lib/tools/query-docs.ts 作为 TypeBox 参数 schema 的 description 注入工具定义。完整文案给出了正反示例：

好："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"。

文案同时保留了安全约束：query 会被发送到 Context7 API 处理，因此不得包含 API key、密码、凭证、个人数据或专有代码。

值得注意的是这条变更末尾的 "Applied consistently across the MCP server, CLI, pi, and AI SDK tools"——同一 commit 33229cb 在 packages/mcp/CHANGELOG.md、packages/cli/CHANGELOG.md 与 packages/tools-ai-sdk/CHANGELOG.md 中也有对应条目。可以确认，"单一概念"约束是跨四个客户端统一落地的：在 pi 侧它是 lib/prompts.ts 中的 QUERY_DOCS_QUERY_DESCRIPTION；在技能文档 skills/context7-docs/SKILL.md 的工作流第 2 步中也同步写入了相同的措辞；而 MCP 服务器侧则在 packages/mcp/src/index.ts 中以相同的描述文本暴露同名参数。这正是 0.1.0 确立的"pi 与 MCP 客户端给 LLM 相同指令"原则在后续版本中的延续。

0.1.2（commit 1c081df）：查询提示词改进，让代理"问文档"而不是"交任务"

0.1.2 是 CHANGELOG 中最新的 patch 版本（commit 1c081df），变更原文：

Improve query prompts so agents request relevant library documentation instead of passing the task to complete.

这条变更针对的是一个常见的代理行为偏差：早期版本的提示词下，LLM 有时会把"完成某项开发任务"直接作为 query 传给文档检索接口，而不是先提炼出"应该查阅哪部分库文档"。改进后的提示词让代理的行为从"转发任务"收敛为"检索相关文档"。

从源码结构看，改进落在 lib/prompts.ts 中 resolve-library-id 工具的 query 参数描述（RESOLVE_LIBRARY_ID_QUERY_DESCRIPTION）上：当前文案要求 query 表达"要在该库文档中查阅什么内容（What to look up in the library's documentation）"，并说明它用于按用户意图的相关性对检索结果排序。同时，skills/context7-docs/SKILL.md 的工作流第 1 步也要求代理"用库名 + 要查阅的内容"调用 resolve-library-id。配合 0.1.1 引入的单一概念约束，pi 扩展的文档查询行为在 0.1.2 版本后形成了完整的调用规范：先解析、再按单一概念查询、每问题最多 3 次调用。

其中"每个问题对任一工具最多调用 3 次"的上限直接写死在工具描述中（lib/prompts.ts 的 RESOLVE_LIBRARY_ID_DESCRIPTION 结尾与 QUERY_DOCS_DESCRIPTION 中均有 "Do not call ... more than 3 times per question"），技能文档的 Constraints 一节也重复了这条约束，双通道保证 LLM 无论走自动工具调用还是技能引导都受同一上限约束。

版本能力对照与使用约束汇总

综合 packages/pi/CHANGELOG.md 与当前 packages/pi/package.json（版本号为 0.1.2，与 CHANGELOG 最新条目一致），三次发布的能力演进可归纳为：

版本	变更	内容
0.1.0	Minor	首发：注册 `resolve-library-id` 与 `query-docs` 工具、`context7-docs` 技能、`/c7-docs` 斜杠命令；wire format 与工具描述逐字对齐 `@upstash/context7-mcp`；自包含、无 Context7 运行时依赖
0.1.1	Patch	`query-docs` 的 query 描述明确"单次查询限定单一概念"，多主题按概念拆分查询；与 MCP、CLI、AI SDK 工具同步
0.1.2	Patch	改进查询提示词，让代理请求相关库文档而非直接转发待完成的任务

使用层面的关键约束（与三个版本的变更直接相关）：

安装：pi install npm:@upstash/context7-pi，包内 pi 字段声明了 extensions、skills、prompts 三类资源的加载路径（见 packages/pi/package.json）；
鉴权：零配置可用（IP 限流档）；更高配额需 export CONTEXT7_API_KEY=ctx7sk_...，由 lib/api.ts 的 authHeaders() 读取该环境变量并附加到请求头；
调用纪律：每个问题内 resolve-library-id 与 query-docs 各最多调用 3 次；若 3 次后仍未命中，使用已有最佳结果；
安全：query 参数会被发送至 Context7 API，禁止携带密钥、凭证、个人数据或专有代码；
一致性契约：工具标题、描述、参数描述从 @upstash/context7-mcp 逐字复制，lib/prompts.ts 头部注释明确要求修改提示词时两侧同步更新，以保证 pi 与 MCP 客户端向 LLM 传递完全相同的指令。