refactor(saas): 架构重构 + 性能优化 — 借鉴 loco-rs 模式

Phase 0: 知识库 - docs/knowledge-base/loco-rs-patterns.md — loco-rs 10 个可借鉴模式研究 Phase 1: 数据层重构 - crates/zclaw-saas/src/models/ — 15 个 FromRow 类型化模型 - Login 3 次查询合并为 1 次 AccountLoginRow 查询 - 所有 service 文件从元组解构迁移到 FromRow 结构体 Phase 2: Worker + Scheduler 系统 - crates/zclaw-saas/src/workers/ — Worker trait + 5 个具体实现 - crates/zclaw-saas/src/scheduler.rs — TOML 声明式调度器 - crates/zclaw-saas/src/tasks/ — CLI 任务系统 Phase 3: 性能修复 - Relay N+1 查询 → 精准 SQL (relay/handlers.rs) - Config RwLock → AtomicU32 无锁 rate limit (state.rs, middleware.rs) - SSE std::sync::Mutex → tokio::sync::Mutex (relay/service.rs) - /auth/refresh 阻塞清理 → Scheduler 定期执行 Phase 4: 多环境配置 - config/saas-{development,production,test}.toml - ZCLAW_ENV 环境选择 + ZCLAW_SAAS_CONFIG 精确覆盖 - scheduler 配置集成到 TOML
2026-03-29 19:21:48 +08:00
parent 5fdf96c3f5
commit 8b9d506893
64 changed files with 3348 additions and 520 deletions
--- a/docs/features/AUDIT_TRACKER.md
+++ b/docs/features/AUDIT_TRACKER.md
@@ -0,0 +1,63 @@
+# ZCLAW 审计追踪表 (V9)
+
+> **创建日期**: 2026-03-29
+> **审计版本**: V9
+> **追踪规则**: 每个发现项记录状态变更，修复后需附验证方法
+
+---
+
+## P0: 阻断级
+
+| ID | 问题 | 状态 | 负责人 | 目标日期 | 验证方法 |
+|----|------|------|--------|---------|---------|
+| SEC-V9-01 | prompt/service.rs:94,97,100 SQL 注入 | OPEN | - | - | grep "format!" prompt/service.rs 无 SQL 拼接 |
+
+## P1: 严重级
+
+| ID | 问题 | 状态 | 负责人 | 目标日期 | 验证方法 |
+|----|------|------|--------|---------|---------|
+| BREAK-01 | LlmDriverForExtraction 无生产实现 | OPEN | - | - | grep "impl LlmDriverForExtraction" desktop/src-tauri/ |
+| BREAK-02 | 记忆提取未接入 post_conversation_hook | OPEN | - | - | grep "process_conversation" kernel_commands.rs |
+| BREAK-03 | 审批后不自动执行 Hand | OPEN | - | - | 验证 approval_respond 中 approved=true 触发执行 |
+| BREAK-04 | pipeline-complete 事件未监听 | OPEN | - | - | grep "pipeline-complete" desktop/src/ |
+
+## P2: 高优先级
+
+| ID | 问题 | 状态 | 负责人 | 目标日期 | 验证方法 |
+|----|------|------|--------|---------|---------|
+| DEAD-01 | PromptInjector 全文件死代码 | OPEN | - | - | 决策：接入或清理 |
+| DEAD-02 | MemoryRetriever 全文件死代码 | OPEN | - | - | 决策：接入或清理 |
+| DEAD-03 | GrowthTracker 全文件死代码 | OPEN | - | - | 决策：接入或清理 |
+| DEAD-05 | 39 个未调用 saas-client 方法 | OPEN | - | - | 评估是否需要桌面端入口 |
+| DOC-01 | Tauri 命令数文档 58+ vs 实际 130 | OPEN | - | - | 更新 06-tauri-backend 文档 |
+| DOC-02 | 智能层文档引用已删除模块 | OPEN | - | - | 更新 02-intelligence-layer 文档 |
+| TYPE-01 | Desktop/Admin 类型不一致 (6 组) | OPEN | - | - | 统一类型定义 |
+| G-07 | account_api_keys 被 relay 绕过 | OPEN | - | - | 决策：统一 key 管理或标记独立功能 |
+
+## P3: 中优先级
+
+| ID | 问题 | 状态 | 负责人 | 目标日期 | 验证方法 |
+|----|------|------|--------|---------|---------|
+| CONF-01 | 配置参数孤儿 (batch_window_ms 等) | OPEN | - | - | 实现消费或移除 |
+| SEC-V9-02 | relay 输入验证可加强 | OPEN | - | - | 添加基本校验 |
+| AUDIT-01 | 前端 audit-logger 无消费者 | OPEN | - | - | grep "auditLogger" desktop/src/ |
+| DEAD-04 | director.rs 907 行孤立代码 | OPEN | - | - | 移至 feature flag 后面 |
+| ADMIN-01 | config_sync_logs 无 Admin 页面 | OPEN | - | - | 添加页面 |
+| ADMIN-02 | operation_logs 无 Admin 页面 | OPEN | - | - | 添加页面 |
+
+## P4: 低优先级
+
+| ID | 问题 | 状态 | 负责人 | 目标日期 | 验证方法 |
+|----|------|------|--------|---------|---------|
+| DOC-03 | SKILL.md 数量 69→70 | OPEN | - | - | 更新 README.md |
+| DOC-04 | Hands 数量 CLAUDE.md vs README 不一致 | OPEN | - | - | 统一口径 |
+| EVAL-01 | zclaw-channels 评估 | OPEN | - | - | 决定保留或删除 |
+| IFACE-01 | trigger_update 接口不匹配 | OPEN | - | - | 对齐 TS/Rust 参数 |
+
+---
+
+## 状态变更日志
+
+| 日期 | ID | 变更 | 备注 |
+|------|-----|------|------|
+| 2026-03-29 | - | V9 审计创建 | 20 个发现项 |
--- a/docs/features/COMPREHENSIVE_AUDIT_V9.md
+++ b/docs/features/COMPREHENSIVE_AUDIT_V9.md
@@ -0,0 +1,307 @@
+# 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 | **1 HIGH** + 2 MEDIUM | 改善 (CRITICAL 已修复) |
+| **差距模式** | 12 个 | **16 个** (新增 4, 修复 8, 保留 4) | 净增 4 |
+| **整体完成度** | ~82% | **~83%** | 微升 |
+
+### 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 平台 | 云端能力 | **88%** | prompt SQL 注入；类型不一致 |
+
+### 2.5 智能层评分汇总
+
+| 模块 | 评分 | 说明 |
+|------|------|------|
+| zclaw-growth | **63%** | 架构设计优秀，但 3 个关键组件生产中未使用 |
+| intelligence/ | **78%** | 功能完整度好 |
+| zclaw-pipeline | **87%** | 实现质量高 |
+| zclaw-memory | **78%** | CRUD 完整，测试充分 |
+| **整体** | **~83%** | 记忆闭环未接通是最大差距 |
+
+---
+
+## 三、关键发现
+
+### 3.1 安全发现
+
+| ID | 严重度 | 组件 | 描述 | 证据 |
+|----|--------|------|------|------|
+| SEC-V9-01 | **HIGH** | prompt/service.rs | SQL 注入：3 处 format!() 字符串拼接 (category, source, status) | 行 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** | zclaw-growth | LlmDriverForExtraction 无生产实现 — 对话不会自动产生记忆 | extractor.rs trait |
+| 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 参数化查询 (参考 agent_template 修复模式) | 1h |
+
+### P1: 严重级 (功能断裂)
+
+| # | 问题 | 修复方案 | 工作量 |
+|---|------|---------|--------|
+| 2 | BREAK-01: LlmDriverForExtraction 无实现 | 在 Tauri 层创建 TauriExtractionDriver impl LlmDriverForExtraction | 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 (10h) + P2 (20h) + P3 (10h) + P4 (4h) = **~45h**
+
+---
+
+## 七、架构健康度评分
+
+| 模块 | 评分 | 趋势 | 关键问题 |
+|------|------|------|---------|
+| 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 | **63%** | ↓ | 3 个关键组件未接入生产 |
+| zclaw-channels | 20% | ↓ | 仅 ConsoleChannel |
+| zclaw-saas | 88% | ↑ | SQL 注入修复后可到 90%+ |
+| Desktop 前端 | 82% | → | 降级策略完善 |
+| Admin 后台 | 85% | → | 缺日志/同步日志页面 |
+| **整体** | **~83%** | **↑** | 核心功能可用，智能层闭环待修复 |
+
+---
+
+## 八、核心结论
+
+### 根因分析
+
+V9 审计发现的根本问题集中在一条断裂的数据链路上：
+
+**`对话 → 记忆提取 → 存储 → 检索 → 注入 → 增强回复`**
+
+当前只有 `检索 → 注入 → 增强回复` 在工作。记忆的"生长"依赖：
+1. LlmDriverForExtraction 的实现 (BREAK-01)
+2. post_conversation_hook 的接入 (BREAK-02)
+3. PromptInjector 替代字符串拼接 (DEAD-01)
+
+修复这 3 项后，智能层的完成度将从 63% 跃升至 85%+。
+
+### 安全状态
+
+V8 的 CRITICAL (agent_template SQL 注入) 已修复。仅剩 1 个 HIGH (prompt SQL 注入) 和 2 个 MEDIUM。SSRF 防护全面，Auth 覆盖完整，密码/TOTP/加密实现安全。
+
+### 最大改进方向
+
+1. **记忆闭环修复** — P1 修复后用户体验显著提升
+2. **文档更新** — 130 个命令只记录了 58 个，严重低估
+3. **死代码清理** — Growth crate 3 个核心组件设计完善但未接入
+4. **Admin 补全** — 操作日志、同步日志、设备管理页面缺失
--- a/docs/features/SYSTEM_ARCHITECTURE.md
+++ b/docs/features/SYSTEM_ARCHITECTURE.md
@@ -0,0 +1,744 @@
+# ZCLAW 多端系统架构文档
+
+> 版本: 1.0 | 日期: 2026-03-29 | 状态: 待审核
+
+---
+
+## 目录
+
+1. [系统总览](#1-系统总览)
+2. [端口与协议分配](#2-端口与协议分配)
+3. [技术栈选型](#3-技术栈选型)
+4. [数据流向](#4-数据流向)
+5. [SaaS 后端 API 接口清单](#5-saas-后端-api-接口清单)
+6. [桌面端内部通信](#6-桌面端内部通信)
+7. [权限体系](#7-权限体系)
+8. [各端交互逻辑](#8-各端交互逻辑)
+9. [部署与启动](#9-部署与启动)
+10. [接口设计背景与业务价值](#10-接口设计背景与业务价值)
+
+---
+
+## 1. 系统总览
+
+ZCLAW 是面向中文用户的 AI Agent 桌面客户端，由 **4 个独立服务/端** 组成：
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        ZCLAW 系统架构                            │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────┐  │
+│  │  Desktop App  │  │  Admin Web   │  │  SaaS Backend        │  │
+│  │  (Tauri+React)│  │  (Next.js)   │  │  (Axum + PostgreSQL) │  │
+│  │  Port: 1420   │  │  Port: 3000  │  │  Port: 8080          │  │
+│  │               │  │              │  │                      │  │
+│  │  内核模式:     │  │  管理后台     │  │  REST API            │  │
+│  │  Tauri IPC    │  │  JWT 鉴权     │  │  JWT + API Token     │  │
+│  │               │  │              │  │  RBAC 权限            │  │
+│  │  网关模式:     │  │              │  │                      │  │
+│  │  WS :50051    │  │              │  │  ┌────────────────┐  │  │
+│  │  WS :4200     │  │              │  │  │  PostgreSQL     │  │  │
+│  │               │  │              │  │  │  Port: 5432    │  │  │
+│  │  SaaS 模式:   │  │              │  │  └────────────────┘  │  │
+│  │  HTTPS REST   │  │              │  │                      │  │
+│  └──────────────┘  └──────────────┘  └──────────────────────┘  │
+│                                                                 │
+│  ┌──────────────┐  ┌──────────────┐                             │
+│  │  ZCLAW 网关   │  │  LLM 服务商  │                             │
+│  │  (独立二进制) │  │  (外部)      │                             │
+│  │  Port: 4200   │  │  OpenAI 等   │                             │
+│  │  Port: 50051  │  │              │                             │
+│  └──────────────┘  └──────────────┘                             │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### 核心设计理念
+
+- **双模式架构**: 桌面端支持「本地内核」(离线/低延迟) 和「远程网关」(团队协作) 两种运行模式
+- **统一 LLM 接入**: 4 条 LLM 路径 (直连 OpenAI、直连火山引擎、SaaS 中转、网关透传)
+- **集中管控**: SaaS 后端统一管理账号、模型、服务商、Prompt 模板、配置同步
+- **安全审计**: 完整的操作日志 + TOTP 2FA + JWT + RBAC
+
+---
+
+## 2. 端口与协议分配
+
+| 端口 | 服务 | 协议 | 用途 | 启动方式 |
+|------|------|------|------|----------|
+| 1420 | Vite Dev Server | HTTP | 桌面端前端开发服务 (仅 dev) | `pnpm tauri dev` |
+| 3000 | Next.js Dev Server | HTTP | Admin 管理后台开发服务 | `pnpm dev` (admin/) |
+| 4200 | ZCLAW Gateway/Kernel | WebSocket + REST | 网关备用端口 | ZCLAW 二进制 |
+| 50051 | ZCLAW Gateway | WebSocket + REST | 网关主端口 | ZCLAW 二进制 |
+| 5432 | PostgreSQL | PostgreSQL Wire | SaaS 后端数据库 | Docker/start-all.ps1 |
+| 8080 | SaaS Backend | HTTP REST | 管理后台 API + 中转代理 | start-saas.ps1 |
+| 4444 | ChromeDriver | WebDriver HTTP | 浏览器 Hand 自动化 | start-all.ps1 |
+| N/A | Tauri IPC | invoke() | 桌面端内部进程通信 | 内嵌 |
+
+---
+
+## 3. 技术栈选型
+
+### 3.1 桌面端 (Desktop)
+
+| 层级 | 技术 | 选型理由 |
+|------|------|----------|
+| 桌面框架 | Tauri 2.x | Rust 原生性能，小体积，安全 IPC |
+| 前端框架 | React 18 + TypeScript | 生态丰富，类型安全 |
+| 状态管理 | Zustand | 轻量、灵活、无 boilerplate |
+| 样式方案 | Tailwind CSS | 原子化 CSS，暗色主题友好 |
+| 数据存储 | SQLite (本地) | 离线优先，FTS5 全文搜索 |
+
+### 3.2 Admin 管理后台
+
+| 层级 | 技术 | 选型理由 |
+|------|------|----------|
+| 框架 | Next.js 14 (App Router) | SSR/CSR 灵活切换，API 代理 |
+| 数据获取 | SWR 2.x | 缓存+去重+自动重验证，stale-while-revalidate |
+| UI 组件 | shadcn/ui | 暗色主题原生支持，可定制 |
+| 图表 | Recharts | React 原生集成，轻量 |
+
+### 3.3 SaaS 后端
+
+| 层级 | 技术 | 选型理由 |
+|------|------|----------|
+| Web 框架 | Axum | Rust 高性能异步 Web 框架 |
+| 数据库 | PostgreSQL | 关系型，复杂查询支持好 |
+| ORM | sqlx | 编译时 SQL 检查，零开销 |
+| 认证 | JWT + TOTP | 无状态鉴权 + 双因素认证 |
+| 加密 | AES-256-GCM | API Key 加密存储 |
+
+### 3.4 核心运行时 (Rust Workspace)
+
+```
+zclaw-types        → 基础类型 (AgentId, Message, Error)
+zclaw-memory       → 存储层 (SQLite, FTS5, TF-IDF, Embeddings)
+zclaw-runtime      → 运行时 (LLM 驱动, 工具, Agent 循环)
+zclaw-kernel       → 核心协调 (注册, 调度, 事件, 工作流)
+zclaw-skills       → 技能系统 (SKILL.md 解析, WASM 执行器)
+zclaw-hands        → 自主能力 (Hand/Trigger 注册管理)
+zclaw-protocols    → 协议支持 (MCP, A2A)
+zclaw-saas         → SaaS 后端 (独立服务, 8080 端口)
+```
+
+---
+
+## 4. 数据流向
+
+### 4.1 Admin 管理后台数据流
+
+```
+用户操作 → React UI → SWR Hook → api-client.ts → Next.js Rewrites → SaaS 后端 (:8080)
+                ↑                                                          ↓
+                └── SWR Cache ←── JSON Response ←── PostgreSQL (:5432) ←─┘
+```
+
+**关键路径:**
+- Admin 前端所有请求通过 `next.config.js rewrites` 代理到 `localhost:8080`
+- API 基路径: `/api/v1/*` (前端) → `http://localhost:8080/api/v1/*` (后端)
+- SWR 缓存: 页面切换后缓存 5s 去重，stale-while-revalidate 模式
+
+### 4.2 桌面端数据流 (Tauri 模式)
+
+```
+React UI → Zustand Store → invoke() IPC → Rust Tauri Commands → Kernel → LLM/Tools/Skills/Hands
+                                                       ↓
+                                                  SQLite (~/.zclaw/data.db)
+```
+
+### 4.3 桌面端数据流 (网关模式)
+
+```
+React UI → gateway-client.ts → WebSocket (:50051) → ZCLAW Gateway → Kernel
+                              → REST API (/api/*) →
+```
+
+### 4.4 桌面端数据流 (SaaS 模式)
+
+```
+React UI → saas-client.ts → HTTPS REST → SaaS 后端 (:8080)
+          llm-service.ts  → relay/chat/completions → Provider → LLM API
+```
+
+### 4.5 LLM 请求路由 (4 条路径)
+
+```
+┌─────────────┐    ┌─ Direct OpenAI ────→ api.openai.com
+│             │    ├─ Direct Volcengine ─→ volcengine endpoint
+│  llm-service│────┤
+│             │    ├─ SaaS Relay ────────→ saas.zclaw.com/relay → Provider
+│             │    └─ Gateway ───────────→ invoke('agent_chat') or REST
+└─────────────┘
+```
+
+---
+
+## 5. SaaS 后端 API 接口清单
+
+### 5.0 通用规范
+
+- **Base URL**: `http://localhost:8080/api/v1`
+- **认证方式**: `Authorization: Bearer <JWT_TOKEN>` 或 `Authorization: Bearer zclaw_<API_KEY>`
+- **Content-Type**: `application/json`
+- **分页响应格式**: `{ items: T[], total: number, page: number, page_size: number }`
+- **错误响应格式**: `{ error: string, message: string }`
+- **HTTP 状态码**: 200 OK, 201 Created, 204 No Content, 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 409 Conflict, 500 Internal Error
+
+### 5.1 公开接口 (无需认证)
+
+| # | 方法 | 路径 | 用途 | 业务价值 |
+|---|------|------|------|----------|
+| 1 | GET | `/api/health` | 健康检查 | 运维监控探针，检测 DB 连通性 |
+| 2 | POST | `/api/v1/auth/register` | 用户注册 | 自助开户，降低运营成本 |
+| 3 | POST | `/api/v1/auth/login` | 用户登录 | 身份验证入口，支持 TOTP 2FA |
+| 4 | POST | `/api/v1/auth/refresh` | Token 刷新 | 无感续期，单次使用 refresh_token |
+
+**POST /api/v1/auth/login**
+
+请求:
+```typescript
+{
+  username: string      // 接受用户名或邮箱
+  password: string      // 8-128 字符
+  totp_code?: string    // 6 位数字，启用 TOTP 时必填
+}
+```
+
+响应:
+```typescript
+{
+  token: string         // JWT access token
+  refresh_token: string // 单次使用 refresh token
+  account: AccountPublic
+}
+```
+
+### 5.2 认证自服务接口 (需登录)
+
+| # | 方法 | 路径 | 用途 |
+|---|------|------|------|
+| 5 | GET | `/api/v1/auth/me` | 获取当前用户信息 |
+| 6 | PUT | `/api/v1/auth/password` | 修改密码 |
+| 7 | POST | `/api/v1/auth/totp/setup` | 生成 TOTP 密钥 |
+| 8 | POST | `/api/v1/auth/totp/verify` | 激活 TOTP 2FA |
+| 9 | POST | `/api/v1/auth/totp/disable` | 关闭 TOTP 2FA |
+
+### 5.3 账号管理接口 (Admin)
+
+| # | 方法 | 路径 | 用途 | 权限 |
+|---|------|------|------|------|
+| 10 | GET | `/api/v1/accounts` | 账号列表 (支持搜索/筛选/分页) | `account:admin` |
+| 11 | GET | `/api/v1/accounts/:id` | 账号详情 | `account:admin` |
+| 12 | PATCH | `/api/v1/accounts/:id` | 更新账号信息 | `account:admin` |
+| 13 | PATCH | `/api/v1/accounts/:id/status` | 变更账号状态 | `account:admin` |
+| 14 | GET | `/api/v1/logs/operations` | 操作日志列表 | `account:admin` |
+| 15 | GET | `/api/v1/stats/dashboard` | 仪表盘统计聚合 | `account:admin` |
+| 16 | GET | `/api/v1/devices` | 用户设备列表 | 认证用户 |
+| 17 | POST | `/api/v1/devices/register` | 注册/更新设备 | 认证用户 |
+| 18 | POST | `/api/v1/devices/heartbeat` | 设备心跳 | 认证用户 |
+
+**GET /api/v1/accounts** 查询参数:
+```typescript
+{
+  page?: number          // 页码，默认 1
+  page_size?: number     // 每页条数，默认 20
+  search?: string        // 搜索用户名/邮箱/显示名
+  role?: string          // 按角色筛选: super_admin | admin | user
+  status?: string        // 按状态筛选: active | disabled | suspended
+}
+```
+
+**GET /api/v1/stats/dashboard** 响应:
+```typescript
+{
+  total_accounts: number
+  active_accounts: number
+  tasks_today: number
+  active_providers: number
+  active_models: number
+  tokens_today_input: number
+  tokens_today_output: number
+}
+```
+
+### 5.4 服务商管理接口
+
+| # | 方法 | 路径 | 用途 | 权限 |
+|---|------|------|------|------|
+| 19 | GET | `/api/v1/providers` | 服务商列表 | 认证用户 |
+| 20 | GET | `/api/v1/providers/:id` | 服务商详情 | 认证用户 |
+| 21 | POST | `/api/v1/providers` | 创建服务商 | `provider:manage` |
+| 22 | PATCH | `/api/v1/providers/:id` | 更新服务商 | `provider:manage` |
+| 23 | DELETE | `/api/v1/providers/:id` | 删除服务商 | `provider:manage` |
+| 24 | GET | `/api/v1/providers/:id/models` | 服务商下的模型列表 | 认证用户 |
+
+**Provider 数据结构:**
+```typescript
+{
+  id: string
+  name: string               // 唯一标识名，如 "openai"
+  display_name: string       // 显示名，如 "OpenAI"
+  base_url: string           // API 基地址
+  api_protocol: 'openai' | 'anthropic'
+  enabled: boolean
+  rate_limit_rpm?: number    // 每分钟请求限制
+  rate_limit_tpm?: number    // 每分钟 Token 限制
+  created_at: string
+  updated_at: string
+}
+```
+
+### 5.5 模型管理接口
+
+| # | 方法 | 路径 | 用途 | 权限 |
+|---|------|------|------|------|
+| 25 | GET | `/api/v1/models` | 模型列表 | 认证用户 |
+| 26 | GET | `/api/v1/models/:id` | 模型详情 | 认证用户 |
+| 27 | POST | `/api/v1/models` | 创建模型 | `model:manage` |
+| 28 | PATCH | `/api/v1/models/:id` | 更新模型 | `model:manage` |
+| 29 | DELETE | `/api/v1/models/:id` | 删除模型 | `model:manage` |
+
+**Model 数据结构:**
+```typescript
+{
+  id: string
+  provider_id: string
+  model_id: string           // 如 "gpt-4o"
+  alias: string              // 显示别名
+  context_window: number     // 上下文窗口大小
+  max_output_tokens: number  // 最大输出 Token
+  supports_streaming: boolean
+  supports_vision: boolean
+  enabled: boolean
+  pricing_input: number      // $/1M tokens
+  pricing_output: number     // $/1M tokens
+}
+```
+
+### 5.6 API Key 管理接口
+
+| # | 方法 | 路径 | 用途 | 权限 |
+|---|------|------|------|------|
+| 30 | GET | `/api/v1/keys` | 当前用户的 API Key 列表 | 认证用户 |
+| 31 | POST | `/api/v1/keys` | 创建 API Key | 认证用户 |
+| 32 | POST | `/api/v1/keys/:id/rotate` | 轮换 API Key | 认证用户 |
+| 33 | DELETE | `/api/v1/keys/:id` | 撤销 API Key | 认证用户 |
+
+### 5.7 Key Pool 管理接口 (Admin)
+
+| # | 方法 | 路径 | 用途 | 权限 |
+|---|------|------|------|------|
+| 34 | GET | `/api/v1/providers/:id/keys` | 服务商 Key Pool 列表 | `provider:manage` |
+| 35 | POST | `/api/v1/providers/:id/keys` | 添加 Key 到 Pool | `provider:manage` |
+| 36 | PUT | `/api/v1/providers/:id/keys/:keyId/toggle` | 启用/禁用 Key | `provider:manage` |
+| 37 | DELETE | `/api/v1/providers/:id/keys/:keyId` | 删除 Key | `provider:manage` |
+
+**业务价值**: Key Pool 实现多 API Key 智能轮转，自动绕过 429 限流，提升整体吞吐量。
+
+### 5.8 中转代理接口 (Relay)
+
+| # | 方法 | 路径 | 用途 | 权限 |
+|---|------|------|------|------|
+| 38 | POST | `/api/v1/relay/chat/completions` | LLM 中转请求 | `relay:use` |
+| 39 | GET | `/api/v1/relay/tasks` | 中转任务列表 | 认证用户 |
+| 40 | GET | `/api/v1/relay/tasks/:id` | 任务详情 | 认证用户 |
+| 41 | POST | `/api/v1/relay/tasks/:id/retry` | 重试失败任务 | `relay:admin` |
+| 42 | GET | `/api/v1/relay/models` | 可用模型列表 | 认证用户 |
+
+**POST /api/v1/relay/chat/completions** — 核心中转接口
+
+请求: OpenAI 兼容格式
+```typescript
+{
+  model: string
+  messages: Array<{ role: string, content: string }>
+  temperature?: number
+  max_tokens?: number
+  stream?: boolean         // 支持 SSE 流式响应
+  // ... 其他字段透传给服务商
+}
+```
+
+响应:
+- 非流式: `application/json` — 原始服务商响应
+- 流式: `text/event-stream` — SSE 事件流
+
+**业务价值**: 统一入口代理多家 LLM 服务商，自动 Key Pool 轮转、429 处理、用量计费。
+
+### 5.9 用量统计接口
+
+| # | 方法 | 路径 | 用途 |
+|---|------|------|------|
+| 43 | GET | `/api/v1/usage` | 用量统计 (按天/按模型) |
+
+**查询参数:**
+```typescript
+{
+  from?: string          // ISO 8601 开始日期
+  to?: string            // ISO 8601 结束日期
+  provider_id?: string   // 按服务商筛选
+  model_id?: string      // 按模型筛选
+  group_by?: 'day' | 'model'
+  days?: number          // 最近 N 天
+}
+```
+
+**响应:**
+```typescript
+{
+  total_requests: number
+  total_input_tokens: number
+  total_output_tokens: number
+  by_model: Array<{ model_id, count, input_tokens, output_tokens }>
+  by_day: Array<{ day, count, input_tokens, output_tokens }>
+}
+```
+
+### 5.10 配置管理接口
+
+| # | 方法 | 路径 | 用途 | 权限 |
+|---|------|------|------|------|
+| 44 | GET | `/api/v1/config/items` | 配置项列表 | 认证用户 |
+| 45 | GET | `/api/v1/config/items/:id` | 配置项详情 | 认证用户 |
+| 46 | POST | `/api/v1/config/items` | 创建配置项 | `config:write` |
+| 47 | PATCH | `/api/v1/config/items/:id` | 更新配置项 | `config:write` |
+| 48 | DELETE | `/api/v1/config/items/:id` | 删除配置项 | `config:write` |
+| 49 | GET | `/api/v1/config/analysis` | 配置分析 | 认证用户 |
+| 50 | POST | `/api/v1/config/seed` | 种子配置 | `config:write` |
+| 51 | POST | `/api/v1/config/sync` | 双向配置同步 | `config:write` |
+| 52 | POST | `/api/v1/config/diff` | 配置差异比较 | 认证用户 |
+| 53 | GET | `/api/v1/config/sync-logs` | 同步日志 | 认证用户 |
+| 54 | GET | `/api/v1/config/pull` | 批量拉取配置 | 认证用户 |
+
+**业务价值**: 集中管理所有运行参数（服务器、Agent、记忆、LLM、安全策略），支持桌面端双向同步，推送/拉取/合并三种模式。
+
+### 5.11 角色与权限接口
+
+| # | 方法 | 路径 | 用途 | 权限 |
+|---|------|------|------|------|
+| 55 | GET | `/api/v1/roles` | 角色列表 | `account:read` |
+| 56 | GET | `/api/v1/roles/:id` | 角色详情 | `account:read` |
+| 57 | POST | `/api/v1/roles` | 创建角色 | `account:admin` |
+| 58 | PUT | `/api/v1/roles/:id` | 更新角色 | `account:admin` |
+| 59 | DELETE | `/api/v1/roles/:id` | 删除角色 | `account:admin` |
+| 60 | GET | `/api/v1/roles/:id/permissions` | 角色权限列表 | `account:read` |
+| 61 | GET | `/api/v1/permission-templates` | 权限模板列表 | `account:read` |
+| 62 | GET | `/api/v1/permission-templates/:id` | 权限模板详情 | `account:read` |
+| 63 | POST | `/api/v1/permission-templates` | 创建权限模板 | `account:admin` |
+| 64 | DELETE | `/api/v1/permission-templates/:id` | 删除权限模板 | `account:admin` |
+| 65 | POST | `/api/v1/permission-templates/:id/apply` | 批量应用权限模板 | `account:admin` |
+
+### 5.12 Prompt 模板管理接口
+
+| # | 方法 | 路径 | 用途 | 权限 |
+|---|------|------|------|------|
+| 66 | GET | `/api/v1/prompts` | 模板列表 | `prompt:read` |
+| 67 | POST | `/api/v1/prompts` | 创建模板 | `prompt:write` |
+| 68 | GET | `/api/v1/prompts/:name` | 模板详情 | `prompt:read` |
+| 69 | PUT | `/api/v1/prompts/:name` | 更新模板元数据 | `prompt:write` |
+| 70 | DELETE | `/api/v1/prompts/:name` | 归档模板 | `prompt:admin` |
+| 71 | GET | `/api/v1/prompts/:name/versions` | 版本历史 | `prompt:read` |
+| 72 | GET | `/api/v1/prompts/:name/versions/:v` | 特定版本 | `prompt:read` |
+| 73 | POST | `/api/v1/prompts/:name/versions` | 发布新版本 | `prompt:write` |
+| 74 | POST | `/api/v1/prompts/:name/rollback/:v` | 回滚版本 | `prompt:admin` |
+| 75 | POST | `/api/v1/prompts/check` | OTA 更新检查 | 认证用户 |
+
+**POST /api/v1/prompts/check** — OTA 更新检查
+
+请求:
+```typescript
+{
+  device_id: string
+  versions: Record<string, number>  // { "reflection": 3, "compaction": 2 }
+}
+```
+
+响应:
+```typescript
+{
+  updates: Array<{
+    name: string
+    version: number
+    system_prompt: string
+    user_prompt_template?: string
+    variables: PromptVariable[]
+    source: string
+    min_app_version?: string
+  }>
+  server_time: string
+}
+```
+
+**业务价值**: 集中管理 Prompt 模板，桌面端每 30 分钟检查更新，无需发版即可优化提示词。
+
+### 5.13 Agent 模板管理接口
+
+| # | 方法 | 路径 | 用途 | 权限 |
+|---|------|------|------|------|
+| 76 | GET | `/api/v1/agent-templates` | Agent 模板列表 | `model:read` |
+| 77 | POST | `/api/v1/agent-templates` | 创建 Agent 模板 | `model:manage` |
+| 78 | GET | `/api/v1/agent-templates/:id` | 模板详情 | `model:read` |
+| 79 | POST | `/api/v1/agent-templates/:id` | 更新模板 | `model:manage` |
+| 80 | DELETE | `/api/v1/agent-templates/:id` | 归档模板 | `model:manage` |
+
+**AgentTemplate 数据结构:**
+```typescript
+{
+  id: string
+  name: string
+  description?: string
+  category: string
+  source: 'builtin' | 'custom'
+  model?: string
+  system_prompt?: string
+  tools: string[]
+  capabilities: string[]
+  temperature?: number
+  max_tokens?: number
+  visibility: 'public' | 'team' | 'private'
+  status: 'active' | 'archived'
+  current_version: number
+}
+```
+
+### 5.14 遥测接口
+
+| # | 方法 | 路径 | 用途 | 权限 |
+|---|------|------|------|------|
+| 81 | POST | `/api/v1/telemetry/report` | 上报遥测数据 | 认证用户 |
+| 82 | GET | `/api/v1/telemetry/stats` | 按模型统计 | 认证用户 |
+| 83 | GET | `/api/v1/telemetry/daily` | 按天统计 | 认证用户 |
+| 84 | POST | `/api/v1/telemetry/audit` | 上报审计摘要 | 认证用户 |
+
+**POST /api/v1/telemetry/report** 请求:
+```typescript
+{
+  device_id: string
+  app_version: string
+  entries: Array<{
+    model_id: string
+    input_tokens: number
+    output_tokens: number
+    latency_ms?: number
+    success: boolean
+    error_type?: string
+    timestamp: string
+    connection_mode: 'tauri' | 'saas'
+  }>  // 最多 500 条/请求
+}
+```
+
+**业务价值**: 桌面端批量上报本地 LLM 用量，管理员可在后台查看所有设备的 Token 消耗、延迟、成功率。
+
+---
+
+## 6. 桌面端内部通信
+
+### 6.1 Tauri Commands 清单
+
+桌面端通过 `invoke()` IPC 暴露以下命令组：
+
+| 命令组 | 文件 | 命令数 | 用途 |
+|--------|------|--------|------|
+| 进程管理 | lib.rs | 10 | zclaw_start/stop/restart, doctor, health_check |
+| 内核操作 | kernel_commands.rs | 20+ | agent_create/chat_stream, skill_execute, hand_execute |
+| 工作流 | pipeline_commands.rs | 9 | pipeline_run/progress/cancel, route_intent |
+| 持久记忆 | memory_commands.rs | 12 | memory_store/get/search/export |
+| Viking 存储 | viking_commands.rs | 9 | viking_add/find/grep/read |
+| 智能钩子 | intelligence_hooks.rs | 2 | pre/post_conversation_hook |
+
+### 6.2 WebSocket 事件类型
+
+| 方向 | 事件 | 说明 |
+|------|------|------|
+| Server→Client | `text_delta` | 流式文本片段 |
+| Server→Client | `phase` | 阶段切换 (thinking/tool) |
+| Server→Client | `tool_call` / `tool_result` | 工具调用与结果 |
+| Server→Client | `hand` | Hand 自主能力触发 |
+| Server→Client | `error` | 错误通知 |
+| Client→Server | `message` | 发送消息 |
+| Client→Server | `auth_challenge` / `auth_response` | Ed25519 握手 |
+| 双向 | `ping` / `pong` | 心跳 (30s 间隔) |
+
+---
+
+## 7. 权限体系
+
+### 7.1 角色定义
+
+| 角色 | 权限范围 |
+|------|----------|
+| `super_admin` | 全部权限 (`admin:full`) |
+| `admin` | 账号管理、服务商/模型管理、中转管理、配置读写、Prompt 读写发布 |
+| `user` | 模型读取、中转使用、配置读取、Prompt 读取 |
+
+### 7.2 权限清单
+
+| 权限 | 说明 |
+|------|------|
+| `admin:full` | 超级权限，绕过所有检查 |
+| `account:admin` | 账号管理 (列表、状态变更、角色分配) |
+| `account:read` | 读取账号、角色、权限模板 |
+| `provider:manage` | 创建/更新/删除服务商、管理 Key Pool |
+| `model:manage` | 创建/更新/删除模型、Agent 模板 |
+| `model:read` | 读取模型、Agent 模板 |
+| `relay:use` | 使用中转 (chat completions) |
+| `relay:admin` | 查看任意中转任务、重试失败任务 |
+| `config:write` | 创建/更新/删除配置项、同步、种子 |
+| `prompt:read` | 读取 Prompt 模板和版本 |
+| `prompt:write` | 创建/更新 Prompt 模板和版本 |
+| `prompt:admin` | 归档 Prompt、回滚版本 |
+
+---
+
+## 8. 各端交互逻辑
+
+### 8.1 Admin 管理后台 ↔ SaaS 后端
+
+```
+┌───────────────────────────────────────────────────────────┐
+│  Admin 浏览器 (localhost:3000)                             │
+│                                                           │
+│  ┌──────────┐  SWR Cache  ┌──────────────┐               │
+│  │ React UI │◄────────────►│ api-client   │               │
+│  │ 11 页面   │             │ JWT 鉴权      │               │
+│  └──────────┘             └──────┬───────┘               │
+│                                  │ fetch()                │
+└──────────────────────────────────┼────────────────────────┘
+                                   │
+                    Next.js Rewrite│ /api/* → localhost:8080/api/*
+                                   │
+┌──────────────────────────────────┼────────────────────────┐
+│  SaaS Backend (:8080)            │                        │
+│                           ┌──────▼───────┐               │
+│                           │  Axum Router  │               │
+│                           │  中间件栈:     │               │
+│                           │  1. Auth      │               │
+│                           │  2. RateLimit │               │
+│                           │  3. RequestID │               │
+│                           │  4. Version   │               │
+│                           └──────┬───────┘               │
+│                                  │                        │
+│                    ┌─────────────▼──────────────┐        │
+│                    │  Handlers (72 个端点)       │        │
+│                    │  auth/account/model/relay/  │        │
+│                    │  config/prompt/telemetry/   │        │
+│                    └─────────────┬──────────────┘        │
+│                                  │                        │
+│                    ┌─────────────▼──────────────┐        │
+│                    │  PostgreSQL (:5432)          │        │
+│                    └─────────────────────────────┘        │
+└───────────────────────────────────────────────────────────┘
+```
+
+### 8.2 桌面端交互矩阵
+
+| 场景 | 通信方式 | 目标 | 数据 |
+|------|----------|------|------|
+| 本地对话 | Tauri IPC invoke() | Kernel | 消息、Agent、Skills |
+| 流式响应 | Tauri Event listen() | Kernel | stream:chunk 事件 |
+| 远程对话 | WebSocket :50051 | ZCLAW Gateway | 消息、事件流 |
+| SaaS 登录 | HTTPS REST | SaaS :8080 | JWT 认证 |
+| LLM 中转 | HTTPS REST | SaaS :8080/relay | OpenAI 兼容请求 |
+| Prompt OTA | HTTPS REST | SaaS :8080/prompts/check | 版本号 → 更新 |
+| 配置同步 | HTTPS REST | SaaS :8080/config/sync | 双向键值对 |
+| 遥测上报 | HTTPS REST | SaaS :8080/telemetry/report | 批量用量数据 |
+
+---
+
+## 9. 部署与启动
+
+### 9.1 完整启动顺序
+
+```powershell
+# start-all.ps1 启动顺序:
+1. PostgreSQL    → :5432 (Docker 或本地服务)
+2. SaaS Backend  → :8080 (zclaw-saas.exe)
+3. ChromeDriver  → :4444 (可选, 用于 Browser Hand)
+4. Desktop Dev   → :1420 (Tauri dev)
+```
+
+### 9.2 SaaS 后端配置
+
+```toml
+# saas-config.toml
+[server]
+host = "0.0.0.0"
+port = 8080
+
+[database]
+url = "postgres://postgres:123123@localhost:5432/zclaw"
+
+[auth]
+jwt_expiration_hours = 24
+totp_issuer = "ZCLAW SaaS"
+
+[relay]
+max_queue_size = 1000
+max_concurrent_per_provider = 5
+batch_window_ms = 50
+retry_delay_ms = 1000
+max_attempts = 3
+
+[rate_limit]
+requests_per_minute = 60
+burst = 10
+```
+
+---
+
+## 10. 接口设计背景与业务价值
+
+### 10.1 中转代理 (Relay) — 核心收入引擎
+
+**背景**: 多家 LLM 服务商 API 各不相同，用户需统一入口。
+
+**设计价值**:
+- OpenAI 兼容接口降低接入成本
+- Key Pool 智能轮转绕过限流
+- 自动 429 处理 + 冷却恢复
+- 按账号精确计费 (input/output tokens)
+
+### 10.2 Prompt OTA — 无感更新
+
+**背景**: Prompt 工程需要频繁迭代，但桌面端发版周期长。
+
+**设计价值**:
+- 集中管理 reflection/compaction/extraction 等核心 Prompt
+- 桌面端每 30 分钟自动检查更新
+- 版本化 + 回滚能力
+- min_app_version 兼容性控制
+
+### 10.3 配置同步 — 多设备一致
+
+**背景**: 用户多台设备需保持配置一致。
+
+**设计价值**:
+- push/pull/merge 三种同步模式
+- 乐观锁 (client_timestamps) 冲突检测
+- 只读 diff 不修改数据
+- 同步日志可追溯
+
+### 10.4 Key Pool — 高可用保障
+
+**背景**: 单个 API Key 容易触发限流 (429)。
+
+**设计价值**:
+- 多 Key 按优先级智能选择
+- 429 自动冷却 + 切换
+- RPM/TPM 限额独立配置
+- 配额重置周期支持
+
+### 10.5 遥测上报 — 数据驱动优化
+
+**背景**: 桌面端本地 LLM 用量无法直接观测。
+
+**设计价值**:
+- 批量上报 (500 条/次) 减少请求
+- 按模型聚合: Token 消耗、延迟、成功率
+- 按天聚合: 请求量、设备活跃度
+- 审计摘要: 操作类型 + 结果
+
+---
+
+> **文档统计**: 84 个 API 端点 | 5 个通信通道 | 12 种权限 | 4 个独立服务