[[[[Switch to English]]]]

OPSX 工作流

OPSX (OpenSpec Experience) 是 OpenSpec 的工件驱动工作流。它旨在使 AI 辅助开发流畅、透明且由开发者控制。

核心理念

行动胜于阶段 (Actions over Phases)

旧的工作流有僵化的“阶段”（规划 → 规格 → 设计）。OPSX 关注 行动：

• 创建提案
• 阐明需求
• 起草任务
• 验证代码

您可以按任何顺序执行这些操作。需要先写代码再写规格？可以。想跳过设计直接进入任务？没问题。

工件作为控制点 (Artifacts as Control Points)

每个工件（文档）都是您可以检查、编辑和指导 AI 的检查点。

• Proposal: "我们要构建这个吗？"
• Specs: "这是正确的行为吗？"
• Design: "这是正确的技术方法吗？"
• Tasks: "这是正确的实施计划吗？"

智能体与人类协作 (Agent-Human Protocol)

OPSX 定义了一个协议，您和 AI 在其中拥有明确的角色：

• 您 提供意图、审查工件并做出决定。
• AI 生成草稿、验证一致性并编写样板代码。
• CLI 管理状态并保持一切同步。

---

组件架构

OPSX 由三个主要部分组成：

1. Schemas

Schemas 定义了工作流的“形状”。它们指定：

• 哪些工件存在（例如 proposal, design）
• 它们如何相互依赖
• 用什么模板生成它们

默认 Schema 是 spec-driven，但您可以为不同类型的工作（例如 research-first, bug-fix, exploration）创建自定义 Schema。

2. 图形引擎 (Graph Engine)

在幕后，OpenSpec 维护着工件的依赖图。 当您运行 /opsx:continue 时，引擎会：

1. 查看图表
2. 检查哪些工件已完成
3. 识别下一步可以创建什么
4. 提示 AI 生成它

3. Skills

AI 通过 Skills 与 OpenSpec 交互。这些是向 AI 解释如何使用 CLI 以及命令意味着什么的定义。

• openspec-cli.md: 教 AI 如何运行终端命令
• openspec-slash.md: 教 AI 如何响应 /opsx: 命令

---

用户体验

1. 探索 (Exploration)

通常您从一个模糊的想法开始。

/opsx:explore "我们应该如何处理移动端离线支持？"

这不会创建任何文件。它只是您和 AI 之间的对话，可以访问您的代码库。您可以集思广益，比较选项，直到您准备好继续。

2. 启动 (Inception)

一旦您知道要做什么：

/opsx:new add-offline-mode

这会创建一个变更文件夹。此时文件夹几乎是空的，只有一个配置文件。

3. 规划 (Planning)

您有两个速度选项：

选项 A：逐步 (Step-by-Step) 使用 /opsx:continue 逐个生成工件。

• 创建提案 → 您审查它。
• 创建规格 → 您审查它。
• 创建设计 → 您审查它。 如果您在构建复杂的东西并且想要严格的控制，这很好。

选项 B：快进 (Fast-Forward) 使用 /opsx:ff 一次生成所有规划工件。 AI 将根据依赖链全速前进。 如果您的想法清晰且任务简单，这很好。

4. 实施 (Implementation)

/opsx:apply

AI 读取 tasks.md 并开始工作。它会：

1. 选择第一个未完成的任务
2. 为了该任务编写代码/测试
3. 标记任务完成
4. 重复直到完成或需要输入

5. 验证 (Verification)

实施后，您想知道它是否符合规格。

/opsx:verify

此命令进行“三向握手”检查：

1. 规格 说它应该做什么
2. 任务 说要做什么
3. 代码 实际做了什么

它会报告任何不一致之处。

6. 完成 (Completion)

/opsx:archive

这会将您的变更封装起来：

• 将增量规格合并到事实来源
• 将变更文件夹移动到归档
• 保持您的工作区清洁

---

最佳实践

尽早编辑，经常编辑

不要害怕编辑生成的工件。如果 AI 写了一个您不喜欢的提案，直接编辑 proposal.md。如果设计偏离了方向，在运行 /opsx:apply 之前修复 design.md。

工件是您的指令。 它们越好，实施就越好。

使用上下文

在您的 config.yaml 中放置全局上下文。

• 编码约定
• 架构模式
• 库偏好

AI 在生成工件时会读取此上下文。

混合模式

您可以混合使用 CLI 和聊天。

• 在聊天中运行 /opsx:new。
• 在编辑器中手动调整 specs/。
• 在终端中运行 openspec validate。
• 回到聊天中运行 /opsx:apply。

状态在文件系统上，所以工具总是同步的。

保持变更小

OPSX 最适合中小型变更。如果您发现自己在写巨大的规格，考虑将其拆分为两个变更。

• add-offline-basic（基础）
• add-offline-sync（同步逻辑）

相信但要验证

始终运行 /opsx:verify。令人惊讶的是，仅仅是要求 AI 检查它自己的工作就能捕捉到多少细微的 bug。