Spec Kit CLI 如何升级并在升级后更新项目文件与已装扩展-育师

Spec Kit CLI 如何升级并在升级后更新项目文件与已装扩展

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

当你已经通过uv tool或pipx安装了specifyCLI，并且项目里已经跑过specify init之后，要拿到新版本的斜杠命令、模板和扩展更新，需要分两步完成：先升级 CLI 本体，再刷新项目里已安装的 integration 文件和扩展。Spec Kit 的 CLI 工具与项目文件是相互独立的，只做其中一步意味着要么拿到新 CLI 却还在用旧命令文件，要么项目文件是新的但 CLI 行为仍是旧版。本文覆盖这两步的操作、验证方式和升级后常见的文件冲突处理，操作步骤来自 Upgrade Guide 以及 integration 参考、extension 参考。

升级前的准备

specify self upgrade会自动检测你的运行时是uv tool还是pipx，这两类会被原地升级；uvx（一次性运行）、源码检出和其他不支持的路径只会打印针对性的指引并以退出码 0 结束，不执行任何修改。如果你的 CLI 比引入self upgrade命令的版本更老，则需使用下文的安装方式对应的手动命令。

升级前建议先检查本地是否定制过共享脚本或模板：

# 备份自定义模板和脚本（如果你修改过 .specify/ 下的内容） cp -r .specify/templates .specify/templates-backup cp -r .specify/scripts .specify/scripts-backup

如果定制内容已提交到 Git，用git status确认工作区干净后再升级，升级后可以按 diff 审查被刷新的文件。文档明确：manifest 感知的升级路径只刷新仍与上次受管副本一致的共享脚本和模板，本地定制默认会被保留，但在走init --here --force兜底路径之前，务必先提交或备份以便事后审查。

第一步：升级 CLI

在项目外任意目录都可以执行以下命令，因为它们只操作 CLI 本身：

# 只读检查是否有新版本，不修改任何内容 specify self check # 预览将要执行什么（安装方式、当前版本、目标 tag），实际不升级 specify self upgrade --dry-run # 原地升级到最新稳定版（自动识别 uv tool 与 pipx） specify self upgrade

裸命令specify self upgrade会立即执行，与pip install -U的行为一致。对于uv tool安装，其内部执行uv tool install specify-cli --force --from <git ref>，因此可以配合 tag 固定版本：

# 升级到指定发布 tag；vX.Y.Z[suffix] 需替换为真实 tag specify self upgrade --tag vX.Y.Z[suffix]

tag 有严格格式要求：必须以vMAJOR.MINOR.PATCH开头，可选后缀仅限 dev、alpha/beta/rc 以及 build 元数据形式，例如v1.0.0-rc1、v0.8.0.dev0、v0.8.0+build.42或组合v1.0.0-rc1+build.42；分支名、hash 引用、latest和没有v前缀的裸版本号都会被拒绝。

如果self upgrade在你的版本上还不可用，按安装方式使用手动等价命令（vX.Y.Z替换为你要安装的发布 tag）：

# uv tool 安装 uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git@vX.Y.Z # pipx 安装 pipx install --force git+https://github.com/github/spec-kit.git@vX.Y.Z

一个容易混淆的点：uvx只为单条命令运行一个临时副本，比如uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init --here --integration copilot不会更新你 PATH 上持久的specify。如果某个新功能通过uvx可用而本地specify仍报告旧版本，需要用与安装方式匹配的命令升级持久 CLI。

默认情况下安装子进程没有超时限制（可用Ctrl+C中断）。设置SPECIFY_UPGRADE_TIMEOUT_SECS可以封顶安装子进程的运行时长；若该内部超时触发，specify self upgrade以退出码 124 退出并报告超时信息。注意真正的安装程序退出码 124 也会透传并附带Upgrade failed. Installer exit code: 124.，所以脚本中应把退出码 124 视为歧义，需要时检查消息内容来区分两种情况。

验证 CLI 升级结果

# 确认 CLI 可正常工作并显示周边工具环境（离线检查） specify check # 对照 GitHub 最新发布版本确认安装版本 specify self check

specify self check是只读的版本查询：已在最新版时输出形如Up to date: X.Y.Z，有更新时输出Update available: X.Y.Z → vY.Z.W（以上为文档给出的输出示例）。如果它显示版本不对，用uv tool list确认specify-cli存在、which specify确认指向安装目录；都找不到时重新安装：

uv tool uninstall specify-cli uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

第二步：更新项目文件

CLI 升级完成后，切换到项目根目录刷新 Spec Kit 文件。manifest 感知的升级路径只更新：

各 agent 的 integration 命令/技能文件（如.claude/skills/、.github/prompts/、.agents/skills/）；
仍与上次受管副本一致的受管共享脚本和模板（.specify/scripts/、.specify/templates/）；
已安装扩展（在执行specify extension update时）。

以下内容永远不会被该路径触碰：specs/下的规格、计划与任务文件（specs/001-my-feature/spec.md、plan.md、tasks.md）、使用specify integration upgrade时的.specify/memory/constitution.md、源码和 Git 历史。specs/目录完全排除在模板包之外。

1. 查看已安装的 integrations

specify integration status

该命令报告默认 integration、所有已安装 integration 以及被修改或缺失的受管文件，不改动任何文件。也可以直接检查.specify/integration.json，已安装列表在installed_integrations字段下。

2. 逐个升级已安装的 integration

specify integration upgrade <key>

<key>替换为已安装的 integration key，如copilot、claude、codex；省略 key 时默认升级默认 integration。项目中安装了多个 integration 时，每个已安装 key 各跑一次：

specify integration upgrade claude specify integration upgrade codex

可用选项见 integration 参考：--force（即使文件被修改也覆盖）、--script sh|ps|py（脚本类型：bash/zsh、PowerShell 或 Python）、--integration-options（integration 选项）。旧安装中不再需要的文件会被自动移除。

两点行为需要提前知道：

本地修改会阻断升级：如果 manifest 跟踪的 integration 文件在安装后被修改过，命令会停下并要求你检查改动或改用--force重跑。先审查 diff，再决定是否强制覆盖。
扩展和 preset 只在升级默认（active）integration 时重新注册：升级非默认 integration 只刷新其核心命令，不会重新注册扩展/preset 层，之后用use/switch激活它时会重新脚手架化。此外，如果一次升级会改变 integration 的 command/skills 布局而它注册了 preset 产物，升级会在改动任何文件之前被拒绝——先移除受影响 preset、执行升级、再重新安装 preset。

3. 更新已安装的扩展

# 更新全部已安装扩展 specify extension update # 只更新某一个扩展 specify extension update <extension-id-or-name>

不带参数时更新所有已安装扩展。参数细节见 extension 参考。

兜底路径：重新运行 init（可选）

只有当项目早于 manifest 机制、integration 元数据缺失、或需要更宽泛的恢复时，才使用：

specify init --here --force --integration <your-agent>

<your-agent>替换为使用的 agent integration key。文档明确把它定位为逃生舱而非默认路径：它刷新选定 integration 和共享脚手架，但不做逐 integration 的 manifest 检查就覆盖文件。执行前提交或备份本地定制，以便事后审查 diff。当前init --here --force会保留已存在的.specify/memory/constitution.md，仅在文件缺失时从模板创建。

在已有文件的目录运行init --here时会看到如下确认提示（"25 items" 为文档示例值）：

Warning: Current directory is not empty (25 items) Template files will be merged with existing content and may overwrite existing files Do you want to continue? [y/N]

输入y继续合并，输入n取消，或用--force跳过确认。会被覆盖的仅限 Spec Kit 基础设施文件（agent 命令/技能文件、.specify/scripts/、.specify/templates/；缺失的 memory 文件如 constitution 会从模板创建，已存在的 constitution 保留）；specs/、源码、.git/和其他非模板文件不受影响。

升级后排查常见问题

斜杠命令升级后不显示。文档给出的原因是 agent 未重新加载命令文件：完整重启 IDE/编辑器（不是只 reload window）；CLI 类 agent 先确认文件存在：

ls -la .claude/skills/ # Claude Code ls -la .gemini/commands/ # Gemini ls -la .cursor/skills/ # Cursor ls -la .pi/prompts/ # Pi Coding Agent ls -la .omp/commands/ # Oh My Pi

个别 agent 有额外条件：Codex 需要CODEX_HOME环境变量；有些 agent 需要重启 workspace 或清缓存。

IDE 类 agent 出现重复斜杠命令。Kilo Code、Cline 等 IDE 类 agent 升级后可能同时出现新旧两版命令。解法是手动删除 agent 目录里的旧命令文件。以 Kilo Code 为例（以下文件名为文档示例，实际文件名可能不同，先用ls确认再删）：

# 查看当前与遗留命令目录 ls -la .kilo/commands/ ls -la .kilocode/workflows/ # 删除旧版本命令文件（示例文件名，按实际内容操作） rm .kilocode/workflows/speckit.specify-old.md rm .kilocode/workflows/speckit.plan-v1.md

删除后重启 IDE 刷新命令列表。

CLI 升级后行为仍像旧版本。先问 CLI 本身：

# 只读，输出 "Up to date: X.Y.Z" 或 "Update available: ..." specify self check # 预览安装方式、当前版本和目标 tag specify self upgrade --dry-run

specify check是离线环境扫描，specify self check才是版本查询。若版本查询显示异常，再按上文验证安装（uv tool list、which specify）直至重装。

版本兼容性与限制

Spec Kit 对大版本遵循语义化版本；CLI 与项目文件在同一 major 版本内设计为兼容，最佳实践是在 major 版本变更时两者一起升级。
specify integration upgrade <key>不会更新.specify/memory/constitution.md；兜底 init 路径也会保留已存在的 constitution。
git 扩展现在是 opt-in：升级不会安装它，除非显式执行specify extension add git。
/constitution命令在新版中只更新.specify/memory/constitution.md并写入 Sync Impact Report，不再编辑plan-template.md、spec-template.md、tasks-template.md等模板。非强制升级下，已被旧版"物化"的模板因 hash 偏离受管副本会被视为定制而保留，不会回退。如果团队需要旧的传播行为，可安装constitution-syncpreset：specify preset add constitution-sync。