# #01 四相循环实施方案

**序号**: #01
**名称**: 四相循环 — PRD Phase 1~4 完整实现方案
**版本**: v1.3（实现完成，待 E2E 验证）
**基于**: PRD-v3.0 §4 四相架构 + architecture-v3.0.md
**作者**: 庞统（副军师）🐦
**日期**: 2026-05-29
**状态**: 实现完成，待 E2E 验证
**评审**: 司马懿

---

## §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. **不重复别人的工作。**动手前先读黑板看谁在做什么（Separation）。
3. **保持方向对齐。**你的产出方向和 parent goal 对齐，不确定时 @pangtong-fujunshi（Alignment）。
4. **产出可共享。**产出写入黑板，让其他人能看到你的成果（Cohesion）。
5. **不越界。**安全红线不要碰，超出能力的 @ 庞统升级（Boundary）。
6. **随时讨论。**执行过程中需要协作时 @ 对应 Agent，讨论是灵活的不是固定阶段的。

## 完成标准

{success_criteria}
```

### 3.4 @mention 通知机制

Agent 写 comment 时指定 mentions → Daemon tick 扫描新 comments → spawn 被 @ 的 Agent 读黑板。

**通知可靠性保障**：

新增 `mention_queue` 表，记录 mentions 的通知状态：
```sql
CREATE TABLE IF NOT EXISTS mention_queue (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    comment_id INTEGER NOT NULL,
    task_id TEXT NOT NULL,
    mentioned_agent TEXT NOT NULL,
    status TEXT NOT NULL DEFAULT 'pending',  -- pending / notified / failed
    retry_count INTEGER NOT NULL DEFAULT 0,
    created_at TEXT NOT NULL DEFAULT (datetime('now')),
    notified_at TEXT,
    FOREIGN KEY (comment_id) REFERENCES comments(id)
);
```

流程：
1. Agent 写 comment 带 mentions → 写入 `mention_queue`（status=pending）
2. Daemon tick 扫描 pending mentions → 尝试 spawn
3. spawn 成功 → status=notified
4. spawn 失败（Agent busy）→ 保持 pending，下次 tick 重试
5. 超过 N 次重试仍失败 → status=failed，记录事件

**备选方案**（更轻量）：走 Inbox JSONL 方式通知，不 spawn，Agent 读 inbox 即可。MVP 阶段先用 tick 扫描 + 重试，后续视性能再升级。

---

## §4. 庞统 Review 机制

### 4.1 触发条件

Daemon 30s tick 检测：parent task 下所有 sub task 均为终态（done/failed/cancelled）。

**终态区分**：

传给庞统的状态摘要包含维度信息：
```json
{ "done": 3, "failed": 1, "cancelled": 0, "total": 4 }
```

庞统 review prompt 中增加指引：
> 有 sub task failed 时，优先判断是应该重试（同一 Agent）、换人（换 Agent）、还是调整方案（修改 goal/约束）。

### 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 "计划可演进" |
### 4.4 一轮结束后的执行顺序

Ticker tick 串行执行，明确顺序避免冲突：
```
1. 超时检测（claimed 超时 → 重置 pending，executing 超时 → failed）
2. 依赖推进（检查 blocker 完成 → 推进状态）
3. 调度 pending（含 review 类型的 task）
4. 一轮结束检测（在调度之后，确保 review 结果已生效）
5. 庞统 review spawn
```

关键：步骤 4 在步骤 3 之后，确保司马懿 review 打回的 sub task 已重新进入 working 状态，不会误触发一轮结束。

### 4.5 防止庞统 review 无限循环

庞统 review 后创建新 sub task → sub 全部 done → 又触发一轮结束 → 又 spawn 庞统 review → 无限循环。

缓解方案：
- parent task 新增 `round_count` 字段，每触发一次庞统 review +1
- round_count 上限（如 5 轮），超过后强制进入 Phase 4 汇报给用户
- 或：庞统 review 后标记 parent 为 `reviewing`，一轮结束检测跳过 `reviewing` 状态的 parent

MVP 阶段用 round_count 上限，简单可靠。

### 4.6 任务状态机完整流转

两层 review（司马懿 + 庞统）在状态机中的完整路径：

```
─── Sub Task（执行 Agent）───

pending → claimed → working
                        │
                        ▼ Agent 完成 + 三信号检查通过
                       review
                        │
                        ▼ 司马懿 review（_dispatch_reviews 确定性路由）
                  ┌── done ──┐
                  │           │
              review 通过   review 不通过 → working（打回重做）
                  │
                  ▼
             （sub task 终态）

─── Parent Task（庞统三问）───

parent 下所有 sub task 终态
        │
        ▼ _check_round_complete 检测
       reviewing（防重复触发）
        │
        ▼ _spawn_pangtong_review
        │
        ├── GOAL_ACHIEVED → done（项目完成）
        ├── 创建新 sub task → working（新一轮执行）
        └── 方向偏离 → 调整 goal + working
```

**关键规则**：

| 规则 | 说明 |
|------|------|
| sub task 终态 = done / failed / cancelled | 司马懿 review 通过 → done；不通过 → 打回 working |
| 司马懿 review 是 sub task 的必经关卡 | 每个 sub task 完成后必须过司马懿，通过才算 done |
| 庞统 review 是 parent task 的关卡 | 一轮结束后庞统三问，决定继续还是完成 |
| 司马懿 spawn 完成后不再触发 _auto_complete | 审查 Agent（司马懿）的 on_complete 回调直接标 done/failed，不走 _task_auto_complete |
| 庞统 spawn 完成后走 _handle_review_conclusion | 解析 GOAL_ACHIEVED 或继续新一轮 |

**为什么审查 Agent 完成后不再触发 _auto_complete**：

`_auto_complete` 的设计意图是检测"执行 Agent 是否真的完成了工作"（三层幻觉门控）。而审查 Agent（司马懿）是被派来 review 的，他的完成意味着 review 本身完成了，不应该再走一遍"检测是否完成 → 标 review → 又派审查 Agent"的循环。

实现方式：`_dispatch_reviews` 在 dispatch 审查 Agent 时，通过 `spawn_full_agent` 的 `on_complete` 回调直接标 done/failed，绕过 `_task_auto_complete`。

---

## §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()` | 扫描 mention_queue → spawn 被 @ 的 Agent | ✅ 已实现 |
| `ticker.py` | 新增 `_build_mention_prompt()` | 构建 @mention 通知 prompt | ✅ 已实现 |
| `ticker.py` | tick 流程明确顺序（§4.4） | 超时→依赖→调度→聚合 parent→一轮结束→mention 通知→写事件→健康检查（8 步） | ✅ 已实现 |
| `dispatcher.py` | 扩展 spawn 类型 | 支持 "discussion" + "review"（spawn_type 参数） | ✅ 已实现 |
| `bootstrap.py` | ~~新增 `build_for_review()`~~ | review 上下文构建已内联在 ticker._build_review_prompt 中 | ✅ 已移除（dead code） |
| `bootstrap.py` | ~~新增 `_format_review_context()`~~ | 同上 | ✅ 已移除（dead code） |
| `spawner.py` | 新增 `DISCUSSION_PROMPT_TEMPLATE` | §3.3 框架 + Boids 四条 + API 契约 | ✅ 已实现 |
| `spawner.py` | 新增 `_build_discussion_prompt()` | discussion 类型 prompt 构建 | ✅ 已实现 |
| `spawner.py` | `build_spawn_message` 新增 `spawn_type` | executor/discussion/review 类型路由 | ✅ 已实现 |
| `models.py` | parent 新增 `round_count` 字段 | 防止无限循环（§4.5） | ✅ 已实现 |

### 6.2 数据库层

| 文件 | 改动 | 说明 | 状态 |
|------|------|------|------|
| `db.py` | `_SCHEMA_STATEMENTS` 加 `round_count` | tasks 表新增轮次字段 | ✅ 已实现 |
| `db.py` | 新增 `mention_queue` 表 | id, comment_id, task_id, mentioned_agent, status, retry_count | ✅ 已实现 |
| `db.py` | mention_queue 索引 | status + (mentioned_agent, status) | ✅ 已实现 |

### 6.3 操作层

| 文件 | 改动 | 说明 | 状态 |
|------|------|------|------|
| `operations.py` | 新增 `get_subtasks_summary()` | 批量查询 parent 下所有 sub 状态摘要 | ✅ 已实现 |
| `operations.py` | 新增 `get_aggregate_outputs()` | 聚合所有 sub 的产出 | ✅ 已实现 |
| `operations.py` | 新增 `get_round_comments()` | 获取当前轮次的讨论记录 | ✅ 已实现 |
| `operations.py` | 新增 `increment_round_count()` | 递增 parent 的 round_count | ✅ 已实现 |
| `operations.py` | 新增 `record_mentions()` | comment 创建时写入 mention_queue（去重） | ✅ 已实现 |
| `operations.py` | 新增 `get_pending_mentions()` | 扫描 pending 且未超重试上限的 mentions | ✅ 已实现 |
| `operations.py` | 新增 `mark_mention_notified()` | 标记 mention 为已通知 | ✅ 已实现 |
| `operations.py` | 新增 `mark_mention_retry()` | 递增 retry_count（AgentBusyError 除外） | ✅ 已实现 |
| `operations.py` | 新增 `mark_mention_failed()` | 标记 mention 为失败（超重试上限） | ✅ 已实现 |

### 6.4 API 层

| 文件 | 改动 | 说明 | 状态 |
|------|------|------|------|
| `blackboard_routes.py` | `add_comment` 联动 `record_mentions` | comment 创建后自动写入 mention_queue | ✅ 已实现 |
| `blackboard_routes.py` | 新增成果物聚合端点 | `GET /tasks/{id}/outputs/aggregate` | ❌ 后续 |

### 6.5 Skill 层

| 位置 | 内容 | 说明 | 状态 |
|------|------|------|------|
| 司马懿 workspace | review skill 文件 | 司马懿基于 §5.2 优秀实践自行设计 | ❌ 独立 |
| 庞统 bootstrap | review prompt 模板 | 庞统 review 的三问框架 | ✅ 已实现（ticker._build_review_prompt） |

### 6.6 前端（可选，后续）

| 改动 | 说明 |
|------|------|
| 黑板讨论面板增强 | 实时显示 comments、@mention 高亮 |
| 一轮进度指示 | 显示当前轮次、已完成/总计 sub task |

### 6.7 运维修复

| 文件 | 改动 | 说明 | 状态 |
|------|------|------|------|
| `sanguo_git_sync/auto-sync.sh` | Step 5 兜底 catch-all | 修复 fswatch 漏检文件变化 | ✅ 已实现 |

---

## §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 |
| @mention 通知丢失（Agent busy 时 spawn 失败） | mention_queue 表 + 重试机制（见 §3.4） |
| 一轮结束检测延迟（最长 30s） | 可接受，30s tick 是当前设计约束 |
| Agent 创建 sub task 不规范 | 庞统 review 时检查，不合规的 sub task 打回 |
| 庞统 review 后创建新 sub 触发无限循环 | parent 新增 `reviewing` 状态，庞统 review 期间不触发一轮结束检测；或设 round 上限（如 5 轮） |
| Agent 创建 sub task 缺少 assignee | Agent 创建 sub task 时 capability 必填（用于路由），assignee 可选（认领时填） |
| 讨论阶段 token 消耗高 | 设上下文预算：每个 Agent 读黑板 comments 不超过最近 50 条，goal summary 不超过 2KB |

---

## §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：完整讨论过程记忆（2026-05-28 ~ 05-29）

### A.1 讨论起因

2026-05-28，基于 architecture-v3.0.md v3.0.1 完成的背景，启动 T2（持续指挥 + 动态规划）的调研和设计。目标是补齐 PRD-v3.0 四相架构中未实现的 Phase 2（动态规划）和 Phase 3（持续指挥）。

### A.2 阶段一：T2 前置清理（2026-05-28）

**#1 B8/B9 确认移除**：庞统验证代码发现，BUG-7（planning 暂停失败）和 BUG-8（cancel→resume 空图完成）是 v1.0 (mozi) 的 bug。moziplus v2.0 没有 `planning` 状态（v2 状态机 11 个状态不含 planning）和 `execute_graph` 函数（执行模型完全不同）。结论：从 T2 遗留问题清单中移除。

**#2 architecture-v3.0.md 升级至 v3.0.1**：新增 4 个设计方向章节（§6.5 广播认领、§10.4~10.6）和 §21 T 阶段规划（T1~T8），为后续迭代建立路线图。

**#3 司马懿评审通过**（Mail #1779979934362, #1779980383850, #1779981185745）：修复广播认领状态矛盾、BUG-22/25/26 确认、采纳 5 条建议改进。

**#4 AGENTS.md 更新**：补充 request vs inform 判断标准——"对方收到后是否需要回复/确认/采取行动？需要→request，不需要→inform"。

### A.3 阶段二：持续指挥与动态规划调研（2026-05-28 ~ 05-29）

庞统三路调研（NAS 知识库 → 代码 → 优秀实践）：

**#5 NAS 知识库搜索**：搜索 wiki-vault/practices/ 中关于"持续指挥"和"动态规划"的内容，找到 get-shit-done、claude-code、hermes、multi-agent-collaboration 等相关实践文件。

**#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（讨论涌现）和完整闭环

**#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 种通信协议

### 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 |
| 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 | 四相架构（§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.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 待确认事项

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

### A.11 司马懿评审记录（v1.2 修复）

**评审结论**：通过，需修复 3 个设计问题。

**3 个设计问题修复**：

| # | 问题 | 修复方案 | 位置 |
|---|------|---------|------|
| 1 | @mention 通知丢失（Agent busy 时 spawn 失败，mention 永远收不到） | 新增 `mention_queue` 表 + 重试机制 + 通知状态追踪 | §3.4 |
| 2 | 一轮结束检测不区分 done/failed/cancelled | 传给庞统的状态摘要包含维度信息 {done, failed, cancelled}，prompt 增加失败处理指引 | §4.1 |
| 3 | 司马懿 review 和庞统 review 执行顺序未定义 | tick 流程明确 8 步顺序，一轮结束检测在调度之后，mention 在 review 之后 | §4.4 |

**4 条建议采纳**：

| # | 建议 | 采纳情况 |
|---|------|---------|
| 4 | Spawn Prompt 补充 Boids 四条具体行为描述 | ✅ 已映射为 Separation/Alignment/Cohesion/Boundary 四条准则 |
| 5 | 代码改动清单缺少 MVP 优先级标注 | ✅ 每行加 MVP 列（✅ 必须 / ❌ 后续） |
| 6 | 风险表缺少 3 个关键风险（无限循环/assignee 缺失/token 消耗） | ✅ 新增 3 条风险 + 缓解方案 |
| 7 | 司马懿 review skill 设计方向 | ✅ 记录为参考，司马懿独立设计不阻塞 #01 |

**v1.2 新增章节**：
- §4.4 一轮结束后的执行顺序
- §4.5 防止庞统 review 无限循环
- §3.4 扩展 @mention 通知可靠性保障

**Rebuttal 备注无**——3 个设计问题全部接受，无争议。