Files

T

claude_dev abb50cbce5 docs(v0.5.1): 补充 Linus 三问 + Superpowers 五技能体系

- 添加 Linus 三问工程审慎决策框架到决策部分
- 对齐 Superpowers 五技能标准工作流
  - writing-plans → executing-plans → requesting-code-review → systematic-debugging → finishing-a-development-branch
- 更新能力对照表和工作流图
- 添加版本变更说明附录

2026-07-01 19:05:28 +08:00

44 KiB

Raw Permalink Blame History

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.1	补充 Linus 三问 + Superpowers 五技能体系	2026-07-01

v0.5 核心变化

变更项	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)                        │
│  • 分析任务复杂度和范围                                         │
│  • 根据任务需要分析和决策                                       │
│  • 动态安排 Sub Agents                                          │
│  • 不是固化流程，而是灵活调整                                    │
│  • 最终验收和整合                                               │
│                                                                 │
│  能力 (依托 Superpowers):                                      │
│  • deep-interview — 需求讨论和知识提取                          │
│  • planning — 复杂任务的方案规划                               │
│  • CODE-REVIEW — 代码审查验证                                   │
│  • 其他 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: 快速确认需求 (AskUserQuestion)
     ↓
分析后决定
     ↓
安排 Execute Sub Agent (修复)
     ↓
验收整合

中等任务

用户: "实现用户登录功能"
     ↓
Main Agent: 使用 deep-interview 讨论需求
     ↓
分析后决定
     ↓
安排 Execute Sub Agent (实现)
     ↓
安排 Review Sub Agent (审查)
     ↓
验收整合

复杂任务

用户: "实现完整的用户认证系统"
     ↓
Main Agent: 使用 deep-interview 深度讨论需求
     ↓
使用 planning 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 进行系统化需求提取
分析任务需求 — 确定任务复杂度和范围
根据需要决定安排哪些 Sub Agents
协调 Sub Agents 之间的协作
验证整合 — 使用 CODE-REVIEW skill 进行代码审查验收
最终整合和提交

能力 (依托 Superpowers):

deep-interview — 需求讨论和知识提取 (核心能力)
planning — 复杂任务的方案规划
CODE-REVIEW — 代码审查验收
debugger — 问题诊断
其他 100+ Superpowers skills

限制:

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

工作方式:

1. 接收用户输入
2. 使用 deep-interview 讨论需求 (如需要)
3. 分析任务需要什么
4. 决定安排哪些 Sub Agents
5. 协调执行
6. 验收整合 (CODE-REVIEW)
7. 向用户汇报结果

需求讨论流程 (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
    │
    ├─ 安排 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 实现用户认证系统

┌─────────────────────────────────────────────────────────────┐
│  用户: "实现用户认证系统"                                     │
└─────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────┐
│  0. Main Agent: 需求讨论 (deep-interview)                   │
│                                                              │
│  使用 AskUserQuestion 提问:                                  │
│  • 需要支持哪些认证方式? (JWT/OAuth/Session)                 │
│  • 需要哪些端点? (登录/注册/刷新/登出)                       │
│  • 有什么安全要求? (加密/2FA/限流)                           │
│  • 前端需要什么功能? (表单/状态管理)                         │
│                                                              │
│  记录答案到 requirements/requirements.md                      │
└─────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────┐
│  Main Agent 分析决策                                          │
│                                                              │
│  这是一个复杂任务，需要:                                     │
│  1. 先用 planning skill 规划                                │
│  2. 安排 Execute Sub Agents 实现                            │
│  3. 安排 Review Sub Agent 审查                              │
│  4. 安排 Test Sub Agent 测试                                │
│  5. 验收整合 (CODE-REVIEW)                                  │
└─────────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────────┐
│  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: 验收整合 (CODE-REVIEW)                      │
│                                                              │
│  使用 CODE-REVIEW skill 进行验收:                           │
│  • 检查逻辑正确性和边界情况                                  │
│  • 安全漏洞检查 (JWT、密码处理)                              │
│  • 性能影响评估                                              │
│  • 测试覆盖率和质量                                          │
│  • 错误处理验证                                              │
│                                                              │
│  收集结果:                                                   │
│  • Execute 结果: 后端 API + 前端页面                        │
│  • Review 结果: 代码通过审查                                │
│  • Test 结果: 测试全部通过                                  │
│  • CODE-REVIEW 结果: 验收通过                                │
│                                                              │
│  整合并提交 Git                                            │
└─────────────────────────────────────────────────────────────┘

5.2 修复 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...

注意: 这个流程没有 planning 阶段，Main 根据任务需要直接跳过了

6. Superpowers 集成

6.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
      ↓                  ↓                       ↓                        ↓                          ↓
   编写计划            执行计划                 请求审查                  系统调试                   完成收尾

6.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

6.3 Main Agent 验收整合使用 Superpowers

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

// 整合结果并提交 Git

6.4 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.5 所有 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)

7. 动态编排模式

7.1 Main Agent 决策逻辑

// Main Agent 分析任务
async function orchestrate(task) {
  // 0. 需求讨论 (如需要)
  if (await needsDiscussion(task)) {
    const requirements = await /deep-interview `${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 /code-review `${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 /plan `分析: ${task}`
    const execute = await agent({ prompt: `执行: ${plan}` })
    const review = await agent({ prompt: `审查: ${execute.files}` })
    const test = await agent({ prompt: `测试: ${execute.features}` })
    const codeReview = await /code-review `${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
}

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. **与用户讨论需求** — 使用 `deep-interview` skill
2. 分析任务需求 — 确定任务复杂度和范围
3. 根据需要决定安排哪些 Sub Agents
4. 协调 Sub Agents 之间的协作
5. **验收整合** — 使用 `CODE-REVIEW` skill
6. 向用户汇报最终结果

## 需求讨论 (deep-interview)

**何时使用**:
- 用户输入模糊 (如 "实现一个功能"、"添加一个功能")
- 任务较复杂 (超过 20 字)
- 需要了解更多上下文

**如何使用**:
```javascript
// 需求讨论
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-skill", 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 工具编排

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: 只看需要测试的功能

决策框架

Linus 三问 (工程审慎决策)

Main Agent 在安排 Sub Agents 之前，必须先进行工程审慎判断：

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

如何应用：

用户提出模糊需求时，使用 Linus 三问过滤
规划复杂功能前，先验证问题真实性
选择技术方案时，评估是否能真正解决问题

技术编排决策

通过 Linus 三问后，再进行技术决策：

需求是否清晰? 不清晰 → 使用 deep-interview
这个任务需要哪些 Sub Agents?
需要 planning 吗?
Sub Agents 之间有依赖关系吗?
可以并行执行吗?

验收框架

在向用户汇报之前:

使用 CODE-REVIEW 验证代码质量
确认所有测试通过
整合所有结果
准备清晰的汇报


---

## 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: 创建项目结构

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 Agent 使用 deep-interview skill 与用户讨论需求
验收整合职责: Main Agent 使用 CODE-REVIEW skill 进行代码审查验收
不是固化流程: Main 根据需求灵活调整
专业分工: Sub Agents 有明确的专业角色
上下文隔离: 每个 Sub Agent 只能看到必要信息
共享能力: 所有 Agent 都遵循 Superpowers 工作方式

Main Agent 的核心能力

能力	Superpowers Skill	用途
规划	`writing-plans`	编写综合实现计划，假设执行者对代码库零上下文
执行	`executing-plans` (Agent 工具)	按步骤执行计划，有审查检查点
审查	`requesting-code-review` (CODE-REVIEW)	验收代码质量、安全、性能
调试	`systematic-debugging` (debugger)	系统化定位问题，而非随机尝试
收尾	`finishing-a-development-branch`	完成开发分支收尾（测试、文档、清理）
需求讨论	`deep-interview` (补充)	与用户系统化讨论需求，ASK→LISTEN→WRITE→DEEPEN→REPEAT
编排能力	Agent 工具	动态安排 Sub Agents

Superpowers 五技能工作流

┌─────────────────────────────────────────────────────────────────┐
│                    Main Agent (编排者)                            │
│                                                                 │
│  工作流 (Superpowers 五技能):                                    │
│  1. writing-plans → 编写实现计划                                 │
│  2. executing-plans → 执行计划 (Agent 工具编排 Sub Agents)      │
│  3. requesting-code-review → 请求代码审查 (CODE-REVIEW)           │
│  4. systematic-debugging → 系统化调试 (debugger)                 │
│  5. finishing-a-development-branch → 完成收尾                    │
│                                                                 │
│  补充能力:                                                       │
│  - deep-interview — 需求讨论和知识提取                           │
│  - Agent 工具 — 动态编排 Sub Agents                              │
└─────────────────────────────────────────────────────────────────┘

与 v0.4 的区别

v0.4	v0.5
架构师 Plan + Review	Main 需求讨论 + 编排 + 验收
无明确需求讨论机制	deep-interview skill
backend/frontend 执行	Execute/Review/Test 专业角色
无明确验收机制	CODE-REVIEW skill
固化工作流	Main 根据需求动态安排
SendMessage 跨实例	Agent 工具

关键变化

v0.5 更完整:

Main 承担需求讨论职责 (deep-interview)
Main 承担验收整合职责 (CODE-REVIEW)
Main 不是固化的 Plan/Review 角色
Sub Agents 有更细的专业分工
工作流不是固化的，Main 根据任务需要安排

v0.5 的三个核心变化:

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

文档版本: v0.5.1 最后更新: 2026-07-01 作者: Claude Dev 审核状态: Draft 实施状态: 设计阶段

附录：版本变更说明

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 标准的映射关系

44 KiB Raw Permalink Blame History Unescape Escape

sanguo_moziplus_v3 设计文档 v0.5

1. 版本变更

v0.5 核心变化

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 隔离原则

4.2 为什么隔离

5. 完整工作流示例

5.1 实现用户认证系统

5.2 修复 Bug (更简单的流程)

6. Superpowers 集成

6.1 Superpowers 五技能体系

6.2 Main Agent 使用 Superpowers

规划阶段 (writing-plans)

需求讨论 (deep-interview)

执行阶段 (executing-plans)

审查阶段 (requesting-code-review)

调试阶段 (systematic-debugging)

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

6.3 Main Agent 验收整合使用 Superpowers

6.4 Sub Agent 使用 Superpowers

6.5 所有 Agent 共享

7. 动态编排模式

7.1 Main Agent 决策逻辑

7.2 并行编排

7.3 串行编排

7.4 条件编排

8. 配置文件

8.1 Main Agent CLAUDE.md

验收整合 (CODE-REVIEW)

Sub Agent 类型

Execute Sub Agents

Review Sub Agents

Test Sub Agents

工作方式

简单任务

中等任务

复杂任务

调试任务

严格限制

可用能力 (Superpowers)

Superpowers 五技能体系 (核心工作流)

补充能力

Sub Agent 指派

上下文隔离

决策框架

Linus 三问 (工程审慎决策)

技术编排决策

验收框架

Phase 2: 创建项目结构

Phase 3: 创建 Main Agent 配置

Phase 4: 创建工作流脚本

Phase 5: 验证测试

10. 优势对比

11. 精髓总结

v0.5 设计精髓

Main Agent 的核心能力

Superpowers 五技能工作流

与 v0.4 的区别

关键变化

附录：版本变更说明

v0.5.1 (2026-07-01)

44 KiB

Raw Permalink Blame History