auto-sync: 2026-05-19 22:29:11

docs/review/v2-code-design-prd-audit.md

@@ -0,0 +1,226 @@
+# moziplus v2.0 PRD-设计-编码 全覆盖审查报告
+
+> **版本**: v1.0
+> **日期**: 2026-05-19
+> **作者**: 庞统（副军师）🐦
+> **审查范围**: PRD v2.0 → 25份设计文档 → 全部后端+前端代码
+> **子报告**: backend-audit.md + frontend-audit.md + prd-coverage-audit.md
+
+---
+
+## 零、执行摘要
+
+### 一句话结论
+
+> **核心架构完整落地，v2.7/v2.8 已超前实现；主要缺口在安全红线（guardrails.yaml）和配置目录外置（prompt_templates/review_protocols/schemas）。**
+
+### 数据速览
+
+| 指标 | 数值 |
+|------|------|
+| PRD 需求条目 | 48 条 |
+| 完整实现 | 34 条（71%） |
+| 部分实现 | 11 条（23%） |
+| 未实现（v2.1+） | 3 条（6%） |
+| 后端代码 | 31 文件 / ~7,200 行 |
+| 前端代码 | 28 文件 / ~6,200 行 |
+| 测试代码 | 20 文件 / ~4,300 行 / 36+ E2E用例 |
+| 设计文档 | 25 份（7份主文档 + 8份Topic + 10份辅助） |
+| DB 表 | 13 张（含 v2.6/v2.7/v2.8 迁移链） |
+
+### 版本混乱问题
+
+| 问题 | 说明 |
+|------|------|
+| development-plan-v2.6.md 标注 v2.8 "待开发" | 代码中 v2.8 已完整实现（状态增强+Checkpoint+归档） |
+| architecture-v2.6.md 文件名 v2.6 | 内容已包含 v2.7/v2.8 变更，建议更名 |
+| 5 份 Topic proposal 文档 | 已全部纳入主架构，未归档 |
+| architecture-v2.md（v2.0 版） | 已过时，仍在 design/ 目录 |
+
+---
+
+## 一、三路审查核心发现
+
+### 1.1 后端审查（backend-audit.md）
+
+**结论：后端 31 个模块与设计高度一致，4 个"已实现未集成"的独立模块**
+
+| 分类 | 模块 | 状态 |
+|------|------|------|
+| ✅ 完整实现 | 黑板 CRUD + 11 状态机 + 13 张表 + 迁移链 | 与设计完全匹配 |
+| ✅ 完整实现 | Daemon Ticker + Router/Dispatcher 分层路由 | Mode A LLM + Mode B Handoff |
+| ✅ 完整实现 | Spawner Full Agent + API 契约 + 进程监控 | SPAWN_PROMPT_TEMPLATE |
+| ✅ 完整实现 | Checkpoint M3 完整 CRUD + approve/reject | v2.8 设计已全部落地 |
+| ✅ 完整实现 | Mail Tab 后端 6 端点 + 归档机制 | v2.7 设计已全部落地 |
+| 🔴 已实现未集成 | HealthChecker（僵尸检测） | health.py 完整，Ticker 未调用 |
+| 🔴 已实现未集成 | BootstrapBuilder（L0-L3 上下文） | bootstrap.py 完整，Spawner 用自己模板 |
+| 🟡 已实现未集成 | InboxWatcher（即时事件） | inbox.py 完整，Ticker 未启动 |
+| 🟡 已实现未集成 | ExperienceDistiller（经验蒸馏） | experience.py 完整，无自动流程 |
+| 🐛 潜在 Bug | checkpoint_routes.py `_bb()` | 调用不存在的 `registry.get_db_path()` |
+
+### 1.2 前端审查（frontend-audit.md）
+
+**结论：27 个组件全面实现，但设计文档要求"精简到 5 页"未执行**
+
+| 分类 | 发现 |
+|------|------|
+| ✅ 完整实现 | 12 个 Tab 全部有对应组件，状态管理(store.ts)与后端完全对齐 |
+| ✅ 完整实现 | CheckpointPanel 三类型面板 + ArtifactPanel 成果物 |
+| ✅ 超前实现 | Mail/Usage/Templates 三个 Tab 设计文档未规划 |
+| ✅ 超前实现 | MorningPanel(418行)/GlobalSearch(104行) 已编码但未注册 |
+| 🔴 P0 Bug | TaskModal StatusButtons 无 onClick 绑定（按钮不响应点击） |
+| 🟡 设计偏差 | 设计要求 5 页精简，代码保留 12 Tab |
+| 🟡 未实现 | DAG 拓扑视图、SSE 实时推送、通知中心完整版 |
+
+### 1.3 PRD 覆盖审查（prd-coverage-audit.md）
+
+**结论：71% 完整实现，94% 部分覆盖，3 条缺口属 v2.1+ 范围**
+
+| PRD 维度 | 完整率 | 关键缺口 |
+|---------|--------|---------|
+| §4 四相架构 | 78% | P1 需求探索依赖 Agent Skill（架构决策） |
+| §5 核心能力 | 50% | C9 安全护栏无独立 guardrails.yaml，C10 工具链属 v2.1+ |
+| §6 技术方向 | 78% | T7 对话入口依赖 OpenClaw（架构决策） |
+| §10.1 安全红线 | **33%** | R1 实盘拦截/R4 Token 消耗追踪未实现 |
+| §10.2 v2.0 范围 | 100% | 无缺口 |
+| §10.3 多任务并发 | 100% | 无缺口 |
+| §10.4 失败恢复 | 80% | replan 流程未显式设计 |
+
+---
+
+## 二、超前实现清单（代码有 → 设计/PRD 没有）
+
+> 这些超前实现多数是好事，需要做的是**更新设计文档**来反映真实状态。
+
+| # | 功能 | 代码位置 | 建议 |
+|---|------|---------|------|
+| 1 | **v2.8 状态增强 + Checkpoint + 归档** | db.py + checkpoint_routes.py + 前端 11 状态 | development-plan 标注"待开发"，实际已完成。**更新开发计划** |
+| 2 | **Mail Tab 后端 6 端点 + 前端完整** | mail_routes.py + MailPanel.tsx | v2.7 设计已覆盖但主架构文档未更新 |
+| 3 | **前端 12 Tab 全面实现** | App.tsx + 27 组件 | PRD §10.2 标注 Dashboard 为 v2.1+，实际已提前实现 |
+| 4 | **UsagePanel 花费总览** | UsagePanel.tsx (172行) | 设计文档未规划 |
+| 5 | **TemplatePanel 任务模板** | TemplatePanel.tsx (232行) + store.ts TEMPLATES (10个模板) | 设计文档未规划 |
+| 6 | **MorningPanel AI 晨报** | MorningPanel.tsx (418行) | 组件已实现但未注册到 TAB_DEFS |
+| 7 | **GlobalSearch ⌘K 搜索** | GlobalSearch.tsx (104行) | 组件已实现但未注册到 App.tsx |
+| 8 | **BootstrapBuilder L0-L3 四层上下文** | daemon/bootstrap.py (215行) | 完整实现但未被 Spawner 调用 |
+| 9 | **outputs content 直传自动写文件** | blackboard_routes.py | 设计只提 content_path |
+| 10 | **Project delete（从注册表移除）** | registry.py | 设计只提 archive |
+| 11 | **V2Task.must_haves / estimated_duration_minutes 字段** | store.ts | 设计文档未记录 |
+| 12 | **10 个任务模板（量化策略/数据采集/回测/风控审查等）** | store.ts TEMPLATES | 设计文档未规划 |
+
+---
+
+## 三、缺口清单（PRD/设计有 → 代码没有）
+
+### 🔴 P0 — 必须解决
+
+| # | 缺口 | PRD/设计依据 | 影响 |
+|---|------|------------|------|
+| 1 | **guardrails.yaml 安全红线文件不存在** | PRD §10.1 R1-R6 + architecture-v2.6 §9.4.2 | 实盘交易/数据删除/系统配置变更无硬编码拦截 |
+| 2 | **TaskModal StatusButtons 无 onClick** | topic9 §3.3 | 前端状态操作按钮不工作 |
+| 3 | **checkpoint_routes.py `_bb()` 运行时 Bug** | v2.8 §四 | checkpoint API 调用会报错 |
+
+### 🟡 P1 — 应该解决
+
+| # | 缺口 | PRD/设计依据 | 影响 |
+|---|------|------------|------|
+| 4 | **prompt_templates/ 目录未创建** | architecture-v2.6 §9.4 (S-01~S-28) | Agent prompt 模板硬编码在 spawner.py |
+| 5 | **review_protocols/ 目录未创建** | architecture-v2.6 §9.4 | 审查协议硬编码在 review.py |
+| 6 | **schemas/ 目录未创建** | architecture-v2.6 §7 | 产出物校验用正则而非 JSON Schema |
+| 7 | **HealthChecker 未集成到 Ticker** | architecture-v2.6 §14 | 僵尸检测不生效 |
+| 8 | **BootstrapBuilder 未集成到 Spawner** | architecture-v2.6 v2.6.5 | L0-L3 四层上下文未生效 |
+| 9 | **token 消耗追踪** | PRD §10.1 R4 | 大额消耗无自动暂停 |
+| 10 | **用户评论输入** | topic9 §D9-8 | TaskModal 评论区仅展示无输入 |
+
+### 🟢 P2 — 可以后续（v2.1+ 或低优先级）
+
+| # | 缺口 | 说明 |
+|---|------|------|
+| 11 | DAG 拓扑视图 | 需要 React Flow，前端未实现 |
+| 12 | SSE 实时推送（前端） | 仍用 HTTP 5s 轮询 |
+| 13 | 通知中心完整实现 | 仅有铃铛占位按钮 |
+| 14 | Tab 精简到 5 页 | 设计要求但未执行（12 Tab 更丰富） |
+| 15 | 乐观锁(expected_version) | topic9 §D9-10 |
+| 16 | F7 全生命周期阶段映射 | 两次审查均未设计 |
+| 17 | F8 工具链自动化 | PRD 明确 v2.1+ |
+| 18 | Subagent spawn | placeholder，当前只走 Full Agent |
+
+---
+
+## 四、设计文档版本梳理与建议
+
+### 权威文档（保留）
+
+| 文档 | 角色 | 备注 |
+|------|------|------|
+| architecture-v2.6.md | 主架构 | 建议更名为 architecture-v2.8.md |
+| technical-design-v2.6.md | 技术设计 | 保留 |
+| PRD-v2.0.md | 需求文档 | §6.3/§7 需更新（双入口+不分阶段） |
+| v2.7-subtask-model.md | SubTask 设计 | 保留 |
+| v2.8-state-enhancement.md | 状态增强设计 | 保留 |
+| development-plan-v2.6.md | 开发计划 | **需更新 v2.8 状态** |
+| frontend-redesign-v2.6.md | 前端设计 | 保留 |
+| deployment-v2.6.md | 部署方案 | 保留 |
+
+### 应归档（已纳入主文档）
+
+| 文档 | 原因 |
+|------|------|
+| architecture-v2.md | 已被 v2.6 完全替代 |
+| topic3-challenge-review-proposal.md | 已纳入 architecture-v2.6 §9 |
+| topic4-decomposition-skill-proposal.md | 已纳入 architecture-v2.6 §6 |
+| topic6-experience-loop-proposal.md | 已纳入 architecture-v2.6 v2.6.7 |
+| topic7-interaction-dashboard-proposal.md | 已纳入 topic9 |
+| topic7-9-interaction-dashboard-proposal.md | 被 topic7+9 替代 |
+| topic9-dashboard-design.md | 已纳入前端设计 |
+| topic11-multi-project-proposal.md | 已纳入 registry.py |
+| topic4-skill-checklist-draft.md | 被 topic4 替代 |
+| agent-routing-redesign.md | 已在代码中完整实现 |
+
+---
+
+## 五、变更历史（PRD v2.0 → 当前代码）
+
+| 版本 | 日期 | 变更内容 | 文档 |
+|------|------|---------|------|
+| PRD v2.0 | 05-13 | 初版，四相架构 + 核心理念 | PRD-v2.0.md |
+| 设计 v2.6 | 05-14~16 | 完整架构设计 + 8个课题 | architecture-v2.6.md + topic*.md |
+| 设计 v2.6.1 | 05-17 | Agent 路由重设计 | agent-routing-redesign.md |
+| 代码 F1-F18 | 05-17~18 | 全部功能编码完成 | src/ |
+| v2.7 SubTask | 05-18 | Card 回滚 + SubTask + Mail Tab | v2.7-subtask-model.md |
+| v2.8 状态增强 | 05-18~19 | 3 新状态 + Checkpoint + 归档 | v2.8-state-enhancement.md |
+| **当前** | 05-19 | 代码 = v2.8，文档 = 混合状态 | 本报告 |
+
+---
+
+## 六、行动建议
+
+### 第一优先级：修复 Bug + 补齐安全
+
+| # | 行动 | 工作量 | 负责人 |
+|---|------|--------|--------|
+| 1 | 修复 checkpoint_routes.py `_bb()` Bug | 0.5h | 张飞 |
+| 2 | 修复 TaskModal StatusButtons onClick | 2h | 张飞 |
+| 3 | 创建 guardrails.yaml + 6 条安全红线 | 1-2天 | 张飞 + 关羽 |
+| 4 | token 消耗追踪 + 超限暂停 | 1天 | 张飞 |
+
+### 第二优先级：集成 + 配置外置
+
+| # | 行动 | 工作量 | 负责人 |
+|---|------|--------|--------|
+| 5 | HealthChecker 集成到 Ticker | 2h | 张飞 |
+| 6 | BootstrapBuilder 集成到 Spawner（替换硬编码模板） | 4h | 张飞 |
+| 7 | 创建 prompt_templates/ + review_protocols/ + schemas/ 目录 | 1-2天 | 张飞 |
+| 8 | 用户评论输入框（TaskModal） | 2h | 张飞 |
+
+### 第三优先级：文档对齐
+
+| # | 行动 | 工作量 | 负责人 |
+|---|------|--------|--------|
+| 9 | development-plan 更新 v2.8 状态 | 1h | 庞统 |
+| 10 | architecture-v2.6.md 更名/标注 | 0.5h | 庞统 |
+| 11 | 过期文档归档到 archive/ | 0.5h | 庞统 |
+| 12 | PRD §6.3/§7 更新 | 1h | 庞统 |
+
+---
+
+*报告完毕。详细子报告见 docs/review/ 目录下 backend-audit.md / frontend-audit.md / prd-coverage-audit.md。*