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 工具指派任务

Agent({
  subagent_type: "executor",
  prompt: "实现用户认证 API: ..."
})

Sub → Main: 通过返回结果

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

3. 并行执行

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

工作流示例

完整开发流程

1. Main Agent 接收需求

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

2. Main Agent 拆分任务

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

3. Main Agent 指派 Sub Agent

// 指派 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 收集结果

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

5. Main Agent 整合

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/ 目录创建配置：

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

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

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

步骤 3: 工作流脚本

创建 .claude/workflows/ 目录：

// 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 状态

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

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

Sub Agent 输出结构

{
  "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 工具文档
• 设计文档
• 示例工作流