# #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 待确认事项

无。本方案为完整设计方案，待司马懿评审后决定下一步。