diff --git a/.claude/workflows/feature-development.js b/.claude/workflows/feature-development.js new file mode 100644 index 0000000..d30404d --- /dev/null +++ b/.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) +} diff --git a/docs/design/05-migration-to-sub-agent.md b/docs/design/05-migration-to-sub-agent.md new file mode 100644 index 0000000..e86af2f --- /dev/null +++ b/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) diff --git a/docs/design/06-design-v0.5-dynamic-orchestration.md b/docs/design/06-design-v0.5-dynamic-orchestration.md new file mode 100644 index 0000000..059cbc6 --- /dev/null +++ b/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 +**实施状态**: 设计阶段 diff --git a/docs/sub-agent-orchestration.md b/docs/sub-agent-orchestration.md new file mode 100644 index 0000000..e34ab10 --- /dev/null +++ b/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_` + +## 调试和监控 + +### 查看 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)