Context7 AI SDK 工具包版本演进实录：从 0.1.0 到 0.2.5 的工具改名、响应格式变更与提示词工程

本文以 @upstash/context7-tools-ai-sdk 的官方变更记录（CHANGELOG）为骨架，逐版本还原这个 Vercel AI SDK 工具包的完整演进路线：0.1.0 对齐 MCP 命名约定的工具改名、0.2.0 默认响应格式从 txt 切换到 json 的关键设计决策、AI SDK v6 与 Zod 4 的依赖升级，以及 0.2.3～0.2.5 连续三轮针对工具描述（tool description）的提示词优化。读完后，你既能掌握该工具包当前的 resolveLibraryId、queryDocs 工具与 Context7Agent 的接入方式，也能从源码层面理解每一条变更背后的实现依据。

这个包是什么

@upstash/context7-tools-ai-sdk 是 Context7 平台面向 Vercel AI SDK 的工具包，让 AI 应用能够按需检索最新、带版本号的库文档与代码示例，而不是依赖模型训练数据中可能过期的知识。该包提供两类集成方式：

• 独立工具：resolveLibraryId 与 queryDocs 两个 AI SDK tool，可加入你自己的 generateText / streamText 调用；
• 预制 Agent：Context7Agent，封装了"解析库 ID → 拉取文档 → 生成回答"的完整工作流。

从 包入口 的导出清单可以看到当前的完整 API 面：

// packages/tools-ai-sdk/src/index.ts
export { Context7Agent, type Context7AgentConfig } from "@agents";
export { resolveLibraryId, queryDocs, type Context7ToolsConfig } from "@tools";
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";

值得注意的是入口中的类型再导出（Library、Documentation、GetContextOptions）——这正是 0.1.0 变更记录里"Update type re-exports to match new SDK types"的直接产物，下文会展开。

版本演进：从 0.1.0 到 0.2.5

以下按时间正序完整继承 CHANGELOG 的全部条目，每条都结合当前仓库源码说明其落地形态。

0.1.0（Minor）：对齐 MCP 命名约定的全面改名

这是该包第一次以"工具语义重定义"为核心的发布，对应提交 b3cd38a：

• resolveLibrary → resolveLibraryId，并引入新的 query 参数（用于按相关性排序候选库，而不只是按名字匹配）；
• getLibraryDocs → queryDocs，topic 参数被 query 取代；
• 描述常量改名：RESOLVE_LIBRARY_DESCRIPTION → RESOLVE_LIBRARY_ID_DESCRIPTION，GET_LIBRARY_DOCS_DESCRIPTION → QUERY_DOCS_DESCRIPTION；
• 类型再导出对齐 SDK 新类型（Library、Documentation、GetContextOptions），与上游依赖 @upstash/context7-sdk@0.2.0 联动升级；
• 从 Context7ToolsConfig 和 Context7AgentConfig 中移除已废弃的 defaultMaxResults 选项——当前 配置接口 只剩 apiKey 一个可选字段：

// packages/tools-ai-sdk/src/tools/types.ts
export interface Context7ToolsConfig {
  /**
   * Context7 API key. If not provided, will use CONTEXT7_API_KEY environment variable.
   */
  apiKey?: string;
}

• 在工具描述中加入限流指引（rate limiting guidance）。这一指引至今仍然有效，可以在 提示词源码 中逐字看到：

IMPORTANT: Do not call this tool more than 3 times per question.
If you cannot find what you need after 3 calls, use the best result you have.

改名的意义在于让 AI SDK 侧的工具命名与 Context7 MCP Server 的工具命名保持一致（MCP 侧同样是 resolve-library-id / query-docs），这样同一套提示词工程可以在多个客户端（MCP、CLI、pi、AI SDK）之间复用。

0.2.0（Minor）：默认响应类型从 "txt" 切换为 "json"

提交 9412e62 带来了一个影响面很大的默认值变更：searchLibrary 和 getContext 两个 SDK 方法的默认响应类型从 "txt" 改为 "json"，同时 AI SDK 工具被改为显式传入 type: "txt" 以获得对 LLM 更友好的纯文本结果。这个"默认改结构、调用方显式覆盖"的分工在源码中有两处实证：

其一，SDK 侧的默认值——GetContextCommand 中：

// packages/sdk/src/commands/get-context/index.ts
const DEFAULT_TYPE = "json";
// ...
const responseType = options?.type ?? DEFAULT_TYPE;
queryParams.type = responseType;

其二，AI SDK 工具侧的显式覆盖——queryDocs 的 execute 实现：

execute: async ({ libraryId, query }: { libraryId: string; query: string }) => {
  const client = getClient();
  // 显式指定 txt，覆盖 SDK 0.3.0+ 的 json 默认值
  const documentation = await client.getContext(query, libraryId, { type: "txt" });
  ...
}

从源码结构看，这样设计的意图是：结构化（JSON）响应适合程序化处理与 RAG 管道，而纯文本（txt）响应 token 密度更高、更适合直接喂给 LLM 上下文；把选择权下放给各上层封装，各自显式声明自己的偏好。该版本同时联动升级了 @upstash/context7-sdk@0.3.0。

0.2.1（Patch）：兼容 AI SDK v6

提交 07a53dc 将 ai 的 peer dependency 提升为 >=6.0.0。当前 package.json 中的三个 peer 依赖约束完整记录了这个演进结果：

"peerDependencies": {
  "@upstash/context7-sdk": ">=0.3.1",
  "ai": ">=6.0.0",
  "zod": ">=4.0.0"
}

0.2.2（Patch）：Zod 从 3.x 升级到 4.x

提交 02148ff 跟随 AI SDK v6 的生态升级，把 zod 的 peer 依赖从 3.x 提升到 >=4.0.0（上表可见）。工具输入模式仍然使用 z.object + z.string().describe(...) 的标准写法，与 Zod 4 完全兼容。

0.2.3（Patch）：规范 libraryName 的输入格式

提交 8322879 改进了 resolveLibraryId 的提示词，要求调用方以正确格式提供 libraryName 查询。该改进固化在 resolve-library-id.ts 的参数模式 中：

inputSchema: z.object({
  query: z.string().describe(
    "What to look up in the library's documentation. This is used to rank library results by relevance ... "
  ),
  libraryName: z.string().describe(
    "Library name to search for and retrieve a Context7-compatible library ID. Use the official library name " +
    "with proper punctuation — e.g., 'Next.js' instead of 'nextjs', 'Customer.io' instead of 'customerio', " +
    "'Three.js' instead of 'threejs'."
  ),
}),

要点是把"库名必须带官方标点"（Next.js 而非 nextjs）直接写进 schema 的 describe 文案，让模型在生成工具调用参数时就带上正确的拼写，从而提升库检索的召回质量。

0.2.4（Patch）：每次查询只允许一个概念

提交 33229cb 澄清了 queryDocs 的 query 描述：一次查询只问一个概念；如果问题横跨多个独立主题，应拆成多次调用（除非问题本身就是关于这些概念如何交互），避免"稀释"出的浅层结果。这条规则同样写进了 query-docs.ts 的参数模式：

query: z.string().describe(
  "What to look up in the library's documentation, scoped to a single concept. ... " +
  "if the user's question spans multiple distinct concepts, make a separate call per concept instead of " +
  "combining them, unless the question is about how the concepts interact. " +
  "Good: 'How to set up authentication with JWT in Express.js' ... " +
  "Bad (too broad): 'routing and auth and caching in Next.js'. ..."
)

变更记录特别说明该规则被一致地应用到了 MCP server、CLI、pi 扩展与 AI SDK 工具四个表面——在当前仓库中，packages/mcp、packages/cli、packages/pi 与 packages/tools-ai-sdk 的对应提示词文本是互相镜像的。

0.2.5（Patch，当前版本）：强化"查文档"而非"完成任务"的定位

提交 1c081df 改进查询提示词，让 Agent 明确要求获取相关库文档，而不是试图把用户任务直接做完。这与 AGENT_PROMPT 中定义的多步工作流呼应：

Step 1: ALWAYS start by calling 'resolveLibraryId' with the library name ...
Step 2: Analyze the results ... select the BEST library ID based on:
   - Official sources ... Name similarity ... Source reputation ... Code snippet coverage ...
Step 3: Call 'queryDocs' with the selected library ID ...
Step 4: Provide a clear answer with code examples from the documentation

IMPORTANT:
- You MUST call resolveLibraryId first before calling queryDocs
- Do not call either tool more than 3 times per question
- Always cite which library ID you used

从 0.2.3 到 0.2.5 这三轮 Patch 的共同特征值得注意：没有改动任何执行逻辑，全部通过修改描述文本（提示词工程）来约束模型行为。对工具型包来说，tool description 就是模型可见的"接口契约"，这类变更的收益直接体现为工具调用的准确性。

源码级补充：两个工具的实际行为

错误处理与返回约定

两个工具的 execute 都采用"永不抛异常、以字符串形式返回"的约定，把错误信息转成模型可自我修正的提示。见 resolve-library-id.ts#L51-L64 与 query-docs.ts#L51-L65：

• 未命中时，resolveLibraryId 返回 No libraries found matching "${libraryName}". Try a different search term...；queryDocs 返回 No documentation found for library "${libraryId}"... Use 'resolveLibraryId' to get a valid ID.——后者还显式指回了第一步，形成闭环引导；
• 捕获异常后返回 Error ...: ${errorMessage}. Check your API key and try again.，同样以文本形式交还给模型处理。

认证方式

两个工具都接受可选的 Context7ToolsConfig（当前只有 apiKey 字段），未提供时回落到 CONTEXT7_API_KEY 环境变量。Context7Agent 把 apiKey 同时注入两个工具，并在未传入时保持空配置以走环境变量路径：

const context7Config = { apiKey };
super({
  ...agentSettings,
  model,
  instructions: instructions || AGENT_PROMPT,
  tools: {
    ...tools,                      // 允许并入自定义工具
    resolveLibraryId: resolveLibraryId(context7Config),
    queryDocs: queryDocs(context7Config),
  },
  stopWhen,                        // 默认 stepCountIs(5)
});

stopWhen 默认为 stepCountIs(5)，与提示词中"每个工具每题不超过 3 次调用"的约束共同构成步数与限流的双重保险。

测试覆盖

集成测试 验证了三层行为：工具结构断言（execute / inputSchema / description 齐备）、与 generateText 组合的真实工具调用（断言 toolCalls[0].toolName 为 resolveLibraryId / queryDocs）、以及 Context7Agent 的完整工作流（断言 result.steps 中依次出现两个工具调用）。在仓库中可用 pnpm test 运行该包的 vitest 用例。

使用方式：在当前版本上接入

以下示例基于 0.2.5 的当前 API（新工具名 resolveLibraryId / queryDocs）。需要留意的一点是：该包的 README 中的快速开始代码仍残留 0.1.0 改名前的旧名 resolveLibrary / getLibraryDocs，接入时请以 CHANGELOG 0.1.0 条目 与当前源码导出为准。

安装（npm/pnpm/yarn/bun 均可，见 官方入门文档）：

npm install @upstash/context7-tools-ai-sdk

配置 API Key（工具会自动读取该环境变量）：

CONTEXT7_API_KEY=ctx7sk-...

方式一：把工具挂进 generateText：

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: "Find React documentation about hooks",
  tools: {
    resolveLibraryId: resolveLibraryId(),
    queryDocs: queryDocs(),
  },
  stopWhen: stepCountIs(5),
});

方式二：显式传入 apiKey（覆盖环境变量）：

const tools = {
  resolveLibraryId: resolveLibraryId({ apiKey: "your-api-key" }),
  queryDocs: queryDocs({ apiKey: "your-api-key" }),
};

方式三：使用预制 Agent，自动执行"解析 → 检索 → 引用"工作流：

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 result = await agent.generate({
  prompt: "How do I use React Server Components?",
});

streamText 场景与 generateText 用法一致，把两个工具挂入 tools 字段即可。

小结

从 CHANGELOG 的七个版本条目可以读出这个包的一条清晰演进主线：0.1.0 完成命名与 SDK 类型对齐（架构层），0.2.0 确立"JSON 为默认、LLM 场景显式 txt"的响应格式分工（数据层），0.2.1–0.2.2 跟进 AI SDK v6 与 Zod 4 生态（依赖层），0.2.3–0.2.5 则通过纯提示词工程持续收紧工具描述以约束模型调用行为（提示词层）。四个层面各司其职，且每一层变更都能在 packages/tools-ai-sdk 的源码与 packages/sdk 的命令实现中找到对应证据，适合作为"工具型 SDK 如何做版本化提示词迭代"的参考案例。