【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 upgrade）](#一、升级 CLI 工具（specify self upgrade）)
- - [1. 先检查当前版本](#1. 先检查当前版本)
  - [2. 标准升级方式](#2. 标准升级方式)
  - [3. 踩坑：升级卡在 Preparing packages，GitHub 直连下载慢](#3. 踩坑：升级卡在 Preparing packages，GitHub 直连下载慢)
  - [4. 验证升级结果](#4. 验证升级结果)
- [二、更新项目里的 integration 文件（specify integration upgrade）](#二、更新项目里的 integration 文件（specify integration upgrade）)
- - [1. 检查项目 integration 状态](#1. 检查项目 integration 状态)
  - [2. 升级 integration](#2. 升级 integration)
  - [3. 更新 extensions](#3. 更新 extensions)
  - [4. 升级不会动哪些文件](#4. 升级不会动哪些文件)
- [三、兜底方案：specify init --force 重刷](#三、兜底方案：specify init --force 重刷)
- 四、完整流程总结
- 五、常见问题（FAQ）

TL;DR：Spec Kit 升级就是两条命令
bash 复制代码
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 upgrade）

1. 先检查当前版本

bash 复制代码

# 只读检查，看有没有新版本
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 CLI（Claude Code、Codex 之类）	离线

2. 标准升级方式

bash 复制代码

specify self upgrade

这个命令会自动识别你的安装方式（uv tool 或 pipx），底层执行对应的安装命令。我机器上是 miniconda 里装的 uv tool，所以它实际执行的是：

bash 复制代码

uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git@v1.2.0

其他可用参数：

bash 复制代码

# 预览会执行什么，不实际升级
specify self upgrade --dry-run

# 锁定特定版本
specify self upgrade --tag v1.2.0

--tag 参数的格式要求：必须以 vMAJOR.MINOR.PATCH 开头，可以带 dev / alpha / beta / rc / build metadata 后缀，比如 v1.0.0-rc1。分支名、commit hash、latest、不带 v 的纯版本号都不行。

3. 踩坑：升级卡在 Preparing packages，GitHub 直连下载慢

实际跑 specify self upgrade 的时候，卡在 Preparing packages... 半天没动静，直接 Ctrl+C 了。原因是 uv tool install / pipx install 要从 GitHub 拉 git 仓库，国内直连很慢。

解决办法：用 fastgit 镜像前缀，手动执行底层安装命令：

bash 复制代码

uv tool install specify-cli --force --from git+https://fastgit.cc/https://github.com/github/spec-kit@v1.2.0

注意镜像写法的细节：spec-kit 后面直接跟 @v1.2.0，不带 .git。实测 16 秒装完，输出：

复制代码

Uninstalled 1 package in 7ms
Installed 1 package in 2ms
- specify-cli==1.1.2
+ specify-cli==1.2.0

如果你是 pipx 装的，对应写法：

bash 复制代码

pipx install --force git+https://fastgit.cc/https://github.com/github/spec-kit@v1.2.0

这个 fastgit 前缀写法不只适用于 Spec Kit，git clone 和 uv/pipx 的 git+https 源都适用，国内网络环境下建议当成默认操作。

4. 验证升级结果

bash 复制代码

specify self check
# Up to date: 1.2.0

到这里 CLI 升级完成。

二、更新项目里的 integration 文件（specify integration upgrade）

CLI 升完只是工具更新了，项目里 .claude/skills/、.specify/scripts/、.specify/templates/ 这些文件还是旧的。需要进到项目目录里再操作。

1. 检查项目 integration 状态

bash 复制代码

cd ~/workspace/3dbinpackingmodel
specify integration status

我的输出：

复制代码

Integration status: OK
Default integration: claude
Installed integrations: claude
Modified managed files: 0
Missing managed files: 0

Modified managed files: 0 说明没改过受管理的文件，可以放心升。如果这里有非零值，说明本地改过 integration 文件，升级命令会停下来问你，确认改动没用了再加 --force。

2. 升级 integration

bash 复制代码

specify integration upgrade claude

装了多个 integration 的（比如同时有 copilot 和 claude），每个 key 跑一遍：

bash 复制代码

specify integration upgrade copilot
specify integration upgrade claude

3. 更新 extensions

bash 复制代码

specify 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/，升级前备份一下：

bash 复制代码

cp -r .specify/templates .specify/templates-backup
cp -r .specify/scripts .specify/scripts-backup

三、兜底方案：specify init --force 重刷

项目太老没有 manifest 元数据，或者文件缺失比较多的时候，用 init 强刷：

bash 复制代码

specify init --here --force --integration claude

官方定位是逃生通道，不是常规升级路径。它会绕过 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 版本内兼容。

五、常见问题（FAQ）

Q1：specify self upgrade 卡住不动怎么办？

大概率是 GitHub 直连慢，卡在 Preparing packages...。Ctrl+C 中断，改用 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/ 这类受管理文件，且改过的话升级前会询问。

Q5：specify init --here --force 什么时候用？

项目太老没有 manifest 元数据，或者 integration 文件缺失较多时兜底用。它绕过逐文件检查直接覆盖，跑之前务必备份或 commit，跑完 git diff 检查。