From d16a4aa765da2a42e22c35e6af9c90879cc05ec4 Mon Sep 17 00:00:00 2001 From: cfdaily Date: Tue, 19 May 2026 22:43:25 +0800 Subject: [PATCH] auto-sync: 2026-05-19 22:43:25 --- docs/review/simayi-independent-audit.md | 272 ++++++++++++++++++++++++ 1 file changed, 272 insertions(+) create mode 100644 docs/review/simayi-independent-audit.md diff --git a/docs/review/simayi-independent-audit.md b/docs/review/simayi-independent-audit.md new file mode 100644 index 0000000..8999b56 --- /dev/null +++ b/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*