sanguo_moziplus_v3/docs/design/07-design-v0.5-dynamic-orchestration-integrated.md

sanguo_moziplus_v3 设计文档 v0.5

项目名称: sanguo_moziplus_v3
版本: v0.5
状态: Draft
创建日期: 2026-07-01

---

摘要

sanguo_moziplus_v3 是一个基于 Claude Code 的多 Agent 协作系统。系统采用 Main Agent 编排 + Sub Agents 执行 的架构，通过动态编排实现灵活的任务协作。

核心特性：

• Main Agent 作为编排者，根据任务需要动态安排 Sub Agents
• 集成标准化工作流（规划、执行、审查、调试、完成）
• 通过工程审慎决策框架（Linus 三问）过滤需求和方案
• 上下文隔离确保各 Agent 专注执行

---

目录

1. 系统架构
2. 角色定义
3. 编排机制
4. 工作流程
5. 实施指南
6. 附录

---

1. 系统架构

1.1 架构概览

┌─────────────────────────────────────────────────────────────────┐
│                    Main Agent (编排者)                          │
│                                                                 │
│  职责:                                                          │
│  • 接收用户需求                                                │
│  • 工程审慎决策 (Linus 三问)                                   │
│  • 需求讨论与澄清                                              │
│  • 分析任务复杂度                                              │
│  • 动态安排 Sub Agents                                         │
│  • 验收整合结果                                                │
│                                                                 │
│  核心能力:                                                      │
│  • 需求讨论 (deep-interview)                                   │
│  • 方案规划 (writing-plans)                                    │
│  • 代码审查 (requesting-code-review)                           │
│  • 问题诊断 (systematic-debugging)                             │
│  • Agent 编排工具                                              │
└─────────────────────────────────────────────────────────────────┘
                    │
                    │ Agent 工具动态编排
                    │
         ┌──────────┼──────────┐
         │          │          │
         ▼          ▼          ▼
┌──────────────────┐ ┌──────────┐ ┌──────────┐
│ Sub Agent:       │ │Sub Agent:│ │Sub Agent:│
│ Execute          │ │Review    │ │Test      │
│                  │ │          │ │          │
│ 专业角色:        │ │专业角色: │ │专业角色: │
│ • backend-dev    │ • 代码质量 │ • 单元测试 │
│ • frontend-dev   │ • 安全性   │ • E2E测试  │
│ • database-dev   │ • 性能     │ • QA测试   │
│ • infrastructure │            │            │
└──────────────────┘ └──────────┘ └──────────┘

所有 Agent 都能访问标准化工作流能力

1.2 核心设计原则

原则	说明
动态编排	Main Agent 根据任务需要决定安排哪些 Sub Agents，不使用固化流程
专业分工	Sub Agents 有明确的专业角色（Execute/Review/Test）
上下文隔离	每个 Sub Agent 只能看到完成工作所需的最小信息
验证整合	Main Agent 负责最终验收和结果整合
标准化工作流	所有 Agent 遵循相同的五阶段工作流

1.3 标准化工作流

系统遵循五阶段工作流（源自 Superpowers 标准实践）：

┌──────────────┐   ┌──────────────┐   ┌───────────────┐   ┌──────────────┐   ┌──────────────┐
│ 1. 规划      │ → │ 2. 执行      │ → │ 3. 审查       │ → │ 4. 调试      │ → │ 5. 完成      │
│ writing-plans │   │ executing   │   │ requesting    │   │ systematic   │   │ finishing   │
│              │   │ -plans      │   │ -code-review  │   │ -debugging   │   │ -development │
│              │   │             │   │               │   │              │   │ -branch     │
└──────────────┘   └──────────────┘   └───────────────┘   └──────────────┘   └──────────────┘
     编写计划            执行计划            请求审查            系统调试            完成收尾

---

2. 角色定义

2.1 Main Agent (编排者)

职责范围：

领域	职责	工具/方法
需求管理	接收、澄清、确认需求	deep-interview skill
工程决策	Linus 三问审慎判断	决策框架
任务分析	评估复杂度、确定所需 Sub Agents	分析逻辑
编排执行	安排 Sub Agents、协调协作	Agent 工具
验收整合	验证结果、一致性检查、整合输出	requesting-code-review skill + 一致性检查

工作方式：

1. 接收用户需求
2. Linus 三问过滤（是否现实问题、是否需要解决、方案是否可行）
3. 需求澄清（如需要，使用 deep-interview）
4. 分析任务复杂度
5. 决定编排策略（简单/中等/复杂）
6. 执行编排
7. 验收整合
8. 向用户汇报

严格限制：

• 不亲自编写代码
• 不亲自执行具体实现

2.2 Sub Agent: Execute (执行者)

专业角色：

• backend-dev: 后端开发（API、数据库、业务逻辑）
• frontend-dev: 前端开发（UI/UX、交互、状态管理）
• database-dev: 数据库开发（Schema、迁移、优化）
• infrastructure: 基础设施（部署、监控、配置）

上下文：接收任务描述和项目代码访问权限

2.3 Sub Agent: Review (审查者)

专业角色：

• 代码质量审查：代码规范、可维护性、设计模式
• 安全审查：安全漏洞、权限控制、数据保护
• 性能审查：性能瓶颈、资源使用、优化建议

上下文：接收需要审查的代码和审查标准

2.4 Sub Agent: Test (测试者)

专业角色：

• 单元测试：代码级测试、覆盖率、边界情况
• E2E 测试：端到端场景、用户流程、集成测试
• QA 测试：质量保证、测试计划、验收标准

上下文：接收需要测试的功能和测试要求

---

3. 编排机制

3.1 编排策略

Main Agent 根据任务复杂度采用不同的编排策略：

复杂度	特征	编排策略
简单	明确的 bug 修复、小改动	Execute → 验收
中等	单一功能实现	需求讨论 → Execute → Review → 验收
复杂	多功能、跨领域	需求讨论 → 规划 → Execute → Review → Test → 验收
调试	问题定位和修复	定位 → Execute → Test → 验收

3.2 工程审慎决策（Linus 三问）

Main Agent 在编排前必须通过三问过滤：

问题	判断标准	拒绝条件
1. 这是现实问题还是想象问题？	有明确证据或用户反馈	"可能需要"、"也许将来"
2. 这个问题真的需要解决吗？	影响核心功能或用户体验	边缘场景、伪需求
3. 这个方案真的能解决问题吗？	有明确验证路径	理论上可行但无验证

决策流程：

用户需求
    ↓
Linus 三问
    ↓
┌─────────────┐
│  通过？     │
└──────┬──────┘
       ├─ 否 → 拒绝/澄清
       └─ 是 → 继续编排
            ↓
       需求清晰？
            ├─ 否 → deep-interview
            └─ 是 → 执行编排

3.3 需求讨论机制

当需求不清晰时，Main Agent 使用 deep-interview 方法：

ASK → LISTEN → WRITE → DEEPEN → REPEAT

• ASK: 每次提问不超过 2-3 个问题
• LISTEN: 认真听取用户回答
• WRITE: 立即记录到 requirements/ 目录
• DEEPEN: 根据答案深入追问
• REPEAT: 直到需求清晰为止

3.4 上下文隔离

隔离原则：

Main Agent
    │
    ├─ Execute Sub Agent
    │   └─ 只看到: 任务描述 + 项目代码
    │
    ├─ Review Sub Agent
    │   └─ 只看到: 需要审查的代码
    │
    └─ Test Sub Agent
        └─ 只看到: 需要测试的功能

为什么隔离：

• Execute 不受 Review 影响，专注实现
• Review 不受实现过程影响，客观评估
• Test 不受实现细节影响，独立验证

3.5 编排模式

并行编排

// 独立任务可并行执行
const [backend, frontend] = await Promise.all([
  agent({ prompt: "后端: 实现 API" }),
  agent({ prompt: "前端: 实现页面" })
])

串行编排

// 有依赖关系需串行执行
const execute = await agent({ prompt: "实现功能" })
const review = await agent({ prompt: `审查: ${execute.files}` })

条件编排

// 根据中间结果决定下一步
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}` })
  return await integrate(fix, await agent({ prompt: `重新审查: ${fix.files}` }))
}

3.6 验收机制：需求-设计-编码一致性检查

Main Agent 在验收时必须执行三向一致性检查：

┌─────────────────────────────────────────────────────────────┐
│              验收：三向一致性检查                          │
│                                                             │
│  ┌─────────┐    ┌─────────┐    ┌─────────┐              │
│  │  需求   │ ←→ │  设计   │ ←→ │  编码   │              │
│  └─────────┘    └─────────┘    └─────────┘              │
│       ↑              ↑              ↑                      │
│       └──────────────┴──────────────┘                      │
│                    一致性检查                              │
└─────────────────────────────────────────────────────────────┘

检查方法：

对照三向检查，逐项验证：

• 需求 → 设计：设计是否完整覆盖需求？
• 设计 → 编码：编码是否正确实现设计？
• 需求 → 编码：实现是否满足原始需求？

偏差处理：

发现偏差时，重新进入 Superpowers 五阶段工作流：

验收发现偏差
    ↓
┌─────────────────────────────────┐
│  重新进入 Superpowers 工作流     │
│                                 │
│  1. 规划 (writing-plans)       │ ← 需求/设计偏差
│  2. 执行 (executing-plans)     │ ← 编码偏差
│  3. 审查 (requesting-code-review) │
│  4. 调试 (systematic-debugging) │
│  5. 完成 (finishing-development) │
│                                 │
│  → 重新验收                     │
└─────────────────────────────────┘

一致性检查时机：

• 复杂任务：每次 Sub Agent 完成后检查
• 中等任务：Review 阶段检查
• 简单任务：最终验收时检查

---

4. 工作流程

4.1 标准工作流（五阶段）

阶段 1：规划 (writing-plans)

何时使用：复杂任务（涉及多个领域或需要架构决策）

输出：一份假设执行者对代码库零上下文的实现计划

内容包括：

• 任务背景和目标
• 技术方案选择
• 实施步骤
• 验收标准

阶段 2：执行 (executing-plans)

方式：通过 Agent 工具编排 Sub Agents

执行模式：

• 并行执行独立任务
• 串行执行有依赖的任务
• 根据审查结果调整执行

阶段 3：审查 (requesting-code-review)

何时使用：代码实现完成后、向用户汇报前

检查维度：

• 逻辑正确性和边界情况
• 安全漏洞
• 性能影响
• 测试覆盖率
• 错误处理

阶段 4：调试 (systematic-debugging)

何时使用：遇到问题或错误时

方法：

• 系统化定位问题（而非随机尝试）
• 分析根本原因
• 设计验证方案

阶段 5：完成 (finishing-a-development-branch)

内容：

• 确认所有测试通过
• 验证代码质量
• 准备提交
• 清理临时文件

4.2 任务类型示例

简单任务：修复 Bug

用户: "登录接口报错"
    ↓
Main Agent: 快速确认错误信息
    ↓
安排 debugger Sub Agent 定位问题
    ↓
安排 Execute Sub Agent 修复
    ↓
安排 Test Sub Agent 验证
    ↓
验收整合

中等任务：实现登录功能

用户: "实现用户登录功能"
    ↓
Main Agent: deep-interview 需求讨论
    ↓
记录需求到 requirements/requirements.md
    ↓
安排 Execute Sub Agent 实现
    ↓
安排 Review Sub Agent 审查
    ↓
验收整合

复杂任务：实现用户认证系统

用户: "实现用户认证系统"
    ↓
Main Agent: deep-interview 深度需求讨论
    ↓
使用 writing-plans 规划
    ↓
并行安排 Execute Sub Agents（后端 + 前端）
    ↓
安排 Review Sub Agents（代码 + 安全）
    ↓
安排 Test Sub Agent 验证
    ↓
验收整合

---

5. 实施指南

5.1 环境配置

项目结构：

sanguo_moziplus_v3/
├── .claude/
│   ├── CLAUDE.md          # Main Agent 配置
│   └── workflows/
│       └── dynamic-orchestration.js  # 编排脚本
├── requirements/          # 需求文档
└── docs/design/          # 设计文档

Main Agent 配置 (.claude/CLAUDE.md)：

# Main Agent 配置

## 角色
你是任务编排者，负责与用户讨论需求、动态安排 Sub Agents、验收整合。

## 核心职责
1. 需求讨论 - 使用 deep-interview skill
2. 工程决策 - Linus 三问过滤
3. 任务分析 - 评估复杂度
4. 编排执行 - 动态安排 Sub Agents
5. 验收整合 - 验证并整合结果

## 严格限制
- 不亲自编写代码
- 不亲自执行具体实现

## 可用能力
- deep-interview - 需求讨论
- writing-plans - 方案规划
- requesting-code-review - 代码审查
- systematic-debugging - 问题诊断
- Agent 工具 - 编排 Sub Agents

5.2 编排脚本示例

export const meta = {
  name: 'dynamic-orchestration',
  description: 'Main Agent 根据任务需要动态编排 Sub Agents',
  phases: [
    { title: '分析', detail: '分析任务需求' },
    { title: '编排', detail: '决定 Sub Agents' },
    { title: '执行', detail: 'Sub Agents 执行' },
    { title: '验收', detail: '验收整合' }
  ]
}

export default async function (task) {
  // 1. 分析任务
  const analysis = await analyzeTask(task)
  
  // 2. 根据复杂度编排
  if (analysis.complexity === 'high') {
    // 复杂任务：规划 → 执行 → 审查 → 测试
    const plan = await Skill({ skill: 'writing-plans', args: task })
    const execute = await executeAgents(plan)
    const review = await reviewAgents(execute)
    const test = await testAgents(execute)
    return await integrate(plan, execute, review, test)
  }
  
  if (analysis.complexity === 'medium') {
    // 中等任务：执行 → 审查
    const execute = await executeAgents(task)
    const review = await reviewAgents(execute)
    return await integrate(execute, review)
  }
  
  // 简单任务：直接执行
  const execute = await executeAgents(task)
  return await integrate(execute)
}

5.3 配置 Gitea 协作

见 docs/gitea-collaboration-guide.md

---

6. 附录

6.1 术语表

术语	说明
Main Agent	编排者，负责任务编排和结果整合
Sub Agent	执行者，负责具体实现、审查、测试
deep-interview	需求讨论方法，ASK→LISTEN→WRITE→DEEPEN→REPEAT
Linus 三问	工程审慎决策框架
标准化工作流	五阶段：规划→执行→审查→调试→完成

6.2 版本历史

版本	日期	变更
v0.5	2026-07-01	Main Agent + Sub Agents 动态编排
v0.5.1	2026-07-01	补充 Linus 三问 + 标准化工作流

6.3 参考资料

• Superpowers 标准工作流规范
• Claude Code Agent 工具文档
• Linus Torvalds: "Talk Like a Kernel Developer"

---

文档版本: v0.5
最后更新: 2026-07-01
维护者: Claude Dev