auto-sync: 2026-05-29 09:15:34

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

@@ -2,11 +2,11 @@
 
 **序号**: #01
 **名称**: 四相循环 — PRD Phase 1~4 完整实现方案
-**版本**: v1.2（修复司马懿评审 3 个设计问题 + 采纳 4 条建议）
+**版本**: v1.3（实现完成，待 E2E 验证）
 **基于**: PRD-v3.0 §4 四相架构 + architecture-v3.0.md
 **作者**: 庞统（副军师）🐦
 **日期**: 2026-05-29
-**状态**: 待评审
+**状态**: 实现完成，待 E2E 验证
 **评审**: 司马懿
 
 ---
@@ -309,47 +309,70 @@ AGENTS.md 中的角色从"质量总监：代码评审、多空辩论、最终验
 
 ### 6.1 Daemon 层
 
-| 文件 | 改动 | 说明 | MVP |
+| 文件 | 改动 | 说明 | 状态 |
 |------|------|------|------|
-| `ticker.py` | 新增 `_check_round_complete()` | 检测 parent 下所有 sub 终态 | ✅ |
-| `ticker.py` | 新增 `_spawn_pangtong_review()` | 一轮结束时 spawn 庞统 review | ✅ |
-| `ticker.py` | 新增 `_process_mentions()` | 扫描 mention_queue → spawn 被 @ 的 Agent | ❌ 后续 |
-| `ticker.py` | tick 流程明确顺序（§4.4） | 超时→依赖→调度→一轮结束→庞统 review | ✅ |
-| `dispatcher.py` | 扩展 spawn 类型 | 支持 "discussion" + "review" | ✅ |
-| `bootstrap.py` | 扩展上下文构建 | goal + 成果物聚合 + 讨论 history | ✅ |
-| `spawner.py` | 更新 prompt 模板 | 使用 §3.3 框架 + Boids 映射 | ✅ |
-| `models.py` | parent 新增 `round_count` 字段 | 防止无限循环（§4.5） | ✅ |
+| `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） | 超时→依赖→调度→一轮结束→mention 通知 | ✅ 已实现 |
+| `dispatcher.py` | 扩展 spawn 类型 | 支持 "discussion" + "review"（spawn_type 参数） | ✅ 已实现 |
+| `bootstrap.py` | 新增 `build_for_review()` | review 上下文构建（goal + outputs + comments） | ✅ 已实现 |
+| `bootstrap.py` | 新增 `_format_review_context()` | 格式化 status 摘要 + outputs + comments | ✅ 已实现 |
+| `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 API 层
+### 6.2 数据库层
 
-| 文件 | 改动 | 说明 | MVP |
+| 文件 | 改动 | 说明 | 状态 |
 |------|------|------|------|
+| `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` | ❌ 后续 |
-| `blackboard_routes.py` | mention_queue 表初始化 | comments 表联动 | ❌ 后续 |
 
-### 6.3 Model 层
+### 6.5 Skill 层
 
-| 文件 | 改动 | 说明 | MVP |
-|------|------|------|------|
-| `operations.py` | 新增 `get_subtasks_status()` | 批量查询 parent 下所有 sub 状态 | ✅ |
-| `operations.py` | 新增 `get_mentioned_agents()` | 从 mention_queue 提取 pending mentions | ❌ 后续 |
-
-### 6.4 Skill 层
-
-| 位置 | 内容 | 说明 | MVP |
+| 位置 | 内容 | 说明 | 状态 |
 |------|------|------|------|
 | 司马懿 workspace | review skill 文件 | 司马懿基于 §5.2 优秀实践自行设计 | ❌ 独立 |
-| 庞统 bootstrap | review prompt 模板 | 庞统 review 的三问框架 | ✅ |
+| 庞统 bootstrap | review prompt 模板 | 庞统 review 的三问框架 | ✅ 已实现（ticker._build_review_prompt） |
 
-**MVP 范围**：ticker 流程重排 + 一轮结束检测 + 庞统 review spawn + spawn prompt 模板 + round_count 防循环。@mention 通知和成果物聚合端点后续迭代。
-
-### 6.5 前端（可选，后续）
+### 6.6 前端（可选，后续）
 
 | 改动 | 说明 |
 |------|------|
 | 黑板讨论面板增强 | 实时显示 comments、@mention 高亮 |
 | 一轮进度指示 | 显示当前轮次、已完成/总计 sub task |
 
+### 6.7 运维修复
+
+| 文件 | 改动 | 说明 | 状态 |
+|------|------|------|------|
+| `sanguo_git_sync/auto-sync.sh` | Step 5 兜底 catch-all | 修复 fswatch 漏检文件变化 | ✅ 已实现 |
+
 ---
 
 ## §7. 安全红线（不变）