Context7 Power 实战指南用 resolve-library-id 与 query-docs 为 LLM 精准获取最新库文档【免费下载链接】context7Context7 Platform -- Up-to-date code documentation for LLMs and AI code editors项目地址: https://gitcode.com/gh_mirrors/co/context7本篇技术指南围绕仓库内 POWER.md 展开系统讲解 Context7 Power 的定位、适用场景与四步工作流并深入其底层实现MCP 配置、AI SDK 工具与 SDK 客户端剖析resolve-library-id与query-docs两个核心工具的输入输出契约。读完本文你将掌握如何在任意 MCP 客户端或 AI SDK 应用中让编码 Agent 先解析库 ID、再按单一概念分次拉取文档最终生成基于最新版本、附带真实代码示例的准确回答。Context7 Power 是什么Context7 Power 是 Context7 平台为编码类 Agent 提供的一项「文档增强能力」documentation power。它的核心定位非常聚焦为库Libraries、框架Frameworks、SDK、API 与开发者工具检索最新文档用这些实时文档来锚定ground代码生成过程避免大模型仅凭训练数据中的过时信息作答。该 Power 的元信息定义在 POWER.md 的文件头 frontmatter 中它同时是声明文件元数据与检索入口字段值含义namecontext7Power 的内部名称displayNameContext7对外展示名称description查找库、框架、SDK 与开发者工具的最新文档、API 参考与代码示例供 Agent 判断何时调用keywordscontext7、library docs、framework docs、sdk docs 等供搜索引擎/Agent 检索定位authorContext7作者信息配套的 mcp.json 定义了该 Power 所依赖的 MCP 服务器连接方式指向远程托管端点{ mcpServers: { context7: { url: https://mcp.context7.com/mcp } } }也就是说这个 Power 不需要本地启动进程而是直接通过 Streamable HTTP 方式连接 Context7 官方托管的 MCP 服务开箱即用。何时使用、何时不使用POWER.md 明确给出了触发条件与禁用场景这既是给 Agent 的行为准则也是开发者集成时的决策依据。应当使用 Context7 Power 的场景用户询问某个库、框架、SDK、API、CLI 工具或云服务的安装或配置问题用户要求编写涉及特定库或框架的代码用户需要API 参考或当前文档用户点名提及某个框架、SDK 或开发者工具用户需要版本迁移、库相关的调试或 CLI 用法帮助。不应使用 Context7 Power 的场景直接交给常规编程能力处理重构refactoring从零编写脚本调试业务逻辑business logic代码评审code review通用编程概念。这一边界清单极其关键Context7 的定位是文档检索增强而不是替代通用代码推理。只有把它的使用范围收敛到查库文档才能避免每次对话都产生不必要的工具调用开销。四步工作流从提问到带文档依据的回答POWER.md 给出了标准的四步工作流这也是Context7Agent见 agents/context7.ts默认遵循的执行协议。系统提示词 system.ts 中的AGENT_PROMPT将同一流程写成了对 Agent 的硬性约束必须先调用resolveLibraryId才能调用queryDocs且每个问题对两个工具合计调用不超过 3 次。Step 1解析库 IDresolve-library-id一切检索的起点是拿到合法的 Context7 库 ID。调用resolve-library-id时传入两个参数参数类型说明libraryNamestring从用户问题中提取的库名称要求使用官方名称与正确标点例如用Next.js而非nextjs、用Three.js而非threejsquerystring要在该库文档中查找的内容用于提升结果的相关性排序relevance ranking唯一可以跳过此步骤的情形是用户直接给出了组织/项目/org/project或组织/项目/版本/org/project/version格式的精确库 ID此时可以跳过解析、直接进入 Step 3。从源码看这一步在 resolve-library-id.ts 中的实现是用 zod 定义query与libraryName两个必填字段后执行client.searchLibrary(query, libraryName, { type: txt })把 SDK 的搜索能力包装成 AI SDK 工具搜索无结果时返回提示No libraries found matching ...失败时提示检查 API key。SDK 侧的具体实现在 client.ts 中searchLibrary(query, libraryName, options)会构造SearchLibraryCommand并经由带重试的 HTTP 客户端执行。Step 2选择最佳匹配拿到resolve-library-id的返回结果后需要从候选库中选出最合适的库 ID选择依据按优先级排列名称匹配度与用户所问库的精确或最接近匹配benchmark 分数更高的分数代表更好的文档质量源码注释中说明 100 为满分见 system.ts版本偏好如果用户提到了版本如 React 19优先选择版本专属 ID官方来源优先存在多个匹配时优先官方/主包而非社区 fork例如 React 应选/reactjs/react.devNext.js 应选/vercel/next.js兜底策略如果结果看起来不对尝试替代名称或改写query后重试若连续 3 次仍未找到理想结果用已有最佳结果继续这也是每个问题最多调用 3 次限制的由来。Step 3拉取文档query-docs拿到库 ID 后调用query-docs获取目标文档参数类型说明libraryIdstring上一步选中的 Context7 库 ID例如/vercel/next.js也支持带版本后缀的 ID如/vercel/next.js/v14.3.0-canary.87querystring要在库文档中查找的内容限定为单一概念且使用多于一个单词的描述这一步有两个重要的调用纪律单概念原则如果用户的问题跨越多个独立概念例如同时涉及 routing、auth、caching应当对每个概念用同一个libraryId分别发起一次query-docs调用而不是合并成一个大 query——合并查询会稀释相关性排序导致每个主题都只得到浅层结果例外情况如果问题本身就是这些概念如何交互例如Next.js 中 auth 与 middleware 如何配合则合并查询是合理的。源码实现见 query-docs.tsqueryDocs(config)同样用 zod 定义libraryId与query两个必填字段执行时调用client.getContext(query, libraryId, { type: txt })若返回为空会提示可能是无效库 ID请用 resolveLibraryId 获取合法 ID。参数描述中还明确要求不要在 query 中包含 API 密钥、密码、凭证等敏感或机密信息。Step 4使用文档生成回答最后一步是把取回的文档真正用起来用当前、准确的信息回答用户问题引用文档中相关的代码示例在相关时注明库版本citing the library version。这套取文档 → 引用示例 → 标注版本的输出规范使得生成结果既可追溯来源又贴近最新 API正是 Context7 Power 与普通 Web 搜索的本质区别。最佳实践清单POWER.md 的最佳实践小节可归纳为如下可执行规则建议在编写 Agent 指令或评估工具调用质量时逐条对照描述查询目标但每个 query 只限一个概念多主题问题拆分为多个query-docs调用除非问题关于概念间的交互版本感知用户提及版本Next.js 15React 19时优先使用解析阶段给出的版本专属库 ID官方优先多匹配时优先官方/主包聚焦文档类任务适用于 API 语法、配置、安装步骤、版本迁移、库专属调试和 CLI 工具用法不要以为自己会就跳过即使用户问题看似简单、模型自认为知道答案也应使用 Context7——因为训练数据可能落后于最新变更对于库文档优先使用 Context7 而非 Web 搜索红线不要用于重构、从零写脚本、调试业务逻辑、代码评审或通用编程概念。底层原理从 Power 到 SDK 的完整调用链从仓库源码可以完整还原该 Power 的技术底座整个链路分为三层第一层MCP 连接层。mcp.json 声明远程端点https://mcp.context7.com/mcp供支持 MCP 的客户端Cursor、Claude Code、VS Code 等直接挂载本地化替代方案是通过npx -y upstash/context7-mcp启动 stdio 服务详见 packages/mcp/README.md。第二层AI SDK 工具层。tools-ai-sdk 包把两个工具以标准 AI SDKtool()形式暴露并内置了带完整工作流约束的Context7Agentagents/context7.ts它继承ToolLoopAgent默认stopWhen: stepCountIs(5)最多 5 轮工具循环并把resolveLibraryId、queryDocs与用户自定义tools合并注入。两个工具都支持传apiKey不传时回退到CONTEXT7_API_KEY环境变量。第三层SDK 客户端层。packages/sdk/src/client.ts 中的Context7类是最终执行者几个值得注意的实现细节默认 API 端点为https://context7.com/api认证方式为Authorization: Bearer apiKeyAPI key 以ctx7sk前缀开头未提供时直接抛出错误前缀不符时打印警告HTTP 客户端内置 5 次重试与指数退避Math.exp(retryCount) * 50毫秒并设置cache: no-store确保每次拿到的都是新鲜文档。这也解释了 POWER.md 中即使你知道答案也应使用 Context7的工程动机SDK 层刻意关闭了缓存并启用重试就是为了保证 Agent 拿到的始终是当前版本的文档而不是任何缓存过的旧内容。工具输入输出契约速查把两把工具的契约合并成一张速查表方便在集成或调试时快速对照工具输入输出行为失败兜底resolve-library-idlibraryName官方名称、query查询内容返回匹配库列表含名称匹配、benchmark 分数、来源声誉、代码片段覆盖等无匹配时提示换词异常时提示检查 API keyquery-docslibraryId如/vercel/next.js、query单一概念返回该库当前文档与代码示例纯文本格式空结果提示库 ID 无效异常返回错误信息需要注意system.ts 中的AGENT_PROMPT强调解析结果的选择应综合官方来源如 React 对应/reactjs/react.dev、名称相似度、描述相关性、来源声誉High/Medium 更优、代码片段覆盖率越高越好与benchmark 分数越高越好这与 POWER.md Step 2 的选择标准完全一致两处文档相互印证。许可与支持该 Power 集成基于MIT 许可证的 Context7 MCP Server对应仓库 packages/mcp/LICENSE并随附隐私政策说明与官方支持联系方式。若需要更高的速率限制或访问私有仓库可以在 Context7 控制台创建 API key 后在 MCP 配置中通过Authorization: Bearer YOUR_API_KEY请求头或本地启动时的--api-key参数启用认证模式。【免费下载链接】context7Context7 Platform -- Up-to-date code documentation for LLMs and AI code editors项目地址: https://gitcode.com/gh_mirrors/co/context7创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考