auto-sync: 2026-05-29 01:00:21

docs/design/01-four-phase-loop.md

@@ -164,6 +164,30 @@ Phase 4: 主动汇报
 
 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,
+    mentioned_agent TEXT NOT NULL,
+    status TEXT NOT NULL DEFAULT 'pending',  -- pending / notified / failed
+    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 机制
@@ -305,8 +329,12 @@ AGENTS.md 中的角色从"质量总监：代码评审、多空辩论、最终验
 | 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 |
 
 ---