⚙️ 实现原理
整体架构
┌──────────────────────────────────────────────────────┐
│ openspec/ │
│ ┌──────────────────┐ ┌────────────────────────┐ │
│ │ specs/ │◄───│ changes/ │ │
│ │ (source of truth)│ │ (proposed changes) │ │
│ │ 系统当前行为 │ merge │ 每个变更=一个文件夹 │ │
│ └──────────────────┘ └────────────────────────┘ │
└──────────────────────────────────────────────────────┘
核心数据结构
Specs（规范） — 系统的行为描述，描述"是什么"，包含需求（Requirements）和场景（Scenarios），采用 GIVEN/WHEN/THEN 格式。
Changes（变更） — 提议的修改，封装为独立文件夹，包含 proposal、design、tasks、delta specs。
Delta Specs（增量规范） — 描述相对于当前规范的变化（新增/修改/删除），而非重写整个规范，这是 brownfield 开发的关键。
Artifact 流程
proposal ──► specs ──► design ──► tasks ──► implement
│ │ │ │
why what how steps
📖 Workflows 工作流详解（中英对照）
以下为 OpenSpec 官方 workflows.md 的中文翻译，保持技术术语原文。
核心理念：动作而非阶段
传统工作流强制你按阶段推进：先规划，再实现，然后完成。但实际工作并不按这种僵硬的盒子运转。OPSX 采用不同方式：
传统方式（阶段锁定）:
PLANNING ────────► IMPLEMENTING ────────► DONE
│ │
│ "无法回退" │
└────────────────────┘
OPSX 方式（流畅动作）:
proposal ──► specs ──► design ──► tasks ──► implement
核心原则：
- 动作而非阶段 — 命令是你能做的事，而非被困住的阶段
- 依赖是使能器 — 它们展示可能的事，而非下一步必需的事
两种模式
默认快速路径（core profile）
新安装默认为 core，提供：/opsx:propose、/opsx:explore、/opsx:apply、/opsx:archive
/opsx:propose ──► /opsx:apply ──► /opsx:archive
完整工作流（扩展模式）
启用所有命令：/opsx:new、/opsx:continue、/opsx:ff、/opsx:verify、/opsx:sync、/opsx:bulk-archive
openspec config profile → openspec update
工作流模式（扩展模式）
快速功能（Quick Feature）
当你明确知道要构建什么，只需执行时使用：
/opsx:new ──► /opsx:ff ──► /opsx:apply ──► /opsx:verify ──► /opsx:archive
示例对话：
你: /opsx:new add-logout-button
AI: 已创建 openspec/changes/add-logout-button/
准备创建：proposal
你: /opsx:ff
AI: 正在创建所有规划 artifacts...
✓ proposal.md
✓ specs/
✓ design.md
✓ tasks.md
准备开始实现！
你: /opsx:apply
AI: 正在执行 tasks...
✓ 已添加 logout 按钮到 header
✓ 已实现 session 清理
✓ 已添加确认对话框
所有 tasks 完成！
你: /opsx:archive
AI: ✓ 已合并 specs
✓ 已归档变更
最佳适用场景：中小型功能、Bug 修复、直接了当的变更
探索模式（Exploratory）
当需求不明确或需要先调研时使用：
/opsx:explore ──► /opsx:new ──► /opsx:continue ──► ... ──► /opsx:apply
示例对话：
你: /opsx:explore
AI: 你想探索什么？
你: 我想改善页面加载性能，但不确定瓶颈在哪里。
AI: 让我帮你调研...
[分析 bundle sizes，识别 slow queries，
审查 component render patterns]
我发现三个主要瓶颈：
1. 大尺寸未优化图片
2. ProductList 中同步数据获取
3. Context 变化导致的 re-renders
你想先解决哪个？
你: 我们先处理数据获取问题吧。
你: /opsx:new optimize-product-list-fetching
AI: 已创建变更。准备创建：proposal
你: /opsx:continue
AI: 基于调研结果创建 proposal...
[整合调研洞察撰写 proposal]
准备创建：specs, design
你想先做哪个？
你: /opsx:continue
AI: 正在创建 specs...
最佳适用场景：性能优化、调试、架构决策、需求不明确的场景
并行变更（Parallel Changes）
同时处理多个变更：
变更 A: /opsx:new ──► /opsx:ff ──► /opsx:apply (进行中)
│
context switch
│
变更 B: /opsx:new ──► /opsx:ff ─────────► /opsx:apply
示例对话：
你: 我正在做 add-dark-mode，但被拉去修一个 bug
你: /opsx:new fix-login-redirect
AI: 已创建 openspec/changes/fix-login-redirect/
你: /opsx:ff
AI: ✓ 已创建规划 artifacts
你: /opsx:apply
AI: 正在处理 fix-login-redirect...
[实现修复]
所有 tasks 完成！
你: /opsx:archive
AI: ✓ 已归档 fix-login-redirect
你: 继续做 dark mode
你: /opsx:apply add-dark-mode
AI: 恢复 add-dark-mode...
从 task 2.3: Update Header... 继续
多个变更完成时，使用 /opsx:bulk-archive 批量归档，自动检测 spec 冲突并按时间顺序合并。
最佳适用场景：并行工作流、紧急中断、团队协作
变更完成流程
/opsx:apply ──► /opsx:verify ──► /opsx:archive
│ │
验证实现 提示 sync
是否符合规范 如需要
/opsx:verify — 验证检查
/opsx:verify 从三个维度验证实现与规范的一致性：
你: /opsx:verify
AI: 正在验证 add-auth...
COMPLETENESS（完整性）
✓ tasks.md 中的 12 个 tasks 已全部检查
✓ specs 中的所有 requirements 都有对应代码
⚠ Scenario "Session timeout after inactivity" 未测试
CORRECTNESS（正确性）
✓ 实现符合规范意图
✓ 场景中的 edge cases 都有处理
✓ 错误状态与 spec 定义一致
COHERENCE（一致性）
✓ 设计决策反映在代码结构中
✓ 命名规范与 design.md 一致
⚠ design 中提到 "event-driven" 但实现用的是 polling
SUMMARY（摘要）
─────────────────────────────
关键问题：0
警告：2
可以归档：是（含警告）
建议：
1. 添加 session timeout 场景的测试
2. 考虑按 design 重构为 event-driven，或更新 design.md
| 维度 | 验证内容 |
|---|
| Completeness | 所有 tasks 是否完成，所有 requirements 是否有对应代码，scenarios 是否覆盖 |
| Correctness | 实现是否符合规范意图，edge cases 是否处理，错误状态是否匹配 |
| Coherence | 设计决策是否反映在代码结构中，模式是否一致 |
/opsx:archive — 归档完成
完成变更并将其移至 archive：
你: /opsx:archive
AI: 正在归档 add-auth...
Artifact 状态：
✓ proposal.md 存在
✓ specs/ 存在
✓ design.md 存在
✓ tasks.md 存在（12/12 tasks 完成）
Delta specs：尚未 sync 到主规范
→ 是否现在 sync？
你: 是
AI: ✓ 已 sync specs 到 openspec/specs/auth/spec.md
✓ 已移动到 openspec/changes/archive/2025-01-24-add-auth/
变更归档成功。
何时用哪个命令
| 场景 | 命令 |
|---|
| 需求明确，准备好了 | /opsx:ff |
| 探索中，想逐步审查 | /opsx:continue |
| 想在 specs 前迭代 proposal | /opsx:continue |
| 时间紧迫，需要快速推进 | /opsx:ff |
| 复杂变更，想要控制 | /opsx:continue |
更新现有变更 vs 发起新变更
更新现有变更当：
- 意图相同，执行方式细化
- 范围收窄（先 MVP，其余后续）
- 基于学习的修正（codebase 不是你预期的）
- 基于实现发现的设计调整
发起新变更当：
- 意图从根本上改变
- 范围爆炸到完全不同的工作
- 原始变更可以独立"完成"
- 补丁会造成更多混淆
最佳实践
- 保持变更专注 — 每个变更一个逻辑工作单元
- 需求不明确时用 /opsx:explore — 承诺变更前先探索问题空间
- 归档前验证 — 使用 /opsx:verify 检查实现与规范的一致性
- 专注单一逻辑单元 — 易于 review 和理解，archive 历史更清晰，可独立发布，回滚更简单