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 命令格式最常见情况子类只需设置三个类属性即可TomlIntegrationTOML 命令格式适用于 Gemini、Tabnine 等以 TOML 存储命令的 AgentSkillsIntegration以 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-corerepository指向 spec-kit 仓库本体tags用于标注集成类别例如 Claude Code 是[cli, anthropic]、Cline 是[ide]、Droid 是[cli, skills, factory]。顶层还包含updated_atISO 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.0integration.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-L726integration下的id、name、version、description四个字段缺一不可且必须为字符串L728-L741id不匹配正则^[a-z0-9-]$时报 must be lowercase alphanumeric with hyphens onlyL743-L747version通过pkg_version.Version()解析失败即视为非法 PEP 440 版本L749-L754requires.speckit_version缺失或为空字符串直接报错L761-L768印证了贡献指南中当前校验仅检查存在性的说明provides中commands与scripts全空时报 Integration must provide at least one command or scriptL801-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安装时逐个记录文件内容哈希L162check_modified()则对每个已记录文件重新计算 SHA-256 并与期望值比对L300-L313。CLI 命令本体是 _migrate_commands.py 中的integration_upgrade。其执行链为解析目标 key参数缺省时取当前已安装集成未安装或 key 不在已安装列表中则直接报错退出L604-L617从.specify/integrations/key.manifest.json加载 manifestmanifest 不存在时提示改为执行specify integration install keyL619-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__.pytests/integrations/下存在同构测试catalog.json 条目字段齐全id/name/version/description/author/repository/tagsAGENTS.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。【免费下载链接】spec-kit Toolkit to help you get started with Spec-Driven Development项目地址: https://gitcode.com/GitHub_Trending/sp/spec-kit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
