Files

T

claude_dev 9c6eaa2ebd docs: 添加 v0.5 动态编排设计文档整合版

- 整合 06 文档，消除重复内容
- 重组结构：概述→设计精髓→角色→编排→Superpowers→工作流→实施→对比
- 清理历史调研痕迹
- 添加清晰的设计叙述主线

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

2026-07-01 19:32:31 +08:00

48 KiB

Raw Blame History

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 关键特性

需求讨论: Main Agent 使用 deep-interview skill 与用户讨论需求，确保理解正确
动态编排: Main 根据任务需要决定安排哪些 Sub Agents
专业分工: Sub Agents 有明确的专业角色
上下文隔离: 每个 Sub Agent 只能看到必要信息
共享能力: 所有 Agent 都遵循 Superpowers 工作方式
灵活调整: 不是固化流程，Main 可以根据情况调整
验证整合: 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 决策逻辑

// 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 编排模式

并行编排

// Main Agent 可以并行安排多个 Sub Agents
const [backend, frontend] = await Promise.all([
  agent({ prompt: "后端: 实现 API" }),
  agent({ prompt: "前端: 实现页面" })
])

串行编排

// Main Agent 可以串行安排 Sub Agents
const execute = await agent({ prompt: "实现功能" })
const review = await agent({ prompt: `审查: ${execute.files}` })
const test = await agent({ prompt: `测试: ${execute.features}` })

条件编排

// 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)

// 复杂任务，先规划
Skill({
  skill: "writing-plans",
  args: "用户认证系统实现计划"
})
// 输出计划文件，假设执行者对代码库零上下文

需求讨论 (deep-interview)

// 需求讨论 - 使用 deep-interview (补充能力)
Skill({
  skill: "deep-interview",
  args: "用户认证系统需求"
})
// 记录到 requirements/requirements.md
// ASK -> LISTEN -> WRITE -> DEEPEN -> REPEAT

执行阶段 (executing-plans)

// 通过 Agent 工具编排 Sub Agents
const backend = await Agent({
  subagent_type: "claude",
  prompt: "作为后端开发专家，执行计划中的后端任务..."
})

const frontend = await Agent({
  subagent_type: "claude",
  prompt: "作为前端开发专家，执行计划中的前端任务..."
})

审查阶段 (requesting-code-review)

// 使用 CODE-REVIEW skill 进行代码审查
Skill({
  skill: "code-review",
  args: "审查用户认证代码"
})
// 检查逻辑正确性、安全、性能、测试覆盖率

调试阶段 (systematic-debugging)

// 遇到问题时，使用 systematic-debugging
Skill({
  skill: "systematic-debugging",
  args: "登录接口问题诊断"
})
// 系统化定位问题，而非随机尝试

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

// Main Agent 验收整合
// - 检查所有测试通过
// - 确认代码质量
// - 准备提交 Git

5.3 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. 返回结果

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

// ~/.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 创建项目结构

cd ~/.openclaw/sanguo_projects/sanguo_moziplus_v3

# 创建配置
mkdir -p .claude/workflows

7.3 创建 Main Agent 配置

创建 .claude/CLAUDE.md:

# 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:

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 验证测试

// 测试简单任务
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 的三个核心变化:

需求讨论 — Main Agent 使用 deep-interview skill 与用户讨论需求
验收整合 — Main Agent 使用 CODE-REVIEW skill 进行代码审查验收
动态编排 — Main Agent 根据任务需要灵活安排 Sub Agents

技术优势:

更灵活的协作模式
更细的专业分工
更清晰的职责边界
更好的上下文隔离
标准化的 Superpowers 工作流

附录 A：版本变更说明

v0.5.1 (2026-07-01)

补充内容：

Linus 三问 (工程审慎决策框架)
- 添加到决策框架部分
- 在安排 Sub Agents 之前必须先进行工程审慎判断
- 防止过度设计、伪需求、自嗨方案
Superpowers 五技能体系
- 对齐 videotext 方案的标准工作流
- 明确五个核心技能：writing-plans → executing-plans → requesting-code-review → systematic-debugging → finishing-a-development-branch
- 保持 v0.5 灵活性的同时，遵循 Superpowers 标准实践
能力对照更新
- 更新 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 实施状态: 设计阶段

48 KiB Raw Blame History Unescape Escape

sanguo_moziplus_v3 设计文档 v0.5 (整合版)

1. 概述

1.1 项目简介

1.2 版本变更

1.3 核心变化

2. 设计精髓

2.1 核心理念

2.2 动态编排示例

简单任务

中等任务

复杂任务

调试任务

2.3 关键特性

3. 角色与职责

3.1 Main Agent (编排者)

3.2 Sub Agent: Execute (执行者)

3.3 Sub Agent: Review (审查者)

3.4 Sub Agent: Test (测试者)

4. 编排机制

4.1 Main Agent 决策逻辑

4.2 Linus 三问决策框架

4.3 编排模式

并行编排

串行编排

条件编排

4.4 上下文隔离

5. Superpowers 集成

5.1 Superpowers 五技能体系

5.2 Main Agent 使用 Superpowers

规划阶段 (writing-plans)

需求讨论 (deep-interview)

执行阶段 (executing-plans)

审查阶段 (requesting-code-review)

调试阶段 (systematic-debugging)

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

5.3 Sub Agent 使用 Superpowers

5.4 所有 Agent 共享

6. 工作流示例

6.1 简单任务：修复 Bug

6.2 中等任务：实现登录功能

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

7. 实施指南

7.1 环境准备

配置 GLM-5.2

7.2 创建项目结构

7.3 创建 Main Agent 配置

7.4 创建工作流脚本

7.5 验证测试

8. 对比分析

8.1 v0.4 vs v0.5

8.2 优势总结

附录 A：版本变更说明

v0.5.1 (2026-07-01)

v0.5 (2026-07-01)

48 KiB

Raw Blame History