spec-superflow 上手指南：6 平台安装- 在 Claude Code / Cursor / Codex /

你将学到

在 Claude Code / Cursor / Codex / Copilot / Gemini 五个主流平台上安装 spec-superflow 的具体命令

安装后如何用 ssf doctor 验证环境健康，而不是直接开工

第一次 workflow-start 的完整对话流程，从输入到 DP-0 确认

ssf CLI 的 9 个子命令分类与常用组合

适合人群：上一讲已经知道 spec-superflow 的价值，现在想把工具装到自己主力 AI 编码环境里的开发者 预计阅读：12 分钟 前置知识：第 1 讲《spec-superflow 凭什么让我扔掉手动流程》

上一讲我们聊完 spec-superflow 为什么能把 OpenSpec（5.8 万星）的「想清楚」和 Superpowers（24 万星）的「做对」焊在一起。这一讲不聊原理，直接动手。你现在的目标很简单，打开自己常用的 AI 编码工具，输入一条命令，让它学会规格驱动的工作方式。

很多人卡在这一步。不是命令有多难，而是每个平台的插件机制、skill 目录、hook 注入方式都不一样。Claude Code 用 /plugin，Cursor 用 .cursor/skills/，Copilot CLI 靠 plugin.json，Gemini CLI 还在实验通道。你照着官方 README 复制，很可能在某个平台踩到一个不起眼的坑，然后怀疑「是不是这个工具还不支持」。

这一讲会把 6 个平台的安装命令、验证方式和常见坑一次性说清楚。 所有命令都可以直接复制，预期输出基于 v0.8.4 本地源码验证。

一、先搞清楚这一讲要帮你解决什么问题

上一讲是「为什么值得装」，这一讲是「装完之后怎么跑起来」。读者最想确认的 5 件事分别是：我的 AI 工具能不能装、每个平台的命令是什么、装好之后第一句话说什么、第一次 workflow-start 会经历哪些阶段、CLI 工具链怎么验证环境健康。

这 5 件事里，最影响体验的不是命令本身，而是「不知道自己卡在哪」。安装失败时，报错信息往往很模糊，你分不清是 Node 版本不够、skill 目录没放对，还是 hook 没注入成功。如果每个平台都给你一张清晰的检查清单，排查时间可以从半小时压缩到三分钟。

spec-superflow 是零依赖的自包含插件。 你不需要先装 OpenSpec，也不需要先装 Superpowers。它把两边的核心能力源码级吸收后，以一套 skill 包的形式发布。截至 v0.8.4，官方支持 8 个平台，本讲重点覆盖其中 6 个：Claude Code、Cursor、Codex CLI、Copilot CLI、Gemini CLI，OpenCode 和 Trae 作为补充带过。

整个流程可以压缩成四步：环境准备 → 平台安装 → ssf doctor 验证 → 第一次 workflow-start。每一步我都会给出一个可以复制的命令和一段预期输出，你照着跑，遇到问题按 ssf doctor 的报错逐条排查即可。

6 平台安装路径与验证入口总览

二、环境准备，只有一条硬性要求

spec-superflow 的硬性依赖只有一个，Node.js ≥ 22。它用 Node 运行安装脚本、CLI 工具链和 Guard 检查，不依赖 Python、Docker 或其他运行时。选择 22 而不是 18 或 20，是因为脚本里用到了 node:util.parseArgs 的完整特性和部分新文件系统 API，低版本会抛 ERR_UNKNOWN_BUILTIN_MODULE 或参数解析错误。

先检查你的 Node 版本。

node --version

预期输出类似下面这样，主版本号必须 ≥ 22。

v22.12.0

如果版本不够，建议用 nvm 或 fnm 升级。两者都不影响系统级 Node，升级和回滚都很快。

# macOS / Linux，用 nvm
nvm install 22
nvm use 22
nvm alias default 22

# 或者用 fnm
fnm install 22
fnm use 22
fnm default 22

国内访问 GitHub 不稳定的话，安装脚本会自动走镜像。如果自动镜像失败，可以手动设置 GH_PROXY 环境变量再跑命令。

export GH_PROXY=https://ghproxy.com/

Git 也是必需的，因为 /plugin marketplace add 实际是从 GitHub 拉取仓库。没有 Git 的话，Claude Code 内的插件市场会报 git: command not found。用 git --version 确认一下，低于 2.40 的话建议升级，旧版在处理浅克隆时偶尔会卡住。

最后确认一下网络。如果你能正常打开 GitHub，安装过程会顺利很多。如果打不开，除了设置 GH_PROXY，也可以考虑把仓库先手动 clone 到本地，再用本地路径安装。

还有一个建议，安装前关闭其他可能占用同一配置目录的 AI 工具进程。比如同时开着 Cursor 和 Claude Code 跑安装脚本，偶尔会争夺 .cursor/ 或 .claude/ 目录的写锁，导致 hook 注入失败。

三、6 个平台安装指南

下面这张表是全文的总览。后面会按平台展开细节和踩坑提示。

平台	安装命令	验证方式	常见坑
Claude Code	`/plugin marketplace add MageByte-Zero/spec-superflow` `/plugin install spec-superflow@spec-superflow`	`ssf doctor`	无
Cursor	`npx spec-superflow@latest install-cursor`	检查 `.cursor/skills/spec-superflow/`	目录名与 skill 名不一致
Codex CLI	`npx spec-superflow@latest install-codex`	`ssf doctor`	CLI 插件路径
Copilot CLI	`npx spec-superflow@latest install-copilot`	检查 `plugin.json`	author 字段格式
Gemini CLI	`npx spec-superflow@latest install-gemini`	`ssf doctor`	实验性支持
OpenCode / Trae	`npx spec-superflow@latest install-opencode` `npx spec-superflow@latest install-trae`	手动检查 skills 目录	文档更新较慢

6 平台安装方式、验证命令与风险点对比

小调查：你主力用哪个 AI 编码工具？欢迎在评论区回复编号。

Claude Code

Cursor

Copilot

其他 / 还没定

3.1 Claude Code

Claude Code 的插件市场最省事。在会话里直接输入下面两行。

/plugin marketplace add MageByte-Zero/spec-superflow
/plugin install spec-superflow@spec-superflow

第一行把仓库注册到插件市场，第二行执行安装。安装完成后，Claude Code 会自动把 skill 注入到当前会话。你可以立即输入 ssf version 测试，预期输出如下。

spec-superflow v0.8.4
OpenSpec v1.5.0
Superpowers v6.1.0

Claude Code 的 SessionStart hook 在 v0.8.4 仅注入约 40 tokens，不会吃掉上下文窗口。

3.2 Cursor

Cursor 没有内置插件市场，spec-superflow 提供了一键安装脚本。

npx spec-superflow@latest install-cursor

脚本会完成三件事：把 skill 文件复制到 ~/.cursor/skills/spec-superflow/、在 .cursor/rules/ 下生成 phase-guard.mdc、把 SessionStart hook 注入到 Cursor 的启动配置。

安装完成后，务必检查目录名。

ls -la ~/.cursor/skills/spec-superflow/

Cursor 最大的坑是目录名。 有些旧文档写的目录名是 spec_superflow 或 SpecSuperflow，Cursor 的 Agent 只会按 skill 名精确匹配 spec-superflow。目录名不对，Agent 就找不着 skill。如果你发现输入 workflow-start 后 Cursor 没反应，先检查这一层。phase-guard.mdc 也不要随意改名，它是 Guard 系统的软防线。

3.3 Codex CLI

Codex CLI 的安装方式与 Cursor 类似，也是命令行脚本。

npx spec-superflow@latest install-codex

Codex CLI 的 skill 加载路径取决于你的配置目录，脚本会自动探测 ~/.codex/ 或 ~/.config/codex/。探测失败时，脚本会打印出它尝试过的路径，你按提示手动复制即可。

验证方式同样是 ssf doctor。

3.4 Copilot CLI

Copilot CLI 的插件注册需要一份 plugin.json。安装脚本会帮你生成。

npx spec-superflow@latest install-copilot

安装完成后，检查 plugin.json 的 author 字段。

{
  "author": "MageByte-Zero"
}

v0.7.0 之前有一个常见 bug，author 字段被写成对象而不是字符串。 如果你看到 author 后面跟了花括号套 name 的格式，手动改成字符串。v0.8.4 的脚本已修复，但旧教程还在传播错误模板。

3.5 Gemini CLI

Gemini CLI 的支持目前标记为实验性。

npx spec-superflow@latest install-gemini

由于其插件规范迭代较快，安装后先跑 ssf doctor。如果报 hooks not found，按提示手动把 hooks/session-start 复制到启动脚本目录。

3.6 OpenCode 与 Trae

这两个平台的用户相对较少。

npx spec-superflow@latest install-opencode
npx spec-superflow@latest install-trae

由于 skill 目录规范更新较慢，脚本采用「复制到默认路径 + 打印手动确认步骤」的方式。跑完后按终端提示检查对应目录。

四、安装后第一件事，跑 ssf doctor

很多人装完插件就急着说 workflow-start。我习惯先跑一遍 ssf doctor。doctor 不是装饰品，它是环境健康的唯一真实来源。 直接开工而跳过验证，就像开车前不看仪表盘，多数时候没事，但真有事的时候代价很高。

ssf doctor

v0.8.4 的预期输出大致如下。

[spec-superflow] Environment Check
----------------------------------
Node.js          ✓ v22.12.0
git              ✓ v2.48.1
skill path       ✓ /Users/you/.claude/skills/spec-superflow
hooks            ✓ session-start injected (~40 tokens)
state dir        ✓ .spec-superflow/
config file      ✓ spec-superflow.config.json
 Guard rules     ✓ phase-guard.mdc found
platform         ✓ Claude Code

All checks passed. You can run `workflow-start` now.

逐行解读。

skill path，skill 文件是否在 Agent 能发现的目录里。Cursor 用户这里如果显示 ✗，99% 是目录名问题。
hooks，SessionStart hook 是否注入成功，以及注入了多少 token。v0.8.4 是约 40 tokens，比早期版本的 ~2,200 个单词大幅压缩。
state dir，.spec-superflow/ 目录是否存在。这是状态文件和 Guard 缓存的家目录。
config file，配置文件是否存在。第一次安装会生成默认配置。
Guard rules，phase-guard 是否就位。Cursor 用户特别要看这一条。
platform，当前检测到的平台。如果识别错了，后续 ssf inject 生成的 hook 格式也会错。

任何一行打叉，都先修好再进入 workflow。否则到了执行阶段，Agent 可能找不到 skill，或者 Guard 检查会误拦。如果 ssf doctor 报 hooks ✗，先运行 ssf inject 重新注入；如果报 skill path ✗，检查对应平台的 skills 目录名是否严格为 spec-superflow。

我建议把 ssf doctor 加入每次升级后的习惯动作。spec-superflow 的版本迭代很快，v0.8.x 系列几乎每个小版本都会调整 hook 格式，doctor 能在你开工前把这类问题拦截掉。

五、第一次 workflow-start 全流程

环境健康之后，你可以对 Agent 说出那句开场白了。

用 workflow-start 开始。我要给用户管理模块加一个分页查询。

注意，不是直接说「写个分页查询」，而是先说「用 workflow-start 开始」。 这两个字决定了后续所有 skill 的调度入口。

workflow-start 会做三件事：内容级检测判断是全新变更还是继续旧变更，模式判定决定走 full / hotfix / tweak 哪条路径，路由到第一个 skill。全新变更进入 need-explorer，已有工件则进入 spec-writer 或 contract-builder。

对于我们这个例子，目录里没有现成 artifact，workflow-start 会把状态设为 exploring（探索中）并调用 need-explorer。

5.1 DP-0，设计前确认

在 need-explorer 提问之前，workflow-start 会先触发 DP-0（Decision Point 0，用户确认门禁）。它会问你。

我将开始一次新的变更，方向是「给用户管理模块加分页查询」。请确认这是你想要的方向，还是你想调整范围。

你回答「确认」。这个确认是后续所有工件的「意图锁」，如果中途需求跑偏，Guard 会拿它做比对。

5.2 exploring → specifying

DP-0 确认后，状态进入 exploring（探索中）。need-explorer 一次只问一个问题，比如「页码从 0 开始还是从 1 开始」「pageSize 上限是多少」。两到三个问题后给出方案对比，你确认其一。状态自动推进到 specifying（规格生成中），spec-writer 开始写 proposal / specs / design / tasks 四个工件。

5.3 bridging，唯一一次人工审批

四个工件生成后，状态进入 bridging（桥接中）。contract-builder 自动读取工件，生成 execution-contract.md，然后暂停展示给你。

## Intent Lock
为用户管理模块添加分页查询接口，变更范围仅限三文件。

## Scope Fence
- 可修改，UserController / UserService / UserListDTO
- 不可修改，UserEntity

## Test Obligations
- page=0 → 400
- size=101 → 400
- 空结果 → 200 + 空数组

你确认无误后说「批准」。状态进入 approved-for-build（已批准构建），之后的执行阶段基本不需要你再手动切换工具。

第一次 workflow-start 完整状态流转

六、CLI 工具链速览

ssf 是 spec-superflow 的命令行入口。v0.8.4 有 9 个子命令，可以分成三类。

类别	命令	用途
信息查询	`list` `version` `state`	看当前变更、版本、状态
质量检查	`validate` `doctor` `audit`	验证工件、环境、决策记录
工程维护	`sync` `config` `inject`	同步 delta spec、改配置、重新注入 hook

ssf CLI 9 个子命令分类

最常用的是下面四条。

# 查看当前目录下的所有变更
ssf list

# 验证当前变更的工件是否符合 Schema
ssf validate

# 查看状态机当前位置和下一步建议
ssf state

# 生成审计报告，记录所有 Decision Point
ssf audit

ssf list 的输出示例。

ID                  STATUS              SKILL               LAST_UPDATE
pagination-20260703 exploring           need-explorer       2026-07-03T10:23:11Z

ssf validate 会检查 proposal / specs / design / tasks 的格式，比如 SHALL 关键字是否大写、Given-When-Then 是否完整、delta spec 标记是否合法。验证失败会直接指出文件名和行号。

ssf inject 在你升级 spec-superflow 版本后很有用。它会重新生成各平台需要的 hook 和 mdc 文件，避免旧版本的 phase-guard 残留。ssf sync 则在变更关闭后把 delta spec 合并回主规范，棕地项目几乎每次都会用到它。

还有两个不常用但关键时刻能救命的命令。ssf config 用于查看和修改当前配置，比如调整 artifact 顺序或切换验证语言。ssf audit 会输出本次变更的所有 Decision Point 记录，适合在复盘或 CI 失败时逐条检查。

日常使用中，我的习惯是「开工前 doctor，提交前 validate，关闭后 sync」。这套组合能覆盖 90% 以上的 CLI 使用场景。把这三条写成 alias，可以进一步减少记忆负担。

七、快速路径提示

不是所有变更都要走完整 8 状态。Guard 系统会在 workflow-start 阶段自动检测变更规模，把变更分成三类。

hotfix，不超过 2 个文件，跳过 exploring 和 specifying，生成最小契约后直接执行。
tweak，配置或文档变更，跳过全部规划阶段，直接编辑并归档。
full，标准流程，完整 8 状态。

举两个例子。你发现生产环境有一个空指针异常，原因是某行代码少判了 null，只改一个文件就能修好。这种场景 workflow-start 会自动判定为 hotfix，不会逼你先写 proposal 再写 specs。

再比如你只需要把 README 里的安装命令从 v0.8.3 改成 v0.8.4。这种 tweak 级别的变更会直接编辑文档，然后归档，整个过程半分钟不到。

快速路径会在执行过程中自动升级。 如果你启动时是个 hotfix，改到一半发现波及 4 个文件，Guard 会把流程升级为 full，要求补全规划工件。这比「我以为只是小改动，结果把项目改崩了」安全得多。

v0.8.4 还修复了 tweak 模式下 Guard 误拦的 bug。现在改 README、调配置真的可以在半分钟内完成归档。

快速路径不是偷懒，而是用规则替代人的判断。你不需要每次都在心里盘算「这个改动要不要写 spec」，Guard 会根据文件数和变更类型自动决定。

八、踩坑记录

这里记录三个我亲自踩过、也是最常被读者问到的坑。

坑一：Cursor 的 skill 目录名不对

症状是输入 workflow-start 后 Cursor 完全没有反应，或者 Agent 回答说不知道这个命令。你第一反应可能是「skill 没装上」，然后反复跑安装脚本。

解法：先检查 ~/.cursor/skills/ 下的目录名是否严格等于 spec-superflow。有些旧教程写成 spec_superflow 或带空格的版本，Cursor 的 Agent 只会按 skill 名精确匹配。改对目录名后重启 Cursor 即可，不需要重装。

坑二：Copilot CLI 的 plugin.json author 字段格式错误

症状是安装后 ssf doctor 报 platform plugin not loaded，但 skill 文件明明存在。

解法：打开 Copilot CLI 配置目录下的 plugin.json，确保 author 是字符串。

{
  "author": "MageByte-Zero"
}

不要写成对象。这个问题在 v0.7.0 已经修复，但网络上仍有不少旧文档在传播错误格式。如果你从旧博客复制配置，务必核对这一行。

坑三：以为必须先装 OpenSpec 和 Superpowers

这是概念坑，不是技术坑。spec-superflow 是自包含插件，已经把两边的必要源码吸收进来。你不需要先跑 OpenSpec 的安装命令，也不需要先配 Superpowers 的 skill。 直接装 spec-superflow 即可。这个误解很常见，因为项目名字让人误以为它是 OpenSpec 和 Superpowers 的「 wrapper」。

九、FAQ

Q1，我装了 spec-superflow 之后，还要单独装 OpenSpec 或 Superpowers 吗？

不需要。spec-superflow 把 OpenSpec 的 Schema 验证、Delta Spec 机制和 Superpowers 的 TDD 铁律、Review Gate、SDD 等核心能力源码级吸收后重新整合，对外是零依赖的单一插件。

Q2，安装后会不会吃掉大量上下文窗口？

不会。v0.8.4 的 SessionStart hook 仅注入约 40 tokens，对比早期版本 ~2,200 个单词的全文注入，几乎可以忽略。ssf doctor 会显示具体注入量。

Q3，小改动也要走完整 8 状态吗？

不需要。hotfix 和 tweak 快速路径会自动跳过规划阶段。Guard 会在执行中检测变更规模，超出阈值自动升级为 full。

Q4，Cursor 安装后 Agent 还是找不到 skill 怎么办？

先检查 ~/.cursor/skills/spec-superflow/ 是否存在且目录名严格为 spec-superflow。再检查 .cursor/rules/phase-guard.mdc 是否存在。最后重启 Cursor。

Q5，ssf doctor 报 state file 不一致怎么办？

通常是上次变更没有正常关闭。先运行 ssf state 查看当前状态，如果是 abandoned（已放弃）或 closing（关闭中）的残留，可以手动删除 .spec-superflow/state.json 后重新运行 workflow-start。如果状态是 executing（执行中），建议先 ssf audit 查看审计记录，不要直接删文件。

Q6，我升级了 spec-superflow，需要重新安装吗？

不需要重新跑平台安装脚本。先运行 ssf inject 重新生成 hook 和 mdc 文件，再跑 ssf doctor 确认版本号。如果 ssf version 还是旧版本，再用对应平台的安装脚本覆盖一次。

十、参考资料

spec-superflow GitHub 仓库，本专栏主角，README 包含安装说明、CLI 文档和 Guard 配置示例
OpenSpec GitHub 仓库，规划引擎参考实现
Superpowers GitHub 仓库，执行纪律框架参考实现
Claude Code 插件文档，/plugin 命令机制
Cursor 自定义规则文档，.cursor/rules/ 和 .cursor/skills/ 加载顺序
Codex CLI 官方文档，插件目录结构
GitHub Copilot CLI 文档，插件注册格式

这些参考资料覆盖了安装和后续深入学习的全部入口。遇到平台-specific 的问题，优先查对应官方文档；遇到 spec-superflow 行为疑问，优先看 GitHub README 和 issue 列表。社区里已经积累了不少 Cursor 目录名、Copilot plugin.json 等常见问题的讨论。

安装跑通只是第一步。下一讲我们会深入 OpenSpec 的四个工件依赖拓扑，看 proposal / specs / design / tasks 为什么必须按这个顺序生成，以及 Delta Spec 的 ADDED / MODIFIED / REMOVED 标记在棕地项目里怎么救命。理解了这一层，你才会明白 spec-superflow 的 bridge-contract 为什么能从这些工件里自动提取出可检查的契约。

🪐 读完这篇「spec-superflow 上手指南」，如果对你有帮助，去 GitHub 给 spec-superflow 点个 Star ⭐。这个开源项目从第一行代码到 v0.8.4，每一步都在解决 AI 编码「想清楚再做」的问题。你的 star 是这个项目活下去的燃料。