20 KiB
20 KiB
ZCLAW SaaS + Tauri 系统性功能审计报告 v6
ARCHIVED — 此报告已过时
本报告是 2026-03-27 审计迭代的 v6 版本。最终结论已合并到 DEEP_AUDIT_REPORT.md。
请参考最新文档 → README.md
审计日期: 2026-03-27 (原文标注 2026) 审计范围: Main 分支 Tauri 端 + SaaS worktree（
.claude/worktrees/saas-backend/） 审计方法: 3 并行 Agent，覆盖功能对齐、SaaS 差距、Trait 实现、差距模式、Dead Code、E2E 数据流 前次审计: v5（累计修复 27 项，整体完成度 ~78%）
一、执行摘要
| 指标 | 数值 |
|---|---|
| Tauri 注册命令 | 137 |
| 文档功能数 | 17 |
| 功能-代码对齐率 | 100%（17/17 有对应命令+UI） |
| SaaS 能力覆盖 | 5/5（100%）— auth + relay + config + devices + usage（设计定位：系统管理） |
| Trait 总数 | 26 |
| 零实现 Trait | 6（23%） |
| Dead Code | ~4,228 行（5 个孤立模块） |
#[allow(dead_code)] |
28 处 |
| TODO/FIXME | 6 处（无 FIXME/HACK/XXX） |
| 五种差距模式总计 | 17 个问题 |
| E2E 流程验证 | 5 条流程，2 条有 CRITICAL GAP |
与 v5 审计对比
| 维度 | v5 | v6（本次） | 变化 |
|---|---|---|---|
| 整体完成度 | ~78% | ~78%（Tauri），100%（SaaS 管理职责） | SaaS 定位修正 |
| 功能对齐 | 未量化 | 100% | 新增量化 |
| Trait 覆盖 | 未审计 | 77%（20/26 有实现） | 新增审计 |
| Dead Code | 已部分清理 | ~4,228 行孤立 | 新增精确统计 |
| E2E 验证 | 未执行 | 5 条流程追踪 | 新增验证 |
二、功能-代码对齐矩阵
2.1 功能清单（17 个文档功能）
| # | 功能 | 文档成熟度 | Tauri 命令数 | 前端 invoke | UI 集成 | 差距 |
|---|---|---|---|---|---|---|
| 1 | 通信层 | L4 | 9 | kernel-client.ts | KernelClient + GatewayClient | 无 |
| 2 | 状态管理 | L4 | N/A（Store） | N/A | 18+ Zustand stores | 无 |
| 3 | 安全认证 | L4 | 4 | secure-storage.ts | Ed25519 + OS Keyring | 无 |
| 4 | 聊天界面 | L4 | 2 | kernel-client.ts | ChatArea, MessageItem | 无 |
| 5 | Agent 分身 | L4 | 4 | kernel-client.ts | AgentSelector | 无 |
| 6 | Hands 系统 | L4 | 7 | kernel-client.ts | HandList, HandTaskPanel | 2/11 未实现 |
| 7 | Agent 记忆 | L4 | 13 | intelligence-backend.ts | MemoryPanel, MemoryGraph | 无 |
| 8 | 身份演化 | L4 | 14 | intelligence-backend.ts | AgentOnboardingWizard | 无 |
| 9 | 自我反思 | L4 | 6 | intelligence-backend.ts | ReflectionLog.tsx | 文档有 L2 矛盾标注 |
| 10 | 心跳巡检 | L4 | 10 | intelligence-backend.ts | IntelligenceStore | 无 |
| 11 | 自主授权 | L4 | 0（TS only） | N/A | AutonomyConfig.tsx | 无 Rust 后端 |
| 12 | 上下文压缩 | L3 | 4 | intelligence-backend.ts | AgentLoop 集成 | LLM 摘要未实现 |
| 13 | OpenViking | L4 | 13 | App.tsx | viking-client.ts | 无 |
| 14 | 技能系统 | L4 | 3 | kernel-client.ts | SkillMarket | PythonSkill 未实例化 |
| 15 | Hands 详情 | L4 | 7+23 | browser-client.ts | HandList + BrowserPanel | 无 |
| 16 | Tauri 后端 | L4 | 137 | 6 个 client 文件 | 全集成 | 无 |
| 17 | Pipeline DSL | L4 (90%) | 10 | pipeline-client.ts | PipelinesPanel | skill/hand stage 失败 |
结论: Tauri 端功能-代码对齐率 100%。所有 17 个文档功能都有对应的 Tauri 命令注册和前端调用。
三、SaaS-Tauri 功能差距矩阵
设计定位（v6.1 更新）: SaaS 后端不是 Tauri 功能的云端复制品。SaaS 仅负责系统管理工作：账号管理、功能权限控制、大模型中转（Relay）。Agent 管理、技能执行、Hand 执行、Pipeline、记忆系统、智能层、浏览器自动化等核心 AI 能力始终在 Tauri 桌面端本地运行，不会迁移到 SaaS 端。因此原报告中标记为 "CRITICAL" 的 9 个差距项已重新分类。
3.1 能力域对照
| # | 能力域 | Tauri 端 | SaaS 端 | 差距状态 | 说明 |
|---|---|---|---|---|---|
| 1 | 用户认证 | 本地 IPC，Ed25519 设备密钥 | JWT + Argon2 + TOTP 2FA，RBAC | 对等（模型不同） | 各自负责各自场景 |
| 2 | LLM 调用 | 8 个直接 LlmDriver | OpenAI 兼容 Relay 代理 | 部分（仅 relay） | SaaS 做 relay 中转 |
| 3 | Agent 管理 | 9 个 kernel 命令，SQLite | 不需要 | N/A | 本地能力，不迁移到 SaaS |
| 4 | 技能执行 | skill_list/refresh/execute，69 SKILL.md | 不需要 | N/A | 本地能力，不迁移到 SaaS |
| 5 | Hand 执行 | 7 命令 + 审批流程 | 不需要 | N/A | 本地能力，不迁移到 SaaS |
| 6 | Pipeline | 10 命令，8 action 类型 | 不需要 | N/A | 本地能力，不迁移到 SaaS |
| 7 | 记忆系统 | 13 命令，SQLite + FTS5 | 不需要 | N/A | 本地能力，不迁移到 SaaS |
| 8 | 智能层 | 43 命令（心跳/反思/身份/压缩） | 不需要 | N/A | 本地能力，不迁移到 SaaS |
| 9 | 浏览器自动化 | 23 个 browser_* 命令 | 不需要 | N/A | 本地能力，不迁移到 SaaS |
| 10 | OpenViking | 13 个 viking_* 命令 | 不需要 | N/A | 本地能力，不迁移到 SaaS |
| 11 | 配置同步 | 无专用机制 | config diff/sync API | SaaS 独有 | SaaS 管理职责 |
| 12 | 设备管理 | 无 | devices 表 + 心跳 | SaaS 独有 | SaaS 管理职责 |
| 13 | 用量追踪 | 无 | usage_records + stats | SaaS 独有 | SaaS 管理职责 |
| 14 | 审计日志 | 无 | operation_logs | SaaS 独有 | SaaS 管理职责 |
3.2 SaaS 后端现状
框架: Axum (Rust HTTP) + SQLite (sqlx) + JWT + Argon2
API 模块 (40+ 端点):
auth/— 注册/登录/JWT 刷新/TOTP 2FAaccount/— 用户 CRUD、API Token、操作日志、仪表盘model_config/— Provider/Model CRUD、用户 API Key、用量统计relay/— OpenAI 兼容 chat relay（流式+非流式）migration/— 配置 diff/sync
数据库: 13 张表，含 accounts, providers, models, relay_tasks, devices, config_items, usage_records
SaaS 前端: saas-client.ts（563 行）+ saasStore.ts（467 行），无专属 UI 组件
Main 分支: 零 SaaS 代码合并
3.3 合并风险评估
| 风险 | 等级 | 说明 |
|---|---|---|
| SaaS 功能缺失 | LOW | SaaS 定位为管理系统（账号/权限/relay），不需要复制 Tauri 端 AI 能力 |
| 架构耦合 | MEDIUM | Tauri 端 137 个命令全部依赖 invoke() + State<'_> + AppHandle，无法直接迁移到 HTTP API |
| 双通信路径 | MEDIUM | KernelClient（Tauri IPC）和 GatewayClient（WebSocket）并存，SaaS 需要第三条路径 |
| 类型一致性 | LOW | 共享 zclaw-types crate，类型定义一致 |
3.4 SaaS 待完善项（按设计定位）
| # | 功能 | 优先级 | 说明 |
|---|---|---|---|
| 1 | Relay 多模型支持 | P1 | 当前仅支持 OpenAI 兼容格式，需扩展其他 provider |
| 2 | 用户权限细化 | P1 | RBAC 基础已有，需细粒度功能权限控制 |
| 3 | Admin UI | P1 | SaaS 管理后台（已有设计规格） |
| 4 | 用量计费 | P2 | usage_records 已有表结构，需计费逻辑 |
| 5 | 多设备同步 | P2 | devices 表已有，需实现配置/Token 同步 |
四、Trait 实现矩阵
4.1 完整 26 Trait 清单
| # | Trait | Crate | 生产实现数 | 测试实现 | 零实现? | 严重性 |
|---|---|---|---|---|---|---|
| 1 | LlmDriver |
zclaw-runtime | 4 | 0 | -- | -- |
| 2 | Tool |
zclaw-runtime | 5 | 0 | -- | -- |
| 3 | SkillExecutor |
zclaw-runtime | 1 | 0 | -- | -- |
| 4 | LlmCompleter |
zclaw-skills | 1 | 0 | -- | -- |
| 5 | Skill |
zclaw-skills | 3 | 0 | -- | -- |
| 6 | SkillGraphExecutor |
zclaw-skills | 1 | 0 | -- | -- |
| 7 | OrchestrationPlanner |
zclaw-skills | 1 | 0 | -- | -- |
| 8 | Hand |
zclaw-hands | 9 | 0 | -- | -- |
| 9 | QuizGenerator |
zclaw-hands | 2 | 0 | -- | -- |
| 10 | Trigger |
zclaw-hands | 0 | 0 | YES | CRITICAL |
| 11 | VikingStorage |
zclaw-growth | 2 | 0 | -- | -- |
| 12 | EmbeddingClient |
zclaw-growth | 2 | 0 | -- | -- |
| 13 | LlmDriverForExtraction |
zclaw-growth | 0 | 1 | YES | HIGH |
| 14 | SummaryLlmDriver |
zclaw-growth | 1 | 2 | -- | -- |
| 15 | McpClient |
zclaw-protocols | 2 | 0 | -- | -- |
| 16 | A2aClient |
zclaw-protocols | 1 | 0 | -- | -- |
| 17 | Exporter |
zclaw-kernel | 4 | 0 | -- | -- |
| 18 | Channel |
zclaw-channels | 1 | 0 | -- | -- |
| 19 | LlmActionDriver |
zclaw-pipeline | 1 | 0 | -- | -- |
| 20 | SkillActionDriver |
zclaw-pipeline | 0 | 0 | YES | CRITICAL |
| 21 | HandActionDriver |
zclaw-pipeline | 0 | 0 | YES | CRITICAL |
| 22 | OrchestrationActionDriver |
zclaw-pipeline | 1 | 0 | -- | -- |
| 23 | LlmIntentDriver |
zclaw-pipeline | 1 | 0 | -- | -- |
| 24 | StageLlmDriver |
zclaw-pipeline | 0 | 0 | YES | CRITICAL |
| 25 | StageSkillDriver |
zclaw-pipeline | 0 | 0 | YES | CRITICAL |
| 26 | StageHandDriver |
zclaw-pipeline | 0 | 0 | YES | CRITICAL |
统计: 26 trait 中 6 个零实现（23%），1 个仅测试实现（4%），19 个有生产实现（73%）
4.2 ActionRegistry 接线状态
| Driver 槽位 | Builder 方法 | 是否接线 | 影响 |
|---|---|---|---|
llm_driver |
.with_llm_driver() |
已接线 | LLM stage 正常工作 |
skill_registry |
.with_skill_registry() |
未接线 | skill stage 必然失败 |
hand_registry |
.with_hand_registry() |
未接线 | hand stage 必然失败 |
orchestration_driver |
.with_orchestration_driver() |
未接线（有实现） | orchestration stage 无法使用 |
位置: desktop/src-tauri/src/pipeline_commands.rs:701-711
五、五种差距模式
5.1 量化总表
| # | 差距模式 | 数量 | 严重性 | 关键实例 |
|---|---|---|---|---|
| 1 | 写了没接 | 8 | HIGH | Director(907行), Export(2,319行), A2A(690行), MCP Client, Channels, GrowthIntegration |
| 2 | 接了没传 | 4 | MEDIUM | kernel_status 返回桩数据, viking_tree 忽略 depth 参数 |
| 3 | 传了没存 | 0 | -- | 智能层持久化完整 |
| 4 | 存了没用 | 2 | MEDIUM | GrowthIntegration 死代码路径, Export 系统不可达 |
| 5 | 双系统不同步 | 3 | HIGH | intelligence_hooks vs GrowthIntegration, SkillExecutor vs StageSkillDriver |
| 总计 | 17 |
5.2 Pattern 1: "写了没接" 详情
| 模块 | 位置 | 行数 | Tauri 可达? | 说明 |
|---|---|---|---|---|
| Director | crates/zclaw-kernel/src/director.rs |
907 | 否 | 多 Agent 编排，完全孤立 |
| Export 系统 | crates/zclaw-kernel/src/export/*.rs |
2,319 | 否 | 4 个 Exporter 实现，无 Tauri 命令 |
| A2A 协议 | crates/zclaw-protocols/src/a2a.rs |
690 | 否 | feature-gated 但从未激活 |
| MCP Client | crates/zclaw-protocols/src/mcp.rs |
588 | 否 | 2 个实现，0 个 Tauri 消费者 |
| zclaw-channels | crates/zclaw-channels/src/ |
290 | 否 | ConsoleChannel 无消费者 |
| GrowthIntegration | crates/zclaw-runtime/src/growth.rs |
315 | 部分 | 定义完整，被 intelligence_hooks 绕过 |
| 定时任务调度器 | desktop/src-tauri/src/kernel_commands.rs |
-- | 半接线 | 命令注册但无调度循环 |
5.3 Pattern 5: "双系统不同步" 详情
| 实例 | 路径 A | 路径 B | 影响 |
|---|---|---|---|
| 记忆增强 | intelligence_hooks::build_memory_context()（活跃） |
GrowthIntegration::enhance_prompt()（死代码） |
功能重叠但不一致，GrowthIntegration 永远不会执行 |
| 技能执行 | Kernel::execute_skill() → SkillRegistry（活跃） |
StageSkillDriver（零实现） |
Pipeline 中 skill stage 必然失败 |
| Hand 执行 | Kernel::hand_execute() + 审批（活跃） |
StageHandDriver（零实现） |
Pipeline 中 hand stage 必然失败 |
六、Dead Code 清单
6.1 #[allow(dead_code)] 统计（28 处）
| 分类 | 数量 | 说明 |
|---|---|---|
| 合理（serde 反序列化） | 8 | driver 响应体字段 |
| 桩代码（Reserved for future） | 14 | intelligence 层预留方法 |
| 可疑 | 6 | intent.rs, stage.rs, browser session 等 |
6.2 孤立模块（~4,228 行）
| 模块 | 位置 | 行数 | 建议 |
|---|---|---|---|
director |
crates/zclaw-kernel/src/director.rs |
907 | 移除或 feature-gate |
a2a |
crates/zclaw-protocols/src/a2a.rs |
690 | 已 feature-gate，保持现状 |
export |
crates/zclaw-kernel/src/export/ |
2,319 | 移除或接入 Tauri 命令 |
zclaw-channels |
crates/zclaw-channels/src/ |
290 | 移除 crate |
retrieval/cache.rs |
crates/zclaw-growth/src/retrieval/cache.rs |
22+ | 移除 |
6.3 TODO 注释（6 处）
| 位置 | 内容 | 风险 |
|---|---|---|
registry.rs:56 |
// TODO: Track this |
LOW |
orchestration.rs:41 |
// TODO: implement graph storage |
LOW |
html.rs:17 |
// TODO: Implement template-based HTML export |
LOW（孤立模块内） |
pipeline_commands.rs:442 |
// TODO: use actual time |
LOW |
pipeline_commands.rs:782 |
// TODO: add pattern support |
LOW |
七、E2E 数据流验证
7.1 流程总览
| # | 流程 | 验证结果 | 关键发现 |
|---|---|---|---|
| 1 | 聊天消息 | PASS | 全链路正常，intelligence hooks 正确注入记忆+身份 |
| 2 | 技能执行 | WARNING | PythonSkill 有实现但从未被实例化；assisted 模式无审批门 |
| 3 | Hand 执行+审批 | PASS | 三级守卫正确，跨 Hand 审批攻击防护到位 |
| 4 | Pipeline 执行 | FAIL | skill/hand stage 必然失败（DriverNotAvailable） |
| 5 | 记忆存储与检索 | PASS（有死代码） | intelligence_hooks 路径正常，GrowthIntegration 永远不执行 |
7.2 Flow 4 失败详情
Pipeline 的 StageExecutor 在执行 skill/hand 类型 stage 时，调用：
self.skill_driver.as_ref().ok_or_else(|| StageError::DriverNotAvailable("Skill"))?
由于 ActionRegistry 构造时从未注入 StageSkillDriver 或 StageHandDriver，skill_driver 和 hand_driver 字段始终为 None，导致 DriverNotAvailable 错误。
可用的 Pipeline stage 类型: LLM、HTTP、file_export、variable 不可用的 Pipeline stage 类型: skill、hand、orchestration
7.3 Flow 2 警告详情
SkillRegistry 在匹配 SkillMode::Python 时（registry.rs:79），直接 fall-through 到 PromptOnly，导致 PythonSkill（完整实现在 runner.rs:74-109）永远不会被实例化。
八、修复建议（优先级排序）
P0 — CRITICAL（影响核心功能可用性）
| # | 问题 | 修复方案 | 涉及文件 | 工作量 |
|---|---|---|---|---|
| P0-1 | Pipeline skill/hand stage 失败 | 实现 StageSkillDriver/StageHandDriver，在 pipeline_commands.rs 中注入 |
crates/zclaw-pipeline/, desktop/src-tauri/src/pipeline_commands.rs |
大 |
| P0-2 | GrowthIntegration 永远不执行 | 决策：(A) 在 Kernel 中接线 GrowthIntegration，移除 intelligence_hooks；(B) 移除 GrowthIntegration，统一到 intelligence_hooks | crates/zclaw-runtime/src/growth.rs, desktop/src-tauri/src/intelligence_hooks.rs |
中 |
P1 — HIGH（影响功能完整性）
| # | 问题 | 修复方案 | 涉及文件 | 工作量 |
|---|---|---|---|---|
| P1-1 | PythonSkill 未实例化 | 修复 registry.rs:79 的 fall-through 逻辑 |
crates/zclaw-skills/src/registry.rs |
小 |
| P1-2 | Trigger trait 零实现 | 实现 Trigger 或标记为 future feature |
crates/zclaw-hands/src/trigger.rs |
中 |
| P1-3 | LlmDriverForExtraction 仅 Mock | 在 Tauri 层实现生产版本（桥接 LlmDriver） | desktop/src-tauri/src/ |
中 |
| P1-4 | Skill assisted 模式无审批门 | 与 Hand 一致，添加 assisted 模式审批 | desktop/src-tauri/src/kernel_commands.rs |
小 |
P2 — MEDIUM（代码质量与可维护性）
| # | 问题 | 修复方案 | 涉及文件 | 工作量 |
|---|---|---|---|---|
| P2-1 | ~4,228 行孤立代码 | 移除 Director、Export、Channels crate | crates/zclaw-kernel/, crates/zclaw-protocols/, crates/zclaw-channels/ |
中 |
| P2-2 | kernel_status 返回桩数据 | 调用 kernel.config() 返回真实值 |
desktop/src-tauri/src/kernel_commands.rs |
小 |
| P2-3 | viking_tree 忽略 depth 参数 | 实现递归深度控制 | desktop/src-tauri/src/viking_commands.rs |
小 |
| P2-4 | 审批拒绝理由被丢弃 | 存储/返回 _reason 参数 |
crates/zclaw-kernel/src/kernel.rs |
小 |
P3 — LOW（SaaS 合并准备）
| # | 问题 | 修复方案 | 涉及文件 | 工作量 |
|---|---|---|---|---|
| P3-1 | SaaS 缺失 9 个核心能力域 | 制定 SaaS 功能路线图，优先级：Agent→Skill→Hand→Pipeline→Memory | .claude/worktrees/saas-backend/ |
大 |
| P3-2 | SaaS 无专属 UI 组件 | 设计/实现 SaaS 登录面板、设置页、仪表盘 | desktop/src/components/ |
大 |
| P3-3 | Tauri IPC 耦合 | 抽象通信层，支持 HTTP/WebSocket/Tauri IPC 三种模式 | desktop/src/lib/ |
大 |
九、审计结论
Tauri 端健康度: 良好（78%）
- 功能-代码对齐率 100%，17 个功能全部有对应命令和 UI
- 5 条核心 E2E 流程中 3 条完全通过，1 条有警告，1 条失败
- 智能层（记忆/身份/心跳/反思/压缩）已完整接入聊天流程
- 主要问题集中在 Pipeline 的 skill/hand stage 不可用，以及 GrowthIntegration 死代码路径
SaaS 端健康度: 早期（18%）
- 仅实现 auth + LLM relay + config sync 三个基础能力
- 9 个核心能力域（Agent/Skill/Hand/Pipeline/Memory/Intelligence/Browser/OpenViking）完全缺失
- 前端仅有 client/store 层，无专属 UI 组件
- Main 分支零 SaaS 代码，完全隔离
合并建议
建议在合并 SaaS worktree 前，先完成以下工作：
- 修复 P0-1（Pipeline skill/hand stage）
- 解决 P0-2（GrowthIntegration vs intelligence_hooks 决策）
- 制定 SaaS 核心能力实现路线图（至少覆盖 Agent + Skill + Hand）
- 为 SaaS 模式设计/实现专属 UI 组件
审计完成。本报告基于 2026-03-27 代码快照，所有发现均可通过文档中引用的文件路径和行号验证。
九、v6.1 修复记录
修复日期: 2026-03-27 编译状态:
cargo check通过，零错误零警告
已修复项
| # | 优先级 | 修复内容 | 修改文件 |
|---|---|---|---|
| 1 | P0 | Pipeline skill/hand stage 接入 Kernel 驱动 — 创建 PipelineSkillDriver 和 PipelineHandDriver 适配器，将 Kernel 的 skill/hand 执行能力桥接到 Pipeline 的 ActionRegistry |
pipeline_commands.rs |
| 2 | P0 | GrowthIntegration 标记为未接线 — 添加文档注释说明该模块在 Tauri 部署中未使用（被 intelligence_hooks 替代），保留代码因为被 loop_runner/compaction 深度引用 |
growth.rs |
| 3 | P1 | PythonSkill 未实例化 — SkillMode::Python 分支添加到 registry，当 main.py 存在时创建 PythonSkill 实例 |
registry.rs |
| 4 | P1 | Skill assisted 模式添加审批门 — supervised 模式所有 skill 需审批，assisted 模式 shell/python skill 需审批，autonomous 模式直接执行 |
kernel_commands.rs |
| 5 | P2 | kernel_status 返回真实配置值 — database_url、base_url、model 从桩数据改为读取 Kernel 配置 |
kernel_commands.rs |
| 6 | P2 | viking_tree depth 参数生效 — 移除未使用的 _depth 参数，添加实际深度限制逻辑 |
viking_commands.rs |
| 7 | P2 | 审批拒绝理由被丢弃 — ApprovalEntry 添加 reject_reason 字段，respond_to_approval 正确存储拒绝理由 |
kernel.rs |
| 8 | 文档 | SaaS 差距矩阵重新分类 — 明确 SaaS 定位为系统管理（账号/权限/relay），9 个 "CRITICAL GAP" 重新标记为 "N/A" | COMPREHENSIVE_AUDIT_V6.md |
待办项
| # | 优先级 | 内容 | 说明 |
|---|---|---|---|
| 1 | P2 | 清理孤立代码（Director/Export/Channels） | ~4,228 行，建议作为独立重构任务 |
| 2 | P3 | 6 个零实现 Trait 评估 | 4 个属于 Pipeline v2（未使用），2 个属于 Trigger 系统 |