Spec Kit 集成管理实战：用 specify CLI 管理 40 个 AI 编码代理的完整指南

Spec Kit 集成管理实战：用 specify CLI 管理 40 个 AI 编码代理的完整指南

【免费下载链接】spec-kit💫 Toolkit to help you get started with Spec-Driven Development项目地址: https://gitcode.com/GitHub_Trending/sp/spec-kit

本篇指南围绕 Spec Kit 的集成（Integration）体系展开：Specify CLI 内置了 40 个 AI 编码代理的官方集成，specify init会根据你选择的代理生成对应的命令文件与目录结构，而specify integration子命令族则负责集成在生命周期中的全部操作——安装、卸载、切换默认、升级模板、状态检查、目录（catalog）发现与自定义集成脚手架。读完本文，你将能独立完成多代理项目的集成编排，并理解底层哈希清单（manifest）、多安装安全（multi-install safe）声明与状态文件的工作机制。

内置集成总览：39 个 AI 代理 + generic 逃生舱

Specify CLI 支持范围广泛的 AI 编码代理。运行specify init时，CLI 会为你所选的代理搭建好对应的命令文件和目录结构——无论你偏好哪款工具，都可以立即开始使用规范驱动开发（Spec-Driven Development）。

下表完整继承自官方参考文档 Supported AI Coding Agent Integrations，Key 列是specify integration install <key>使用的标识符：

代理	Key	说明
Alquimia AI	alquimia	Skills 集成；技能安装到.alquimia/skills，以/speckit-<command>调用
Amp	amp
Antigravity (agy)	agy	Skills 集成；技能自动安装
Auggie CLI	auggie
Claude Code	claude	Skills 集成；技能安装到.claude/skills
Cline	cline	基于 IDE 的代理
CodeBuddy CLI	codebuddy
Codex CLI	codex	Skills 集成；技能安装到.agents/skills，以$speckit-<command>调用
Command Code	command-code	Skills 集成；技能安装到.commandcode/skills/，以$speckit-<command>调用
Cursor	cursor-agent
Devin for Terminal	devin	Skills 集成；技能安装到.devin/skills/，以/speckit-<command>调用
Docker Agent	docker-agent	Skills 集成；技能安装到.agents/skills/（与 Codex 和 Zed 共用目录）。需在所选代理 YAML 中启用本地技能（skills: true）并授予文件系统读权限；能识别独立docker-agent二进制或 Docker CLI 插件（docker agent）。用SPECKIT_INTEGRATION_DOCKER_AGENT_EXTRA_ARGS=./agent.yaml配置工作流分派，Spec Kit 提示词会追加在这些参数之后。由于技能目录共享，默认不声明多安装安全
Factory Droid	droid	Skills 集成；技能安装到.factory/skills/，以/speckit-<command>调用
Firebender	firebender	面向 Android Studio / IntelliJ 的 IDE 代理
Forge	forge
Gemini CLI	gemini
GitHub Copilot	copilot	默认 Skills 集成；在.github/skills/下安装speckit-<command>/SKILL.md。传--integration-options="--commands"可改用受支持的 commands 布局：.github/agents/下的.agent.md文件、.github/prompts/下的配套.prompt.md文件，外加一次.vscode/settings.json合并
Goose	goose	使用.goose/recipes/下的 YAML recipe 格式
Grok Build	grok	Skills 集成；技能安装到.grok/skills，以/speckit-<command>调用
Hermes	hermes	Skills 集成；技能全局安装到~/.hermes/skills/
IBM Bob	bob	默认 Skills 集成；技能以speckit-<command>/SKILL.md安装到.bob/skills/，以/speckit-<command>调用。传--integration-options="--legacy-commands"可搭建已弃用的 Bob 1.x 布局（.bob/commands/*.md）；该旗标将在未来版本移除。已有旧布局安装可用specify integration upgrade bob --integration-options="--skills"迁移，该命令会转换为 skills 布局并删除旧命令文件。若安装了 preset 覆盖，迁移会被拒绝并给出可操作错误（preset 产物尚不能在布局切换间协调）——先移除 preset、迁移、再重装
Junie	junie
Kilo Code	kilocode	命令安装到.kilo/commands；旧版.kilocode/workflows安装仍作为注册回退受支持
Kimi Code	kimi	Skills 集成；安装到.kimi-code/skills/。--migrate-legacy可把旧版.kimi/skills/安装迁移到新路径
Kiro CLI	kiro-cli	Kiro CLI 不会在文件型提示词中替换$ARGUMENTS，因此 Spec Kit 在渲染时附带一段散文形式的回退说明。别名：--integration kiro
Lingma	lingma	Skills 集成；技能自动安装
Mistral Vibe	vibe
Oh My Pi	omp	斜杠命令安装到.omp/commands
opencode	opencode
Pi Coding Agent	pi	Pi 默认不带 MCP 支持，因此taskstoissues无法按预期工作；可通过其扩展机制添加 MCP 支持
Qoder CLI	qodercli
Qwen Code	qwen
RovoDev	rovodev	生成.rovodev/skills/、提示词包装与prompts.yml；运行时通过acli rovodev分派
SHAI (OVHcloud)	shai
Tabnine CLI	tabnine
Trae	trae	Skills 集成；技能自动安装
ZCode	zcode	Skills 集成；技能安装到.zcode/skills/，以$speckit-<command>调用
Zed	zed	Skills 集成；技能安装到.agents/skills，以/speckit-<command>调用
Generic	generic	自带代理——对未列出的 AI 编码代理，使用--integration generic --integration-options="--commands-dir <path>"

从源码结构看，这 39 个代理加generic共 40 个内置 key 与 注册表初始化函数 中的_register_builtins()完全对应：每个集成是一个自包含子包（如claude/、cursor_agent/、kiro_cli/），包目录名用 Python 合法标识符，而对外的 key 保留连字符以匹配实际 CLI 工具名（例如kiro-cli、cursor-agent）。

从调用方式上，上表可归为三类：

• 斜杠命令（/speckit.<command>或/speckit-<command>）：多数 Markdown 命令型与 Skills 型代理；
• 美元命令（$speckit-<command>）：如 Codex、Command Code、ZCode；
• 文件型配置：如 Goose 的 YAML recipe、Copilot 的.agent.md/.prompt.md、RovoDev 的prompts.yml。

底层架构：注册表、基类与哈希清单

在讲命令之前，先看清每个集成背后的三层结构，这决定了后文所有命令的行为边界。

集成注册表

INTEGRATION_REGISTRY 是key → IntegrationBase 实例的全局字典，由_register()在导入时填充，key 重复会抛KeyError。specify integration list遍历的就是这张表；search/info则在此之上叠加远端目录查询（见目录管理小节）。

IntegrationBase：每个集成的契约

集成基类IntegrationBase要求每个子类设置三个类属性，并提供一组安装/卸载原语：

• key：唯一标识，需与实际 CLI 工具名一致；
• config：包含folder（代理根目录，如.claude/）、commands_subdir（命令子目录，如skills）、requires_cli（是否必须安装 CLI 工具）等元数据；
• registrar_config：注册时的目标目录、文件格式（markdown/toml/yaml/skills）、参数占位符、文件扩展名；
• 可选multi_install_safe：声明该集成能否与其他集成安全共存（默认False），基类注释 明确要求安全声明方必须使用静态且唯一的代理根目录与命令目录，注册表测试会强制校验这些不变量。

几个关键机制值得展开：

1. 模板渲染管线process_template()：从命令模板 frontmatter 的scripts:块选择脚本变体（sh/ps/py）→ 替换{SCRIPT}→ 删除scripts:段 → 替换{ARGS}/$ARGUMENTS→ 替换__AGENT__→ 重写项目相对路径 → 把__SPECKIT_COMMAND_<NAME>__占位符解析成符合该代理风格的调用串（/speckit.plan或/speckit-plan）。这就是为什么同一份 templates/commands/ 模板能派生出所有代理的本地化命令文件。
2. 非交互分派dispatch_command()：构造斜杠命令提示词后经由build_exec_args()生成 CLI 参数并subprocess执行，支持流式输出（用户可 Ctrl+C）与捕获输出两种模式；SPECKIT_INTEGRATION_<KEY>_EXECUTABLE和SPECKIT_INTEGRATION_<KEY>_EXTRA_ARGS两个环境变量可分别覆盖可执行文件路径与注入额外参数。
3. 文件操作原语：copy_command_to_directory()、record_file_in_manifest()、write_file_and_record()等，全部把写入路径限制在项目根内——安装时还会显式校验目标目录不逃逸项目根。

以 Claude Code 集成 为例，它继承SkillsIntegration，声明folder=".claude/"、commands_subdir="skills"、multi_install_safe = True，还会为每个技能注入argument-hintfrontmatter 并把 Spec Kit 事件映射为 Claude 原生钩子（SessionStart、PreToolUse等写入.claude/settings.json）。

哈希清单（manifest）：卸载与升级的安全网

每个安装过的集成在.specify/integrations/<key>.manifest.json记录一份清单，IntegrationManifest 把每个受管文件映射到其原始内容的SHA-256 哈希。清单读取路径经过严格校验：拒绝绝对路径、..段、符号链接与逃逸项目根的路径，防止恶意或损坏的清单触发越界删除。

卸载时的删除逻辑（manifest.uninstall()）正是官方文档中"未修改文件自动删除、已修改文件保留"这一行为的实现：

• 哈希与记录值一致 → 删除该文件；
• 哈希不一致（你手动改过）→ 跳过并列入skipped报告；
• 文件已变成符号链接或不可读 → 按"被修改"处理，保留；
• 加--force则无条件删除。

此外，清单还支持recovered_files标记：安装时若文件已存在而未被覆盖，其哈希只是"观测"而非"产出"，后续刷新受管文件前必须先检查该标记，避免用观测哈希覆盖用户定制。

核心管理命令

以下命令都需要项目已经通过specify init初始化；要在新项目上指定代理，应使用specify init <project> --integration <key>。

列出可用集成

specify integration list

选项	说明
--catalog	同时浏览目录（内置与社区）。未内置的社区集成只会在这里显示

显示内置集成、当前已安装哪一个、每个集成是否需要 CLI 工具还是 IDE 型。当安装了多个集成时，列表会把默认集成与其他已安装集成分开标注，并显示每个内置集成是否声明多安装安全。

从源码看，list 命令 读取.specify/integration.json中的默认 key 与已安装 key 集合，把每一行渲染为Key / Name / Status / CLI Required / Multi-install Safe五列表格；加--catalog时改为调用IntegrationCatalog.search()拉取合并目录，并对"仅发现不可安装"（discovery-only）条目单独标记。

搜索与查看详情

specify integration search [query]

选项	说明
--tag	按标签过滤
--author	按作者过滤

在活动的目录栈（catalog stack）中搜索匹配集成，不带 query 时列出全部。必须在 Spec Kit 项目内运行。

specify integration info <integration_id>

显示单个集成的目录详情：描述、作者、许可证、标签、来源目录、仓库（如有）以及当前是否激活。同样必须在 Spec Kit 项目内运行。

从 search/info 的实现 可以看出几个实用细节：社区目录的条目被标记install_allowed=False时，输出会注明 "discovery only — not installable"；内置集成即使目录不可达也能离线查看（info会回退到注册表元数据）；目录配置错误与网络错误会给出不同的排障提示（检查.specify/integration-catalogs.yml、~/.specify/integration-catalogs.yml或SPECKIT_INTEGRATION_CATALOG_URL）。

安装集成

specify integration install <key>

选项	说明
--script sh\|ps\|py	脚本类型：sh（bash/zsh）、ps（PowerShell）、py（Python）
--force	显式同意与未声明多安装安全的集成并存安装
--integration-options	集成专属选项（如--integration-options="--commands-dir .myagent/cmds"）

把指定集成安装到当前项目。若已有其他集成安装，仅当所有相关集成都声明多安装安全时才自动继续；否则用switch替换默认集成，或加--force显式同意多安装。安装过程中途失败会自动回滚到干净状态。

安装额外集成不会改变默认集成；用specify integration use <key>修改默认。

版本提示：受控多安装支持自 Spec Kit 0.8.5 引入。若specify integration install <key>提示已有集成安装且只建议switch或uninstall，请用specify version检查本地 CLI 并升级。注意通过uvx --from git+...方式运行的一次性命令只使用临时副本，不会更新你PATH上持久化的specify可执行文件。

安装流程在 install 命令实现 中的关键步骤：

1. key 未注册 → 报错并列出可用 key；已安装 → 提示use/upgrade后直接退出；
2. 多安装安全检查：任一已安装集成或新集成未声明安全 → 拒绝（除非--force），并给出switch替代方案；
3. 先确保共享基础设施（.specify/scripts/等）就位，且共享模板始终对齐当前默认集成的调用风格（分隔符与调用前缀取自默认集成而非新集成）；
4. 构造IntegrationManifest并执行integration.setup(...)，随后manifest.save()、更新.specify/integration.json（追加installed_integrations、写入integration_settings）；
5. 任何异常 → 调teardown(force=True)回滚已写文件、恢复原integration.json状态。

卸载集成

specify integration uninstall [<key>]

选项	说明
--force	即使文件已被修改也删除

卸载当前集成（或指定集成）。Spec Kit 跟踪安装期间创建的每个文件及其原始内容 SHA-256 哈希：

• 未修改的文件自动删除；
• 已修改的文件（你手动编辑过的）会被保留，避免丢失定制；
• 加--force则无论是否修改都删除全部集成文件。

卸载后若被卸载的是默认集成，uninstall 命令 会自动从剩余已安装集成中选出新的默认并刷新共享模板；若清单文件不可读，会打印明确的恢复步骤（删除损坏清单 → 重新 uninstall 清理元数据 → 重新 install 生成）。

切换与指定默认集成

specify integration switch <key>

选项	说明
--script sh\|ps\|py	脚本类型
--force	卸载阶段强制删除已修改文件；目标已安装时则在切换默认的同时覆盖受管共享模板
--refresh-shared-infra	即使你定制过共享基础设施文件也一并覆盖（否则保留定制）
--integration-options	目标集成尚未安装时使用的集成选项

目标集成未安装时，switch等价于一步完成uninstall+install，此时--force控制是否删除被移除集成中已修改的文件；目标已安装时，switch仅改变默认集成（行为同use），此时--force控制切换默认时是否覆盖受管共享模板。对已安装目标传--integration-options会被拒绝——修改集成选项需要重装受管文件，应先用upgrade <key> --integration-options ...，再use <key>。与use一样，switch在目标集成成为默认后会为其重新脚手架已安装的扩展与 preset。

specify integration use <key>

选项	说明
--force	切换默认时覆盖受管共享模板

在不卸载其他已安装集成的情况下设置默认集成，同时刷新受管共享模板，使命令引用匹配新默认集成的调用风格。已修改或未跟踪的共享模板会被保留，除非使用--force。

use也是扩展与 preset 的激活点：它会把所有已启用扩展和 preset 的命令覆盖（skills 型代理还包括技能）为新的活动集成重新注册，使得在其他集成激活期间安装的产物在这里被重新脚手架，而非在安装时。这一点在 use 命令实现 中体现为_set_default_integration_or_exit(...)之后紧跟_register_extensions_for_agent(...)与_register_presets_for_agent(...)。

升级集成

specify integration upgrade [<key>]

选项	说明
--force	即使文件已被修改也覆盖
--script sh\|ps\|py	脚本类型
--integration-options	集成选项

用更新后的模板与命令重装一个已安装集成（例如升级 Spec Kit 之后）。默认作用于默认集成；指定 key 时必须是已安装集成之一。能检测本地已修改的文件，未加--force则阻止升级。上一次安装遗留、本次不再需要的陈旧文件会被自动清理。即使升级非默认集成，共享模板仍与默认集成保持对齐。

已启用的扩展与 preset只在升级当前活动（默认）集成时重新注册；非默认升级仍会刷新该集成的核心命令，但不会重注册其扩展/preset 层——之后use/switch到该集成即可重新脚手架。若升级要在 commands 与 skills 布局之间切换且该集成注册了 preset 产物，升级会在改动任何文件前被拒绝：先移除受影响 preset、执行改布局的升级、再重装 preset。

状态报告

specify integration status specify integration status --json

只报告不改文件。报告内容包括：默认集成、已安装集成、多安装安全性、缺失的受管文件、已修改的受管文件、无效清单路径、共享 Spec Kit 基础设施健康度、未检查的清单，以及默认敏感共享模板的目标集成。--json输出面向 CI 与编码代理，提供稳定的机器可读数据；它还会报告原始记录的集成列表，以及当状态修复启发式与记录文件不一致时被检查的集成清单。

退出码约定：报告状态为ok或warning时退出 0，仅error时退出 1。JSON 输出中，当无法评估任何已安装集成集合时（状态缺失、不可读、无有效记录列表或没有记录任何已安装集成），multi_install_safe为null。

从 status 命令 看，人类可读输出会逐项打印计数并列出带 severity（error/warning）、code 与修复建议（suggestion）的 Findings，方便直接作为修复清单使用。

目录管理（Catalog）

集成目录控制发现命令（search、info）去哪里找集成。目录按优先级顺序检查，首个匹配生效：

1. 环境变量—SPECKIT_INTEGRATION_CATALOG_URL覆盖所有目录
2. 项目配置—.specify/integration-catalogs.yml
3. 用户配置—~/.specify/integration-catalogs.yml
4. 内置默认— 官方目录 + 社区目录

这一顺序在 IntegrationCatalog.get_active_catalogs() 中逐层实现，且内置默认里社区目录被标记为install_allowed=False（仅发现不可安装）。目录内容在.specify/integrations/.cache/按 URL 哈希缓存，缓存有效期 1 小时；缓存读取与新鲜拉取共用同一个形状校验器（必须含schema_version与integrations映射），损坏缓存会被丢弃并重新拉取。

列出目录

specify integration catalog list

显示活动的目录来源。项目级来源（若已配置）可按索引移除；否则活动来源显示为不可移除。设置了SPECKIT_INTEGRATION_CATALOG_URL时，项目/用户配置整体失效，列表会明确提示。

添加目录

specify integration catalog add <url>

选项	说明
--name <name>	目录的可选名称

把自定义目录 URL 加入项目的.specify/integration-catalogs.yml。URL 必须使用 HTTPS（本地测试例外：http://localhost、http://127.0.0.1、http://[::1]）。使用非默认目录时 CLI 会打印一次"仅使用你信任的来源"的警告。

移除目录

specify integration catalog remove <index>

按catalog list中 0 起始的索引移除项目目录来源。

集成专属选项（--integration-options）

部分集成通过--integration-options接受额外选项，底层由IntegrationOption数据类在 基类中声明（名称、是否布尔旗标、是否必填、默认值、帮助文本）：

集成	选项	说明
generic	--commands-dir	必填。命令文件目录
kimi	--migrate-legacy	把旧版.kimi/skills/安装迁移到.kimi-code/skills/（含点号→连字符的技能命名，如speckit.xxx→speckit-xxx）
copilot	--commands	改用.github/agents/*.agent.md命令 +.github/prompts/*.prompt.md配套文件并合并.vscode/settings.json，代替默认 skills 布局
copilot	--skills	强制默认 skills 布局，在显式迁移中覆盖已有 commands 布局

示例：

specify integration install generic --integration-options="--commands-dir .myagent/cmds"

用 scaffold 开发新的内置集成

specify integration scaffold <key>

在 Spec Kit 仓库中创建一个最小内置集成包和配套的测试骨架，然后打印接线步骤。该命令须在 Spec Kit 仓库根目录运行；<key>必须是小写 kebab-case（例如my-agent）。

选项	说明
--type	脚手架模板类型：markdown（默认）、skills、toml、yaml

scaffold 命令 与 scaffold 执行器 配合：它面向 Spec Kit源码仓库布局而非.specify/成员项目（因此不受SPECIFY_INIT_DIR影响），文件写入失败（权限、只读检出、路径冲突）都会以干净的 CLI 错误呈现而非 traceback，并给出编号的 Next steps。

状态文件：.specify/integration.json

多安装 FAQ 中提到的状态布局由 integration_state.py 维护，.specify/integration.json包含：

• default_integration：唯一的默认集成；
• installed_integrations：全部已安装集成列表；
• integration_settings：每个集成的运行时设置（脚本类型、集成选项等）；
• integration_state_schema：为未来状态迁移预留的版本字段（当前值为 1，读到更高 schema 会报错而非静默误读）；
• 旧版integration字段保留为默认集成的别名。

读取路径区分"文件不存在"与"文件存在但不可读/损坏"：非 UTF-8、JSON 解析失败、非对象、schema 过新都会返回结构化的IntegrationReadError，由各命令映射为对应的人可读错误与恢复建议。

常见问题（FAQ）

同一项目能安装多个集成吗？

可以，但这是面向团队可移植性的能力，不是默认工作流。仅当已安装集成与新安装集成都被声明为多安装安全时才自动放行；其他组合需传--force，即你确认接受多个代理可能看到互不相关的代理专属指令或命令这一事实。

哪些集成是多安装安全的？

判定标准：使用静态唯一的代理根目录与命令目录、稳定的命令调用设置、独立的安装清单，且受管文件与其他安全集成不重叠。注册表测试强制这些路径与清单不变量。当前声明多安装安全的集成及其命令目录：

Key	命令目录
alquimia	.alquimia/skills
auggie	.augment/commands
claude	.claude/skills
cline	.clinerules/workflows
codebuddy	.codebuddy/commands
codex	.agents/skills
command-code	.commandcode/skills
cursor-agent	.cursor/skills
droid	.factory/skills
firebender	.firebender/commands
gemini	.gemini/commands
grok	.grok/skills
junie	.junie/commands
kilocode	.kilo/commands
kiro-cli	.kiro/prompts
lingma	.lingma/skills
omp	.omp/commands
pi	.pi/prompts
qodercli	.qoder/skills
qwen	.qwen/commands
shai	.shai/commands
tabnine	.tabnine/agent/commands
trae	.trae/skills
zcode	.zcode/skills

与别的集成共享命令目录、需要--commands-dir这类动态安装路径、或合并共享工具配置的集成默认不声明安全，仍可加--force并存安装。

注意上下文文件定位与多安装安全是两个独立概念：multi_install_safe是关于命令/技能路径的集成声明，而可选的 agent-context 扩展 管理每个代理的上下文文件（如AGENTS.md、CLAUDE.md），可通过其context_files设置同时同步多个锚点——多个代理映射到同一上下文文件在那里是预期行为，不影响多安装安全判定。

卸载或切换时我的修改会怎样？

已修改的文件自动保留，只有未修改（SHA-256 哈希仍匹配）的文件会被删除；--force可覆盖此行为。

怎么知道该用哪个 key？

运行specify integration list查看全部可用集成及其 key，或查阅上文内置集成总览表格。

使用集成前必须装好对应的 AI 编码代理吗？

CLI 型集成（如 Claude Code、Gemini CLI）要求工具本身已安装；IDE 型集成（如 Cursor）通过 IDE 自身工作；GitHub Copilot 这类代理同时支持 IDE 与 CLI 用法。specify integration list会显示每个集成的类型。

何时用upgrade，何时用switch？

升级了 Spec Kit 想刷新已安装集成的受管文件时用upgrade；想用一个新集成替换当前默认时用switch——若目标已安装，switch行为等价于use。

我装的扩展和 preset 会应用到每个已安装集成吗？

不会。扩展（specify extension add）与 preset（specify preset add）只为当前活动（默认）集成注册命令覆盖，即使其他集成已安装也不例外。非默认集成要等它成为默认才会获得这些产物：specify integration use <key>（或switch <key>）会为新的活动集成重新脚手架所有已启用扩展与 preset。specify integration upgrade遵循同一规则——只在升级活动集成时重新注册扩展与 preset。

适用前提与限制

• 所有集成管理命令（除scaffold面向 Spec Kit 源码仓库外）都要求项目已通过specify init初始化；新项目请在 init 阶段用--integration <key>指定代理；
• 受控多安装需要 Spec Kit ≥ 0.8.5，旧版 CLI 只会出现switch/uninstall的建议；
• 目录发现命令（search/info/list --catalog）依赖网络拉取目录 JSON（1 小时缓存），离线时info对内置集成仍可用；
• 命令目录、事件配置等细节以 integrations 目录 下的目录清单（catalog.json、catalog.community.json）与各集成子包（src/specify_cli/integrations/）为准，相关行为由 tests/integrations/ 下按代理组织的测试套件（如test_integration_claude.py、test_integration_catalog.py）持续验证。

【免费下载链接】spec-kit💫 Toolkit to help you get started with Spec-Driven Development项目地址: https://gitcode.com/GitHub_Trending/sp/spec-kit