iven/zclaw_openfang
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
8e9fc54d92eb2285649dd14fa825bd2ee23b5098
zclaw_openfang/docs/features/COMPREHENSIVE_AUDIT_V9.md
iven 7de294375b
Some checks failed
CI / Lint & TypeCheck (push) Has been cancelled
Details
CI / Unit Tests (push) Has been cancelled
Details
CI / Build Frontend (push) Has been cancelled
Details
CI / Rust Check (push) Has been cancelled
Details
CI / Security Scan (push) Has been cancelled
Details
CI / E2E Tests (push) Has been cancelled
Details
feat(auth): 添加异步密码哈希和验证函数 
refactor(relay): 复用HTTP客户端和请求体序列化结果

feat(kernel): 添加获取单个审批记录的方法

fix(store): 改进SaaS连接错误分类和降级处理

docs: 更新审计文档和系统架构文档

refactor(prompt): 优化SQL查询参数化绑定

refactor(migration): 使用静态SQL和COALESCE更新配置项

feat(commands): 添加审批执行状态追踪和事件通知

chore: 更新启动脚本以支持Admin后台

fix(auth-guard): 优化授权状态管理和错误处理

refactor(db): 使用异步密码哈希函数

refactor(totp): 使用异步密码验证函数

style: 清理无用文件和注释

docs: 更新功能全景和审计文档

refactor(service): 优化HTTP客户端重用和请求处理

fix(connection): 改进SaaS不可用时的降级处理

refactor(handlers): 使用异步密码验证函数

chore: 更新依赖和工具链配置
2026-03-29 21:45:29 +08:00

309 lines
16 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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 审计发现的根本问题集中在一条断裂的数据链路上：
**`对话 → 记忆提取 → 存储 → 检索 → 注入 → 增强回复`**
当前状态:
1. LlmDriverForExtraction 的实现 (BREAK-01) — **已修复**: extraction_adapter.rs 实现 TauriExtractionDriver
2. post_conversation_hook 的接入 (BREAK-02) — **待修复**: GrowthIntegration::process_conversation 未被调用
3. 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/加密实现安全。
### 最大改进方向
1. **记忆闭环修复** — BREAK-01 已修复，剩余 BREAK-02 (post_conversation_hook 接入) 和 DEAD-01 (PromptInjector) 待修复
2. **文档更新** — 130 个命令只记录了 58 个，严重低估
3. **死代码清理** — Growth crate 3 个核心组件设计完善但未接入 (PromptInjector/MemoryRetriever/GrowthTracker)
4. **Admin 补全** — 操作日志、同步日志、设备管理页面缺失
5. **SaaS 架构优化** — Worker + Scheduler 已上线，连接池已优化，未来可迁移到 Redis 队列
Reference in New Issue View Git Blame Copy Permalink