Context Hub (chub) 详细总结

本文档总结 Context Hub 的用途、原理、远程地址、本地目录、注解机制及与 Claude Code 的配合方式，便于查阅和落地使用。

---

1. 是什么

Context Hub 是为编程 AI Agent 准备的「文档中心」：

• 提供版本化、可检索的 API/技能文档，减少 Agent 幻觉和过时用法。
• 内容以 Markdown 形式在仓库中维护，可审查、可贡献。
• 支持本地注解和反馈回上游，让 Agent 随使用变聪明。

核心 CLI 叫 chub（@aisuite/chub），设计给 Agent 调用，而不是主要给人手敲。

---

2. 原理简述

环节	说明
Curated 文档	文档按主题/API 组织，Agent 用 CLI 按需拉取，而不是泛搜网页。
版本 + 语言	同一文档可有多种语言（如 --lang py / --lang js），保证拿到的是对应版本。
本地注解	Agent 用 chub annotate 在本地给某条文档加备注；下次 chub get 同一 ID 时，备注会自动附在文档后。
反馈回上游	通过 `chub feedback up

整体流程：搜索 → 拉取 → 写代码 → 有坑就注解/反馈 → 下次更准。

---

3. 安装与基本用法

3.1 安装

npm install -g @aisuite/chub

3.2 常用命令

命令	作用
chub search [query]	搜索文档（不写 query 则列出全部）
chub get <id> [--lang py|js]	按 ID 拉取文档（可指定语言）
chub annotate <id> <note>	给该文档加本地注释
chub annotate <id> --clear	清除该文档的本地注释
chub annotate --list	列出所有本地注释
chub feedback <id> up|down	对该文档投赞成/反对（反馈给维护者）
chub update	从远程刷新 registry 缓存
chub cache status	查看缓存状态

3.3 典型流程（给 Agent 用）

chub search "stripe payments"
chub get stripe/api --lang js
# 若发现文档有缺漏，可本地记一笔
chub annotate stripe/api "Webhook 校验需要 raw body"
chub feedback stripe/api up

---

4. 搜索与拉取：数据从哪来

4.1 搜索范围

• chub search 只搜 Context Hub 的 registry（目录），不搜全网。
• 目录来自：默认远程 CDN，或 ~/.chub/config.yaml 里配置的 sources（含本地 path）。
• 若执行过 chub update，会优先用本地缓存的 registry。

4.2 文档拉取来源

• chub get <id> [--lang py] 的文档内容来自：当前生效的 source。
• 默认 source 的 base URL：https://cdn.aichub.org/v1（可在 config 里改）。

4.3 远程地址规则（源码依据）

在 cli/src/lib/cache.js 中：

用途	拼接方式	默认完整 URL 示例
Registry（目录）	source.url + "/registry.json"	https://cdn.aichub.org/v1/registry.json
单篇文档	source.url + "/" + docPath	https://cdn.aichub.org/v1/openai/docs/chat/python/DOC.md
全量离线包	source.url + "/bundle.tar.gz"	https://cdn.aichub.org/v1/bundle.tar.gz

其中 docPath 来自 registry 里该条目的 path + 主入口文件名（doc 为 DOC.md）。例如 registry 里 openai/chat 的 python 项为：

• path: "openai/docs/chat/python"
• files: ["DOC.md"]

则拉取 Python 文档时请求的 URL 即为：

https://cdn.aichub.org/v1/openai/docs/chat/python/DOC.md

---

5. Registry 条目结构示例

Registry 里一条 doc 的典型结构（与你看到的 openai/chat 一致）：

{
  "id": "openai/chat",
  "name": "chat",
  "description": "OpenAI API for text generation, chat completions, ...",
  "source": "maintainer",
  "tags": ["openai", "chat", "llm", "ai"],
  "languages": [
    {
      "language": "python",
      "versions": [
        {
          "version": "2.26.0",
          "path": "openai/docs/chat/python",
          "files": ["DOC.md"],
          "size": 14043,
          "lastUpdated": "2026-03-06"
        }
      ],
      "recommendedVersion": "2.26.0"
    }
  ]
}

• path：该语言版本在 CDN 上的目录路径。
• files：该目录下可拉取的文件列表，主入口为 DOC.md。
• chub get openai/chat --lang py 会解析到上述 path，再请求 path/DOC.md。

---

6. 本地注解（annotate）

6.1 含义

• 「给该文档加本地注释」 = 在你本机给「某条文档」绑一段自己写的备注；之后每次 chub get 该 ID 时，这段备注会自动附在文档正文后面。
• 本地：只存在本机 ~/.chub/annotations/，不上传到 Context Hub 服务器。
• 注释：即你在 chub annotate <id> <note> 里写的 <note> 内容。

6.2 适用场景

• 文档里没写、但你在项目里踩过的坑（例如：必须用 v2 webhook、要传 raw body、需配合 idempotency key 等）。
• 希望 Agent 在新会话或换机器后，只要再次 chub get 同一条文档，就能看到这些补充说明。

6.3 常用命令

chub annotate openai/chat "项目里用 v2 webhook，校验时传 raw body"
chub annotate openai/chat                  # 查看当前备注
chub annotate openai/chat --clear         # 删除备注
chub annotate --list                      # 列出所有加过备注的文档

6.4 与文档内容的区别

对比项	文档内容（DOC.md）	annotate 备注
来源	远程 CDN / 本地 source	本机 chub annotate 写入
存储位置	拉取后可能在 ~/.chub/sources/<name>/data/	~/.chub/annotations/
可见范围	所有能访问该 source 的人	仅本机
用途	官方/社区 API 说明	项目/环境相关的坑与注意点

---

7. 本地目录 ~/.chub 结构

7.1 典型目录与文件

~/.chub/
├── client_id              # 匿名客户端 ID（遥测用，可选）
├── config.yaml            # 可选；不创建则使用 CLI 默认配置
├── sources/
│   └── <source_name>/     # 例如 default
│       ├── meta.json      # 该 source 的元信息（如 lastUpdated、bundledSeed）
│       ├── registry.json  # 该 source 的文档/技能目录
│       └── data/          # 拉取过的文档缓存（按 path 存）；可能不存在
└── annotations/           # 仅在使用过 chub annotate 后存在
    └── <id>.json         # 按条目 ID 存的注解

7.2 各文件含义

• client_id：匿名标识本机，用于可选遥测（如 feedback）；无个人身份信息。
• config.yaml：若不存在，则使用内置默认（如默认 source、cdn.aichub.org）。
• sources//meta.json：该 source 的 registry 上次更新时间等；bundledSeed: true 表示来自 npm 包自带种子数据。
• sources//registry.json：chub search / chub get 解析 ID、语言、path 的依据。
• sources//data/：按 path 缓存的已拉取文档；未拉取过则可能无此目录。
• annotations/：仅在使用 chub annotate 后存在；每条注解一个文件。

7.3 若 registry 中没有某库（如 Taro）

• 当前官方/社区 registry 中若没有该库（例如 Taro），chub search / chub get 无法直接使用。
• 可选做法：
  1. 直接用官方文档：例如 Taro 用 taro-docs.jd.com。
  2. 向 Context Hub 贡献：按 Content Guide 在 content/ 中提交该库的 doc，合并后大家可通过 chub update 使用。
  3. 自建本地 source：在本地按 Context Hub 格式组织 Markdown + registry.json，在 config.yaml 中增加 path 类型 source，即可用 chub get 拉取自建文档。

---

8. 与 Claude Code 的配合

• 直接提示：让 Agent「用 chub 拉取最新的 XXX API 文档，先执行 chub help 了解用法」。
• Skill：在 ~/.claude/skills/get-api-docs（或项目内技能目录）中提供 SKILL.md，说明何时用 Context Hub、何时用 chub search / chub get，让 Agent 在需要查 API/文档时自动使用 chub。

---

9. 配置示例（可选）

~/.chub/config.yaml 示例：

sources:
  - name: community
    url: https://cdn.aichub.org/v1
  # 可选：本地 content 目录
  # - name: internal
  #   path: /path/to/local/docs

source: "maintainer,community"   # 信任的 source 列表
refresh_interval: 86400          # registry 缓存 TTL（秒），默认 24 小时
telemetry: true                   # 匿名使用统计，可关

多 source 时，若同一 ID 在多处存在，可用 chub get <source>:<id> 指定来源。

---

10. chub 与 Context7 MCP 对比及上下文控制

10.1 二者区别

维度	Context Hub (chub)	Context7 MCP
形态	CLI：终端执行 chub search / chub get	MCP：通过工具 resolve-library-id、query-docs 调用
数据来源	Context Hub 自有的 registry + CDN（固定清单）	Context7 API，库 ID 形如 /org/project 或 /org/project/version
检索方式	按文档 ID 拉整份：search → get 拿到一整份 DOC.md（或 --file 单文件）	按问题取片段：resolve 库名 → 用 query 问「具体问题」→ API 返回与该问题相关的片段
返回内容	完整 Markdown 文档（可能较长）	针对本次 query 的若干片段（更切题）
覆盖范围	仅 registry 内条目（如无 Taro 则搜不到）	依赖 Context7 支持的库，通常覆盖更广且可带版本
本地/注解	支持 chub annotate、chub feedback	无本地注解，纯在线查询

简要：chub 适合「我要这份 API 的完整说明」；Context7 适合「我要回答这个具体问题该用哪段文档」。

10.2 会不会造成上下文过大？

会。 两种方式都会往对话里塞内容，只是方式不同：

• chub：一次 get 就是整份文档（registry 里可见 size，如 14KB～几十 KB）；若再 --full 或连续 get 多条，上下文会明显膨胀。
• Context7：单次返回多为「相关片段」，但多次调用或 query 过泛仍会累积；工具说明已限制「每问题最多 3 次调用」以控制用量。

10.3 使用建议（控制上下文）

1. 用 chub 时：一次只 get 当前任务需要的那一条；能用 --file 只拉某一小节就不用整份；避免在同一会话里无脑 get 多份大文档。
2. 用 Context7 时：遵守「每问题最多 3 次」；query 尽量具体，减少无效调用和长返回。
3. 选择与搭配：要整份、权威的 API 说明且 chub 有该条 → 用 chub；要针对具体问题找片段，或 chub 没有该库 → 用 Context7；也可组合使用，但注意只拉/只问当前必要的一条或几次，避免上下文过大。

---

11. 小结表

主题	要点
用途	给编程 Agent 提供可检索、版本化、可反馈的 API/技能文档，减少幻觉。
搜索范围	仅 Context Hub 的 registry，不搜全网。
默认远程	https://cdn.aichub.org/v1（registry.json、DOC.md、bundle.tar.gz）。
文档 URL	{source.url}/{path}/{文件名}，如 .../openai/docs/chat/python/DOC.md。
本地注解	存于 ~/.chub/annotations/，仅本机；下次 chub get 同 ID 时自动附在文档后。
反馈	`chub feedback up
无某库时	用官方文档、向 Context Hub 贡献、或自建本地 source。

---

参考链接

• Context Hub 仓库
• CLI Reference
• Feedback and Annotations
• Content Guide