diff --git a/docs/design/01-four-phase-loop.md b/docs/design/01-four-phase-loop.md index fbe5079..1f2868b 100644 --- a/docs/design/01-four-phase-loop.md +++ b/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 | ---