spec-kit：用 pipx 隔离安装 Specify CLI 的完整实战指南（版本锁定、验证、升级与卸载）

本文基于 spec-kit 仓库中的 pipx 安装文档 展开，讲解如何用 pipx 在隔离环境中安装 GitHub Spec Kit 的 specify CLI：包括锁定发布标签的可复现安装、specify version 验证、pipx install --force 升级以及卸载方法，并结合 pyproject.toml 与 self-upgrade 实现源码 说明包名、命令名、安装检测机制之间的底层关系，帮助你在团队环境中安全、可复现地部署 Spec-Driven Development 工具链。

为什么选择 pipx：隔离的 Python CLI 安装方式

pipx 安装文档 开篇即给出定位：pipx 是专门用于在隔离环境中安装 Python CLI 应用的工具，且该路线不依赖 uv。这与 Spec Kit 的推荐安装路线（安装指南 中的 uv tool install）形成互补——两条路线最终提供完全相同的 specify 命令，读者可以按自己已有的工具链任选其一。

从仓库元数据看，pipx 安装 Spec Kit 时有两个必须知道的前提：

• Python 版本要求：pyproject.toml 中声明 requires-python = ">=3.11"，即 specify-cli 的最低运行时是 Python 3.11。pipx 可以为工具单独管理解释器，若本机系统 Python 低于 3.11，需要确保 pipx 能找到一个 3.11+ 的解释器。
• 依赖集：CLI 本体依赖 typer、click、rich、platformdirs、readchar、pyyaml、packaging、pathspec、json5（见 pyproject.toml），pipx 会在隔离 venv 中自动解析这些依赖，不会污染全局 Python 环境。

官方文档同时列出的其他前置条件包括一个 AI 编码 agent（Claude Code、GitHub Copilot、Gemini CLI 等）以及可选的 Git（仅当启用 git 扩展时需要），详见 安装指南的前置条件章节。

安装 Specify CLI

官方文档 给出两条安装命令。第一种是推荐的稳定性优先路线——固定到某个发布标签（标签格式可从 Releases 中查到）：

# 安装某个稳定版本（推荐 —— 将 vX.Y.Z 替换为最新标签，
# 保留前导的 v，例如写 v0.12.11 而不是 0.12.11）
pipx install git+https://github.com/github/spec-kit.git@vX.Y.Z

第二种是直接从 main 分支安装最新代码，可能包含尚未发布的变更：

# 或安装 main 分支最新版本（可能包含未发布的改动）
pipx install git+https://github.com/github/spec-kit.git

包名与命令名：为什么卸载时写 specify-cli

一个实操中容易困惑的细节是：安装用的是 Git 地址，卸载的却是 specify-cli。原因在于 pyproject.toml 将发行包（distribution）命名为 specify-cli，而 入口点定义 将命令行可执行文件命名为 specify：

[project]
name = "specify-cli"
...
[project.scripts]
specify = "specify_cli:main"

因此 pipx 以发行包名 specify-cli 管理该工具（pipx list 中显示的名字），而 PATH 中暴露的可执行命令是 specify。这也解释了 安装指南 中反复强调的验证方式：specify version 只是一个本地版本/运行时自检，不能证明可执行文件来自 PyPI 还是 Git 安装——pipx 管理环境下可用 pipx list --json 查看精确的安装规格（参见 PyPI 安装文档的说明）。

wheel 内打包了什么

从 pyproject.toml 的 wheel force-include 配置 可以看到，构建产物不只是 Python 包：wheel 内还打包了页面模板（spec-template.md、plan-template.md 等）、Bash/PowerShell/Python 三套脚本、四个内置扩展（git、agent-context、assess、bug）、speckit workflow 以及 lean、constitution-sync 两个 preset。这意味着一次 pipx 安装后，specify init 可以直接离线落盘项目骨架，无需再回仓库拉取模板——这也是 安装指南 中声明的"本地构建 wheel 同样有效"的离线能力来源（完整离线流程见 企业/隔离环境安装指南）。

验证安装

specify version

version 子命令的实现位于 src/specify_cli/init.py：默认输出包含 CLI 版本、当前 Python 版本、操作系统、架构等信息的面板；版本数值来自 get_speckit_version()，而 self check 所使用的安装版本 则通过 importlib.metadata.version("specify-cli") 读取已安装发行包的元数据（而非源码树中的值），保证自检结论反映 pipx 实际安装的内容。

若只想快速拿到版本号，入口点 还注册了 --version/-V 快捷选项；想确认所有前置工具（各 coding agent、VS Code）是否就绪，可运行 specify check，它会遍历 AGENT_CONFIG 逐项检测（实现见 check 命令）。

升级安装

pipx 文档 给出的手动升级方式是带 --force 的重新安装：

pipx install --force git+https://github.com/github/spec-kit.git@vX.Y.Z

--force 会覆盖已存在的同名工具 venv，等效于"卸载后重装同一位置"。这里同样注意标签要保留前导 v——升级目标标签的校验逻辑在 src/specify_cli/_version.py 中强制要求 vMAJOR.MINOR.PATCH 格式（可选 dev/alpha/beta/rc 后缀与 build 元数据，分支名、hash、不带 v 的裸版本号一律被拒绝），手动升级时遵循同样的书写规范可以避免踩坑。

自动化替代：specify self upgrade 如何识别 pipx 安装

除手动命令外，CLI 自带 specify self upgrade，它会自动识别安装方式并执行对应的升级命令。从 安装方式检测源码 可以看到，pipx 安装被识别的路径前缀为：

"pipx": [
    "~/.local/pipx/venvs/specify-cli/",
    "%LOCALAPPDATA%\\pipx\\venvs\\specify-cli\\",
],

检测采用三级策略（见 _detect_install_method）：

1. Tier 1 — 路径前缀匹配：当前 specify 可执行文件位于 ~/.local/pipx/venvs/specify-cli/（Linux/macOS）或 %LOCALAPPDATA%\pipx\venvs\specify-cli\（Windows）下时直接判定为 pipx 安装；
2. Tier 2 — 可编辑安装标记：direct_url.json 中记录为 editable 时判定为源码检出；
3. Tier 3 — 注册表对账：执行 pipx list --json 检查输出 JSON 的 venvs 中是否包含 specify-cli，且只有当 uv 与 pipx 两个注册表恰好有一个声明所有权时才采纳该结论，两者同时命中则归为 unsupported，避免误升级错误的环境。

识别为 pipx 安装后，升级命令拼装逻辑 会生成与文档手动命令完全一致的 argv：pipx install --force <git 源>@<标签>。源码注释还特别说明：pipx 1.5+ 移除了 --spec 参数，包规格改为位置参数，包名从源仓库的 pyproject.toml 自动探测——这与 升级指南 中"自动检测 uv tool 与 pipx"的文档描述一致。

几个实用细节（来自 升级指南）：

• specify self check 是只读命令，仅报告是否有新版本可用，不修改任何内容；
• specify self upgrade --dry-run 可先预览将要执行的命令；
• 可用环境变量 SPECIFY_UPGRADE_TIMEOUT_SECS 为安装子进程设置硬性超时，超时以退出码 124 报告。

卸载

pipx uninstall specify-cli

注意这里用的是发行包名 specify-cli 而非命令名 specify（原因见上文"包名与命令名"一节）。卸载后 pipx 会删除对应的隔离 venv 及 PATH 中的 specify 入口；已初始化项目中的 .specify/ 目录不会被删除。

与 Spec Kit 其他安装路线的关系

安装指南 将 Spec Kit 的官方分发渠道归纳为 GitHub 源码仓库（标签固定的源安装，推荐路线）与 PyPI 上的 specify-cli 包，pipx 文档属于"源码 + pipx"的组合路线。四条主要路线速查：

路线	命令要点	适用场景	参考文档
uv tool（推荐）	uv tool install specify-cli --from git+...@vX.Y.Z	长期使用，需先安装 uv	安装指南、uv 安装
pipx（本文主题）	pipx install git+...@vX.Y.Z	已有 pipx、不想引入 uv	pipx 文档
PyPI	pipx install specify-cli / uv tool install specify-cli	从包索引安装，可配私有镜像源	PyPI 文档
uvx 一次性运行	uvx --from git+... specify init <项目名>	临时试用，命令结束后环境即丢弃	一次性使用文档

需要提醒的是：本文主题的 pipx 路线从 Git 地址安装，要求能访问 GitHub 仓库；企业内网若无法直达，应改用 企业/隔离环境安装指南 中的本地 wheel 方案。

下一步

安装验证通过后，按 快速入门 初始化第一个 Spec Kit 项目。一个典型的最小命令是：

specify init <PROJECT_NAME> --integration copilot

交互式终端会提示选择编码 agent 集成与脚本类型（Bash/PowerShell/Python）；非交互环境（CI、管道）在未传 --integration 时默认使用 GitHub Copilot。初始化完成后即可在编码 agent 中使用 /speckit.specify、/speckit.plan、/speckit.tasks、/speckit.implement 等 slash 命令（完整清单见 安装指南的验证章节）。