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

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

【免费下载链接】spec-kit💫 Toolkit to help you get started with Spec-Driven Development项目地址: https://gitcode.com/GitHub_Trending/sp/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 的文档字符串中有明确说明。

新增内置集成的六步清单

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

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

新增社区集成的前置条件

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

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

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>格式），用于后续比对描述文件是否变更。

提交到社区目录的流程

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

版本更新

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

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

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

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

哈希比对—— manifest 记录所有已安装文件的 SHA-256 哈希；
修改文件检测—— 自安装以来被修改的文件会被标记；
安全默认—— 只要有任何已安装文件被修改，升级即被阻断；
强制重装—— 传入--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是用户覆盖本地修改的唯一途径。