Spec Kit 集成目录开发指南：从内置集成到社区目录的完整贡献流程

本篇基于 Spec Kit 仓库的 集成目录贡献指南，系统讲解如何将 AI Agent 集成（如 Copilot、Claude Code、Gemini CLI 等）贡献到 Spec Kit 的内置目录或社区目录。读完本文，你将掌握两类集成各自的落地清单、catalog.json 目录条目格式、integration.yml 描述文件的字段规范与校验规则，以及 specify integration upgrade 的 diff 感知升级机制在源码中的实际实现。

集成生态的两种形态：内置集成与社区集成

Spec Kit 通过 specify integration 子命令族将 Spec-Driven 开发的命令模板分发到不同 AI 助手。贡献指南明确区分了两条路径（见 integrations/CONTRIBUTING.md）：

• 内置集成（Built-In）：由 Spec Kit 核心团队维护，随 CLI 一起发布，用户开箱即装；
• 社区集成（Community）：由外部开发者贡献，登记在 integrations/catalog.community.json 中供发现，用户从集成自身的源仓库安装。

从源码结构看，内置集成全部注册在 INTEGRATION_REGISTRY 这个全局字典中。_register() 函数在注册时做了两道防线：空 key 抛 ValueError、重复 key 抛 KeyError（注册实现）。_register_builtins() 目前按字母序导入了 39 个集成模块并逐一注册，覆盖 agy、claude、copilot、gemini、cursor_agent、kiro_cli 等主流工具。

一个值得注意的命名约定：用户面向的集成 key 保留连字符（如 cursor-agent、kiro-cli，与实际 CLI 工具/二进制名一致），而包目录必须使用 Python 合法的包名——即连字符替换为下划线（cursor-agent → cursor_agent/，kiro-cli → kiro_cli/）。该约定在 init.py 的文档字符串 中有明确说明。

新增内置集成的六步清单

贡献指南给出的内置集成落地清单如下，每一步都能在当前仓库中找到对应落点：

1. 创建集成的子包：位于 src/specify_cli/integrations/<package_dir>/。<package_dir> 在无连字符时与集成 key 一致（如 gemini），有连字符时将连字符替换为下划线（如 key cursor-agent → 目录 cursor_agent/）——因为 Python 包名不允许连字符；
2. 实现集成类：继承 MarkdownIntegration、TomlIntegration 或 SkillsIntegration 三者之一；
3. 注册集成：在 src/specify_cli/integrations/__init__.py 中导入并调用 _register(...)；
4. 添加测试：位于 tests/integrations/test_integration_<package_dir>.py（仓库中已有如 test_integration_claude.py、test_integration_gemini.py 等 30 余个同构测试文件可参照）；
5. 添加目录条目：写入 integrations/catalog.json；
6. 更新文档：同步修改 AGENTS.md 与 README.md。

三种基类分别对应哪种安装形态

base.py 的模块文档说明了三种基类的定位：

基类	适用形态	说明
MarkdownIntegration	标准 Markdown 命令格式	最常见情况，子类只需设置三个类属性即可
TomlIntegration	TOML 命令格式	适用于 Gemini、Tabnine 等以 TOML 存储命令的 Agent
SkillsIntegration	以 Agent Skill 形式安装命令	采用 speckit-<name>/SKILL.md 布局

base.py 还定义了 IntegrationOption 数据类，用于声明集成接受的 --integration-options 选项（如 --commands-dir、布尔标志 --skills），包括 is_flag、required、default、help 等字段。此外，base.py 中维护了 _CORE_COMMAND_TEMPLATE_ORDER 常量，规定了核心命令模板（analyze、clarify、constitution、implement、converge、plan、checklist、specify、tasks、taskstoissues）的安装排序——新增内置集成时，其命令安装行为会自动对齐这一顺序。

catalog.json 条目格式

内置目录条目添加在 integrations/catalog.json 顶层 integrations 键下，标准格式如下：

{
  "schema_version": "1.0",
  "integrations": {
    "my-agent": {
      "id": "my-agent",
      "name": "My Agent",
      "version": "1.0.0",
      "description": "Integration for My Agent",
      "author": "spec-kit-core",
      "repository": "https://github.com/github/spec-kit",
      "tags": ["cli"]
    }
  }
}

对照真实仓库中的 catalog.json，各字段取值有明确模式：核心团队维护的条目 author 统一为 spec-kit-core，repository 指向 spec-kit 仓库本体；tags 用于标注集成类别，例如 Claude Code 是 ["cli", "anthropic"]、Cline 是 ["ide"]、Droid 是 ["cli", "skills", "factory"]。顶层还包含 updated_at（ISO 8601 时间戳）与 catalog_url 元数据字段，如 integrations/README.md 的 Schema 一节所列。

新增社区集成的前置条件

社区集成由外部开发者贡献，指南列出了五项前置条件：

1. 可用的集成 —— 已通过 specify integration install 实测；
2. 公开仓库 —— 托管在 GitHub 或同类平台；
3. integration.yml 描述文件 —— 格式有效的描述符（下文详述）；
4. 文档 —— 含使用说明的 README；
5. 开源许可证文件。

integration.yml 描述文件

每个社区集成必须包含 integration.yml，完整示例如下：

schema_version: "1.0"
integration:
  id: "my-agent"
  name: "My Agent"
  version: "1.0.0"
  description: "Integration for My Agent"
  author: "your-name"
  repository: "https://github.com/your-name/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"
  scripts:
    - update-context.sh

描述文件校验规则

字段	规则
schema_version	必须为 "1.0"
integration.id	小写字母数字 + 连字符（^[a-z0-9-]+$）
integration.version	合法 PEP 440 版本（用 packaging.version.Version() 解析）
requires.speckit_version	必填字段；需给出 >=0.6.0 之类的版本约束（当前校验仅检查其存在且非空）
provides	至少包含一个命令或脚本
provides.commands[].name	字符串标识符
provides.commands[].file	指向模板文件的相对路径

这些规则并非纸面约定，而是有真实的源码实现。catalog.py 中的 _validate() 方法 逐条执行上述校验：

• schema_version 不等于 1.0 时抛出 "Unsupported schema version" 错误（L722-L726）；
• integration 下的 id、name、version、description 四个字段缺一不可且必须为字符串（L728-L741）；
• id 不匹配正则 ^[a-z0-9-]+$ 时报 "must be lowercase alphanumeric with hyphens only"（L743-L747）；
• version 通过 pkg_version.Version() 解析，失败即视为非法 PEP 440 版本（L749-L754）；
• requires.speckit_version 缺失或为空字符串直接报错（L761-L768），印证了贡献指南中"当前校验仅检查存在性"的说明；
• provides 中 commands 与 scripts 全空时报 "Integration must provide at least one command or script"（L801-L804）；每个 command 条目必须同时带非空的 name 与 file。

另外，catalog.py 还实现了描述文件内容的 SHA-256 指纹（get_hash 方法 返回 sha256:<hexdigest> 格式），用于后续比对描述文件是否变更。

提交到社区目录的流程

1. Fork spec-kit 仓库；
2. 在 integrations/catalog.community.json 的 integrations 键下添加你的条目（格式与内置目录一致，author 填个人/组织名，repository 指向你的集成仓库）；
3. 提交 Pull Request，内容需包含：你的目录条目、集成仓库链接、以及 integration.yml 有效性确认。

版本更新

当你需要更新集成版本时：

1. 发布集成的新版本；
2. 提交 PR 更新 catalog.community.json 中对应条目的 version 字段；
3. 保证向后兼容，或明确记录破坏性变更。

Upgrade 工作流：diff 感知升级的源码剖析

贡献指南的最后一节描述了 specify integration upgrade 的四个机制：

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

# 升级当前集成（若文件被修改则阻断）
specify integration upgrade

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

源码层面的对应实现非常清晰。哈希基础设施位于 manifest.py：模块文档明确指出"卸载时只删除哈希仍匹配的文件"，IntegrationManifest 内部维护 rel_path → sha256 hex 的映射（L129），安装时逐个记录文件内容哈希（L162），check_modified() 则对每个已记录文件重新计算 SHA-256 并与期望值比对（L300-L313）。

CLI 命令本体是 _migrate_commands.py 中的 integration_upgrade。其执行链为：

• 解析目标 key：参数缺省时取当前已安装集成；未安装或 key 不在已安装列表中则直接报错退出（L604-L617）；
• 从 .specify/integrations/<key>.manifest.json 加载 manifest，manifest 不存在时提示改为执行 specify integration install <key>（L619-L623）；
• 调用 old_manifest.check_modified() 检测修改文件；若存在修改且未传 --force，逐行列出被修改文件并提示"Use --force to overwrite modified files, or resolve manually"，然后以非零码退出（L631-L638）；
• 未阻断时继续按脚本类型（--script sh/ps/py）与 --integration-options 重建安装参数完成重装。

同文件的 uninstall 命令也复用了同一套哈希保护逻辑——默认保留被修改的文件，仅在 --force 下才删除它们（_install_commands.py L220-L326），即"安全默认"策略贯穿了安装、升级、卸载的完整生命周期。

贡献前检查清单

综合本文各节，提交集成 PR 前可以按以下顺序自检：

• 内置集成：子包目录名与 key 的连字符/下划线转换正确；集成类继承了三种基类之一且三个类属性已设置；_register 调用已加入 __init__.py；tests/integrations/ 下存在同构测试；catalog.json 条目字段齐全（id/name/version/description/author/repository/tags）；AGENTS.md 与 README.md 已同步更新。
• 社区集成：集成可通过 specify integration install 实测；integration.yml 能通过 catalog.py 的校验逻辑（schema_version 为 "1.0"、id 符合 ^[a-z0-9-]+$、version 符合 PEP 440、requires.speckit_version 非空、provides 至少含一个命令或脚本）；catalog.community.json 条目已添加；README 与许可证齐备。
• 版本更新：确认新版本向后兼容，或在 PR 中明确记录破坏性变更，并知晓 upgrade --force 是用户覆盖本地修改的唯一途径。

以上流程均基于当前仓库的实际代码与文档，适用前提是使用支持 specify integration 命令族的 Spec Kit CLI 版本；目录 Schema 当前固定为 schema_version "1.0"。