Klavis 仓库 Context7 包解析用 resolveLibraryId / queryDocs 工具与 Context7Agent 为 Vercel AI SDK 接入实时库文档【免费下载链接】klavisKlavis AI: MCP integration platforms that let AI agents use tools reliably at any scale项目地址: https://gitcode.com/GitHub_Trending/kl/klavis本文基于 Klavis 仓库内置的 Context7 项目中的 tools-ai-sdk 包系统讲解upstash/context7-tools-ai-sdk如何将 Context7 的库文档检索能力封装为 Vercel AI SDK 兼容的工具与智能体读完你可以掌握两个核心工具resolveLibraryId、queryDocs的输入参数与底层调用链、Context7Agent的多步工作流实现原理以及 API Key 配置、构建与测试的完整操作方式。1. 包定位与能力概览upstash/context7-tools-ai-sdk当前版本 0.2.1见 package.json提供 Vercel AI SDK 兼容的工具和智能体让 AI 应用通过 Context7 获取最新的、带版本信息的库文档。包的 README 将其典型用途概括为三类在generateText/streamText工作流中加入文档查找工具使用预配置的Context7Agent创建文档感知智能体构建可检索准确、版本化代码示例的 RAG 管线。从 入口文件 src/index.ts 看包对外导出四大类内容// Agents export { Context7Agent, type Context7AgentConfig } from agents; // Tools export { resolveLibraryId, queryDocs, type Context7ToolsConfig } from tools; // Prompts export { SYSTEM_PROMPT, AGENT_PROMPT, RESOLVE_LIBRARY_ID_DESCRIPTION, QUERY_DOCS_DESCRIPTION, } from prompts; // Re-export useful types from SDK export type { Context7Config, Library, Documentation, GetContextOptions, } from upstash/context7-sdk;需要注意一个命名细节README 正文中称两个工具为resolveLibrary与getLibraryDocs其 Quick Start 示例导入的也是这两个名字但从源码实际导出来看src/tools/index.ts真实的导出名是resolveLibraryId与queryDocs。源码示例、测试用例与 README 中Context7Agent的用法均一致采用resolveLibraryId/queryDocs因此实际集成时应以源码导出名为准。package.json的依赖约束说明了适用前提字段取值含义peerDependencies→upstash/context7-sdk0.3.0文档检索客户端为同级工作区包peerDependencies→ai6.0.0面向 AI SDK v6tool、generateText、ToolLoopAgent等 APIpeerDependencies→zod4.0.0工具输入 Schema 校验exports.与./agent双入口主入口含工具与提示词./agent子路径单独暴露智能体安装命令README Quick Startnpm install upstash/context7-tools-ai-sdk upstash/context7-sdk ai zodAPI Key 从 Context7 平台获取通过环境变量配置见第 5 节。2. 核心工具一resolveLibraryId —— 库名到 Context7 库 ID 的解析实现在 src/tools/resolve-library-id.ts。工厂函数resolveLibraryId(config: Context7ToolsConfig {})返回一个 AI SDKtool对象其执行逻辑如下通过getClient()创建Context7客户端未显式传apiKey时由 SDK 读取CONTEXT7_API_KEY环境变量调用client.searchLibrary(query, libraryName, { type: txt })执行库检索源码 L52无结果时返回提示文案No libraries found matching ...建议更换搜索词异常时不抛出而是返回Error searching for libraries: ...的错误说明文本提示检查 API Key——这种把错误变成可读字符串的设计保证工具调用不会中断 AI 的多步循环。其inputSchema定义了两个必填参数参数类型说明querystring用户的原始问题或任务用于按相关性对检索结果排序。Schema 描述中特别强调不得在 query 中包含 API 密钥、密码等敏感信息libraryNamestring要搜索的库名用于换取 Context7 兼容的库 ID工具描述文本RESOLVE_LIBRARY_ID_DESCRIPTION定义于 src/prompts/system.ts给模型划定了明确的调用纪律必须先调用它拿到合法库 ID 再调queryDocs除非用户直接提供了/org/project或/org/project/version格式的 ID并且每个问题最多调用 3 次。描述中还规定了结果选择标准名称相似度、描述相关性、代码片段覆盖量、来源信誉High/Medium 优先、Benchmark 分数。3. 核心工具二queryDocs —— 按库 ID 拉取版本化文档实现在 src/tools/query-docs.ts同样是工厂函数 tool()的结构getClient()创建客户端后调用client.getContext(query, libraryId, { type: txt })拉取文档源码 L54返回空时给出针对性诊断No documentation found for library ...并提示可能用了非法 ID建议回退到resolveLibraryId重新解析异常时返回Error fetching documentation for ...及原始错误信息。inputSchema参数参数类型说明libraryIdstringContext7 库 ID格式为/org/project或/org/project/version例如/vercel/next.js、/supabase/supabase、/vercel/next.js/v14.3.0-canary.87Schema 描述中给出的示例querystring具体化后的问题要求Good: How to set up authentication with JWT in Express.jsBad: auth即拒绝过于宽泛的查询同样禁止携带敏感信息两个工具共享同一个配置接口src/tools/types.tsexport interface Context7ToolsConfig { /** * Context7 API key. If not provided, will use CONTEXT7_API_KEY environment variable. */ apiKey?: string; }即显式配置与环境变量二选一显式传参优先。4. 两种使用方式裸工具组合与 Context7Agent4.1 用generateText手动编排多步工具调用这是 README Quick Start 给出的模式导入名以源码导出resolveLibraryId/queryDocs为准import { resolveLibraryId, queryDocs } from upstash/context7-tools-ai-sdk; import { generateText, stepCountIs } from ai; import { openai } from ai-sdk/openai; const { text } await generateText({ model: openai(gpt-4o), prompt: How do I use React Server Components?, tools: { resolveLibraryId: resolveLibraryId(), queryDocs: queryDocs(), }, stopWhen: stepCountIs(5), // 限制最多 5 个工具调用步骤 }); console.log(text);要点stopWhen: stepCountIs(5)是防止模型在检索—查询文档之间无限循环的熔断器两个工具对象不带参数调用API Key 自动取自环境变量。4.2 用预配置智能体Context7Agent托管整个工作流Context7Agent实现见 src/agents/context7.ts。它继承 AI SDK 的ToolLoopAgent构造函数做了三件事export class Context7Agent extends ToolLoopAgentnever, ToolSet { constructor(config: Context7AgentConfig) { const { model, stopWhen stepCountIs(5), // 默认最多 5 步 instructions, // 默认使用 AGENT_PROMPT apiKey, tools, // 允许注入额外自定义工具 ...agentSettings } config; super({ ...agentSettings, model, instructions: instructions || AGENT_PROMPT, tools: { ...tools, resolveLibraryId: resolveLibraryId({ apiKey }), queryDocs: queryDocs({ apiKey }), }, stopWhen, }); } }从源码结构看该类的行为约定为默认 5 步熔断不传stopWhen时回落到stepCountIs(5)内置双工具且可叠加resolveLibraryId/queryDocs始终存在用户通过tools传入的自定义工具会被合并而非覆盖提示词可替换instructions缺省为第 6 节讲的AGENT_PROMPTAPI Key 透传apiKey通过Context7ToolsConfig同时注入两个工具。用法README 示例import { Context7Agent } from upstash/context7-tools-ai-sdk; import { anthropic } from ai-sdk/anthropic; const agent new Context7Agent({ model: anthropic(claude-sonnet-4-20250514), }); const { text } await agent.generate({ prompt: How do I set up routing in Next.js?, }); console.log(text);也可以显式传入 Key、自定义停止条件new Context7Agent({ model, apiKey: your-context7-api-key, stopWhen: stepCountIs(3) })Context7AgentConfig继承ToolLoopAgentSettings因此模型、instructions、tools 等标准智能体设置均可透传。5. 配置API Key 的两种提供方式包内所有涉及鉴权的对象两个工具工厂与Context7Agent都接受可选的apiKey缺省时由底层 SDK 读取环境变量CONTEXT7_API_KEYctx7sk-...配置后resolveLibraryId()即可无参使用。这一显式配置优先、环境变量兜底的约定在 src/tools/resolve-library-id.ts 的文件头注释中有明确声明src/agents/context7.ts 的Context7AgentConfig.apiKey注释与之完全一致。6. 提示词体系多步工作流如何被约束system.ts 导出了四段提示词是理解 Agent 行为的钥匙AGENT_PROMPTL20-L47Context7Agent的默认指令规定了强制四步工作流——① 必须先用resolveLibraryId解析库名并审阅全部结果② 按官方来源、名称相似度、描述相关性、来源信誉、代码片段覆盖、Benchmark 分数六个维度选出最优库 ID③ 用精确 ID 与用户原始问题调用queryDocs④ 基于文档给出带代码示例的答案并引用所用库 ID。同时硬性约束每个问题两个工具各不超过 3 次调用SYSTEM_PROMPT轻量版文档助手指令要求检索、给出代码示例并引用来源库 ID适合自组装场景RESOLVE_LIBRARY_ID_DESCRIPTION/QUERY_DOCS_DESCRIPTION直接作为两个tool()的description字段把先解析后查询限次调用拒绝歧义查询需澄清等纪律写进了工具协议本身使模型即便不使用AGENT_PROMPT也能获得一致行为。这种工具描述即协议的设计是裸generateText用法与 Agent 用法行为趋同的原因。7. 测试验证从结构断言到真实模型调用链包的 src/index.test.ts 使用 vitest基于 Amazon Bedrock 上的 Claude 3 HaikucreateAmazonBedrock需AWS_REGION、AWS_BEARER_TOKEN_BEDROCK环境变量覆盖四个层面工具结构L20-L53断言resolveLibraryId()/queryDocs()返回对象具有execute、inputSchema、description且可接受{ apiKey: ctx7sk-test-key }自定义配置generateText工具编排L55-L111用toolChoice强制调用单个工具验证调用与结果产出并有一例先resolveLibraryId再queryDocs的多步组合测试stopWhen: stepCountIs(5)断言两个工具名都出现在步骤的toolCalls中Context7AgentL113-L207验证generate/stream方法存在接受自定义stopWhen、instructions、apiKey与额外自定义工具端到端用例断言result.steps非空且工具调用链同时包含resolveLibraryId与queryDocs印证了第 6 节工作流确实被执行提示词导出L209-L227断言SYSTEM_PROMPT、AGENT_PROMPT、RESOLVE_LIBRARY_ID_DESCRIPTION均为非空字符串且含预期关键词。其中真实调用用例设置了 30~60 秒超时说明它们会真实访问模型服务与 Context7 API运行前需要备好对应凭证。8. 构建与验证包使用 tsup 构建双格式产物dist/index.js/dist/index.cjs见 package.json 的main/module/exports测试脚本为vitest run。在包目录下可执行pnpm test # 运行 vitest 测试需要 AWS_REGION、AWS_BEARER_TOKEN_BEDROCK、CONTEXT7_API_KEY pnpm build # tsup 构建仓库根目录还提供pnpm-workspace.yaml组织工作区mcp_servers/context7/README.md 与 mcp_servers/context7/docs/ 下有 Context7 主项目的完整文档可作为理解检索 APIsearchLibrary/getContext语义的进一步入口。9. 小结upstash/context7-tools-ai-sdk的价值在于把找到正确库 → 拉取版本化文档 → 基于文档作答这一 RAG 前置链路标准化为两个带严格调用纪律的工具和一个开箱即用的ToolLoopAgent子类resolveLibraryId负责库名到/org/project[/version]ID 的解析queryDocs负责按主题检索文档两者错误处理都回传可读文本而非抛异常配合stepCountIs熔断形成可靠的多步文档问答工作流。对已在 Klavis 生态中使用 AI SDK 构建 MCP 智能体的开发者而言这是接入实时库文档最直接的一块拼图。【免费下载链接】klavisKlavis AI: MCP integration platforms that let AI agents use tools reliably at any scale项目地址: https://gitcode.com/GitHub_Trending/kl/klavis创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考