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

2026-09-06 14:36:36作者：凤尚柏Louis

本篇指南围绕 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），基类注释明确要求安全声明方必须使用静态且唯一的代理根目录与命令目录，注册表测试会强制校验这些不变量。

几个关键机制值得展开：

模板渲染管线 process_template()：从命令模板 frontmatter 的 scripts: 块选择脚本变体（sh/ps/py）→ 替换 {SCRIPT} → 删除 scripts: 段 → 替换 {ARGS}/$ARGUMENTS → 替换 __AGENT__ → 重写项目相对路径 → 把 __SPECKIT_COMMAND_<NAME>__ 占位符解析成符合该代理风格的调用串（/speckit.plan 或 /speckit-plan）。这就是为什么同一份 templates/commands/ 模板能派生出所有代理的本地化命令文件。
非交互分派 dispatch_command()：构造斜杠命令提示词后经由 build_exec_args() 生成 CLI 参数并 subprocess 执行，支持流式输出（用户可 Ctrl+C）与捕获输出两种模式；SPECKIT_INTEGRATION_<KEY>_EXECUTABLE 和 SPECKIT_INTEGRATION_<KEY>_EXTRA_ARGS 两个环境变量可分别覆盖可执行文件路径与注入额外参数。
文件操作原语：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-hint frontmatter 并把 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 命令实现中的关键步骤：

key 未注册 → 报错并列出可用 key；已安装 → 提示 use/upgrade 后直接退出；
多安装安全检查：任一已安装集成或新集成未声明安全 → 拒绝（除非 --force），并给出 switch 替代方案；
先确保共享基础设施（.specify/scripts/ 等）就位，且共享模板始终对齐当前默认集成的调用风格（分隔符与调用前缀取自默认集成而非新集成）；
构造 IntegrationManifest 并执行 integration.setup(...)，随后 manifest.save()、更新 .specify/integration.json（追加 installed_integrations、写入 integration_settings）；
任何异常 → 调 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）去哪里找集成。目录按优先级顺序检查，首个匹配生效：

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

这一顺序在 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）持续验证。