【免费下载链接】context-hub项目地址https://gitcode.com/gh_mirrors/co/context-hub点击查看免费下载本文以 Context Hub 仓库中的多版本文档测试样例 v1/DOC.md 为线索系统讲解 Context Hubchub CLI如何组织、构建、检索与获取按版本划分的 API 文档包括多版本目录的布局规范、frontmatter 元数据约定、recommendedVersion的确定规则以及chub get --version的底层解析逻辑。读完本文你将能独立为第三方 API 编写多版本文档并理解 Agent 通过 chub 拉取指定版本文档时的完整调用链。一、多版本文档的定位为什么需要按版本维护文档编码 Agent 在调用第三方 API 时最容易犯的错误是凭训练数据中的记忆去猜测 API 形态而真实 API 往往随版本演进发生破坏性变更breaking changes。Context Hub 的解决方案是把文档做成版本化、按语言划分的 Markdown 内容Agent 先chub get拉取当前版本文档再据此写代码参见 README.md 与 get-api-docs 技能。当同一个 API 存在多个不兼容的大版本如 v1、v2时就不能再用单一文档而要为每个版本单独维护一份DOC.md。仓库中的versioned-api样例正是为了演示并测试这一机制而存在的它在 cli/test/fixtures/acme/docs/versioned-api/ 下同时存放 v1、v2 两个版本目录二者共享同一个 frontmattername: versioned-api而metadata.versions分别声明为1.0.0与2.0.0。二、逐字段解剖 v1 文档frontmatter 与正文先看关联文档 v1/DOC.md 的完整内容--- name: versioned-api description: A test API with multiple versions metadata: languages: javascript versions: 1.0.0 revision: 1 updated-on: 2025-01-01 source: community tags: test,versioned --- # Versioned API v1 This is version 1.0.0 of the API documentation. ## Usage javascript const client new AcmeClient({ version: v1 });这份文档由两部分组成YAML frontmatter 元数据 Markdown 正文。结合 [build.js](https://link.gitcode.com/i/a79507a91ee147ce115429432cffa2e9) 的解析逻辑parseFrontmatter 见 [frontmatter.js](https://link.gitcode.com/i/43bafb9a7db3983b888dec6aac4063aa)各字段的作用如下 | 字段 | 必填 | 说明 | |------|------|------| | name | 是 | 文档条目名与 author 一起构成唯一 ID如 acme/versioned-api同一 API 的多个版本必须使用**相同**的 namebuild 才会把它们聚合成一个条目 | | description | 建议 | 搜索摘要用于 chub search 的结果展示与 BM25 索引 | | metadata.languages | 是 | 文档适用的语言逗号分隔如 javascript缺失会导致 build 报错 missing metadata.languages in frontmatter | | metadata.versions | 是 | 版本号逗号分隔如 1.0.0缺失同样导致 build 报错 | | metadata.revision | 否 | 内容修订序号该样例为 1 | | metadata.updated-on | 否 | 文档更新日期缺省时 build 会回退到构建当天的日期 | | metadata.source | 否 | 内容来源缺省时回退为 community样例显式声明 community | | metadata.tags | 否 | 逗号分隔的标签用于 chub search --tags 过滤 | 正文部分则是常规 Markdown标题 # Versioned API v1、版本说明、以及一个可直接运行的 JavaScript 用法示例 javascript const client new AcmeClient({ version: v1 });该示例通过构造参数指定version: v1与本文档声明versions: 1.0.0一一对应体现了文档版本号与 SDK 客户端版本参数保持一致的编写惯例。三、多版本目录的组织规范官方内容规范在 content-guide.md 的 Multi-version docs 一节给出了明确约定当 API 存在跨大版本的破坏性变更时为每个版本建一个子目录每个子目录放一份DOC.mdauthor/docs/entry-name/ v1/ DOC.md # versions: 1.0.0 v2/ DOC.md # versions: 2.0.0versioned-api样例完全遵循该布局v1 目录声明1.0.0v2 目录声明2.0.0二者name相同均为versioned-api。这样 build 时就会把它们合并为同一个 registry 条目而不是两个独立文档。仓库中真实内容的同款示例是 content/openai/docs/chat/按语言拆分为go1.3.0、javascript6.27.0、python2.26.0三个变体共用openai/chat这个 ID。规范还支持多版本 × 多语言的组合嵌套author/docs/entry-name/ v1/ javascript/ DOC.md python/ DOC.md v2/ javascript/ DOC.md python/ DOC.md四、build 阶段如何聚合版本从目录到 registry执行chub build content-dir时build.js 的discoverAuthor函数会递归扫描每个 author 目录下的所有DOC.md/SKILL.md并完成版本聚合。关键逻辑以 build.js 为准可以概括为四步按 name 分组以 frontmatter 的name为 key把多个版本目录下的DOC.md归并到同一个docsMap 项中按语言收集版本每个语言下维护一个版本数组遍历metadata.languages与metadata.versions的组合为每个语言, 版本生成一条{ version, path, files, size, lastUpdated }记录版本降序排序versions.sort((a, b) b.version.localeCompare(a.version, undefined, { numeric: true }))——注释明确说明这是简单字符串排序对 semver 足够用确定推荐版本recommendedVersion直接取排序后数组的第一个即数值意义下的最高版本作为 Agent 不指定版本时的默认值。因此对versioned-api而言build 后 registry 中会出现id: acme/versioned-api languages: - language: javascript recommendedVersion: 2.0.0 versions: - version: 2.0.0 # path: acme/docs/versioned-api/v2 - version: 1.0.0 # path: acme/docs/versioned-api/v1这一行为在端到端测试 e2e.test.js 中有明确断言acme/versioned-api的 javascript 语言下应有 2 个版本且recommendedVersion为2.0.0。需要说明的是这种排序方式对标准 semver如1.0.0、2.0.0是正确的从源码注释看项目有意选择了足够用的简单字符串排序而非完整 semver 比较。五、get 阶段的版本解析原理resolveDocPath当 Agent 执行chub get acme/versioned-api --lang js [--version X]时版本解析发生在 registry.js 的resolveDocPath函数中其决策树如下未指定--version优先使用langObj.recommendedVersion对应的版本若推荐版本记录不存在则回退到该语言版本数组的第一个元素langObj.versions?.[0]。这就是默认拿到最新文档的机制指定--version在langObj.versions中精确匹配v.version version命中则返回该版本的path随后 resolveEntryFile 拼接出path/DOC.md未命中则返回versionNotFound: true并携带available该语言所有可用版本列表。错误信息最终由 get.js 输出例如Version 99.0.0 not found for acme/versioned-api. Available versions: 2.0.0, 1.0.0此外--lang的解析也值得一提用户可用js、py、ts、rb、cs等别名normalize.js 会将其统一映射为javascript、python等全称后再做匹配若文档存在多个语言变体而未指定--lang则返回needsLanguage提示并列出可用语言get.js。六、实战搜索与获取指定版本文档结合 get-api-docs 技能 的完整工作流多版本文档的典型用法如下# 1. 搜索可用文档可加 --json 便于程序解析 chub search acme versioned --json # 2. 获取推荐最新版本——不传 --version 时默认拿到 v2 chub get acme/versioned-api --lang js # 3. 显式指定历史版本 chub get acme/versioned-api --lang js --version 1.0.0 # 4. 版本不存在时CLI 会列出可用版本 chub get acme/versioned-api --lang js --version 99.0.0执行第 2 步时输出内容即为 v2/DOC.md 的正文# Versioned API v2、version 2.0.0执行第 3 步时输出内容才是本文主角 v1/DOC.md# Versioned API v1、version 1.0.0与const client new AcmeClient({ version: v1 });。这些行为均有端到端测试背书e2e.test.js默认获取推荐版本chub get acme/versioned-api --lang js输出包含Versioned API v2指定版本--version 1.0.0输出包含Versioned API v1不存在的版本--version 99.0.0报错并列出2.0.0、1.0.0。七、编写多版本文档的实操建议结合上述机制为第三方 API 编写多版本文档时应遵循以下几点每个大版本一个目录目录名使用v1、v2等可读形式版本号写入metadata.versions如1.0.0所有版本目录共享同一name否则 build 会把它们当作互相独立的文档条目确保metadata.languages与metadata.versions都非空否则 build.js 会直接报错拒绝构建正文与版本号保持一致文档标题、示例代码中的版本参数如AcmeClient({ version: v1 })要与 frontmatter 声明的版本对应避免 Agent 拿到 v1 文档却写出 v2 的调用代码把最新版本作为默认build 自动以最高版本为recommendedVersionAgent 不传--version时永远拿到最新文档因此维护者应确保最新版本目录内容更新、准确组合多语言时嵌套语言目录v1/javascript/、v1/python/并在每个DOC.md中各自声明languages与versions。八、可继续深入阅读的仓库路径本文主角文档v1/DOC.md 与同条目的 v2/DOC.md多版本目录规范docs/content-guide.mdbuild 聚合与推荐版本逻辑cli/src/commands/build.js版本解析核心函数cli/src/lib/registry.js--version/--lang命令行入口cli/src/commands/get.js多版本端到端测试cli/test/e2e.test.js真实多语言版本化内容示例content/openai/docs/chat/赞分享【免费下载链接】context-hub项目地址https://gitcode.com/gh_mirrors/co/context-hub点击查看免费下载相关推荐Parabol性能优化如何应对大规模团队并发会议场景Parabol性能优化如何应对大规模团队并发会议场景 Parabol作为一款免费的在线敏捷回顾会议工具在支持大规模团队并发会议时面临着诸多性能挑战。本文将深Context Hubchub完全指南为 Coding Agent 提供可信、可版本化、可自我进化的 API 文档服务Context Hubchub完全指南为 Coding Agent 提供可信、可版本化、可自我进化的 API 文档服务 导读 Context HubCLTypeGraphQL类型文档版本控制多版本API文档管理TypeGraphQL类型文档版本控制多版本API文档管理 随着TypeGraphQL项目的快速迭代多版本API文档的管理成为开发者面临的重要挑战。本文将详后端GraphQLAPI设计创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考