txyzznc 引导用户完成第一个完整的 OpenSpec 工作流循环。这是一次教学体验——您将在他们的代码库中做真实的工作，同时讲解每个步骤。
预检
开始前，检查 OpenSpec CLI 是否已安装：
# Unix/macOS
openspec --version 2>&1 || echo "CLI_NOT_INSTALLED"
# Windows (PowerShell)
# if (Get-Command openspec -ErrorAction SilentlyContinue) { openspec --version } else { echo "CLI_NOT_INSTALLED" }
若 CLI 未安装：
OpenSpec CLI 未安装。请先安装，然后再回来使用
/opsx:onboard。
若未安装则停止。
第一阶段：欢迎
显示：
## 欢迎使用 OpenSpec！
我将引导您完成一个完整的变更循环——从想法到实现——在您的代码库中完成一个真实任务。在此过程中，您将通过实践学习工作流。
**我们将做什么：**
1. 在您的代码库中挑选一个小的真实任务
2. 简要探索问题
3. 创建变更（工作的容器）
4. 构建 artifact：proposal → specs → design → tasks
5. 实现任务
6. 归档已完成的变更
**时间：** 约 15-20 分钟
让我们先找点要做的事情。
第二阶段：任务选择
代码库分析
扫描代码库寻找小的改进机会。查找：
- TODO/FIXME 注释 - 在代码文件中搜索
TODO、FIXME、HACK、XXX - 缺少错误处理 - 吞掉错误的
catch块，没有 try-catch 的危险操作 - 没有测试的函数 - 交叉对比
src/与测试目录 - 类型问题 - TypeScript 文件中的
any类型（: any、as any） - 调试遗留物 - 非调试代码中的
console.log、console.debug、debugger语句 - 缺少验证 - 没有验证的用户输入处理程序
同时检查近期 git 活动：
# Unix/macOS
git log --oneline -10 2>/dev/null || echo "无 git 历史"
# Windows (PowerShell)
# git log --oneline -10 2>$null; if ($LASTEXITCODE -ne 0) { echo "无 git 历史" }
展示建议
根据您的分析，提出 3-4 个具体建议：
## 任务建议
基于对您代码库的扫描，以下是一些好的入门任务：
**1. [最有潜力的任务]**
位置：`src/path/to/file.ts:42`
范围：约 1-2 个文件，约 20-30 行
推荐原因：[简短说明]
**2. [第二个任务]**
位置：`src/another/file.ts`
范围：约 1 个文件，约 15 行
推荐原因：[简短说明]
**3. [第三个任务]**
位置：[位置]
范围：[估计]
推荐原因：[简短说明]
**4. 其他想法？**
告诉我您想做什么。
您对哪个任务感兴趣？（选择数字或描述您自己的）
若未发现任何问题： 退而询问用户想构建什么：
我在您的代码库中没有找到明显的快速改进点。有什么小功能您一直想添加或修复的吗？
范围限制
若用户选择或描述了过大的任务（主要功能、多天工作）：
这是个有价值的任务，但对您第一次 OpenSpec 流程来说可能偏大。
对于学习工作流，越小越好——这样您可以看到完整循环，而不会在实现细节中卡住。
**选项：**
1. **缩小范围** - [他们的任务]中最小有用的部分是什么？也许就是[具体切片]？
2. **选其他** - 其他建议之一，或其他小任务？
3. **就这个** - 若您真的想处理这个，也可以。只是会花更长时间。
您更倾向于哪种？
若用户坚持，可以继续——这是软性限制。
第三阶段：探索演示
选定任务后，简短演示探索模式：
在我们创建变更之前，让我快速展示**探索模式**——这是您在确定方向之前思考问题的方式。
花 1-2 分钟调查相关代码：
- 读取涉及的文件
- 若有帮助，画一个简短的 ASCII 图
- 记录任何注意事项
## 快速探索
[您的简短分析——发现了什么，任何注意事项]
┌─────────────────────────────────────────┐
│ [可选：若有帮助的 ASCII 图] │
└─────────────────────────────────────────┘
探索模式（`/opsx:explore`）就是用于这种思考——在实现前先调查。您随时可以使用它来思考问题。
现在让我们创建一个变更来容纳我们的工作。
暂停 - 等待用户确认后继续。
第四阶段：创建变更
讲解：
## 创建变更
OpenSpec 中的"变更"是围绕一块工作的所有思考和规划的容器。它存放在 `openspec/changes/<name>/` 中，保存您的 artifact——proposal、specs、design、tasks。
让我为我们的任务创建一个。
执行： 用推导出的 kebab-case 名称创建变更：
openspec new change "<derived-name>"
展示：
已创建：`openspec/changes/<name>/`
目录结构：
openspec/changes// ├── proposal.md ← 我们为什么要做这件事（空，我们来填） ├── design.md ← 我们如何构建它（空） ├── specs/ ← 详细需求（空） └── tasks.md ← 实现清单（空）
现在让我们填写第一个 artifact——proposal。
第五阶段：Proposal
讲解：
## Proposal
Proposal 记录我们**为什么**要进行此变更，以及它在高层面上涉及什么。这是工作的"电梯演讲"。
我将根据我们的任务起草一个。
执行： 起草 proposal 内容（暂不保存）：
这是一个 proposal 草稿：
---
## Why（为什么）
[1-2 句话说明问题/机会]
## What Changes（变更内容）
[将发生什么不同的要点]
## Capabilities（功能）
### New Capabilities（新功能）
- `<capability-name>`：[简短描述]
### Modified Capabilities（修改的功能）
<!-- 若修改现有行为 -->
## Impact（影响）
- `src/path/to/file.ts`：[变更内容]
- [其他文件，如适用]
---
这是否准确表达了意图？我可以在保存之前调整。
暂停 - 等待用户批准/反馈。
批准后保存 proposal：
openspec instructions proposal --change "<name>" --json
然后将内容写入 openspec/changes/<name>/proposal.md。
Proposal 已保存。这是您的"为什么"文档——随着理解的演进，您随时可以回来完善它。
下一步：specs。
第六阶段：Specs
讲解：
## Specs
Spec 以精确、可测试的方式定义**我们在构建什么**。它们使用需求/场景格式，使预期行为一目了然。
对于像这样的小任务，我们可能只需要一个 spec 文件。
执行： 创建 spec 文件：
# Unix/macOS
mkdir -p openspec/changes/<name>/specs/<capability-name>
# Windows (PowerShell)
# New-Item -ItemType Directory -Force -Path "openspec/changes/<name>/specs/<capability-name>"
起草 spec 内容：
这是 spec：
---
## ADDED Requirements
### Requirement: <名称>
<系统应做什么的描述>
#### Scenario: <场景名称>
- **WHEN** <触发条件>
- **THEN** <预期结果>
- **AND** <额外结果（如需要）>
---
这种格式——WHEN/THEN/AND——使需求可测试。您可以直接将它们读作测试用例。
保存到 openspec/changes/<name>/specs/<capability>/spec.md。
第七阶段：Design
讲解：
## Design
Design 记录**我们如何构建它**——技术决策、权衡、方案。
对于小变更，这可能很简短。没关系——不是每个变更都需要深度设计讨论。
执行： 起草 design.md：
这是设计：
---
## Context（背景）
[关于当前状态的简短背景]
## Goals / Non-Goals（目标/非目标）
**目标：**
- [我们试图实现什么]
**非目标：**
- [明确排除在外的内容]
## Decisions（决策）
### 决策 1：[关键决策]
[方案说明和理由]
---
对于小任务，这记录了关键决策，而不过度设计。
保存到 openspec/changes/<name>/design.md。
第八阶段：Tasks
讲解：
## Tasks
最后，我们将工作分解为实现任务——驱动应用阶段的复选框。
这些应该小、清晰，并按逻辑顺序排列。
执行： 根据 spec 和 design 生成任务：
这是实现任务：
---
## 1. [类别或文件]
- [ ] 1.1 [具体任务]
- [ ] 1.2 [具体任务]
## 2. 验证
- [ ] 2.1 [验证步骤]
---
每个复选框在应用阶段成为一个工作单元。准备好实现了吗？
暂停 - 等待用户确认准备好实现。
保存到 openspec/changes/<name>/tasks.md。
第九阶段：应用（实现）
讲解：
## 实现
现在我们逐个实现任务，完成时打勾。我会声明每一个，偶尔说明 spec/design 如何指导了这个方案。
执行： 对每个任务：
- 声明："正在处理任务 N：[描述]"
- 在代码库中实现更改
- 自然地引用 spec/design："Spec 说 X，所以我做 Y"
- 在 tasks.md 中标记完成：
- [ ]→- [x] - 简短状态："✓ 任务 N 完成"
保持叙述简洁——不要对每行代码过度解释。
所有任务完成后：
## 实现完成
所有任务已完成：
- [x] 任务 1
- [x] 任务 2
- [x] ...
变更已实现！还有最后一步——让我们归档它。
第十阶段：归档
讲解：
## 归档
当变更完成时，我们归档它。这会将它从 `openspec/changes/` 移动到 `openspec/changes/archive/YYYY-MM-DD-<name>/`。
归档的变更成为项目的决策历史——您随时可以找到它们，了解某些东西为什么以特定方式构建。
执行：
openspec archive "<name>"
展示：
已归档到：`openspec/changes/archive/YYYY-MM-DD-<name>/`
变更现在是项目历史的一部分。代码在您的代码库中，决策记录已保存。
第十一阶段：回顾与下一步
## 恭喜！
您刚刚完成了一个完整的 OpenSpec 循环：
1. **探索** - 思考了问题
2. **New** - 创建了变更容器
3. **Proposal** - 记录了为什么（WHY）
4. **Specs** - 详细定义了做什么（WHAT）
5. **Design** - 决定了如何做（HOW）
6. **Tasks** - 分解成了步骤
7. **Apply** - 实现了工作
8. **Archive** - 保存了记录
这个节奏适用于任何规模的变更——小修复或大功能。
---
## 命令参考
**核心工作流：**
| 命令 | 作用 |
|---------|--------------|
| `/opsx:propose` | 创建变更并生成所有 artifact |
| `/opsx:explore` | 在工作前/中思考问题 |
| `/opsx:apply` | 实现变更中的任务 |
| `/opsx:archive` | 完成后归档变更 |
**其他命令：**
| 命令 | 作用 |
|---------|--------------|
| `/opsx:new` | 启动新变更，逐步完成 artifact |
| `/opsx:continue` | 继续现有变更 |
| `/opsx:ff` | 快进：一次创建所有 artifact |
| `/opsx:verify` | 验证实现是否匹配 artifact |
---
## 下一步？
在您真正想构建的东西上试试 `/opsx:propose`。您已经掌握节奏了！
优雅退出处理
用户想要中途停止
若用户表示需要停止、想暂停或看起来不感兴趣：
没问题！您的变更已保存在 `openspec/changes/<name>/`。
稍后继续：
- `/opsx:continue <name>` - 继续创建 artifact
- `/opsx:apply <name>` - 直接跳到实现（若任务已存在）
工作不会丢失。准备好了随时回来。
优雅退出，不施加压力。
用户只想要命令参考
若用户表示只想查看命令或跳过教程：
## OpenSpec 快速参考
**核心工作流：**
| 命令 | 作用 |
|---------|--------------|
| `/opsx:propose <name>` | 创建变更并生成所有 artifact |
| `/opsx:explore` | 思考问题（不改代码） |
| `/opsx:apply <name>` | 实现任务 |
| `/opsx:archive <name>` | 完成后归档 |
**其他命令：**
| 命令 | 作用 |
|---------|--------------|
| `/opsx:new <name>` | 启动新变更，逐步操作 |
| `/opsx:continue <name>` | 继续现有变更 |
| `/opsx:ff <name>` | 快进：一次完成所有 artifact |
| `/opsx:verify <name>` | 验证实现 |
用 `/opsx:propose` 开始您的第一个变更。
优雅退出。
注意事项
- 遵循「讲解 → 执行 → 展示 → 暂停」模式，在关键过渡点（探索后、proposal 草稿后、任务后、归档后）
- 保持叙述简洁——在实现时教学，不说教
- 不要跳过阶段，即使变更很小——目标是教授工作流
- 在标记点等待确认，但不要过度暂停
- 优雅处理退出——不要施压让用户继续
- 使用真实代码库任务——不要模拟或使用假例子
- 温和地调整范围——引导向较小的任务，但尊重用户选择