Kc's blog

Appearance

kc_shen2026-04-17
2876
11.3m

openspec使用指南 ​

OpenSpec 是什么（在 Cursor 里用来干嘛） ​

OpenSpec 是一种**规范驱动开发（Spec-Driven Development）**的工作流工具：先把“要做什么、为什么做、怎么验收、怎么实现、怎么拆任务”写成结构化制品（Markdown/YAML），再让 Cursor 的 AI 按制品一步步产出代码并自检，减少“AI 写着写着跑偏/返工多/改动不可追踪”的问题。

你可以把它理解成：给 AI 一个项目内的“作业说明书 + 任务清单 + 验收标准”，并且这些内容会随着开发过程持续迭代、可回溯、可归档。

安装与初始化（只做一次） ​

0）macOS 前置条件（Node.js / npm） ​

OpenSpec 的 CLI 通过 npm 安装，因此你需要先有 Node.js 环境。

bash
node -v
npm -v

如果你还没装 Node.js，常见方式是用 Homebrew 安装（或使用 nvm 管理多版本 Node）。

1）安装 CLI ​

如果你用的是官方 OpenSpec（Fission-AI/OpenSpec）：

bash
npm install -g @fission-ai/openspec@latest
openspec --version

可选：在 macOS（zsh）里安装命令补全（更好用）：

bash
openspec completion install

2）在项目里初始化（生成 Cursor 所需的技能/命令） ​

在你的仓库根目录运行：

bash
openspec init --tools cursor

初始化后，项目里通常会出现这些内容（不同版本可能略有差异）：

  • openspec/
    • specs/：项目“长期有效”的规格说明（事实来源）
    • changes/：每次要做的变更（一个变更一个目录）
    • config.yaml：OpenSpec 项目配置（schema、上下文、规则等）
  • .cursor/skills/：Cursor 用来识别 OpenSpec 能力的技能文件
  • .cursor/commands/：Cursor 的 OPSX 命令文件（用于在聊天输入框里触发工作流）

如果你更新了 OpenSpec 版本，建议在项目里再跑一次：

bash
openspec update

在 Cursor 里怎么用（最短闭环） ​

OpenSpec 的常见闭环是：

  • 探索：把需求/方案想清楚
  • 提案与制品生成：生成 proposal/specs/design/tasks
  • 实施：按 tasks 写代码
  • 校验：检查“实现是否符合制品”
  • 归档：把这次变更收口，留下可追溯记录

下面给一条“最短上手路径”（建议第一次就按这个跑通）。

场景：拿到一个新项目，想让它先“阅读项目”再自动生成文件 ​

你在 Cursor 聊天输入框里，主要就用下面两条（先选一种即可）：

  • 引导式（第一次推荐）：/opsx-onboard（或 /opsx:onboard）
    • 会先阅读你的仓库，并带你走完一次完整流程
  • 直接生成制品文件（最常用）：/opsx-propose <变更描述>（或 /opsx:propose ...）
    • 会读取代码库作为上下文，然后在 openspec/changes/<change>/ 里生成 proposal/specs/design/tasks 等文件

注意：OpenSpec 生成文件是围绕某个 change（变更） 来做的，所以你需要给它一句“要做什么”的描述（例如新增功能/修复 bug/重构模块）。

可直接复制的输入框示例 ​

text
/opsx-onboard
text
/opsx-propose 给现有登录流程增加“图形验证码”，并补齐错误提示与验收标准
text
/opsx-propose refactor-api-client 把 fetch 封装统一到一个模块，并给出迁移任务清单

0）确认 Cursor 里命令前缀（很重要） ​

不同集成会出现两种写法之一：

  • 冒号风格：/opsx:propose、/opsx:apply…
  • 短横线风格（Cursor 常见）：/opsx-propose、/opsx-apply…

你在 Cursor 聊天输入框里打一个 /opsx，看自动补全出来的是哪一种，用你看到的那种即可。

0.5）新项目初始化（终端执行一次） ​

在项目根目录执行：

bash
# 1) 安装（若已安装可跳过）
npm install -g @fission-ai/openspec@latest

# 2) 初始化 Cursor 集成（生成 .cursor/commands 与 .cursor/skills）
openspec init --tools cursor

# 3) 升级后/命令缺失时，重新生成一次
openspec update

然后 重启 Cursor，回到聊天框输入 /opsx 检查命令是否出现。

1）先探索（可选但强烈推荐） ​

当你还没想清楚改什么、或者需要先读代码/对比方案时：

  • /opsx:explore（或 /opsx-explore）

这一步的目标不是产出文件，而是把问题范围、约束、验收标准先聊清楚，避免后面制品写一堆最后全推翻。

1.5）想“自动读项目并带你跑一遍”？用引导式命令（推荐第一次） ​

  • /opsx:onboard（或 /opsx-onboard）

它会先扫描你的仓库，再引导你完成一次完整闭环：创建变更 → 生成制品 → 实施 → 校验 → 归档。

2）一键创建变更并生成规划制品（推荐起手式） ​

直接在 Cursor 聊天里输入：

  • /opsx:propose add-dark-mode

add-dark-mode 也可以换成一句中文描述（例如“给文章页增加目录吸顶”）。执行后会在 openspec/changes/<change>/ 下生成一组规划制品，常见包括：

  • proposal.md：为什么做、影响面、风险/回滚
  • specs/**：可验证的需求（场景/验收标准）
  • design.md：技术方案与关键决策
  • tasks.md：可执行任务清单（一般是复选框）

补充：如果你想“只生成文件（proposal/specs/design/tasks）先不写代码”，就先停在这一步，打开这些文件审一下、改一下，再进入 /opsx:apply。

3）按任务实施写代码 ​

当 tasks.md 已经准备好之后：

  • /opsx:apply（或 /opsx-apply）

OpenSpec 会引导 AI 逐项完成 tasks，并将完成项打勾。中途被打断也没关系，下次继续 /opsx:apply 通常会从未完成任务接着做。

4）校验“实现是否符合制品” ​

  • /opsx:verify（或 /opsx-verify）

它会从三个角度检查并给出问题清单：

  • 完整性：任务是否都做了、需求是否都覆盖
  • 正确性：实现是否符合 specs 的意图、边界情况是否处理
  • 一致性：代码结构是否反映 design 的决策（命名/模式/约定）

5）归档本次变更（收口） ​

  • /opsx:archive（或 /opsx-archive）

归档的意义是把这次变更从“进行中 changes”转成“历史记录”，并在需要时把增量规格合并回主 openspec/specs/（不同配置下可能会提示你同步）。

想更“可控”？使用扩展工作流命令 ​

上面的 /opsx:propose 是“最快路径”。如果你希望每个制品都能一份一份生成、边看边改，可以启用扩展命令（不同版本叫法可能略不同，但思路一致）：

  • 先创建变更骨架：/opsx:new
  • 按依赖逐个生成制品：/opsx:continue
  • 一次性快速生成全部规划制品：/opsx:ff
  • 把增量 specs 合并回主 specs（可选）：/opsx:sync
  • 批量归档多个变更（适合并行变更）：/opsx:bulk-archive
  • 引导式教程：/opsx:onboard

如果你在 Cursor 里看不到这些命令，通常是因为当前 profile 只启用了 core 工作流。你可以在终端里调整（以官方 OpenSpec 为例）：

bash
openspec config profile
openspec update

然后回到 Cursor 再试 /opsx 的自动补全。

openspec/config.yaml：让 AI 更懂你的项目（强烈建议写） ​

OpenSpec 生成制品的质量，很大程度取决于你给它的“项目上下文”。你可以在 openspec/config.yaml 里写：

  • schema：默认工作流（常见是 spec-driven）
  • context：技术栈、目录结构、命名约定、测试框架、发布流程等
  • rules：对不同制品的额外要求（例如 specs 必须 Given/When/Then、proposal 必须包含回滚方案）

它的目标是把你平时口头会说的“我们项目是这样写的”固化下来，减少 AI 猜测。

常见问题与排查 ​

1）Cursor 里输入 /opsx... 没反应/没有补全 ​

可以按这个顺序排：

  • 确认项目初始化过：仓库里是否有 openspec/、.cursor/skills/、.cursor/commands/
  • 重新生成：运行 openspec update
  • 重启 Cursor：部分情况下需要重启让命令/技能重新被索引

2）命令写法不对（冒号还是短横线？） ​

Cursor 常见是短横线：

  • /opsx-propose、/opsx-apply

但有些文档会写成冒号：

  • /opsx:propose、/opsx:apply

以你 Cursor 的 / 自动补全为准。

3）找不到 change / 不知道当前在操作哪个变更 ​

  • 在命令后面显式指定变更名（例如 /opsx-apply add-dark-mode）
  • 或者用 CLI 看一眼当前变更列表（官方 OpenSpec）：
bash
openspec list
openspec status --json

4）生成的制品质量一般、太空泛 ​

通常是因为 context 太少或验收标准不清晰：

  • 在 proposal/specs 里补充边界条件、非功能性要求（性能/可用性/兼容性）
  • 把“验收标准”写成可检查的条目（页面上看到什么、接口返回什么、哪些错误要提示）
  • 在 openspec/config.yaml 的 rules 里强制格式（例如 Given/When/Then）

一个最小示例（你可以直接照着跑） ​

在 Cursor 聊天里：

  • /opsx-explore：先确认“要改什么、验收是什么”
  • /opsx-propose improve-blog-search：生成制品
  • 打开 openspec/changes/improve-blog-search/tasks.md 看任务清单
  • /opsx-apply improve-blog-search：按任务实现
  • /opsx-verify improve-blog-search：对齐制品
  • /opsx-archive improve-blog-search：归档

跑通一次后，你就能把它当作日常开发的默认流程：先写清楚，再动手；写完能对照验收；最后能追溯。

示例脚本（macOS / zsh）：一键初始化 OpenSpec（新项目常用） ​

把下面脚本保存为 openspec-bootstrap.zsh，在项目根目录执行：

bash
chmod +x ./openspec-bootstrap.zsh
./openspec-bootstrap.zsh

脚本内容：

bash
#!/usr/bin/env zsh
# OpenSpec 一键初始化脚本（macOS / zsh）
# 用途：把“检查环境 → 安装 openspec → init Cursor 集成 → update 生成文件”串起来，避免漏步骤。
set -euo pipefail

# [可选] 如果你不想每次都升级 openspec，可以把第 2 步删掉（保留 init/update 即可）。

echo "[1/4] Check Node.js & npm"
# 1) 检查 node/npm 是否存在；没有就提示安装（OpenSpec 通过 npm 安装）
command -v node >/dev/null 2>&1 || { echo "node not found. Please install Node.js first."; exit 1; }
command -v npm  >/dev/null 2>&1 || { echo "npm not found. Please install npm first."; exit 1; }
node -v
npm -v

echo "[2/4] Install/Upgrade OpenSpec CLI"
# 2) 安装/升级 OpenSpec CLI（全局）
npm i -g @fission-ai/openspec@latest
openspec --version

echo "[3/4] Init OpenSpec for Cursor (run in project root)"
# 3) 初始化项目（生成 openspec/ 目录 + Cursor 所需的 .cursor/commands/.cursor/skills）
#    如果你还想同时生成其他工具集成，可以改成：openspec init --tools cursor,claude
openspec init --tools cursor

echo "[4/4] Update generated Cursor files"
# 4) 重新生成指令文件（常用于 CLI 升级后、命令缺失/不更新时）
openspec update

cat <<'EOF'

Done.

Next (in Cursor Chat):
- Type "/opsx" and pick the autocomplete commands.
- Recommended first run: /opsx-onboard
- Or generate artifacts directly: /opsx-propose <your-change-description>

Tips:
- If you can't see opsx commands, restart Cursor after init/update.
- Use the exact command style Cursor suggests: /opsx-xxx or /opsx:xxx

EOF

常用命令速查（Cursor 输入框） ​

以 Cursor 输入框 /opsx 的自动补全为准：你看到的是 /opsx-xxx 就用短横线；如果是 /opsx:xxx 就用冒号。

快速闭环（最常用） ​

  • 创建变更 + 自动生成规划制品：/opsx-propose <变更描述或变更名>
  • 按 tasks 实施：/opsx-apply [change-name]
  • 校验实现与制品一致：/opsx-verify [change-name]
  • 归档变更（收口）：/opsx-archive [change-name]

示例：

text
/opsx-propose 给文章页增加目录吸顶，并补齐验收标准
/opsx-apply
/opsx-verify
/opsx-archive

先读项目再开始（适合第一次） ​

  • 引导式完整流程：/opsx-onboard
  • 探索/调研（不产出制品）：/opsx-explore [topic]

示例：

text
/opsx-onboard
text
/opsx-explore 这个项目的鉴权是怎么做的？有哪些入口？

更可控的制品生成（逐步/批量） ​

  • 只创建变更骨架：/opsx-new [change-name]
  • 创建下一个制品：/opsx-continue [change-name]
  • 一次生成所有规划制品：/opsx-ff [change-name]

维护与合并 ​

  • 同步增量 specs 到主 specs（可选）：/opsx-sync [change-name]
  • 批量归档多个变更：/opsx-bulk-archive [change-names...]
最近更新