第四章:完整工作流演示

本章通过一个完整的案例,演示 OpenSpec 的实际使用流程。

两种使用方式

OpenSpec 可以通过两种方式使用:

方式 说明 示例
CLI 方式 直接在终端使用 CLI 命令 openspec new change xxx
AI-native 方式 在 AI 工具的对话中使用命令 /opsx:propose "xxx"

两种方式可以结合使用:


案例:添加暗黑模式

假设我们要为一个 React 项目添加暗黑模式功能。


第一步:创建变更

CLI 方式(直接创建)

openspec new change add-dark-mode

AI-native 方式(让 AI 帮忙)

在 AI 工具中告诉它:

/opsx:propose "添加暗黑模式,用户可以在亮色和暗色主题之间切换"

AI 会自动:

  1. 运行 openspec new change add-dark-mode 创建目录
  2. 生成规范文档
  3. 展示给你确认

无论哪种方式,创建后目录结构如下:

openspec/changes/add-dark-mode/
├── proposal.md
├── specs/
│   └── requirements.md
├── design.md
└── tasks.md

proposal.md 内容示例

# 提案:添加暗黑模式

## 背景
当前应用只有亮色主题,在夜间或弱光环境下使用体验不佳。

## 目标
- 支持亮色/暗色主题切换
- 自动跟随系统主题偏好
- 用户偏好持久化

## 成功标准
- 用户可以通过开关切换主题
- 切换后所有组件正确显示
- 刷新页面后保持用户选择

specs/requirements.md 内容示例

# 需求规范

## 功能需求
1. 添加主题切换开关(位于导航栏右侧)
2. 支持三种模式:
   - Light(亮色)
   - Dark(暗色)
   - System(跟随系统)
3. 用户选择保存到 localStorage
4. 默认值为 System

## 视觉需求
- 暗色模式背景色:#1a1a2e
- 暗色模式文字色:#eaeaea
- 所有组件需要适配两种主题

## 场景
### 场景 1:首次访问
用户首次访问,检测系统主题,自动应用

### 场景 2:手动切换
用户点击切换按钮,主题立即改变

### 场景 3:重新访问
用户再次访问,恢复上次选择的主题

design.md 内容示例

# 技术设计

## 方案
使用 React Context + CSS Variables 实现

## 文件结构

src/ ├── components/ │ └── ThemeToggle.tsx # 主题切换按钮 ├── contexts/ │ └── ThemeContext.tsx # 主题上下文 ├── hooks/ │ └── useTheme.ts # 主题 Hook └── styles/ └── theme.css # 主题变量


## 实现细节
1. ThemeContext 管理当前主题状态
2. CSS Variables 定义颜色变量
3. localStorage 持久化用户选择
4. matchMedia 监听系统主题变化

## 颜色变量
```css
:root {
  --bg-primary: #ffffff;
  --text-primary: #1a1a2e;
}

[data-theme="dark"] {
  --bg-primary: #1a1a2e;
  --text-primary: #eaeaea;
}

### tasks.md 内容示例

```markdown
# 实现任务

## 1. 创建主题系统
- [ ] 1.1 创建 ThemeContext.tsx
- [ ] 1.2 创建 useTheme hook
- [ ] 1.3 创建 theme.css 变量文件

## 2. 创建切换组件
- [ ] 2.1 创建 ThemeToggle 组件
- [ ] 2.2 添加太阳/月亮图标
- [ ] 2.3 实现点击切换逻辑

## 3. 集成到应用
- [ ] 3.1 在 App.tsx 包裹 ThemeProvider
- [ ] 3.2 在导航栏添加 ThemeToggle
- [ ] 3.3 更新现有组件使用 CSS 变量

## 4. 持久化和系统适配
- [ ] 4.1 实现 localStorage 存储
- [ ] 4.2 实现系统主题监听
- [ ] 4.3 处理首次访问的默认主题

第二步:审查规范

这是最关键的一步!

仔细阅读 AI 生成的文档:

# 查看提案
openspec show add-dark-mode
cat openspec/changes/add-dark-mode/proposal.md

# 查看需求
cat openspec/changes/add-dark-mode/specs/requirements.md

# 查看设计
cat openspec/changes/add-dark-mode/design.md

# 查看任务
cat openspec/changes/add-dark-mode/tasks.md

确认无误

如果文档符合预期,告诉 AI:

规范文档看起来不错,可以开始实现了

需要修改

如果有问题,直接指出:

design.md 里的颜色方案我们改用 Tailwind 的 dark: 前缀,不用 CSS Variables
tasks.md 里需要添加单元测试任务

AI 会更新文档,直到你满意为止。


第三步:开始实现

AI-native 方式(推荐)

在 AI 工具中:

/opsx:apply

实现过程

AI 会按 tasks.md 的顺序执行:

开始实现暗黑模式功能...

✓ 1.1 创建 ThemeContext.tsx
  创建了主题上下文,包含 theme、setTheme、toggleTheme

✓ 1.2 创建 useTheme hook
  封装了主题状态获取和切换方法

✓ 1.3 创建 theme.css 变量文件
  定义了亮色和暗色模式的颜色变量

✓ 2.1 创建 ThemeToggle 组件
  创建了带有太阳/月亮图标的切换按钮

✓ 2.2 添加太阳/月亮图标
  使用 lucide-react 图标库

✓ 2.3 实现点击切换逻辑
  点击时切换主题并保存到 localStorage

✓ 3.1 在 App.tsx 包裹 ThemeProvider
  在应用根节点添加了主题提供者

✓ 3.2 在导航栏添加 ThemeToggle
  在 Header 组件右侧添加了切换按钮

✓ 3.3 更新现有组件使用 CSS 变量
  更新了 Button、Card、Input 等组件

✓ 4.1 实现 localStorage 存储
  主题选择持久化到 localStorage

✓ 4.2 实现系统主题监听
  使用 matchMedia 监听系统主题变化

✓ 4.3 处理首次访问的默认主题
  首次访问时检测系统偏好

🎉 所有任务完成!

第四步:验证功能

CLI 方式验证

# 验证变更是否符合规范
openspec validate add-dark-mode

# 查看任务完成状态
openspec status --change add-dark-mode

AI-native 方式验证

在 AI 工具中:

/opsx:verify

AI 会对比 specs/ 和代码,报告是否符合规范:

✓ 手机号登录 - 已实现
✓ 验证码 5 分钟过期 - 已实现
✗ 微信登录 - 未实现(tasks.md 1.4 未完成)
⚠ 登录失败次数限制 - 规范要求 5 次,代码实现为 3 次

手动测试

# 启动应用
npm run dev

# 测试以下场景:
# 1. 点击切换按钮,主题是否正确切换
# 2. 刷新页面,主题是否保持
# 3. 切换系统主题,应用是否跟随

第五步:归档变更

CLI 方式

# 归档变更(会提示确认)
openspec archive add-dark-mode

# 跳过确认
openspec archive add-dark-mode --yes

AI-native 方式

在 AI 工具中:

/opsx:archive

AI 会调用 CLI 的 archive 命令完成归档。

归档结果

变更被移动到:

openspec/archive/YYYY-MM-DD-add-dark-mode/

目录结构:

openspec/archive/YYYY-MM-DD-add-dark-mode/
├── proposal.md
├── specs/
├── design.md
├── tasks.md
└── summary.md          # 新增:实现摘要

summary.md 内容示例

# 实现摘要

## 完成时间
2025-03-16

## 实现内容
- ✅ ThemeContext 和 useTheme hook
- ✅ ThemeToggle 组件(太阳/月亮图标)
- ✅ CSS 变量主题系统
- ✅ localStorage 持久化
- ✅ 系统主题自动适配

## 新增文件
- src/contexts/ThemeContext.tsx
- src/hooks/useTheme.ts
- src/components/ThemeToggle.tsx
- src/styles/theme.css

## 修改文件
- src/App.tsx
- src/components/Header.tsx
- src/components/Button.tsx
- src/components/Card.tsx
- src/components/Input.tsx

## 备注
实现过程顺利,无需调整规范

完整流程图

开始
  │
  ▼
┌─────────────────────────────────────┐
│  创建变更                            │
│  CLI: openspec new change xxx       │
│  AI: /opsx:propose "xxx"           │
└─────────────────────────────────────┘
  │
  ▼
┌─────────────────────────────────────┐
│  AI 生成规范文档                      │
│  proposal.md / specs/               │
│  design.md / tasks.md              │
└─────────────────────────────────────┘
  │
  ▼
  你审查规范文档
  │
  ├─ 不满意 ──→ 告诉 AI 修改 ──→ 回到审查
  │
  └─ 满意 ─────→ /opsx:apply
                  │
                  ▼
              AI 实现代码
                  │
                  ▼
              手动测试验证
                  │
              ├─ 有问题 ──→ 告诉 AI 修复 ──→ 继续测试
              │
              └─ 没问题 ──→ /opsx:archive
                              │
                              ▼
                          归档完成
                              │
                              ▼
                          开始下一个功能

常用命令速查

CLI 命令(终端)

# 初始化
openspec init
openspec init --tools claude,cursor

# 创建
openspec new change <name>

# 查看
openspec list
openspec show <name>
openspec view

# 验证
openspec validate [name]
openspec validate --all

# 状态
openspec status
openspec status --change <name>

# 归档
openspec archive <name>
openspec archive <name> --yes

# 配置
openspec config list
openspec config profile
openspec update

AI-native 命令(AI 对话)

/opsx:propose "描述需求"    # 创建提案
/opsx:apply                  # 开始实现
/opsx:verify                 # 验证实现
/opsx:sync                   # 同步状态
/opsx:archive                # 归档
/opsx:onboard                # 新成员引导

下一步

→ 第五章:项目结构详解