ZCLAW 全面系统审计报告 V9
审计日期: 2026-03-29
审计范围: 全量四端审计 — SaaS 后端 + Tauri 桌面端 + Admin 管理后台 + Rust Crates
审计方法: V8 基线重验证 + 五步审计流程 + 十项通用检查 + 五种差距模式 + 安全专项
前次审计: V8 (2026-03-29, 发现 12 差距 + 5 安全)
本次审计: 8 Agent 并行执行，覆盖 11 crate / 130+ Tauri 命令 / 76+ API 端点 / 55+ 组件
一、执行摘要
| 指标 |
V8 数值 |
V9 数值 |
变化 |
| SaaS API 端点 |
76+ |
76+ |
不变 |
| Tauri 命令 |
150+ |
130 |
修正 (文档从 58+ 修正) |
| Admin 页面 |
12 |
12 |
不变 |
| 文档-代码对齐率 |
~95% |
~95% |
不变 |
| 数据流连通率 |
60% (3/5) |
65% (4/6 部分连通, 1 断裂) |
提升 |
| Dead Code |
28+ #[allow(dead_code)] |
18 (desktop) + 13 (crates) |
减少 |
| 安全漏洞 |
1 CRITICAL + 2 HIGH |
0 HIGH + 2 MEDIUM (SEC-V9-01 确认为误报) |
改善 |
| 差距模式 |
12 个 |
14 个 (新增 4, 修复 8, 保留 4, 误报消除 2) |
改善 |
| 整体完成度 |
~82% |
~85% |
提升 |
V8 修复确认
| V8_ID |
描述 |
V8级别 |
V9状态 |
| SEC-01 |
agent_template SQL 注入 |
CRITICAL |
FIXED — 已改用 $N 参数化查询 |
| SEC-02 |
prompt/service.rs SQL 注入 |
HIGH |
STILL_PRESENT — 行 94/97/100 仍用 format!() |
| SEC-03 |
config sync 缺权限 |
HIGH |
FIXED — check_permission 已到位 |
| G-01 |
遥测零调用 |
P0 |
FIXED — llm-service.ts 已调用 |
| G-02 |
startPromptOTASync 未调用 |
P1 |
FIXED — saasStore.ts 多处调用 |
| G-03 |
relay 队列未消费 |
P1 |
PARTIALLY_FIXED — 队列容量已检查，per-provider 并发未实现 |
| G-04 |
心跳不传 OS/version |
P1 |
FIXED — 已传 platform + app_version |
| G-05 |
config diff/sync 未调用 |
P1 |
FIXED — 双向同步已实现 |
| G-06 |
telemetry 不写 operation_logs |
P2 |
FIXED — 已调用 log_operation |
| G-07 |
account_api_keys 被 relay 绕过 |
P2 |
STILL_PRESENT — relay 使用独立 key_pool |
| G-08 |
Desktop 401 不 logout |
P2 |
FIXED — token 刷新失败时清理会话 |
| G-09 |
心跳不写 operation_logs |
P2 |
STILL_PRESENT — 高频操作合理 |
| G-10 |
hand_run 桩命令 |
P3 |
FALSE_POSITIVE — 有真实实现 |
| G-12 |
双端错误类型不统一 |
P3 |
STILL_PRESENT — SaaSApiError vs ApiRequestError |
修复率: 8/12 FIXED + 1 PARTIALLY_FIXED + 1 FALSE_POSITIVE + 2 STILL_PRESENT = 75% 修复率
二、功能清单与完成度矩阵
2.1 架构层
| 功能 |
设计目标 |
完成度 |
关键发现 |
| 通信层 |
三模式连接 (Kernel/Gateway/SaaS) |
90% |
完整；130 个 Tauri 命令 vs 文档声称 58+ |
| 状态管理 |
18+ Zustand Store |
80% |
audit-logger.ts 无消费者 |
| 安全认证 |
Ed25519+JWT+TOTP |
85% |
SSRF 防护全面；relay 输入验证可加强 |
2.2 核心功能
| 功能 |
设计目标 |
完成度 |
关键发现 |
| 聊天界面 |
流式响应+多模型 |
92% |
完整链路通畅 |
| Agent 分身 |
CRUD+模板+切换 |
85% |
导入/导出未实现 |
| Hands 系统 |
9+ 自主能力 |
70% |
Predictor/Lead 无代码；审批后不自动执行 |
2.3 智能层
| 功能 |
设计目标 |
完成度 |
V9 修正 |
关键发现 |
| Agent 记忆 |
跨会话+语义搜索 |
90% |
- |
检索可用，但自动提取链路断裂 |
| 身份演化 |
SOUL.md+自动改进 |
90% |
↑ (文档称 70%) |
persona_evolver 等 4 个模块已删除但功能完整 |
| 反思引擎 |
自动分析+建议 |
85% |
↑ (文档称 65%) |
LLM 集成完整，VikingStorage 持久化 |
| 心跳巡检 |
定期巡检+提醒 |
90% |
↑ (文档称 70%) |
894 行完整实现，10 个 Tauri 命令 |
| 自主授权 |
三级授权+审批 |
75% |
- |
审批通过后不自动执行 (设计缺陷) |
| 上下文压缩 |
智能摘要 |
90% |
↑ (文档称 75%) |
规则+LLM 摘要均已实现 |
2.4 平台层
| 功能 |
设计目标 |
完成度 |
关键发现 |
| 技能系统 |
70 SKILL.md |
80% |
WASM/Native 未实现 |
| 智能路由 |
语义匹配 |
50% |
SemanticSkillRouter 核心未实现 |
| Pipeline DSL |
YAML 工作流 |
87% |
pipeline-complete 事件未监听 |
| SaaS 平台 |
云端能力 |
90% |
Worker + Scheduler 系统上线；SQL 迁移 Schema v6；多环境配置；prompt SQL 注入已确认为误报 |
2.5 智能层评分汇总
| 模块 |
评分 |
说明 |
| zclaw-growth |
70% |
ExtractionDriver 已修复 (BREAK-01)，PromptInjector/MemoryRetriever/GrowthTracker 仍未接入 |
| intelligence/ |
78% |
功能完整度好 |
| zclaw-pipeline |
87% |
实现质量高 |
| zclaw-memory |
78% |
CRUD 完整，测试充分 |
| 整体 |
~85% |
记忆闭环部分接通 (BREAK-01 已修复)，剩余 BREAK-02 和 PromptInjector 待接入 |
三、关键发现
3.1 安全发现
| ID |
严重度 |
组件 |
描述 |
证据 |
| SEC-V9-01 |
HIGH → FALSE_POSITIVE |
prompt/service.rs |
SQL 注入: format!() 仅构建 $N 参数占位符索引，实际值通过 .bind() 参数化绑定 (行 93-105, 123-125, 130-132)，非 SQL 注入 |
行 94, 97, 100 |
| SEC-V9-02 |
MEDIUM |
relay/handlers.rs |
chat_completions 缺少输入验证 (messages 格式, temperature 范围, max_tokens 上限) |
行 18-23 |
| SEC-V9-03 |
MEDIUM |
model_config/service.rs |
query.bind(format!("{}", p)) 类型强制转换 |
行 134 |
3.2 功能断裂
| ID |
严重度 |
组件 |
描述 |
证据 |
| BREAK-01 |
CRITICAL → FIXED |
zclaw-growth |
LlmDriverForExtraction 无生产实现: extraction_adapter.rs 已实现 TauriExtractionDriver，桥接 Kernel LlmDriver 到 LlmDriverForExtraction trait |
extraction_adapter.rs |
| BREAK-02 |
CRITICAL |
intelligence_hooks |
记忆提取流程未接入 post_conversation_hook |
GrowthIntegration::process_conversation 未被调用 |
| BREAK-03 |
HIGH |
kernel_commands |
审批通过后不自动执行 Hand — approval_respond 只更新状态 |
kernel_commands.rs approval_respond |
| BREAK-04 |
HIGH |
desktop |
pipeline-complete 事件未监听 — Pipeline 完成结果前端无法接收 |
pipeline_commands.rs:480 emit 无对应 listen |
3.3 Dead Code
| ID |
严重度 |
位置 |
描述 |
| DEAD-01 |
HIGH |
zclaw-growth/injector.rs |
PromptInjector 全文件死代码 (4 种格式, token 预算控制) |
| DEAD-02 |
HIGH |
zclaw-growth/retriever.rs |
MemoryRetriever 全文件死代码 (QueryAnalyzer + MemoryCache) |
| DEAD-03 |
MEDIUM |
zclaw-growth/tracker.rs |
GrowthTracker 全文件死代码 |
| DEAD-04 |
MEDIUM |
zclaw-kernel/director.rs |
907 行，零生产调用者 |
| DEAD-05 |
MEDIUM |
desktop/saas-client.ts |
39 个方法从未被调用 (Admin-only API) |
| DEAD-06 |
LOW |
desktop/audit-logger.ts |
无任何消费者 |
| DEAD-07 |
LOW |
intelligence/validation.rs |
全文件保留为 "future API" |
3.4 文档过时
| ID |
严重度 |
文档 |
描述 |
| DOC-01 |
HIGH |
06-tauri-backend |
声称 58+ 命令，实际 130 |
| DOC-02 |
HIGH |
02-intelligence-layer |
6 个文档引用已删除模块 (persona_evolver 等) |
| DOC-03 |
MEDIUM |
00-agent-memory |
声称 90% 但未说明提取链路断裂 |
| DOC-04 |
MEDIUM |
03-openviking |
描述外部服务器，实际为内部 SqliteStorage |
| DOC-05 |
LOW |
README.md |
SKILL.md 数量 69 → 实际 70 |
四、十项通用检查结果
| # |
检查项 |
判定 |
关键发现 |
| 1 |
代码存在性 |
PASS |
11 crate 全部确认；SKILL 70 vs 文档 69 |
| 2 |
调用链连通性 |
PASS |
SaaS handler 100% 连通 |
| 3 |
配置参数完整性 |
WARN |
batch_window_ms / max_concurrent_per_provider 预留标注，burst 已消费 |
| 4 |
降级策略 |
PASS |
3 种连接模式 + 心跳降级 + 离线队列 |
| 5 |
错误处理 |
PASS |
16 种 SaaS 错误 + 10 种前端分类 + 401 自动登出 |
| 6 |
日志完整性 |
WARN |
auth/refresh 缺日志；前端 audit-logger 无消费者 |
| 7 |
性能监控 |
PASS |
全 list 端点分页；Dashboard 2 查询聚合 |
| 8 |
安全控制 |
PASS |
SSRF 全面防护；relay 输入验证可加强 |
| 9 |
兼容性 |
PASS |
Rust edition 统一；TS strict；Tauri 2.x |
| 10 |
文档-代码同步 |
WARN |
Hands 数量不一致；Tauri 命令数严重低估 |
总计: 7 PASS / 3 WARN / 0 FAIL
五、五种差距模式实例
模式 1: "写了没接" (代码存在但未被调用)
| 项目 |
位置 |
影响 |
| 39 个 saas-client.ts 方法 |
desktop/src/lib/saas-client.ts |
Admin-only API 暴露在桌面端 |
| ~45 个 Tauri 命令 |
desktop/src-tauri/src/lib.rs |
注册但前端未 invoke |
| PromptInjector (全文件) |
zclaw-growth/injector.rs |
设计完善的 token 预算控制完全未用 |
| MemoryRetriever (全文件) |
zclaw-growth/retriever.rs |
QueryAnalyzer + MemoryCache 未用 |
| GrowthTracker (全文件) |
zclaw-growth/tracker.rs |
成长指标追踪未用 |
| director.rs (907 行) |
zclaw-kernel/director.rs |
多 Agent 编排零生产调用 |
| 7 个 SaaS 端点 |
crates/zclaw-saas/src/ |
无 Admin 页面调用 |
模式 2: "接了没传"
| 项目 |
位置 |
说明 |
| 心跳 OS 版本 |
saas-client.ts:763 |
传 navigator.platform 而非真实 OS 版本 |
| Relay 优先级 |
relay/handlers.rs |
客户端无法指定 priority |
| 智能记忆 scope |
intelligence-client.ts |
find() 回退模式忽略 scope 参数 |
模式 3: "传了没存"
| 项目 |
位置 |
说明 |
| account_api_keys |
relay/key_pool.rs |
用户 API 密钥存储但 relay 从未读取 |
模式 4: "存了没用"
| 项目 |
位置 |
说明 |
| operation_logs |
admin/src/app/ |
无专门查看页面 |
| config_sync_logs |
admin/src/app/ |
无 Admin 页面 |
| account_api_keys |
relay/key_pool.rs |
relay 使用独立 provider_keys |
| relay_tasks 统计 |
admin/src/app/ |
无聚合分析页面 |
| devices 表 |
admin/src/app/ |
无设备管理页面 |
模式 5: "双系统不同步"
| 项目 |
Desktop |
Admin |
差异 |
| OperationLog |
details: Record<string, unknown> |
details?: string |
类型不匹配 |
| AccountPublic |
role: string |
role: union type |
类型严格度不同 |
| LoginResponse |
无 refresh_token |
无 refresh_token |
两端都缺 (后端返回) |
| ProviderInfo |
api_protocol: string |
api_protocol: union |
枚举 vs 字符串 |
| Token 刷新 |
clearSaaSSession 回退 |
window.location 跳转 |
策略不同 |
| RelayTaskInfo |
error: string | null |
error?: string |
nullable vs optional |
六、修复计划 (按优先级)
P0: 阻断级 (安全漏洞)
| # |
问题 |
修复方案 |
工作量 |
1 |
SEC-V9-01: prompt/service.rs SQL 注入 |
已确认为误报: format!() 仅构建 $N 占位符索引，值通过 .bind() 绑定 |
1h 已完成 |
P1: 严重级 (功能断裂)
| # |
问题 |
修复方案 |
工作量 |
2 |
BREAK-01: LlmDriverForExtraction 无实现 |
已完成: extraction_adapter.rs 实现 TauriExtractionDriver |
4h 已完成 |
| 3 |
BREAK-02: 记忆提取未接入 post_hook |
将 GrowthIntegration::process_conversation() 接入 post_conversation_hook |
2h |
| 4 |
BREAK-03: 审批后不自动执行 |
在 approval_respond 中，approved=true 时自动触发对应 Hand 执行 |
3h |
| 5 |
BREAK-04: pipeline-complete 未监听 |
在 workflowStore 或 pipeline-client 中添加 listen('pipeline-complete') |
1h |
P2: 高优先级 (质量改进)
| # |
问题 |
修复方案 |
工作量 |
| 6 |
DEAD-01/02/03: Growth 死代码 |
评估是否接入或清理 PromptInjector/MemoryRetriever/GrowthTracker |
8h |
| 7 |
DEAD-05: 39 个未调用 saas-client 方法 |
评估是否需要桌面端 Admin 功能入口或移除方法 |
2h |
| 8 |
DOC-01/02: 文档严重过时 |
更新 Tauri 命令数 (130)、智能层模块状态 |
3h |
| 9 |
类型不一致 (6 组) |
统一 Desktop 和 Admin 类型定义 |
4h |
| 10 |
G-07: account_api_keys 被 relay 绕过 |
决策：统一 key 管理或标记 account_api_keys 为独立功能 |
3h |
P3: 中优先级 (技术债务)
| # |
问题 |
修复方案 |
工作量 |
| 11 |
配置参数孤儿 (batch_window_ms 等) |
实现消费或移除配置项 |
2h |
| 12 |
relay 输入验证加强 |
添加 messages 数组、temperature、max_tokens 基本校验 |
2h |
| 13 |
前端 audit-logger 集成 |
在 Hand 触发、Agent CRUD 中调用 auditLogger |
2h |
| 14 |
DEAD-04: director.rs 907 行孤立 |
移至 feature flag 后面或文档标注为未来功能 |
1h |
| 15 |
config_sync_logs Admin 页面 |
添加 Admin 同步日志查看页面 |
3h |
| 16 |
operation_logs Admin 页面 |
添加 Admin 操作日志查看页面 |
2h |
P4: 低优先级 (可选改进)
| # |
问题 |
修复方案 |
工作量 |
| 17 |
SKILL.md 数量更新 (69→70) |
更新 README.md |
5min |
| 18 |
Hands 数量统一 (CLAUDE.md vs README) |
统一口径 |
5min |
| 19 |
zclaw-channels 评估 |
决定保留或删除近乎空的 crate |
1h |
| 20 |
trigger_update 接口不匹配 |
TS 传 {id, updates} vs Rust 期望平铺参数 |
2h |
总工作量估计: P0 (1h) + P1 (4h 已完成) + P1 (6h 剩余) + P2 (20h) + P3 (10h) + P4 (4h) = ~40h (已完成 5h)
七、架构健康度评分
| 模块 |
评分 |
趋势 |
关键问题 |
| zclaw-types |
95% |
→ |
基础类型，稳定 |
| zclaw-memory |
78% |
→ |
与 zclaw-growth 存储边界模糊 |
| zclaw-runtime |
85% |
→ |
4 个 LLM Driver 完整 |
| zclaw-kernel |
80% |
→ |
Director 死代码 |
| zclaw-skills |
80% |
→ |
WASM/Native 待实现 |
| zclaw-hands |
70% |
→ |
2 个 Hand 无代码 |
| zclaw-protocols |
65% |
↓ |
A2A feature-gated，MCP 最小实现 |
| zclaw-pipeline |
87% |
→ |
高质量实现 |
| zclaw-growth |
70% |
↑ |
TauriExtractionDriver 已实现 (BREAK-01 修复)，PromptInjector/MemoryRetriever/GrowthTracker 仍未接入 |
| zclaw-channels |
20% |
↓ |
仅 ConsoleChannel |
| zclaw-saas |
92% |
↑ |
Worker + Scheduler + SQL 迁移 v6 + 多环境配置；SQL 注入确认为误报 |
| Desktop 前端 |
82% |
→ |
降级策略完善 |
| Admin 后台 |
85% |
→ |
缺日志/同步日志页面 |
| 整体 |
~85% |
↑ |
核心功能可用，记忆闭环部分修复 (BREAK-01 已修复)，SaaS Worker/Scheduler 系统上线 |
八、核心结论
根因分析
V9 审计发现的根本问题集中在一条断裂的数据链路上：
对话 → 记忆提取 → 存储 → 检索 → 注入 → 增强回复
当前状态:
- LlmDriverForExtraction 的实现 (BREAK-01) — 已修复: extraction_adapter.rs 实现 TauriExtractionDriver
- post_conversation_hook 的接入 (BREAK-02) — 待修复: GrowthIntegration::process_conversation 未被调用
- PromptInjector 替代字符串拼接 (DEAD-01) — 待修复: PromptInjector 全文件死代码
修复 BREAK-01 后，记忆提取的 LLM 驱动问题已解决。剩余 2 项修复后，智能层的完成度将从 70% 跃升至 85%+。
安全状态
V8 的 CRITICAL (agent_template SQL 注入) 已修复。V9 的 SEC-V9-01 (prompt SQL 注入) 已确认为误报 (format!() 仅构建参数占位符索引，实际值通过 .bind() 绑定)。仅剩 2 个 MEDIUM 级安全发现 (relay 输入验证、类型强制转换)。SSRF 防护全面，Auth 覆盖完整，密码/TOTP/加密实现安全。
最大改进方向
- 记忆闭环修复 — BREAK-01 已修复，剩余 BREAK-02 (post_conversation_hook 接入) 和 DEAD-01 (PromptInjector) 待修复
- 文档更新 — 130 个命令只记录了 58 个，严重低估
- 死代码清理 — Growth crate 3 个核心组件设计完善但未接入 (PromptInjector/MemoryRetriever/GrowthTracker)
- Admin 补全 — 操作日志、同步日志、设备管理页面缺失
- SaaS 架构优化 — Worker + Scheduler 已上线，连接池已优化，未来可迁移到 Redis 队列
7de294375b