# ZCLAW V12 模块化端到端审计总报告

> **审计版本**: V12 (第 15 次)
> **审计日期**: 2026-04-04
> **审计方法**: 混合矩阵式（10 个功能模块 + 五维检查清单）
> **审计范围**: 全量 9 大功能领域，11 个模块

---

## 1. 审计总览

### 各模块健康度评分

| 排名 | 模块 | 健康度 | P0 | P1 | P2 | P3 | 总问题数 |
|------|------|--------|----|----|----|----|---------|
| 1 | M1 智能对话 | **91** | 0 | 0 | 4 | 7 | 11 |
| 2 | M9 通信与安全 | **86** | 0 | 0 | 5 | 4 | 9 |
| 3 | M5 技能生态 | **85** | 0 | 1 | 2 | 3 | 6 |
| 4 | M7 SaaS Desktop | **85** | 0 | 2 | 2 | 2 | 6 |
| 5 | M8 Admin V2 | **82** | 0 | 0 | 3 | 5 | 8 |
| 6 | M6 Pipeline 工作流 | **72** | 0 | 2 | 5 | 1 | 8 |
| 7 | M11 Classroom | **70** | 0 | 3 | 2 | 3 | 8 |
| 8 | M4 智能层 | **61** | 2 | 2 | 5 | 4 | 13 |
| 9 | M2 Agent 分身 | **67** | 0 | 2 | 7 | 5 | 14 |
| 10 | M3 Hands 自主能力 | **58** | 0 | 5 | 5 | 3 | 13 |

**项目整体健康度: 76/100**

---

## 2. P0/P1 问题优先修复清单

### P0 — 必然崩溃或数据丢失（2 项，全部在 M4 智能层）

| ID | 模块 | 问题 | 文件 | 修复方案 |
|----|------|------|------|---------|
| M4-01 | M4 | **双数据库**: PersistentMemoryStore vs SqliteStorage 数据不共享，用户手动保存的记忆不出现在对话注入中 | `memory/persistent.rs` vs `zclaw-growth/storage/sqlite.rs` | 合并为单一存储或让前端也查询 SqliteStorage |
| M4-02 | M4 | **反思引擎 LLM 未接入**: reflection_reflect 传 driver=None，永远只用规则分析 | `reflection.rs:759-766` | 传入实际 LLM 驱动 |

### P1 — 功能失效/核心断链（15 项）

| ID | 模块 | 问题 | 文件 |
|----|------|------|------|
| M2-01 | M2 | KernelClient createClone 只传 3 字段，丢失 7 个人格字段 | `kernel-agent.ts:74-97` |
| M2-02 | M2 | 两条通路创建逻辑严重不对等 | `gateway-api.ts` vs `kernel-agent.ts` |
| M3-01 | M3 | hand_execute 丢弃 run_id | `hand.rs:184` |
| M3-02 | M3 | Browser Hand 双路径断裂 | `browser.rs:191-343` |
| M3-03 | M3 | browserHandStore 绕过审批流程 | `browserHandStore.ts:222-339` |
| M3-04 | M3 | max_concurrent 未实现 | `kernel/hands.rs` |
| M3-05 | M3 | timeout_secs 未实现 | `hand.rs:47` |
| M4-03 | M4 | 心跳不自动启动 | `heartbeat.rs` |
| M4-04 | M4 | 自主授权后端无强制 | `autonomy-manager.ts` |
| M4-05 | M4 | 前端记忆搜索用 LIKE 非 FTS5 | `persistent.rs` |
| M5-01 | M5 | skill-discovery 将 tags 误映射为 triggers | `skill-discovery.ts:110-123` |
| M6-01 | M6 | route_intent Tauri 命令未注册 | `intent.rs` / `IntentInput.tsx` |
| M6-02 | M6 | pipeline_list 只用 v1 解析器，v2 被丢弃 | `discovery.rs:59` |
| M7-02 | M7 | ConfigMigrationWizard PUT 路径参数语义错误 | `ConfigMigrationWizard.tsx:118` |
| M7-04 | M7 | refreshToken 未传 body，Tauri 可能无 cookie | `saas-client.ts:66` |
| M11-01 | M11 | blocking_lock() 在 async 中可能死锁 | `generate.rs:141-144` |
| M11-02 | M11 | Stage 0/1 LLM 无 map_err | `generate.rs:158-175` |
| M11-03 | M11 | 课堂数据仅内存，重启丢失 | `generate.rs:190-213` |

---

## 3. 断链模式分析

### 3.1 "写了没接"型断链（前端代码存在但后端未消费）

| 断链 | 模块 | 影响 |
|------|------|------|
| hand-execution-complete 事件前端无人监听 | M3 | Hand 执行结果不自动更新 UI |
| classroom_list / classroom_generation_progress | M11 | 课堂历史列表和进度查询功能空置 |
| TOML permissions/rate_limit/max_concurrent 配置 | M3 | 9 个 TOML 中丰富的安全和限流配置形同虚设 |
| 反思引擎 LLM 路径 | M4 | Tauri 命令层永远传 None |

### 3.2 "接了不对"型断链（两端参数/类型不匹配）

| 断链 | 模块 | 影响 |
|------|------|------|
| hand_execute 返回值类型不匹配 | M3 | 前端拿不到 runId |
| skill-discovery tags→triggers 映射错误 | M5 | 所有技能的触发词数据错误 |
| pipeline inputs 映射为 steps | M6 | WorkflowBuilder 展示虚假步骤数据 |
| createClone 仅传 3 字段 | M2 | 人格/工作空间配置丢失 |

### 3.3 "双实现未统一"型问题

| 问题 | 模块 | 影响 |
|------|------|------|
| PersistentMemoryStore vs SqliteStorage | M4 | 双数据库数据不共享 |
| hand_approve vs approval_respond | M3 | 重复审批逻辑 |
| BrowserHand Rust vs browserHandStore 前端 | M3 | 两条完全独立的浏览器操作路径 |
| Tauri 压缩 vs Runtime 压缩 | M4 | 两套 CompactionConfig 默认值不同 |
| WhiteboardCanvas vs SceneRenderer 内联 SVG | M11 | 两套白板渲染实现 |

---

## 4. 按模块类型统计

### 安全相关（跨模块）

| 问题 | 涉及模块 | 优先级 |
|------|---------|--------|
| Gemini API Key URL 泄漏 | M1 | P2 |
| master key 明文 localStorage | M9 | P2 |
| TOTP QR 通过外部服务生成 | M7 | P2 |
| ToolOutputGuard 只 warn 不 block | M1 | P2 |
| browserHandStore 绕过审批 | M3 | P1 |
| 自主授权后端无强制 | M4 | P1 |

### 状态管理相关

| 问题 | 涉及模块 |
|------|---------|
| 共享 isLoading（非操作级） | M2 |
| Agent 切换不取消流 | M2 |
| hand-execution-complete 无人接收 | M3 |
| 心跳不自动启动 | M4 |
| 课堂数据无持久化 | M11 |

### 参数/类型一致性相关

| 问题 | 涉及模块 |
|------|---------|
| 前端 password 6 vs 后端 8 | M7 |
| types 数组 vs 单值 | M4 |
| v1 `{{}}` vs `${}` 混用 | M6 |
| WorkflowDetail 映射语义错误 | M6 |

---

## 5. 修复优先级路线图

### 第一阶段：P0 立即修复（预计 2-3 天）

1. **[M4-01]** 统一记忆存储层 — 让前端 memory_search 也查询 SqliteStorage
2. **[M4-02]** 反思引擎接入 LLM — reflection_reflect 传入实际 driver

### 第二阶段：P1 核心功能修复（预计 5-7 天）

3. **[M2-01/02]** 扩展 kernel-agent.ts createClone 字段 + 统一双通路
4. **[M3-01]** hand_execute 返回 run_id
5. **[M3-05]** 实现 timeout_secs 超时保护
6. **[M3-04]** 实现 max_concurrent 并发限制
7. **[M3-03]** browserHandStore 集成审批流程
8. **[M5-01]** 修正 skill-discovery triggers 映射
9. **[M6-01]** 注册 route_intent Tauri 命令
10. **[M6-02]** pipeline_list 支持 v2 格式
11. **[M4-03]** 自动启动心跳引擎
12. **[M4-05]** 前端记忆搜索升级 FTS5
13. **[M11-01]** 修复 blocking_lock 死锁风险
14. **[M11-03]** 课堂数据持久化

### 第三阶段：P2 健壮性提升（预计 5-7 天）

- M1: Gemini Key URL → header, ToolOutputGuard Block, Mutex unwrap
- M2: 参数验证、Agent 切换联动、SQLite 外键确认
- M3: 注册全局事件监听、审批 TTL、统一审批路径
- M4: interval 验证、identity 加密、自主映射修正
- M7: 密码校验统一、master key 安全、TOTP 本地 QR
- M8: 权限动态获取、Relay retry、API Key admin 端点
- M11: placeholder 标志、ID 冲突、导出丰富

---

## 6. 对 TRUTH.md 的更新建议

审计中发现的数字偏差：

| 条目 | TRUTH.md 当前值 | 审计实际值 | 说明 |
|------|----------------|----------|------|
| Tauri 命令无前端调用 | 24 | 需重新统计 | classroom_list/generation_progress 等新增 @reserved |
| 75 个 SKILL.md | 75 | 75 ✅ | 全部可解析，但 tools 字段未消费 |
| 11 个 Hand | 9 启用 + 2 禁用 | 9 启用，TOML 中无 enabled=false | 2 个禁用 Hand 未找到 TOML 或 Rust 实现 |
| 5 个 Pipeline 模板 | 5 | 17 个 YAML 文件 | pipelines/ 目录有更多模板 |
| Desktop 前端测试 | 0 | 0 ✅ | 仍未解决 |

---

## 7. 审计方法总结

本审计采用**混合矩阵式**方案：
- **主轴**: 11 个功能模块（M1-M11）
- **检查模板**: 五维检查（链路完整性/参数一致性/边界错误/状态管理/安全资源）
- **断链检测**: Tauri 命令调用矩阵 + 参数签名比对 + 事件链路追踪 + DB-API-UI 三端对齐
- **验证深度**: 60% 静态分析 + 30% 代码推理 + 10% 实机验证（M1/M3 加强至 20-30%）

相比前 14 轮审计的创新：
1. 首次以功能领域为主轴追踪完整调用链
2. 首次系统验证参数/类型一致性（发现了 4 处前端参数不匹配）
3. 首次验证边界场景（错误传播、空状态、并发）
4. 建立了模块级健康度基线，未来审计可增量更新