sanguo_moziplus_v3/docs/design/06-design-v0.5-dynamic-orchestration.md

# sanguo_moziplus_v3 设计文档 v0.5

**项目名称**: sanguo_moziplus_v3
**版本**: v0.5
**创建日期**: 2026-07-01
**状态**: Draft
**基于**: v0.4 + Main + Sub Agent 动态编排

---

## 1. 版本变更

| 版本 | 变更说明 | 日期 |
|------|---------|------|
| v0.1 | 初始设计 | 2026-06-29 |
| v0.2 | videotext 调研，GLM-5.2、Web 访问 | 2026-06-29 |
| v0.3 | 移除 CCB，采用 Claude Code 内置多 Agent | 2026-06-30 |
| v0.4 | 三实例方案：SendMessage 跨实例 | 2026-06-30 |
| **v0.5** | **Main + Sub Agent：动态编排** | **2026-07-01** |

### v0.5 核心变化

| 变更项 | v0.4 | v0.5 | 原因 |
|--------|------|------|------|
| **编排方式** | SendMessage 跨实例 | **Agent 工具动态编排** | 更灵活的协作 |
| **Main 角色** | 架构师 (Plan + Review) | **编排者 + 验收整合** | 专注于编排 |
| **Sub Agent 角色** | backend/frontend 执行 | **Execute/Review/Test 专业角色** | 更细的分工 |
| **工作流** | 固化流程 | **Main 根据需求动态安排** | 更灵活 |

---

## 2. 设计精髓

### 2.1 核心理念

**Main Agent 根据需求动态编排 Sub Agents**

```
┌─────────────────────────────────────────────────────────────────┐
│                    Main Agent (编排者)                          │
│                                                                 │
│  职责:                                                          │
│  • 根据任务需要分析和决策                                       │
│  • 动态安排 Sub Agents                                          │
│  • 不是固化流程，而是灵活调整                                    │
│  • 最终验收和整合                                               │
│                                                                 │
│  能力 (依托 Superpowers):                                      │
│  • planning (如需要)                                            │
│  • 其他 100+ Superpowers skills                                │
│  • Agent 工具编排                                               │
└─────────────────────────────────────────────────────────────────┘
                    │
                    │ Agent 工具动态编排
                    │
         ┌──────────┼──────────┐
         │          │          │
         ▼          ▼          ▼
┌──────────────────┐ ┌──────────┐ ┌──────────┐
│ Sub Agent:       │ │Sub Agent:│ │Sub Agent:│
│ Execute          │ │Review    │ │Test      │
│                  │ │          │ │          │
│ 专业角色:        │ │专业角色: │ │专业角色: │
│ • backend-dev    │ │CODE-     │ │test-     │
│ • frontend-dev   │ │REVIEW    │ │engineer  │
│ • ...            │ │security  │ │e2e       │
│                  │ │perf      │ │...       │
└──────────────────┘ └──────────┘ └──────────┘

所有 Agent 都能访问 Superpowers
```

### 2.2 动态编排示例

**不是固化流程，Main 根据任务需要安排**

#### 简单任务

```
用户: "修复这个 bug"
     ↓
Main Agent: 分析后决定
     ↓
安排 Execute Sub Agent (修复)
     ↓
验收整合
```

#### 中等任务

```
用户: "实现用户登录功能"
     ↓
Main Agent: 分析后决定
     ↓
安排 Execute Sub Agent (实现)
     ↓
安排 Review Sub Agent (审查)
     ↓
验收整合
```

#### 复杂任务

```
用户: "实现完整的用户认证系统"
     ↓
Main Agent: 使用 planning skill 分析
     ↓
安排 Execute Sub Agent (后端实现)
安排 Execute Sub Agent (前端实现)
     ↓
安排 Review Sub Agent (代码审查)
安排 Review Sub Agent (安全审查)
     ↓
安排 Test Sub Agent (测试验证)
     ↓
验收整合
```

#### 调试任务

```
用户: "登录接口有问题"
     ↓
Main Agent: 分析后决定
     ↓
安排 debugger Sub Agent (定位问题)
     ↓
安排 Execute Sub Agent (修复问题)
     ↓
安排 Test Sub Agent (验证修复)
     ↓
验收整合
```

### 2.3 关键特性

1. **动态编排**: Main 根据任务需要决定安排哪些 Sub Agents
2. **专业分工**: Sub Agents 有明确的专业角色
3. **上下文隔离**: 每个 Sub Agent 只能看到必要信息
4. **共享能力**: 所有 Agent 都遵循 Superpowers 工作方式
5. **灵活调整**: 不是固化流程，Main 可以根据情况调整

---

## 3. 角色定义

### 3.1 Main Agent (编排者)

**职责**:
- 分析任务需求
- 根据需要决定安排哪些 Sub Agents
- 协调 Sub Agents 之间的协作
- 最终验收和整合

**能力 (依托 Superpowers)**:
- `planning` — 复杂任务的方案规划
- `debugger` — 问题诊断
- 其他 100+ Superpowers skills

**限制**:
- 不亲自编写代码
- 不亲自执行具体实现

**工作方式**:
```
1. 接收任务
2. 分析任务需要什么
3. 决定安排哪些 Sub Agents
4. 协调执行
5. 验收整合
```

### 3.2 Sub Agent: Execute (执行者)

**职责**:
- 执行具体实现任务
- 编写代码
- 实现功能

**专业角色 (通过 prompt 指定)**:
- **backend-dev**: 后端开发
- **frontend-dev**: 前端开发
- **database-dev**: 数据库开发
- **infrastructure**: 基础设施

**上下文**:
- 只能看到任务描述和项目代码
- 看不到其他 Sub Agents 的工作

### 3.3 Sub Agent: Review (审查者)

**职责**:
- 审查代码质量
- 检查安全性
- 检查性能

**专业角色 (通过 prompt 指定)**:
- **CODE-REVIEW**: 代码质量审查
- **security-reviewer**: 安全审查
- **performance-reviewer**: 性能审查

**上下文**:
- 只能看到需要审查的代码
- 看不到实现过程

### 3.4 Sub Agent: Test (测试者)

**职责**:
- 编写测试用例
- 执行测试
- 验证功能

**专业角色 (通过 prompt 指定)**:
- **test-engineer**: 单元测试
- **e2e-tester**: 端到端测试
- **qa-tester**: 质量保证测试

**上下文**:
- 只能看到需要测试的功能
- 看不到实现细节

---

## 4. 上下文隔离

### 4.1 隔离原则

```
Main Agent
    │
    ├─ 安排 Execute Sub Agent
    │   └─ 只传递任务描述
    │
    ├─ 安排 Review Sub Agent
    │   └─ 只传递需要审查的代码
    │
    └─ 安排 Test Sub Agent
        └─ 只传递需要测试的功能
```

**每个 Sub Agent 只能看到必要信息**

| Sub Agent | 可以看到 | 不能看到 |
|-----------|---------|---------|
| **Execute** | 任务描述、项目代码 | 其他 Sub Agents 的工作 |
| **Review** | 需要审查的代码 | 实现过程、其他 Sub Agents |
| **Test** | 需要测试的功能 | 实现细节、审查过程 |

### 4.2 为什么隔离

- **Execute 不受 Review 影响**: 专注实现
- **Review 不受 Execute 过程影响**: 客观评估
- **Test 不受实现细节影响**: 独立验证

---

## 5. 完整工作流示例

### 5.1 实现用户认证系统

```
┌─────────────────────────────────────────────────────────────┐
│  用户: "实现用户认证系统"                                     │
└─────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────┐
│  Main Agent 分析决策                                          │
│                                                              │
│  这是一个复杂任务，需要:                                     │
│  1. 先用 planning skill 规划                                │
│  2. 安排 Execute Sub Agents 实现                            │
│  3. 安排 Review Sub Agent 审查                              │
│  4. 安排 Test Sub Agent 测试                                │
│  5. 验收整合                                                │
└─────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────┐
│  1. Main Agent: planning skill                              │
│                                                              │
│  分析需求:                                                   │
│  - 用户认证: JWT 方案                                        │
│  - 后端: /auth/login, /auth/register                        │
│  - 前端: 登录页面、注册页面                                  │
│  - 测试: 单元测试 + E2E 测试                                 │
│                                                              │
│  输出规划文档                                               │
└─────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────┐
│  2. Main Agent: 安排 Execute Sub Agents                     │
│                                                              │
│  Agent({                                                     │
│    subagent_type: "claude",                                 │
│    prompt: `                                                 │
│      作为后端开发专家，实现 JWT 认证 API:                    │
│                                                              │
│      ${planResult.backendTask}                              │
│                                                              │
│      技术要求:                                               │
│      - JWT 认证                                              │
│      - bcrypt 密码哈希                                       │
│      - 编写单元测试                                          │
│    `                                                         │
│  })                                                         │
│                                                              │
│  Agent({                                                     │
│    subagent_type: "claude",                                 │
│    prompt: `                                                 │
│      作为前端开发专家，实现登录注册页面:                      │
│                                                              │
│      ${planResult.frontendTask}                             │
│                                                              │
│      技术要求:                                               │
│      - shadcn/ui 组件                                        │
│      - 表单验证                                              │
│      - 调用后端 API                                          │
│    `                                                         │
│  })                                                         │
└─────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────┐
│  3. Main Agent: 安排 Review Sub Agent                       │
│                                                              │
│  Agent({                                                     │
│    subagent_type: "claude",                                 │
│    prompt: `                                                 │
│      作为代码审查专家，审查以下文件:                          │
│                                                              │
│      ${executeResult.files}                                 │
│                                                              │
│      检查:                                                   │
│      - 代码质量                                              │
│      - 安全性 (JWT、密码处理)                                │
│      - 性能                                                  │
│    `                                                         │
│  })                                                         │
└─────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────┐
│  4. Main Agent: 安排 Test Sub Agent                         │
│                                                              │
│  Agent({                                                     │
│    subagent_type: "claude",                                 │
│    prompt: `                                                 │
│      作为测试工程师，验证用户认证功能:                       │
│                                                              │
│      ${executeResult.features}                              │
│                                                              │
│      测试:                                                   │
│      - 单元测试覆盖                                          │
│      - E2E 测试 (登录、注册、登出)                           │
│      - 边界情况测试                                          │
│    `                                                         │
│  })                                                         │
└─────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────┐
│  5. Main Agent: 验收整合                                    │
│                                                              │
│  收集结果:                                                   │
│  • Execute 结果: 后端 API + 前端页面                        │
│  • Review 结果: 代码通过审查                                │
│  • Test 结果: 测试全部通过                                  │
│                                                              │
│  整合并提交 Git                                            │
└─────────────────────────────────────────────────────────────┘
```

### 5.2 修复 Bug (更简单的流程)

```
┌─────────────────────────────────────────────────────────────┐
│  用户: "登录接口报错"                                        │
└─────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────┐
│  Main Agent 分析决策                                          │
│                                                              │
│  这是一个简单任务，不需要规划:                               │
│  1. 安排 debugger Sub Agent 定位问题                        │
│  2. 安排 Execute Sub Agent 修复                             │
│  3. 安排 Test Sub Agent 验证                                │
│  4. 验收整合                                                │
└─────────────────────────────────────────────────────────────┘
                          ↓
Main Agent 直接安排 Sub Agents...
```

**注意**: 这个流程没有 planning 阶段，Main 根据任务需要直接跳过了

---

## 6. Superpowers 集成

### 6.1 Main Agent 使用 Superpowers

```javascript
// 复杂任务，先规划
const plan = await /plan "设计用户认证系统"

// 根据规划安排 Sub Agents
// ...
```

### 6.2 Sub Agent 使用 Superpowers

```javascript
// Execute Sub Agent 内部也可以使用 Superpowers

Agent({
  subagent_type: "claude",
  prompt: `
作为后端开发专家，实现 JWT 认证 API。

完成后:
1. 使用 backend-dev skill 自我审查代码
2. 使用 test-engineer skill 编写测试
3. 返回完整结果
  `
})

// Sub Agent 内部流程:
// 1. 编写代码
// 2. backend-dev 自我审查
// 3. test-engineer 编写测试
// 4. 返回结果
```

### 6.3 所有 Agent 共享

```
Main Agent
    │
    ├─ planning skill
    ├─ debugger skill
    ├─ ... (其他 Superpowers)
    └─ Agent 工具编排

Sub Agents
    │
    ├─ backend-dev skill
    ├─ frontend-dev skill
    ├─ CODE-REVIEW skill
    ├─ test-engineer skill
    ├─ ... (其他 Superpowers)
    └─ Agent 工具 (可启动更深层 Agent)

Superpowers Skills
    │
    ├─ planning
    ├─ CODE-REVIEW
    ├─ test-engineer
    ├─ backend-dev
    ├─ frontend-dev
    ├─ debugger
    ├─ ... (100+ skills)
```

---

## 7. 动态编排模式

### 7.1 Main Agent 决策逻辑

```javascript
// Main Agent 分析任务
async function orchestrate(task) {
  const analysis = await analyzeTask(task)

  // 根据分析结果决定编排策略

  if (analysis.complexity === "low") {
    // 简单任务: 直接 Execute
    const execute = await agent({ prompt: `执行: ${task}` })
    return await integrate(execute)
  }

  if (analysis.complexity === "medium") {
    // 中等任务: Execute + Review
    const execute = await agent({ prompt: `执行: ${task}` })
    const review = await agent({ prompt: `审查: ${execute.files}` })
    return await integrate(execute, review)
  }

  if (analysis.complexity === "high") {
    // 复杂任务: Plan + Execute + Review + Test
    const plan = await /plan `分析: ${task}`
    const execute = await agent({ prompt: `执行: ${plan}` })
    const review = await agent({ prompt: `审查: ${execute.files}` })
    const test = await agent({ prompt: `测试: ${execute.features}` })
    return await integrate(plan, execute, review, test)
  }
}
```

### 7.2 并行编排

```javascript
// Main Agent 可以并行安排多个 Sub Agents
const [backend, frontend] = await Promise.all([
  agent({ prompt: "后端: 实现 API" }),
  agent({ prompt: "前端: 实现页面" })
])
```

### 7.3 串行编排

```javascript
// Main Agent 可以串行安排 Sub Agents
const execute = await agent({ prompt: "实现功能" })
const review = await agent({ prompt: `审查: ${execute.files}` })
const test = await agent({ prompt: `测试: ${execute.features}` })
```

### 7.4 条件编排

```javascript
// Main Agent 根据中间结果决定下一步
const execute = await agent({ prompt: "实现功能" })
const review = await agent({ prompt: `审查: ${execute.files}` })

if (review.passed) {
  // 审查通过，直接验收
  return await integrate(execute, review)
} else {
  // 审查不通过，安排修复
  const fix = await agent({ prompt: `修复问题: ${review.findings}` })
  const review2 = await agent({ prompt: `重新审查: ${fix.files}` })
  return await integrate(fix, review2)
}
```

---

## 8. 配置文件

### 8.1 Main Agent CLAUDE.md

```markdown
# sanguo_moziplus_v3 - Main Agent (编排者)

## 角色

你是任务编排者，负责根据任务需要动态安排 Sub Agents。

## 核心职责

1. 分析任务需求
2. 根据需要决定安排哪些 Sub Agents
3. 协调 Sub Agents 之间的协作
4. 最终验收和整合

## Sub Agent 类型

### Execute Sub Agents
- backend-dev: 后端开发
- frontend-dev: 前端开发
- database-dev: 数据库开发
- infrastructure: 基础设施

### Review Sub Agents
- CODE-REVIEW: 代码质量审查
- security-reviewer: 安全审查
- performance-reviewer: 性能审查

### Test Sub Agents
- test-engineer: 单元测试
- e2e-tester: 端到端测试
- qa-tester: 质量保证测试

## 工作方式

**不是固化流程，根据任务需要灵活安排**

### 简单任务
```
分析 → 安排 Execute → 验收整合
```

### 中等任务
```
分析 → 安排 Execute → 安排 Review → 验收整合
```

### 复杂任务
```
分析 → planning → 安排 Execute → 安排 Review → 安排 Test → 验收整合
```

### 调试任务
```
分析 → 安排 debugger → 安排 Execute (修复) → 安排 Test (验证) → 验收整合
```

## 严格限制

- 不亲自编写代码
- 不亲自执行具体实现

## 可用能力 (Superpowers)

- planning — 复杂任务的方案规划
- debugger — 问题诊断
- 其他 100+ Superpowers skills
- Agent 工具编排

## Sub Agent 指派

\`\`\`javascript
// Execute
Agent({
  subagent_type: "claude",
  prompt: \`作为后端开发专家，实现: \${task}\`
})

// Review
Agent({
  subagent_type: "claude",
  prompt: \`作为代码审查专家，审查: \${files}\`
})

// Test
Agent({
  subagent_type: "claude",
  prompt: \`作为测试工程师，测试: \${features}\`
})
\`\`\`

## 上下文隔离

- Execute Sub Agent: 只看任务描述
- Review Sub Agent: 只看需要审查的代码
- Test Sub Agent: 只看需要测试的功能

## 决策框架

在安排 Sub Agents 之前问自己:
1. 这个任务需要哪些 Sub Agents?
2. 需要 planning 吗?
3. Sub Agents 之间有依赖关系吗?
4. 可以并行执行吗?
```

---

## 9. 实施步骤

### Phase 1: 环境准备

#### 1.1 配置 GLM-5.2

```json
// ~/.claude/settings.json
{
  "env": {
    "CLAUDE_CODE_AUTO_COMPACT_WINDOW": "1000000",
    "ANTHROPIC_BASE_URL": "https://api.z.ai/api/anthropic",
    "ANTHROPIC_API_KEY": "你的智谱API_Key",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "glm-5.2[1m]",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "glm-5.2[1m]"
  }
}
```

### Phase 2: 创建项目结构

```bash
cd ~/.openclaw/sanguo_projects/sanguo_moziplus_v3

# 创建配置
mkdir -p .claude/workflows
```

### Phase 3: 创建 Main Agent 配置

创建 `.claude/CLAUDE.md` (使用第 8.1 节内容)

### Phase 4: 创建工作流脚本

创建 `.claude/workflows/dynamic-orchestration.js`:

```javascript
export const meta = {
  name: 'dynamic-orchestration',
  description: 'Main Agent 根据任务需要动态编排 Sub Agents',
  phases: [
    { title: '分析', detail: 'Main Agent 分析任务需求' },
    { title: '编排', detail: 'Main Agent 决定安排哪些 Sub Agents' },
    { title: '执行', detail: 'Sub Agents 执行任务' },
    { title: '验收', detail: 'Main Agent 验收整合' }
  ]
}

export default async function (task) {
  // 1. Main Agent 分析任务
  phase('分析')
  const analysis = await analyzeTask(task)

  log(`任务复杂度: ${analysis.complexity}`)
  log(`需要的 Sub Agents: ${analysis.requiredAgents.join(', ')}`)

  // 2. Main Agent 根据分析结果编排
  phase('编排')
  const results = []

  if (analysis.needPlan) {
    phase('Plan')
    const plan = await /plan `分析: ${task}`
    results.push({ plan })
    log(`✅ Plan 完成`)
  }

  // 3. Execute Sub Agents
  phase('Execute')
  if (analysis.requiredAgents.includes('backend')) {
    const backend = await agent({
      subagent_type: 'claude',
      prompt: `作为后端开发专家，实现: ${analysis.backendTask}`,
      label: 'Backend Execute'
    })
    results.push({ backend })
    log(`✅ Backend Execute 完成`)
  }

  if (analysis.requiredAgents.includes('frontend')) {
    const frontend = await agent({
      subagent_type: 'claude',
      prompt: `作为前端开发专家，实现: ${analysis.frontendTask}`,
      label: 'Frontend Execute'
    })
    results.push({ frontend })
    log(`✅ Frontend Execute 完成`)
  }

  // 4. Review Sub Agent
  phase('Review')
  if (analysis.requiredAgents.includes('review')) {
    const files = results.flatMap(r => r.backend?.files || r.frontend?.files || [])
    const review = await agent({
      subagent_type: 'claude',
      prompt: `作为代码审查专家，审查: ${files.join(', ')}`,
      label: 'Review'
    })
    results.push({ review })
    log(`✅ Review 完成`)
  }

  // 5. Test Sub Agent
  phase('Test')
  if (analysis.requiredAgents.includes('test')) {
    const features = results.flatMap(r => r.backend?.features || r.frontend?.features || [])
    const test = await agent({
      subagent_type: 'claude',
      prompt: `作为测试工程师，测试: ${features.join(', ')}`,
      label: 'Test'
    })
    results.push({ test })
    log(`✅ Test 完成`)
  }

  // 6. Main Agent 验收整合
  phase('验收整合')
  const integrated = await integrateResults(results)
  log(`✅ 验收完成`)

  return integrated
}

// 辅助函数
async function analyzeTask(task) {
  return await agent({
    subagent_type: 'Plan',
    prompt: `
分析任务: "${task}"

返回 JSON:
{
  "complexity": "low|medium|high",
  "needPlan": true|false,
  "requiredAgents": ["backend", "frontend", "review", "test"],
  "backendTask": "后端任务描述",
  "frontendTask": "前端任务描述"
}
    `,
    schema: AnalysisSchema
  })
}

async function integrateResults(results) {
  // Main Agent 整合所有结果
  return {
    plan: results.find(r => r.plan),
    execute: results.filter(r => r.backend || r.frontend),
    review: results.find(r => r.review),
    test: results.find(r => r.test),
    status: '完成'
  }
}

const AnalysisSchema = {
  type: "object",
  properties: {
    complexity: { type: "string", enum: ["low", "medium", "high"] },
    needPlan: { type: "boolean" },
    requiredAgents: { type: "array", items: { type: "string" } },
    backendTask: { type: "string" },
    frontendTask: { type: "string" }
  }
}
```

### Phase 5: 验证测试

```javascript
// 测试简单任务
Workflow({
  scriptPath: ".claude/workflows/dynamic-orchestration.js",
  args: "修复登录页面样式"
})

// 测试复杂任务
Workflow({
  scriptPath: ".claude/workflows/dynamic-orchestration.js",
  args: "实现用户认证系统"
})
```

---

## 10. 优势对比

| 方面 | v0.4 (三实例) | v0.5 (Main + Sub) |
|------|--------------|-------------------|
| **Main 角色** | 架构师 (Plan + Review) | **编排者 + 验收整合** |
| **Sub Agent 角色** | backend/frontend 执行 | **Execute/Review/Test 专业角色** |
| **工作流** | 固化流程 | **Main 根据需求动态安排** ✅ |
| **编排方式** | SendMessage 跨实例 | **Agent 工具** ✅ |
| **灵活性** | 固定三个实例 | **动态 Sub Agents** ✅ |

---

## 11. 精髓总结

### v0.5 设计精髓

1. **Main Agent 是编排者**: 根据任务需要动态安排 Sub Agents
2. **不是固化流程**: Main 根据需求灵活调整
3. **专业分工**: Sub Agents 有明确的专业角色
4. **上下文隔离**: 每个 Sub Agent 只能看到必要信息
5. **共享能力**: 所有 Agent 都遵循 Superpowers 工作方式

### 与 v0.4 的区别

| v0.4 | v0.5 |
|------|------|
| 架构师 Plan + Review | Main 编排 + 验收 |
| backend/frontend 执行 | Execute/Review/Test 专业角色 |
| 固化工作流 | **Main 根据需求动态安排** |
| SendMessage 跨实例 | Agent 工具 |

### 关键变化

**v0.5 更灵活**:
- Main 不是固化的 Plan/Review 角色
- Sub Agents 有更细的专业分工
- 工作流不是固化的，Main 根据任务需要安排

---

**文档版本**: v0.5
**最后更新**: 2026-07-01
**作者**: Claude Dev
**审核状态**: Draft
**实施状态**: 设计阶段