diff --git a/docs/design/01-four-phase-loop.md b/docs/design/01-four-phase-loop.md index 2326d39..fbe5079 100644 --- a/docs/design/01-four-phase-loop.md +++ b/docs/design/01-four-phase-loop.md @@ -2,7 +2,7 @@ **序号**: #01 **名称**: 四相循环 — PRD Phase 1~4 完整实现方案 -**版本**: v1.0 +**版本**: v1.1(附录扩展:完整讨论过程记录) **基于**: PRD-v3.0 §4 四相架构 + architecture-v3.0.md **作者**: 庞统(副军师)🐦 **日期**: 2026-05-29 @@ -324,51 +324,163 @@ AGENTS.md 中的角色从"质量总监:代码评审、多空辩论、最终验 --- -## 附录 A:讨论过程记忆 -### A.1 讨论背景 +## 附录 A:完整讨论过程记忆(2026-05-28 ~ 05-29) -基于 PRD-v3.0 四相架构(需求探索→动态规划→自主执行→主动汇报),讨论如何将 PRD 的设计落地到实际代码中。 +### A.1 讨论起因 -### A.2 关键讨论节点 +2026-05-28,基于 architecture-v3.0.md v3.0.1 完成的背景,启动 T2(持续指挥 + 动态规划)的调研和设计。目标是补齐 PRD-v3.0 四相架构中未实现的 Phase 2(动态规划)和 Phase 3(持续指挥)。 -1. **B8/B9 确认移除**:经代码验证,BUG-7(planning 暂停失败)和 BUG-8(cancel→resume 空图完成)是 v1.0 (mozi) 的 bug,moziplus v2.0 没有 `planning` 状态和 `execute_graph`,从 T2 中移除。 +### A.2 阶段一:T2 前置清理(2026-05-28) -2. **持续指挥 vs 庞统 native**:初始方案是"庞统全程在场持续指挥",用户指出风险——"搞不好就是庞统 native"。改为:**Agent 在黑板上讨论涌现**,庞统通过 @mention 回答问题和一轮结束时 review 来参与,不是独裁者而是引导者。 +**#1 B8/B9 确认移除**:庞统验证代码发现,BUG-7(planning 暂停失败)和 BUG-8(cancel→resume 空图完成)是 v1.0 (mozi) 的 bug。moziplus v2.0 没有 `planning` 状态(v2 状态机 11 个状态不含 planning)和 `execute_graph` 函数(执行模型完全不同)。结论:从 T2 遗留问题清单中移除。 -3. **"一轮"定义**:确认方案 A——parent task 下所有 sub task 均为终态(done/failed/cancelled)。 +**#2 architecture-v3.0.md 升级至 v3.0.1**:新增 4 个设计方向章节(§6.5 广播认领、§10.4~10.6)和 §21 T 阶段规划(T1~T8),为后续迭代建立路线图。 -4. **司马懿角色扩展**:从"代码评审"扩展为"全维度质量把控"(需求覆盖、设计一致性、代码质量、方向一致性、产出物验证)。用户强调"质量包括更广义的范围"。 +**#3 司马懿评审通过**(Mail #1779979934362, #1779980383850, #1779981185745):修复广播认领状态矛盾、BUG-22/25/26 确认、采纳 5 条建议改进。 -5. **司马懿 review skill 设计方式**:用户要求"基于优秀实践",不要庞统拍脑袋设计。调研了 quality-gate-patterns、GSD、moziplus-agent-lifecycle 等实践,整理成参考材料供司马懿自行设计。 +**#4 AGENTS.md 更新**:补充 request vs inform 判断标准——"对方收到后是否需要回复/确认/采取行动?需要→request,不需要→inform"。 -6. **讨论时机灵活化**:用户强调"讨论是随时灵活的,哪怕任务执行过程中也可以随时讨论,不要僵化"。Phase 2 和 Phase 3 的讨论不硬分,黑板讨论贯穿全程。 +### A.3 阶段二:持续指挥与动态规划调研(2026-05-28 ~ 05-29) -7. **用户不参与触发**:确认 PRD B4 原则——AI 能决定就 AI 决定,人只在安全红线和最终验收时介入。当前 `guardrails.yaml` 已实现 6 条红线。 +庞统三路调研(NAS 知识库 → 代码 → 优秀实践): -8. **T 阶段不是目标**:用户明确"别被 T2 限制,T2 不是目标,PRD 才是"。四相循环一起实现,不按 T 阶段拆分。 +**#5 NAS 知识库搜索**:搜索 wiki-vault/practices/ 中关于"持续指挥"和"动态规划"的内容,找到 get-shit-done、claude-code、hermes、multi-agent-collaboration 等相关实践文件。 -9. **评审机制强调**:用户要求庞统和司马懿可以 rebuttal,"我需要更优的方案,不是谁服从谁"。 +**#6 代码实现程度调研**: +- `ticker.py`(960 行):30s tick 只做 4 件事——超时检测、僵尸回收、pending 任务派发、review 匹配 +- `dispatcher.py`(653 行):spawn Agent 执行,无黑板讨论环节 +- `router.py`(195 行):LLMDriver 路由(v3.0-router-refactor 计划改为广播认领) +- 庞统 spawn 时机:只在 Router 模糊路由时被 delegate spawn,每次新建隔离 session,无上下文延续 +- 结论:当前只有 Phase 3 的后半段,缺失 Phase 2(讨论涌现)和完整闭环 -### A.3 优秀实践引用 +**#7 优秀实践调研**(8 个来源,详见 A.5 引用表): +- get-shit-done:Wave Execution、Scope Reduction Detection、决策覆盖门禁 +- claude-code:四级权限(default/auto/bypass/yolo)、Dream 记忆系统 +- hermes:幻觉门控、心跳+reclaim +- oh-my-codex:Autonomy Directive(自主指令) +- moziplus-agent-lifecycle:Auftragstaktik 任务式指挥、Boids 群体智能、元认知自评 +- quality-gate-patterns:三阶段评估门控、反合理化表、约束分级 +- supervision-practices:分层审批策略 +- multi-agent-collaboration-patterns:4 种编排模式 × 3 种通信协议 -| 来源 | 关键实践 | 引用位置 | -|------|---------|---------| -| oh-my-codex | Autonomy Directive | §3.3 Spawn Prompt | +### A.4 阶段三:初始设计方向讨论(2026-05-29) + +庞统提出初始方案:Iterative Execution Loop(迭代执行环)—— Daemon 检测一轮结束 → 自动 spawn 庞统 review → 庞统自主决定调整方案 → 司马懿质量门控(计划放 T4)。 + +用户提出四个关键问题: + +**#8 "一轮"定义**:用户倾向方案 A——parent 下所有 sub task 均为终态。确认采纳。 + +**#9 司马懿角色不是代码评审**:用户明确"司马懿角色不是代码评审,是质量把控,这个质量是需要包括更广义的范围的,比如需求、代码设计一致性,不能仅仅局限在代码评审"。司马懿应该有多种 review skill,不同类型的评审用不同类型的 skill。 + +**#10 庞统 review 调整能力**:用户问"这块也可以参考更多优秀实践吧?给庞统明确的指导,但是不是限制,和司马懿一样,他可以有很多 skill 来应对不同的任务 review"。庞统调研后给出 6 种调整能力(创建新任务、拆分、标记偏离、调整优先级、修改 goal、终止),每种都有优秀实践来源。 + +**#11 用户不参与触发**:用户问"肯定不是用户参与,以前设计过,如果 AI 能决定,就不要让用户参与,用户的角色已经定义过了"。庞统确认 PRD B4 已定义——安全红线(guardrails.yaml 6 条)才拉人,其余 AI 自主。代码已实现。 + +### A.5 阶段四:关键转折——黑板讨论涌现(2026-05-29) + +**#12 "庞统 native"风险**:用户指出初始方案"庞统苏格拉底对话 → 明确 goal + 创建 parent task + 初始 sub tasks"中,"这个度在哪里,搞不好就是庞统 native 了"。如果庞统既定 goal 又规划任务,和 v1.0 的确定性编排有什么区别? + +**#13 黑板讨论涌现**:用户提出核心思路——"能否这样,让 AI 之间也进行沟通,庞统和用户明确 goal 和初始需求,然后大家可以进行黑板探讨啊,有 comments 和 @ 功能啊,大家探讨的过程其实也在黑板上留痕了,最终都拉齐后,Agent 创建子任务到黑板上,这个时候如果不确定任务是否正确,也可以 @ 庞统进行目标对齐,这样黑板的作用就发挥出来了"。 + +**#14 庞统无形对齐**:用户指出"庞统其实在讨论的过程中也就无形地把目标对齐了"——不需要庞统主动规划一切,而是在 Agent 讨论过程中通过回答 @ 问题自然对齐方向。 + +庞统搜了 PRD-v3.0 和 architecture-v2.6,确认: +- PRD Phase 3 已有完整的共享意识空间设计(每个 Agent 随时读全局状态、写状态、感知变化、主动发起协作) +- architecture-v2.6 已有黑板讨论示例和 @mention API + comment_type 8 种类型 +- 但代码里这些基础设施虽已实现,Agent 仍未主动使用 + +### A.6 阶段五:最终纠偏(2026-05-29) + +用户提出三个决定性纠正: + +**#15 司马懿 review 时机不变**:"司马懿质量门控发生在每个 Agent 完成自己任务之后,必须要找司马懿 review 才能算是完成,这个设计不要变。" + +**#16 Skill 基于优秀实践**:"司马懿和庞统的 review 的 skill 我不要你设计,我要优秀实践基础上。"庞统改为整理调研结果供司马懿参考,让司马懿自行设计。 + +**#17 讨论随时灵活**:"讨论是随时,哪怕任务执行过程中,也可以随时讨论,不要僵化,尽量灵活,这个 prompt 看看是否有优秀实践可以参考。" + +**#18 T 阶段不是目标**:"别被 T2 限制,T2 不是目标,PRD 才是。" + +**#19 一起做完**:"我不同意一个事情放到不同的 T 阶段实现,要做就一起做完。" + +**#20 评审 rebuttal**:"做完发给司马懿评审,我们再考虑下一步,注意,你们可以 rebuttal,我需要更优的方案,不是谁服从谁。" + +### A.7 关键设计决策溯源 + +| 方案中的决策 | 触发讨论 | 最终结论 | +|-------------|---------|---------| +| Agent 自主讨论涌现(§2 Phase 2) | #12 庞统 native 风险 → #13 用户提出黑板讨论 | Agent 在黑板讨论 → 自主创建任务 | +| 庞统通过 @mention 参与(§2) | #14 庞统无形对齐 | 不全程在场,但关键节点通过 @ 响应 | +| 一轮 = 所有 sub 终态(§2.1) | #8 用户倾向方案 A | 方案 A,简洁可靠 | +| 司马懿每个 sub 完成后 review(§5.1) | #15 用户纠正 | 不变,已有机制 | +| 司马懿全维度质量把控(§5.2) | #9 用户扩展角色 | 需求/设计/代码/方向/产出物 5 维度 | +| Skill 基于优秀实践(§5.2) | #16 用户要求 | 整理调研结果供司马懿自行设计 | +| 讨论 Phase 2+3 贯穿(§2.1) | #17 用户灵活化 | 不僵化分阶段,随时讨论 | +| 四相循环一起实现(§1.3) | #18 #19 用户纠正 | 不按 T 阶段拆分 | +| Spawn prompt 用实践指导(§3) | #17 用户问 prompt 实践 | Autonomy Directive + Auftragstaktik + Boids | +| Rebuttal 机制(§8) | #20 用户要求 | 庞统和司马懿可以互相 challenge | + +### A.8 优秀实践引用索引 + +| 来源 | 关键实践 | 方案引用位置 | +|------|---------|-------------| +| oh-my-codex | Autonomy Directive(自主指令) | §3.3 Spawn Prompt | +| oh-my-codex | 需求清晰度量化评分 | §3.1 设计理念 | | 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 | +| moziplus-agent-lifecycle | Agent 崩溃自动恢复 | §8 风险参考 | +| moziplus-agent-lifecycle | 成本追踪 Token 自报 | §8 风险参考 | | 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 | +| quality-gate-patterns | 门控记录与追溯 | §9 验证 | +| get-shit-done | Scope Reduction Detection | §4.3, §5.2 | +| get-shit-done | 决策覆盖门禁 | §5.2 | +| get-shit-done | Nyquist 验证层 | §9 验证 | +| get-shit-done | 上下文工程(Context Rot) | §8 风险 | +| hermes | 幻觉门控(产出物验证) | §5.2 | +| hermes | 心跳+reclaim+僵尸检测 | §8 风险 | +| claude-code | 四级权限体系 | §7 安全红线 | +| claude-code | Dream 记忆整合系统 | §4 长期参考 | +| supervision-practices | 分层审批策略 | §7 安全红线 | +| multi-agent-collaboration | 4 种编排 × 3 种通信协议 | §2 模型 | +| open-multi-agent | Goal→DAG 动态图构建 | §4.3 调整能力 | +| TradingAgents | 动态图构建 | §4.3 调整能力 | | PRD-v3.0 | B4 人退到边缘 | §2.2 | -| PRD-v3.0 | 四相架构 | §2 | +| PRD-v3.0 | 四相架构(§4) | §2 | +| PRD-v3.0 | Phase 3 共享意识空间 | §2, §3 | | architecture-v2.6 | 黑板讨论示例 | §3.3 | +| architecture-v2.6 | @mention API + comment_type | §3.4 | +| v3.0-router-refactor | 广播认领 + 确定性交接 | §2 模型 | +| guardrails.yaml | 6 条安全红线 | §7 | -### A.4 待确认事项 +### A.9 调研文件清单 + +| 调研对象 | 路径 | +|---------|------| +| PRD v3.0 | `docs/PRD-v3.0.md` | +| architecture v3.0.1 | `docs/design/architecture-v3.0.md` | +| architecture v2.6(archive) | `docs/design/archive-2.0/architecture-v2.6.md` | +| v3.0 router refactor | `docs/design/archive-2.0/v3.0-router-refactor.md` | +| topic7 交互设计 | `docs/design/archive-2.0/topic7-interaction-dashboard-proposal.md` | +| ticker.py | `src/daemon/ticker.py`(960 行) | +| dispatcher.py | `src/daemon/dispatcher.py`(653 行) | +| router.py | `src/daemon/router.py`(195 行) | +| blackboard_routes.py | `src/api/blackboard_routes.py` | +| guardrails.yaml | `config/guardrails.yaml` | +| GSD practices | `wiki-vault/practices/get-shit-done-practices.md` | +| quality-gate practices | `wiki-vault/practices/quality-gate-patterns.md` | +| oh-my-codex practices | `wiki-vault/practices/oh-my-codex-practices.md` | +| agent lifecycle practices | `wiki-vault/practices/moziplus-agent-lifecycle-practices.md` | +| multi-agent collaboration | `wiki-vault/practices/multi-agent-collaboration-patterns.md` | +| claude-code insights | `wiki-vault/practices/claude-code-architecture-insights.md` | +| supervision practices | `wiki-vault/practices/supervision-practices.md` | +| skill engineering practices | `wiki-vault/practices/moziplus-skill-engineering-practices.md` | + +### A.10 待确认事项 无。本方案为完整设计方案,待司马懿评审后决定下一步。