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