EmailBill/.opencode/skills/openspec-onboard/SKILL.cn.md

name, description, license, compatibility, metadata

name	description	license	compatibility	metadata
openspec-onboard	OpenSpec 引导式入门教程 - 通过真实代码库工作完整演示工作流程	MIT	需要 openspec CLI。	author version generatedBy openspec 1.0 1.1.1

引导用户完成他们的第一个完整 OpenSpec 工作流程周期。这是一次教学体验——你将在他们的代码库中做真实的工作,同时解释每个步骤。

---

准备检查

在开始之前,检查 OpenSpec 是否已初始化:

openspec status --json 2>&1 || echo "NOT_INITIALIZED"

如果未初始化:

OpenSpec 还未在此项目中设置。请先运行 openspec init,然后再回到 /opsx-onboard。

如果未初始化,在这里停止。

---

阶段 1: 欢迎

显示:

## 欢迎使用 OpenSpec!

我将带你完成一个完整的变更周期——从想法到实现——使用代码库中的真实任务。在此过程中,你将通过实践来学习工作流程。

**我们将做什么:**
1. 在你的代码库中选择一个小的真实任务
2. 简要探索问题
3. 创建一个变更(我们工作的容器)
4. 构建工件: proposal → specs → design → tasks
5. 实现任务
6. 归档完成的变更

**时间:** ~15-20 分钟

让我们从找到要做的事情开始。

---

阶段 2: 任务选择

代码库分析

扫描代码库寻找小的改进机会。查找:

1. TODO/FIXME 注释 - 在代码文件中搜索 TODO, FIXME, HACK, XXX
2. 缺失的错误处理 - 吞噬错误的 catch 块,没有 try-catch 的风险操作
3. 缺少测试的函数 - 将 src/ 与测试目录交叉引用
4. 类型问题 - TypeScript 文件中的 any 类型(: any, as any)
5. 调试残留 - 非调试代码中的 console.log, console.debug, debugger 语句
6. 缺失的验证 - 没有验证的用户输入处理器

还检查最近的 git 活动:

git log --oneline -10 2>/dev/null || echo "No git history"

呈现建议

根据你的分析,呈现 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. **照做** - 如果你真的想处理这个,我们可以。只是知道会花更长时间。

你更喜欢什么?

如果他们坚持,让用户覆盖——这是一个软守护。

---

阶段 3: 探索演示

一旦选择了任务,简要演示探索模式:

在创建变更之前,让我快速展示**探索模式**——这是你在承诺方向之前思考问题的方式。

花 1-2 分钟调查相关代码:

• 读取涉及的文件
• 如果有帮助,画一个快速的 ASCII 图
• 注意任何考虑因素

## 快速探索

[你的简要分析——你发现了什么,任何考虑因素]

┌─────────────────────────────────────────┐
│   [可选: 如果有帮助的 ASCII 图]        │
└─────────────────────────────────────────┘

探索模式 (`/opsx-explore`) 就是用于这种思考——在实现之前进行调查。你可以在需要思考问题时随时使用它。

现在让我们创建一个变更来保存我们的工作。

暂停 - 等待用户确认后再继续。

---

阶段 4: 创建变更

解释:

## 创建变更

在 OpenSpec 中,"变更"是围绕一项工作的所有思考和规划的容器。它位于 `openspec/changes/<name>/` 中,包含你的工件——proposal、specs、design、tasks。

让我为我们的任务创建一个。

执行: 使用派生的 kebab-case 名称创建变更:

openspec new change "<derived-name>"

显示:

创建: `openspec/changes/<name>/`

文件夹结构:

openspec/changes// ├── proposal.md ← 我们为什么这样做(空的,我们会填充) ├── design.md ← 我们如何构建它(空的) ├── specs/ ← 详细需求(空的) └── tasks.md ← 实现检查清单(空的)

现在让我们填充第一个工件——proposal。

---

阶段 5: Proposal

解释:

## Proposal

proposal 捕获我们为什么进行这个变更以及高层次的内容。这是工作的"电梯演讲"。

我将根据我们的任务起草一个。

执行: 起草 proposal 内容(还不要保存):

这是一个草案 proposal:

---

## 为什么 (Why)

[1-2 句话解释问题/机会]

## 变更内容 (What Changes)

[将会有什么不同的要点]

## 能力 (Capabilities)

### 新能力
- `<capability-name>`: [简要描述]

### 修改的能力
<!-- 如果修改现有行为 -->

## 影响 (Impact)

- `src/path/to/file.ts`: [什么变更]
- [其他适用的文件]

---

这是否捕获了意图? 我可以在保存前调整。

暂停 - 等待用户批准/反馈。

批准后,保存 proposal:

openspec instructions proposal --change "<name>" --json

然后将内容写入 openspec/changes/<name>/proposal.md。

Proposal 已保存。这是你的"为什么"文档——随着理解的演变,你总是可以回来完善它。

接下来: specs。

---

阶段 6: Specs

解释:

## Specs

Specs 以精确、可测试的术语定义我们正在构建什么。它们使用需求/场景格式,使预期行为非常清晰。

对于像这样的小任务,我们可能只需要一个 spec 文件。

执行: 创建 spec 文件:

mkdir -p 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。

---

阶段 7: Design

解释:

## Design

design 捕获我们如何构建它——技术决策、权衡、方法。

对于小变更,这可能很简短。这没关系——不是每个变更都需要深度设计讨论。

执行: 起草 design.md:

这是 design:

---

## 上下文 (Context)

[关于当前状态的简要上下文]

## 目标 / 非目标 (Goals / Non-Goals)

**目标:**
- [我们试图实现什么]

**非目标:**
- [明确超出范围的内容]

## 决策 (Decisions)

### Decision 1: [关键决策]

[方法和理由的解释]

---

对于小任务,这捕获了关键决策而不会过度设计。

保存到 openspec/changes/<name>/design.md。

---

阶段 8: Tasks

解释:

## Tasks

最后,我们将工作分解为实现任务——驱动应用阶段的复选框。

这些应该小、清晰且按逻辑顺序排列。

执行: 基于 specs 和 design 生成任务:

这是实现任务:

---

## 1. [类别或文件]

- [ ] 1.1 [具体任务]
- [ ] 1.2 [具体任务]

## 2. 验证 (Verify)

- [ ] 2.1 [验证步骤]

---

每个复选框在应用阶段成为一个工作单元。准备好实现了吗?

暂停 - 等待用户确认他们准备好实现。

保存到 openspec/changes/<name>/tasks.md。

---

阶段 9: Apply (实现)

解释:

## 实现 (Implementation)

现在我们实现每个任务,在进行时勾选它们。我会宣布每一个,偶尔注意 specs/design 如何指导方法。

执行: 对于每个任务:

1. 宣布: "正在处理任务 N: [描述]"
2. 在代码库中进行所需的更改
3. 自然地引用 specs/design: "spec 说 X,所以我做 Y"
4. 在 tasks.md 中标记完成: - [ ] → - [x]
5. 简要状态: "✓ 任务 N 完成"

保持叙述轻量——不要过度解释每行代码。

所有任务完成后:

## 实现完成

所有任务完成:
- [x] Task 1
- [x] Task 2
- [x] ...

变更已实现! 还有一步——让我们归档它。

---

阶段 10: Archive

解释:

## 归档 (Archiving)

当变更完成时,我们归档它。这将它从 `openspec/changes/` 移动到 `openspec/changes/archive/YYYY-MM-DD-<name>/`。

归档的变更成为你项目的决策历史——你总是可以在以后找到它们,以了解为什么某些东西是以某种方式构建的。

执行:

openspec archive "<name>"

显示:

归档到: `openspec/changes/archive/YYYY-MM-DD-<name>/`

变更现在是你项目历史的一部分。代码在你的代码库中,决策记录被保存。

---

阶段 11: 回顾与下一步

## 恭喜!

你刚刚完成了一个完整的 OpenSpec 周期:

1. **Explore** - 思考问题
2. **New** - 创建变更容器
3. **Proposal** - 捕获为什么 (WHY)
4. **Specs** - 详细定义什么 (WHAT)
5. **Design** - 决定如何 (HOW)
6. **Tasks** - 分解为步骤
7. **Apply** - 实现工作
8. **Archive** - 保存记录

这个相同的节奏适用于任何规模的变更——无论是小修复还是主要功能。

---

## 命令参考

| 命令 | 功能 |
|---------|--------------|
| `/opsx-explore` | 在工作前/期间思考问题 |
| `/opsx-new` | 启动新变更,逐步完成工件 |
| `/opsx-ff` | 快进: 一次创建所有工件 |
| `/opsx-continue` | 继续现有变更的工作 |
| `/opsx-apply` | 实现变更中的任务 |
| `/opsx-verify` | 验证实现与工件匹配 |
| `/opsx-archive` | 归档完成的变更 |

---

## 下一步是什么?

在你真正想构建的东西上尝试 `/opsx-new` 或 `/opsx-ff`。你现在已经掌握了节奏!

---

优雅退出处理

用户想中途停止

如果用户说他们需要停止、想暂停或看起来不再参与:

没问题! 你的变更保存在 `openspec/changes/<name>/`。

要在以后从我们离开的地方继续:
- `/opsx-continue <name>` - 恢复工件创建
- `/opsx-apply <name>` - 跳转到实现(如果任务存在)

工作不会丢失。准备好时随时回来。

优雅退出,不施加压力。

用户只想要命令参考

如果用户说他们只想看命令或跳过教程:

## OpenSpec 快速参考

| 命令 | 功能 |
|---------|--------------|
| `/opsx-explore` | 思考问题(不改代码) |
| `/opsx-new <name>` | 启动新变更,逐步进行 |
| `/opsx-ff <name>` | 快进: 一次所有工件 |
| `/opsx-continue <name>` | 继续现有变更 |
| `/opsx-apply <name>` | 实现任务 |
| `/opsx-verify <name>` | 验证实现 |
| `/opsx-archive <name>` | 完成时归档 |

试试 `/opsx-new` 来开始你的第一个变更,或者如果你想快速移动就用 `/opsx-ff`。

优雅退出。

---

守护

• 遵循 EXPLAIN → DO → SHOW → PAUSE 模式 在关键转换点(探索后、proposal 草案后、任务后、归档后)
• 保持叙述轻量 在实现期间——教学但不说教
• 不要跳过阶段 即使变更很小——目标是教学工作流程
• 在标记的点暂停等待确认,但不要过度暂停
• 优雅处理退出——永远不要强迫用户继续
• 使用真实代码库任务——不要模拟或使用假例子
• 温和地调整范围——引导向更小的任务但尊重用户选择