auto-sync: 2026-05-19 22:43:25

docs/review/simayi-independent-audit.md

@@ -0,0 +1,272 @@
+# 司马懿独立审计报告：PRD→设计→代码 三层一致性审查
+
+**审查人**: 司马懿（simayi-challenger）
+**日期**: 2026-05-19
+**范围**: moziplus v2.0 全链路（PRD + 7 设计文档 + 24 后端文件 + 22 前端文件）
+
+---
+
+## 一、总体评价
+
+moziplus v2.0 的 F1-F18 编码完成度很高，核心链路（黑板 CRUD → Ticker 调度 → Dispatcher 分发 → Spawner 执行 → Checkpoint 人工确认）已经贯通。v2.7 SubTask 模型、v2.8 状态增强、M3 Checkpoint 均已落地。
+
+**做得好的**：
+- 黑板（Blackboard）模块设计扎实，operations.py 20+ 方法覆盖完整 CRUD + 聚合 + 归档
+- Ticker 580 行实现持续指挥循环，_tick_project/_dispatch_pending/_dispatch_reviews/_check_timeouts 职责清晰
+- Counter + Dispatcher + Spawner 三层限流机制设计正确（BUG-30/31 已修）
+- Checkpoint 端到端实现（DDL → operations → routes → CheckpointPanel → TaskModal 集成）质量高
+- 前端 12 Tab 覆盖全面，EdictBoard 任务卡片 + CARD_ACTIONS 操作按钮设计实用
+
+**需要改进的**：
+- 安全红线（PRD §10.1 六条）落地不足，6 条中只有 2.5 条有代码实现
+- development-plan 文档严重滞后（v2.8/M3 仍标"待开发"，实际已完成+已评审）
+- 5 个前端组件已编写但未被任何主流程引用（死代码）
+- 设计文档版本混乱，存在重复/过时文件未归档
+
+---
+
+## 二、PRD 能力 → 设计覆盖 → 代码实现（§5 十大能力）
+
+| # | PRD 能力 | 设计覆盖 | 代码实现 | 状态 |
+|---|---------|---------|---------|------|
+| C1 | 需求探索对话 | ✅ topic4 + architecture §5 苏格拉底 Skill | ⚠️ skill_system.py 有 Skill 框架，但苏格拉底 Skill 未注册 | **缺口** |
+| C2 | 动态规划 | ✅ architecture §6 指挥循环 | ⚠️ Ticker 有 _dispatch_pending 但无 AI 规划环节 | **部分** |
+| C3 | 持续指挥 | ✅ architecture §6 Ticker + 庞统关键节点介入 | ✅ ticker.py 580行，_tick_project 完整循环 | ✅ |
+| C4 | 共享意识 | ✅ architecture §7 Blackboard + Daemon API | ✅ blackboard/ 全套 + 7 routes 模块 | ✅ |
+| C5 | 自主协作 | ✅ PRD §6.2 标注 v2.1+ | ❌ 未实现（PRD 明确 v2.1+ 范围） | **预期缺口** |
+| C6 | 质量门禁 | ✅ topic3 + review.py | ✅ review.py ReviewPipeline + router.py AI 路由 | ✅ |
+| C7 | 主动汇报 | ✅ architecture §8 SSE 推送 | ✅ sse_routes.py + 前端 NotificationCenter | ✅ |
+| C8 | 经验沉淀 | ✅ topic6 | ✅ experience.py 291行 ExperienceStore | ✅ |
+| C9 | 安全护栏 | ✅ PRD §10.1 六条红线 | ⚠️ 详见下方安全红线分析 | **重大缺口** |
+| C10 | 工具链集成 | ✅ PRD §10.2 标注 v2.1+ | ❌ toolchain-proposal.md 有设计但未实现 | **预期缺口** |
+
+### 安全红线（PRD §10.1 六条）落地分析
+
+| 红线 | 设计覆盖 | 代码实现 | 状态 |
+|------|---------|---------|------|
+| 实盘交易拦截 | ❌ 无专门设计 | ❌ 无代码 | **P0 缺口** |
+| 数据删除拦截 | ⚠️ archive 改 metadata 不删文件 | ✅ archive_task 只改 archived=1，不删除记录 | **部分满足** |
+| 系统配置变更拦截 | ❌ 无专门设计 | ❌ 无代码 | **P0 缺口** |
+| 大额 token 消耗 | ⚠️ architecture 提及 L3 tripwire | ⚠️ bootstrap.py L113 有 token limit 警告，但非拦截 | **部分** |
+| Agent 不受控行为 | ✅ counter.py + health.py | ✅ counter.py 并发限制 + health.py zombie 检测 | ✅ |
+| 连续失败 | ✅ max_retries + review pipeline | ✅ Task.max_retries=2 + ReviewPipeline | ✅ |
+
+**结论**：6 条安全红线中只有 2 条完整落地（Agent 不受控 + 连续失败），1.5 条部分满足（数据删除 + token），2 条完全缺失（实盘交易 + 配置变更）。这是 **P0 级缺口**——PRD 明确标注"必须 AI 拦截并拉人确认，不允许自主执行"，但代码无实现。
+
+---
+
+## 三、设计文档 → 代码一致性
+
+### 3.1 API 路由对比
+
+| 设计文档 API | 代码实现 | 一致性 |
+|-------------|---------|--------|
+| GET /api/projects/{pid}/tasks | ✅ blackboard_routes L31 | ✅ |
+| GET /api/projects/{pid}/tasks/{id} | ✅ blackboard_routes L41 | ✅ |
+| POST /api/projects/{pid}/tasks | ✅ blackboard_routes L66 | ✅ |
+| POST /api/projects/{pid}/tasks/{id}/claim | ✅ blackboard_routes L101 | ✅ |
+| PATCH /api/projects/{pid}/tasks/{id}/status | ⚠️ 代码用 POST（blackboard_routes L109） | **偏差** |
+| POST /api/projects/{pid}/tasks/{id}/comments | ✅ blackboard_routes L172 | ✅ |
+| POST /api/projects/{pid}/tasks/{id}/outputs | ✅ blackboard_routes L189 | ✅ |
+| POST /api/projects/{pid}/tasks/{id}/decisions | ✅ blackboard_routes L264 | ✅ |
+| POST /api/projects/{pid}/tasks/{id}/observations | ✅ blackboard_routes L275 | ✅ |
+| POST /api/projects/{pid}/tasks/{id}/reviews | ✅ blackboard_routes L291 | ✅ |
+| POST /api/projects/{pid}/tasks/{id}/archive | ✅ blackboard_routes L337 | ✅ |
+| POST /api/projects/{pid}/tasks/archive-done | ✅ blackboard_routes L353 | ✅ |
+| GET /api/projects/{pid}/tasks/{id}/checkpoints | ✅ checkpoint_routes | ✅ |
+| POST /api/projects/{pid}/tasks/{id}/checkpoints | ✅ checkpoint_routes | ✅ |
+| POST /.../checkpoints/{cid}/approve | ✅ checkpoint_routes | ✅ |
+| POST /.../checkpoints/{cid}/reject | ✅ checkpoint_routes | ✅ |
+| POST /api/daemon/tick | ✅ daemon_routes L26 | ✅ |
+| GET /api/daemon/status | ✅ daemon_routes L10 | ✅ |
+| GET /api/daemon/sessions | ❌ **未实现** | **缺口** |
+| GET /api/events?project={pid} | ✅ sse_routes | ✅ |
+| GET /api/projects | ✅ project_routes L20 | ✅ |
+| POST /api/projects | ✅ project_routes L28 | ✅ |
+| GET /api/projects/{pid} | ✅ project_routes L42 | ✅ |
+| DELETE /api/projects/{pid} | ⚠️ 代码用 POST /{id}/archive | **偏差** |
+
+### 3.2 关键偏差
+
+**偏差1：PATCH status → POST status**（P2）
+- 设计文档 technical-design-v2.6.md L749：`PATCH /api/projects/{pid}/tasks/{id}/status`
+- 代码 blackboard_routes.py L109：`@router.post("/tasks/{task_id}/status")`
+- 影响：语义偏差（PATCH 表示部分更新，POST 表示动作），功能无差异
+- 建议：统一为 PATCH 或设计文档改 POST
+
+**偏差2：DELETE project → POST archive**（P1）
+- 设计文档 technical-design-v2.6.md L786：`DELETE /api/projects/{pid}` 归档项目
+- 代码 project_routes.py：`POST /{project_id}/archive`
+- 影响：违反 RESTful 约定（删除操作用 DELETE），且设计文档与代码不同步
+- 建议：PRD §10.1 要求"数据删除需人工确认"，POST + 确认流程比 DELETE 更安全，代码做法更合理，应更新设计文档
+
+**偏差3：GET /api/daemon/sessions 未实现**（P1）
+- 设计文档 technical-design-v2.6.md L768 定义 `GET /api/daemon/sessions`
+- 代码中无此端点
+- spawner.py L142-148 有 `_sessions` 字典和 `active_sessions` 属性，但未暴露为 API
+- 建议：补实现或设计文档标记为 v2.1+
+
+### 3.3 数据模型一致性
+
+| 设计定义 | 代码实现 | 一致性 |
+|---------|---------|--------|
+| tasks 表 11 状态 CHECK | ✅ db.py L87 11 状态完整 | ✅ |
+| checkpoints 表 DDL | ✅ db.py L121 11 字段完整 | ✅ |
+| outputs 表扩展 4 字段 | ✅ db.py _migrate_v28 | ✅ |
+| events 表 FK tasks(id) | ✅ db.py L106 | ✅ |
+| Task Pydantic model | ✅ models.py 28 字段 | ✅ |
+
+---
+
+## 四、超前实现（代码有但设计文档无记录）
+
+| 组件 | 文件 | 评价 |
+|------|------|------|
+| MailPanel | components/MailPanel.tsx | ✅ 好事 — Mail Tab 是 v2.7 新增功能，前端-redesign 未提及但合理 |
+| MorningPanel | components/MorningPanel.tsx | ⚠️ 孤立 — 未被 App.tsx 引用，无设计文档 |
+| ArtifactList | components/ArtifactList.tsx | ⚠️ 孤立 — 未被引用，设计文档提到 ArtifactPanel 但未提到 ArtifactList |
+| ConfirmDialog | components/ConfirmDialog.tsx | ⚠️ 孤立 — 未被引用，通用组件可保留 |
+| GlobalSearch | components/GlobalSearch.tsx | ⚠️ 孤立 — 未被引用，topic7 提到全局搜索但未落地到主流程 |
+| ArtifactPanel | components/ArtifactPanel.tsx | ⚠️ 孤立 — 设计文档 §5.1 提到成果物面板，但 TaskModal 未引用 |
+| court Tab | CourtDiscussion.tsx | ✅ 好事 — topic3 挑战/评审体系的前端展示 |
+| agent-api-contract.md | docs/design/ | ⚠️ 设计文档但未在 architecture 中引用 |
+| agent-routing-redesign.md | docs/design/ | ⚠️ 设计文档但未在 architecture 中引用 |
+| frontend-principles.md | docs/design/ | ⚠️ 孤立设计文档 |
+
+---
+
+## 五、缺口分析
+
+### 5.1 PRD 有但代码未实现（按优先级）
+
+| # | 优先级 | 缺口 | PRD 来源 | 影响 |
+|---|--------|------|---------|------|
+| 1 | **P0** | 实盘交易安全拦截 | §10.1 红线1 | 量化平台核心安全需求 |
+| 2 | **P0** | 系统配置变更拦截 | §10.1 红线3 | 防止 Agent 擅自改配置 |
+| 3 | **P1** | 苏格拉底需求探索 Skill | §5 C1 | PRD 定义为"核心入口能力" |
+| 4 | **P1** | AI 动态规划环节 | §5 C2 | 当前 Ticker 只做调度，无 AI 规划 |
+| 5 | **P2** | GET /api/daemon/sessions | technical-design L768 | 已有数据但未暴露 API |
+| 6 | **P2** | ArtifactPanel 集成到 TaskModal | v2.8-state-enhancement §5 | 组件已写但未接入 |
+
+### 5.2 PRD 标注 v2.1+ 的预期缺口（可接受）
+
+| 能力 | PRD 声明 | 状态 |
+|------|---------|------|
+| C5 自主协作 | §10.2 v2.1+ | ✅ 预期缺口 |
+| C10 工具链集成 | §10.2 v2.1+ | ✅ 预期缺口 |
+| peer-to-peer 协作 | §6.2 | ✅ 预期缺口 |
+| Agent 主动感知 | §10.2 | ✅ 预期缺口 |
+| Fidelity 信息路由 | §10.2 | ✅ 预期缺口 |
+
+---
+
+## 六、文档版本混乱
+
+| 文件 | 问题 | 建议 |
+|------|------|------|
+| architecture-v2.md (2757行) | 旧版，被 v2.6 替代但仍保留 | **归档到 archive/** |
+| topic7-9-interaction-dashboard-proposal.md (247行) | 与 topic7-interaction-dashboard-proposal.md (456行) 重复 | 保留 456 行版本，删除旧版 |
+| topic4-skill-checklist-draft.md (96行) | topic4-decomposition-skill-proposal.md (638行) 的草稿 | 归档到 archive/ |
+| product-direction-notes.md | 产品方向笔记，非正式设计文档 | 归档到 archive/ |
+| agent-integration-v2.6.md | 可能与 architecture §9 重叠 | 检查后归档或合并 |
+| agent-routing-redesign.md | 可能与 architecture §8 重叠 | 检查后归档或合并 |
+| **development-plan-v2.6.md** | **v2.8/M3 仍标"待开发"，实际已完成+已评审** | **立即更新** |
+
+**权威文档定义**：
+- architecture-v2.6.md：主架构（权威）
+- technical-design-v2.6.md：技术设计（权威）
+- development-plan-v2.6.md：开发计划（需更新）
+- frontend-redesign-v2.6.md：前端设计（权威）
+- v2.7-subtask-model.md：SubTask 补充（权威）
+- v2.8-state-enhancement.md：状态增强补充（权威）
+
+---
+
+## 七、代码质量问题
+
+### 7.1 死代码（已编写但未被主流程引用）
+
+| # | 优先级 | 组件 | 证据 | 建议 |
+|---|--------|------|------|------|
+| 1 | P1 | MorningPanel.tsx | App.tsx 未 import | 接入 morning tab 或删除 |
+| 2 | P1 | ArtifactList.tsx | 无 import | TaskModal 产出区域集成或删除 |
+| 3 | P1 | ArtifactPanel.tsx | 无 import（设计文档 §5.1 要求接入） | TaskModal 产出区域集成 |
+| 4 | P2 | ConfirmDialog.tsx | 无 import | 通用组件保留，后续使用 |
+| 5 | P2 | GlobalSearch.tsx | 无 import | topic7 提到但未落地，v2.1+ 接入 |
+
+### 7.2 集成缺失
+
+| # | 优先级 | 问题 | 证据 |
+|---|--------|------|------|
+| 1 | P1 | F19-F22 开发计划标注"设计评审中/待开始" | development-plan L280-282 |
+| 2 | P1 | experience.py ExperienceStore 未被 Ticker 自动调用 | 无 auto-distill 逻辑 |
+| 3 | P2 | router.py AgentRouter.route() 未被 Dispatcher 调用 | dispatcher.py 用 _legacy_dispatch |
+
+### 7.3 已知 Bug（本轮及之前评审发现，已修或待修）
+
+| Bug | 状态 | 说明 |
+|-----|------|------|
+| BUG-30/31 Counter leak | ✅ 已修 | on_complete 回调链 |
+| BUG-32 resolve 状态校验 | ✅ 已修 | waiting_human 守卫 |
+| BUG-33 payload version 校验 | ✅ 已修 | version 字段校验 |
+| BUG-34 CheckpointPanel 索引 | ✅ 已修 | pendingIdx 管理 |
+| FK 恢复缺 finally | ⚠️ 待修 | db.py _migrate_v28 |
+
+---
+
+## 八、问题汇总（按优先级排序）
+
+### P0（必须修）
+
+| # | 问题 | 证据 |
+|---|------|------|
+| 1 | **安全红线未落地**：实盘交易拦截 + 系统配置变更拦截无代码实现 | PRD §10.1 红线1/3，代码中无任何拦截逻辑 |
+| 2 | **development-plan 严重滞后**：v2.8/M3 标"待开发"，实际已完成+评审通过 | development-plan-v2.6.md L277-278 |
+
+### P1（应该修）
+
+| # | 问题 | 证据 |
+|---|------|------|
+| 3 | GET /api/daemon/sessions 未实现 | technical-design L768，spawner.py L146 有数据 |
+| 4 | 5 个前端组件死代码 | MorningPanel/ArtifactList/ArtifactPanel/ConfirmDialog/GlobalSearch 无 import |
+| 5 | ArtifactPanel 未集成到 TaskModal | v2.8-state-enhancement §5.1 要求，组件已写未接入 |
+| 6 | design 文档版本混乱 | architecture-v2.md + 3 份重复 topic 文件未归档 |
+| 7 | FK 恢复缺 finally 保护 | db.py _migrate_v28，异常时 FK 永久 OFF |
+| 8 | ExperienceStore 未被 Ticker 自动调用 | experience.py 291 行写好但无 auto-distill |
+
+### P2（可以后修）
+
+| # | 问题 | 证据 |
+|---|------|------|
+| 9 | PATCH status → POST status 偏差 | technical-design L749 vs blackboard_routes L109 |
+| 10 | DELETE project → POST archive 偏差 | technical-design L786 vs project_routes |
+| 11 | 苏格拉底 Skill 未注册 | PRD C1 核心能力，skill_system.py 有框架无 Skill |
+| 12 | AI 动态规划环节缺失 | PRD C2，Ticker 只有调度无规划 |
+| 13 | agent-api-contract.md / agent-routing-redesign.md 未在主架构引用 | 孤立设计文档 |
+
+---
+
+## 九、结论
+
+### 做得好的 ✅
+1. **黑板模块完整**：operations.py 20+ 方法 + 7 API routes 模块，覆盖设计文档全部要求
+2. **v2.8 + M3 端到端贯通**：DDL → operations → routes → CheckpointPanel → TaskModal，质量高
+3. **Ticker 持续指挥**：580 行实现，调度/超时/依赖推进/审查分发 职责清晰
+4. **Counter 限流**：BUG-30/31 修复后三层限流机制完整
+5. **前端 12 Tab 全覆盖**：EdictBoard + TaskModal + MailPanel + 9 个辅助面板
+
+### 必须立即修的 🔴
+1. **安全红线 P0**：实盘交易 + 配置变更拦截必须实现，这是 PRD 硬性要求
+2. **development-plan P0**：立即更新 v2.8/M3 状态为"已完成"
+
+### 应该近期修的 🟡
+1. daemon/sessions API 补实现
+2. ArtifactPanel 集成到 TaskModal
+3. 死代码清理或接入
+4. 设计文档归档（architecture-v2.md + 重复 topic 文件）
+5. FK 恢复 finally 保护
+6. ExperienceStore auto-distill 接入 Ticker
+
+---
+
+*审查完毕。司马懿 🗡️ 2026-05-19*