Spec Kit 集成目录（Integration Catalog）详解：发现、配置与管理 AI 智能体集成的完整机制

Spec Kit 通过集成目录（Integration Catalog）体系实现了 AI 编码智能体集成的统一发现、版本管理与分发。本篇以 integrations/README.md 为主体，结合 集成目录实现源码 与配套贡献指南 CONTRIBUTING.md，完整讲解目录文件的组织结构、配置解析优先级、描述符 integration.yml 的校验规则，以及 specify integration 系列命令的底层工作流程——读完后你可以独立配置私有目录源、解析目录栈行为，并为社区目录提交新的集成条目。

1. 集成目录是什么：两级目录文件结构

Spec Kit 的集成目录是一个可发现的注册表系统，用于让 specify CLI 找到可以安装到项目中的 AI 智能体集成（如 Claude Code、GitHub Copilot、Gemini CLI 等）。目录体系由两个 JSON 文件构成：

文件	定位	说明
catalog.json	内置目录（Built-In Catalog）	由 Spec Kit 核心团队维护、随 CLI 一起分发的集成，始终可安装
catalog.community.json	社区目录（Community Catalog）	社区贡献的集成，仅用于发现（discovery only）——用户需从源仓库自行安装

当前内置目录包含 38 个集成条目（schema_version: "1.0"，updated_at: "2026-08-26T00:00:00Z"），覆盖 CLI 型（如 claude、gemini、codex、droid）、IDE 型（如 copilot、cline、kilocode、zed）、skills 型（如 kimi、hermes、zcode）以及一个特殊的 generic 条目——后者支持"自带智能体"（bring your own agent），通过 --integration-options="--commands-dir <dir>" 将命令输出到任意目录（见 docs/reference/integrations.md）。一个典型的目录条目如下（摘自 catalog.json）：

"claude": {
  "id": "claude",
  "name": "Claude Code",
  "version": "1.0.0",
  "description": "Anthropic Claude Code CLI integration",
  "author": "spec-kit-core",
  "repository": "https://github.com/github/spec-kit",
  "tags": ["cli", "anthropic"]
}

社区目录当前 integrations 为空对象（"updated_at": "2026-04-08T00:00:00Z"），等待社区通过 PR 提交条目。

2. 目录栈的解析顺序：环境变量、项目配置、用户配置与内置默认值

这是集成目录设计的核心。目录栈按以下优先级顺序解析，首个匹配即生效（first match wins）：

1. 环境变量 — SPECKIT_INTEGRATION_CATALOG_URL 以单个 URL 覆盖所有目录
2. 项目配置 — 项目根目录下的 .specify/integration-catalogs.yml
3. 用户配置 — 用户主目录下的 ~/.specify/integration-catalogs.yml
4. 内置默认值 — catalog.json + catalog.community.json

integration-catalogs.yml 的完整格式：

catalogs:
  - url: "https://example.com/my-catalog.json"
    name: "my-catalog"
    priority: 1
    install_allowed: true

这一行为可以在源码中得到逐条印证。IntegrationCatalog.get_active_catalogs() 的解析逻辑与文档完全一致：

• 环境变量非空时，先调用 _validate_catalog_url() 校验，然后构造单个 IntegrationCatalogEntry(url=env_value, name="custom", priority=1, install_allowed=True) 直接返回，完全绕过项目/用户配置文件；
• 若环境变量指向的是非默认目录 URL，源码会向 stderr 打印一次性警告 "Warning: Using non-default integration catalog. Only use catalogs from sources you trust."——即信任提醒；
• 无任何配置时，返回两个内置条目：default（指向内置 catalog.json，priority 1，install_allowed=True）与 community（指向 catalog.community.json，priority 2，install_allowed=False）。注意社区目录在源码层面就被标记为"仅发现、不可安装"，这与 README 中 "Listed for discovery only" 的表述互为印证。

2.1 URL 安全校验：强制 HTTPS，仅允许本地例外

目录 URL 的校验逻辑位于共享基类 CatalogStackBase._validate_catalog_url()。从源码看，规则相当严格：

• 必须使用 HTTPS；http 仅在主机为 localhost、127.0.0.1 或 [::1] 时放行（便于本地测试）；
• 显式访问 parsed.port 以触发端口语法/范围校验，畸形端口会抛出 Catalog URL is malformed 而不是延迟到抓取时才失败；
• 检查 hostname 而非 netloc——因为 https://:8080 这类无主机 URL 的 netloc 为非空字符串，会绕过主机保证。

另外，_load_catalog_config() 对已存在的配置文件采取 fail-closed 策略：文件不存在返回 None（从而继续向下解析），但文件已存在却格式错误、为空或没有可用 URL 时直接抛错，而不是静默忽略。

3. CLI 命令：从列装、搜索到目录源管理

README 给出的核心命令序列如下，均可直接复制运行（install/upgrade 需要在已初始化的 Spec Kit 项目内执行）：

# 列装内置集成（默认）
specify integration list

# 浏览完整目录（内置 + 社区）
specify integration list --catalog

# 安装一个集成
specify integration install copilot

# 升级当前集成（diff-aware，感知本地修改）
specify integration upgrade

# 强制升级（覆盖已修改的文件）
specify integration upgrade --force

围绕这些命令，源码中还有几处值得了解的细节：

• install 的完整参数：integration_install() 除了集成 key，还接受 --script（脚本类型 sh/ps/py，默认取自 init-options 或平台默认）、--force（允许在多集成共存未声明安全时强制多装）以及 --integration-options（如 --integration-options="--commands-dir .myagent/cmds"，用于 generic 集成）。安装前会检查 key 是否已装：已装时给出 use/upgrade 的建议并直接退出。
• upgrade 的 diff-aware 机制：integration_upgrade() 通过对比 .specify/integrations/{key}.manifest.json 中记录的 SHA-256 哈希检测本地修改过的文件；有修改时默认阻止升级，加 --force 才会覆盖。manifest 不存在时提示先执行全新 install。
• 目录浏览命令：search（支持自由查询词、--tag、--author 过滤）、info（查看单个集成的完整元数据）、status（含 --json 机器可读输出）、use（切换默认集成）。命令处理器见 integration_search()。
• 目录源管理子命令：specify integration catalog list（列出当前生效的目录源）、catalog add <url> [--name ...]（写入项目级 .specify/integration-catalogs.yml）、catalog remove <index>（按 0 基索引删除）。integration_catalog_add() 的参数帮助明确复述了 HTTPS 限制。

源码中有一段注释值得引用（_query_commands.py）：集成命令刻意不提供 add/remove/enable/disable 之类的增删开关，因为集成是"单一激活"模型（install / uninstall / switch），不同于 extensions 与 presets 的叠加式管理。

4. 集成描述符 integration.yml：元数据、依赖与提供物

每个（尤其是社区）集成应包含一个 integration.yml 描述符，声明其元数据、运行要求与提供的命令/脚本。README 给出的完整示例：

schema_version: "1.0"
integration:
  id: "my-agent"
  name: "My Agent"
  version: "1.0.0"
  description: "Integration for My Agent"
  author: "my-org"
  repository: "https://github.com/my-org/speckit-my-agent"
  license: "MIT"
requires:
  speckit_version: ">=0.6.0"
  tools:
    - name: "my-agent"
      version: ">=1.0.0"
      required: true
provides:
  commands:
    - name: "speckit.specify"
      file: "templates/speckit.specify.md"
    - name: "speckit.plan"
      file: "templates/speckit.plan.md"
  scripts:
    - update-context.sh
    - update-context.ps1

4.1 描述符的校验规则（源码级）

IntegrationDescriptor 类在加载描述符时会执行严格校验，REQUIRED_TOP_LEVEL = ["schema_version", "integration", "requires", "provides"]。对照 CONTRIBUTING.md 中的校验规则表，源码实现还包括若干文档未逐条列出的硬约束：

字段	规则
schema_version	必须精确等于 "1.0"（SCHEMA_VERSION 常量）
integration.id	正则 ^[a-z0-9-]+$：仅小写字母、数字与连字符
integration.name / version / description	必须存在且为字符串
integration.version	合法 PEP 440 版本（用 packaging.version.Version() 解析，如 1.0.0、1.0.0a1）
requires.speckit_version	必填，非空字符串（当前校验只检查存在性）
requires.tools[]	每个条目的 name 必须是非空字符串
provides	至少提供一个 command 或 script
provides.commands[].file	相对路径，禁止绝对路径、禁止 .. 路径穿越、禁止盘符/锚点
provides.scripts[]	非空字符串，同样禁止绝对路径与 ..

空文档处理也经过精细设计：_load() 区分"真正的空文档"与显式 null/[]/false 等形状——只有真空文档会被归一化为空映射后报缺字段错，其余伪形状原样进入 _validate 以报出"描述符形状错误"，避免静默吞掉畸形文件。描述符还提供 get_hash() 返回整个文件的 sha256: 摘要，供升级/校验流程使用。

5. 目录 JSON Schema：必填字段与条目字段

两个目录文件遵循同一 JSON schema：

{
  "schema_version": "1.0",
  "updated_at": "2026-04-08T00:00:00Z",
  "catalog_url": "https://...",
  "integrations": {
    "my-agent": {
      "id": "my-agent",
      "name": "My Agent",
      "version": "1.0.0",
      "description": "Integration for My Agent",
      "author": "my-org",
      "repository": "https://github.com/my-org/speckit-my-agent",
      "tags": ["cli"]
    }
  }
}

必填字段：

字段	类型	说明
schema_version	string	必须为 "1.0"
updated_at	string	ISO 8601 时间戳
integrations	object	集成 ID → 元数据的映射

集成条目字段：

字段	类型	必填	说明
id	string	是	唯一 ID（小写字母数字 + 连字符）
name	string	是	人类可读的显示名
version	string	是	PEP 440 版本（如 1.0.0、1.0.0a1）
description	string	是	一行描述
author	string	否	作者名或组织
repository	string	否	源仓库 URL
tags	array	否	可检索标签（如 ["cli", "ide"]）

从源码看，这份 schema 在运行时由 _catalog_shape_error() 强制：payload 必须是 JSON 对象，同时携带 schema_version 键和 integrations 映射（且 integrations 必须仍是对象）。该校验器被新鲜抓取与缓存读取两条路径共用——注释明确解释这是为了防止两条路径校验规则漂移，让被污染或旧格式的缓存载荷无法绕过格式契约。

6. 抓取、缓存与合并：目录栈的运行时机制

理解了"解析顺序"之后，IntegrationCatalog 的抓取与合并逻辑回答了"多个目录源同时在线时会发生什么"：

• 逐 URL 缓存：_fetch_single_catalog() 以 URL 的 SHA-256 前 16 位命名缓存文件，存放在项目级 .specify/integrations/.cache/，缓存有效期 CACHE_DURATION = 3600（1 小时）。缓存读取前同样过 _catalog_shape_error() 校验，损坏或形状异常的缓存会被删除并重新抓取。
• 下载安全约束：响应体经 read_response_limited() 限制大小（MAX_JSON_METADATA_BYTES），非 UTF-8 响应会转换为 IntegrationCatalogError 而不是让原始 UnicodeDecodeError 逃逸；重定向后还会对最终 URL 再跑一次 _validate_catalog_url()，防止 HTTPS 请求被 302 到不安全的地址。
• 合并规则：_get_merged_integrations() 按 get_active_catalogs() 返回的顺序遍历各目录，同一集成 ID 以先出现者（低 priority 数值）胜出；每个条目会被注入两个内部字段 _catalog_name（来自哪个目录源）与 _install_allowed（该源是否允许安装）。单个目录抓取失败只打印警告并跳过；所有目录都失败才抛出 "Failed to fetch any integration catalog"。
• 搜索实现：search() 将 name + description + id + tags 拼成小写搜索域做子串匹配；--tag 为大小写不敏感的标签成员判断；--author 为大小写不敏感的精确相等。
• 目录源增删：add_catalog() 对既有条目逐条重新校验（URL 合法性、priority 必须为整数且拒绝布尔值），新条目 priority 自动取 max(既有) + 1 并默认 install_allowed=True；remove_catalog() 按 catalog list 的显示顺序（priority 升序、缺省为 YAML 下标 +1）映射 0 基索引，删除最后一条时会直接删除配置文件本身，避免留下空 catalogs: 列表导致后续所有 integration 命令失败。

这套机制与 bundler 侧的通用目录栈 CatalogStack 共享同一"priority 排序 + 安装策略"模型，说明 Spec Kit 将目录栈作为跨 integrations / extensions / presets / workflows 的公共基础设施来设计。

7. 贡献指南：添加内置集成与社区集成

CONTRIBUTING.md 定义了成为目录成员的两条路径。

7.1 添加内置集成（随 CLI 分发）

内置集成由核心团队维护，检查清单为：

1. 在 src/specify_cli/integrations/<package_dir>/ 下创建集成子包——key 无连字符时包名即 key（如 gemini），含连字符时用下划线（key cursor-agent → 目录 cursor_agent/，因为 Python 包名不允许连字符）；
2. 实现继承自 MarkdownIntegration、TomlIntegration 或 SkillsIntegration 的集成类（三种基类分别对应 Markdown、TOML 与 skills 布局，见 base.py 的模块文档：MarkdownIntegration 是绝大多数集成走的标准路径，子类只需设置三个类属性；SkillsIntegration 则以 speckit-<name>/SKILL.md 布局安装命令）；
3. 在 src/specify_cli/integrations/init.py 中注册；
4. 在 tests/integrations/test_integration_<package_dir>.py 添加测试（例如 tests/integrations/test_integration_claude.py 对应 claude）；
5. 在 integrations/catalog.json 的顶层 integrations 键下添加条目（格式见上文第 5 节 schema）；
6. 更新 AGENTS.md 与 README.md 文档。

7.2 添加社区集成（仅发现）

社区集成需满足五项前置条件：可工作的集成（经 specify integration install 测试通过）、公开仓库、合法的 integration.yml 描述符、README 使用文档、开源许可。提交流程为：Fork 仓库 → 在 catalog.community.json 的 integrations 键下添加条目 → 提交 PR（附条目、集成仓库链接、integration.yml 合法性确认）。版本更新时，需发布新版本、PR 修改 version 字段，并保证向后兼容或记录破坏性变更。

7.3 diff-aware 升级工作流

社区与内置集成共用同一套升级语义（specify integration upgrade）：

1. 哈希对比 — manifest 记录所有已安装文件的 SHA-256 哈希；
2. 修改检测 — 自安装以来发生变化的文件被标记；
3. 安全默认 — 只要有任何已安装文件被修改，升级即被阻止；
4. 强制重装 — 传入 --force 才会以最新版本覆盖已修改文件。

# 升级当前集成（文件有修改时阻止）
specify integration upgrade

# 强制升级（覆盖已修改文件）
specify integration upgrade --force

8. 小结

Spec Kit 的集成目录把"发现—信任—安装"三个环节拆成了清晰的层次：catalog.json/catalog.community.json 定义可发现的内容，integration-catalogs.yml 与环境变量按固定优先级控制"从哪里发现"，install_allowed 标志与 HTTPS-only 的 URL 校验控制"能不能装、可不可信"，而 integration.yml 描述符加上 1 小时缓存、形状校验与 diff-aware 升级则保证了安装过程可审计、可回退。所有行为均可在 src/specify_cli/integrations/ 包与 tests/integrations/ 测试集中找到对应实现，读者可以沿本文给出的文件路径继续深入，例如对照 test_registry.py 理解集成注册的完整性约束。