sanguo/sanguo_moziplus_v3
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
- 创建 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>
This commit is contained in:
Claude Dev
2026-07-01 08:23:58 +08:00
parent ddccd8fbfa
commit 449eec9df7
4 changed files with 1587 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/design/05-migration-to-sub-agent.md
+266
View File
@@ -0,0 +1,266 @@
# v0.4 → Main + Sub Agent 迁移计划
## 概述
将三实例方案 (v0.4) 迁移到 Main + Sub Agent 架构。
## 架构对比
### v0.4 (三实例)
```
┌─────────────────────────────────────────┐
│ tmux sanguo_dev │
│ ┌─────────────┐ ┌─────────┐ ┌───────┐ │
│ │ Claude │ │ Codex │ │Gemini │ │
│ │ (架构师) │ │(后端) │ │(前端) │ │
│ └─────────────┘ └─────────┘ └───────┘ │
└─────────────────────────────────────────┘
通信: SendMessage 跨实例
项目: 3 个独立目录
```
### Main + Sub Agent
```
┌─────────────────────────────────────────┐
│ sanguo_moziplus_v3 项目 │
│ ┌───────────────────────────────────┐ │
│ │ Main Agent (架构师) │ │
│ │ - 分析需求 │ │
│ │ - Agent() 指派 Sub Agent │ │
│ │ - 整合结果 │ │
│ └───────────────────────────────────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌──────────────┐ ┌──────────────┐ │
│ │ Sub Agent 1 │ │ Sub Agent 2 │ │
│ │ (Executor) │ │ (Reviewer) │ │
│ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────┘
通信: Agent 工具
项目: 1 个目录
```
## 迁移映射
| 组件 | v0.4 | 目标 | 操作 |
|------|------|------|------|
| **Claude Code 实例** | 3 个 | 1 个 | 移除多余实例 |
| **项目目录** | 3 个 | 1 个 | 保留 sanguo_moziplus_v3 |
| **CLAUDE.md** | 3 个文件 | 1 个文件 | 合并到主项目 |
| **SendMessage** | 跨实例 | Agent 工具 | 替换通信方式 |
| **tmux 配置** | ~/.tmux-sanguo.conf | 不需要 | 删除 |
| **启动脚本** | start-sanguo-env.sh | 不需要 | 删除 |
| **消息队列** | message.sh | 不需要 | 删除 |
| **ttyd Web** | 8088 端口 | 可选 | 保留用于远程 |
| **角色 Skills** | 3 个 | 3 个 | ✅ 保留 |
| **Superpowers** | 共享 | 共享 | ✅ 保留 |
| **GLM-5.2** | 统一后端 | 统一后端 | ✅ 保留 |
## 迁移步骤
### 步骤 1: 保留部分
#### 1.1 保留 Superpowers Skills
**无需操作** - 已安装在 `~/.claude/skills/`
#### 1.2 保留角色 Skills
**无需操作** - 已创建:
- `~/.claude/skills/architect-role/`
- `~/.claude/skills/backend-dev/`
- `~/.claude/skills/frontend-dev/`
#### 1.3 保留 GLM-5.2 配置
**无需操作** - 已在 `~/.claude/settings.json`
### 步骤 2: 创建 Main Agent 配置
#### 2.1 创建主项目 CLAUDE.md
在 `sanguo_moziplus_v3/.claude/CLAUDE.md`:
```markdown
# sanguo_moziplus_v3 - Main Agent
## 角色
你是架构师/项目经理，负责协调 Sub Agent 完成开发任务。
## 核心职责
- 接收用户需求
- 分析并拆分任务
- 指派 Sub Agent 执行
- 收集并整合结果
- 最终审查和验收
## 严格限制
**绝对不亲自编写代码**。所有编码任务通过 Agent 工具指派给 Sub Agent。
## 工作流程
1. 接收用户需求
2. 加载 architect-role skill
3. 分析需求，拆分任务
4. 使用 Agent 工具指派 Sub Agent:
```javascript
Agent({
subagent_type: "claude",
prompt: "作为后端开发专家，实现: ..."
})
```
5. 收集 Sub Agent 返回结果
6. 加载 CODE-REVIEW skill 审查
7. 整合结果并提交 Git
## Sub Agent 类型
- **Executor**: 执行编码任务 (加载 backend-dev/frontend-dev)
- **Reviewer**: 代码审查 (加载 CODE-REVIEW)
## 决策框架 (Linus 三问)
1. 这是现实问题还是想象问题？
2. 这个问题真的需要解决吗？
3. 这个方案真的能解决问题吗？
```
### 步骤 3: 创建工作流
已在 `.claude/workflows/feature-development.js`
### 步骤 4: 清理 v0.4 组件
#### 4.1 可以删除的文件
```bash
# tmux 配置 (可选删除，如果不用三实例)
rm ~/.tmux-sanguo.conf
# 旧项目目录 (可选删除，如果不再使用)
rm -rf ~/.claude/projects/sanguo-main
rm -rf ~/.claude/projects/sanguo-backend
rm -rf ~/.claude/projects/sanguo-frontend
# 启动脚本 (可选删除)
rm ~/.claude/messages/sanguo/start-sanguo-env.sh
rm ~/.claude/messages/sanguo/message.sh
```
#### 4.2 保留的文件
```bash
# 角色 Skills - 保留
~/.claude/skills/architect-role/
~/.claude/skills/backend-dev/
~/.claude/skills/frontend-dev/
# GLM-5.2 配置 - 保留
~/.claude/settings.json
# 可选: ttyd 配置 (如果需要 Web 访问)
~/.ttyd
```
### 步骤 5: 更新文档
#### 5.1 创建新设计文档
`docs/design/06-design-v0.5-sub-agent.md`
#### 5.2 更新快速参考
`docs/06-quick-reference-v0.5.md`
### 步骤 6: 验证测试
#### 6.1 测试 Agent 工具
```javascript
// 在 Main Agent 中测试
Agent({
subagent_type: "claude",
prompt: "作为后端开发专家，编写一个简单的 Hello World API"
})
```
#### 6.2 测试工作流
```javascript
Agent({
scriptPath: ".claude/workflows/feature-development.js",
args: "实现用户登录功能"
})
```
## 对比表
| 方面 | v0.4 三实例 | Main + Sub Agent |
|------|-------------|------------------|
| **复杂度** | 🟡 中等 | 🟢 简单 |
| **启动** | 需要启动脚本 | 直接使用 |
| **通信** | SendMessage (有限制) | Agent 工具 |
| **隔离** | 实例级别 | 会话级别 |
| **并行** | ⚠️ 复杂 | ✅ 支持 |
| **学习成本** | 🟡 中等 | 🟢 低 |
| **维护成本** | 🟡 中等 | 🟢 低 |
| **Web 访问** | ✅ ttyd + tmux | ⚠️ 需要 Claude Code |
## 优势
Main + Sub Agent 方案优势:
1. **更简单**: 不需要 tmux、启动脚本
2. **更灵活**: Sub Agent 自动隔离、并行执行
3. **更可靠**: Agent 工具是内置功能，无跨实例限制
4. **更易维护**: 单一项目目录
## 迁移检查清单
### 保留
- [x] Superpowers skills
- [x] 角色 Skills (architect-role, backend-dev, frontend-dev)
- [x] GLM-5.2 配置
- [ ] ttyd (可选)
### 创建
- [ ] .claude/CLAUDE.md
- [ ] .claude/workflows/feature-development.js
- [ ] docs/design/06-design-v0.5-sub-agent.md
- [ ] docs/06-quick-reference-v0.5.md
### 删除
- [ ] ~/.tmux-sanguo.conf
- [ ] ~/.claude/projects/sanguo-*
- [ ] ~/.claude/messages/sanguo/*.sh
### 测试
- [ ] Agent 工具测试
- [ ] 工作流测试
- [ ] Skills 加载测试
## 回滚方案
如果需要回滚到 v0.4:
```bash
# 恢复项目目录
# 从 Git 恢复或重新创建
# 重新运行 v0.4 设置
~/.claude/messages/sanguo/test-sanguo-env.sh
~/.claude/messages/sanguo/start-sanguo-env.sh
```
## 相关文档
- [v0.4 设计文档](./04-design-v0.4.md)
- [Sub Agent 方案](../sub-agent-orchestration.md)
- [Agent 工具文档](https://docs.anthropic.com/claude-code/agent)
docs/design/06-design-v0.5-dynamic-orchestration.md
+876
View File
@@ -0,0 +1,876 @@
# 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
**实施状态**: 设计阶段
docs/sub-agent-orchestration.md
+271
View File
@@ -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)