claude_dev
449eec9df7
- 创建 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>
29 KiB
29 KiB
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 关键特性
- 动态编排: Main 根据任务需要决定安排哪些 Sub Agents
- 专业分工: Sub Agents 有明确的专业角色
- 上下文隔离: 每个 Sub Agent 只能看到必要信息
- 共享能力: 所有 Agent 都遵循 Superpowers 工作方式
- 灵活调整: 不是固化流程，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
// 复杂任务，先规划
const plan = await /plan "设计用户认证系统"
// 根据规划安排 Sub Agents
// ...
6.2 Sub Agent 使用 Superpowers
// 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 决策逻辑
// 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 并行编排
// Main Agent 可以并行安排多个 Sub Agents
const [backend, frontend] = await Promise.all([
agent({ prompt: "后端: 实现 API" }),
agent({ prompt: "前端: 实现页面" })
])
7.3 串行编排
// 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 条件编排
// 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
# 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
// ~/.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: 创建项目结构
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:
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: 验证测试
// 测试简单任务
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 设计精髓
- Main Agent 是编排者: 根据任务需要动态安排 Sub Agents
- 不是固化流程: Main 根据需求灵活调整
- 专业分工: Sub Agents 有明确的专业角色
- 上下文隔离: 每个 Sub Agent 只能看到必要信息
- 共享能力: 所有 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 实施状态: 设计阶段