一、核心概念速览

工具/方法	角色定位
OpenSpec	规格驱动，人机对齐需求，生成 spec/proposal/task
Oh-My-OpenCode	AI 多 Agent 编排器，协调多模型分工协作
OpenCode	AI 编码执行引擎，读取 spec 落地代码
SDD	Specification-Driven Development，先写规格再写代码
ATDD	Acceptance Test-Driven Development，先写验收测试再实现

协作流程总览

需求 → OpenSpec(规格对齐) → ATDD(验收测试) → Oh-My-OpenCode(多Agent实现) → OpenCode(执行) → 验证
  ↑_________________________反馈循环_______________________________________________|

---

二、环境搭建

2.1 安装 Bun（Oh-My-OpenCode 依赖）

curl -fsSL https://bun.sh/install | bash
# 重启终端生效

2.2 安装 OpenSpec

npm install -g @fission-ai/openspec@latest

2.3 安装 Oh-My-OpenCode + OpenCode

# 根据你的订阅情况替换参数
bunx oh-my-opencode install --no-tui --claude=yes --chatgpt=yes --gemini=yes

# 只有 Claude 的情况
bunx oh-my-opencode install --no-tui --claude=yes --chatgpt=no --gemini=no

# 无 Bun 时用 npx
npx oh-my-opencode install --no-tui --claude=yes

2.4 验证安装

# 验证 Oh-My-OpenCode
cat ~/.config/opencode/opencode.json | grep "oh-my-opencode"

# 验证 OpenSpec
openspec --version

2.5 身份认证

opencode auth login
# 选择提供商 → 浏览器 OAuth 登录

2.6 推荐模型配置

编辑 ~/.config/opencode/oh-my-opencode.json：

{
  "agents": {
    "frontend-ui-ux-engineer": {
      "model": "google/gemini-2.5-pro"
    },
    "oracle": {
      "model": "anthropic/claude-opus-4-5"
    },
    "backend-engineer": {
      "model": "openai/gpt-5.2"
    }
  },
  "sisyphus_agent": {
    "disabled": false
  },
  "background_task": {
    "defaultConcurrency": 5
  }
}

💡 OpenSpec 推荐使用高推理模型：Opus 4.5 和 GPT 5.2

---

三、SDD 规格驱动开发流程

3.1 初始化项目规格

cd /path/to/your/project

# 初始化 OpenSpec
openspec init

# 初始化 OpenCode 项目分析
opencode
# 在 OpenCode 中输入：
/init

/init 会分析项目结构，生成 AGENTS.md，定义编码规范和 Agent 行为边界。

3.2 创建变更提案（Change Proposal）

小改动（Bug 修复、小优化） → 直接提 PR

大改动（新功能、重构、架构变更） → 先创建 OpenSpec 提案：

# 使用 OpenSpec slash 命令创建提案
/spec new "用户认证模块重构"

OpenSpec 会自动生成以下结构：

.openspec/
└── changes/
    └── user-auth-refactor/
        ├── proposal.md      # 变更提案（WHY）
        ├── specs.md         # 功能规格（WHAT）
        ├── design.md        # 技术设计（HOW）
        └── tasks.md         # 任务拆解（TODO）

3.3 编写规格文档

proposal.md 示例：

# 提案：用户认证模块重构

## 背景
当前 JWT 实现存在 token 刷新缺陷，导致用户频繁掉线。

## 目标
- 实现 refresh token 机制
- 支持多设备登录管理
- Token 黑名单机制

## 非目标
- 不涉及第三方 OAuth 集成
- 不修改用户注册流程

specs.md 示例：

# 功能规格

## AC-001：Token 刷新
- GIVEN 用户持有有效 refresh_token
- WHEN access_token 过期
- THEN 系统自动签发新 access_token，无需重新登录

## AC-002：多设备管理
- GIVEN 用户已在 3 台设备登录
- WHEN 用户查看设备列表
- THEN 显示所有活跃 session，可单独踢出

## AC-003：Token 黑名单
- GIVEN 用户主动登出
- WHEN 使用旧 access_token 请求
- THEN 返回 401，拒绝访问

💡 SDD 核心原则：代码动手前，人机必须对齐规格

3.4 更新规格

OpenSpec 允许随时更新任何文档，无强制阶段限制：

/spec update specs.md   # 更新规格
/spec update design.md  # 更新设计

---

四、ATDD 验收测试驱动开发

4.1 ATDD 工作流

specs.md(AC验收条件) → 编写验收测试 → 运行(红) → AI实现代码 → 运行(绿) → 重构

4.2 从 AC 生成验收测试

将 specs.md 的验收条件交给 OpenCode/Oh-My-OpenCode 生成测试：

在 OpenCode 中输入：

根据 .openspec/changes/user-auth-refactor/specs.md 中的验收条件，
生成对应的 ATDD 验收测试，使用 Jest + Supertest，
每个 AC 对应一个 describe 块，先写测试骨架不实现

生成示例（tests/acceptance/auth.ac.test.ts）：

describe('AC-001: Token 刷新', () => {
  it('access_token 过期时，使用 refresh_token 自动续期', async () => {
    // Arrange
    const { refreshToken } = await loginUser(testUser);
    await expireAccessToken();

    // Act
    const response = await request(app)
      .post('/auth/refresh')
      .send({ refresh_token: refreshToken });

    // Assert
    expect(response.status).toBe(200);
    expect(response.body).toHaveProperty('access_token');
    expect(response.body).toHaveProperty('expires_in');
  });
});

describe('AC-002: 多设备管理', () => {
  it('用户可查看所有活跃 session 列表', async () => {
    // Arrange
    await loginFromDevices(testUser, 3);

    // Act
    const response = await request(app)
      .get('/auth/sessions')
      .set('Authorization', `Bearer ${accessToken}`);

    // Assert
    expect(response.status).toBe(200);
    expect(response.body.sessions).toHaveLength(3);
  });

  it('用户可踢出指定设备 session', async () => {
    // ...
  });
});

describe('AC-003: Token 黑名单', () => {
  it('登出后旧 token 应被拒绝', async () => {
    // Arrange
    const { accessToken } = await loginUser(testUser);
    await request(app)
      .post('/auth/logout')
      .set('Authorization', `Bearer ${accessToken}`);

    // Act
    const response = await request(app)
      .get('/user/profile')
      .set('Authorization', `Bearer ${accessToken}`);

    // Assert
    expect(response.status).toBe(401);
  });
});

4.3 运行验收测试（此时应该全红）

npm test tests/acceptance/auth.ac.test.ts
# ❌ 全部失败 —— 符合预期，代码还没实现

---

五、Oh-My-OpenCode 多 Agent 协作实现

5.1 触发多 Agent 协作

验收测试写完后，切换到 OpenCode，使用 ulw 触发多 Agent 并行实现：

ulw 根据 .openspec/changes/user-auth-refactor/ 下的规格文档，
实现用户认证模块重构，需通过 tests/acceptance/auth.ac.test.ts 所有测试

ulw 会触发 Oh-My-OpenCode 的 Sisyphus 编排器，自动分工：

Sisyphus(编排器)
├── @oracle          → 设计数据库 schema（Token 表、Session 表）
├── @backend-engineer → 实现 refresh token 核心逻辑
├── @frontend-ui-ux  → 实现设备管理页面
└── @oracle          → 审查代码，验证 AC 覆盖

5.2 分步实现（Plan → Build 模式）

复杂功能建议先 Plan 再 Build：

# 在 OpenCode 中按 Tab 切换到 Plan 模式
# 输入：
"按照 tasks.md 的任务拆解，制定实现计划：
 1. 先实现 refresh token 数据模型
 2. 再实现 token 刷新 API
 3. 最后实现黑名单机制
 每步完成后运行对应验收测试"

# 确认计划后，按 Tab 切换回 Build 模式，输入：
"Go ahead!"

5.3 指定 Agent 处理特定任务

让 @oracle 设计 Token 黑名单的 Redis 数据结构
让 @backend-engineer 实现 /auth/refresh 接口

---

六、完整迭代闭环

# 1. 实现完成后运行验收测试
npm test tests/acceptance/auth.ac.test.ts

# 期望：✅ 全部通过

# 2. 运行完整测试套件，确保无回归
npm test

# 3. 如有失败，回到 OpenCode 修复
/undo   # 撤销上一步修改（如需要）

# 4. 更新 OpenSpec 文档（如实现中有调整）
/spec update design.md

# 5. 提交代码
git add .
git commit -m "feat: 实现用户认证模块重构 - AC-001/002/003"
git push

---

七、完整工作流一览

Day 1: 需求澄清
├── openspec init
├── /spec new "功能名"
└── 编写 proposal.md + specs.md (AC 验收条件)

Day 2: 测试先行
├── opencode /init
├── 根据 AC 生成验收测试骨架
└── npm test → 全红（正常）

Day 3: AI 多 Agent 实现
├── ulw 触发多 Agent 协作
├── Plan 模式确认计划
├── Build 模式执行实现
└── npm test → 全绿

Day 4: 验收 & 交付
├── 更新 OpenSpec 文档
├── /spec update
├── git push
└── 提 PR（小改动直接 PR，大改动附 proposal 链接）

---

八、最佳实践

实践	说明
规格先行	代码动手前，务必完成 specs.md 的 AC 编写
测试先行	AC → 验收测试 → 实现，严格遵守红绿循环
清洁上下文	开始实现前清除 OpenCode 上下文窗口，避免干扰
目录规范	github/gitlab 项目分目录存放，配合 git 多账户配置
小步提交	每个 AC 实现完即提交，方便 /undo 回退 <sub index="1" url="https://www.cnblogs.com/gyc567/p/19467284" title="OpenCode + Oh My OpenCode 配置和开发教程（新手小白 ..." snippet="* ChatGPT Plus：用--chatgpt=yes。* Gemini：用--gemini=yes。* 没有就用no。* Claude Pro/Max：用* 安装Bun（如果没装，Oh My需要）： curl -fsSL https://bun.sh/install
自然语言	用自然语言描述需求，复杂任务用 ulw 全自动处理 <sub index="1" url="https://www.cnblogs.com/gyc567/p/19467284" title="OpenCode + Oh My OpenCode 配置和开发教程（新手小白 ..." snippet="* ChatGPT Plus：用--chatgpt=yes。* Gemini：用--gemini=yes。* 没有就用no。* Claude Pro/Max：用* 安装Bun（如果没装，Oh My需要）： curl -fsSL https://bun.sh/install
模型选择	规划用高推理模型（Opus 4.5/GPT-5.2），实现可用轻量模型

---

💡 核心理念：OpenSpec 保证人机对齐，ATDD 保证质量可验收，Oh-My-OpenCode 保证实现效率——三者形成完整的 AI 辅助工程化闭环。