diff --git a/docs/design/06-design-v0.5-dynamic-orchestration.md b/docs/design/06-design-v0.5-dynamic-orchestration.md index 059cbc6..837f0f2 100644 --- a/docs/design/06-design-v0.5-dynamic-orchestration.md +++ b/docs/design/06-design-v0.5-dynamic-orchestration.md @@ -23,7 +23,8 @@ | 变更项 | v0.4 | v0.5 | 原因 | |--------|------|------|------| | **编排方式** | SendMessage 跨实例 | **Agent 工具动态编排** | 更灵活的协作 | -| **Main 角色** | 架构师 (Plan + Review) | **编排者 + 验收整合** | 专注于编排 | +| **Main 角色** | 架构师 (Plan + Review) | **需求讨论 + 编排 + 验收整合** | 承担需求讨论职责 | +| **需求讨论** | 无明确机制 | **deep-interview skill** | 系统化需求提取 | | **Sub Agent 角色** | backend/frontend 执行 | **Execute/Review/Test 专业角色** | 更细的分工 | | **工作流** | 固化流程 | **Main 根据需求动态安排** | 更灵活 | @@ -40,13 +41,17 @@ │ Main Agent (编排者) │ │ │ │ 职责: │ +│ • 与用户讨论需求 (deep-interview skill) │ +│ • 分析任务复杂度和范围 │ │ • 根据任务需要分析和决策 │ │ • 动态安排 Sub Agents │ │ • 不是固化流程，而是灵活调整 │ │ • 最终验收和整合 │ │ │ │ 能力 (依托 Superpowers): │ -│ • planning (如需要) │ +│ • deep-interview — 需求讨论和知识提取 │ +│ • planning — 复杂任务的方案规划 │ +│ • CODE-REVIEW — 代码审查验证 │ │ • 其他 100+ Superpowers skills │ │ • Agent 工具编排 │ └─────────────────────────────────────────────────────────────────┘ @@ -79,7 +84,9 @@ ``` 用户: "修复这个 bug" ↓ -Main Agent: 分析后决定 +Main Agent: 快速确认需求 (AskUserQuestion) + ↓ +分析后决定 ↓ 安排 Execute Sub Agent (修复) ↓ @@ -91,7 +98,9 @@ Main Agent: 分析后决定 ``` 用户: "实现用户登录功能" ↓ -Main Agent: 分析后决定 +Main Agent: 使用 deep-interview 讨论需求 + ↓ +分析后决定 ↓ 安排 Execute Sub Agent (实现) ↓ @@ -105,7 +114,9 @@ Main Agent: 分析后决定 ``` 用户: "实现完整的用户认证系统" ↓ -Main Agent: 使用 planning skill 分析 +Main Agent: 使用 deep-interview 深度讨论需求 + ↓ +使用 planning skill 分析和规划 ↓ 安排 Execute Sub Agent (后端实现) 安排 Execute Sub Agent (前端实现) @@ -123,7 +134,9 @@ Main Agent: 使用 planning skill 分析 ``` 用户: "登录接口有问题" ↓ -Main Agent: 分析后决定 +Main Agent: 询问问题详情 (AskUserQuestion) + ↓ +分析后决定 ↓ 安排 debugger Sub Agent (定位问题) ↓ @@ -136,11 +149,13 @@ Main Agent: 分析后决定 ### 2.3 关键特性 -1. **动态编排**: Main 根据任务需要决定安排哪些 Sub Agents -2. **专业分工**: Sub Agents 有明确的专业角色 -3. **上下文隔离**: 每个 Sub Agent 只能看到必要信息 -4. **共享能力**: 所有 Agent 都遵循 Superpowers 工作方式 -5. **灵活调整**: 不是固化流程，Main 可以根据情况调整 +1. **需求讨论**: Main Agent 使用 `deep-interview` skill 与用户讨论需求，确保理解正确 +2. **动态编排**: Main 根据任务需要决定安排哪些 Sub Agents +3. **专业分工**: Sub Agents 有明确的专业角色 +4. **上下文隔离**: 每个 Sub Agent 只能看到必要信息 +5. **共享能力**: 所有 Agent 都遵循 Superpowers 工作方式 +6. **灵活调整**: 不是固化流程，Main 可以根据情况调整 +7. **验证整合**: Main Agent 负责 CODE-REVIEW 验收和最终整合 --- @@ -149,13 +164,17 @@ Main Agent: 分析后决定 ### 3.1 Main Agent (编排者) **职责**: -- 分析任务需求 +- **与用户讨论需求** — 使用 `deep-interview` skill 进行系统化需求提取 +- 分析任务需求 — 确定任务复杂度和范围 - 根据需要决定安排哪些 Sub Agents - 协调 Sub Agents 之间的协作 -- 最终验收和整合 +- **验证整合** — 使用 `CODE-REVIEW` skill 进行代码审查验收 +- 最终整合和提交 **能力 (依托 Superpowers)**: +- `deep-interview` — **需求讨论和知识提取** (核心能力) - `planning` — 复杂任务的方案规划 +- `CODE-REVIEW` — 代码审查验收 - `debugger` — 问题诊断 - 其他 100+ Superpowers skills @@ -165,13 +184,28 @@ Main Agent: 分析后决定 **工作方式**: ``` -1. 接收任务 -2. 分析任务需要什么 -3. 决定安排哪些 Sub Agents -4. 协调执行 -5. 验收整合 +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 (执行者) **职责**: @@ -266,6 +300,18 @@ Main Agent └─────────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────────┐ +│ 0. Main Agent: 需求讨论 (deep-interview) │ +│ │ +│ 使用 AskUserQuestion 提问: │ +│ • 需要支持哪些认证方式? (JWT/OAuth/Session) │ +│ • 需要哪些端点? (登录/注册/刷新/登出) │ +│ • 有什么安全要求? (加密/2FA/限流) │ +│ • 前端需要什么功能? (表单/状态管理) │ +│ │ +│ 记录答案到 requirements/requirements.md │ +└─────────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────────┐ │ Main Agent 分析决策 │ │ │ │ 这是一个复杂任务，需要: │ @@ -273,7 +319,7 @@ Main Agent │ 2. 安排 Execute Sub Agents 实现 │ │ 3. 安排 Review Sub Agent 审查 │ │ 4. 安排 Test Sub Agent 测试 │ -│ 5. 验收整合 │ +│ 5. 验收整合 (CODE-REVIEW) │ └─────────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────────┐ @@ -357,12 +403,20 @@ Main Agent └─────────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────────┐ -│ 5. Main Agent: 验收整合 │ +│ 5. Main Agent: 验收整合 (CODE-REVIEW) │ +│ │ +│ 使用 CODE-REVIEW skill 进行验收: │ +│ • 检查逻辑正确性和边界情况 │ +│ • 安全漏洞检查 (JWT、密码处理) │ +│ • 性能影响评估 │ +│ • 测试覆盖率和质量 │ +│ • 错误处理验证 │ │ │ │ 收集结果: │ │ • Execute 结果: 后端 API + 前端页面 │ │ • Review 结果: 代码通过审查 │ │ • Test 结果: 测试全部通过 │ +│ • CODE-REVIEW 结果: 验收通过 │ │ │ │ 整合并提交 Git │ └─────────────────────────────────────────────────────────────┘ @@ -376,13 +430,24 @@ Main Agent └─────────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────────┐ +│ 0. Main Agent: 快速确认需求 (AskUserQuestion) │ +│ │ +│ 使用 AskUserQuestion 提问: │ +│ • 具体的错误信息是什么? │ +│ • 在什么情况下发生? (操作步骤/环境) │ +│ • 有错误日志吗? │ +│ │ +│ 快速确认问题范围 │ +└─────────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────────┐ │ Main Agent 分析决策 │ │ │ -│ 这是一个简单任务，不需要规划: │ +│ 这是一个简单任务，不需要规划和深度访谈: │ │ 1. 安排 debugger Sub Agent 定位问题 │ │ 2. 安排 Execute Sub Agent 修复 │ │ 3. 安排 Test Sub Agent 验证 │ -│ 4. 验收整合 │ +│ 4. 验收整合 (CODE-REVIEW) │ └─────────────────────────────────────────────────────────────┘ ↓ Main Agent 直接安排 Sub Agents... @@ -397,6 +462,10 @@ Main Agent 直接安排 Sub Agents... ### 6.1 Main Agent 使用 Superpowers ```javascript +// 需求讨论 - 使用 deep-interview +const requirements = await /deep-interview "用户认证系统需求" +// 记录到 requirements/requirements.md + // 复杂任务，先规划 const plan = await /plan "设计用户认证系统" @@ -404,6 +473,16 @@ const plan = await /plan "设计用户认证系统" // ... ``` +### 6.2 Main Agent 验收整合使用 Superpowers + +```javascript +// 使用 CODE-REVIEW skill 进行验收 +const review = await /code-review "审查用户认证代码" +// 检查逻辑正确性、安全、性能、测试覆盖率 + +// 整合结果并提交 Git +``` + ### 6.2 Sub Agent 使用 Superpowers ```javascript @@ -433,8 +512,10 @@ Agent({ ``` Main Agent │ - ├─ planning skill - ├─ debugger skill + ├─ deep-interview — 需求讨论和知识提取 + ├─ planning — 复杂任务规划 + ├─ CODE-REVIEW — 代码审查验收 + ├─ debugger — 问题诊断 ├─ ... (其他 Superpowers) └─ Agent 工具编排 @@ -449,12 +530,13 @@ Sub Agents Superpowers Skills │ - ├─ planning - ├─ CODE-REVIEW - ├─ test-engineer - ├─ backend-dev - ├─ frontend-dev - ├─ debugger + ├─ deep-interview — 需求讨论 (Main 核心能力) + ├─ planning — 任务规划 + ├─ CODE-REVIEW — 代码审查 (Main 验收能力) + ├─ test-engineer — 测试工程 + ├─ backend-dev — 后端开发 + ├─ frontend-dev — 前端开发 + ├─ debugger — 问题调试 ├─ ... (100+ skills) ``` @@ -467,6 +549,13 @@ Superpowers Skills ```javascript // 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) // 根据分析结果决定编排策略 @@ -474,25 +563,38 @@ async function orchestrate(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}` }) + 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 + // 复杂任务: 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}` }) - return await integrate(plan, execute, review, test) + 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 并行编排 @@ -543,14 +645,57 @@ if (review.passed) { ## 角色 -你是任务编排者，负责根据任务需要动态安排 Sub Agents。 +你是任务编排者，负责与用户讨论需求、动态安排 Sub Agents、验收整合。 ## 核心职责 -1. 分析任务需求 -2. 根据需要决定安排哪些 Sub Agents -3. 协调 Sub Agents 之间的协作 -4. 最终验收和整合 +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 前 + +**如何使用**: +```javascript +// 代码审查验收 +Skill({ skill: "code-review-skill", args: "文件路径" }) + +// CODE-REVIEW 会检查: +// • 逻辑正确性和边界情况 +// • 安全漏洞 +// • 性能影响 +// • 测试覆盖率 +// • 错误处理 +``` ## Sub Agent 类型 @@ -576,22 +721,22 @@ if (review.passed) { ### 简单任务 ``` -分析 → 安排 Execute → 验收整合 +接收任务 → 快速确认 (AskUserQuestion) → 安排 Execute → 验收整合 → 汇报 ``` ### 中等任务 ``` -分析 → 安排 Execute → 安排 Review → 验收整合 +接收任务 → 需求讨论 (deep-interview) → 安排 Execute → 安排 Review → 验收整合 → 汇报 ``` ### 复杂任务 ``` -分析 → planning → 安排 Execute → 安排 Review → 安排 Test → 验收整合 +接收任务 → 需求讨论 (deep-interview) → planning → 安排 Execute → 安排 Review → 安排 Test → 验收整合 → 汇报 ``` ### 调试任务 ``` -分析 → 安排 debugger → 安排 Execute (修复) → 安排 Test (验证) → 验收整合 +接收任务 → 询问详情 (AskUserQuestion) → 安排 debugger → 安排 Execute → 安排 Test → 验收整合 → 汇报 ``` ## 严格限制 @@ -601,8 +746,10 @@ if (review.passed) { ## 可用能力 (Superpowers) -- planning — 复杂任务的方案规划 -- debugger — 问题诊断 +- **deep-interview** — 需求讨论和知识提取 (核心能力) +- **planning** — 复杂任务的方案规划 +- **CODE-REVIEW** — 代码审查验收 (核心能力) +- **debugger** — 问题诊断 - 其他 100+ Superpowers skills - Agent 工具编排 @@ -637,10 +784,19 @@ Agent({ ## 决策框架 在安排 Sub Agents 之前问自己: -1. 这个任务需要哪些 Sub Agents? -2. 需要 planning 吗? -3. Sub Agents 之间有依赖关系吗? -4. 可以并行执行吗? +1. 需求是否清晰? 不清晰 → 使用 deep-interview +2. 这个任务需要哪些 Sub Agents? +3. 需要 planning 吗? +4. Sub Agents 之间有依赖关系吗? +5. 可以并行执行吗? + +## 验收框架 + +在向用户汇报之前: +1. 使用 CODE-REVIEW 验证代码质量 +2. 确认所有测试通过 +3. 整合所有结果 +4. 准备清晰的汇报 ``` --- @@ -846,27 +1002,48 @@ Workflow({ ### v0.5 设计精髓 1. **Main Agent 是编排者**: 根据任务需要动态安排 Sub Agents -2. **不是固化流程**: Main 根据需求灵活调整 -3. **专业分工**: Sub Agents 有明确的专业角色 -4. **上下文隔离**: 每个 Sub Agent 只能看到必要信息 -5. **共享能力**: 所有 Agent 都遵循 Superpowers 工作方式 +2. **需求讨论职责**: Main Agent 使用 `deep-interview` skill 与用户讨论需求 +3. **验收整合职责**: Main Agent 使用 `CODE-REVIEW` skill 进行代码审查验收 +4. **不是固化流程**: Main 根据需求灵活调整 +5. **专业分工**: Sub Agents 有明确的专业角色 +6. **上下文隔离**: 每个 Sub Agent 只能看到必要信息 +7. **共享能力**: 所有 Agent 都遵循 Superpowers 工作方式 + +### Main Agent 的核心能力 + +| 能力 | Superpowers Skill | 用途 | +|------|------------------|------| +| **需求讨论** | `deep-interview` | 与用户系统化讨论需求，ASK->LISTEN->WRITE->DEEPEN->REPEAT | +| **任务规划** | `planning` | 复杂任务的方案规划 | +| **代码审查** | `CODE-REVIEW` | 验收代码质量、安全、性能 | +| **问题诊断** | `debugger` | 定位和诊断问题 | +| **编排能力** | Agent 工具 | 动态安排 Sub Agents | ### 与 v0.4 的区别 | v0.4 | v0.5 | |------|------| -| 架构师 Plan + Review | Main 编排 + 验收 | +| 架构师 Plan + Review | Main **需求讨论 + 编排 + 验收** | +| 无明确需求讨论机制 | **deep-interview skill** | | backend/frontend 执行 | Execute/Review/Test 专业角色 | +| 无明确验收机制 | **CODE-REVIEW skill** | | 固化工作流 | **Main 根据需求动态安排** | | SendMessage 跨实例 | Agent 工具 | ### 关键变化 -**v0.5 更灵活**: +**v0.5 更完整**: +- Main 承担**需求讨论**职责 (deep-interview) +- Main 承担**验收整合**职责 (CODE-REVIEW) - Main 不是固化的 Plan/Review 角色 - Sub Agents 有更细的专业分工 - 工作流不是固化的，Main 根据任务需要安排 +**v0.5 的三个核心变化**: +1. **需求讨论** — Main Agent 使用 `deep-interview` skill 与用户讨论需求 +2. **验收整合** — Main Agent 使用 `CODE-REVIEW` skill 进行代码审查验收 +3. **动态编排** — Main Agent 根据任务需要灵活安排 Sub Agents + --- **文档版本**: v0.5