【AI工具】Spec Kit 升级教程：specify CLI 从 1.1.2 升到 1.2.0 全流程（含 GitHub 下载慢的镜像解法）

【AI工具】Spec Kit 升级教程specify CLI 从 1.1.2 升到 1.2.0 全流程含 GitHub 下载慢的镜像解法文章目录【AI工具】Spec Kit 升级教程specify CLI 从 1.1.2 升到 1.2.0 全流程含 GitHub 下载慢的镜像解法一、升级 CLI 工具specify self upgrade1. 先检查当前版本2. 标准升级方式3. 踩坑升级卡在 Preparing packagesGitHub 直连下载慢4. 验证升级结果二、更新项目里的 integration 文件specify integration upgrade1. 检查项目 integration 状态2. 升级 integration3. 更新 extensions4. 升级不会动哪些文件三、兜底方案specify init --force 重刷四、完整流程总结五、常见问题FAQTL;DRSpec Kit 升级就是两条命令specify self upgrade# 第一步升级 CLI 工具specify integration upgrade claude# 第二步升级项目里的 integration 文件卡在Preparing packages...下载不动是 GitHub 直连慢导致的换 fastgit 镜像手动装见第三节实测 16 秒装完。GitHub Spec Kit 的升级分两块CLI 工具本身specify-cli和项目里安装的 integration 文件.claude/skills/、.specify/scripts/、.specify/templates/。两者要一起升尤其大版本更新的时候只升 CLI 不升项目文件新加的 slash command 不会出现。本文是 Debian 开发机上 1.1.2 升 1.2.0 的实操记录覆盖标准升级路径、国内网络下的镜像加速方案、以及没有 manifest 元数据时的兜底方案。一、升级 CLI 工具specify self upgrade1. 先检查当前版本# 只读检查看有没有新版本specify self check输出类似Update available: 1.1.2 → v1.2.0 To upgrade: specify self upgrade注意specify self check和specify check是两个不同的命令很多人混淆命令作用是否联网specify self check检查 CLI 自身版本是否落后于 GitHub 最新 release联网specify check扫描本地环境装了哪些 Agent CLIClaude Code、Codex 之类离线2. 标准升级方式specify self upgrade这个命令会自动识别你的安装方式uv tool或pipx底层执行对应的安装命令。我机器上是 miniconda 里装的 uv tool所以它实际执行的是uv toolinstallspecify-cli--force--fromgithttps://github.com/github/spec-kit.gitv1.2.0其他可用参数# 预览会执行什么不实际升级specify self upgrade --dry-run# 锁定特定版本specify self upgrade--tagv1.2.0--tag参数的格式要求必须以vMAJOR.MINOR.PATCH开头可以带dev/alpha/beta/rc/ build metadata 后缀比如v1.0.0-rc1。分支名、commit hash、latest、不带 v 的纯版本号都不行。3. 踩坑升级卡在 Preparing packagesGitHub 直连下载慢实际跑specify self upgrade的时候卡在Preparing packages...半天没动静直接 CtrlC 了。原因是uv tool install/pipx install要从 GitHub 拉 git 仓库国内直连很慢。解决办法用 fastgit 镜像前缀手动执行底层安装命令uv toolinstallspecify-cli--force--fromgithttps://fastgit.cc/https://github.com/github/spec-kitv1.2.0注意镜像写法的细节spec-kit后面直接跟v1.2.0不带.git。实测 16 秒装完输出Uninstalled 1 package in 7ms Installed 1 package in 2ms - specify-cli1.1.2 specify-cli1.2.0如果你是 pipx 装的对应写法pipxinstall--forcegithttps://fastgit.cc/https://github.com/github/spec-kitv1.2.0这个 fastgit 前缀写法不只适用于 Spec Kitgit clone 和 uv/pipx 的 githttps 源都适用国内网络环境下建议当成默认操作。4. 验证升级结果specify self check# Up to date: 1.2.0到这里 CLI 升级完成。二、更新项目里的 integration 文件specify integration upgradeCLI 升完只是工具更新了项目里.claude/skills/、.specify/scripts/、.specify/templates/这些文件还是旧的。需要进到项目目录里再操作。1. 检查项目 integration 状态cd~/workspace/3dbinpackingmodel specify integration status我的输出Integration status: OK Default integration: claude Installed integrations: claude Modified managed files: 0 Missing managed files: 0Modified managed files: 0说明没改过受管理的文件可以放心升。如果这里有非零值说明本地改过 integration 文件升级命令会停下来问你确认改动没用了再加--force。2. 升级 integrationspecify integration upgrade claude装了多个 integration 的比如同时有 copilot 和 claude每个 key 跑一遍specify integration upgrade copilot specify integration upgrade claude3. 更新 extensionsspecify extension update没装 extension 的话会提示No extensions installed跳过即可。注意 git extension 现在是 opt-in 的升级不会自动装需要的话手动specify extension add git。4. 升级不会动哪些文件这套 manifest 感知的升级路径不会碰你的业务内容specs/目录下的 spec.md、plan.md、tasks.md完全不碰.specify/memory/constitution.md不会被 integration upgrade 覆盖源代码和 git 历史自然不受影响如果本地改过.specify/scripts/或.specify/templates/升级前备份一下cp-r.specify/templates .specify/templates-backupcp-r.specify/scripts .specify/scripts-backup三、兜底方案specify init --force 重刷项目太老没有 manifest 元数据或者文件缺失比较多的时候用 init 强刷specify init--here--force--integrationclaude官方定位是逃生通道不是常规升级路径。它会绕过 manifest 的逐文件检查直接覆盖所以跑之前先把本地改动 commit 或备份跑完用git diff检查一遍。四、完整流程总结1. specify self check # 看版本 2. specify self upgrade # 升 CLI慢就换 fastgit 镜像手动装 3. specify self check # 验证 Up to date 4. cd 项目目录 5. specify integration status # 确认 Modified/Missing 为 0 6. specify integration upgrade key # 升项目 integration 文件 7. specify extension update # 有 extension 才需要大版本更新时 CLI 和项目文件要一起升保持同一个 major 版本内兼容。五、常见问题FAQQ1specify self upgrade 卡住不动怎么办大概率是 GitHub 直连慢卡在Preparing packages...。CtrlC 中断改用 fastgit 镜像手动执行底层安装命令见第三节。self upgrade的安装子进程默认没有超时限制卡住就手动接管。Q2升级报退出码 124 是什么意思124 是内部超时标志。看到它就放弃self upgrade改用手动安装命令。Q3只升级 CLI 不升级项目文件行不行不建议。CLI 和项目 integration 文件要配对升级只升 CLI 的话项目里不会出现新版本的 slash command 和模板大版本更新时可能出现版本不兼容。Q4升级会覆盖我写的 spec 和 constitution 吗不会。specs/目录下的 spec.md、plan.md、tasks.md 完全不碰.specify/memory/constitution.md也不会被 integration upgrade 覆盖。会覆盖的只有.specify/scripts/、.specify/templates/这类受管理文件且改过的话升级前会询问。Q5specify init --here --force 什么时候用项目太老没有 manifest 元数据或者 integration 文件缺失较多时兜底用。它绕过逐文件检查直接覆盖跑之前务必备份或 commit跑完 git diff 检查。