upstash/context7-pi 版本演进解析pi 编程代理接入 Context7 文档检索的 0.1.0 至 0.1.2 变更全解【免费下载链接】context7Context7 Platform -- Up-to-date code documentation for LLMs and AI code editors项目地址: https://gitcode.com/gh_mirrors/co/context7本文基于 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的 mockExtensionAPI来验证注册行为断言最终恰好注册了query-docs与resolve-library-id两个工具并校验各自的参数 schema——resolve-library-id拥有querylibraryName两个参数query-docs拥有libraryIdquery两个参数。这组测试正是 0.1.0 注册两个工具这一变更承诺的可执行验证。自包含 API 客户端与逐字对齐的错误消息0.1.0 强调的自包含在 lib/api.ts 的头部注释中得到印证该文件改编自upstash/context7-mcppackages/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 控制台创建免费 key404库不存在建议更换库 ID401API key 无效并提示 key 应以ctx7sk前缀开头其他状态码返回通用的Request failed with status n消息。当fetchLibraryContext成功但响应为空时lib/api.ts 会返回一条引导性提示告诉 LLM 应改用resolve-library-id重新获取有效库 ID——这条消息同样是从 MCP 侧复制而来的。0.1.1commit 33229cbquery-docs 的单一概念查询约束0.1.1 的变更条目33229cb聚焦于query-docs工具query参数的描述文案。变更原文Clarify thequery-docsquery 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——同一 commit33229cb在 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.2commit 1c081df查询提示词改进让代理问文档而不是交任务0.1.2 是 CHANGELOG 中最新的 patch 版本commit1c081df变更原文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 librarys 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.0Minor首发注册resolve-library-id与query-docs工具、context7-docs技能、/c7-docs斜杠命令wire format 与工具描述逐字对齐upstash/context7-mcp自包含、无 Context7 运行时依赖0.1.1Patchquery-docs的 query 描述明确单次查询限定单一概念多主题按概念拆分查询与 MCP、CLI、AI SDK 工具同步0.1.2Patch改进查询提示词让代理请求相关库文档而非直接转发待完成的任务使用层面的关键约束与三个版本的变更直接相关安装pi install npm:upstash/context7-pi包内pi字段声明了extensions、skills、prompts三类资源的加载路径见 packages/pi/package.json鉴权零配置可用IP 限流档更高配额需export CONTEXT7_API_KEYctx7sk_...由 lib/api.ts 的authHeaders()读取该环境变量并附加到请求头调用纪律每个问题内resolve-library-id与query-docs各最多调用 3 次若 3 次后仍未命中使用已有最佳结果安全query 参数会被发送至 Context7 API禁止携带密钥、凭证、个人数据或专有代码一致性契约工具标题、描述、参数描述从upstash/context7-mcp逐字复制lib/prompts.ts 头部注释明确要求修改提示词时两侧同步更新以保证 pi 与 MCP 客户端向 LLM 传递完全相同的指令。延伸阅读扩展总览与用法示例packages/pi/README.md扩展注册入口packages/pi/extensions/context7.ts提示词与工具描述含 0.1.1 / 0.1.2 变更落点packages/pi/lib/prompts.tsAPI 客户端与错误消息packages/pi/lib/api.ts工具实现packages/pi/lib/tools/resolve-library-id.ts、packages/pi/lib/tools/query-docs.ts技能文档packages/pi/skills/context7-docs/SKILL.md斜杠命令模板packages/pi/prompts/c7-docs.md注册行为测试与真实 API 冒烟测试packages/pi/tests/extension.test.ts同批变更在其他客户端的记录packages/mcp/CHANGELOG.md、packages/cli/CHANGELOG.md、packages/tools-ai-sdk/CHANGELOG.md【免费下载链接】context7Context7 Platform -- Up-to-date code documentation for LLMs and AI code editors项目地址: https://gitcode.com/gh_mirrors/co/context7创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考