第四章:完整工作流演示
本章通过一个完整的案例,演示 OpenSpec 的实际使用流程。
两种使用方式
OpenSpec 可以通过两种方式使用:
| 方式 | 说明 | 示例 |
|---|---|---|
| CLI 方式 | 直接在终端使用 CLI 命令 | openspec new change xxx |
| AI-native 方式 | 在 AI 工具的对话中使用命令 | /opsx:propose "xxx" |
两种方式可以结合使用:
- 使用 CLI 创建和管理变更
- 使用 AI-native 命令让 AI 自动完成文档生成和代码实现
案例:添加暗黑模式
假设我们要为一个 React 项目添加暗黑模式功能。
第一步:创建变更
CLI 方式(直接创建)
openspec new change add-dark-mode
AI-native 方式(让 AI 帮忙)
在 AI 工具中告诉它:
/opsx:propose "添加暗黑模式,用户可以在亮色和暗色主题之间切换"
AI 会自动:
- 运行
openspec new change add-dark-mode创建目录 - 生成规范文档
- 展示给你确认
无论哪种方式,创建后目录结构如下:
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 # 新成员引导