Context7 TypeScript SDK 版本演进解析从 API 简化到默认响应类型变更0.1.0 至 0.3.0【免费下载链接】klavisKlavis AI: MCP integration platforms that let AI agents use tools reliably at any scale项目地址: https://gitcode.com/GitHub_Trending/kl/klavis本文基于 Context7 TypeScript SDK 的 CHANGELOG 完整梳理upstash/context7-sdk从 0.1.0 到 0.3.0 的三次版本演进初始发布的 REST 客户端能力、0.2.0 的 API 简化重构以及 0.3.0 将searchLibrary与getContext的默认响应类型从txt切换为json这一关键行为变更。读完本文你将掌握该 SDK 当前仓库内版本 0.3.0的完整 API 面——客户端初始化、库检索、文档上下文获取、json/txt双响应模式——并能从 源码 层面理解每次变更背后的实现细节、HTTP 层重试机制与测试验证方式。一、SDK 定位与版本演进总览upstash/context7-sdk是一个基于 HTTP/REST 的 TypeScript 客户端用于调用 Context7 API。Context7 解决的问题是LLM 依赖过时或泛化的训练数据容易产生基于陈旧版本的代码示例和虚构 APIContext7 从源头提供最新的、版本相关的文档与代码示例该 SDK 可用于构建携带准确文档上下文的 AI Agent、可靠文档 RAG 流水线、以及由真实 API 参考驱动的代码生成工具参见 README。CHANGELOG 记录的三个版本与各自核心变更如下版本核心变更关联提交0.1.0初始发布HTTP/REST 客户端、searchLibrary()、getDocs()、环境变量 API key 支持5e11d350.2.0简化 APIgetDocs()替换为getContext(query, libraryId, options)searchLibrary(query, libraryName)双参数响应类型统一为Library/Documentation移除 pagination、mode、topic、limit 选项GetContextOptions仅保留type: json \| txtb3cd38a0.3.0searchLibrary与getContext的默认响应类型从txt改为jsonAI SDK 工具改为显式传type: txt以获取 LLM 友好的文本响应9412e62仓库中 package.json 的版本号为0.3.0即当前代码对应的正是 CHANGELOG 的最新版本构建使用tsup测试使用vitest runpnpm test另有typecheck与lint脚本。二、0.1.0初始发布的 REST 客户端0.1.0 确立了 SDK 的基本形态一个 HTTP/REST 客户端暴露searchLibrary()在 Context7 数据库中检索库和getDocs()带过滤选项地获取文档两个方法并支持通过环境变量配置 API key。从当前源码的构造函数可以确认这一初始能力仍然完整保留client.tsconst DEFAULT_BASE_URL https://context7.com/api; const API_KEY_PREFIX ctx7sk; export class Context7 { constructor(config: Context7Config {}) { const apiKey config.apiKey || process.env.CONTEXT7_API_KEY; if (!apiKey) { throw new Context7Error( API key is required. Pass it in the config or set CONTEXT7_API_KEY environment variable. ); } if (!apiKey.startsWith(API_KEY_PREFIX)) { console.warn(API key should start with ${API_KEY_PREFIX}); } this.httpClient new HttpClient({ baseUrl: DEFAULT_BASE_URL, headers: { Authorization: Bearer ${apiKey} }, retry: { retries: 5, backoff: (retryCount) Math.exp(retryCount) * 50 }, cache: no-store, }); } }初始化要点API key 解析优先级构造参数config.apiKey优先回退到环境变量CONTEXT7_API_KEY两者皆缺时抛出Context7Error错误类定义见 error/index.ts。前缀校验合法的 key 以ctx7sk开头不满足时仅输出console.warn警告而非抛错。底层 HTTP 配置Authorization: Bearer头、5 次重试、指数退避Math.exp(retryCount) * 50毫秒、no-store缓存策略。README 给出的环境变量用法与此一致CONTEXT7_API_KEYctx7sk-...const client new Context7();对应的回归测试位于 client.test.ts验证从环境变量创建客户端、缺失 key 时new Context7()抛出API key is required、以及配置中的 key 优先于环境变量。三、0.2.0API 简化重构0.2.0 是一次接口重塑CHANGELOG 逐条列出了五处变化当前源码可逐条印证3.1getDocs()替换为getContext(query, libraryId, options)新签名引入了query参数以支持基于相关性的文档检索relevance-based retrieval取代了原先按库取文档的粗粒度方式async getContext(query: string, libraryId: string, options?: GetContextOptions)query是用户的问题或任务libraryId是 Context7 库 ID如/facebook/react。命令层实现见 get-context/index.tsquery、libraryId、type三个键组装为 GET 查询参数请求固定端点v2/context。3.2searchLibrary(query, libraryName)双参数搜索同时接收自然语言query用于相关性排序和libraryName如react对应端点v2/libs/searchsearch-library/index.ts。command.ts 中_ENDPOINTS数组恰好只包含这两个端点[v2/libs/search, v2/context]说明 0.2.0 之后的 API 面收敛到了这两个操作。3.3 响应类型统一为Library与Documentation原先的SearchResult、CodeDocsResponse、InfoDocsResponse等分散类型被 commands/types.ts 中的两个接口取代export interface Library { id: string; // Context7 library ID (e.g., /facebook/react) name: string; // 显示名称 description: string; // 库描述 totalSnippets: number; trustScore: number; // 来源信誉分0-10 benchmarkScore: number; // 质量指标分0-100 versions?: string[]; } export interface Documentation { title: string; // 文档片段标题 content: string; // 内容可能含 Markdown 代码块 source: string; // 来源 URL 或标识 }trustScore在文本格式化中会被映射为可读标签见 utils/format.ts7为 High、4为 Medium否则 Low这为 LLM 选择可信度更高的文档来源提供了结构化依据。3.4 移除 pagination、mode、topic、limit 选项上下文检索不再接受分页与主题过滤参数GetContextOptions被简化为只含一个字段export interface GetContextOptions { type?: json | txt; // default 见 0.3.0 章节 } export interface SearchLibraryOptions { type?: json | txt; }这是客户端尽量薄、检索策略交给服务端的设计取舍SDK 只负责传query/libraryName/type相关性排序、片段选取由 Context7 API 完成。四、0.3.0默认响应类型从 txt 变为 json这是当前仓库版本对应的最后一次行为变更也是使用旧版 SDK 升级时最容易踩坑的点两个方法的默认返回都变成了结构化数组而非格式化文本。从源码看两条命令内部都声明了const DEFAULT_TYPE jsonget-context/index.ts 与 search-library/index.ts并在未显式指定options.type时采用它。客户端通过 TypeScript 函数重载保证类型推断正确client.ts// 显式 { type: json } → PromiseDocumentation[] // 显式 { type: txt } → Promisestring // 不传 options → PromiseDocumentation[]默认 json async getContext( query: string, libraryId: string, options?: GetContextOptions ): PromiseDocumentation[] | string;AI SDK 工具的配套适配0.3.0 的另一半变更是AI SDK 工具显式使用type: txt。仓库中的 upstash/context7-tools-ai-sdk 印证了这一点——queryDocs工具在调用 SDK 时硬编码了文本模式因为 LLM 消费的是拼接进 prompt 的字符串而非 JSON 数组const documentation await client.getContext(query, libraryId, { type: txt });这揭示了一个实践模式程序化下游RAG 索引、结构化处理用默认的json拿Documentation[]直接喂给 LLM 的场景显式txt拿格式化文本。client.test.ts 中的 type inference 测试组正是对这一重载推断的回归保障。五、响应解析json 与 txt 两条路径5.1 JSON 路径默认v2/context返回{ codeSnippets, infoSnippets }两类原始数据get-context/types.ts命令层将其统一映射为Documentation[]const codeDocs apiResult.codeSnippets.map(formatCodeSnippet); const infoDocs apiResult.infoSnippets.map(formatInfoSnippet); return [...codeDocs, ...infoDocs];formatCodeSnippetutils/format.ts会把 API 的codeList含语言标记重新拼装为 围栏代码块再拼上codeDescriptionsource字段取自codeId/pageId保留了可回溯的来源标识。5.2 TXT 路径type: txt时服务端直接返回格式化文本SDK 原样透传字符串searchLibrary的 txt 路径则例外——它仍先解析results为Library[]再由formatLibrariesAsText本地渲染为人类可读的库清单含 Title、Context7-compatible library ID、Description、Trust Score 标签、Versions 等字段utils/format.ts。5.3 HTTP 层重试、退避与内容类型分支http/index.ts 中的HttpClient承担通用传输职责重试循环L153-L169最多attempts默认 5次网络异常时按backoff(retryCount)默认Math.exp(retryCount) * 50ms约 148/407/1103/2981ms 递增等待后重试AbortSignal触发时直接抛出耗尽后抛Exhausted all retries。非 2xx 处理解析错误响应体中的error/message字段封装为Context7Error。内容类型分支L176-L185application/json走res.json()返回结构化结果否则读取文本并尽力解析x-context7-page、x-context7-limit、x-context7-total-pages、x-context7-has-next/prev、x-context7-total-tokens等响应头为分页元数据。从源码结构看这些TxtResponseHeaders目前由传输层提取并随Context7Response返回但GetContextCommand/SearchLibraryCommand的exec只消费result分页元数据尚未向 SDK 使用者暴露——这与 0.2.0移除分页选项的简化方向一致。六、可复制的最小用法与测试基线综合 README 与 0.3.0 语义当前版本的完整用法如下json为默认可省略 optionsnpm install upstash/context7-sdkimport { Context7 } from upstash/context7-sdk; const client new Context7({ apiKey: CONTEXT7_API_KEY }); // 1. 检索库默认返回 Library[] const libraries await client.searchLibrary( I need to build a UI with components, react ); console.log(libraries[0].id); // /facebook/react // 2. 获取文档上下文默认 jsonDocumentation[] const docs await client.getContext(How do I use hooks?, /facebook/react); console.log(docs[0].title, docs[0].content); // 3. 显式取纯文本LLM 友好 const context await client.getContext( How do I use hooks?, /facebook/react, { type: txt }); console.log(context);仓库自带的集成测试 client.test.ts需设置CONTEXT7_API_KEY后pnpm test运行覆盖了默认与显式json返回数组且字段完整title/content/source、txt返回非空字符串、多库场景/vuejs/core、/expressjs/express、无效库 ID 的拒绝rejects.toThrow()、以及空参数在命令层即抛Context7Error对应 search-library/index.ts 的参数守卫。七、升级与使用注意事项结合 CHANGELOG 与源码使用该 SDK 时的关键注意点0.3.0 的默认值变更是运行时行为变化如果旧代码依赖searchLibrary/getContext不传type时拿到字符串升级后拿到的是数组需要显式补{ type: txt }。AI SDK 工具包的适配方式显式txt是官方给出的参考做法。0.2.0 起不存在getDocs迁移旧代码时应改为getContext(query, libraryId)且不再支持分页、topic、limit 等参数libraryId需使用 Context7 库 ID 格式/org/project可带版本如/org/project/v14.3.0-canary.87格式说明见 query-docs.ts 的输入 schema。API key 必须可用构造期缺 key 即抛错前缀不匹配仅告警环境变量名为CONTEXT7_API_KEY。README 标注该 SDK 处于活跃开发期Work in Progress未来可能引入破坏性变更仓库内版本为 0.3.0MIT 许可LICENSE。从 CHANGELOG 的演进轨迹可以归纳出该 SDK 的设计收敛路径0.1.0 提供完整的 REST 能力 → 0.2.0 砍掉客户端侧的分页与过滤把决策权交给服务端 → 0.3.0 把默认输出改为结构化json让 SDK 对程序化消费更友好同时保留txt供 LLM 直用。两个端点v2/libs/search、v2/context、两个数据类型Library、Documentation、一个选项type——这套极简 API 面与命令式分层Command→HttpClient的源码结构共同构成了当前版本的稳定骨架。【免费下载链接】klavisKlavis AI: MCP integration platforms that let AI agents use tools reliably at any scale项目地址: https://gitcode.com/GitHub_Trending/kl/klavis创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考