sanguo_moziplus_v2/docs/review/simayi-independent-audit.md

# 司马懿独立审计报告：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*