2e5f63be32
Some checks failed
CI / Lint & TypeCheck (push) Has been cancelled
CI / Unit Tests (push) Has been cancelled
CI / Build Frontend (push) Has been cancelled
CI / Rust Check (push) Has been cancelled
CI / Security Scan (push) Has been cancelled
CI / E2E Tests (push) Has been cancelled
- Create docs/brainstorming/ with 5 discussion records (Mar 16 - Apr 7) - Archive ~30 outdated audit reports (V5-V11) to docs/archive/old-audits/ - Archive superseded analysis docs to docs/archive/old-analysis/ - Archive completed session plans to docs/archive/old-plans/ - Archive old test reports/validations to respective archive folders - Remove empty directories left after moves - Keep current docs: TRUTH.md, feature docs, deployment, knowledge-base, superpowers
8.2 KiB
8.2 KiB
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 天）
- [M4-01] 统一记忆存储层 — 让前端 memory_search 也查询 SqliteStorage
- [M4-02] 反思引擎接入 LLM — reflection_reflect 传入实际 driver
第二阶段：P1 核心功能修复（预计 5-7 天）
- [M2-01/02] 扩展 kernel-agent.ts createClone 字段 + 统一双通路
- [M3-01] hand_execute 返回 run_id
- [M3-05] 实现 timeout_secs 超时保护
- [M3-04] 实现 max_concurrent 并发限制
- [M3-03] browserHandStore 集成审批流程
- [M5-01] 修正 skill-discovery triggers 映射
- [M6-01] 注册 route_intent Tauri 命令
- [M6-02] pipeline_list 支持 v2 格式
- [M4-03] 自动启动心跳引擎
- [M4-05] 前端记忆搜索升级 FTS5
- [M11-01] 修复 blocking_lock 死锁风险
- [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 轮审计的创新：
- 首次以功能领域为主轴追踪完整调用链
- 首次系统验证参数/类型一致性（发现了 4 处前端参数不匹配）
- 首次验证边界场景（错误传播、空状态、并发）
- 建立了模块级健康度基线，未来审计可增量更新