From 35cd321241384b8e29f42278e4ff00c6cff085f8 Mon Sep 17 00:00:00 2001 From: cfdaily Date: Tue, 19 May 2026 22:29:11 +0800 Subject: [PATCH] auto-sync: 2026-05-19 22:29:11 --- docs/review/v2-code-design-prd-audit.md | 226 ++++++++++++++++++++++++ 1 file changed, 226 insertions(+) create mode 100644 docs/review/v2-code-design-prd-audit.md diff --git a/docs/review/v2-code-design-prd-audit.md b/docs/review/v2-code-design-prd-audit.md new file mode 100644 index 0000000..a028fc4 --- /dev/null +++ b/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。*