sanguo/sanguo_moziplus_v2
8
0
Fork 0
Code Issues Pull Requests 2 Actions Packages Projects Releases Wiki Activity

auto-sync: 2026-05-29 00:47:23

Browse Source
This commit is contained in:
cfdaily
2026-05-29 00:47:23 +08:00
parent 3aa4acf2f9
commit 1a2e409abd
1 changed files with 374 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/design/01-four-phase-loop.md
+374
View File
@@ -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 待确认事项
无。本方案为完整设计方案，待司马懿评审后决定下一步。