From 1a2e409abd9464e98ec9a1dbe19887e9b0368a4e Mon Sep 17 00:00:00 2001 From: cfdaily Date: Fri, 29 May 2026 00:47:23 +0800 Subject: [PATCH] auto-sync: 2026-05-29 00:47:23 --- docs/design/01-four-phase-loop.md | 374 ++++++++++++++++++++++++++++++ 1 file changed, 374 insertions(+) create mode 100644 docs/design/01-four-phase-loop.md diff --git a/docs/design/01-four-phase-loop.md b/docs/design/01-four-phase-loop.md new file mode 100644 index 0000000..2326d39 --- /dev/null +++ b/docs/design/01-four-phase-loop.md @@ -0,0 +1,374 @@ +# #01 四相循环实施方案 + +**序号**: #01 +**名称**: 四相循环 — PRD Phase 1~4 完整实现方案 +**版本**: v1.0 +**基于**: PRD-v3.0 §4 四相架构 + architecture-v3.0.md +**作者**: 庞统（副军师）🐦 +**日期**: 2026-05-29 +**状态**: 待评审 +**评审**: 司马懿 + +--- + +## §1. 背景和问题 + +### 1.1 当前状态 + +moziplus v2.0 已实现： +- Blackboard 黑板（SQLite 14 表） +- Comment + @mention 系统 +- Agent 认领（claim API + CAS） +- Daemon 30s tick 调度循环 +- Guardrail 安全红线 +- SubTask 模型 + Mail Tab + +### 1.2 核心问题 + +PRD-v3.0 定义了四相架构（需求探索 → 动态规划 → 自主执行 → 主动汇报），但当前代码只实现了"Phase 3 的后半段"——Daemon 调度 Agent 执行。缺失： + +1. **Phase 2 的讨论涌现**：Agent 不在黑板上讨论，不自主创建任务，完全依赖 Daemon 调度 +2. **Phase 3 的持续指挥**：庞统不在一轮结束时 review，没有方向校正机制 +3. **司马懿全维度质量门控**：当前只有代码评审 skill，缺少需求覆盖、方向一致性、产出物验证等维度 +4. **Phase 3 的完整闭环**：每个 Agent 完成后过司马懿 review（已实现），但一轮结束后的庞统 review + 动态调整 + 循环未实现 + +### 1.3 设计原则 + +> PRD 是目标，T 阶段不是。不按 T 阶段拆分，四相循环一起实现。 + +--- + +## §2. 核心模型：四相循环 + +``` +Phase 1: 需求探索 + 用户 + 庞统苏格拉底对话 → 明确 goal + 庞统创建 parent task，goal 写入 must_haves + │ + ▼ +Phase 2: 动态规划（讨论涌现） + 庞统把 goal 写到黑板 → spawn 各 Agent 读黑板 + 各 Agent 在黑板上讨论（comment / @mention） + 讨论过程中庞统无形中对齐方向（回答 @ 的问题） + 讨论收敛 → 各 Agent 自主创建 sub task + 不确定时 @ 庞统 进行目标对齐 + │ + ▼ +Phase 3: 自主执行（循环） + ┌─────────────────────────────────────────────┐ + │ │ + │ Daemon tick 派发 pending sub tasks │ + │ 各 Agent 自主执行 │ + │ Agent 完成 → 司马懿 review（已有机制） │ + │ review 通过 → sub task done │ + │ review 不通过 → Agent 修改 → 再 review │ + │ │ + │ 一轮结束（parent 下所有 sub 终态） │ + │ ↓ │ + │ 庞统 review 三问： │ + │ 1. Goal 还清晰吗？ │ + │ 2. 成果物覆盖 goal 了吗？ │ + │ 3. 下一轮需要做什么？ │ + │ ↓ │ + │ 庞统决定： │ + │ - 创建新一轮 sub tasks → 回到执行 │ + │ - goal 达成 → 进入 Phase 4 │ + │ - 方向偏离 → 调整 goal + 新一轮 │ + │ │ + └─────────────────────────────────────────────┘ + │ + ▼ +Phase 4: 主动汇报 + 庞统推送成果物摘要 + 关键发现 + 用户验收 +``` + +### 2.1 关键设计决策 + +| 决策 | 选择 | 理由 | +|------|------|------| +| "一轮"定义 | parent 下所有 sub task 均为终态（done/failed/cancelled） | 方案 A，简洁可靠 | +| 庞统参与方式 | 讨论阶段通过 @mention 回答问题，一轮结束时 spawn review | 不全程在线（OpenClaw 限制），但关键节点在场 | +| Agent 自主度 | Auftragstaktik + Autonomy Directive | 给目标不给步骤，Agent 自主决定怎么协作 | +| 司马懿 review 时机 | 每个 Agent 完成任务后 | 已有机制，不变 | +| 庞统 review 时机 | 一轮结束时 | 检查整体方向，不介入每个 sub task | +| 讨论时机 | 随时，不僵化分阶段 | Phase 2 和 Phase 3 都可以在黑板上讨论 | + +### 2.2 人的参与密度（PRD B4） + +| Phase | 人的参与 | AI 自主 | +|-------|---------|--------| +| Phase 1 | 高（和庞统对话） | 庞统主动提问 | +| Phase 2 | 可选（可旁观讨论） | Agent 自主讨论、创建任务 | +| Phase 3 | 几乎不参与 | 只有安全红线才拉人 | +| Phase 4 | 验收 | AI 主动推送 | + +--- + +## §3. Agent Spawn Prompt 设计 + +### 3.1 设计理念 + +不是"固定步骤"，不是"庞统规划流程"，而是： +1. 告诉 Agent 目标和约束（Auftragstaktik） +2. 告诉 Agent 黑板 API 能力 +3. 告诉 Agent 你是自主的（Autonomy Directive） +4. 告诉 Agent 行为边界（Boids 四条） +5. 让 Agent 自己决定怎么协作和讨论 + +### 3.2 优秀实践来源 + +| 实践 | 来源 | 启示 | +|------|------|------| +| **Autonomy Directive** | oh-my-codex 实践 #12 | Agent 自主执行，遇阻才问 | +| **Auftragstaktik 任务式指挥** | moziplus-agent-lifecycle #4 | Intent→End State→Constraints，不指定步骤 | +| **Boids 群体智能** | moziplus-agent-lifecycle #6 | Separation/Alignment/Cohesion/Boundary | +| **元认知自评** | moziplus-agent-lifecycle #5 | Agent 产出自带 confidence | +| **Agent API 契约自描述** | moziplus-agent-lifecycle #9 | API 返回可操作错误信息 | +| **约束分级**（高/中/低自由） | quality-gate-patterns #2 | 不同场景用不同严格度 | + +### 3.3 Spawn Prompt 框架 + +``` +## 你的任务 + +{goal_snapshot} + +## 约束 + +{constraints} + +## 黑板 API + +你可以随时： +- 读黑板：GET /api/projects/{pid}/tasks/{tid}（含 comments、outputs） +- 写 comment：POST /api/projects/{pid}/tasks/{tid}/comments + body: { "author": "{agent_id}", "body": "内容", "mentions": ["agent_id"] } +- 创建 sub task：POST /api/projects/{pid}/tasks +- 认领任务：POST /api/projects/{pid}/tasks/{tid}/claim + +## 行为准则 + +1. 你是自主的。读黑板、思考、行动，不要等指令。 +2. 不确定时 @pangtong-fujunshi 对齐目标。 +3. 需要协作时 @ 对应 Agent。 +4. 讨论是随时灵活的，执行过程中也可以在黑板上讨论。 +5. 产出写入 output，完成时通知。 + +## 完成标准 + +{success_criteria} +``` + +### 3.4 @mention 通知机制 + +Agent 写 comment 时指定 mentions → Daemon tick 扫描新 comments → spawn 被 @ 的 Agent 读黑板。 + +--- + +## §4. 庞统 Review 机制 + +### 4.1 触发条件 + +Daemon 30s tick 检测：parent task 下所有 sub task 均为终态（done/failed/cancelled）。 + +### 4.2 Review 三问（框架，不是限制） + +庞统被 spawn 后拿到： +- goal_snapshot：原始 goal +- round_outputs：本轮所有 sub task 产出物聚合 +- round_comments：本轮黑板讨论记录 + +庞统自主判断，不限于三问，但三问是核心框架： + +1. **Goal 还清晰吗？** — 是否被静默修改（goal drift） +2. **成果物覆盖 goal 了吗？** — 逐条检查验收标准 +3. **下一轮需要做什么？** — 创建新一轮 sub tasks / 标记完成 / 调整方向 + +### 4.3 调整能力 + +庞统 review 后可执行的操作（不限制，以下是已知操作类型）： + +| 操作 | 说明 | 优秀实践来源 | +|------|------|-------------| +| 创建新 sub tasks | 补充遗漏工作 | open-multi-agent Goal→DAG | +| 拆分过大任务 | 任务太大则拆 | moziplus 实践模板骨架+AI填充 | +| 标记偏离 | 需求被静默丢弃 | GSD Scope Reduction Detection | +| 调整优先级 | 根据执行进展重排 | Hermes `/goal` 持续锁定 | +| 修改 goal | 用户改主意时 | PRD B2 "计划可演进" | +| 终止/重来 | 方向完全偏了 | TradingAgents 动态图构建 | + +--- + +## §5. 司马懿 Review 扩展 + +### 5.1 机制不变 + +每个 Agent 完成任务后 → 司马懿 review → 通过才算 done。这是已有机制，**不变**。 + +### 5.2 质量维度扩展 + +当前只有代码评审，需要扩展到全维度质量把控。司马懿根据优秀实践自行设计 review skill，以下是调研结果供参考： + +#### 可用优秀实践 + +| 实践 | 来源 | 司马懿可用场景 | +|------|------|--------------| +| **三阶段评估门控**（机械→语义→共识） | quality-gate-patterns #1 | 代码用机械+语义，方向一致性用共识 | +| **Scope Reduction Detection** | GSD 实践 #2 | 检查需求是否被静默丢弃 | +| **反合理化表** | quality-gate-patterns #3 | 每个 Skill 内置"常见借口+反驳" | +| **约束分级**（高/中/低自由） | quality-gate-patterns #2 | brainstorming 高自由，部署低自由 | +| **Auftragstaktik 三元组** | moziplus-agent-lifecycle #4 | 检查 Intent→End State→Constraints 是否完整 | +| **元认知自评** | moziplus-agent-lifecycle #5 | Agent 产出自带 confidence，司马懿决定是否升级 | +| **决策覆盖门禁** | GSD 实践 #5 | 讨论中的决策是否落地到产出 | +| **产出物验证** | Hermes 幻觉门控 | 产出物是否真实存在、可验证 | + +#### 建议的 Review 维度 + +| 维度 | 检查内容 | 约束等级 | +|------|---------|---------| +| 需求覆盖 | 产出是否覆盖 task 的 must_haves | 中自由 | +| 设计-代码一致性 | 代码是否和设计文档对齐 | 中自由 | +| 代码质量 | 规范、安全、边界条件（现有） | 低自由 | +| 方向一致性 | 是否偏离 parent goal | 中自由 | +| 产出物真实性 | 文件是否存在、可验证 | 低自由 | + +### 5.3 司马懿角色定义建议 + +AGENTS.md 中的角色从"质量总监：代码评审、多空辩论、最终验收"调整为： + +> **质量总监：全维度质量把控** +> - 需求一致性检查 +> - 设计-代码一致性检查 +> - 代码质量评审 +> - 方向一致性检查 +> - 产出物验证 +> - 不同维度使用不同的 review skill +> - 反合理化：不做"建议优化"，必须说"第X行有问题，应该改为Y，因为Z" + +--- + +## §6. 代码改动清单 + +### 6.1 Daemon 层 + +| 文件 | 改动 | 说明 | +|------|------|------| +| `ticker.py` | 新增 `_check_round_complete()` | 检测 parent 下所有 sub 终态 | +| `ticker.py` | 新增 `_spawn_pangtong_review()` | 一轮结束时 spawn 庞统 review | +| `ticker.py` | 新增 `_process_mentions()` | 扫描新 comments 的 mentions → spawn 被 @ 的 Agent | +| `dispatcher.py` | 扩展 spawn 类型 | 支持 "discussion" spawn（Phase 2）+ "review" spawn（一轮结束） | +| `bootstrap.py` | 扩展上下文构建 | 构建 goal + 一轮成果物聚合 + 讨论 history | +| `spawner.py` | 更新 prompt 模板 | 使用 §3.3 的 spawn prompt 框架 | + +### 6.2 API 层 + +| 文件 | 改动 | 说明 | +|------|------|------| +| `blackboard_routes.py` | 新增成果物聚合端点 | `GET /tasks/{id}/outputs/aggregate` 聚合 parent 下所有 sub 的 outputs | + +### 6.3 Model 层 + +| 文件 | 改动 | 说明 | +|------|------|------| +| `operations.py` | 新增 `get_subtasks_status()` | 批量查询 parent 下所有 sub 状态 | +| `operations.py` | 新增 `get_mentioned_agents()` | 从 comments 中提取未通知的 mentions | + +### 6.4 Skill 层 + +| 位置 | 内容 | 说明 | +|------|------|------| +| 司马懿 workspace | review skill 文件 | 司马懿基于 §5.2 优秀实践自行设计 | +| 庞统 bootstrap | review prompt 模板 | 庞统 review 的三问框架 | + +### 6.5 前端（可选，后续） + +| 改动 | 说明 | +|------|------| +| 黑板讨论面板增强 | 实时显示 comments、@mention 高亮 | +| 一轮进度指示 | 显示当前轮次、已完成/总计 sub task | + +--- + +## §7. 安全红线（不变） + +现有 `guardrails.yaml` 的 6 条红线不变。Phase 3 循环中： +- 非红线操作 → AI 自主决策，不拉人 +- 红线触发 → `block_and_notify` / `pause_and_escalate` + +--- + +## §8. 风险和缓解 + +| 风险 | 缓解 | +|------|------| +| Agent 讨论不收敛，无限循环 | 庞统兜底：讨论超过 N 轮未收敛 → 庞统裁决创建任务 | +| 庞统 review 产出质量不稳定 | 司马懿可以 challenge 庞统的 review 结果（rebuttal 机制） | +| @mention 风暴（互相 @ 导致 spawn 爆炸） | Daemon 去重：同一 Agent 在同一 task 的 pending mention 合并为一次 spawn | +| 一轮结束检测延迟（最长 30s） | 可接受，30s tick 是当前设计约束 | +| Agent 创建 sub task 不规范 | 庞统 review 时检查，不合规的 sub task 打回 | + +--- + +## §9. 验证标准 + +| 标准 | 验证方式 | +|------|---------| +| Phase 2 讨论：Agent 能在黑板上写 comment + @mention | E2E：spawn Agent → 检查 comment 写入 | +| Phase 2 涌现：Agent 能自主创建 sub task | E2E：Agent 通过 API 创建 sub task | +| @mention 通知：被 @ 的 Agent 能被 spawn | E2E：写 comment @zhaoyun-data → Daemon spawn 赵云 | +| 一轮结束检测：parent 下所有 sub 终态 → 触发庞统 review | E2E：创建 parent + subs → 完成 subs → 检测庞统 spawn | +| 庞统 review：能创建新一轮 sub tasks 或标记完成 | E2E：庞统 review 后检查新 sub task 创建 | +| 司马懿 review：每个 Agent 完成后必须过 review | 已有机制，回归测试 | +| 安全红线不触发时 AI 全自主 | E2E：正常任务不触发 guardrail | + +--- + +## 附录 A：讨论过程记忆 + +### A.1 讨论背景 + +基于 PRD-v3.0 四相架构（需求探索→动态规划→自主执行→主动汇报），讨论如何将 PRD 的设计落地到实际代码中。 + +### A.2 关键讨论节点 + +1. **B8/B9 确认移除**：经代码验证，BUG-7（planning 暂停失败）和 BUG-8（cancel→resume 空图完成）是 v1.0 (mozi) 的 bug，moziplus v2.0 没有 `planning` 状态和 `execute_graph`，从 T2 中移除。 + +2. **持续指挥 vs 庞统 native**：初始方案是"庞统全程在场持续指挥"，用户指出风险——"搞不好就是庞统 native"。改为：**Agent 在黑板上讨论涌现**，庞统通过 @mention 回答问题和一轮结束时 review 来参与，不是独裁者而是引导者。 + +3. **"一轮"定义**：确认方案 A——parent task 下所有 sub task 均为终态（done/failed/cancelled）。 + +4. **司马懿角色扩展**：从"代码评审"扩展为"全维度质量把控"（需求覆盖、设计一致性、代码质量、方向一致性、产出物验证）。用户强调"质量包括更广义的范围"。 + +5. **司马懿 review skill 设计方式**：用户要求"基于优秀实践"，不要庞统拍脑袋设计。调研了 quality-gate-patterns、GSD、moziplus-agent-lifecycle 等实践，整理成参考材料供司马懿自行设计。 + +6. **讨论时机灵活化**：用户强调"讨论是随时灵活的，哪怕任务执行过程中也可以随时讨论，不要僵化"。Phase 2 和 Phase 3 的讨论不硬分，黑板讨论贯穿全程。 + +7. **用户不参与触发**：确认 PRD B4 原则——AI 能决定就 AI 决定，人只在安全红线和最终验收时介入。当前 `guardrails.yaml` 已实现 6 条红线。 + +8. **T 阶段不是目标**：用户明确"别被 T2 限制，T2 不是目标，PRD 才是"。四相循环一起实现，不按 T 阶段拆分。 + +9. **评审机制强调**：用户要求庞统和司马懿可以 rebuttal，"我需要更优的方案，不是谁服从谁"。 + +### A.3 优秀实践引用 + +| 来源 | 关键实践 | 引用位置 | +|------|---------|---------| +| oh-my-codex | Autonomy Directive | §3.3 Spawn Prompt | +| moziplus-agent-lifecycle | Auftragstaktik 任务式指挥 | §3.1, §4.3 | +| moziplus-agent-lifecycle | Boids 群体智能四条 | §3.3 | +| moziplus-agent-lifecycle | 元认知自评 confidence | §5.2 | +| moziplus-agent-lifecycle | Agent API 契约自描述 | §3.3 | +| quality-gate-patterns | 三阶段评估门控 | §5.2 | +| quality-gate-patterns | 反合理化表 | §5.2 | +| quality-gate-patterns | 约束分级 | §5.2 | +| GSD | Scope Reduction Detection | §4.3, §5.2 | +| GSD | 决策覆盖门禁 | §5.2 | +| Hermes | 幻觉门控（产出物验证） | §5.2 | +| PRD-v3.0 | B4 人退到边缘 | §2.2 | +| PRD-v3.0 | 四相架构 | §2 | +| architecture-v2.6 | 黑板讨论示例 | §3.3 | + +### A.4 待确认事项 + +无。本方案为完整设计方案，待司马懿评审后决定下一步。