docs: 添加 v0.5 动态编排设计

- 创建 Main + Sub Agent 动态编排方案 - Main Agent 作为编排者，根据任务需要动态安排 Sub Agents - Sub Agents 分为 Execute、Review、Test 专业角色 - 不是固化工作流，而是 Main 根据需求灵活调整 - 添加上下文隔离原则 - 创建工作流脚本模板 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-01 08:23:58 +08:00
parent ddccd8fbfa
commit 449eec9df7
4 changed files with 1587 additions and 0 deletions
@@ -0,0 +1,271 @@
+# 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)