diff --git a/docs/design/01-four-phase-loop.md b/docs/design/01-four-phase-loop.md index 69168c4..a769588 100644 --- a/docs/design/01-four-phase-loop.md +++ b/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. 安全红线(不变)