zclaw_openfang/docs/superpowers/specs/2026-04-04-module-audit-design.md

ZCLAW 模块化端到端深度功能验证审计方案

版本: v1.1 (review fix) 日期: 2026-04-04 状态: 设计完成，待执行 审计目标: 端到端功能验证——系统性找出每个模块从 UI 到后端的断链

---

1. 背景与动机

ZCLAW 项目已有 14 次审计历史（V1-V11 共 11 轮版本化审计 + 3 轮专项审计），前几轮以"技术层横向扫描"为主：检查 Tauri 命令调用率、SaaS API 前端消费、死代码清理等。这些审计修复了大量问题，但存在三个结构性盲区：

1. 缺乏功能视角 — 已知 24 个 Tauri 命令无前端调用，但不知属于哪些用户故事
2. 缺乏边界验证 — 只查"调了没有"，没查"调错了怎么表现"、"空数据怎么表现"
3. 缺乏累积性 — 每轮从头扫，无模块级基线

本方案以功能领域为主轴组织审计，以标准化的五维检查清单确保不遗漏，以三波并行策略高效执行。

---

2. 审计模块划分

模块清单

模块	功能领域	核心链路	涉及关键文件
M1	智能对话	用户输入 → ChatArea → chatStore → Kernel → LLM Driver → 流式回传	components/ai/*, store/chat/*, lib/kernel-chat.ts, kernel_commands/chat.rs, zclaw-runtime/src/driver/*
M2	Agent 分身	创建/切换/配置 Agent → agentStore → Kernel → SQLite	agentStore.ts, lib/kernel-agent.ts, kernel_commands/agent.rs, zclaw-memory/src/agent_store.rs
M3	Hands 自主能力	触发 Hand → handStore → Kernel → Hand 执行 → 事件回调	handStore.ts, lib/kernel-hands.ts, crates/zclaw-hands/src/hands/*, hands/*.HAND.toml
M4	智能层	记忆/身份/反思/心跳/自主授权/压缩 各链路	intelligence-client/*, store/memoryGraphStore.ts, intelligence/*.rs
M5	技能生态	技能浏览/搜索/执行 → Skills 语义路由 → SKILL.md	lib/kernel-skills.ts, crates/zclaw-skills/src/*, skills/*.md
M6	Pipeline 工作流	创建/编辑/执行 Pipeline → workflowStore → DSL Engine	components/pipeline/*, workflowStore.ts, crates/zclaw-pipeline/src/*
M7	SaaS 平台(Desktop)	登录/配置/支付 → saasStore → saas-client → SaaS API	components/SaaS/*, saasStore.ts, lib/saas-client.ts, crates/zclaw-saas/src/*
M8	Admin V2	14 页面 CRUD → 18 services → SaaS API → PostgreSQL	admin-v2/src/pages/*, admin-v2/src/services/*
M9	通信与安全	连接管理/认证/TOTP/加密/限流/MCP 协议	connectionStore.ts, securityStore.ts, gateway-client.ts, lib/mcp-client.ts, crates/zclaw-saas/src/auth/*, crates/zclaw-protocols/src/mcp/*
M10	横切关注点	错误一致性、类型一致性、并发安全（汇总分析）	全局横切
M11	Classroom 课堂	课堂场景播放/聊天/笔记/白板/TTS	store/classroomStore.ts, components/classroom_player/*, lib/classroom-adapter.ts

---

3. 五维检查模板

每个模块必须完成以下五个维度的检查：

维度 1: 链路完整性

• 画出该模块的完整调用链（UI → Store → Client → IPC/API → Rust → DB/网络）
• 标注每个节点的文件路径
• 检查每条边的连通性（"写了没接"检查）

维度 2: 参数/类型一致性

检查点	方法
前端调用参数 vs Rust 命令签名	逐字段比对名称、类型、Optionality
返回值类型链路	Rust struct → Tauri IPC → TS type → Store state
枚举值/常量两端同步	比对 Rust enum 与 TS union type
数据库字段与 API 字段对齐	SQL 列 vs handler struct field

维度 3: 边界与错误处理

场景	检查内容
空状态	数据库无数据时 UI 表现；空字符串/空数组/null 参数传递
错误状态	网络 5xx / 4xx / 超时 / 序列化失败 → 是否有用户可见反馈
并发	快速双击；多操作并行；Token 刷新并发
性能降级	大数据量（1000+ 消息）；FTS 全表扫描；连接池满
输入边界	超长文本、特殊字符、非 UTF-8、负数、零值

维度 4: 状态管理

• Store 状态机完整性（loading / success / error / reset）
• 组件是否正确订阅 Store 变化
• 持久化/恢复路径是否完整
• 竞态条件风险（stale closure、过期 setState）

维度 5: 安全与资源

• 敏感数据加密/脱敏
• 资源泄漏（事件监听器未清理、定时器未清除、连接未释放）
• 权限检查完整性
• 日志是否包含敏感信息

---

4. 断链检测方法

步骤 1: Tauri 命令调用矩阵

对模块涉及的所有 Tauri 命令:
  1. 从 kernel_commands/mod.rs 提取 #[tauri::command] 注册名
  2. grep desktop/src/ 找 invoke('commandName') 调用
  3. 对比 → 标注 connected / reserved / broken

步骤 2: 参数签名级比对

对每个 connected 命令:
  1. 提取 Rust 端参数类型定义 (struct/derive)
  2. 提取 TS 端调用参数
  3. 逐字段比对名称/类型/Optionality
  4. 不匹配 → 记为 P1 断链

步骤 3: 事件链路追踪

  1. grep desktop/src-tauri/src/ 找 .emit("event-name") 发射点
  2. grep desktop/src/ 找 .listen("event-name") 监听点
  3. 交叉比对 → 找出 emit 但无 listen 的断裂

步骤 4: 数据库-API-UI 三端对齐

  1. grep crates/zclaw-saas/src/ 找 SELECT/INSERT 语句
  2. 对比 API handler 暴露的端点
  3. 对比前端 service 层调用
  4. 找出"有表无 API" 或 "有 API 前端未调"

---

5. 边界验证方法

采用三层验证策略：

第一层: 静态分析（工具辅助，60% 工作量）

检查	命令
TypeScript 类型安全	tsc --noEmit
Rust 编译检查	cargo check
潜在 panic	grep -rn "unwrap()" crates/
静默忽略	grep -rn "let _ =" crates/
类型逃逸	grep -rn "as any" desktop/src/
技术债标记	grep -rn "TODO|FIXME|HACK"

第二层: 代码推理（人工审查，30% 工作量）

对每条链路的每个"edge"，推理：

• 上游返回 null/undefined/Err 时，下游如何处理？
• 上游超时 30s 无响应，UI 如何表现？
• 用户在 loading 期间切换页面，状态如何恢复？

第三层: 实机验证（P0/P1 必须，高频模块加强）

标准模块（M2/M4-M11）: 10% 工作量，仅 P0/P1 级发现做实机验证。

高频模块（M1/M3）: 20-30% 工作量，除 P0/P1 外还需验证：

• 并发场景：快速连续发送消息、快速连续触发 Hand
• 流式中断：中途断网、切换模型、切换 Agent
• 大数据场景：1000+ 消息加载、长时间会话压缩

实机验证启动命令：pnpm start:dev

• 空数据场景：清空相关表，验证 UI 不崩溃
• 错误场景：关闭后端服务，验证前端降级提示
• 并发场景：快速连续触发同一操作

---

6. 优先级分级标准

级别	定义	示例	修复时限
P0	必然崩溃或数据丢失，用户无法绕过	skill_execute 空参数导致 serde panic	立即
P1	功能失效但不崩溃；核心功能断链	API 路径 404、参数不匹配静默失败	24h
P2	功能部分可用但不完整；可能演变为 P1	静默忽略错误、fire-and-forget spawn	1 周
P3	不影响功能但影响可维护性	类型命名不一致、文档数字偏差	下个迭代
P4	信息级建议改进	配置参数预留未消费、feature-gated 未启用	backlog

判断流程

用户是否看到异常？ → 是 → P0/P1
数据是否丢失/损坏？ → 是 → P0
核心路径是否受阻？ → 是 → P1
是否可能引发 P1？ → 是 → P2
是否仅影响开发者体验？ → 是 → P3/P4

---

7. 执行策略

执行假设与节奏

• 执行者假设: 单人执行（AI Agent 辅助 + 人工决策）
• 模块粒度: 每模块约 1 个工作日（含五维检查 + 报告编写）
• 总工期: 11 个工作日（11 模块 x 1 天/模块），跨约 2.5 周

波次安排

波次	模块	耗时	说明
第一波	M1(对话) + M2(Agent) + M3(Hands)	3 天	核心路径，历史断链最密集区
第二波	M4(智能层) + M5(技能) + M6(Pipeline)	3 天	智能与编排
第三波	M7(SaaS) + M8(Admin) + M11(Classroom)	3 天	平台层
第四波	M9(通信安全) + M10(横切汇总)	2 天	基础设施+全量汇总

每波内模块顺序执行（单 Agent 每日 1 模块），避免 context 窗口溢出。

模块内部执行顺序

五维检查串行执行：链路图 → 参数比对 → 边界验证 → 状态管理 → 安全检查

---

8. 报告格式

每个模块独立输出一份审计报告，格式如下：

# 模块 [Mx] [模块名] 审计报告

## 1. 模块概况
- 功能描述
- 涉及文件清单（按层分类）
- 调用链路图
- 前次审计已知问题继承

## 2. 五维检查结果

### 2.1 链路完整性
| 链路 | 起点 | 终点 | 状态 | 断裂点 |

### 2.2 参数/类型一致性
| 接口 | 前端类型 | 后端类型 | 一致性 | 不匹配字段 |

### 2.3 边界与错误处理
| 场景 | 输入 | 预期行为 | 实际行为 | 级别 |

### 2.4 状态管理
| Store | 状态机完整性 | 持久化 | 竞态风险 |

### 2.5 安全与资源
| 检查项 | 状态 | 说明 |

## 3. 问题清单
| ID | 描述 | 文件:行号 | 级别 | 修复建议 | 验证方法 |

## 4. 改进建议
- 短期修复项（按优先级排序）
- 长期架构建议

最终汇总为 docs/features/MODULE_AUDIT_SUMMARY.md，包含：

• 各模块问题统计表
• P0/P1 问题优先修复清单
• 整体健康度评分
• 对 TRUTH.md 数字更新的建议

---

9. 与已有审计的衔接

• 继承 AUDIT_TRACKER.md：每个模块开头从已有追踪表继承已知问题
• 更新 TRUTH.md：审计中发现的数字偏差回写真相源
• 延续版本线：本审计为 V12（第 15 次），报告编号继续递增
• 新 P0 处理流程：审计中发现的 P0 级问题立即中断当前模块审计，优先修复并验证，再继续审计
• 避免重复：已标记为"已修复"的问题仅做验证性检查，不重新审计

---

10. 前几轮审计盲区（本次重点关注）

盲区	说明	本次覆盖维度
Store 状态机完整性	前几轮几乎未检查 loading/error/reset	维度 4
错误传播链路	后端 Err 是否能传到 UI	维度 3
事件监听对称性	emit 但无 listen 的断裂	维度 1
并发安全	约 15 处 fire-and-forget spawn 未审计	维度 5
空数据降级	Desktop 端空数据表现未验证	维度 3
Desktop 前端零测试	边界验证只能靠代码推理+实机	维度 3，M1/M3 加强实机验证
Classroom 课堂	27 个 Tauri 命令中 7 个无前端调用，未审计	新增 M11
MCP 协议链路	MCP 服务发现→工具列举→执行 链路未验证	M9 增加检查项