docs: 添加 v0.5 动态编排设计

- 创建 Main + Sub Agent 动态编排方案
- Main Agent 作为编排者，根据任务需要动态安排 Sub Agents
- Sub Agents 分为 Execute、Review、Test 专业角色
- 不是固化工作流，而是 Main 根据需求灵活调整
- 添加上下文隔离原则
- 创建工作流脚本模板

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

.claude/workflows/feature-development.js

@@ -0,0 +1,174 @@
+/**
+ * Feature Development Workflow
+ *
+ * 使用 Main + Sub Agent 架构完成功能开发
+ *
+ * 用法: Agent({ scriptPath: ".claude/workflows/feature-development.js", args: "实现用户认证功能" })
+ */
+
+export const meta = {
+  name: 'feature-development',
+  description: 'Main Agent 协调 Sub Agent 完成功能开发',
+  phases: [
+    { title: '分析需求', detail: 'Main Agent 分析并拆分任务' },
+    { title: '执行开发', detail: 'Executor Sub Agent 编写代码和测试' },
+    { title: '代码审查', detail: 'Reviewer Sub Agent 审查代码质量' },
+    { title: '整合验收', detail: 'Main Agent 整合结果并验收' }
+  ]
+}
+
+// 工作流主逻辑
+export default async function (feature) {
+  phase('分析需求')
+
+  log(`📋 功能需求: ${feature}`)
+
+  // Main Agent 分析需求
+  const analysis = await agent(`
+作为架构师，分析以下功能需求:
+
+"${feature}"
+
+请提供:
+1. 技术方案概述
+2. 需要的文件列表
+3. Executor 任务描述
+4. Reviewer 审查点
+
+返回结构化 JSON:
+{
+  "approach": "技术方案概述",
+  "files": ["预计需要的文件"],
+  "executorTask": "详细任务描述",
+  "reviewPoints": ["审查要点"]
+}
+  `, { schema: AnalysisSchema })
+
+  log(`✅ 分析完成: ${analysis.approach}`)
+
+  phase('执行开发')
+
+  // 指派 Executor Sub Agent
+  const executorResult = await agent(`
+作为后端开发专家，执行以下任务:
+
+${analysis.executorTask}
+
+技术要求:
+- 使用项目现有代码风格
+- 编写完整的单元测试
+- 测试覆盖率 > 80%
+
+完成后返回结构化 JSON:
+{
+  "files": ["修改的文件列表"],
+  "tests": "测试结果",
+  "changes": "主要改动说明",
+  "status": "完成|部分完成|失败"
+}
+  `, {
+    label: 'Executor',
+    schema: ExecutorResultSchema
+  })
+
+  log(`✅ Executor 完成: ${executorResult.status}`)
+  log(`📁 修改文件: ${executorResult.files.join(', ')}`)
+
+  phase('代码审查')
+
+  // 指派 Reviewer Sub Agent
+  const reviewResult = await agent(`
+作为代码审查专家，审查以下改动:
+
+文件: ${executorResult.files.join(', ')}
+改动: ${executorResult.changes}
+
+审查要点:
+${analysis.reviewPoints.map(p => `- ${p}`).join('\n')}
+
+检查项目:
+1. 代码质量和可读性
+2. 测试覆盖是否充分
+3. 是否有潜在的 bug
+4. 安全性考虑
+5. 性能影响
+
+返回结构化 JSON:
+{
+  "findings": ["发现的问题"],
+  "severity": "low|medium|high|critical",
+  "approval": true|false,
+  "suggestions": ["改进建议"]
+}
+  `, {
+    label: 'Reviewer',
+    schema: ReviewResultSchema
+  })
+
+  log(`📊 审查结果: ${reviewResult.approval ? '✅ 通过' : '❌ 需修改'}`)
+
+  if (reviewResult.findings.length > 0) {
+    log(`⚠️ 发现 ${reviewResult.findings.length} 个问题:`)
+    reviewResult.findings.forEach(f => log(`  - ${f}`))
+  }
+
+  phase('整合验收')
+
+  // Main Agent 整合结果
+  const final = {
+    feature,
+    approach: analysis.approach,
+    files: executorResult.files,
+    tests: executorResult.tests,
+    review: reviewResult,
+    status: reviewResult.approval ? '完成' : '需修改'
+  }
+
+  log(`🎯 最终状态: ${final.status}`)
+
+  return final
+}
+
+// JSON Schema 定义
+const AnalysisSchema = {
+  type: "object",
+  properties: {
+    approach: { type: "string", description: "技术方案概述" },
+    files: { type: "array", items: { type: "string" }, description: "预计需要的文件" },
+    executorTask: { type: "string", description: "详细任务描述" },
+    reviewPoints: { type: "array", items: { type: "string" }, description: "审查要点" }
+  },
+  required: ["approach", "files", "executorTask", "reviewPoints"]
+}
+
+const ExecutorResultSchema = {
+  type: "object",
+  properties: {
+    files: { type: "array", items: { type: "string" }, description: "修改的文件列表" },
+    tests: { type: "string", description: "测试结果" },
+    changes: { type: "string", description: "主要改动说明" },
+    status: { type: "string", enum: ["完成", "部分完成", "失败"], description: "执行状态" }
+  },
+  required: ["files", "tests", "changes", "status"]
+}
+
+const ReviewResultSchema = {
+  type: "object",
+  properties: {
+    findings: { type: "array", items: { type: "string" }, description: "发现的问题" },
+    severity: { type: "string", enum: ["low", "medium", "high", "critical"], description: "严重程度" },
+    approval: { type: "boolean", description: "是否通过审查" },
+    suggestions: { type: "array", items: { type: "string" }, description: "改进建议" }
+  },
+  required: ["findings", "severity", "approval", "suggestions"]
+}
+
+// 导出 phase 函数供脚本使用
+function phase(title) {
+  // 在实际使用中，这会被 Workflow 工具的 phase() 替换
+  console.log(`\n=== ${title} ===`)
+}
+
+function log(message) {
+  console.log(message)
+}

docs/design/05-migration-to-sub-agent.md

@@ -0,0 +1,266 @@
+# v0.4 → Main + Sub Agent 迁移计划
+
+## 概述
+
+将三实例方案 (v0.4) 迁移到 Main + Sub Agent 架构。
+
+## 架构对比
+
+### v0.4 (三实例)
+
+```
+┌─────────────────────────────────────────┐
+│         tmux sanguo_dev                 │
+│  ┌─────────────┐ ┌─────────┐ ┌───────┐ │
+│  │ Claude      │ │ Codex   │ │Gemini │ │
+│  │ (架构师)    │ │(后端)   │ │(前端) │ │
+│  └─────────────┘ └─────────┘ └───────┘ │
+└─────────────────────────────────────────┘
+
+通信: SendMessage 跨实例
+项目: 3 个独立目录
+```
+
+### Main + Sub Agent
+
+```
+┌─────────────────────────────────────────┐
+│    sanguo_moziplus_v3 项目              │
+│  ┌───────────────────────────────────┐  │
+│  │     Main Agent (架构师)          │  │
+│  │  - 分析需求                       │  │
+│  │  - Agent() 指派 Sub Agent        │  │
+│  │  - 整合结果                       │  │
+│  └───────────────────────────────────┘  │
+│           │              │              │
+│           ▼              ▼              │
+│  ┌──────────────┐ ┌──────────────┐     │
+│  │ Sub Agent 1  │ │ Sub Agent 2  │     │
+│  │ (Executor)  │ │ (Reviewer)  │     │
+│  └──────────────┘ └──────────────┘     │
+└─────────────────────────────────────────┘
+
+通信: Agent 工具
+项目: 1 个目录
+```
+
+## 迁移映射
+
+| 组件 | v0.4 | 目标 | 操作 |
+|------|------|------|------|
+| **Claude Code 实例** | 3 个 | 1 个 | 移除多余实例 |
+| **项目目录** | 3 个 | 1 个 | 保留 sanguo_moziplus_v3 |
+| **CLAUDE.md** | 3 个文件 | 1 个文件 | 合并到主项目 |
+| **SendMessage** | 跨实例 | Agent 工具 | 替换通信方式 |
+| **tmux 配置** | ~/.tmux-sanguo.conf | 不需要 | 删除 |
+| **启动脚本** | start-sanguo-env.sh | 不需要 | 删除 |
+| **消息队列** | message.sh | 不需要 | 删除 |
+| **ttyd Web** | 8088 端口 | 可选 | 保留用于远程 |
+| **角色 Skills** | 3 个 | 3 个 | ✅ 保留 |
+| **Superpowers** | 共享 | 共享 | ✅ 保留 |
+| **GLM-5.2** | 统一后端 | 统一后端 | ✅ 保留 |
+
+## 迁移步骤
+
+### 步骤 1: 保留部分
+
+#### 1.1 保留 Superpowers Skills
+
+**无需操作** - 已安装在 `~/.claude/skills/`
+
+#### 1.2 保留角色 Skills
+
+**无需操作** - 已创建:
+- `~/.claude/skills/architect-role/`
+- `~/.claude/skills/backend-dev/`
+- `~/.claude/skills/frontend-dev/`
+
+#### 1.3 保留 GLM-5.2 配置
+
+**无需操作** - 已在 `~/.claude/settings.json`
+
+### 步骤 2: 创建 Main Agent 配置
+
+#### 2.1 创建主项目 CLAUDE.md
+
+在 `sanguo_moziplus_v3/.claude/CLAUDE.md`:
+
+```markdown
+# sanguo_moziplus_v3 - Main Agent
+
+## 角色
+
+你是架构师/项目经理，负责协调 Sub Agent 完成开发任务。
+
+## 核心职责
+
+- 接收用户需求
+- 分析并拆分任务
+- 指派 Sub Agent 执行
+- 收集并整合结果
+- 最终审查和验收
+
+## 严格限制
+
+**绝对不亲自编写代码**。所有编码任务通过 Agent 工具指派给 Sub Agent。
+
+## 工作流程
+
+1. 接收用户需求
+2. 加载 architect-role skill
+3. 分析需求，拆分任务
+4. 使用 Agent 工具指派 Sub Agent:
+   ```javascript
+   Agent({
+     subagent_type: "claude",
+     prompt: "作为后端开发专家，实现: ..."
+   })
+   ```
+5. 收集 Sub Agent 返回结果
+6. 加载 CODE-REVIEW skill 审查
+7. 整合结果并提交 Git
+
+## Sub Agent 类型
+
+- **Executor**: 执行编码任务 (加载 backend-dev/frontend-dev)
+- **Reviewer**: 代码审查 (加载 CODE-REVIEW)
+
+## 决策框架 (Linus 三问)
+
+1. 这是现实问题还是想象问题？
+2. 这个问题真的需要解决吗？
+3. 这个方案真的能解决问题吗？
+```
+
+### 步骤 3: 创建工作流
+
+已在 `.claude/workflows/feature-development.js`
+
+### 步骤 4: 清理 v0.4 组件
+
+#### 4.1 可以删除的文件
+
+```bash
+# tmux 配置 (可选删除，如果不用三实例)
+rm ~/.tmux-sanguo.conf
+
+# 旧项目目录 (可选删除，如果不再使用)
+rm -rf ~/.claude/projects/sanguo-main
+rm -rf ~/.claude/projects/sanguo-backend
+rm -rf ~/.claude/projects/sanguo-frontend
+
+# 启动脚本 (可选删除)
+rm ~/.claude/messages/sanguo/start-sanguo-env.sh
+rm ~/.claude/messages/sanguo/message.sh
+```
+
+#### 4.2 保留的文件
+
+```bash
+# 角色 Skills - 保留
+~/.claude/skills/architect-role/
+~/.claude/skills/backend-dev/
+~/.claude/skills/frontend-dev/
+
+# GLM-5.2 配置 - 保留
+~/.claude/settings.json
+
+# 可选: ttyd 配置 (如果需要 Web 访问)
+~/.ttyd
+```
+
+### 步骤 5: 更新文档
+
+#### 5.1 创建新设计文档
+
+`docs/design/06-design-v0.5-sub-agent.md`
+
+#### 5.2 更新快速参考
+
+`docs/06-quick-reference-v0.5.md`
+
+### 步骤 6: 验证测试
+
+#### 6.1 测试 Agent 工具
+
+```javascript
+// 在 Main Agent 中测试
+Agent({
+  subagent_type: "claude",
+  prompt: "作为后端开发专家，编写一个简单的 Hello World API"
+})
+```
+
+#### 6.2 测试工作流
+
+```javascript
+Agent({
+  scriptPath: ".claude/workflows/feature-development.js",
+  args: "实现用户登录功能"
+})
+```
+
+## 对比表
+
+| 方面 | v0.4 三实例 | Main + Sub Agent |
+|------|-------------|------------------|
+| **复杂度** | 🟡 中等 | 🟢 简单 |
+| **启动** | 需要启动脚本 | 直接使用 |
+| **通信** | SendMessage (有限制) | Agent 工具 |
+| **隔离** | 实例级别 | 会话级别 |
+| **并行** | ⚠️ 复杂 | ✅ 支持 |
+| **学习成本** | 🟡 中等 | 🟢 低 |
+| **维护成本** | 🟡 中等 | 🟢 低 |
+| **Web 访问** | ✅ ttyd + tmux | ⚠️ 需要 Claude Code |
+
+## 优势
+
+Main + Sub Agent 方案优势:
+
+1. **更简单**: 不需要 tmux、启动脚本
+2. **更灵活**: Sub Agent 自动隔离、并行执行
+3. **更可靠**: Agent 工具是内置功能，无跨实例限制
+4. **更易维护**: 单一项目目录
+
+## 迁移检查清单
+
+### 保留
+- [x] Superpowers skills
+- [x] 角色 Skills (architect-role, backend-dev, frontend-dev)
+- [x] GLM-5.2 配置
+- [ ] ttyd (可选)
+
+### 创建
+- [ ] .claude/CLAUDE.md
+- [ ] .claude/workflows/feature-development.js
+- [ ] docs/design/06-design-v0.5-sub-agent.md
+- [ ] docs/06-quick-reference-v0.5.md
+
+### 删除
+- [ ] ~/.tmux-sanguo.conf
+- [ ] ~/.claude/projects/sanguo-*
+- [ ] ~/.claude/messages/sanguo/*.sh
+
+### 测试
+- [ ] Agent 工具测试
+- [ ] 工作流测试
+- [ ] Skills 加载测试
+
+## 回滚方案
+
+如果需要回滚到 v0.4:
+
+```bash
+# 恢复项目目录
+# 从 Git 恢复或重新创建
+
+# 重新运行 v0.4 设置
+~/.claude/messages/sanguo/test-sanguo-env.sh
+~/.claude/messages/sanguo/start-sanguo-env.sh
+```
+
+## 相关文档
+
+- [v0.4 设计文档](./04-design-v0.4.md)
+- [Sub Agent 方案](../sub-agent-orchestration.md)
+- [Agent 工具文档](https://docs.anthropic.com/claude-code/agent)

docs/design/06-design-v0.5-dynamic-orchestration.md

@@ -0,0 +1,876 @@
+# sanguo_moziplus_v3 设计文档 v0.5
+
+**项目名称**: sanguo_moziplus_v3
+**版本**: v0.5
+**创建日期**: 2026-07-01
+**状态**: Draft
+**基于**: v0.4 + Main + Sub Agent 动态编排
+
+---
+
+## 1. 版本变更
+
+| 版本 | 变更说明 | 日期 |
+|------|---------|------|
+| v0.1 | 初始设计 | 2026-06-29 |
+| v0.2 | videotext 调研，GLM-5.2、Web 访问 | 2026-06-29 |
+| v0.3 | 移除 CCB，采用 Claude Code 内置多 Agent | 2026-06-30 |
+| v0.4 | 三实例方案：SendMessage 跨实例 | 2026-06-30 |
+| **v0.5** | **Main + Sub Agent：动态编排** | **2026-07-01** |
+
+### v0.5 核心变化
+
+| 变更项 | v0.4 | v0.5 | 原因 |
+|--------|------|------|------|
+| **编排方式** | SendMessage 跨实例 | **Agent 工具动态编排** | 更灵活的协作 |
+| **Main 角色** | 架构师 (Plan + Review) | **编排者 + 验收整合** | 专注于编排 |
+| **Sub Agent 角色** | backend/frontend 执行 | **Execute/Review/Test 专业角色** | 更细的分工 |
+| **工作流** | 固化流程 | **Main 根据需求动态安排** | 更灵活 |
+
+---
+
+## 2. 设计精髓
+
+### 2.1 核心理念
+
+**Main Agent 根据需求动态编排 Sub Agents**
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    Main Agent (编排者)                          │
+│                                                                 │
+│  职责:                                                          │
+│  • 根据任务需要分析和决策                                       │
+│  • 动态安排 Sub Agents                                          │
+│  • 不是固化流程，而是灵活调整                                    │
+│  • 最终验收和整合                                               │
+│                                                                 │
+│  能力 (依托 Superpowers):                                      │
+│  • planning (如需要)                                            │
+│  • 其他 100+ Superpowers skills                                │
+│  • Agent 工具编排                                               │
+└─────────────────────────────────────────────────────────────────┘
+                    │
+                    │ Agent 工具动态编排
+                    │
+         ┌──────────┼──────────┐
+         │          │          │
+         ▼          ▼          ▼
+┌──────────────────┐ ┌──────────┐ ┌──────────┐
+│ Sub Agent:       │ │Sub Agent:│ │Sub Agent:│
+│ Execute          │ │Review    │ │Test      │
+│                  │ │          │ │          │
+│ 专业角色:        │ │专业角色: │ │专业角色: │
+│ • backend-dev    │ │CODE-     │ │test-     │
+│ • frontend-dev   │ │REVIEW    │ │engineer  │
+│ • ...            │ │security  │ │e2e       │
+│                  │ │perf      │ │...       │
+└──────────────────┘ └──────────┘ └──────────┘
+
+所有 Agent 都能访问 Superpowers
+```
+
+### 2.2 动态编排示例
+
+**不是固化流程，Main 根据任务需要安排**
+
+#### 简单任务
+
+```
+用户: "修复这个 bug"
+     ↓
+Main Agent: 分析后决定
+     ↓
+安排 Execute Sub Agent (修复)
+     ↓
+验收整合
+```
+
+#### 中等任务
+
+```
+用户: "实现用户登录功能"
+     ↓
+Main Agent: 分析后决定
+     ↓
+安排 Execute Sub Agent (实现)
+     ↓
+安排 Review Sub Agent (审查)
+     ↓
+验收整合
+```
+
+#### 复杂任务
+
+```
+用户: "实现完整的用户认证系统"
+     ↓
+Main Agent: 使用 planning skill 分析
+     ↓
+安排 Execute Sub Agent (后端实现)
+安排 Execute Sub Agent (前端实现)
+     ↓
+安排 Review Sub Agent (代码审查)
+安排 Review Sub Agent (安全审查)
+     ↓
+安排 Test Sub Agent (测试验证)
+     ↓
+验收整合
+```
+
+#### 调试任务
+
+```
+用户: "登录接口有问题"
+     ↓
+Main Agent: 分析后决定
+     ↓
+安排 debugger Sub Agent (定位问题)
+     ↓
+安排 Execute Sub Agent (修复问题)
+     ↓
+安排 Test Sub Agent (验证修复)
+     ↓
+验收整合
+```
+
+### 2.3 关键特性
+
+1. **动态编排**: Main 根据任务需要决定安排哪些 Sub Agents
+2. **专业分工**: Sub Agents 有明确的专业角色
+3. **上下文隔离**: 每个 Sub Agent 只能看到必要信息
+4. **共享能力**: 所有 Agent 都遵循 Superpowers 工作方式
+5. **灵活调整**: 不是固化流程，Main 可以根据情况调整
+
+---
+
+## 3. 角色定义
+
+### 3.1 Main Agent (编排者)
+
+**职责**:
+- 分析任务需求
+- 根据需要决定安排哪些 Sub Agents
+- 协调 Sub Agents 之间的协作
+- 最终验收和整合
+
+**能力 (依托 Superpowers)**:
+- `planning` — 复杂任务的方案规划
+- `debugger` — 问题诊断
+- 其他 100+ Superpowers skills
+
+**限制**:
+- 不亲自编写代码
+- 不亲自执行具体实现
+
+**工作方式**:
+```
+1. 接收任务
+2. 分析任务需要什么
+3. 决定安排哪些 Sub Agents
+4. 协调执行
+5. 验收整合
+```
+
+### 3.2 Sub Agent: Execute (执行者)
+
+**职责**:
+- 执行具体实现任务
+- 编写代码
+- 实现功能
+
+**专业角色 (通过 prompt 指定)**:
+- **backend-dev**: 后端开发
+- **frontend-dev**: 前端开发
+- **database-dev**: 数据库开发
+- **infrastructure**: 基础设施
+
+**上下文**:
+- 只能看到任务描述和项目代码
+- 看不到其他 Sub Agents 的工作
+
+### 3.3 Sub Agent: Review (审查者)
+
+**职责**:
+- 审查代码质量
+- 检查安全性
+- 检查性能
+
+**专业角色 (通过 prompt 指定)**:
+- **CODE-REVIEW**: 代码质量审查
+- **security-reviewer**: 安全审查
+- **performance-reviewer**: 性能审查
+
+**上下文**:
+- 只能看到需要审查的代码
+- 看不到实现过程
+
+### 3.4 Sub Agent: Test (测试者)
+
+**职责**:
+- 编写测试用例
+- 执行测试
+- 验证功能
+
+**专业角色 (通过 prompt 指定)**:
+- **test-engineer**: 单元测试
+- **e2e-tester**: 端到端测试
+- **qa-tester**: 质量保证测试
+
+**上下文**:
+- 只能看到需要测试的功能
+- 看不到实现细节
+
+---
+
+## 4. 上下文隔离
+
+### 4.1 隔离原则
+
+```
+Main Agent
+    │
+    ├─ 安排 Execute Sub Agent
+    │   └─ 只传递任务描述
+    │
+    ├─ 安排 Review Sub Agent
+    │   └─ 只传递需要审查的代码
+    │
+    └─ 安排 Test Sub Agent
+        └─ 只传递需要测试的功能
+```
+
+**每个 Sub Agent 只能看到必要信息**
+
+| Sub Agent | 可以看到 | 不能看到 |
+|-----------|---------|---------|
+| **Execute** | 任务描述、项目代码 | 其他 Sub Agents 的工作 |
+| **Review** | 需要审查的代码 | 实现过程、其他 Sub Agents |
+| **Test** | 需要测试的功能 | 实现细节、审查过程 |
+
+### 4.2 为什么隔离
+
+- **Execute 不受 Review 影响**: 专注实现
+- **Review 不受 Execute 过程影响**: 客观评估
+- **Test 不受实现细节影响**: 独立验证
+
+---
+
+## 5. 完整工作流示例
+
+### 5.1 实现用户认证系统
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  用户: "实现用户认证系统"                                     │
+└─────────────────────────────────────────────────────────────┘
+                          ↓
+┌─────────────────────────────────────────────────────────────┐
+│  Main Agent 分析决策                                          │
+│                                                              │
+│  这是一个复杂任务，需要:                                     │
+│  1. 先用 planning skill 规划                                │
+│  2. 安排 Execute Sub Agents 实现                            │
+│  3. 安排 Review Sub Agent 审查                              │
+│  4. 安排 Test Sub Agent 测试                                │
+│  5. 验收整合                                                │
+└─────────────────────────────────────────────────────────────┘
+                          ↓
+┌─────────────────────────────────────────────────────────────┐
+│  1. Main Agent: planning skill                              │
+│                                                              │
+│  分析需求:                                                   │
+│  - 用户认证: JWT 方案                                        │
+│  - 后端: /auth/login, /auth/register                        │
+│  - 前端: 登录页面、注册页面                                  │
+│  - 测试: 单元测试 + E2E 测试                                 │
+│                                                              │
+│  输出规划文档                                               │
+└─────────────────────────────────────────────────────────────┘
+                          ↓
+┌─────────────────────────────────────────────────────────────┐
+│  2. Main Agent: 安排 Execute Sub Agents                     │
+│                                                              │
+│  Agent({                                                     │
+│    subagent_type: "claude",                                 │
+│    prompt: `                                                 │
+│      作为后端开发专家，实现 JWT 认证 API:                    │
+│                                                              │
+│      ${planResult.backendTask}                              │
+│                                                              │
+│      技术要求:                                               │
+│      - JWT 认证                                              │
+│      - bcrypt 密码哈希                                       │
+│      - 编写单元测试                                          │
+│    `                                                         │
+│  })                                                         │
+│                                                              │
+│  Agent({                                                     │
+│    subagent_type: "claude",                                 │
+│    prompt: `                                                 │
+│      作为前端开发专家，实现登录注册页面:                      │
+│                                                              │
+│      ${planResult.frontendTask}                             │
+│                                                              │
+│      技术要求:                                               │
+│      - shadcn/ui 组件                                        │
+│      - 表单验证                                              │
+│      - 调用后端 API                                          │
+│    `                                                         │
+│  })                                                         │
+└─────────────────────────────────────────────────────────────┘
+                          ↓
+┌─────────────────────────────────────────────────────────────┐
+│  3. Main Agent: 安排 Review Sub Agent                       │
+│                                                              │
+│  Agent({                                                     │
+│    subagent_type: "claude",                                 │
+│    prompt: `                                                 │
+│      作为代码审查专家，审查以下文件:                          │
+│                                                              │
+│      ${executeResult.files}                                 │
+│                                                              │
+│      检查:                                                   │
+│      - 代码质量                                              │
+│      - 安全性 (JWT、密码处理)                                │
+│      - 性能                                                  │
+│    `                                                         │
+│  })                                                         │
+└─────────────────────────────────────────────────────────────┘
+                          ↓
+┌─────────────────────────────────────────────────────────────┐
+│  4. Main Agent: 安排 Test Sub Agent                         │
+│                                                              │
+│  Agent({                                                     │
+│    subagent_type: "claude",                                 │
+│    prompt: `                                                 │
+│      作为测试工程师，验证用户认证功能:                       │
+│                                                              │
+│      ${executeResult.features}                              │
+│                                                              │
+│      测试:                                                   │
+│      - 单元测试覆盖                                          │
+│      - E2E 测试 (登录、注册、登出)                           │
+│      - 边界情况测试                                          │
+│    `                                                         │
+│  })                                                         │
+└─────────────────────────────────────────────────────────────┘
+                          ↓
+┌─────────────────────────────────────────────────────────────┐
+│  5. Main Agent: 验收整合                                    │
+│                                                              │
+│  收集结果:                                                   │
+│  • Execute 结果: 后端 API + 前端页面                        │
+│  • Review 结果: 代码通过审查                                │
+│  • Test 结果: 测试全部通过                                  │
+│                                                              │
+│  整合并提交 Git                                            │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 5.2 修复 Bug (更简单的流程)
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  用户: "登录接口报错"                                        │
+└─────────────────────────────────────────────────────────────┘
+                          ↓
+┌─────────────────────────────────────────────────────────────┐
+│  Main Agent 分析决策                                          │
+│                                                              │
+│  这是一个简单任务，不需要规划:                               │
+│  1. 安排 debugger Sub Agent 定位问题                        │
+│  2. 安排 Execute Sub Agent 修复                             │
+│  3. 安排 Test Sub Agent 验证                                │
+│  4. 验收整合                                                │
+└─────────────────────────────────────────────────────────────┘
+                          ↓
+Main Agent 直接安排 Sub Agents...
+```
+
+**注意**: 这个流程没有 planning 阶段，Main 根据任务需要直接跳过了
+
+---
+
+## 6. Superpowers 集成
+
+### 6.1 Main Agent 使用 Superpowers
+
+```javascript
+// 复杂任务，先规划
+const plan = await /plan "设计用户认证系统"
+
+// 根据规划安排 Sub Agents
+// ...
+```
+
+### 6.2 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. 返回结果
+```
+
+### 6.3 所有 Agent 共享
+
+```
+Main Agent
+    │
+    ├─ planning skill
+    ├─ debugger skill
+    ├─ ... (其他 Superpowers)
+    └─ Agent 工具编排
+
+Sub Agents
+    │
+    ├─ backend-dev skill
+    ├─ frontend-dev skill
+    ├─ CODE-REVIEW skill
+    ├─ test-engineer skill
+    ├─ ... (其他 Superpowers)
+    └─ Agent 工具 (可启动更深层 Agent)
+
+Superpowers Skills
+    │
+    ├─ planning
+    ├─ CODE-REVIEW
+    ├─ test-engineer
+    ├─ backend-dev
+    ├─ frontend-dev
+    ├─ debugger
+    ├─ ... (100+ skills)
+```
+
+---
+
+## 7. 动态编排模式
+
+### 7.1 Main Agent 决策逻辑
+
+```javascript
+// Main Agent 分析任务
+async function orchestrate(task) {
+  const analysis = await analyzeTask(task)
+
+  // 根据分析结果决定编排策略
+
+  if (analysis.complexity === "low") {
+    // 简单任务: 直接 Execute
+    const execute = await agent({ prompt: `执行: ${task}` })
+    return await integrate(execute)
+  }
+
+  if (analysis.complexity === "medium") {
+    // 中等任务: Execute + Review
+    const execute = await agent({ prompt: `执行: ${task}` })
+    const review = await agent({ prompt: `审查: ${execute.files}` })
+    return await integrate(execute, review)
+  }
+
+  if (analysis.complexity === "high") {
+    // 复杂任务: Plan + Execute + Review + Test
+    const plan = await /plan `分析: ${task}`
+    const execute = await agent({ prompt: `执行: ${plan}` })
+    const review = await agent({ prompt: `审查: ${execute.files}` })
+    const test = await agent({ prompt: `测试: ${execute.features}` })
+    return await integrate(plan, execute, review, test)
+  }
+}
+```
+
+### 7.2 并行编排
+
+```javascript
+// Main Agent 可以并行安排多个 Sub Agents
+const [backend, frontend] = await Promise.all([
+  agent({ prompt: "后端: 实现 API" }),
+  agent({ prompt: "前端: 实现页面" })
+])
+```
+
+### 7.3 串行编排
+
+```javascript
+// 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 条件编排
+
+```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)
+}
+```
+
+---
+
+## 8. 配置文件
+
+### 8.1 Main Agent CLAUDE.md
+
+```markdown
+# sanguo_moziplus_v3 - Main Agent (编排者)
+
+## 角色
+
+你是任务编排者，负责根据任务需要动态安排 Sub Agents。
+
+## 核心职责
+
+1. 分析任务需求
+2. 根据需要决定安排哪些 Sub Agents
+3. 协调 Sub Agents 之间的协作
+4. 最终验收和整合
+
+## Sub Agent 类型
+
+### Execute Sub Agents
+- backend-dev: 后端开发
+- frontend-dev: 前端开发
+- database-dev: 数据库开发
+- infrastructure: 基础设施
+
+### Review Sub Agents
+- CODE-REVIEW: 代码质量审查
+- security-reviewer: 安全审查
+- performance-reviewer: 性能审查
+
+### Test Sub Agents
+- test-engineer: 单元测试
+- e2e-tester: 端到端测试
+- qa-tester: 质量保证测试
+
+## 工作方式
+
+**不是固化流程，根据任务需要灵活安排**
+
+### 简单任务
+```
+分析 → 安排 Execute → 验收整合
+```
+
+### 中等任务
+```
+分析 → 安排 Execute → 安排 Review → 验收整合
+```
+
+### 复杂任务
+```
+分析 → planning → 安排 Execute → 安排 Review → 安排 Test → 验收整合
+```
+
+### 调试任务
+```
+分析 → 安排 debugger → 安排 Execute (修复) → 安排 Test (验证) → 验收整合
+```
+
+## 严格限制
+
+- 不亲自编写代码
+- 不亲自执行具体实现
+
+## 可用能力 (Superpowers)
+
+- planning — 复杂任务的方案规划
+- debugger — 问题诊断
+- 其他 100+ Superpowers skills
+- Agent 工具编排
+
+## Sub Agent 指派
+
+\`\`\`javascript
+// Execute
+Agent({
+  subagent_type: "claude",
+  prompt: \`作为后端开发专家，实现: \${task}\`
+})
+
+// Review
+Agent({
+  subagent_type: "claude",
+  prompt: \`作为代码审查专家，审查: \${files}\`
+})
+
+// Test
+Agent({
+  subagent_type: "claude",
+  prompt: \`作为测试工程师，测试: \${features}\`
+})
+\`\`\`
+
+## 上下文隔离
+
+- Execute Sub Agent: 只看任务描述
+- Review Sub Agent: 只看需要审查的代码
+- Test Sub Agent: 只看需要测试的功能
+
+## 决策框架
+
+在安排 Sub Agents 之前问自己:
+1. 这个任务需要哪些 Sub Agents?
+2. 需要 planning 吗?
+3. Sub Agents 之间有依赖关系吗?
+4. 可以并行执行吗?
+```
+
+---
+
+## 9. 实施步骤
+
+### Phase 1: 环境准备
+
+#### 1.1 配置 GLM-5.2
+
+```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: 创建项目结构
+
+```bash
+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`:
+
+```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 /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: 验证测试
+
+```javascript
+// 测试简单任务
+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 设计精髓
+
+1. **Main Agent 是编排者**: 根据任务需要动态安排 Sub Agents
+2. **不是固化流程**: Main 根据需求灵活调整
+3. **专业分工**: Sub Agents 有明确的专业角色
+4. **上下文隔离**: 每个 Sub Agent 只能看到必要信息
+5. **共享能力**: 所有 Agent 都遵循 Superpowers 工作方式
+
+### 与 v0.4 的区别
+
+| v0.4 | v0.5 |
+|------|------|
+| 架构师 Plan + Review | Main 编排 + 验收 |
+| backend/frontend 执行 | Execute/Review/Test 专业角色 |
+| 固化工作流 | **Main 根据需求动态安排** |
+| SendMessage 跨实例 | Agent 工具 |
+
+### 关键变化
+
+**v0.5 更灵活**:
+- Main 不是固化的 Plan/Review 角色
+- Sub Agents 有更细的专业分工
+- 工作流不是固化的，Main 根据任务需要安排
+
+---
+
+**文档版本**: v0.5
+**最后更新**: 2026-07-01
+**作者**: Claude Dev
+**审核状态**: Draft
+**实施状态**: 设计阶段

docs/sub-agent-orchestration.md

@@ -0,0 +1,271 @@
+# Sub Agent Orchestration 方案
+
+## 概述
+
+使用 Main + Sub Agent 架构替代 CCB（Claude Code Blackboard）方案。
+
+## 架构
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    Main Agent (Planner)                  │
+│  - 需求分析、任务拆分、指派 Sub Agent                     │
+│  - 收集结果、最终审查、整合                               │
+└─────────────────────────────────────────────────────────┘
+           │                    │
+           ▼                    ▼
+┌──────────────────┐  ┌──────────────────┐
+│ Sub Agent 1      │  │ Sub Agent 2      │
+│ (Executor)       │  │ (Reviewer)       │
+│ - 执行编码任务   │  │ - 代码审查       │
+│ - 编写测试       │  │ - 质量检查       │
+└──────────────────┘  └──────────────────┘
+```
+
+## 关键特性
+
+### 1. 默认隔离
+
+- **会话历史隔离**：Sub Agent 看不到 Main Agent 的对话
+- **文件访问共享**：Sub Agent 可以读写项目文件
+- **工作目录相同**：所有 Agent 在同一项目目录
+
+### 2. 通信机制
+
+**Main → Sub**: 通过 `Agent` 工具指派任务
+```javascript
+Agent({
+  subagent_type: "executor",
+  prompt: "实现用户认证 API: ..."
+})
+```
+
+**Sub → Main**: 通过返回结果
+```javascript
+// Sub Agent 完成后返回结构化结果
+return {
+  files: ["src/auth.ts", "src/auth.test.ts"],
+  tests: "12/12 通过",
+  status: "完成"
+}
+```
+
+### 3. 并行执行
+
+```javascript
+// 并行启动多个 Sub Agent
+Agent({ subagent_type: "executor", prompt: "..." })
+Agent({ subagent_type: "reviewer", prompt: "..." })
+```
+
+## 工作流示例
+
+### 完整开发流程
+
+#### 1. Main Agent 接收需求
+
+```javascript
+// 用户: "实现用户认证功能"
+// Main Agent 分析需求
+```
+
+#### 2. Main Agent 拆分任务
+
+```javascript
+const task = {
+  feature: "用户认证",
+  subtasks: [
+    { role: "executor", task: "实现 JWT 认证 API" },
+    { role: "executor", task: "编写单元测试" },
+    { role: "reviewer", task: "代码审查" }
+  ]
+}
+```
+
+#### 3. Main Agent 指派 Sub Agent
+
+```javascript
+// 指派 Executor
+const executorResult = await Agent({
+  subagent_type: "claude",
+  prompt: `
+作为后端开发专家，实现用户认证 API:
+1. POST /auth/login - 用户登录
+2. POST /auth/register - 用户注册
+3. 使用 bcrypt 和 JWT
+4. 编写测试
+返回结构化结果: { files, tests, status }
+  `
+})
+```
+
+#### 4. Main Agent 收集结果
+
+```javascript
+// 指派 Reviewer
+const reviewResult = await Agent({
+  subagent_type: "claude",
+  prompt: `
+作为代码审查专家，审查以下文件:
+${executorResult.files.join(', ')}
+检查: 代码质量、测试覆盖、安全性
+返回: { findings, approval }
+  `
+})
+```
+
+#### 5. Main Agent 整合
+
+```javascript
+if (reviewResult.approval) {
+  // 整合代码，提交 Git
+  await整合提交()
+}
+```
+
+## Sub Agent 类型
+
+### 1. Executor（执行者）
+
+**职责**：
+- 编写代码
+- 编写测试
+- 实现功能
+
+**技能**：backend-dev, frontend-dev
+
+### 2. Reviewer（审查者）
+
+**职责**：
+- 代码审查
+- 质量检查
+- 安全性验证
+
+**技能**：CODE-REVIEW, test-automation-skills
+
+### 3. Planner（规划者 - Main）
+
+**职责**：
+- 需求分析
+- 任务拆分
+- 资源协调
+- 最终验收
+
+## 优势对比 CCB
+
+| 特性 | Main+Sub | CCB |
+|------|----------|-----|
+| 会话隔离 | ✅ 默认 | ⚠️ 需手动管理 |
+| 通信机制 | Agent 工具 | Blackboard |
+| 并行执行 | ✅ 支持 | ⚠️ 复杂 |
+| 上下文共享 | 通过文件 | 通过 Blackboard |
+| 学习成本 | 🟢 低 | 🟡 中 |
+
+## 实施步骤
+
+### 步骤 1: 定义 Sub Agent 类型
+
+在项目 `.claude/` 目录创建配置：
+
+```json
+{
+  "subAgents": {
+    "executor": {
+      "description": "执行编码任务",
+      "skills": ["backend-dev", "frontend-dev"]
+    },
+    "reviewer": {
+      "description": "代码审查",
+      "skills": ["CODE-REVIEW", "qa-test-planner"]
+    }
+  }
+}
+```
+
+### 步骤 2: Main Agent 加载协调技能
+
+```bash
+# Main Agent 启动时加载
+/skill architect-role
+```
+
+### 步骤 3: 工作流脚本
+
+创建 `.claude/workflows/` 目录：
+
+```javascript
+// workflows/feature-development.js
+export default {
+  name: "feature-development",
+  run: async (feature) => {
+    // 1. 分析
+    const plan = await分析需求(feature)
+    
+    // 2. 指派执行
+    const result = await Agent({
+      subagent_type: "executor",
+      prompt: plan.executorTask
+    })
+    
+    // 3. 审查
+    const review = await Agent({
+      subagent_type: "reviewer",
+      prompt: `审查: ${result.files}`
+    })
+    
+    // 4. 整合
+    return 整合结果(result, review)
+  }
+}
+```
+
+## 命名规范
+
+- Main Agent: `main` 或 `planner`
+- Sub Agent: `executor`, `reviewer`, 或具体任务名
+- Agent ID: 自动生成，格式 `a_<random>`
+
+## 调试和监控
+
+### 查看 Sub Agent 状态
+
+```bash
+# 列出当前运行的所有 Agent
+/agents
+
+# 查看 Sub Agent 输出
+Agent({ subagent_type: "executor", prompt: "..." })
+// 返回 agentId，可以用 TaskOutput 查看输出
+```
+
+### Sub Agent 输出结构
+
+```javascript
+{
+  "agentId": "a_123abc",
+  "status": "completed",
+  "result": {
+    "files": ["src/auth.ts"],
+    "tests": "12/12 通过"
+  }
+}
+```
+
+## 局限性
+
+1. **Sub Agent 无法主动通信**：只能通过返回值
+2. **无持久化 Blackboard**：需要用文件共享状态
+3. **Agent 数量限制**：系统限制最大并发数
+
+## 最佳实践
+
+1. **明确任务边界**：每个 Sub Agent 职责单一
+2. **结构化返回**：使用 JSON 格式返回结果
+3. **文件作为状态**：用文件存储中间状态
+4. **Main 协调一切**：Sub Agent 只执行任务
+
+## 相关文档
+
+- [Agent 工具文档](https://docs.anthropic.com/claude-code/agent)
+- [设计文档](./design/04-design-v0.4.md)
+- [示例工作流](./05-example-workflows.md)