From 9c6eaa2ebdbc24a812814a44a3a19ae79d7f645f Mon Sep 17 00:00:00 2001 From: claude_dev Date: Wed, 1 Jul 2026 19:32:31 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=20v0.5=20=E5=8A=A8?= =?UTF-8?q?=E6=80=81=E7=BC=96=E6=8E=92=E8=AE=BE=E8=AE=A1=E6=96=87=E6=A1=A3?= =?UTF-8?q?=E6=95=B4=E5=90=88=E7=89=88?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 整合 06 文档，消除重复内容 - 重组结构：概述→设计精髓→角色→编排→Superpowers→工作流→实施→对比 - 清理历史调研痕迹 - 添加清晰的设计叙述主线 Co-Authored-By: Claude Opus 4.8 (1M context) --- ...n-v0.5-dynamic-orchestration-integrated.md | 1245 +++++++++++++++++ 1 file changed, 1245 insertions(+) create mode 100644 docs/design/07-design-v0.5-dynamic-orchestration-integrated.md diff --git a/docs/design/07-design-v0.5-dynamic-orchestration-integrated.md b/docs/design/07-design-v0.5-dynamic-orchestration-integrated.md new file mode 100644 index 0000000..4924602 --- /dev/null +++ b/docs/design/07-design-v0.5-dynamic-orchestration-integrated.md @@ -0,0 +1,1245 @@ +# sanguo_moziplus_v3 设计文档 v0.5 (整合版) + +**项目名称**: sanguo_moziplus_v3 +**版本**: v0.5.1 +**创建日期**: 2026-07-01 +**状态**: Draft +**核心理念**: Main Agent 根据任务需求动态编排 Sub Agents + +--- + +## 1. 概述 + +### 1.1 项目简介 + +sanguo_moziplus_v3 是一个基于 Claude Code 的多 Agent 协作系统，采用 **Main Agent + Sub Agents** 的动态编排架构。 + +**核心特点**： +- Main Agent 作为编排者，根据任务需要动态安排 Sub Agents +- 集成 Superpowers 五技能体系，提供标准化工作流 +- 通过 Linus 三问进行工程审慎决策 +- 上下文隔离确保各 Agent 专注执行 + +### 1.2 版本变更 + +| 版本 | 变更说明 | 日期 | +|------|---------|------| +| 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.1** | **补充 Linus 三问 + Superpowers 五技能体系** | **2026-07-01** | + +### 1.3 核心变化 + +| 变更项 | v0.4 | v0.5 | 原因 | +|--------|------|------|------| +| **编排方式** | SendMessage 跨实例 | **Agent 工具动态编排** | 更灵活的协作 | +| **Main 角色** | 架构师 (Plan + Review) | **需求讨论 + 编排 + 验收整合** | 承担需求讨论职责 | +| **需求讨论** | 无明确机制 | **deep-interview skill** | 系统化需求提取 | +| **Sub Agent 角色** | backend/frontend 执行 | **Execute/Review/Test 专业角色** | 更细的分工 | +| **工作流** | 固化流程 | **Main 根据需求动态安排** | 更灵活 | + +--- + +## 2. 设计精髓 + +### 2.1 核心理念 + +**Main Agent 根据任务需求动态编排 Sub Agents** + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ Main Agent (编排者) │ +│ │ +│ 职责: │ +│ • 与用户讨论需求 (deep-interview skill) │ +│ • 分析任务复杂度和范围 │ +│ • Linus 三问工程审慎决策 │ +│ • 根据任务需要动态安排 Sub Agents │ +│ • 不是固化流程，而是灵活调整 │ +│ • 最终验收和整合 (CODE-REVIEW) │ +│ │ +│ 能力 (依托 Superpowers): │ +│ • deep-interview — 需求讨论和知识提取 │ +│ • writing-plans — 复杂任务的方案规划 │ +│ • CODE-REVIEW — 代码审查验证 │ +│ • 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: 快速确认需求 (AskUserQuestion) + ↓ +分析后决定 + ↓ +安排 Execute Sub Agent (修复) + ↓ +验收整合 +``` + +#### 中等任务 + +``` +用户: "实现用户登录功能" + ↓ +Main Agent: 使用 deep-interview 讨论需求 + ↓ +分析后决定 + ↓ +安排 Execute Sub Agent (实现) + ↓ +安排 Review Sub Agent (审查) + ↓ +验收整合 +``` + +#### 复杂任务 + +``` +用户: "实现完整的用户认证系统" + ↓ +Main Agent: 使用 deep-interview 深度讨论需求 + ↓ +使用 writing-plans skill 分析和规划 + ↓ +安排 Execute Sub Agent (后端实现) +安排 Execute Sub Agent (前端实现) + ↓ +安排 Review Sub Agent (代码审查) +安排 Review Sub Agent (安全审查) + ↓ +安排 Test Sub Agent (测试验证) + ↓ +验收整合 +``` + +#### 调试任务 + +``` +用户: "登录接口有问题" + ↓ +Main Agent: 询问问题详情 (AskUserQuestion) + ↓ +分析后决定 + ↓ +安排 debugger Sub Agent (定位问题) + ↓ +安排 Execute Sub Agent (修复问题) + ↓ +安排 Test Sub Agent (验证修复) + ↓ +验收整合 +``` + +### 2.3 关键特性 + +1. **需求讨论**: Main Agent 使用 `deep-interview` skill 与用户讨论需求，确保理解正确 +2. **动态编排**: Main 根据任务需要决定安排哪些 Sub Agents +3. **专业分工**: Sub Agents 有明确的专业角色 +4. **上下文隔离**: 每个 Sub Agent 只能看到必要信息 +5. **共享能力**: 所有 Agent 都遵循 Superpowers 工作方式 +6. **灵活调整**: 不是固化流程，Main 可以根据情况调整 +7. **验证整合**: Main Agent 负责 CODE-REVIEW 验收和最终整合 + +--- + +## 3. 角色与职责 + +### 3.1 Main Agent (编排者) + +**职责**: +- **与用户讨论需求** — 使用 `deep-interview` skill 进行系统化需求提取 +- 分析任务需求 — 确定任务复杂度和范围 +- Linus 三问工程审慎决策 +- 根据需要决定安排哪些 Sub Agents +- 协调 Sub Agents 之间的协作 +- **验证整合** — 使用 `CODE-REVIEW` skill 进行代码审查验收 +- 最终整合和提交 + +**能力 (依托 Superpowers)**: +- `deep-interview` — **需求讨论和知识提取** (核心能力) +- `writing-plans` — 复杂任务的方案规划 +- `CODE-REVIEW` — 代码审查验收 +- `debugger` — 问题诊断 +- 其他 100+ Superpowers skills + +**限制**: +- 不亲自编写代码 +- 不亲自执行具体实现 + +**工作方式**: +``` +1. 接收用户输入 +2. 使用 deep-interview 讨论需求 (如需要) +3. Linus 三问工程审慎判断 +4. 分析任务需要什么 +5. 决定安排哪些 Sub Agents +6. 协调执行 +7. 验收整合 (CODE-REVIEW) +8. 向用户汇报结果 +``` + +**需求讨论流程 (deep-interview)**: + +当用户输入不够明确或任务较复杂时，Main Agent 使用 `deep-interview` skill: + +``` +ASK -> LISTEN -> WRITE -> DEEPEN -> REPEAT +``` + +- 每次调用 AskUserQuestion 最多问 2-3 个问题 +- 立即记录答案到文件 +- 根据答案深入追问 +- 直到需求清晰为止 + +### 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 决策逻辑 + +```javascript +// Main Agent 分析任务 +async function orchestrate(task) { + // 0. 需求讨论 (如需要) + if (await needsDiscussion(task)) { + const requirements = await Skill({ + skill: "deep-interview", + args: `${task} 需求讨论` + }) + // 记录到 requirements/requirements.md + log(`需求已记录: ${requirements.path}`) + } + + const analysis = await analyzeTask(task) + + // 根据分析结果决定编排策略 + + if (analysis.complexity === "low") { + // 简单任务: 直接 Execute + const execute = await agent({ prompt: `执行: ${task}` }) + const review = await Skill({ + skill: "code-review", + args: execute.files + }) + return await integrate(execute, review) + } + + if (analysis.complexity === "medium") { + // 中等任务: Execute + Review + Test + const execute = await agent({ prompt: `执行: ${task}` }) + const review = await agent({ prompt: `审查: ${execute.files}` }) + const test = await agent({ prompt: `测试: ${execute.features}` }) + return await integrate(execute, review, test) + } + + if (analysis.complexity === "high") { + // 复杂任务: Plan + Execute + Review + Test + CODE-REVIEW + const plan = await Skill({ + skill: "writing-plans", + args: `分析: ${task}` + }) + const execute = await agent({ prompt: `执行: ${plan}` }) + const review = await agent({ prompt: `审查: ${execute.files}` }) + const test = await agent({ prompt: `测试: ${execute.features}` }) + const codeReview = await Skill({ + skill: "code-review", + args: execute.files + }) + return await integrate(plan, execute, review, test, codeReview) + } +} + +// 判断是否需要需求讨论 +async function needsDiscussion(task) { + // 模糊的需求描述 + const vagueKeywords = ["实现", "添加", "做一个", "弄个"] + // 复杂任务 + const isComplex = task.length > 20 + + return vagueKeywords.some(kw => task.includes(kw)) || isComplex +} +``` + +### 4.2 Linus 三问决策框架 + +**Main Agent 在安排 Sub Agents 之前，必须先进行工程审慎判断**： + +| 问题 | 判断标准 | 决策 | +|------|---------|------| +| **1. 这是现实问题还是想象问题？** | 有明确证据/用户反馈 vs "可能需要"/"也许将来" | 拒绝过度设计 | +| **2. 这个问题真的需要解决吗？** | 影响核心功能/用户体验 vs 边缘场景/伪需求 | 拒绝伪需求 | +| **3. 这个方案真的能解决问题吗？** | 有明确验证路径 vs 理论上可行 | 拒绝自嗨 | + +**如何应用**： +- 用户提出模糊需求时，使用 Linus 三问过滤 +- 规划复杂功能前，先验证问题真实性 +- 选择技术方案时，评估是否能真正解决问题 + +**决策流程**： + +``` +用户提出需求 + ↓ +Linus 三问过滤 + ↓ +是否通过？ + ├─ 否 → 拒绝/澄清需求 + └─ 是 → 继续技术决策 + ↓ + 需求是否清晰？ + ├─ 否 → deep-interview + └─ 是 → 决定 Sub Agents + ↓ + 执行编排 +``` + +### 4.3 编排模式 + +#### 并行编排 + +```javascript +// Main Agent 可以并行安排多个 Sub Agents +const [backend, frontend] = await Promise.all([ + agent({ prompt: "后端: 实现 API" }), + agent({ prompt: "前端: 实现页面" }) +]) +``` + +#### 串行编排 + +```javascript +// Main Agent 可以串行安排 Sub Agents +const execute = await agent({ prompt: "实现功能" }) +const review = await agent({ prompt: `审查: ${execute.files}` }) +const test = await agent({ prompt: `测试: ${execute.features}` }) +``` + +#### 条件编排 + +```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) +} +``` + +### 4.4 上下文隔离 + +**隔离原则**: + +``` +Main Agent + │ + ├─ 安排 Execute Sub Agent + │ └─ 只传递任务描述 + │ + ├─ 安排 Review Sub Agent + │ └─ 只传递需要审查的代码 + │ + └─ 安排 Test Sub Agent + └─ 只传递需要测试的功能 +``` + +**每个 Sub Agent 只能看到必要信息** + +| Sub Agent | 可以看到 | 不能看到 | +|-----------|---------|---------| +| **Execute** | 任务描述、项目代码 | 其他 Sub Agents 的工作 | +| **Review** | 需要审查的代码 | 实现过程、其他 Sub Agents | +| **Test** | 需要测试的功能 | 实现细节、审查过程 | + +**为什么隔离**： + +- **Execute 不受 Review 影响**: 专注实现 +- **Review 不受 Execute 过程影响**: 客观评估 +- **Test 不受实现细节影响**: 独立验证 + +--- + +## 5. Superpowers 集成 + +### 5.1 Superpowers 五技能体系 + +videotext 方案定义了标准的软件开发生命周期五技能： + +| 阶段 | Superpowers 技能 | 用途 | v0.5 对应实践 | +|------|------------------|------|---------------| +| **1. 规划** | `writing-plans` | 编写综合实现计划，假设工程师对代码库零上下文 | `planning` skill | +| **2. 执行** | `executing-plans` | 按步骤执行计划文件，有审查检查点 | Agent 工具编排 | +| **3. 审查** | `requesting-code-review` | 请求代码审查，突出需要关注的区域 | `CODE-REVIEW` skill | +| **4. 调试** | `systematic-debugging` | 系统化调试问题，而不是随机尝试 | `debugger` skill | +| **5. 完成** | `finishing-a-development-branch` | 完成开发分支的收尾（测试、文档、清理） | Main Agent 验收整合 | + +**工作流程**： +``` +writing-plans → executing-plans → requesting-code-review → systematic-debugging → finishing-a-development-branch + ↓ ↓ ↓ ↓ ↓ + 编写计划 执行计划 请求审查 系统调试 完成收尾 +``` + +### 5.2 Main Agent 使用 Superpowers + +#### 规划阶段 (writing-plans) + +```javascript +// 复杂任务，先规划 +Skill({ + skill: "writing-plans", + args: "用户认证系统实现计划" +}) +// 输出计划文件，假设执行者对代码库零上下文 +``` + +#### 需求讨论 (deep-interview) + +```javascript +// 需求讨论 - 使用 deep-interview (补充能力) +Skill({ + skill: "deep-interview", + args: "用户认证系统需求" +}) +// 记录到 requirements/requirements.md +// ASK -> LISTEN -> WRITE -> DEEPEN -> REPEAT +``` + +#### 执行阶段 (executing-plans) + +```javascript +// 通过 Agent 工具编排 Sub Agents +const backend = await Agent({ + subagent_type: "claude", + prompt: "作为后端开发专家，执行计划中的后端任务..." +}) + +const frontend = await Agent({ + subagent_type: "claude", + prompt: "作为前端开发专家，执行计划中的前端任务..." +}) +``` + +#### 审查阶段 (requesting-code-review) + +```javascript +// 使用 CODE-REVIEW skill 进行代码审查 +Skill({ + skill: "code-review", + args: "审查用户认证代码" +}) +// 检查逻辑正确性、安全、性能、测试覆盖率 +``` + +#### 调试阶段 (systematic-debugging) + +```javascript +// 遇到问题时，使用 systematic-debugging +Skill({ + skill: "systematic-debugging", + args: "登录接口问题诊断" +}) +// 系统化定位问题，而非随机尝试 +``` + +#### 完成阶段 (finishing-a-development-branch) + +```javascript +// Main Agent 验收整合 +// - 检查所有测试通过 +// - 确认代码质量 +// - 准备提交 Git +``` + +### 5.3 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. 返回结果 +``` + +### 5.4 所有 Agent 共享 + +``` +Main Agent + │ + ├─ writing-plans — 编写实现计划 + ├─ executing-plans — 执行计划 (Agent 工具编排) + ├─ requesting-code-review — 请求代码审查 (CODE-REVIEW) + ├─ systematic-debugging — 系统化调试 (debugger) + ├─ finishing-a-development-branch — 完成收尾 + ├─ deep-interview — 需求讨论和知识提取 (补充) + └─ Agent 工具编排 + +Sub Agents + │ + ├─ backend-dev skill + ├─ frontend-dev skill + ├─ CODE-REVIEW skill + ├─ test-engineer skill + ├─ debugger skill + ├─ ... (其他 Superpowers) + └─ Agent 工具 (可启动更深层 Agent) + +Superpowers Skills 核心五技能 + │ + ├─ writing-plans — 编写计划 ⭐ + ├─ executing-plans — 执行计划 ⭐ + ├─ requesting-code-review — 请求代码审查 ⭐ + ├─ systematic-debugging — 系统化调试 ⭐ + ├─ finishing-a-development-branch — 完成收尾 ⭐ + ├─ deep-interview — 需求讨论 (补充) + ├─ backend-dev — 后端开发 + ├─ frontend-dev — 前端开发 + ├─ ... (100+ skills) +``` + +--- + +## 6. 工作流示例 + +### 6.1 简单任务：修复 Bug + +``` +┌─────────────────────────────────────────────────────────────┐ +│ 用户: "登录接口报错" │ +└─────────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────────┐ +│ 0. Main Agent: 快速确认需求 (AskUserQuestion) │ +│ │ +│ 使用 AskUserQuestion 提问: │ +│ • 具体的错误信息是什么? │ +│ • 在什么情况下发生? (操作步骤/环境) │ +│ • 有错误日志吗? │ +│ │ +│ 快速确认问题范围 │ +└─────────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────────┐ +│ Main Agent 分析决策 │ +│ │ +│ 这是一个简单任务，不需要规划和深度访谈: │ +│ 1. 安排 debugger Sub Agent 定位问题 │ +│ 2. 安排 Execute Sub Agent 修复 │ +│ 3. 安排 Test Sub Agent 验证 │ +│ 4. 验收整合 (CODE-REVIEW) │ +└─────────────────────────────────────────────────────────────┘ + ↓ +Main Agent 直接安排 Sub Agents... +``` + +### 6.2 中等任务：实现登录功能 + +``` +┌─────────────────────────────────────────────────────────────┐ +│ 用户: "实现用户登录功能" │ +└─────────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────────┐ +│ 0. Main Agent: 需求讨论 (deep-interview) │ +│ │ +│ 使用 AskUserQuestion 提问: │ +│ • 需要支持哪些认证方式? (JWT/OAuth/Session) │ +│ • 需要哪些端点? (登录/注册/刷新/登出) │ +│ • 有什么安全要求? (加密/2FA/限流) │ +│ • 前端需要什么功能? (表单/状态管理) │ +│ │ +│ 记录答案到 requirements/requirements.md │ +└─────────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────────┐ +│ Main Agent 分析决策 │ +│ │ +│ 这是一个中等任务，需要: │ +│ 1. 安排 Execute Sub Agent 实现 │ +│ 2. 安排 Review Sub Agent 审查 │ +│ 3. 验收整合 (CODE-REVIEW) │ +└─────────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────────┐ +│ 1. Main Agent: 安排 Execute Sub Agent │ +│ │ +│ Agent({ │ +│ subagent_type: "claude", │ +│ prompt: ` │ +│ 作为全栈开发专家，实现用户登录功能: │ +│ │ +│ 后端: /auth/login, /auth/register │ +│ 前端: 登录页面、注册页面 │ +│ 技术: JWT 认证, shadcn/ui 组件 │ +│ ` │ +│ }) │ +└─────────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────────┐ +│ 2. Main Agent: 安排 Review Sub Agent │ +│ │ +│ Agent({ │ +│ subagent_type: "claude", │ +│ prompt: ` │ +│ 作为代码审查专家，审查以下文件: │ +│ │ +│ ${executeResult.files} │ +│ │ +│ 检查: │ +│ - 代码质量 │ +│ - 安全性 (JWT、密码处理) │ +│ ` │ +│ }) │ +└─────────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────────┐ +│ 3. Main Agent: 验收整合 (CODE-REVIEW) │ +│ │ +│ 使用 CODE-REVIEW skill 进行验收: │ +│ • 检查逻辑正确性 │ +│ • 安全漏洞检查 │ +│ • 测试覆盖率 │ +│ │ +│ 整合并提交 Git │ +└─────────────────────────────────────────────────────────────┘ +``` + +### 6.3 复杂任务：实现用户认证系统 + +``` +┌─────────────────────────────────────────────────────────────┐ +│ 用户: "实现用户认证系统" │ +└─────────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────────┐ +│ 0. Main Agent: 需求讨论 (deep-interview) │ +│ │ +│ 使用 AskUserQuestion 提问: │ +│ • 需要支持哪些认证方式? (JWT/OAuth/Session) │ +│ • 需要哪些端点? (登录/注册/刷新/登出) │ +│ • 有什么安全要求? (加密/2FA/限流) │ +│ • 前端需要什么功能? (表单/状态管理) │ +│ │ +│ 记录答案到 requirements/requirements.md │ +└─────────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────────┐ +│ Main Agent 分析决策 │ +│ │ +│ 这是一个复杂任务，需要: │ +│ 1. 先用 writing-plans skill 规划 │ +│ 2. 安排 Execute Sub Agents 实现 │ +│ 3. 安排 Review Sub Agent 审查 │ +│ 4. 安排 Test Sub Agent 测试 │ +│ 5. 验收整合 (CODE-REVIEW) │ +└─────────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────────┐ +│ 1. Main Agent: writing-plans skill │ +│ │ +│ Skill({ skill: "writing-plans", args: "用户认证系统" }) │ +│ │ +│ 分析需求: │ +│ - 用户认证: 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 Agents │ +│ │ +│ 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: 验收整合 (CODE-REVIEW) │ +│ │ +│ 使用 CODE-REVIEW skill 进行验收: │ +│ • 检查逻辑正确性和边界情况 │ +│ • 安全漏洞检查 (JWT、密码处理) │ +│ • 性能影响评估 │ +│ • 测试覆盖率和质量 │ +│ • 错误处理验证 │ +│ │ +│ 收集结果: │ +│ • Execute 结果: 后端 API + 前端页面 │ +│ • Review 结果: 代码通过审查 │ +│ • Test 结果: 测试全部通过 │ +│ • CODE-REVIEW 结果: 验收通过 │ +│ │ +│ 整合并提交 Git │ +└─────────────────────────────────────────────────────────────┘ +``` + +--- + +## 7. 实施指南 + +### 7.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]" + } +} +``` + +### 7.2 创建项目结构 + +```bash +cd ~/.openclaw/sanguo_projects/sanguo_moziplus_v3 + +# 创建配置 +mkdir -p .claude/workflows +``` + +### 7.3 创建 Main Agent 配置 + +创建 `.claude/CLAUDE.md`: + +```markdown +# sanguo_moziplus_v3 - Main Agent (编排者) + +## 角色 + +你是任务编排者，负责与用户讨论需求、动态安排 Sub Agents、验收整合。 + +## 核心职责 + +1. **与用户讨论需求** — 使用 `deep-interview` skill +2. 分析任务需求 — 确定任务复杂度和范围 +3. 根据需要决定安排哪些 Sub Agents +4. 协调 Sub Agents 之间的协作 +5. **验收整合** — 使用 `CODE-REVIEW` skill +6. 向用户汇报最终结果 + +## 需求讨论 (deep-interview) + +**何时使用**: +- 用户输入模糊 (如 "实现一个功能"、"添加一个功能") +- 任务较复杂 (超过 20 字) +- 需要了解更多上下文 + +**如何使用**: +- 需求讨论使用 `Skill({ skill: "deep-interview", args: "任务主题" })` +- deep-interview 会: + 1. 使用 AskUserQuestion 逐步提问 + 2. 每次最多 2-3 个问题 + 3. 立即记录答案到文件 + 4. 根据答案深入追问 + +**核心循环**: `ASK -> LISTEN -> WRITE -> DEEPEN -> REPEAT` + +## 验收整合 (CODE-REVIEW) + +**何时使用**: +- Sub Agent 完成代码实现后 +- 需要向用户汇报前 +- 提交 Git 前 + +**如何使用**: +- 代码审查验收使用 `Skill({ skill: "code-review", args: "文件路径" })` +- CODE-REVIEW 会检查: + • 逻辑正确性和边界情况 + • 安全漏洞 + • 性能影响 + • 测试覆盖率 + • 错误处理 + +## 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: 质量保证测试 + +## 工作方式 + +**不是固化流程，根据任务需要灵活安排** + +### 简单任务 +``` +接收任务 → 快速确认 (AskUserQuestion) → 安排 Execute → 验收整合 → 汇报 +``` + +### 中等任务 +``` +接收任务 → 需求讨论 (deep-interview) → 安排 Execute → 安排 Review → 验收整合 → 汇报 +``` + +### 复杂任务 +``` +接收任务 → 需求讨论 (deep-interview) → planning → 安排 Execute → 安排 Review → 安排 Test → 验收整合 → 汇报 +``` + +### 调试任务 +``` +接收任务 → 询问详情 (AskUserQuestion) → 安排 debugger → 安排 Execute → 安排 Test → 验收整合 → 汇报 +``` + +## 严格限制 + +- 不亲自编写代码 +- 不亲自执行具体实现 + +## 可用能力 (Superpowers) + +### Superpowers 五技能体系 (核心工作流) + +- **writing-plans** — 编写综合实现计划，假设工程师对代码库零上下文 +- **executing-plans** — 按步骤执行计划文件，有审查检查点 (通过 Agent 工具实现) +- **requesting-code-review** — 请求代码审查，突出需要关注的区域 (CODE-REVIEW) +- **systematic-debugging** — 系统化调试问题，而非随机尝试 (debugger) +- **finishing-a-development-branch** — 完成开发分支收尾 (测试、文档、清理) + +### 补充能力 + +- **deep-interview** — 需求讨论和知识提取 (ASK→LISTEN→WRITE→DEEPEN→REPEAT) +- **backend-dev** — 后端开发专业能力 +- **frontend-dev** — 前端开发专业能力 +- **test-engineer** — 测试工程 +- 其他 100+ Superpowers skills +- Agent 工具编排 + +## 决策框架 + +### Linus 三问 (工程审慎决策) + +**Main Agent 在安排 Sub Agents 之前，必须先进行工程审慎判断**： + +| 问题 | 判断标准 | 决策 | +|------|---------|------| +| **1. 这是现实问题还是想象问题？** | 有明确证据/用户反馈 vs "可能需要"/"也许将来" | 拒绝过度设计 | +| **2. 这个问题真的需要解决吗？** | 影响核心功能/用户体验 vs 边缘场景/伪需求 | 拒绝伪需求 | +| **3. 这个方案真的能解决问题吗？** | 有明确验证路径 vs 理论上可行 | 拒绝自嗨 | + +**如何应用**： +- 用户提出模糊需求时，使用 Linus 三问过滤 +- 规划复杂功能前，先验证问题真实性 +- 选择技术方案时，评估是否能真正解决问题 + +### 技术编排决策 + +通过 Linus 三问后，再进行技术决策： + +1. 需求是否清晰? 不清晰 → 使用 deep-interview +2. 这个任务需要哪些 Sub Agents? +3. 需要 planning 吗? +4. Sub Agents 之间有依赖关系吗? +5. 可以并行执行吗? + +## 验收框架 + +在向用户汇报之前: +1. 使用 CODE-REVIEW 验证代码质量 +2. 确认所有测试通过 +3. 整合所有结果 +4. 准备清晰的汇报 +``` + +### 7.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 Skill({ + skill: "writing-plans", + args: `分析: ${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" } + } +} +``` + +### 7.5 验证测试 + +```javascript +// 测试简单任务 +Workflow({ + scriptPath: ".claude/workflows/dynamic-orchestration.js", + args: "修复登录页面样式" +}) + +// 测试复杂任务 +Workflow({ + scriptPath: ".claude/workflows/dynamic-orchestration.js", + args: "实现用户认证系统" +}) +``` + +--- + +## 8. 对比分析 + +### 8.1 v0.4 vs v0.5 + +| 方面 | v0.4 (三实例) | v0.5 (Main + Sub) | +|------|--------------|-------------------| +| **Main 角色** | 架构师 (Plan + Review) | **编排者 + 验收整合** | +| **Sub Agent 角色** | backend/frontend 执行 | **Execute/Review/Test 专业角色** | +| **工作流** | 固化流程 | **Main 根据需求动态安排** ✅ | +| **编排方式** | SendMessage 跨实例 | **Agent 工具** ✅ | +| **灵活性** | 固定三个实例 | **动态 Sub Agents** ✅ | +| **需求讨论** | 无明确机制 | **deep-interview skill** ✅ | +| **验收机制** | Review Agent | **CODE-REVIEW skill** ✅ | + +### 8.2 优势总结 + +**v0.5 的三个核心变化**: +1. **需求讨论** — Main Agent 使用 `deep-interview` skill 与用户讨论需求 +2. **验收整合** — Main Agent 使用 `CODE-REVIEW` skill 进行代码审查验收 +3. **动态编排** — Main Agent 根据任务需要灵活安排 Sub Agents + +**技术优势**: +- 更灵活的协作模式 +- 更细的专业分工 +- 更清晰的职责边界 +- 更好的上下文隔离 +- 标准化的 Superpowers 工作流 + +--- + +## 附录 A：版本变更说明 + +### v0.5.1 (2026-07-01) + +**补充内容**： + +1. **Linus 三问 (工程审慎决策框架)** + - 添加到决策框架部分 + - 在安排 Sub Agents 之前必须先进行工程审慎判断 + - 防止过度设计、伪需求、自嗨方案 + +2. **Superpowers 五技能体系** + - 对齐 videotext 方案的标准工作流 + - 明确五个核心技能：writing-plans → executing-plans → requesting-code-review → systematic-debugging → finishing-a-development-branch + - 保持 v0.5 灵活性的同时，遵循 Superpowers 标准实践 + +3. **能力对照更新** + - 更新 Main Agent 核心能力表 + - 添加 Superpowers 五技能工作流图 + - 明确 v0.5 实践与 Superpowers 标准的映射关系 + +### v0.5 (2026-07-01) + +**核心变化**： + +- 从 SendMessage 跨实例编排改为 Agent 工具动态编排 +- Main Agent 承担需求讨论职责 +- Main Agent 承担验收整合职责 +- Sub Agents 细分为 Execute/Review/Test 专业角色 +- 工作流从固化流程改为动态安排 + +--- + +**文档版本**: v0.5.1 (整合版) +**原始文档**: 06-design-v0.5-dynamic-orchestration.md +**整合日期**: 2026-07-01 +**作者**: Claude Dev +**审核状态**: Draft +**实施状态**: 设计阶段