Context Hub（CHUB）是由 Andrew Ng 团队设计并开源的一套**上下文工程（Context Engineering）**基础设施。其核心定位是作为一个基于Model Context Protocol（MCP）的专用文档服务器，旨在系统性解决大型语言模型驱动（LLM-powered）的编程助手因“知识截止”（training data cutoff）而产生的API调用风险——例如调用已废弃的方法、使用错误的参数格式或遗漏必填字段。

它的核心哲学并非试图“升级”LLM本身，而是从根本上革新AI所消费的上下文的供给方式。通过一个标准化、可检索、可缓存、可版本化的文档分发与索引系统，确保AI在生成代码时，始终基于最新、最准确且最结构化的信息源。

1. 核心理念：作为BYOD（Bring Your Own Docs）系统

Context Hub的设计核心是**BYOD（Bring Your Own Docs）**理念。它不仅仅是一个托管公开文档的社区工具，更是一个灵活的、自带文档的私有化基础设施。它使任何团队能够：

1. 定义私有知识源：为内部API、SDK、专有工具和最佳实践构建专属的、结构化的文档知识库。
2. 统一上下文对齐：确保组织内所有开发者和AI助手（如Cursor、Claude Code）共享同一份、且实时的上下文基准。
3. 实现知识沉淀：通过内置的注解和反馈系统，将开发中的隐性经验（如特定环境配置、版本迁移的坑点）显性化、持久化，形成组织级的可复用知识资产。
4. 无缝融入现有工具链：通过CLI工具和标准MCP服务器，将自有文档无缝集成到开发者的本地环境和AI助手的日常工作流中。

简而言之，Context Hub是将“文档即基础设施”这一理念产品化，将上下文信息从临时的、手动的、模糊的输入，转变为标准化的、自动化的、精准的供给系统。

2. 架构与核心组件

Context Hub的生态系统由生产者（构建者）、存储（知识库）、消费者三个核心角色构成闭环工作流。

┌─────────────────┐ 构建产物及缓存-所在地  ┌────────────────────┐
│      生产者       ├──────────────────────┤        存储库        │
│ （内容开发者）      │                       │ （CDN/私有服务器）     │
├─────────────────┤                       ├────────────────────┤
│ → 撰写Doc/Skill  │                       │  → registry.json    │
│ → `chub build`   ├─> dist/──────────────>│   搜索索引缓存       │
│ → `chub validate`│                       │   源文档镜像副本      │
└─────────────────┘                       └────────────────────┘
                                                     ↓  检索与分发
                                              ┌────────────────────┐
                                              │        消费者       │
                                              │ （开发者和AI Agent） │
                                              ├────────────────────┤
                                              │ ← `chub update`      │
                                              │ ← `chub search`      │
                                              │ ← `chub get`        │
                                              │ ← `chub annotate`   │
                                              │ → MCP (`chub-mcp`) │
                                              └────────────────────┘

关键组件详解：

• 生产者（Producer）：内容创建者。遵循严格的结构化规范，编写标记为DOC.md（参考文档）或SKILL.md（操作指南）的Markdown文件，然后使用chub build命令将其编译为标准的知识包。
• 存储库（Repository）：内容托管处。可以是一个指向构建产物的本地路径，也可以是一个托管于CDN或内部服务器的URL。核心存储以下文件：
  • registry.json：所有文档和技能的元数据索引，是系统运行的“中枢”。
  • search-index.json：基于BM25算法，仅对 registry.json 中的 id、name、tags、description 四个字段生成的快速检索索引。
  • {package-name}/：完整的源文件镜像副本，用于按需获取原始内容。
• 消费者（Consumer）：内容和系统的使用者，包含：
  • CLI工具：开发者通过 chub 系列命令直接在终端中搜索、获取、管理内容。
  • AI Agent (MCP服务器)：通过标准化的Model Context Protocol（MCP），使Cursor等AI编程助手能够主动调用 chub_search、chub_get 等工具，动态检索最佳上下文。
• 配置层 (~/.chub/config.yaml)：连接上述所有组件的枢纽。用户在此处声明要使用的数据源（Sources），可以是公共源（如社区源），也可以是私有源（如指向内部构建产物的路径），并配置缓存、信任等全局行为。

3. 内容类型：Doc 与 Skill

Context Hub 将知识内容精炼为两种核心类型，每种都服务于不同的AI消费场景。

类型	定义	文件位置	核心用途与消费场景	类比
Doc （文档）	面向参考的知识（Reference Knowledge），描述“是什么”（What）。	{package}/docs/{topic}/{language}/DOC.md	API调用、SDK使用、参数说明。AI需要查询和理解某个函数、某个类如何工作时使用此类型。例如：“如何使用OpenAI的聊天补全API？”、“FastAPI路由函数的参数有哪些？”	百科全书词条
Skill （技能）	面向操作的知识（Procedural Knowledge），描述“怎么做”（How）。	{package}/skills/{skill-name}/SKILL.md	完成特定任务的工作流、最佳实践、错误处理模式。AI需要执行和实现一个具体目标时使用此类型。例如：“如何使用LandingAI提取PDF表格？”、“如何将一个Express.js应用部署到AWS？”	食谱或操作手册

这两种类型共用相同的分发、检索和标注框架，但其在元数据和构建产物（registry.json）的结构上有着明确的差异（详见下文）。这种清晰的划分旨在减少AI在处理请求时的上下文噪音，让其能够“对症下药”——需要参考信息时获取Doc，需要操作指导时获取Skill。

4. 系统配置 (config.yaml)

配置文件（~/.chub/config.yaml）是用户与Context Hub系统交互的首要接口。该文件在首次运行CLI时自动生成。

4.1 完整配置字段说明

# Context Hub 配置文件 (~/.chub/config.yaml)

telemetry: true                          # [可选] 是否启用匿名遥测数据上报，用于改进工具。可设置为 `false` 关闭，或设置环境变量 `CHUB_TELEMETRY=0`。
source: "official,maintainer,community" # [可选] 全局信任策略，指定在搜索和获取时优先考虑哪些来源等级的条目。按逗号分隔的优先级列表。

refresh_interval: 21600                 # [可选] 传输索引缓存 (`registry.json`) 的默认刷新间隔（单位：秒）。默认值：6小时。只影响元数据，不影响文档内容缓存。

sources:                                # [必需] 定义可供系统使用的数据源列表。
  - name: community                     # [必需] 数据源的唯一标识符。将在命令中用于 `source:ID` 前缀匹配。
    url: https://cdn.aichub.org/v1      # [二选一] 当 `type` 为 `remote`（默认）时使用，指向托管了构建产物（dist/目录）的远程端点。
    # 或
    path: /path/to/local/dist           # [二选一] 当 `type` 为 `local` 时使用，指向本地文件系统上构建产物的路径。

    type: remote                        # [可选] 源类型：`remote` (远程HTTP服务) 或 `local` (本地目录)。默认: `remote`。
    priority: 50                        # [可选] 源优先级。当不同源中存在同名ID条目时，优先使用优先级更高的源。数值越大，优先级越高。默认: 50。
    refresh_interval: 43200             # [可选] 针对此特定源的元数据刷新间隔（秒），覆盖全局设置。

4.2 配置多源与优先级

可以配置多个源，包括公共社区源和多个私有源。priority 字段是关键：当多个源包含相同ID的条目时（例如，既有社区源的 openai/chat，又有内部优化的版本），系统将使用优先级最高源的条目进行搜索和获取。

sources:
  - name: internal-prod               # 内部生产API源，优先级最高
    path: /mnt/internal/docs/dist/prod
    priority: 200

  - name: internal-staging           # 内部预发布API源
    path: /mnt/internal/docs/dist/staging
    priority: 150

  - name: my-team-legacy             # 团队遗留但仍有价值的文档
    path: ~/projects/legacy/dist
    priority: 100

  - name: community                  # 默认公共社区源
    url: https://cdn.aichub.org/v1
    priority: 50                    # 优先级低于内部源

在这种配置下，当搜索 openai/chat 时，如果 internal-prod 源包含此条目，则优先使用它。如果只有 community 源包含，则使用社区源。这确保了内部依赖的优先性，同时保留了后备方案。

5. 内容构建与结构化规范 (chub build)

chub build 命令是将原始文档转换成Context Hub可消费、可索引格式的核心工具。其核心哲学是“通过路径即可推断内容语义”（Read by Path）。

5.1 严格的目录结构规范（Content Tree）

所有源内容必须严格遵循以下树状结构。chub build 会进行严格的路径解析，以自动生成条目ID、判断类型和语言等信息。

{content-dir}/           # 内容根目录，通常命名为 `content/`
└── {package-name}/         # 【必填】顶层包/项目名称。格式：全小写 kebab-case，需与官方包名对齐（例如 `fastapi`, `landingai`, `mycompany-internal-api`）。
    ├── docs/               # 【可选】文档（Doc）目录。
    │   └── {topic}/        # 【必填】功能主题或子模块名称。格式：kebab-case（例如 `chat`, `sdk`, `project-management`）。
    │       └── {language}/ # 【必填】（针对Doc）目标编程语言或接口类型。格式：小写（例如 `python`, `javascript`, `http`）。
    │           └── DOC.md  # 【必需且固定】文档入口文件。文件名必须为大写 `DOC.md`，且包含标准 YAML frontmatter。
    │
    └── skills/             # 【可选】技能（Skill）目录。
        └── {skill-name}/   # 【必填】技能名称。格式：动词或名词短语的 kebab-case（例如 `deploy-to-aws`, `document-extraction`）。
            ├── SKILL.md    # 【必需且固定】技能入口文件。文件名必须为大写 `SKILL.md`。
            ├── .env-sample # [可选] 环境变量模板文件。
            ├── .gitignore  # [可选] Git忽略文件模板。
            └── references/ # [可选] 技能相关的补充参考文档目录。
                └── {topic}.md # 参考文档，例如 `troubleshooting.md`, `advanced-usage.md`。

5.1.1 包结构类型对照表

包/项目类型	典型结构模式	使用场景示例
纯库/框架 (文件仅Doc)	{package}/docs/{topic}/{language}/DOC.md	fastapi/docs/api/python/DOC.md；pandas/docs/dataframe/python/DOC.md
复杂产品 (Doc + Skill)	{package}/docs/{topic}/{language}/DOC.md + {package}/skills/{skill-name}/SKILL.md	landingai/docs/sdk/python/DOC.md + landingai/skills/document-extraction/SKILL.md
操作型工具 (仅有Skill)	{package}/skills/{skill-name}/SKILL.md	sourceparts/skills/create-new-project/SKILL.md
多语言SDK	在 {package}/docs/{topic}/ 下创建多个语言子目录，每个目录内含 DOC.md。	openai/docs/chat/{python,javascript,go}/DOC.md
多版本文档	在 {package}/docs/{topic}/ 下创建版本子目录（如 v1/, v2/），每个版本目录下可按需嵌套语言子目录。	stripe/docs/payments/v1/python/DOC.md 和 stripe/docs/payments/v2/python/DOC.md

请注意：多版本控制原则上是通过管理独立的 Doc 条目（不同的 topic name）实现的。更推荐的做法是将版本号体现在 topic name 或目录结构中，例如 stripe/docs/payments-v1/python/DOC.md。如果使用目录版本，仅用于组织而非复杂的元数据版本管理。

5.2 YAML Frontmatter 元数据规范

DOC.md 和 SKILL.md 文件必须以三段虚线（---）包裹的 YAML frontmatter 开头，它是构建索引的唯一元数据来源。构建工具会进行严格的校验。

5.2.1 DOC.md Frontmatter （文档）

---
# 【核心标识】
name: chat                               # 【必填】构成条目ID的核心部分。此处的`name`将与外层目录的`topic`保持一致吗？请注意：条目ID (`id`) = `{package}/{name}`。此处 `name` 应指代具体的功能名称，可能与目录主题名一致，例如 “chat”。
description: "OpenAI Chat Completions API for text generation with gpt-4o-mini."  # 【警告级】用于搜索和建议的核心描述。缺失将产生构建警告。

# 【元数据块】
metadata:
  languages: "python,javascript,go"       # 【错误级】文档明确支持的语言列表。必须填写，多语言用逗号分隔。缺失将导致构建错误并终止。
  versions: "2.28.0"                     # 【错误级】此文档内容所适用的**包/SDK**的版本号。必须填写，多版本用逗号分隔。遵循语义化版本（例如来自 npm 或 pypi）。注意：这与直接的 API 版本可能不同。
  revision: 1                             # 【错误级】此文件内容的修订号。每次内容更新（即使是措辞修改）必须递增。从 1 开始。缺失将导致构建错误。
  updated-on: "2026-03-30"               # 【错误级】内容最后一次更新的日期。格式：YYYY-MM-DD。缺失将导致构建错误。
  source: "official"                     # 【警告级】文档来源的信任级别。可选值：`official` (官方团队维护)、`maintainer` (可靠社区成员维护)、`community` (一般社区贡献)。缺失将产生构建警告。
  tags: "openai,chat,llm,api"            # [可选] 用于搜索和过滤的标签。使用逗号分隔，无空格。
---

5.2.2 SKILL.md Frontmatter （技能）

---
# 【核心标识】
name: document-extraction                # 【必填】技能的唯一标识名。构成条目ID：`landingai/document-extraction`。
description: "Use LandingAI's ADE platform for intelligent PDF processing, table extraction, and entity recognition."  # 【警告级】技能的核心目标和价值的描述。缺失将产生构建警告。

# 【元数据块】
metadata:
  revision: 1                             # 【错误级】内容修订号。
  updated-on: "2026-03-10"               # 【错误级】更新日期。
  source: "maintainer"                   # 【警告级】来源信任级别。
  tags: "landingai,extraction,pdf,ocr"   # [可选] 搜索标签。
---

构建校验规则：

• 错误级（Error）：缺失 name、metadata.languages（仅限Doc）、metadata.versions（仅限Doc）、metadata.revision、metadata.updated-on 会导致构建立即失败，并提示明确错误。
• 警告级（Warning）：缺失 description、metadata.source 会导致构建产生警告，但会继续执行。

5.3 构建命令详解 (chub build)

# 1. 基本构建：将 './my-content/' 目录构建到默认的输出目录 './my-content/dist/'
chub build ./my-content/

# 2. 指定输出目录：将产物输出到自定义路径
chub build ./my-content/ -o ./output-dist/

# 3. 仅验证模式：检查内容结构和frontmatter，不生成任何文件（用于CI/CD中的预检查）
chub build ./my-content/ --validate-only

# 4. 强制重新构建：即使依赖项未改变，也强制重新执行所有构建步骤
chub build ./my-content/ --force

# 5. JSON输出：以JSON格式报告构建结果，便于脚本处理
chub build ./my-content/ --json

5.4 构建产物与 registry.json 深度解析

成功执行 chub build 后，将生成 dist/ 目录，其核心是 registry.json 和 search-index.json。

5.4.1 registry.json 核心结构

registry.json 是整个CHUB系统的元数据中枢。它显著区分了 docs 和 skills 的条目结构，以匹配其不同的特性。

{
  "version": "1.0.0",
  "generated": "2026-03-30T10:00:00Z",
  "docs": [
    {
      "id": "openai/chat",                // ID = `package/name`
      "name": "chat",
      "description": "...",
      "source": "official",
      "tags": ["openai", "chat"],
      // 【Docs特有】围绕语言（和隐含的版本）组织
      "languages": [
        {
          "language": "python",
          "recommendedVersion": "2.28.0",  // 自动选取 `versions` 中的最新版本
          "versions": [                      // 一个语言下可以有多个版本条目（参见 `metadata.versions`）
            {
              "version": "2.28.0",           // 包/SDK的特定版本
              "path": "openai/docs/chat/python", // 源文件的相对路径（相对于 content 根目录）
              "files": ["DOC.md"],
              "size": 15321,
              "lastUpdated": "2026-03-29"
            }
          ]
        },
        {
          "language": "javascript",
          "recommendedVersion": "4.30.0",
          "versions": [
            {
              "version": "4.30.0",
              "path": "openai/docs/chat/javascript",
              "files": ["DOC.md"],
              "size": 14200,
              "lastUpdated": "2026-03-28"
            }
          ]
        }
      ]
    }
  ],
  "skills": [
    {
      "id": "landingai/document-extraction",
      "name": "document-extraction",
      "description": "...",
      "source": "maintainer",
      "tags": ["landingai", "pdf"],
      "path": "landingai/skills/document-extraction", // 根级路径
      "files": [ // 技能的所有支持文件都直接列出，包含入口文件和所有 references/ 下的文件
        "SKILL.md",
        ".env-sample",
        "references/chunk-types.md",
        "references/troubleshooting.md"
      ],
      "size": 62300,
      "lastUpdated": "2026-03-10"
    }
  ]
}

5.4.2 Doc 与 Skill 在 registry 中的关键差异总结

字段	Doc 条目	Skill 条目	说明与设计意图
id	{package}/{file.name}	{package}/{file.name}	统一的ID生成逻辑，便于引用。
path	不在根级。每个语言版本内部有自己的 path（如 languages[].versions[].path）。	直接存在于根级的 path。	Docs的获取需要指定语言和版本，路径需精确映射到该组合。Skills是完整的打包单元，路径指向技能根目录。
files	在 versions[].files 下，通常只有一个 DOC.md。	直接存在于根级的 files 数组，包含 SKILL.md 和所有 references/ 下的文件。	便于一次性获取技能的全部相关文件。
languages	有。数组结构，内含语言、版本、路径等详细信息。	无。	Docs按语言和版本进行组织，以支持多语言开发场景。Skills是语言无关的操作流，无需此结构。
recommendedVersion	有。自动选择 versions 中的最高版本。	无。	为AI Agent提供默认的、最新版本的文档，减少冗余选择。

5.4.3 search-index.json 与搜索机制

search-index.json 是基于 registry.json 中的 id、name、tags、description 这四个字段生成的BM25倒排索引。正文内容（Markdown body）不参与索引和搜索。这种设计确保了搜索的高效性和准确性，避免了全文检索带来的信噪比低的问题。

BM25算法赋予各字段权重：id权重 4.0 > name权重 3.0 > tags权重 2.0 > description权重 1.0。

5.4.4 启用本地私有源

要将构建产物用作私有知识源：

1. 构建：chub build ./internal-docs -o ./dist/internal。
2. 配置：编辑 ~/.chub/config.yaml，新增源：{ name: "internal", path: "/absolute/path/to/dist/internal", priority: 100 }。
3. 更新索引：chub update --source internal。

此后，chub search 和 chub get 将同时涵盖社区源和您的内部源。当ID冲突时，使用 internal:openai/chat 进行精确指定。

6. 缓存机制详解

Context Hub采用两级缓存策略来平衡数据实时性与访问性能。

6.1 缓存结构与生命周期

缓存类型	数据内容	存储位置	触发命令	生命周期	清除机制
① Registry索引缓存	registry.json、search-index.json、meta.json (记录刷新时间)	~/.chub/sources/{source-name}/	chub update（手动或后台自动触发）	有效期有限。默认6小时（由 refresh_interval 配置）。超时后，下次 chub update 或 chub search/get （当检测到过期时）会自动从远程更新。	chub cache clear （清除所有源的缓存）；chub update --force （强制刷新，不考虑有效期）。
② 文档内容缓存	具体的 DOC.md 或 SKILL.md 文件及其引用文件。	~/.chub/sources/{source-name}/data/{path-from-registry}	chub get <id> （首次拉取某个ID的特定版本/语言的文件时）。	永久缓存，无过期时间。旨在最大化离线可用性和后续访问速度。永久缓存意味着即使是代码错误或早期版本的知识，一经拉取将被长期保留。	chub cache clear （磁盘空间回收）。

本地缓存目录结构示例：

~/.chub/
├── config.yaml
└── sources/
    ├── community/
    │   ├── registry.json         # 索引缓存
    │   ├── search-index.json
    │   ├── meta.json
    │   └── data/                # 内容缓存
    │       └── openai/
    │           └── docs/
    │               └── chat/
    │                   └── python/
    │                       └── DOC.md
    └── internal/
        ├── registry.json
        ├── search-index.json
        ├── meta.json
        └── data/
            └── mycompany/
                └── skills/
                    └── deploy-prod/
                        ├── SKILL.md
                        └── references/
                            └── config-sample.yaml

6.2 获取 (chub get)行为逻辑与缓存优先级

当执行 chub get <id> 时，系统按以下顺序查找并返回内容，形成多级后备方案：

1. 本地缓存（优先级最高）：检查对应路径 ~/.chub/sources/{source}/data/{path} 是否存在缓存文件。若命中，直接读取并返回，无网络请求。
2. 内置包镜像（离线/预分发）：若缓存未命中，检查 chub CLI工具的 npm 包中是否内置了离线内容（适用于企业内网或离线环境）。
3. 远程/本地源拉取（最终兜底）：若以上均未命中，则根据配置的 url 或 path，从源位置拉取对应文件。拉取成功后，将内容自动写入本地缓存 (data/目录)。

6.3 缓存管理命令

# 1. 查看所有已配置源的缓存状态
chub cache status
# 输出示例：显示每个源的条目数、索引大小、最后更新时间、缓存文件大小等。

# 2. 清除所有缓存（强制下次所有操作重新获取）
chub cache clear
# 这是一个 **破坏性操作**，会完全删除 `~/.chub/sources/` 下的所有内容。
# 使用 `--force` 选项避免交互式确认：`chub cache clear --force`

# 3. 清除指定源的缓存
chub cache clear --source internal

# 4. 手动更新某个源或所有源的索引缓存
chub update                    # 更新所有源（遵循refresh_interval规则）
chub update --source internal  # 只更新内部源
chub update --force            # 强制更新，忽略索引缓存的有效期检查

7. 使用工作流：CLI与MCP集成

7.1 CLI 搜索与获取工作流 (chub search / chub get)

Context Hub 提供了一套直接、可脚本化的CLI工作流，非常适合管道（pipeline）和自动化。

7.1.1 深度搜索与过滤

chub search 是发现内容的唯一入口，搜索对象是“条目”，而非“文档内容”。

# 【模式一：列出与浏览】
# 1.1 查看所有可用的内容条目（前20个）
chub search
# 1.2 从指定源（如公司内部）列出内容
chub search --source internal

# 【模式二：精确ID查找/获取详情】
# 2.1 精确获取一个条目的详细信息，用于确认包含哪些语言/版本
chub search landingai/sdk
# 2.2 当有同名ID存在多个源时，使用`source:ID`格式精确指定
chub search internal:stripe/payment-intents

# 【模式三：关键词/标签模糊搜索】
# 3.1 在 `id`、`name`、`tags`、`description` 中匹配”stripe“
chub search stripe
# 3.2 用短语进行更精准的搜索
chub search "natural language processing"
# 3.3 步搜索和获取的管道示例
# 3.3.1 此链式操作为“搜索支付相关条目，并自动获取其最新版本（或指定语言）的完整内容”
# 使用 `jq` 等工具可轻松从 JSON 中提取元数据，然后由 `chub get` 跟进获取。
ID=$(chub search "stripe payment" --limit 1 --json | jq -r '.results[0].id')
chub get "$ID" -o .context/current-payment-doc.md
# 3.3.2 对 `internal` 源中标签为“api”的条目，获取其最新版本，并控制结果数量。
chub search --source internal --tags api --json | jq -r '.results[0].id' | xargs -I {} chub get {}

# 【模式四：高级过滤与脚本化】
# 4.1 只搜索属于 `skills` 类型的条目
# (注意，搜索结果不直接提供类型，但可间接通过不包含`languages`等字段在JSON中判断，或先搜索再`get`时推断。)
# 4.2 按语言过滤，如只列出包含 `python` 的文档。
chub search --lang python
# 4.3 按标签组过滤，查看同时标有“aws”和“deployment”的条目。
chub search --tags "aws,deployment"
# 4.4 限制结果数量，用于快速预览。
chub search "testing" --limit 5

7.1.2 精准获取与文件操作

chub get 是将条目转换为实际内容的关键命令。

# 【基础获取】
# 1.1 获取一个同时支持多语言的文档，必须指定语言 `--lang`
chub get openai/chat --lang python
# 1.2 获取一个技能（Skill），无需指定语言
chub get landingai/document-extraction
# 1.3 当文档仅支持单一语言时，可省略 `--lang`
chub get fastapi/api  # 假设 fastapi/api 仅支持 python
# 1.4 一次获取多个独立条目
chub get stripe/payment-intents openai/chat

# 【获取控制与输出】
# 2.1 将获取的内容直接写入指定文件，而非输出到终端
chub get stripe/payment-intents --lang python -o ./docs/stripe-payments.md
# 2.2 以JSON格式输出获取结果，包含元数据和内容
chub get stripe/payment-intents --lang python --json

# 【处理技能 (Skill) 的附加文件】
# 3.1 查看一个技能有哪些附加的支持文件（配置文件、参考文档等）
chub get landingai/document-extraction
# 输出末尾会提示类似：
# Additional files available (use --file to fetch):
# .env-sample
# references/chunk-types.md
# references/troubleshooting.md
# 3.2 仅获取指定的参考文件（如步骤文档或警告列表）
chub get landingai/document-extraction --file references/chunk-types.md
# 3.3 KILL.md，同时获取全部的相关支持文件，包括那些 `references/` 中的文档
chub get landingai/document-extraction --full
# 如果存在本地路径，`-o` 会指定保存主文件的路径，而 `--full` 行为不变
chub get landingai/document-extraction --full -o ./current-skill/

注意事项：

• 对于多语言Doc，未指定 --lang 时CLI会明确报错，并列出所有可用语言供选择。
• 对于单个附加文件的引用，使用 --file references/file.md。文件名是相对于技能根目录的路径（如注册表中 files[] 所列）。
• --full 适用于完整的技能，将其所有组成部分打包拉取。这对于离线归档或完整的任务复制非常有用。

7.2 AI Agent 集成与官方推荐工作流 (MCP)

Context Hub的核心价值在于赋能AI Agent。通过标准的MCP服务器 (chub-mcp)，AI编程助手能够主动、动态地搜索和获取上下文，全程自动化。

7.2.1 启动MCP服务器并连接AI助手

# 启动独立的MCP服务器（通常在后台运行，由IDE配置启动）
chub-mcp

启动后，AI助手将通过MCP协议获得以下工具（与CLI命令对应，但为函数调用形式）：

• chub_search(query, filters): 对应 chub search 功能。
• chub_get(id, lang, file...): 对应 chub get 功能。
• chub_list(): 列出所有可用条目，类似于不带查询的 chub search。
• chub_annotate(id, note): 读取或写入本地非共享的标注。
• chub_feedback(id, rating, labels...): 提交质量反馈。

AI助手（如Cursor）的配置通常涉及在IDE设置中指定MCP服务器的启动命令或socket。

7.2.2 推荐的AI Agent工作流（黄金闭环）

一个设计完善的Context Hub集成，应引导AI Agent遵循以下五步闭环工作流，形成越用越精准的“增长型知识”体系：

这个循环使得AI Agent不仅是简单的“API查询器”，而是进化为一个能够持续学习和积累“组织记忆” 的协作伙伴。

7.2.3 管道模式（Pipeline）与脚本集成

Context Hub CLI的标准化输出使其极易与shell脚本、自动化工具和CI/CD流水线集成。

#!/bin/bash
# 【脚本示例：自动创建项目上下文快照】
# 1. 搜索与当前项目描述相关的技能和文档
CONTEXT_FILE=".context/project-setup-$(date +%Y%m%d).md"

# 搜索可能相关的条目并获取前2个
SEARCH_RESULTS=$(chub search --tags "setup,database,auth" --limit 2 --json)
IDS=$(echo "$SEARCH_RESULTS" | jq -r '.results[] | .id')

# 2. 拉取每个条目的最新版文档
for ID in $IDS; do
  echo "## Context from: $ID" >> "$CONTEXT_FILE"
  # 尝试获取，如果失败（如多语言未指定）则跳过
  chub get "$ID" --lang python 2>/dev/null >> "$CONTEXT_FILE"
  echo -e "\n---\n" >> "$CONTEXT_FILE"

done

echo "Project context snapshot saved to $CONTEXT_FILE"

# 【管道示例：在切换分支前强制更新本地知识库】
# 假设切换到一个新功能分支，需要确保本地缓存是最新的
chub cache clear --source internal 2>/dev/null  # 清除内部缓存的旧索引
chub update --source internal --force           # 强制获取最新的内部API信息
# 现在 `chub get` 将重新拉取内容

这种脚本化能力使得团队可以将Context Hub的更新和上下文准备集成到标准的开发工作流（如git hooks、项目初始化脚本、环境启动脚本）中，确保开发环境的知识状态始终与代码库或部署环境对齐。

8. 最佳实践

8.1 内容编写与组织最佳实践

遵循以下原则，可以创建出对AI最友好、最易消费的高质量内容。

8.2 管道模式（Pipeline Pattern）示例

管道模式是一种高效利用CLI进行自动化决策和执行的方式，尤其适合处理复杂的执行路径或条件判断。

# 【管道模式示例：自动选择并复用最佳上下文】
# 假设任务：为一个产品 `my-product` 自动生成对应的配置文件和部署脚本

# 1. 搜索可能的自动化技能
export CANDIDATE_ID=$(chub search "auto deploy configuration" --json | jq -r '.results[] | select(.source == "maintainer" or .source == "official") | .id' | head -1)

# 2. 验证技能是否存在，并且是否能够提供适合当前环境变量的配置
if [ -n "$CANDIDATE_ID" ]; then
  echo "Found candidate skill: $CANDIDATE_ID"
  # 3. 自动提取环境变量模板（如果存在）
  chub get "$CANDIDATE_ID" --file .env-sample 2>/dev/null > .env.template
  if [ -s .env.template ]; then
    echo "Environment template extracted. Please fill in values."
    # 这里可以加入自动填充或生成占位的逻辑
  fi
  # 4. 获取技能主文件，开始执行详细步骤
  chub get "$CANDIDATE_ID" -o ./deploy-guide.md
  echo "Deployment guide saved as deploy-guide.md"
else
  echo "No suitable skill found. Falling back to generic guide."
fi

管道模式充分利用了JSON输出和分析工具（如 jq, yq）的能力，将 chub 从一个交互式工具转变为一个强大的、可编程的文档自动化引擎。

8.3 注解（Annotation）最佳实践

chub annotate 是知识沉淀的关键。请遵循以下原则，确保注解的价值最大化：

示例**：

# 为 stripe/webhooks 添加一条实战经验
chub annotate stripe/webhooks "在我司部署环境中，由于负载均衡器添加了额外头部，签名验证代码需要修改为从 X-Forwarded-... 头部读取原始签名，而非标准的 Stripe-Signature。"

8.4 反馈（Feedback）系统最佳实践

chub feedback 是内容质量改进的反馈渠道。提供具体、有标签的反馈能极大帮助维护者。

# 提交积极反馈
chub feedback stripe/api up --label "accurate" --label "well-structured" --comment "The examples matched our production use case exactly."

# 提交具体问题的向下反馈
chub feedback landingai/sdk down --label "outdated" --comment "The code snippet still refers to the deprecated 'analyze' function. It should be 'process' in v2.3.0+."

可用标签：accurate, well-structured, helpful, good-examples, outdated, inaccurate, incomplete, wrong-examples, wrong-version, poorly-structured。

9. 版本管理原则与 versions 字段指南

Context Hub的核心挑战之一是同步知识和软件系统的版本演进。以下原则至关重要：

通过严格的版本字段管理，Context Hub能够为AI提供“版本感知”的上下文，确保生成的代码精确匹配开发环境中实际安装的库版本。

10. 部署与应用场景

10.1 企业级部署模式

对于需要规模化使用Context Hub的团队，建议采用以下部署模式：

1. SEARCH（检索）：当AI接收到一个涉及外部API、库或框架的任务请求时，触发内置工具链或规则，自动执行搜索以寻找相关条目。
   • 目标：找到最相关的 id 和 name。
   • 内部执行：例如，chub_search("stripe create customer")。
2. FETCH（获取）：根据搜索结果，自动触发（或在用户确认后）获取最可能相关的条目内容。
   • 目标：将最新的、结构化的知识加载到当前会话上下文中。
   • 内部执行：例如，chub_get("stripe/customers", lang="python")。
3. USE（使用）：AI基于刚刚获取的上下文，生成代码、设计方案或回答技术问题。这确保了答案与最新的官方规范匹配。
   • 目标：输出在API、参数、版本上完全准确的解决方案。
4. ANNOTATE（标注）：在此过程中，如果AI或开发者发现了文档中未明确提及但至关重要的“实战经验”（例如环境特定配置、版本迁移的隐藏变更、部署的特殊验证步骤），AI可以主动或由开发者手动调用标注功能，将其记录下来。
   • 目标：将“隐性知识”转化为“显性知识”，供未来复用。
   • 内部执行：例如，chub_annotate("stripe/webhooks", "验证签名时必须使用原始请求体（rawBody），而非解析后的JSON对象。")。
5. NEXT SESSION（复用）：在未来任何会话中，当AI或开发者再次获取同一文档时，之前添加的所有标注会自动附加在文档内容之后显示，成为该文档的有机补充。
   • 目标：实现跨时间和跨成员的“知识积累效应”，避免重复踩坑。
   • 清晰解答核心问题（Golden Rule）：在每篇文档（Doc）和技能（Skill）的开头，用一两句简洁的“黄金法则”点明其最核心的用途、最重要的使用前提或最关键的避免事项。
   • 最小可运行示例先行：紧随黄金法则，立即提供一个能复制粘贴并直接运行的最精简代码块，让AI和开发者能第一时间看到“它看起来如何工作”。
   • 结构化与列表化：使用Markdown的标题、列表、表格等，将信息分解为易处理的小块。回答特定场景的操作流程时，使用有序列表。
   • 显式化陷阱和警告：创建独立的“陷阱与警告”或“不要这样做”（Anti-Patterns）章节，明确指出最常见的错误用法及其后果。这是AI最容易忽略但最致命的部分。
   • 拥抱版本管理：在文档中使用显式声明版本号，说明不同版本间的关键变更。版本迁移的注意事项非常重要。通过 versions 字段保持精确，并在SKILL中可能需要为不同版本创建独立的步骤。
   • 自然语言与比喻先行：避免用更复杂的术语解释一个术语。尝试从使用场景和高层目的开始描述，然后逐步深入技术细节。
   • 只记录“不在文档中”的内容：切勿重复文档中已有的信息。注解的核心是捕捉隐性知识。
     • 好示例："生产环境中，此API的请求超时时间需要从默认的10秒调整为30秒，因为后台批量处理较慢。"
     • 坏示例："此API用于创建客户。"（这是文档中已有的内容）
   • 关注环境、配置、版本特例：任何依赖于特定部署环境、公司内部网络、特殊配置或特定包版本的行为差异都应被记录。
   • 记录错误处理模式：文档可能只告诉你如何成功调用，但注解应该记录你在实践中遇到的错误类型、频率以及最有效的恢复策略（如指数退避重试）。
   • 保持简洁和可操作：注解应该是简洁的提醒，而非长篇论文。一条注解聚焦于一个具体的点，并使用清晰的指令性语言。
   1. versions 字段引用的是“包/SDK版本”：在 metadata.versions 中填写的版本号，必须是该库在包管理器（如 npm, PyPI, Go modules）中发布的版本号。这是AI Agent能够从项目的依赖管理器（如 package.json, requirements.txt, go.mod）中检测到的版本。
   2. 区分“包版本”与“API版本”：许多服务有双重版本体系（如OpenAI SDK版本 4.x 对应 2024-12-18 API版本）。versions 字段应使用SDK/库版本。API版本应在文档正文中明确说明，但不在 versions 中列出。
   3. 如何管理破坏性变更的API版本：如果两个API版本（如v1和v2）在接口上完全不兼容，最佳实践是创建两个独立的Doc条目。例如：
      • stripe/docs/payments-v1/python/DOC.md -> name: payments-v1, versions: "~9.0"
      • stripe/docs/payments-v2/python/DOC.md -> name: payments-v2, versions: "~10.0"这样它们在 registry.json 中有独立的ID，AI可以明确区分并请求正确的版本。
   4. recommendedVersion 自动生成：在 registry.json 中，对于Doc条目，系统会自动取 versions 数组中的最高（按照语义化版本排序）版本号作为 recommendedVersion。在未指定 --version 的情况下，chub get 或AI Agent会默认拉取此推荐版本。
   5. 版本发布流程：当新的SDK版本发布时，应及时：1) 创建或更新对应的 Doc.md/Skill.md 文件；2) 在 metadata.versions 中添加新版本号；3) 务必递增 metadata.revision；4) 更新 metadata.updated-on；5) 重新执行 chub build 并部署更新后的 dist/。

   此模式确保了知识的一致性、更新的及时性和访问的安全性。

   10.2 典型应用场景总结

   场景	核心价值	行动
   开源项目维护者	确保全球开发者的AI助手使用你的最新API文档	为你的项目创建CHUB格式的官方文档，发布到社区源，或提供独立的构建产物。
   企业/私有SaaS公司	统一内部开发流程，减少API误用，加速新人融入	为所有内部API、SDK和微服务接口构建私有CHUB知识库。通过CI/CD同步知识更新，并在全公司推广使用CHUB集成的AI助手。
   跨团队/部门开发	打破知识孤岛，促进最佳实践共享	每个团队贡献其擅长的工具、框架的使用技能（Skill）到共享的内部CHUB源。例如，基础设施团队贡献 aws/deploy-lambda，数据团队贡献 pandas/data-cleaning。
   大型单体应用重构	在分拆微服务期间保持上下文的精确性	为即将废弃的旧模块和即将上线的新服务分别构建Doc/Skill，确保重构期间的开发者（及AI）能同时获得新旧两套系统的准确信息，避免混淆。
   快速项目启动	为新项目快速构建标准化的开发环境和工作流	搜索并获取现成的 project-setup、dockerize-app、ci-cd-pipeline 等技能，快速复制最佳实践，而非从零开始。
   教学设计与企业培训	提供结构化、可互动、版本可控的学习材料	将内部技术栈的学习路径编写成一系列的Skill（如 java-bootcamp/lesson-1），受训者可以按步骤获取和练习，AI可以基于此进行辅导。

   11. 快速启动检查清单

   12. 总结：Context Hub 作为上下文工程的基础设施

   Context Hub 不仅仅是一个文档搜索工具或MCP服务器。它从根本上重新定义了人机协作（Human-AI Collaboration）中知识供给的方式。通过将文档从静态的、不可预测的背景信息资源，转变为动态的、可编程的、可版本控制的上下文基础设施，它实现了以下范式转变：

   对于追求高质量软件开发、重视开发效率与安全性、并希望充分利用AI编程潜力的团队而言，投资于Context Hub的构建与普及，不仅是采用一个工具，更是对“上下文工程”这一新兴学科的早期实践。它代表着一种面向未来软件开发范式的战略准备——一个AI原生协作的知识基础设施。

   1. 中央知识库构建与托管：
      • 维护一个内部Git仓库，用于存放所有内部Doc、Skill的源Markdown文件。
      • 在CI/CD流水线中（如GitLab CI, GitHub Actions），配置一个“构建作业”。当文档发生变更（merge到main分支）时，自动触发 chub build。
      • 将构建产物（dist/目录）自动打包，并部署到公司内部的静态文件服务器、CDN或对象存储（如S3桶）。
      • 确保该部署端点有固定的访问URL，例如 https://internal-docs.mycompany.com/chub/v1/。
   2. 分发配置文件：
      • 在团队内部，分发标准的 config.yaml 模板或通过脚本自动生成，其中 sources 部分包含指向中央知识库URL的条目，并设置较高的 priority。
      • 通过此方式，全公司的开发者共享同一份权威、最新的内部API知识。
   3. AI助手集成标准化：
      • 生成统一的IDE配置指南或脚本，指导团队成员如何在其Cursor、Claude Desktop等工具中配置指向 chub-mcp 服务器的连接。
      • 甚至可以将配置好的MCP服务器作为一个Docker镜像或安装包进行分发。
      1. 安装：npm install -g @aisuite/chub。
      2. 验证：运行 chub --version 和 chub --help，确认安装成功。
      3. 初体验：尝试 chub search "python" --limit 5 查看社区内容，然后 chub get openai/chat --lang python 获取一个示例文档。
      4. 规划私有文档：确定一个要文档化的内部包名 (package-name)，如 mycompany-auth-service。
      5. 编写首个Doc/Skill：遵循目录结构和frontmatter规范，创建第一个 DOC.md 或 SKILL.md。
      6. 本地构建与验证：在内容目录执行 chub build ./content --validate-only，检查后 chub build ./content。
      7. 配置本地源：编辑 ~/.chub/config.yaml，添加一个指向 ./content/dist/ 的新 source，命名为 my-local，并设置 priority: 100。
      8. 测试私有内容：运行 chub update --source my-local 然后 chub search --source my-local 和 chub get mycompany-auth-service/...。
      9. 集成AI助手：启动 chub-mcp 服务器，并配置您使用的AI编程助手（如Cursor）连接到该MCP服务器。
      10. 测试协作流：向AI提出一个直接基于您内部文档的问题（例如：“如何调用我们内部mycompany-auth-service的/token接口？”），观察AI是否自动触发 chub_search 和 chub_get 来获取您的新内容。
      • 从记忆依赖到上下文依赖：AI不再（也不应）依赖其静态的训练记忆来生成代码，而是依赖一个由用户控制的、实时的、精准的上下文管道。
      • 从临时粘贴到系统供给：开发者无需在每次对话中手动粘贴相关文档，而是通过一个标准化的系统自动地、按需地获取最佳上下文。
      • 从个人经验到组织知识：通过标注和反馈系统，个人在项目中的踩坑经验和最佳实践得以沉淀、共享和复用，形成组织级的“集体智力”。
      • 从公开通用到私有定制：BYOD哲学首次实现了“自带文档”的大规模实践，让任何拥有私有代码库和复杂内部工具链的团队，都能为自己量身打造专属的AI上下文环境。