欢迎在 Discord 上反馈意见。
OPSX 现在是 OpenSpec 的标准工作流。
它是 OpenSpec 变更的灵活、迭代式工作流。不再有僵化的阶段——你可以随时采取任何行动。
传统的 OpenSpec 工作流程虽然可用，但它是封闭的：
- 指令是硬编码的——埋在 TypeScript 中，你无法修改
- 全有或全无——一个大命令创建所有内容，无法单独测试各个部分
- 固定结构——所有人都用相同的工作流，无法定制
- 黑盒——当 AI 输出不理想时，你无法调整提示词
OPSX 打开了它。 现在任何人都可以：
- 尝试指令——编辑模板，看看 AI 是否做得更好
- 细粒度测试——独立验证每个制品的指令
- 自定义工作流——定义你自己的制品和依赖关系
- 快速迭代——更改模板，立即测试，无需重新构建
传统工作流： OPSX：
┌────────────────────────┐ ┌────────────────────────┐
│ 硬编码在包中 │ │ schema.yaml │◄── 你编辑这个
│ (无法修改) │ │ templates/*.md │◄── 或这个
│ ↓ │ │ ↓ │
│ 等待新版本发布 │ │ 立即生效 │
│ ↓ │ │ ↓ │
│ 希望它变得更好 │ │ 自己测试 │
└────────────────────────┘ └────────────────────────┘
这适用于所有人：
- 团队——创建符合实际工作方式的工作流
- 高级用户——调整提示词以获得更好的代码库 AI 输出
- OpenSpec 贡献者——无需发布即可尝试新方法
我们都在学习什么方法最有效。OPSX 让我们一起学习。
线性工作流的问题： 你处于"规划阶段"，然后是"实施阶段"，然后是"完成"。但实际工作并非如此。你实施了一些东西，意识到设计有问题，需要更新规格，继续实施。线性阶段与实际工作方式相冲突。
OPSX 方法：
- 行动，而非阶段——创建、实施、更新、归档——随时可以执行任何操作
- 依赖关系是赋能者——它们显示什么可以做，而不是下一步必须做什么
提案 ──→ 规格 ──→ 设计 ──→ 任务 ──→ 实施
# 确保已安装 openspec-cn — 技能会自动生成
openspec-cn init这会在 .claude/skills/（或等效目录）中创建技能，AI 编码助手会自动检测这些技能。
在设置过程中，系统会提示你创建项目配置（openspec/config.yaml）。这是可选的，但推荐这样做。
项目配置允许你设置默认值并向所有制品注入项目特定的上下文。
配置在 openspec-cn init 期间创建，或手动创建：
# openspec/config.yaml
schema: spec-driven
context: |
技术栈：TypeScript、React、Node.js
API 约定：RESTful、JSON 响应
测试：Vitest 用于单元测试、Playwright 用于端到端测试
代码风格：ESLint 搭配 Prettier、严格 TypeScript
rules:
proposal:
- 包含回滚计划
- 识别受影响的团队
specs:
- 使用 Given/When/Then 格式描述场景
design:
- 为复杂流程包含序列图| 字段 | 类型 | 描述 |
|---|---|---|
schema |
string | 新变更的默认模式（例如 spec-driven） |
context |
string | 注入到所有制品指令中的项目上下文 |
rules |
object | 按制品 ID 分类的制品特定规则 |
模式优先级（从高到低）：
- CLI 标志（
--schema <name>） - 变更元数据（变更目录中的
.openspec.yaml） - 项目配置（
openspec/config.yaml） - 默认值（
spec-driven）
上下文注入：
- 上下文会附加到每个制品指令的前面
- 用
<context>...</context>标签包裹 - 帮助 AI 理解你项目的约定
规则注入：
- 规则只为匹配的制品注入
- 用
<rules>...</rules>标签包裹 - 出现在上下文之后、模板之前
spec-driven（默认）：
proposal— 变更提案specs— 规格design— 技术设计tasks— 实施任务
rules中未知的制品 ID 会生成警告- 模式名称会根据可用模式进行验证
- 上下文有 50KB 的大小限制
- 无效的 YAML 会报告行号
"规则中有未知的制品 ID：X"
- 检查制品 ID 是否与你的模式匹配（参见上面的列表）
- 运行
openspec-cn schemas --json查看每个模式的制品 ID
配置未生效：
- 确保文件位于
openspec/config.yaml（不是.yml） - 使用验证器检查 YAML 语法
- 配置更改会立即生效（无需重启）
上下文过大：
- 上下文限制为 50KB
- 改为总结或链接到外部文档
| 命令 | 功能 |
|---|---|
/opsx:explore |
深入思考想法、调查问题、明确需求 |
/opsx:new |
开始新变更 |
/opsx:continue |
创建下一个制品（基于已准备好的） |
/opsx:ff |
快进——一次性创建所有规划制品 |
/opsx:apply |
实施任务，必要时更新制品 |
/opsx:sync |
将增量规格同步到主线（可选——如需要则提示归档） |
/opsx:archive |
完成后归档 |
/opsx:explore
深入思考想法、调查问题、比较选项。不需要结构——只是一个思考伙伴。当洞察力成型时，过渡到 /opsx:new 或 /opsx:ff。
/opsx:new
你将被问及想要构建什么以及使用哪个工作流模式。
/opsx:continue
根据依赖关系显示可以创建什么，然后创建一个制品。重复使用以逐步构建变更。
/opsx:ff add-dark-mode
一次性创建所有规划制品。当你对要构建的内容有清晰认识时使用。
/opsx:apply
逐个处理任务并勾选。如果你同时处理多个变更，可以运行 /opsx:apply <name>；否则它应该根据对话推断，如果无法确定则会提示你选择。
/opsx:archive # 完成后移动到归档（如需要会提示同步规格）
实施前你总是可以编辑提案或规格。但何时优化变成了"这是不同的工作"？
提案定义了三件事：
- 意图——你在解决什么问题？
- 范围——什么在内、什么在外？
- 方法——你将如何解决它？
问题是：哪一项改变了，改变了多少？
相同的意图，改进的实施
- 你发现了没有考虑到的边界情况
- 方法需要调整但目标不变
- 实施揭示设计略有偏差
范围缩小
- 你意识到完整范围太大，想先发布 MVP
- "添加暗色模式" → "添加暗色模式切换（v2 中的系统首选项）"
学习驱动的修正
- 代码库结构不像你想象的那样
- 依赖项不像预期那样工作
- "使用 CSS 变量" → "改用 Tailwind 的 dark: 前缀"
意图根本改变
- 问题本身现在不同了
- "添加暗色模式" → "添加包含自定义颜色、字体、间距的全面主题系统"
范围爆炸
- 变更增长太大，本质上是不同的工作
- 更新后原始提案将无法识别
- "修复登录错误" → "重写认证系统"
原始可完成
- 原始变更可以标记为"完成"
- 新工作独立存在，不是改进
- 完成"添加暗色模式 MVP" → 归档 → 新变更"增强暗色模式"
┌─────────────────────────────────────┐
│ 这是相同的工作吗？ │
└──────────────┬──────────────────────┘
│
┌──────────────────┼──────────────────┐
│ │ │
▼ ▼ ▼
相同意图？ >50% 重叠？ 原始可以
相同问题？ 相同范围？ 在没有这些
│ │ 变更的情况下
│ │ "完成"？
┌────────┴────────┐ ┌──────┴──────┐ ┌───────┴───────┐
│ │ │ │ │ │
是的 否 是的 否 否 是的
│ │ │ │ │ │
▼ ▼ ▼ ▼ ▼ ▼
更新 新 更新 新 更新 新
| 测试 | 更新 | 新变更 |
|---|---|---|
| 同一性 | "同一件事，改进了" | "不同的工作" |
| 范围重叠 | >50% 重叠 | <50% 重叠 |
| 完成度 | 如果没有更改就无法"完成" | 可以完成原始工作，新工作独立存在 |
| 连贯性 | 更新链讲述连贯的故事 | 补丁比澄清更令人困惑 |
更新保留上下文。新变更提供清晰度。
当你思考的历史有价值时选择更新。 当重新开始比打补丁更清晰时选择新变更。
把它想象成 git 分支：
- 在处理相同功能时继续提交
- 当它确实是新工作时开始新分支
- 有时合并部分功能并为第二阶段重新开始
Legacy (/openspec:proposal) |
OPSX (/opsx:*) |
|
|---|---|---|
| 结构 | 一个大的提案文档 | 具有依赖关系的离散制品 |
| 工作流 | 线性阶段：规划 → 实施 → 归档 | 灵活行动——随时做任何事情 |
| 迭代 | 很难回头 | 在学习时更新制品 |
| 定制 | 固定结构 | 模式驱动（定义你自己的制品） |
关键洞察： 工作不是线性的。OPSX 不再假装它是。
本节解释 OPSX 在底层的工作原理以及它与传统工作流的比较。
┌─────────────────────────────────────────────────────────────────────────────┐
│ 传统工作流 │
│ (阶段锁定，全有或全无) │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ 规划 │ ───► │ 实施 │ ───► │ 归档 │ │
│ │ 阶段 │ │ 阶段 │ │ 阶段 │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ /opsx:proposal /opsx:apply /opsx:archive │
│ │
│ • 一次性创建所有制品 │
│ • 实施期间无法返回更新规格 │
│ • 阶段关卡强制线性进展 │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────┐
│ OPSX 工作流 │
│ (灵活行动，迭代式) │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌────────────────────────────────────────────┐ │
│ │ 行动（非阶段） │ │
│ │ │ │
│ │ new ◄──► continue ◄──► apply ◄──► archive │ │
│ │ │ │ │ │ │ │
│ │ └──────────┴───────────┴───────────┘ │ │
│ │ 任意顺序 │ │
│ └────────────────────────────────────────────┘ │
│ │
│ • 一次创建一个制品或快进 │
│ • 实施期间更新规格/设计/任务 │
│ • 依赖关系促进进展，阶段不存在 │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
传统工作流使用 TypeScript 中的硬编码模板：
┌─────────────────────────────────────────────────────────────────────────────┐
│ 传统工作流组件 │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ 硬编码模板（TypeScript 字符串） │
│ │ │
│ ▼ │
│ 配置器（18+ 个类，每个编辑器一个） │
│ │ │
│ ▼ │
│ 生成的命令文件（.claude/commands/openspec/*.md） │
│ │
│ • 固定结构，无制品感知 │
│ • 更改需要代码修改 + 重新构建 │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
OPSX使用外部模式和依赖关系图引擎：
┌─────────────────────────────────────────────────────────────────────────────┐
│ OPSX 组件 │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ 模式定义（YAML） │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ name: spec-driven │ │
│ │ artifacts: │ │
│ │ - id: proposal │ │
│ │ generates: proposal.md │ │
│ │ requires: [] ◄── 依赖关系 │ │
│ │ - id: specs │ │
│ │ generates: specs/**/*.md ◄── Glob 模式 │ │
│ │ requires: [proposal] ◄── 提案后启用 │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ 制品图引擎 │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ • 拓扑排序（依赖关系排序） │ │
│ │ • 状态检测（文件系统存在） │ │
│ │ • 丰富的指令生成（模板 + 上下文） │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ 技能文件（.claude/skills/openspec-*/SKILL.md） │
│ │
│ • 跨编辑器兼容（Claude Code、Cursor、Windsurf） │
│ │ • 技能查询 CLI 以获取结构化数据 │ │
│ │ • 通过模式文件完全可定制 │ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
制品形成有向无环图（DAG）。依赖关系是赋能者，而不是关卡：
提案
(根节点)
│
┌─────────────┴─────────────┐
│ │
▼ ▼
规格 设计
(requires: (requires:
proposal) proposal)
│ │
└─────────────┬─────────────┘
│
▼
任务
(requires:
specs, design)
│
▼
┌──────────────┐
│ 实施阶段 │
│ (requires: │
│ tasks) │
└──────────────┘
状态转换：
阻塞 ────────────────► 就绪 ────────────────► 完成
│ │ │
缺少 所有依赖 文件存在于
依赖 都已完成 文件系统上
传统工作流——代理接收静态指令：
用户: "/opsx:proposal"
│
▼
┌─────────────────────────────────────────┐
│ 静态指令： │
│ • 创建 proposal.md │
│ • 创建 tasks.md │
│ • 创建 design.md │
│ • 创建 specs/<capability>/spec.md │
│ │
│ 不感知已存在的内容或 │
│ 制品之间的依赖关系 │
└─────────────────────────────────────────┘
│
▼
代理一次性创建所有制品
OPSX——代理查询丰富的上下文：
用户: "/opsx:continue"
│
▼
┌──────────────────────────────────────────────────────────────────────────┐
│ 步骤 1：查询当前状态 │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ $ openspec-cn status --change "add-auth" --json │ │
│ │ │ │
│ │ { │ │
│ │ "artifacts": [ │ │
│ │ {"id": "proposal", "status": "done"}, │ │
│ │ {"id": "specs", "status": "ready"}, ◄── 首个就绪 │ │
│ │ {"id": "design", "status": "ready"}, │ │
│ │ {"id": "tasks", "status": "blocked", "missingDeps": ["specs"]}│ │
│ │ ] │ │
│ │ } │ │
│ └────────────────────────────────────────────────────────────────────┘ │
│ │
│ 步骤 2：获取就绪制品的丰富指令 │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ $ openspec-cn instructions specs --change "add-auth" --json │ │
│ │ │ │
│ │ { │ │
│ │ "template": "# Specification\n\n## ADDED Requirements...", │ │
│ │ "dependencies": [{"id": "proposal", "path": "...", "done": true}│ │
│ │ "unlocks": ["tasks"] │ │
│ │ } │ │
│ └────────────────────────────────────────────────────────────────────┘ │
│ │
│ 步骤 3：读取依赖 → 创建一个制品 → 显示解锁的内容 │
└──────────────────────────────────────────────────────────────────────────┘
传统工作流——迭代很困难：
┌─────────┐ ┌─────────┐ ┌─────────┐
│/proposal│ ──► │ /apply │ ──► │/archive │
└─────────┘ └─────────┘ └─────────┘
│ │
│ ├── "等等，设计错了"
│ │
│ ├── 选项：
│ │ • 手动编辑文件（破坏上下文）
│ │ • 放弃并重新开始
│ │ • 推进并稍后修复
│ │
│ └── 没有官方的"返回"机制
│
└── 一次性创建所有制品
OPSX——自然迭代：
/opsx:new ───► /opsx:continue ───► /opsx:apply ───► /opsx:archive
│ │ │
│ │ ├── "设计错了"
│ │ │
│ │ ▼
│ │ 直接编辑 design.md
│ │ 然后继续！
│ │ │
│ │ ▼
│ │ /opsx:apply 会从
│ │ 你中断的地方继续
│ │
│ └── 创建一个制品，显示解锁的内容
│
└── 搭建变更，等待指示
使用模式管理命令创建自定义工作流：
# 从零开始创建新模式（交互式）
openspec-cn schema init my-workflow
# 或分叉现有模式作为起点
openspec-cn schema fork spec-driven my-workflow
# 验证模式结构
openspec-cn schema validate my-workflow
# 查看模式的解析位置（对调试有用）
openspec-cn schema which my-workflow模式存储在 openspec/schemas/（项目本地，版本控制）或 ~/.local/share/openspec/schemas/（用户全局）。
模式结构：
openspec/schemas/research-first/
├── schema.yaml
└── templates/
├── research.md
├── proposal.md
└── tasks.md
示例 schema.yaml：
name: research-first
artifacts:
- id: research # 在提案之前添加
generates: research.md
requires: []
- id: proposal
generates: proposal.md
requires: [research] # 现在依赖于研究
- id: tasks
generates: tasks.md
requires: [proposal]依赖关系图：
研究 ──► 提案 ──► 任务
| 方面 | 传统 | OPSX |
|---|---|---|
| 模板 | 硬编码的 TypeScript | 外部 YAML + Markdown |
| 依赖关系 | 无（一次性全部） | DAG 与拓扑排序 |
| 状态 | 基于阶段的心理模型 | 文件系统存在 |
| 定制 | 编辑源码，重新构建 | 创建 schema.yaml |
| 迭代 | 阶段锁定 | 灵活，可编辑任何内容 |
| 编辑器支持 | 18+ 个配置器类 | 单个技能目录 |
模式定义了存在的制品及其依赖关系。当前可用：
- spec-driven（默认）：提案 → 规格 → 设计 → 任务
# 列出可用模式
openspec-cn schemas
# 查看所有模式及其解析来源
openspec-cn schema which --all
# 交互式创建新模式
openspec-cn schema init my-workflow
# 分叉现有模式以进行定制
openspec-cn schema fork spec-driven my-workflow
# 使用前验证模式结构
openspec-cn schema validate my-workflow- 在承诺变更之前使用
/opsx:explore深入思考想法 - 当你知道想要什么时使用
/opsx:ff，探索时使用/opsx:continue - 在
/opsx:apply期间，如果有问题——修复制品，然后继续 - 任务通过
tasks.md中的复选框跟踪进度 - 随时检查状态：
openspec-cn status --change "name"
这还比较粗糙。这是有意为之——我们正在学习什么有效。