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 固定版本# 升级到指定发布 tagvX.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.0build.42或组合v1.0.0-rc1build.42分支名、hash 引用、latest和没有v前缀的裸版本号都会被拒绝。如果self upgrade在你的版本上还不可用按安装方式使用手动等价命令vX.Y.Z替换为你要安装的发布 tag# uv tool 安装 uv tool install specify-cli --force --from githttps://github.com/github/spec-kit.gitvX.Y.Z # pipx 安装 pipx install --force githttps://github.com/github/spec-kit.gitvX.Y.Z一个容易混淆的点uvx只为单条命令运行一个临时副本比如uvx --from githttps://github.com/github/spec-kit.gitvX.Y.Z specify init --here --integration copilot不会更新你 PATH 上持久的specify。如果某个新功能通过uvx可用而本地specify仍报告旧版本需要用与安装方式匹配的命令升级持久 CLI。默认情况下安装子进程没有超时限制可用CtrlC中断。设置SPECIFY_UPGRADE_TIMEOUT_SECS可以封顶安装子进程的运行时长若该内部超时触发specify self upgrade以退出码 124 退出并报告超时信息。注意真正的安装程序退出码 124 也会透传并附带Upgrade failed. Installer exit code: 124.所以脚本中应把退出码 124 视为歧义需要时检查消息内容来区分两种情况。验证 CLI 升级结果# 确认 CLI 可正常工作并显示周边工具环境离线检查 specify check # 对照 GitHub 最新发布版本确认安装版本 specify self checkspecify 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 githttps://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. 查看已安装的 integrationsspecify integration status该命令报告默认 integration、所有已安装 integration 以及被修改或缺失的受管文件不改动任何文件。也可以直接检查.specify/integration.json已安装列表在installed_integrations字段下。2. 逐个升级已安装的 integrationspecify integration upgrade keykey替换为已安装的 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-optionsintegration 选项。旧安装中不再需要的文件会被自动移除。两点行为需要提前知道本地修改会阻断升级如果 manifest 跟踪的 integration 文件在安装后被修改过命令会停下并要求你检查改动或改用--force重跑。先审查 diff再决定是否强制覆盖。扩展和 preset 只在升级默认activeintegration 时重新注册升级非默认 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-agentyour-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 windowCLI 类 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-runspecify 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-syncpresetspecify preset add constitution-sync。升级全部完成后运行/speckit.constitution或其他斜杠命令验证一切工作正常并查看该版本的 release notes 了解新特性和破坏性变更见 Upgrade Guide 的 Next Steps。【免费下载链接】spec-kit Toolkit to help you get started with Spec-Driven Development项目地址: https://gitcode.com/GitHub_Trending/sp/spec-kit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考