sanguo_moziplus_v3/docs/sub-agent-orchestration.md

# Sub Agent Orchestration 方案

## 概述

使用 Main + Sub Agent 架构替代 CCB（Claude Code Blackboard）方案。

## 架构

```
┌─────────────────────────────────────────────────────────┐
│                    Main Agent (Planner)                  │
│  - 需求分析、任务拆分、指派 Sub Agent                     │
│  - 收集结果、最终审查、整合                               │
└─────────────────────────────────────────────────────────┘
           │                    │
           ▼                    ▼
┌──────────────────┐  ┌──────────────────┐
│ Sub Agent 1      │  │ Sub Agent 2      │
│ (Executor)       │  │ (Reviewer)       │
│ - 执行编码任务   │  │ - 代码审查       │
│ - 编写测试       │  │ - 质量检查       │
└──────────────────┘  └──────────────────┘
```

## 关键特性

### 1. 默认隔离

- **会话历史隔离**：Sub Agent 看不到 Main Agent 的对话
- **文件访问共享**：Sub Agent 可以读写项目文件
- **工作目录相同**：所有 Agent 在同一项目目录

### 2. 通信机制

**Main → Sub**: 通过 `Agent` 工具指派任务
```javascript
Agent({
  subagent_type: "executor",
  prompt: "实现用户认证 API: ..."
})
```

**Sub → Main**: 通过返回结果
```javascript
// Sub Agent 完成后返回结构化结果
return {
  files: ["src/auth.ts", "src/auth.test.ts"],
  tests: "12/12 通过",
  status: "完成"
}
```

### 3. 并行执行

```javascript
// 并行启动多个 Sub Agent
Agent({ subagent_type: "executor", prompt: "..." })
Agent({ subagent_type: "reviewer", prompt: "..." })
```

## 工作流示例

### 完整开发流程

#### 1. Main Agent 接收需求

```javascript
// 用户: "实现用户认证功能"
// Main Agent 分析需求
```

#### 2. Main Agent 拆分任务

```javascript
const task = {
  feature: "用户认证",
  subtasks: [
    { role: "executor", task: "实现 JWT 认证 API" },
    { role: "executor", task: "编写单元测试" },
    { role: "reviewer", task: "代码审查" }
  ]
}
```

#### 3. Main Agent 指派 Sub Agent

```javascript
// 指派 Executor
const executorResult = await Agent({
  subagent_type: "claude",
  prompt: `
作为后端开发专家，实现用户认证 API:
1. POST /auth/login - 用户登录
2. POST /auth/register - 用户注册
3. 使用 bcrypt 和 JWT
4. 编写测试
返回结构化结果: { files, tests, status }
  `
})
```

#### 4. Main Agent 收集结果

```javascript
// 指派 Reviewer
const reviewResult = await Agent({
  subagent_type: "claude",
  prompt: `
作为代码审查专家，审查以下文件:
${executorResult.files.join(', ')}
检查: 代码质量、测试覆盖、安全性
返回: { findings, approval }
  `
})
```

#### 5. Main Agent 整合

```javascript
if (reviewResult.approval) {
  // 整合代码，提交 Git
  await整合提交()
}
```

## Sub Agent 类型

### 1. Executor（执行者）

**职责**：
- 编写代码
- 编写测试
- 实现功能

**技能**：backend-dev, frontend-dev

### 2. Reviewer（审查者）

**职责**：
- 代码审查
- 质量检查
- 安全性验证

**技能**：CODE-REVIEW, test-automation-skills

### 3. Planner（规划者 - Main）

**职责**：
- 需求分析
- 任务拆分
- 资源协调
- 最终验收

## 优势对比 CCB

| 特性 | Main+Sub | CCB |
|------|----------|-----|
| 会话隔离 | ✅ 默认 | ⚠️ 需手动管理 |
| 通信机制 | Agent 工具 | Blackboard |
| 并行执行 | ✅ 支持 | ⚠️ 复杂 |
| 上下文共享 | 通过文件 | 通过 Blackboard |
| 学习成本 | 🟢 低 | 🟡 中 |

## 实施步骤

### 步骤 1: 定义 Sub Agent 类型

在项目 `.claude/` 目录创建配置：

```json
{
  "subAgents": {
    "executor": {
      "description": "执行编码任务",
      "skills": ["backend-dev", "frontend-dev"]
    },
    "reviewer": {
      "description": "代码审查",
      "skills": ["CODE-REVIEW", "qa-test-planner"]
    }
  }
}
```

### 步骤 2: Main Agent 加载协调技能

```bash
# Main Agent 启动时加载
/skill architect-role
```

### 步骤 3: 工作流脚本

创建 `.claude/workflows/` 目录：

```javascript
// workflows/feature-development.js
export default {
  name: "feature-development",
  run: async (feature) => {
    // 1. 分析
    const plan = await分析需求(feature)
    
    // 2. 指派执行
    const result = await Agent({
      subagent_type: "executor",
      prompt: plan.executorTask
    })
    
    // 3. 审查
    const review = await Agent({
      subagent_type: "reviewer",
      prompt: `审查: ${result.files}`
    })
    
    // 4. 整合
    return 整合结果(result, review)
  }
}
```

## 命名规范

- Main Agent: `main` 或 `planner`
- Sub Agent: `executor`, `reviewer`, 或具体任务名
- Agent ID: 自动生成，格式 `a_<random>`

## 调试和监控

### 查看 Sub Agent 状态

```bash
# 列出当前运行的所有 Agent
/agents

# 查看 Sub Agent 输出
Agent({ subagent_type: "executor", prompt: "..." })
// 返回 agentId，可以用 TaskOutput 查看输出
```

### Sub Agent 输出结构

```javascript
{
  "agentId": "a_123abc",
  "status": "completed",
  "result": {
    "files": ["src/auth.ts"],
    "tests": "12/12 通过"
  }
}
```

## 局限性

1. **Sub Agent 无法主动通信**：只能通过返回值
2. **无持久化 Blackboard**：需要用文件共享状态
3. **Agent 数量限制**：系统限制最大并发数

## 最佳实践

1. **明确任务边界**：每个 Sub Agent 职责单一
2. **结构化返回**：使用 JSON 格式返回结果
3. **文件作为状态**：用文件存储中间状态
4. **Main 协调一切**：Sub Agent 只执行任务

## 相关文档

- [Agent 工具文档](https://docs.anthropic.com/claude-code/agent)
- [设计文档](./design/04-design-v0.4.md)
- [示例工作流](./05-example-workflows.md)