iven/zclaw_openfang
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

docs: reorganize docs — archive outdated, create brainstorming folder
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

Browse Source 
- 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
This commit is contained in:
iven
2026-04-07 09:54:30 +08:00
parent 8e9fc54d92
commit 2e5f63be32
101 changed files with 1829 additions and 17 deletions
Download Patch File Download Diff File Expand all files Collapse all files

347
docs/features/AUDIT_REPORT_V10.md
View File

@@ -1,347 +0,0 @@
# ZCLAW SaaS + Tauri 系统性功能审计报告 V10
> 审计日期: 2026-03-31
> 审计范围: SaaS 后端 (68 路由/22 表) + Tauri 桌面端 (107 命令/13 Store) + admin-v2 管理后台 (14 服务/11 页面)
> 审计方法: 静态代码分析 + 数据流追踪 + 交叉索引
> 修复状态: P0 已修复, P1 已处理, P2 已处理
---
## 1. 执行摘要
### 1.1 整体完成度
| 层级 | 总数 | 活跃 | 未使用 | 利用率 |
|------|------|------|--------|-------|
| SaaS 路由 | 92 | 84 | 8 | **91.3%** |
| Tauri 命令 | 107 | 79 | 28 | **73.8%** |
| Zustand Store | 13 | 13 | 0 | **100%** |
| admin-v2 服务 | 14 | 14 | 0 | **100%** |
### 1.2 问题统计
| 严重级别 | 数量 | 描述 |
|---------|------|------|
| **P0 (阻塞)** | 1 | trigger_update 参数不匹配导致所有 Trigger 更新失效 |
| **P1 (严重)** | 3 | sessionStore 无 Kernel 适配器、定时任务执行器为 stub、配置同步未传播到 kernel |
| **P2 (高)** | 5 | 8 个孤立路由、2 个写而不读 DB 表、Workflow→Pipeline 元数据丢失、Role 管理无 admin 页面、8+ 个 saas-admin 方法无消费者 |
| **P3 (中)** | 6 | CleanupRateLimitWorker stub、CacheKey 死代码、pipeline-client 缺少 probe 检测、GET 请求无速率限制、SSRF DNS 失败不阻断、connectionStore 客户端切换未重新注入 |
| **P4 (低)** | 4 | 7 个 @deprecated TS 标记、a2a feature-gated 代码、ScheduledTaskRow 部分字段、director.rs 休眠代码 |
---
## 2. 功能交叉索引
### 2.1 SaaS 路由 ↔ 前端消费者映射
#### 路由状态分布
| 状态 | 数量 | 说明 |
|------|------|------|
| CONNECTED (两端消费) | 27 | SaaS 路由同时被 desktop 和 admin-v2 调用 |
| DESKTOP_ONLY | 31 | 仅桌面端消费（含 auth、role、device 等） |
| ADMIN_ONLY | 16 | 仅 admin-v2 消费（含 key 管理、prompt 写操作等） |
| ORPHANED | 8 | 无前端消费者 |
| INTERNAL | 1 | health 端点 |
#### 8 个孤立路由（无前端消费者）
| 路由 | 模块 | 建议 |
|------|------|------|
| `GET /api/v1/providers/:id/models` | model_config | 可通过 `GET /api/v1/models?provider_id=X` 替代，考虑移除 |
| `GET /api/v1/config/items/:id` | migration | 无单条配置查询需求，考虑移除 |
| `DELETE /api/v1/config/items/:id` | migration | 无删除配置 UI，考虑移除或添加到 admin-v2 |
| `GET /api/v1/config/analysis` | migration | 配置分析功能未接入，添加到 admin-v2 或移除 |
| `POST /api/v1/config/seed` | migration | 配置种子引导未接入，内部工具保留 |
| `GET /api/v1/config/sync-logs` | migration | 同步日志查询无 UI，添加到 admin-v2 Config 页面 |
| `GET /api/v1/roles/:id/permissions` | role | 角色权限查询无消费者，整合到角色管理 UI |
| `GET /api/scheduler/tasks/:id` | scheduled_task | 单条任务查询无消费者 |
#### 按模块路由覆盖度
| 模块 | 路由数 | Connected | Desktop Only | Admin Only | Orphaned |
|------|-------|-----------|-------------|------------|----------|
| auth | 9 | 3 | 5 | 1 | 0 |
| account | 12 | 5 | 6 | 0 | 0 |
| model_config | 14 | 9 | 3 | 0 | 1 |
| relay | 9 | 2 | 3 | 4 | 0 |
| migration | 11 | 1 | 5 | 0 | 4 |
| role | 11 | 0 | 10 | 0 | 1 |
| prompt | 10 | 3 | 1 | 5 | 0 |
| agent_template | 7 | 1 | 1 | 4 | 0 |
| scheduled_task | 5 | 0 | 4 | 0 | 1 |
| telemetry | 4 | 0 | 2 | 2 | 0 |
| health | 1 | - | - | - | 1 (internal) |
### 2.2 Tauri 命令 ↔ 前端调用映射
#### 28 个未使用命令
| 分类 | 命令 | 原因 |
|------|------|------|
| **遗留 Gateway (11)** | zclaw_status/start/stop/restart/local_auth/prepare_for_tauri/approve_device_pairing/doctor/process_list/process_logs/version + zclaw_health_check + zclaw_ping | Gateway 已被 Kernel 替代，全部遗留代码 |
| **LLM 内部 (3)** | llm_complete, embedding_create, embedding_providers | 后端内部使用，非前端直接调用 |
| **Agent 导出导入 (2)** | agent_export, agent_import | 后端已实现，前端 UI 未接入 |
| **Kernel 管理 (1)** | kernel_shutdown | 无关闭路径 |
| **Hand (1)** | hand_run_cancel | 取消单次运行未接入 UI |
| **定时任务 (2)** | scheduled_task_create, scheduled_task_list | 整个模块未使用 |
| **Pipeline (1)** | pipeline_templates | 模板列表未接入 |
| **Viking (2)** | viking_add_with_metadata, viking_store_with_summaries | 高级存储功能未接入 |
| **Memory (2)** | memory_configure_embedding, memory_is_embedding_configured | 已有 viking 命令替代 |
| **Context (1)** | estimate_content_tokens | 已有 compactor 命令替代 |
---
## 3. 核心数据流追踪
### 3.1 聊天流 + 记忆提取 (BREAK-02 验证)
**结论: PARTIALLY WORKING — 前端正常，后端缺失**
| 层级 | 记忆提取 | 状态 |
|------|---------|------|
| 前端 (chatStore.ts:509) | `onComplete` 回调调用 `getMemoryExtractor().extractFromConversation()` | **WORKING** |
| Rust (intelligence_hooks.rs:50-108) | 仅调用 `reflect()`，不调用 `extract_and_store_memories()` | **NO extraction** |
| Rust Tauri 命令 (lib.rs:204-205) | 仅注册为手动命令 | **Manual only** |
**影响**: 桌面用户通过前端回调正常工作。但任何绕过前端直接调用 Tauri 命令的路径（如 headless/gateway relay）将缺失记忆提取。
**建议**: 在 `post_conversation_hook` 中添加可选的 `extract_and_store_memories` 调用，或在文档中明确说明设计意图。
### 3.2 Hand 触发 + 审批 (BREAK-03 验证)
**结论: CONFIRMED WORKING**
kernel.rs:1118-1193 的 `respond_to_approval` 实现：
- 状态更新为 "approved"
- `tokio::spawn` 创建后台任务
- 调用 `hands.execute(&hand_id, &context, input).await` 执行 Hand
- 更新 HandRun 结果和 approval 状态为 "completed"/"failed"
BREAK-03 **不是问题**，审批后自动执行机制完整。
### 3.3 Agent CRUD 一致性
**结论: INTENTIONAL GAP — 设计意图**
| 路径 | Create | Read | Update | Delete | Export/Import |
|------|--------|------|--------|--------|--------------|
| Kernel (Tauri) | ✅ | ✅ | ✅ | ✅ | ✅ |
| Gateway (REST) | ✅ | ✅ | ✅ | ✅ | ❌ |
| SaaS | 仅 template | 仅 template | 仅 template | 仅 template | ❌ |
SaaS 仅存储 agent 模板（蓝图），运行时 Agent 是本地状态，由 Kernel/Gateway 管理。这是正确的架构决策。
### 3.4 配置同步流
**结论: PARTIALLY WORKING**
| 方向 | 路径 | 状态 |
|------|------|------|
| SaaS → localStorage | `pullConfig()` → `localStorage.setItem()` | ✅ WORKING |
| localStorage → SaaS | `syncConfig()` + dirty tracking | ✅ WORKING |
| localStorage → Kernel | 无传播机制 | ❌ **GAP** |
**影响**: SaaS 同步的配置仅影响前端 UI 设置（如主题），不会传播到运行中的 Rust kernel。kernel 从磁盘 TOML 读取配置，与 localStorage 无关。
---
## 4. 差距模式分析
### 4.1 "写了没接" — 代码存在但未接入
| ID | 项目 | 文件 | 严重性 |
|----|------|------|--------|
| WNC-01 | CleanupRateLimitWorker (空 stub) | `crates/zclaw-saas/src/workers/cleanup_rate_limit.rs` | P3 |
| WNC-02 | 定时任务执行器 (仅状态管理，无实际执行) | `crates/zclaw-saas/src/scheduler.rs:134-192` | P1 |
| WNC-03 | Role 管理 (无 admin-v2 页面) | `admin-v2/src/` 无 roles 服务/页面 | P2 |
| WNC-04 | Agent export/import (前端未接入) | `desktop/src-tauri/src/kernel_commands/agent.rs:213-235` | P4 |
| WNC-05 | pipeline_templates 命令 (无调用) | `desktop/src-tauri/src/pipeline_commands/presentation.rs` | P4 |
### 4.2 "接了没传" — 接口不匹配
| ID | 项目 | 文件 | 严重性 | 详情 |
|----|------|------|--------|------|
| **MSH-01** | **trigger_update 参数不匹配** | `trigger.rs:183` vs `kernel-triggers.ts:92` | **P0** | **前端发 `{id, updates: {name, enabled, handId}}` 嵌套结构，Rust 期望 `{id, name, enabled, hand_id}` 扁平参数。所有 trigger 更新实际为 no-op** |
| MSH-02 | Workflow→Pipeline 元数据丢失 | `workflowStore.ts:379-502` | P2 | 丢失 category/industry/tags/icon/version/author 等字段 |
### 4.3 "传了没存" — 数据接收但未持久化
| ID | 项目 | 文件 | 严重性 |
|----|------|------|--------|
| PTS-01 | 定时任务执行结果 | `scheduler.rs:134-192` | P1 |
### 4.4 "存了没用" — 写入但无读路径
| ID | 表 | 写入位置 | 读路径 | 严重性 |
|----|-----|---------|--------|--------|
| SUN-01 | `prompt_sync_status` | `prompt/service.rs:272` | **无** | P2 |
| SUN-02 | `config_sync_log` | `migration/service.rs:425` | 有 handler 但 handler 本身孤立 | P2 |
### 4.5 "双系统不同步" — SaaS vs Tauri 功能差异
| 领域 | Gateway | Kernel | SaaS | 差距性质 |
|------|---------|--------|------|---------|
| Agent CRUD | REST | invoke | 仅 template | **INTENTIONAL** |
| Session | REST | ❌ 无命令 | ❌ 无路由 | sessionStore 无 Kernel 适配器 |
| Trigger | REST | invoke | ❌ 无路由 | 仅本地，不同步 |
| Browser | ❌ | invoke | ❌ 无路由 | Tauri-only 特性 |
| Pipeline | ❌ | invoke | ❌ 无路由 | Tauri-only 特性 |
| Role 管理 | ❌ | ❌ | REST | 仅 desktop 消费，无 admin UI |
---
## 5. 安全审计
### 5.1 安全控制验证（全部 PASS）
| 控制项 | 状态 | 证据 |
|--------|------|------|
| JWT secret 管理 | ✅ | debug 模式 fallback，release 模式强制要求环境变量 (`config.rs:236-248`) |
| SSRF 防护 | ✅ | 多层验证：主机名黑名单、DNS 解析检查、私有 IP 段、混淆防护 (`relay/service.rs:452-565`) |
| 速率限制 | ✅ | 公开端点分级限流 (login 5/min, register 3/hour)、认证端点 RPM 限制 (`middleware.rs:56-162`) |
| Relay 认证 | ✅ | `relay:use` 权限检查 (`relay/handlers.rs:24`)、key pool 隔离 |
| 请求体大小限制 | ✅ | MAX_BODY_BYTES = 1MB (`relay/handlers.rs:47-50`) |
| IP 提取安全 | ✅ | 不信任 X-Forwarded-For，仅从 TCP 层获取 (`middleware.rs:133-138`) |
### 5.2 安全注意事项
| 项 | 严重性 | 说明 |
|----|--------|------|
| GET 请求无速率限制 | P3 | GET 免于限流 (middleware.rs:62)，可被利用但 GET 无副作用 |
| SSRF DNS 失败不阻断 | P3 | DNS 解析失败时不阻断请求 (service.rs:530-533)，存在窄 TOCTOU 窗口 |
| sessionStore 类型不安全转换 | P3 | `setSessionStoreClient` 无条件 cast 为 GatewayClient (sessionStore.ts:225-228) |
---
## 6. Store 适配器一致性
| Store | Gateway 适配器 | Kernel 适配器 | SaaS 适配器 | 问题 |
|-------|---------------|-------------|------------|------|
| connectionStore | ✅ | ✅ | ✅ | P3: 客户端切换后未重新注入其他 store |
| chatStore | ✅ (via conn) | ✅ (via conn) | ✅ (relay) | 无 |
| agentStore | ✅ | ✅ | ❌ | 无 |
| handStore | ✅ | ✅ | ❌ | P3: fallback 为 stub client |
| workflowStore | ✅ | ✅ | ❌ | P2: Pipeline→Workflow 元数据丢失 |
| configStore | ✅ | ✅ | ✅ | 无 |
| securityStore | ✅ | ✅ | ❌ | 无 |
| **sessionStore** | ✅ | **❌** | ❌ | **P1: 无 Kernel 适配器，Tauri 模式下 session 失效** |
| saasStore | ❌ | ❌ | ✅ | 无 (SaaS 专用) |
| memoryGraphStore | ❌ | ✅ (invoke) | ❌ | 无 |
| browserHandStore | ❌ | ✅ (invoke) | ❌ | P3: Tauri-only 特性 |
| offlineStore | ✅ (via conn) | ✅ (via conn) | ❌ | 无 |
| workflowBuilderStore | ❌ | ❌ | ❌ | 纯本地存储 |
---
## 7. 死代码审计
### 7.1 已验证的假阳性（AUDIT_TRACKER V9 纠正）
| ID | 项目 | 实际状态 |
|----|------|---------|
| DEAD-01 | PromptInjector | **活跃** — 在 zclaw-runtime/growth.rs 和 viking_commands.rs 中使用 |
| DEAD-02 | MemoryRetriever | **活跃** — 在 zclaw-runtime/growth.rs 和 create_growth_system() 中使用 |
| DEAD-03 | GrowthTracker | **活跃** — 在 zclaw-runtime/growth.rs 和 create_growth_system() 中使用 |
| DEAD-04 | director.rs (897 行) | **Feature-gated** — multi-agent 特性，默认不编译 |
| DEAD-05 | saas-admin.ts Role 方法 | **确认死代码** — 8+ 个方法无前端消费者 |
### 7.2 真正的死代码
| 项目 | 文件 | 说明 |
|------|------|------|
| 11 个 Gateway 命令 | `desktop/src-tauri/src/gateway/commands.rs` | Gateway 已被 Kernel 替代 |
| 8+ Role/Permission 方法 | `desktop/src/lib/saas-admin.ts:183-220` | 完整实现但无调用者 |
| CacheKey 结构体 | `crates/zclaw-growth/src/retrieval/cache.rs:22` | 整个结构体从未使用 |
| CleanupRateLimitWorker | `crates/zclaw-saas/src/workers/cleanup_rate_limit.rs` | 空 stub |
---
## 8. 优先修复清单
### P0 — 阻塞（已修复 ✅）
| ID | 问题 | 文件 | 修复方案 | 状态 |
|----|------|------|---------|------|
| MSH-01 | trigger_update 参数不匹配 | `trigger.rs:183` / `kernel-triggers.ts:92` | Rust 端改为接受 `{ id, updates: {...} }` 结构体，匹配前端格式 | ✅ 已修复 |
### P1 — 严重（已处理 ✅）
| ID | 问题 | 文件 | 修复方案 | 状态 |
|----|------|------|---------|------|
| WNC-02 | 定时任务执行器为 stub | `scheduler.rs:134-192` | 添加 TODO(STUB) 标注 + 运行时 warn 日志 | ✅ 已标注 |
| GAP-01 | sessionStore 无 Kernel 适配器 | `sessionStore.ts:225-228` | 添加类型检测，KernelClient 使用 stub 适配器 | ✅ 已修复 |
| GAP-02 | 配置同步未传播到 kernel | `saasStore.ts:528-531` | 评估为设计意图：SaaS 配置为 UI-only，`llm_routing` 通过 account data 已传播 | ✅ 确认设计意图 |
### P2 — 高（下个迭代）
| ID | 问题 | 修复方案 |
|----|------|---------|
| ORPHAN | 8 个孤立路由 | 评估移除或添加 admin-v2 UI |
| SUN-01 | prompt_sync_status 写而不读 | 添加 admin 读路径或移除表 |
| SUN-02 | config_sync_log 写而不读 | 添加 admin-v2 Config 页面 tab |
| MSH-02 | Pipeline→Workflow 元数据丢失 | 扩展 Workflow 类型或标注忽略字段 |
| ADMIN-01 | Role 管理无 admin 页面 | 添加 admin-v2 角色管理页面 |
| DEAD-05 | 8+ saas-admin 方法无消费者 | 接入 UI 或移除 |
### P3 — 中（后续迭代）
| ID | 问题 | 修复方案 |
|----|------|---------|
| STUB-01 | CleanupRateLimitWorker 空实现 | 移除或实现 |
| DEAD-06 | CacheKey 死结构体 | 移除 |
| GAP-03 | pipeline-client 缺少 probe 检测 | 复用 kernel-client 的 probeTauriAvailability |
| GAP-04 | connectionStore 切换后未重新注入 store | 在 connect() 后重新调用 initializeStores() |
| SEC-01 | GET 请求无速率限制 | 监控 GET 量，必要时添加 |
| SEC-02 | SSRF DNS 失败不阻断 | 考虑 DNS 失败时阻断请求 |
### P4 — 低（维护时处理）
| ID | 问题 |
|----|------|
| CLEANUP-01 | 11 个遗留 Gateway 命令移除 |
| CLEANUP-02 | 7 个 @deprecated TS 标记清理 |
| CLEANUP-03 | 4 个 CANDIDATE 级 dead_code 评估 |
| FEATURE-01 | Agent export/import 前端接入 |
| FEATURE-02 | multi-agent (director.rs) 激活准备 |
---
## 9. 验证命令
```bash
# 编译验证
cargo build -p zclaw-saas
# TypeScript 类型检查
cd desktop && pnpm tsc --noEmit
# admin-v2 类型检查
cd admin-v2 && pnpm tsc --noEmit
# Rust 测试
cargo test -p zclaw-saas
# 搜索 trigger_update 不匹配 (P0 验证)
grep -n "trigger_update" desktop/src-tauri/src/kernel_commands/trigger.rs desktop/src/lib/kernel-triggers.ts
# 搜索孤立路由 (P2 验证)
grep -rn "config/analysis\|config/seed\|config/sync-logs" desktop/src/ admin-v2/src/
# 搜索写而不读表 (P2 验证)
grep -rn "prompt_sync_status" crates/zclaw-saas/src/ --include="*.rs"
```
---
## 10. 审计方法总结
本次审计使用了以下技术：
1. **交叉索引** — 92 条 SaaS 路由 × 107 个 Tauri 命令 × 14 个 admin 服务 全量匹配
2. **数据流追踪** — 4 条核心业务流端到端追踪（聊天、Agent CRUD、Hand 审批、配置同步）
3. **差距模式扫描** — 5 种已知差距模式逐一验证
4. **安全面审计** — JWT/SSRF/rate-limit/auth 中间件逐项检查
5. **死代码检测** — `#[allow(dead_code)]` + `#[deprecated]` + 无引用代码全量扫描
6. **接口一致性** — Tauri 命令签名 vs 前端 invoke 参数逐个比对
总审计代码量：~150,000 行 Rust + ~45,000 行 TypeScript + ~8,000 行 SQL

214
docs/features/AUDIT_ROUND3_V11.md
View File

@@ -1,214 +0,0 @@
# ZCLAW 第三轮全面审计报告
> **审计日期**: 2026-04-02
> **基线**: V11 全面审计 + 深度二次审计 + Sprint 1-4 修复
> **方法**: 5 维并行审计（前端状态一致性、数据库 Schema、API 契约、并发安全、代码质量）
> **完成代理**: 前端状态一致性（1/5），其余 4 维因 API 限流由主线程直接执行
---
## 1. 前端状态一致性 + 内存泄漏审计（代理完成）
### HIGH
| ID | 问题 | 文件 | 描述 |
|----|------|------|------|
| AUD3-FE-01 | **chatStore.sendMessage 无并发保护** | `chatStore.ts:403-675` | `isStreaming` 仅在 UI 层守卫，store 函数本身无互斥。快速双击可在 React re-render 前触发两次发送，导致双重 assistant placeholder + stream 竞态 |
| AUD3-FE-02 | **SaaS client token refresh 无并发锁** | `saas-client.ts:217-229` | 多个并发请求同时收到 401 时，各自独立调用 `refreshToken()`，导致多次 refresh 请求。应使用 refresh mutex（共享 Promise） |
### MEDIUM
| ID | 问题 | 文件 | 描述 |
|----|------|------|------|
| AUD3-FE-03 | initializeStores 可能被调用 3 次 | `connectionStore.ts:415,589` + `index.ts:99` | 模块加载 + connect() 双路径，异步操作中切换 client 可能导致请求失败 |
| AUD3-FE-04 | window 全局变量存储 interval | `App.tsx:257-258` | `@ts-expect-error` + `window.__ZCLAW_STATS_SYNC_INTERVAL__`，React StrictMode 双重 mount 时第一个 interval 无法清理 |
| AUD3-FE-05 | GatewayClient mixin 25+ 处 `as any` | `gateway-heartbeat.ts` 等 | prototype 动态方法通过 `as any` 绕过类型检查，属性名拼写错误无编译时报警 |
| AUD3-FE-06 | PropertyPanel 17 处 `as any` 访问联合类型 | `PropertyPanel.tsx:100-276` | WorkflowNodeData 联合类型的字段直接 `as any` 访问，节点类型不匹配时 undefined |
### LOW
| ID | 问题 | 文件 |
|----|------|------|
| AUD3-FE-07 | offlineStore 全局变量存储 timer（多次调用可能泄漏） | `offlineStore.ts:87-88` |
| AUD3-FE-08 | agentStore 一次性读取 chatStore 可能读到中间态 | `agentStore.ts:254` |
| AUD3-FE-09 | retryAllMessages 无并发锁，可能重复发送 | `offlineStore.ts:188-233` |
### POSITIVE FINDINGS（做得好的地方）
- **无 Store 循环依赖**: 依赖方向是单向树状结构
- **事件监听器清理完善**: classroomStore、useAutomationEvents、chatStore 的 listen 全部有 cleanup
- **React useEffect cleanup 规范**: ConnectionStatus、HandApprovalModal、SaaSStatus 全部正确清理
---
## 2. 数据库 Schema + Migration 审计（主线程执行）
### Migration 文件清单（13 个）
| 编号 | 文件 | 内容 |
|------|------|------|
| 20260329-001 | initial_schema.sql | 21 个核心表 |
| 20260329-002 | seed_data.sql | 种子数据 |
| 20260330-001 | scheduled_tasks.sql | 定时任务表 |
| 20260331-001 | accounts_llm_routing.sql | LLM 路由字段 |
| 20260331-002 | agent_templates_extensions.sql | 模板扩展 |
| 20260401-001 | provider_keys_last_used.sql | key 最近使用时间 |
| 20260401-002 | remove_quota_reset_interval.sql | 移除配额重置 |
| 20260401-003 | models_is_embedding.sql | embedding 标记 |
| 20260401-004 | accounts_password_version.sql | 密码版本 |
| 20260401-005 | rate_limit_events.sql | 限流事件 |
| 20260402-001 | billing_tables.sql | 计费 5 表 |
| 20260402-002 | knowledge_base.sql | 知识库 5 表 |
| 20260402-003 | scheduled_task_results.sql | 任务结果列 |
### MEDIUM
| ID | 问题 | 描述 |
|----|------|------|
| AUD3-DB-01 | 无 down migration | 所有 migration 只有 UP，无回滚脚本。生产环境需要回滚时只能手动操作 |
| AUD3-DB-02 | agent_template/service.rs:136 format! 构建 SQL | `format!("SELECT COUNT(*) FROM agent_templates {}", where_clause)` 中 `where_clause` 虽然是硬编码常量（非用户输入），但模式本身违反防御原则 |
### POSITIVE FINDINGS
- **编号连续无冲突**: 13 个 migration 编号连续
- **无 DELETE/UPDATE 缺少 WHERE**: 全量扫描确认所有写操作都有 WHERE 子句
- **仅 2 处 format! SQL**: `agent_template/service.rs` 和 `db.rs`，两者 where_clause/table 均为硬编码
- **zclaw-growth 和 zclaw-memory 无 migration 目录**: 使用代码内 schema 初始化（SQLite）
---
## 3. API 契约 + 错误恢复审计（主线程执行）
### HIGH
| ID | 问题 | 文件 | 描述 |
|----|------|------|------|
| AUD3-API-01 | **SaaS token refresh 并发竞态** | `saas-client.ts:217-229` | 多个并发请求同时收到 401，各自独立调用 `refreshToken()`。无 `_refreshPromise` 或 mutex。refresh token 可能被第一个请求消耗，后续 refresh 请求失败（单次使用 token） |
### MEDIUM
| ID | 问题 | 描述 |
|----|------|------|
| AUD3-API-02 | 前端错误处理不统一 | 部分 invoke() 调用用 try/catch + log（静默），部分直接 throw（用户看到错误），部分 fallback 默认值。无全局错误提示机制 |
| AUD3-API-03 | 37 处 `as any` 类型断言 | 前端大量绕过类型检查，重构时容易引入运行时错误 |
### POSITIVE FINDINGS
- **AbortController 使用规范**: `request-helper.ts` 有完整的 AbortController 管理（Map<string, AbortController>），支持请求取消
- **认证端点跳过 refresh**: `_isAuthEndpoint()` 正确避免 login/register 端点的无限 refresh 循环
- **timeout 配置**: 所有 fetch 调用使用 `AbortSignal.timeout()`
---
## 4. 并发安全 + 资源管理审计（主线程执行）
### MEDIUM
| ID | 问题 | 文件 | 描述 |
|----|------|------|------|
| AUD3-CONC-01 | kernel_commands 每个命令单独获取 kernel_lock | `kernel_commands/*.rs` | 每个 Tauri 命令独立 `state.lock().await`，无嵌套锁获取。设计安全但串行化所有命令执行 |
| AUD3-CONC-02 | ~15 处 fire-and-forget tokio::spawn | `main.rs:108-151`, `relay/handlers.rs:389`, `scheduler.rs:62-140` | 无 JoinHandle，无优雅停机。shutdown 时运行中的任务可能被截断 |
| AUD3-CONC-03 | approval polling 循环持有 kernel_lock | `approval.rs:96` | `kernel_state.lock().await` 在 sleep 循环中反复获取，每次循环释放后重新获取。设计安全但增加锁竞争 |
### POSITIVE FINDINGS
- **无嵌套锁获取**: 每个 kernel_command 只获取一个 MutexLock，不存在 ABBA 死锁风险
- **DashMap 操作规范**: 所有 RefMut 在 `.await` 前释放（已确认）
- **CancellationToken 用于 SSE**: relay 的 SSE 流有取消机制
---
## 5. 代码质量审计（主线程执行）
### 统计数据
| 指标 | 数值 |
|------|------|
| Rust 测试总数 | 584 |
| 前端测试 | 0 (desktop) + 322 (admin-v2) |
| `as any` 使用 | 37 处 |
| `@ts-expect-error` | 3 处 |
| 未使用 Cargo 依赖 | 0（已清理 hmac/sha1） |
| Feature gate 一致性 | 正确 |
| 编译警告 | 1 (private_interfaces) + 1 (sqlx future-incompat) |
---
## 6. 综合发现汇总
### 新增 HIGH（需立即修复）
| ID | 问题 | 影响 |
|----|------|------|
| AUD3-FE-01 | chatStore.sendMessage 无并发保护 | 快速双击导致双重发送 + stream 竞态 |
| AUD3-FE-02 / AUD3-API-01 | SaaS token refresh 无并发锁 | 并发 401 → 多次 refresh → refresh token 被消耗 → 后续请求全部失败 |
### 新增 MEDIUM
| ID | 问题 | 影响 |
|----|------|------|
| AUD3-FE-03 | initializeStores 可能调用 3 次 | 异步操作中 client 切换 |
| AUD3-FE-04 | window 全局变量存 interval | StrictMode 泄漏 |
| AUD3-FE-05 | 25+ 处 mixin `as any` | 类型安全缺口 |
| AUD3-FE-06 | PropertyPanel 17 处 `as any` | 联合类型不安全 |
| AUD3-DB-01 | 无 down migration | 生产回滚困难 |
| AUD3-DB-02 | format! SQL（硬编码安全但模式差） | 防御性编程 |
| AUD3-API-02 | 前端错误处理不统一 | 用户体验不一致 |
| AUD3-CONC-02 | ~15 处 fire-and-forget spawn | 优雅停机问题 |
### 新增 LOW
| ID | 问题 |
|----|------|
| AUD3-FE-07 | offlineStore 全局变量存储 timer |
| AUD3-FE-08 | agentStore 读取中间态 |
| AUD3-FE-09 | retryAllMessages 无并发锁 |
| AUD3-CONC-03 | approval polling 增加锁竞争 |
---
## 7. 三轮审计累计发现总览
| 来源 | P0 | HIGH/P1 | MEDIUM/P2 | LOW/P3/P4 |
|------|-----|---------|-----------|-----------|
| V11 初次审计 | 0 | 3 | 14 | 13 |
| V11 深度二次 | 2 | 9 | 13 | 3 |
| V11 第三轮 | 0 | **2** | **8** | **4** |
| **合计（去重后）** | **2** | **14** | **35** | **20** |
### 已修复 vs 未修复
| 状态 | 数量 |
|------|------|
| **已修复** | 13（2 P0 + 8 P1 + 3 P2） |
| **未修复** | 40 |
### 未修复中按优先级排序的 TOP 10
1. **AUD3-FE-01**: chatStore.sendMessage 并发保护（HIGH）
2. **AUD3-FE-02/API-01**: token refresh mutex（HIGH）
3. **SEC2-P1-01**: FactStore trait 零实现（P1）
4. **SEC2-P1-08**: Desktop 前端零测试（P1）
5. **AUD3-FE-03**: initializeStores 重复调用（MEDIUM）
6. **AUD3-FE-05**: mixin 模式类型安全（MEDIUM）
7. **SEC2-P2-03**: sqlx-postgres 未来兼容性（P2）
8. **SEC2-P2-05**: ~10 处 tokio::spawn 未绑定（P2）
9. **AUD3-DB-01**: 无 down migration（MEDIUM）
10. **SEC2-P1-01**: FactStore trait 零实现（P1）
---
## 8. 积极发现总结
三轮审计确认以下方面**设计良好、实现规范**：
1. **无 Store 循环依赖** — 单向树状依赖结构
2. **事件监听器全部有 cleanup** — listen/unlisten 配对完整
3. **认证中间件全覆盖** — 公共/受保护/Relay 三层路由无遗漏
4. **SQL 参数化规范** — 除 2 处硬编码 format! 外全部使用 bind()
5. **Lock ordering 安全** — 无嵌套锁获取
6. **Feature gate 一致** — 传播链正确
7. **Admin API 100% 对齐** — 前后端路由完全匹配
8. **编译通过** — cargo check 仅 1 warning
9. **密码安全** — Argon2id + password_version + JWT 失效
10. **SSE 背压设计** — 有界 channel + 信号量 + CancellationToken

236
docs/features/COMPREHENSIVE_AUDIT_V11.md
View File

@@ -1,236 +0,0 @@
# ZCLAW 全面功能审计报告 V11
> **审计日期**: 2026-04-02
> **审计范围**: 10 Rust crate + desktop 前端 + admin-v2 管理后台
> **基线**: V10 审计追踪（20 项发现）
---
## 1. 执行摘要
### 关键指标
| 指标 | 数值 | 文档值 | 状态 |
|------|------|--------|------|
| Tauri 命令（注册） | 175 | 58+ / 130+ | 文档不一致 |
| Tauri 命令（有前端调用） | ~90 | - | 51% 利用率 |
| SKILL.md | 76 | 66/75/77 | 文档不一致 |
| Hands | 9 目录 | 11 | CLAUDE.md 与实际不一致 |
| Zustand Stores | 15 | 14 | 文档偏差 |
| SaaS API 路由 | 58 | 72+ | 文档偏高 |
| Admin-v2 页面 | 12 | 11 | 文档偏低 |
| 源文件 | 233 (.rs) + 122 (.tsx) + 15 (.ts store) | - | - |
### V10→V11 状态变更
| V10 ID | V11 状态 | 说明 |
|--------|----------|------|
| BREAK-02 | **关闭** | 记忆提取通过 MemoryMiddleware.after_completion 正常触发 |
| BREAK-03 | **关闭** | approval_respond 自动 spawn tokio task 执行 Hand |
| BREAK-04 | **关闭** | pipeline-complete 在 discovery.rs:165 emit，前端有监听器 |
| BREAK-01 | 已修复 | 保持 CLOSED |
---
## 2. 发现项索引
### P1: 严重级（3 项）
| ID | 问题 | 文件 | 验证方法 |
|----|------|------|----------|
| V11-P1-01 | trigger_update 参数不匹配，更新静默失败 | `desktop/src/lib/kernel-triggers.ts:99` → `desktop/src-tauri/src/kernel_commands/trigger.rs:183-189` | 前端发 `{id, updates:{...}}` 但 Rust 期望扁平参数 |
| V11-P1-02 | SaaS 配置同步不传播到 Rust Kernel | `desktop/src/store/saasStore.ts:484-541` | localStorage 写入但 Kernel 无读取路径 |
| V11-P1-03 | 3 个 SQL 表零读取：prompt_sync_status, telemetry_reports, key_usage_window | `crates/zclaw-saas/src/db.rs` 迁移定义 | `grep -rn "SELECT.*FROM.*<table>" crates/zclaw-saas/src/` 零结果 |
### P2: 高优先级（6 项）
| ID | 问题 | 文件 |
|----|------|------|
| V11-P2-01 | saas-admin.ts 30 方法零消费者（admin-v2 独立 Axios 实现） | `desktop/src/lib/saas-admin.ts` |
| V11-P2-02 | 7 个 Role/Permission 路由无前端消费者 | `crates/zclaw-saas/src/role/mod.rs` |
| V11-P2-03 | deprecated gateway-storage sync 方法仍被生产代码调用 | `desktop/src/lib/gateway-storage.ts:129,196` |
| V11-P2-04 | ToolDefinition 在 types 和 runtime 重复定义 | `crates/zclaw-types/src/tool.rs:8` vs `crates/zclaw-runtime/src/driver/mod.rs:94` |
| V11-P2-05 | 62 个 Tauri 命令无前端调用（含 8 classroom 命令中 7 个未调用） | `desktop/src-tauri/src/lib.rs:124-323` |
| V11-P2-06 | migration/service.rs config_items 查询缺少 LIMIT | `crates/zclaw-saas/src/migration/service.rs` |
### P3: 中优先级（8 项）
| ID | 问题 | 文件 |
|----|------|------|
| V11-P3-01 | audit-logger.ts 导出但零 import | `desktop/src/lib/audit-logger.ts` |
| V11-P3-02 | OFP 能力定义无消费者 | `crates/zclaw-types/src/capability.rs:28-32` |
| V11-P3-03 | deprecated extract_structured_facts() 零调用但未移除 | `crates/zclaw-runtime/src/growth.rs:224` |
| V11-P3-04 | SaaS knowledge 模块 3 个 handler 返回空数据 | `crates/zclaw-saas/src/knowledge/handlers.rs:91,293,321` |
| V11-P3-05 | Director (multi-agent) 912 行 feature-gated 未启用 | `crates/zclaw-kernel/src/director.rs` |
| V11-P3-06 | 定时任务执行结果未持久化 | `crates/zclaw-saas/src/scheduler.rs:147-225` |
| V11-P3-07 | secure-storage.ts 3 个 deprecated sync 方法零调用 | `desktop/src/lib/secure-storage.ts:309,317,325` |
| V11-P3-08 | SaaS config 2 个预留参数未消费 | `crates/zclaw-saas/src/config.rs:122,125` |
### P4: 低优先级（5 项）
| ID | 问题 | 文件 |
|----|------|------|
| V11-P4-01 | ContentBlock 4 处定义（不同域，非 bug 但名称混淆） | types/message.rs, runtime/driver/mod.rs, hands/slideshow.rs, protocols/mcp_types.rs |
| V11-P4-02 | Desktop ↔ Admin 13+ 类型名称不一致 | `desktop/src/lib/saas-types.ts` vs `admin-v2/src/types/index.ts` |
| V11-P4-03 | 文档数字不一致（Skills 76 vs 66/75/77） | 多个文档 |
| V11-P4-04 | A2A/WASM feature-gated 代码未启用 | `crates/zclaw-protocols/src/a2a.rs`, `crates/zclaw-skills/src/wasm_runner.rs` |
| V11-P4-05 | embedding 生成已禁用（注释掉） | `crates/zclaw-saas/src/workers/generate_embedding.rs:92` |
### Info: 保留不变（V10 继承）
| V10 ID | 状态 | 说明 |
|--------|------|------|
| DEAD-01 | FALSE_POSITIVE | PromptInjector 已通过 PromptBuilder 接入 |
| DEAD-02 | FALSE_POSITIVE | MemoryRetriever 已通过 MemoryMiddleware 接入 |
| DEAD-03 | FALSE_POSITIVE | GrowthTracker 已通过 GrowthIntegration 接入 |
| SEC-V9-01 | FALSE_POSITIVE | SQL 仅构建 $N 占位符 |
---
## 3. Rust Crate 能力矩阵
| Crate | 源文件 | 行数 | 公开项 | Feature-Gate | Dead Code | Deprecated | 测试 |
|-------|--------|------|--------|-------------|-----------|------------|------|
| zclaw-types | 10 | 1,741 | 86 | 0 | 0 | 0 | 57 |
| zclaw-memory | 5 | 1,333 | 36 | 0 | 0 | 0 | 25 |
| zclaw-runtime | 35 | 9,145 | 188 | 0 | 5 | 1 | 42 |
| zclaw-kernel | 25 | 8,185 | 225 | 22 (multi-agent) | 3 | 0 | 52 |
| zclaw-skills | 15 | 4,057 | 116 | 4 (wasm) | 0 | 0 | 22 |
| zclaw-hands | 14 | 7,501 | 140 | 0 | 0 | 0 | 155 |
| zclaw-protocols | 5 | 1,697 | 104 | 2 (a2a) | 1 | 0 | 5 |
| zclaw-pipeline | 23 | 7,502 | 200 | 0 | 1 | 0 | 59 |
| zclaw-growth | 14 | 4,732 | 137 | 0 | 2 | 0 | 66 |
| zclaw-saas | 87 | 14,949 | 489 | 0 | 2 | 0 | 17 |
| **合计** | **233** | **64,842** | **1,621** | **28** | **14** | **1** | **500** |
### Trait 实现完整性
| Trait | 定义位置 | 实现数 | 状态 |
|-------|----------|--------|------|
| LlmDriver | zclaw-runtime/driver/mod.rs | 4 | 完整 |
| Tool | zclaw-runtime/tool.rs | 7 | 完整 |
| Hand | zclaw-hands/hand.rs | 9 | 完整 |
| Exporter | zclaw-kernel/export/mod.rs | 4 | 完整 |
| McpClient | zclaw-protocols/mcp.rs | 2 | 完整 |
| A2aClient | zclaw-protocols/a2a.rs | 1 (gated) | Feature-gated |
| FactStore | zclaw-memory/fact.rs | **0** | **未实现** |
| Worker | zclaw-saas/workers/mod.rs | 7 | 完整 |
---
## 4. 数据流验证结果
### Flow A: 聊天 → 记忆提取 ✅ WORKING
```
chat.rs:246 (LoopEvent::Complete)
→ loop_runner.rs:798 (run_after_completion)
→ MemoryMiddleware.after_completion (middleware/memory.rs:101)
→ GrowthIntegration.extract_combined (growth.rs:279)
→ MemoryExtractor.extract + store_memories
```
Tauri `post_conversation_hook` 不重复提取，仅处理心跳+反思。
### Flow B: 审批 → Hand 自动执行 ✅ WORKING
```
approval.rs:52 → kernel.respond_to_approval (approvals.rs:55)
→ tokio::spawn (approvals.rs:71)
→ hands.execute (approvals.rs:99)
→ emit "hand-execution-complete" (approval.rs:84-137)
```
### Flow C: Pipeline 完成事件 ✅ WORKING
```
Rust emit: discovery.rs:165 → app.emit("pipeline-complete", ...)
Frontend listen: pipeline-client.ts:257 → PipelinesPanel.tsx:383
```
### Flow D: SaaS 配置同步 ❌ BROKEN
```
saasStore.ts:484 → saasClient.pullConfig → localStorage write
⚠️ 无传播路径到 Rust Kernel
```
配置变更停留在 `localStorage`，Kernel 独立读取 TOML 文件，不受 SaaS 配置同步影响。
---
## 5. Admin-v2 审计
### 页面与 API 对齐
| 页面 | Service 文件 | API 调用数 | 状态 |
|------|-------------|-----------|------|
| Login | auth.ts | 2 | 完整 |
| Dashboard | stats.ts | 1 | 完整 |
| Accounts | accounts.ts | 4 | 完整 |
| ModelServices | providers.ts + models.ts | 11 | 完整 |
| Config | config.ts | 2 | 完整 |
| Relay | relay.ts | 2 | 完整 |
| Logs | logs.ts | 1 | 完整 |
| Prompts | prompts.ts | 7 | 完整 |
| Usage | usage.ts | 2 | 完整 |
| Billing | billing.ts | 6 | 完整 |
| AgentTemplates | agent-templates.ts | 5 | 完整 |
| Knowledge | knowledge.ts | 15 | 完整（后端有 3 个 stub handler） |
### 类型一致性
Desktop ↔ Admin-v2 之间存在 13+ 类型名称不一致（详见 V11_GAP_ANALYSIS.md）。
3 个有意义的字段差异：
1. `AccountPublic.llm_routing`: desktop 可选 vs admin 必填
2. `TokenInfo` nullability: `string | null` vs `string | undefined`
3. `PromptVariable.type`: `string` vs `'string'|'number'|'select'|'boolean'`
---
## 6. 孤立路由清单
| 路由 | 模块 | 原因 |
|------|------|------|
| POST /api/v1/auth/logout | auth | 无消费者 |
| GET /api/v1/config/analysis | migration | 无消费者 |
| POST /api/v1/config/seed | migration | 无消费者 |
| GET /api/v1/config/sync-logs | migration | 无消费者 |
| GET /api/v1/usage (model_config) | model_config | 无消费者 |
| GET/POST /api/v1/roles | role | 无 admin-v2 service |
| GET/PUT/DELETE /api/v1/roles/:id | role | 无 admin-v2 service |
| GET/POST /api/v1/permission-templates | role | 无 admin-v2 service |
| GET/DELETE /api/v1/permission-templates/:id | role | 无 admin-v2 service |
| POST /api/v1/permission-templates/:id/apply | role | 无 admin-v2 service |
| GET /api/v1/roles/:id/permissions | role | 无 admin-v2 service |
---
## 7. 验证命令
```bash
# Skills 计数
ls skills/ | wc -l # 预期: 76
# Hands 计数
ls hands/ | wc -l # 预期: 9
# Tauri 命令计数
grep -c "#\[tauri::command\]" desktop/src-tauri/src/ -r --include="*.rs" # 预期: 175
# 死代码验证
grep -rn "from.*audit-logger" desktop/src/ --include="*.ts" # 预期: 0 结果
# 孤立表验证
grep -rn "SELECT.*FROM.*prompt_sync_status" crates/zclaw-saas/src/ # 预期: 0 结果
grep -rn "SELECT.*FROM.*telemetry_reports" crates/zclaw-saas/src/ # 预期: 0 结果
grep -rn "SELECT.*FROM.*key_usage_window" crates/zclaw-saas/src/ # 预期: 0 结果
# deprecated 函数调用者
grep -rn "extract_structured_facts" crates/ --include="*.rs" # 仅定义和注释引用
# trigger_update 参数不匹配
grep -A5 "trigger_update" desktop/src/lib/kernel-triggers.ts
grep -A5 "trigger_update" desktop/src-tauri/src/kernel_commands/ -r --include="*.rs"
```

539
docs/features/COMPREHENSIVE_AUDIT_V5.md
View File

@@ -1,539 +0,0 @@
# ZCLAW 功能完整性深度审计报告 v5
> **ARCHIVED — 此报告已过时**
>
> 本报告是 2026-03-27 审计迭代的 v5 版本。最终结论已合并到 DEEP_AUDIT_REPORT.md。
>
> **请参考最新文档** → [README.md](./README.md)
> **审计日期**: 2026-03-27
> **修复日期**: 2026-03-27
> **审计方法**: 五步审计法（文档对齐 → 数据流追踪 → dead_code 识别 → trait 实现 → 端到端验证）
> **审计范围**: 全部 10 个 Rust crate + Tauri 后端（100+ 命令）+ React 前端 + docs/features 28 份文档
> **独立性声明**: 本报告独立于此前 4 份审计报告，所有结论基于代码实际状态得出。前审计已修复 27 项，本审计在此基础上发现 8 项新问题，**已全部修复**。
---
## 一、执行摘要
### 1.1 总体完成度
| 维度 | DEEP_AUDIT 声称 | 本审计验证 | 修复后 |
|------|----------------|-----------|--------|
| **整体完成度** | ~72% → ~85% | **~78%** | **~82%** |
| **核心功能可用** | ~92% | **~92%** | **~95%** |
| **智能层真实可用** | ~80% | **~75%** | **~80%** |
| **扩展层** | ~80% | **~65%** | **~70%** |
### 1.2 关键发现
1. **DEEP_AUDIT 27 项修复：25 项确认到位，2 项部分到位**
2. **新发现 8 项问题**（1 CRITICAL + 4 MEDIUM + 3 LOW）— ✅ **已全部修复**
3. **~2485 行孤立代码**已通过条件编译处理（Director + A2A 在 `multi-agent` feature 下可用）
4. **WhiteboardHand Export** 已标记为 demo
5. **Pipeline YAML 模板实际存在**（DEEP_AUDIT M7 误判纠正）
---
## 二、DEEP_AUDIT 27 项修复独立验证
### 2.1 P0 修复（3 项）
| ID | 修复内容 | 验证结果 | 证据 |
|----|---------|---------|------|
| C1 | PromptOnly 通过 LlmCompleter 调用 LLM | ✅ CONFIRMED | `skill.rs:96` `llm: Option<Arc<dyn LlmCompleter>>`; `kernel.rs:62` `LlmDriverAdapter` 桥接; `kernel.rs:79` `llm: Some(self.llm.clone())` 注入 SkillContext |
| C2 | 反思引擎传入真实记忆 | ✅ CONFIRMED | `intelligence_hooks.rs:79` `query_memories_for_reflection(agent_id).await`; `intelligence_hooks.rs:182-210` 函数实现：查询 VikingStorage 最多 50 条记忆 |
| H5 | VERIFICATION_REPORT 归档 | ✅ CONFIRMED | 文件前 10 行标记 `⚠️ ARCHIVED` |
### 2.2 P1 修复（8 项）
| ID | 修复内容 | 验证结果 | 证据 |
|----|---------|---------|------|
| H7 | KernelClient 适配 listClones/createClone/deleteClone | ✅ CONFIRMED | `kernel-client.ts:370-415` 三个方法映射到 `listAgents/createAgent/deleteAgent` |
| H8 | hand_execute 检查 needs_approval | ✅ CONFIRMED | `kernel_commands.rs:846-864` 双层检查：supervised 模式全部拦截 + 非 autonomous 模式检查 `needs_approval` |
| M1 | 幽灵命令注册 | ✅ CONFIRMED | `lib.rs:1344-1346` `hand_get`/`hand_run_status`/`hand_run_list` 已注册 |
| H1 | SpeechHand 标记 demo | ✅ CONFIRMED | `speech.rs:236` 注释 `"In real implementation, would call TTS API"`; DEEP_AUDIT 已标注 |
| H2 | TwitterHand 标记 demo | ✅ CONFIRMED | `twitter.rs:297-509` 所有操作返回 `"(simulated)"`; DEEP_AUDIT 已标注 |
| H3 | 记忆统一到 VikingStorage | ✅ CONFIRMED | `memory_commands.rs:1-7` 明确声明 "Unified storage: All operations delegate to VikingStorage"; `memory_store()` 第 68 行 `get_storage().await` → `VikingStorage::store()` |
| H4 | 心跳持久化 | ✅ CONFIRMED | `heartbeat.rs:459-467` `record_interaction()` 通过 `tokio::spawn` 将时间戳写入 VikingStorage metadata |
| H6 | Presentation 渲染器 | ✅ CONFIRMED | 4 个渲染器文件存在：`ChartRenderer.tsx`、`DocumentRenderer.tsx`、`SlideshowRenderer.tsx`、`QuizRenderer.tsx` |
### 2.3 P2 修复（9 项）
| ID | 修复内容 | 验证结果 | 证据 |
|----|---------|---------|------|
| M4b | maybe_compact_with_config 支持 LLM | ✅ CONFIRMED | `compaction.rs:279-299` `if config.use_llm` → 调用 `generate_llm_summary()` → 失败回退 `generate_summary()` |
| M4c | 压缩时记忆刷出 | ✅ CONFIRMED | `compaction.rs:228-253` `if config.memory_flush_enabled` → `growth.process_conversation()` |
| M4 | 反思结果持久化 | ✅ CONFIRMED | `reflection.rs:611-630` `restore_state()` 从 VikingStorage metadata 恢复; `persist_state()` 持久化 |
| M5 | 自主授权后端守卫 | ✅ CONFIRMED | `kernel_commands.rs:680-682` skill_execute supervised 模式拦截; `kernel_commands.rs:828-842` hand_execute 双层守卫 |
| M3 | hand_approve 使用 hand_name | ⚠️ PARTIAL | `kernel_commands.rs:1169-1171` 日志记录 hand_name，但 `respond_to_approval(&run_id, ...)` 只用 run_id，hand_name 未参与查找逻辑 |
| L2 | gatewayStore 清理 | ✅ CONFIRMED | `gatewayStore.ts` 保留为 re-export facade，多个 store 文件仅引用类型 |
| S9 | 消息搜索 Global 模式 | ✅ CONFIRMED | DEEP_AUDIT 声称已修复，MessageSearch 组件存在 |
| M6 | RuntimeLlmIntentDriver 语义路由 | ✅ CONFIRMED | `intent.rs:406-464` `RuntimeLlmIntentDriver` 包装 `LlmDriver`，`semantic_match()` 调用 LLM 并解析 JSON 响应 |
| L1 | Pipeline 并行 buffer_unordered | ✅ CONFIRMED | `stage.rs:355` `.buffer_unordered(workers)`; `executor.rs:397` 同样使用 |
### 2.4 P3 修复（7 项）
| ID | 修复内容 | 验证结果 | 证据 |
|----|---------|---------|------|
| Reflection LLM | analyze_patterns_with_llm() | ✅ CONFIRMED | `reflection.rs:314-353` 完整实现：构建 memory_summary + LLM prompt + JSON 解析 |
| Reflection History | 累积存储 | ✅ CONFIRMED | `intelligence_hooks.rs` 调用 `reflect()` 后结果写入 VikingStorage |
| Identity Rollback | HistoryItem + restoreSnapshot | ✅ CONFIRMED | DEEP_AUDIT 声称 IdentityChangeProposal.tsx 已实现 |
| autonomy_level | hand_execute/skill_execute 参数 | ✅ CONFIRMED | 两个命令都接受 `autonomy_level: Option<String>` 参数 |
| 心跳历史 | VikingStorage metadata | ✅ CONFIRMED | `heartbeat.rs:459-467` 持久化交互时间 |
| 记忆统一 | memory_commands 全部委派 | ✅ CONFIRMED | `memory_commands.rs:68` `get_storage().await` → VikingStorage |
| 幽灵命令 | hand_get/hand_run_status/hand_run_list | ✅ CONFIRMED | `lib.rs:1344-1346` |
### 2.5 修复验证总结
| 结果 | 数量 | 占比 |
|------|------|------|
| ✅ CONFIRMED（完全确认） | 25 | 93% |
| ⚠️ PARTIAL（部分到位） | 2 | 7% |
| ❌ REVERTED（回退） | 0 | 0% |
**部分到位的 2 项**：
- **M3**: `hand_approve` 日志记录了 `hand_name`，但实际审批查找只用 `run_id`，`hand_name` 未参与业务逻辑
- **S9**: 消息搜索 Global 模式声称已修复，但未深入验证前端是否真正调用 VikingStorage 跨会话搜索
---
## 三、新发现问题（前 4 次审计均未发现）
### 3.1 CRITICAL（1 项）
#### N1: Whiteboard Hand Export 动作返回伪造 data_url
| 属性 | 值 |
|------|---|
| **文件** | `crates/zclaw-hands/src/hands/whiteboard.rs:254-260` |
| **差距模式** | 写了没接 |
| **严重度** | CRITICAL |
| **证据** | `"data:image/{};base64,<rendered_data>"` — 硬编码占位字符串，非真实图片数据 |
```rust
WhiteboardAction::Export { format } => {
// In real implementation, would render to image
return Ok(HandResult::success(serde_json::json!({
"status": "exported",
"format": format,
"data_url": format!("data:image/{};base64,<rendered_data>", format)
})));
}
```
**影响**: 用户触发 Whiteboard Hand 的"导出"功能期望获得真实图片，实际获得包含 `<rendered_data>` 占位符的伪造 URL。
### 3.2 MEDIUM（4 项）
#### N2: Director 模块（907 行）完全孤立
| 属性 | 值 |
|------|---|
| **文件** | `crates/zclaw-kernel/src/director.rs`（907 行） |
| **差距模式** | 写了没接 |
| **严重度** | MEDIUM |
**详情**: 实现了完整的多 Agent 协作系统（5 种调度策略、Agent 角色系统、LLM 说话人选择），有 8 个单元测试。从 `lib.rs` 导出为 `pub mod director` + `pub use director::*`，但：
- 无 Tauri 命令暴露
- 无前端 `invoke()` 调用
- `kernel.rs` 不使用 Director
- 前端 Team/Swarm UI 已被删除
#### N3: A2A 协议（690 行）仅被孤立的 Director 消费
| 属性 | 值 |
|------|---|
| **文件** | `crates/zclaw-protocols/src/a2a.rs`（690 行） |
| **差距模式** | 写了没接 |
| **严重度** | MEDIUM |
**详情**: 实现了完整的 Agent-to-Agent 通信协议（信封、路由、组管理、能力发现）。`a2a.rs:259` 标记 `#[allow(dead_code)]`。唯一消费者是 `director.rs`（本身孤立）。
#### N4: viking_adapter find() 使用 String.contains()（降级为 LOW）
| 属性 | 值 |
|------|---|
| **文件** | `crates/zclaw-growth/src/viking_adapter.rs:160-166` |
| **差距模式** | 写了没接 |
| **原严重度** | MEDIUM → **降级为 LOW** |
**纠正**: 经深入追踪，生产环境搜索路径 `intelligence_hooks.rs:112-113` 调用的是 `SqliteStorage.find()`，**不是** `VikingAdapter.find()`。`SqliteStorage.find()` 实现了完整的 TF-IDF + Embedding 混合评分（70% embedding + 30% TF-IDF）。`VikingAdapter` 是一个独立的适配器，当前不被生产路径使用。
#### N5: compactor_compact_llm 注册但前端无调用
| 属性 | 值 |
|------|---|
| **文件** | `desktop/src-tauri/src/lib.rs:1469`（注册） |
| **差距模式** | 写了没接 |
| **严重度** | MEDIUM |
**详情**: `compactor_compact_llm` 作为 Tauri 命令注册，但前端 `intelligence-backend.ts` 中无 `invoke('compactor_compact_llm')` 调用。`maybe_compact_with_config()` 在 runtime 层已支持 LLM 自动压缩，所以手动触发路径是冗余的。
### 3.3 LOW（3 项）
#### N6: MCP 协议框架无消费者
| 属性 | 值 |
|------|---|
| **文件** | `crates/zclaw-protocols/src/mcp.rs` + `mcp_transport.rs`（~588 行） |
| **差距模式** | 写了没接 |
| **严重度** | LOW |
**详情**: 完整的 MCP client trait + transport 实现 + `BasicMcpClient`，但无 Tauri 命令、无 kernel 集成、无前端调用。
#### N7: scheduled_task 调度循环未实现
| 属性 | 值 |
|------|---|
| **文件** | `desktop/src-tauri/src/kernel_commands.rs:1301` |
| **差距模式** | 写了没接 |
| **严重度** | LOW |
**详情**: 注释明确标注 "not yet implemented in embedded kernel mode"。`scheduled_task_create` 创建 TriggerConfig，`scheduled_task_list` 列出已有触发器，但没有后台调度循环执行它们。
#### N8: hand_approve 的 hand_name 参数仅用于日志
| 属性 | 值 |
|------|---|
| **文件** | `desktop/src-tauri/src/kernel_commands.rs:1158-1182` |
| **差距模式** | 接了没传 |
| **严重度** | LOW |
**详情**: `hand_approve` 接收 `hand_name` 参数但仅用于 `tracing::info!` 日志，实际审批操作 `respond_to_approval(&run_id, approved, reason)` 只使用 `run_id`。
---
## 四、孤立代码总量
| 模块 | 行数 | 状态 | 建议 |
|------|------|------|------|
| `director.rs` | 907 | 完全孤立，无 Tauri 命令 | 条件编译 `#[cfg(feature = "director")]` |
| `a2a.rs` | 690 | 仅被孤立的 director 消费 | 跟随 director 处理 |
| `mcp.rs` + `mcp_transport.rs` | ~588 | 无消费者 | 保留为框架预留 |
| `zclaw-channels` 整个 crate | ~300 | 仅 ConsoleChannel | 维持现状 |
| **合计** | **~2485 行** | | |
---
## 五、10 条核心数据流追踪
### 5.1 聊天消息流 ✅ 已验证
```
ChatArea.tsx → chatStore.sendStreamMessage()
→ kernel-client.ts sendStreamMessage() → invoke('agent_chat_stream')
→ kernel_commands.rs agent_chat_stream()
→ intelligence_hooks.rs pre_conversation_hook()
→ build_memory_context() → VikingStorage.find() ✅ (SqliteStorage, TF-IDF + Embedding)
→ build_identity_prompt() → IdentityManager.build_system_prompt() ✅
→ kernel.agent_chat_stream()
→ loop_runner.rs AgentLoop (compaction threshold 15k) ✅
→ LLM driver (4 implementations) ✅
→ intelligence_hooks.rs post_conversation_hook()
→ heartbeat.record_interaction() ✅ (VikingStorage metadata)
→ reflection.record_conversation() + should_reflect() ✅
→ Tauri events ✅
→ kernel-client.ts event listener ✅
→ ChatArea.tsx render ✅
```
**断点**: 无。完整链路。
### 5.2 Hand 执行流 ✅ 已验证（含审批 + 自主守卫）
```
HandList.tsx → handStore.triggerHand()
→ kernel-client.ts triggerHand() → invoke('hand_execute')
→ kernel_commands.rs hand_execute()
→ autonomy_level == "supervised" → create_approval → return pending ✅
→ autonomy_level != "autonomous" && needs_approval → create_approval → return pending ✅
→ kernel.execute_hand() → HandRegistry.get() → Hand.execute()
→ [真实] QuizHand, ResearcherHand, CollectorHand, ClipHand ✅
→ [委托] BrowserHand → Tauri browser commands ✅
→ [模拟] SpeechHand ❌ "In real implementation"
→ [模拟] TwitterHand ❌ "(simulated)"
→ [模拟] WhiteboardHand(Export) ❌ "In real implementation" (NEW)
→ 结果返回 ✅
→ handStore 处理结果 ✅
→ UI 显示 ✅
```
**断点**: SpeechHand、TwitterHand、WhiteboardHand(Export) 返回模拟数据。
### 5.3 记忆存储流 ✅ 已验证（统一到 VikingStorage）
```
路径A (UI面板):
MemoryPanel.tsx → intelligence-backend.ts memory_store()
→ invoke('memory_store') → memory_commands.rs
→ get_storage() → VikingStorage::store() (SqliteStorage) ✅
路径B (聊天流程):
intelligence_hooks.rs build_memory_context()
→ get_storage() → VikingStorage::find() (SqliteStorage)
→ TF-IDF + Embedding hybrid scoring ✅
```
**断点**: 无。双路径统一到同一 SqliteStorage 实例。
### 5.4 技能执行流 ✅ 已验证
```
SkillMarket.tsx → kernel-client.ts executeSkill()
→ invoke('skill_execute') → kernel_commands.rs skill_execute()
→ autonomy guard ✅
→ kernel.execute_skill() → SkillRegistry → SkillExecutor
→ PromptOnlySkill → SkillContext.llm (Some(LlmDriverAdapter))
→ LlmCompleter.complete() → LLM driver → AI 生成内容 ✅
→ ShellSkill → subprocess ✅
→ WasmSkill/NativeSkill → 回退到 PromptOnly ✅
```
**断点**: WasmSkill/NativeSkill 回退到 PromptOnly（已知，非阻塞）。
### 5.5 Pipeline 执行流 ✅ 已验证
```
PipelinesPanel.tsx → workflowStore → invoke('pipeline_run')
→ pipeline_commands.rs → StageEngine
→ Parallel stage: buffer_unordered(max_workers) ✅
→ Sequential/Conditional/Skill/Hand stages ✅
→ 5 YAML templates exist in pipelines/ directory ✅
```
**断点**: 无。
### 5.6 反思流 ✅ 已验证
```
post_conversation_hook → record_conversation()
→ should_reflect() → 阈值检查
→ query_memories_for_reflection() → VikingStorage (max 50) ✅
→ reflect(agent_id, &memories, llm_driver)
→ use_llm && driver → analyze_patterns_with_llm() ✅
→ fallback → analyze_patterns() (rule-based) ✅
→ persist_state() → VikingStorage metadata ✅
```
**断点**: 反思结果在 VikingStorage 中，但需确认 ReflectionLog.tsx 是否展示持久化的历史数据。
### 5.7 心跳流 ⚠️ 部分验证
```
App.tsx → heartbeat.start()
→ tokio spawn → tick loop (30 min interval)
→ check_pending_tasks / check_memory_health / check_reflection_readiness
→ record_interaction() → VikingStorage metadata ✅
→ history restore on restart ✅
```
**断点**: 默认 `enabled: false`（`heartbeat.rs` 配置），但 `App.tsx` 主动调用 `start()`。
### 5.8 身份演化流 ✅ 已验证
```
build_identity_prompt() → IdentityManager.build_system_prompt()
→ SOUL.md 读取 → 注入 system prompt → 聊天
```
### 5.9 上下文压缩流 ✅ 已验证
```
loop_runner → maybe_compact_with_config()
→ memory_flush_enabled → growth.process_conversation() ✅
→ use_llm → generate_llm_summary() → fallback generate_summary() ✅
→ 消息替换 ✅
```
### 5.10 审批流 ✅ 已验证
```
HandApprovalModal.tsx → invoke('hand_approve')
→ kernel_commands.rs → respond_to_approval(&run_id, approved, reason) ✅
```
---
## 六、5 种差距模式分析
### 模式 1: "写了没接"（Code exists but not integrated）
| 实例 | 文件 | 行数 | 严重度 |
|------|------|------|--------|
| Director 模块 | `zclaw-kernel/src/director.rs` | 907 | MEDIUM |
| A2A 协议 | `zclaw-protocols/src/a2a.rs` | 690 | MEDIUM |
| MCP 协议 | `zclaw-protocols/src/mcp.rs` | ~588 | LOW |
| compactor_compact_llm | `lib.rs:1469` 注册无调用 | ~50 | MEDIUM |
| WhiteboardHand Export | `hands/whiteboard.rs:254` | ~10 | CRITICAL |
| zclaw-channels | 整个 crate | ~300 | LOW |
| SpeechHand | `hands/speech.rs:236` | 模拟 | LOW (已标注) |
| TwitterHand | `hands/twitter.rs:297` | 模拟 | LOW (已标注) |
| scheduled_task 调度循环 | `kernel_commands.rs:1301` | ~50 | LOW |
**系统建议**: 孤立代码总量 ~2485 行。建议按功能分组决策：Director+A2A 一起处理，MCP 独立保留，channels 维持现状。
### 模式 2: "接了没传"（Connected but parameter ignored）
| 实例 | 文件 | 详情 |
|------|------|------|
| hand_approve hand_name | `kernel_commands.rs:1158` | hand_name 仅用于日志，未参与审批查找 |
### 模式 3: "传了没存"（Passed but not persisted）
| 实例 | 状态 |
|------|------|
| 心跳 record_interaction | ✅ 已修复 — 写入 VikingStorage metadata |
| 反思结果 | ✅ 已修复 — 写入 VikingStorage metadata |
### 模式 4: "存了没用"（Stored but not used）
| 实例 | 详情 |
|------|------|
| 反思结果持久化 | 存入 VikingStorage metadata，需确认 ReflectionLog.tsx 是否读取展示 |
### 模式 5: "双系统不同步"（Dual systems diverge）
| 实例 | 状态 |
|------|------|
| 记忆双存储路径 | ✅ 已修复 — 统一到 VikingStorage (SqliteStorage) |
---
## 七、跨部门专家头脑风暴
### 议题 1: Whiteboard Hand Export 伪造数据（N1）
**产品视角**: 用户触发"导出"期望真实图片。伪造 data_url 会导致用户困惑和信任损失。建议 UI 标注"导出功能开发中"。
**工程视角**: WhiteboardHand 是纯状态管理器（记录 draw/undo 操作），缺少 Canvas 渲染引擎。修复需集成前端 Canvas 渲染 + toDataURL 导出，或 Rust 端渲染库（如 resvg）。
**安全视角**: 无安全风险（纯本地操作）。
**架构视角**: Whiteboard 的设计是"操作记录器"而非"渲染器"。如果要实现真实导出，需要在 Rust 端或前端添加渲染层。
**决策**: **短期标注 + 长期实现** — UI 标注"导出功能开发中"，长期在前端实现 Canvas 渲染 + 导出。
### 议题 2: Director + A2A 孤立代码（N2+N3，~1597 行）
**产品视角**: 多 Agent 协作是未来功能，当前无用户需求。但代码质量高、测试覆盖好，删除可惜。
**工程视角**: Director 有 8 个单元测试，A2A 有 5 个单元测试。代码逻辑完整。但导出为 pub API 会增加编译时间和二进制大小。
**架构视角**: Team/Swarm UI 已删除，Director 成为死代码。建议用条件编译控制，而非删除。
**决策**: **条件编译** — 添加 `#[cfg(feature = "multi-agent")]` 到 `lib.rs` 导出。默认不编译，需要时通过 Cargo feature 启用。
### 议题 3: compactor_compact_llm 冗余命令（N5）
**产品视角**: 用户不需要手动触发 LLM 压缩，自动压缩（runtime 层）已足够。
**工程视角**: 两条 LLM 压缩路径（runtime 自动 + Tauri 手动）增加维护负担。runtime 的 `maybe_compact_with_config()` 已支持 LLM + 回退。
**决策**: **删除冗余命令** — 从 `lib.rs` 移除 `compactor_compact_llm` 注册，统一使用 runtime 自动路径。
### 议题 4: MCP 协议框架（N6，~588 行）
**产品视角**: MCP 是 AI Agent 互操作的标准协议，长期有战略价值。保留框架为未来集成做准备。
**工程视角**: 代码是干净的 trait + transport 实现，编译开销小。
**决策**: **保留** — 作为预留功能框架，不影响当前使用。
### 议题 5: scheduled_task 调度循环（N7）
**产品视角**: 定时任务对 Hands 自动化很重要。当前只能创建触发器但不能自动执行。
**工程视角**: 需要实现后台调度循环（tokio interval + trigger evaluation）。`kernel_commands.rs` 已有创建/列出逻辑，只需添加执行循环。
**决策**: **保留命令 + 标注为计划中** — 当前触发器系统完整，调度循环是下一步。
---
## 八、功能完成度矩阵（修正版）
### 8.1 架构层
| 功能 | 文档声称 | 本审计结果 | 差距 |
|------|----------|-----------|------|
| **通信层** | L4 (85%) | **L4 (85%)** | 无 |
| **状态管理** | L4 (85%) | **L4 (80%)** | gatewayStore 仍存在（兼容层） |
| **安全认证** | L4 (80%) | **L4 (80%)** | 无 |
### 8.2 核心功能层
| 功能 | 文档声称 | 本审计结果 | 差距 |
|------|----------|-----------|------|
| **聊天界面** | L4 (85%) | **L4 (85%)** | 无 |
| **Agent 分身** | L4 (90%) | **L4 (85%)** | updateClone 抛异常 |
| **Hands 系统** | L4 (70%) | **L3 (55%)** | 3/9 Hands 模拟实现（含 Whiteboard Export 新发现） |
### 8.3 智能层
| 功能 | 文档声称 | 本审计结果 | 差距 |
|------|----------|-----------|------|
| **Agent 记忆** | L4 (90%) | **L4 (85%)** | SqliteStorage 搜索完整（TF-IDF + Embedding） |
| **身份演化** | L2 (70%) | **L2 (70%)** | 回滚 UI 已实现 |
| **反思引擎** | L2 (65%) | **L2 (65%)** | LLM 路径存在但需 use_llm=true |
| **心跳引擎** | L2 (70%) | **L2 (60%)** | 默认禁用，持久化已修复 |
| **自主授权** | L2 (75%) | **L2 (70%)** | 后端守卫已实现 |
| **上下文压缩** | L2 (75%) | **L2 (70%)** | LLM + 记忆刷出已集成 |
### 8.4 扩展层
| 功能 | 文档声称 | 本审计结果 | 差距 |
|------|----------|-----------|------|
| **技能系统** | L3 (80%) | **L3 (75%)** | PromptOnly 通过 LlmCompleter 调用 LLM ✅ |
| **智能路由** | L1 (15%) | **L2 (60%)** | RuntimeLlmIntentDriver 已实现 ✅ |
| **Pipeline DSL** | L2 (75%) | **L2 (75%)** | 并行执行、YAML 模板均正常 |
| **OpenViking** | L3 (70%) | **L3 (65%)** | SqliteStorage 搜索质量好 |
| **Browser 自动化** | L3 (80%) | **L3 (80%)** | Fantoccini 集成完整 |
| **Channels** | — | **L0 (10%)** | 仅 ConsoleChannel |
---
## 九、优先级修复矩阵
| 优先级 | ID | 问题 | 工作量 | 建议 |
|--------|-----|------|--------|------|
| **P1** | N1 | WhiteboardHand Export 伪造 data_url | 2h | UI 标注"开发中" |
| **P2** | N2+N3 | Director + A2A 孤立（1597 行） | 1d | 条件编译 `#[cfg(feature)]` |
| **P2** | N5 | compactor_compact_llm 冗余 | 1h | 删除冗余命令注册 |
| **P2** | M3 | hand_approve hand_name 未参与业务逻辑 | 2h | 实现 hand_name + run_id 联合查找 |
| **P3** | N6 | MCP 协议无消费者 | — | 保留为框架预留 |
| **P3** | N7 | scheduled_task 调度循环 | 2-3d | 后续迭代实现 |
| **P3** | N8 | hand_approve hand_name 日志-only | 1h | 随 M3 一起修复 |
| **P3** | N4 | viking_adapter 文本匹配 | — | 已降级为 LOW，不影响生产 |
---
## 十、审计命令速查
```bash
# Dead code 扫描（28 处已知）
rg '#\[allow\(dead_code\)\]' crates/ desktop/src-tauri/ -B 1 -A 3 --type rust
# 模拟代码扫描（3 个已知）
rg 'simulated|In real implementation' crates/ desktop/src-tauri/ --type rust -n -i
# Tauri 命令注册 vs 前端调用 交叉验证
rg "generate_handler\!\[" desktop/src-tauri/src/lib.rs -A 200 | grep "::" | sort -u > /tmp/registered.txt
rg "invoke\(['\"]" desktop/src/ -o --type ts | sed "s/.*['\"]//;s/['\"].*//" | sort -u > /tmp/called.txt
comm -23 /tmp/registered.txt /tmp/called.txt # 注册但未调用
comm -13 /tmp/registered.txt /tmp/called.txt # 调用但未注册
# 孤立模块行数统计
wc -l crates/zclaw-kernel/src/director.rs crates/zclaw-protocols/src/a2a.rs crates/zclaw-protocols/src/mcp.rs crates/zclaw-protocols/src/mcp_transport.rs
# SqliteStorage 搜索路径确认
rg "VikingStorage::find" desktop/src-tauri/src/ --type rust -n
```
---
## 十一、结论
ZCLAW 的核心架构（通信、状态管理、安全认证、聊天、Agent 管理）**坚实可靠**。DEEP_AUDIT 的 27 项修复基本到位（93% 完全确认），显著提升了系统真实可用率。
**主要问题集中在**：
1. **WhiteboardHand Export** 是新发现的模拟实现（CRITICAL）
2. **~2485 行孤立代码**（Director + A2A + MCP + channels）需要架构决策
3. **hand_approve** 的 `hand_name` 参数仅用于日志（LOW）
4. **compactor_compact_llm** 是冗余的 Tauri 命令（MEDIUM）
**系统真实可用率**: ~78%（核心功能 ~92%，扩展层 ~65%）
**建议优先级**: P1 标注 WhiteboardHand → P2 条件编译孤立代码 + 删除冗余命令 → P3 后续迭代
---
**审计人**: Claude AI Agent (独立审计)
**审计日期**: 2026-03-27
**下次审计建议**: 3 个月后或重大版本发布前

364
docs/features/COMPREHENSIVE_AUDIT_V6.md
View File

@@ -1,364 +0,0 @@
# ZCLAW SaaS + Tauri 系统性功能审计报告 v6
> **ARCHIVED — 此报告已过时**
>
> 本报告是 2026-03-27 审计迭代的 v6 版本。最终结论已合并到 DEEP_AUDIT_REPORT.md。
>
> **请参考最新文档** → [README.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 2FA
- `account/` — 用户 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 时，调用：
```rust
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 前，先完成以下工作：
1. 修复 P0-1（Pipeline skill/hand stage）
2. 解决 P0-2（GrowthIntegration vs intelligence_hooks 决策）
3. 制定 SaaS 核心能力实现路线图（至少覆盖 Agent + Skill + Hand）
4. 为 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 系统 |

518
docs/features/COMPREHENSIVE_AUDIT_V7.md
View File

@@ -1,518 +0,0 @@
# ZCLAW SaaS 功能审计报告 v7
> **ARCHIVED — 此报告已过时**
>
> 本报告是 2026-03-28 审计迭代的 v7 版本。最终结论已合并到 DEEP_AUDIT_REPORT.md。
>
> **请参考最新文档** → [README.md](./README.md)
> **审计日期**: 2026-03-28 (原文标注有误)
> **审计范围**: SaaS worktree（`.claude/worktrees/saas-backend/`）— Rust 后端 + Admin UI + 桌面端集成
> **审计方法**: 五步审计流程（文档对齐 → 数据流追踪 → Dead Code → 接口检查 → E2E 验证）+ 10 项通用清单 + 5 种差距模式 + 跨部门专家论证
> **前次审计**: v6（Tauri 端 78%，SaaS 端 18%）
---
## 一、执行摘要
| 指标 | 数值 |
|------|------|
| **SaaS 后端 API 端点** | 43 个（文档声明 44 个） |
| **文档-代码对齐率** | 97.7%（43/44，缺 `/api/health`） |
| **OpenAPI 文档覆盖** | 37/43（86%），6 个端点未注解 |
| **Admin UI 页面** | 13 个（含 login） |
| **Admin API 方法** | 30 个，全覆盖 |
| **桌面端 SaaS 方法** | 20 个，全覆盖 |
| **10 项审计清单通过率** | auth 90% / account 80% / model_config 100% / relay 90% / migration 60% |
| **五种差距模式发现** | 16 个问题 |
| **Dead Code** | 0 个 `#[allow(dead_code)]`/TODO/FIXME + 3 个配置字段 + 3 个遗留函数 |
| **安全漏洞** | 1 个 CRITICAL + 2 个 HIGH + 1 个 LOW |
| **审计日志缺失** | migration 模块全部缺失（5 个变更端点） |
| **测试总数** | 86 个单元测试（10 个模块有测试，9 个文件零测试） |
| **整体 SaaS 完成度** | **~88%**（V6 审计评估 18% 严重低估，修正为 88%）
### 与 V6 审计关键差异
V6 报告评估 SaaS 完成度为 18%，这是**基于错误假设**（将 Tauri 端 AI 能力缺失计入 SaaS 差距）。本次审计确认 SaaS 的设计定位（系统管理：账号/权限/relay），在定位范围内完成度为 **~88%**。
---
## 二、功能清单与真实完成度
### 2.1 SaaS 功能模块总览
| # | 功能模块 | 设计意图 | 文档声称 | 真实完成度 | 差距说明 |
|---|---------|---------|---------|-----------|---------|
| 1 | 用户认证 | 多模式登录、JWT 生命周期、TOTP 2FA | 100% | **95%** | `/api/health` 未实现；`auth.refresh` 无审计日志 |
| 2 | 账号管理 | CRUD + 角色限制 + 设备管理 | 100% | **90%** | `AccountPublicPaginatedResponse` 死代码；dashboard 7 次串行查询 |
| 3 | API Token | 创建/撤销/权限管理 | 100% | **100%** | 无 |
| 4 | 模型配置 | Provider/Model/Key CRUD + 用量 | 95% | **90%** | `account_api_keys` 存了没用（Relay 未消费） |
| 5 | LLM Relay | OpenAI 兼容代理 + SSE + 重试 + SSRF | 95% | **90%** | `request_hash`/`priority`/`batch_window_ms` 存了没用；`chat_completions` OpenAPI 缺失 |
| 6 | 配置迁移 | diff/sync/seed + 日志 | 90% | **70%** | `sync_config` 缺权限检查（CRITICAL）；`pull` 未实现；5 个端点缺审计日志；`created` 计数器永远为 0 |
| 7 | Admin UI | 13 页面仪表盘 | 95% | **85%** | 权限过滤 Bug（admin 角色缺 4 页面）；分页未连接 API；无前端路由保护 |
| 8 | 桌面端集成 | 登录/设备/Relay/迁移向导 | 95% | **90%** | `computeConfigDiff`/`syncConfig` 定义但未调用；调用路径不一致 |
### 2.2 未实现功能（设计文档提及但代码中不存在）
| 功能 | 文档状态 | 代码状态 | 说明 |
|------|---------|---------|------|
| `/api/health` 健康检查 | 文档声明 | **未实现** | `main.rs` 无此路由 |
| `pull` 配置同步方向 | types.rs 注释 | **未实现** | service 只处理 push/merge |
| 订阅/计费系统 | roadmap 提及 | **未实现** | 无代码 |
| 多租户隔离 | 无 | **未实现** | 无代码 |
| 配额执行 | 无 | **未实现** | `max_queue_size`/`max_concurrent` 定义但未执行 |
---
## 三、API 端点覆盖率
### 3.1 端点清单（文档 vs 代码）
| 分类 | 端点 | 文档 | 代码 | OpenAPI | 测试 |
|------|------|------|------|---------|------|
| **公开** | `POST /api/v1/auth/register` | ✅ | ✅ | ✅ | ✅ |
| | `POST /api/v1/auth/login` | ✅ | ✅ | ✅ | ✅ |
| | `GET /api/health` | ✅ | **❌** | ❌ | ❌ |
| **认证** | `GET /api/v1/auth/me` | ✅ | ✅ | ✅ | — |
| | `POST /api/v1/auth/refresh` | ✅ | ✅ | ✅ | — |
| | `PUT /api/v1/auth/password` | ✅ | ✅ | ✅ | — |
| **TOTP** | `POST /api/v1/auth/totp/setup` | ✅ | ✅ | ✅ | — |
| | `POST /api/v1/auth/totp/verify` | ✅ | ✅ | ✅ | — |
| | `POST /api/v1/auth/totp/disable` | ✅ | ✅ | ✅ | — |
| **账号** | `GET /api/v1/accounts` | ✅ | ✅ | ✅ | — |
| | `GET /api/v1/accounts/{id}` | ✅ | ✅ | ✅ | — |
| | `PUT /api/v1/accounts/{id}` | ✅ | ✅ | ✅ | — |
| | `PATCH /api/v1/accounts/{id}/status` | ✅ | ✅ | ✅ | — |
| | `GET /api/v1/stats/dashboard` | ✅ | ✅ | ✅ | — |
| **Token** | `GET /api/v1/tokens` | ✅ | ✅ | ✅ | — |
| | `POST /api/v1/tokens` | ✅ | ✅ | ✅ | — |
| | `DELETE /api/v1/tokens/{id}` | ✅ | ✅ | ✅ | — |
| **设备** | `POST /api/v1/devices/register` | ✅ | ✅ | ✅ | — |
| | `POST /api/v1/devices/heartbeat` | ✅ | ✅ | ✅ | — |
| | `GET /api/v1/devices` | ✅ | ✅ | ✅ | — |
| **Provider** | `GET/POST /api/v1/providers` | ✅ | ✅ | ✅ | — |
| | `GET/PUT/DELETE /api/v1/providers/{id}` | ✅ | ✅ | ✅ | — |
| | `GET /api/v1/providers/{id}/models` | ✅ | ✅ | ✅ | — |
| **Model** | `GET/POST /api/v1/models` | ✅ | ✅ | ✅ | — |
| | `GET/PUT/DELETE /api/v1/models/{id}` | ✅ | ✅ | ✅ | — |
| **Key** | `GET/POST/DELETE /api/v1/keys` | ✅ | ✅ | ✅ | — |
| | `POST /api/v1/keys/{id}/rotate` | ✅ | ✅ | ✅ | — |
| **Relay** | `GET /api/v1/relay/models` | ✅ | ✅ | ✅ | — |
| | `POST /api/v1/relay/chat/completions` | ✅ | ✅ | **❌** | — |
| | `GET /api/v1/relay/tasks` | ✅ | ✅ | ✅ | — |
| | `GET /api/v1/relay/tasks/{id}` | ✅ | ✅ | ✅ | — |
| | `POST /api/v1/relay/tasks/{id}/retry` | ✅ | ✅ | ✅ | — |
| **Config** | `GET/POST /api/v1/config/items` | ✅ | ✅ | ✅ | — |
| | `GET/PUT/DELETE /api/v1/config/items/{id}` | ✅ | ✅ | ✅ | — |
| | `GET /api/v1/config/analysis` | ✅ | ✅ | ✅ | — |
| | `POST /api/v1/config/seed` | ✅ | ✅ | ✅ | — |
| | `POST /api/v1/config/sync` | ✅ | ✅ | ✅ | — |
| | `POST /api/v1/config/diff` | ✅ | ✅ | ✅ | — |
| | `GET /api/v1/config/sync-logs` | ✅ | ✅ | ✅ | — |
| **审计** | `GET /api/v1/logs/operations` | ✅ | ✅ | ✅ | — |
| | `GET /api/v1/usage` | ✅ | ✅ | ✅ | — |
**统计**: 43/44 端点已实现（97.7%），37/43 有 OpenAPI 文档（86%）
**缺失 OpenAPI 文档的 6 个端点**:
1. `POST /api/v1/auth/totp/setup` — TOTP 设置
2. `POST /api/v1/auth/totp/verify` — TOTP 验证
3. `POST /api/v1/auth/totp/disable` — TOTP 禁用
4. `GET /api/v1/logs/operations` — 操作日志
5. `GET /api/v1/stats/dashboard` — 仪表盘统计
6. `POST /api/v1/relay/chat/completions` — 聊天中转
---
## 四、审计矩阵
### 4.1 十项通用审计清单
| # | 检查项 | auth | account | model_config | relay | migration |
|---|--------|------|---------|-------------|-------|-----------|
| 1 | 代码存在性 | ✅ | ✅ | ✅ | ✅ | ✅ |
| 2 | 调用链连通 | ✅ | ✅ | ✅ | ✅ | ✅ |
| 3 | 配置传递 | ✅ | ✅ | ✅ | **⚠️** 3 字段未使用 | ✅ |
| 4 | 降级策略 | ✅ JWT 过期处理 | — | — | ✅ 上游超时重试 | — |
| 5 | 错误处理 | ✅ | ✅ | ✅ | ✅ | ✅ |
| 6 | 权限执行 | ✅ | ✅ | ✅ | ✅ | **❌** sync_config |
| 7 | 日志覆盖 | **⚠️** refresh 缺失 | ✅ | ✅ | ✅ | **❌** 全部缺失 |
| 8 | 输入验证 | ✅ | ✅ | ✅ | ✅ | **⚠️** sync action |
| 9 | 测试覆盖 | ✅ 3 tests | ✅ 2 tests | ✅ 1 test | ✅ 30+ tests | ✅ 2 tests |
| 10 | 文档一致性 | **⚠️** /health 缺失 | ✅ | ✅ | **⚠️** OpenAPI 缺失 | ✅ |
### 4.2 E2E 数据流验证
| # | 流程 | 结果 | 关键发现 |
|---|------|------|---------|
| 1 | 用户注册 → JWT → 首次请求 | **PASS** | 全链路正常，Argon2 哈希正确 |
| 2 | TOTP 登录 → 受保护 API | **PASS** | verify_totp_code → get_role_permissions → create_token 正确 |
| 3 | Relay SSE 流式 + 用量记录 | **PASS** | SSRF 防护 + DNS Rebinding + SSE 用量提取正确 |
| 4 | 配置同步 push/merge | **WARNING** | push 路径正常但缺权限检查；`created` 计数永远为 0 |
| 5 | 设备注册 + 心跳 | **PASS** | UPSERT + heartbeat UPDATE 正确 |
---
## 五、差距分析（5 种模式）
### 5.1 Pattern 1: "写了没接"（3 项）
| # | 发现 | 位置 | 严重性 |
|---|------|------|--------|
| G1 | `hash_request()` 计算 SHA-256 哈希存入 `request_hash` 但从未被查询 | `relay/service.rs:273` | LOW |
| G2 | `pull` 同步方向在类型注释中声明但 service 未实现 | `migration/service.rs:306` | LOW |
| G3 | `cleanup_stale_entries()` 声明为 pub(crate) 但从未被调用（仅测试使用） | `middleware.rs:54` | LOW |
### 5.2 Pattern 2: "接了没传"（2 项）
| # | 发现 | 位置 | 严重性 |
|---|------|------|--------|
| G4 | `sync_config` 的 `created` 变量初始化为 0 但从未递增 | `migration/service.rs:263` | MEDIUM |
| G5 | `chat_completions` 的 `_headers` 参数提取但未使用 | `relay/handlers.rs:25` | LOW |
### 5.3 Pattern 3: "传了没存"（0 项）
无发现。所有 SQL 变更正确执行。
### 5.4 Pattern 4: "存了没用"（5 项）
| # | 发现 | 位置 | 严重性 |
|---|------|------|--------|
| G6 | `request_hash` 列存储但从未用于去重 | `relay_tasks.request_hash` | LOW |
| G7 | `priority` 列永远为 0，未用于排序 | `relay_tasks.priority` | LOW |
| G8 | `max_queue_size` 配置字段定义但未执行 | `config.rs:49` | LOW |
| G9 | `max_concurrent_per_provider` 配置字段定义但未执行 | `config.rs:51` | LOW |
| G10 | `batch_window_ms` 配置字段定义但未使用 | `config.rs:53` | LOW |
| **G11** | **`account_api_keys` 表完整 CRUD 但 Relay 只使用 provider 级 API Key** | `model_config/service.rs:285` vs `relay/handlers.rs:56` | **HIGH** |
### 5.5 Pattern 5: "双系统不同步"（3 项）
| # | 发现 | 位置 | 严重性 |
|---|------|------|--------|
| G12 | Config 模块写 `config_sync_log` 但不写统一 `operation_logs`，破坏审计追踪 | `migration/handlers.rs` | **MEDIUM** |
| G13 | Provider 级 API Key + 用户级 API Key 双系统，Relay 只消费前者 | `relay/handlers.rs:56` | **MEDIUM** |
| G14 | Admin UI 导航权限过滤逻辑与后端 RBAC 权限系统不同步 | `layout.tsx:107` vs `db.rs` seed roles | **HIGH** |
### 5.6 Pattern 1 补充: "写了没接"（Admin UI + Desktop）
| # | 发现 | 位置 | 严重性 |
|---|------|------|--------|
| G15 | saas-client `computeConfigDiff()`/`syncConfig()` 定义但桌面端从未调用 | `saas-client.ts` | LOW |
| G16 | Admin 5 个列表页面分页组件存在但未连接 API 分页参数 | `accounts/providers/models/api-keys/relay page.tsx` | MEDIUM |
---
## 六、安全问题
| # | 问题 | 严重性 | 位置 | 说明 |
|---|------|--------|------|------|
| **S1** | `sync_config` 无权限检查 | **CRITICAL** | `migration/handlers.rs:83-89` | 任何认证用户可推送配置值，应要求 `config:write` |
| **S2** | Config 变更端点无审计日志 | **HIGH** | `migration/handlers.rs` | create/update/delete/seed/sync 5 个端点未调用 `log_operation()` |
| **S3** | Admin UI 权限过滤逻辑错误 | **HIGH** | `layout.tsx:107` | 普通 admin 角色无法看到 4 个管理页面；隐藏导航但未保护路由 |
| S4 | 邮箱验证仅检查 `@` 和 `.` | LOW | `auth/handlers.rs:28` | 可接受简单验证，PostgreSQL 有 email 类型约束 |
---
## 七、跨部门专家论证
### 发现 S1: `sync_config` 缺权限检查 (CRITICAL)
| 专家视角 | 分析 |
|---------|------|
| **产品经理** | 影响中等。当前仅桌面端调用此端点，但公开后任何用户可修改系统配置。优先级 P0 |
| **架构师** | 实现疏忽。其他所有 mutation 端点都有 `check_permission`，唯独 `sync_config` 遗漏。修复方案简单：添加 `check_permission(ctx, "config:write")` |
| **安全工程师** | 权限边界被突破。一个普通用户（`user` 角色，权限仅 `["model:read","relay:use","config:read"]`）可以覆盖任何配置项。风险：配置投毒 |
| **UX 设计师** | 无 UI 影响。Admin 和桌面端的配置同步 UI 都不会因此出现问题，因为其他端点都有权限检查 |
**结论**: 真实漏洞，P0 修复。一行代码即可修复。
### 发现 G11: `account_api_keys` 未被 Relay 消费 (HIGH)
| 专家视角 | 分析 |
|---------|------|
| **产品经理** | 影响高。用户在桌面端创建的 per-provider API Key 永远不会被使用，Relay 始终使用管理员配置的 provider 级 Key。这导致多用户共享同一个 API Key，无法追踪个人用量到具体 Key |
| **架构师** | 设计不完整。`account_api_keys` 的 CRUD 已实现（创建/撤销/轮换），Admin UI 有专门页面，但消费端（Relay）从未接入。需要决策：(A) Relay 优先使用用户级 Key；(B) 移除 `account_api_keys` 功能 |
| **安全工程师** | 用户级 Key 隔离未生效。当前所有用户的 Relay 请求共享同一个 provider Key，无法在 Key 级别做权限隔离或用量追踪 |
| **UX 设计师** | Admin UI 的 "API Keys" 页面展示用户创建的 Key 和轮换状态，但实际从未使用。用户可能困惑于 "为什么创建了 Key 但用量全部归到 provider" |
**结论**: 真实设计缺陷，需要架构决策。建议方案 A（Relay 优先用户级 Key，回退 provider 级）。
### 发现 G12: Config 模块审计日志缺失 (MEDIUM)
| 专家视角 | 分析 |
|---------|------|
| **产品经理** | 影响低。Config 变更频率低，通常由管理员操作。但合规审计需要完整日志 |
| **架构师** | 不一致。auth/account/model_config 模块都有 `log_operation()`，唯独 migration 模块缺失。`sync_config` 写了 `config_sync_log` 但这是专用日志，不在统一的 `operation_logs` 表中 |
| **安全工程师** | 审计盲区。如果有人在凌晨 3 点覆盖了系统配置，`operation_logs` 表中不会有记录 |
| **UX 设计师** | 无影响。Admin 操作日志页面不会显示 Config 变更记录 |
**结论**: 真实遗漏。修复简单：在 5 个 mutation handler 中添加 `log_operation()` 调用。
### 发现 G4: `sync_config` `created` 计数永远为 0 (MEDIUM)
| 专家视角 | 分析 |
|---------|------|
| **产品经理** | 影响低。桌面端迁移向导显示 "updated: N, created: 0, skipped: M"。`created` 永远为 0 可能让用户困惑 |
| **架构师** | 实现疏忽。push 路径只处理已存在的 config_items（UPDATE），merge 路径也只处理已存在的。真正的新增场景（客户端发送 SaaS 不存在的 key）未被处理 |
| **安全工程师** | 无安全影响 |
| **UX 设计师** | 迁移向导的统计信息不准确。`created` 应该在 INSERT 新 config_item 时递增 |
**结论**: 真实 Bug。`sync_config` 应在 INSERT 时递增 `created` 计数器。
### 发现 S3: `/api/health` 端点未实现 (LOW)
| 专家视角 | 分析 |
|---------|------|
| **产品经理** | 影响低。文档声明了但桌面端 `healthCheck()` 调用时如果返回 404 会判断为不健康。实际影响：桌面端可能误判服务器不可达 |
| **架构师** | 遗漏。实现简单，返回 `{ status: "ok", version: "x.y.z" }` 即可 |
| **安全工程师** | 无安全影响（公开端点） |
| **UX 设计师** | 桌面端 SaaSStatus 组件依赖健康检查。缺失会导致状态显示异常 |
**结论**: 真实遗漏。简单修复。
### 发现 S3: Admin UI 权限过滤逻辑错误 (HIGH)
| 专家视角 | 分析 |
|---------|------|
| **产品经理** | 影响高。多管理员场景下（组织有多个管理员），普通 `admin` 角色用户登录后看不到账号管理、服务商、模型管理、中转任务 4 个核心页面。这严重限制了管理员协作能力。优先级 P1 |
| **架构师** | 实现疏忽。过滤条件 `account.role === 'super_admin' \|\| item.permission === 'admin:full'` 未检查用户是否实际拥有 `item.permission`。正确做法应检查 `account.permissions.includes(item.permission)`。此外，仅隐藏导航项未做前端路由守卫，用户直接输入 URL 可绕过。修复需 2 处：(A) 修正过滤逻辑；(B) 添加路由级权限检查 |
| **安全工程师** | 前端权限过滤失效。虽然后端 API 有权限检查（`check_permission`），但前端暴露了所有路由 URL，攻击者可枚举管理端点。更重要的是，**前端路由未保护**意味着用户可能看到一个有权限错误但功能正常的页面，体验混乱 |
| **UX 设计师** | 用户体验混乱。管理员登录后看到侧边栏只有 6/12 项，可能认为自己权限不足。如果直接输入 URL 访问被隐藏的页面，后端返回 403 错误但页面不会给出清晰提示 |
**结论**: 真实 Bug，P1 修复。修正过滤逻辑 + 添加路由守卫。
### 发现 G16: Admin 分页组件未连接 API (MEDIUM)
| 专家视角 | 分析 |
|---------|------|
| **产品经理** | 影响中等。当前数据量小（早期用户）时无感知。但一旦账号/模型/密钥数量超过默认 page_size，用户只能看到第一批数据，无法翻页查看更多。优先级 P2 |
| **架构师** | 分页组件存在于 5 个页面但全部未连接 API 调用。`PageNavigation` 组件维护 `currentPage`/`pageSize` 状态，但 `api.xxx.list()` 调用未传递这些参数。修复方案：将分页状态传递到 API 调用，监听页码变化触发重新加载 |
| **安全工程师** | 无安全影响 |
| **UX 设计师** | 分页按钮显示但点击无效，或者始终显示"第 1 页"。用户可能认为数据只有这么多，不知道还有更多未加载 |
**结论**: 真实 Bug，P2 修复。5 个页面统一处理。
---
## 八、Admin UI 审计
### 8.1 页面-API 对齐
| 页面 | API 方法调用 | 状态 |
|------|------------|------|
| Login | `api.auth.login()` | ✅ |
| Dashboard | `api.stats.dashboard()` | ✅ |
| Accounts | `api.accounts.list/get/update/updateStatus()` | ✅ |
| Providers | `api.providers.list/get/create/update/delete()` | ✅ |
| Models | `api.models.list/get/create/update/delete()` | ✅ |
| API Keys | `api.tokens.list/create/revoke()` | ✅ |
| Usage | `api.usage.get()` | ✅ |
| Relay | `api.relay.list/get/retry()` | ✅ |
| Config | `api.config.list/update()` | ✅ |
| Logs | `api.logs.list()` | ✅ |
| Devices | `api.devices.list/register/heartbeat()` | ✅ |
| Profile | `api.auth.changePassword()` | ✅ |
| Security | `api.auth.totpSetup/verify/disable()` | ✅ |
**对齐率**: 100%。Admin UI 的 30 个 API 方法全部有对应后端端点。
### 8.2 Admin API 方法 vs 后端端点交叉验证
所有 30 个 Admin API 方法的路径均与后端路由匹配，无多余或缺失。
### 8.3 Admin UI 权限过滤 Bug（HIGH）
**位置**: `admin/src/app/(dashboard)/layout.tsx:103-108`
**问题**: 侧边栏导航过滤逻辑存在逻辑错误：
```typescript
// 当前代码（有 Bug）
.filter((item) => {
if (!item.permission) return true
if (!account) return false
return account.role === 'super_admin' || item.permission === 'admin:full'
})
```
**影响**: `navItems` 中 `account:admin`、`model:admin`、`relay:admin` 三个权限标记对普通 `admin` 角色用户**完全无效**。逻辑等价于：
- `permission: null` → 所有角色可见（正确）
- `permission: 'admin:full'` → 所有角色可见（Bug，应仅 super_admin 可见）
- `permission: 'account:admin'` → **仅** super_admin 可见（Bug，admin 也应有此权限）
- `permission: 'model:admin'` → **仅** super_admin 可见（Bug）
- `permission: 'relay:admin'` → **仅** super_admin 可见（Bug）
**结果**: 普通 `admin` 角色用户只能看到仪表盘、API 密钥、用量统计、个人设置、安全设置、设备管理（6/12），**无法看到**账号管理、服务商、模型管理、中转任务（4/12）。
**缺失**: 仅隐藏导航项，**未做前端路由保护**。用户直接输入 `/accounts`、`/providers` 等路径仍可访问页面（后端权限检查正常，但前端体验不一致）。
**修复方案**: 改用权限检查函数验证用户是否拥有对应权限：
```typescript
.filter((item) => {
if (!item.permission) return true
if (!account) return false
return account.permissions?.includes(item.permission) ?? false
})
```
### 8.4 Admin UI 分页功能不可用（MEDIUM）
**影响页面**: accounts、providers、models、api-keys、relay（5 个列表页面）
**发现**: 5 个页面均包含分页组件（PageNavigation），后端 API 支持分页参数（`page`/`page_size`），但**前端调用 API 时未传递分页参数**，始终获取第一页全部数据。
**根因**: API 调用使用 `api.xxx.list()` 而非 `api.xxx.list({ page, pageSize })`，分页状态（`currentPage`/`pageSize`）存在于组件 state 中但未与 API 调用关联。
### 8.5 Admin UI 错误处理一致性
**发现**: 所有页面均有 `try/catch` 处理 API 错误，但存在不一致：
- 部分页面使用 `setError(err.message)` 显示具体错误（accounts、providers）
- 部分页面使用 `console.error` 但无用户可见反馈（models:113、api-keys:138）
- 无统一的全局错误 Toast/Banner 组件
**影响**: LOW。用户可能在操作失败时看不到任何反馈。
---
## 九、桌面端 SaaS 集成审计
### 9.1 saas-client.ts 端点覆盖
| 方法 | 后端端点 | 匹配 |
|------|---------|------|
| `login()` | `POST /api/v1/auth/login` | ✅ |
| `register()` | `POST /api/v1/auth/register` | ✅ |
| `me()` | `GET /api/v1/auth/me` | ✅ |
| `refreshToken()` | `POST /api/v1/auth/refresh` | ✅ |
| `changePassword()` | `PUT /api/v1/auth/password` | ✅ |
| `setupTotp()` | `POST /api/v1/auth/totp/setup` | ✅ |
| `verifyTotp()` | `POST /api/v1/auth/totp/verify` | ✅ |
| `disableTotp()` | `POST /api/v1/auth/totp/disable` | ✅ |
| `registerDevice()` | `POST /api/v1/devices/register` | ✅ |
| `deviceHeartbeat()` | `POST /api/v1/devices/heartbeat` | ✅ |
| `listDevices()` | `GET /api/v1/devices` | ✅ |
| `listModels()` | `GET /api/v1/relay/models` | ✅ |
| `listRelayTasks()` | `GET /api/v1/relay/tasks` | ✅ |
| `getRelayTask()` | `GET /api/v1/relay/tasks/{id}` | ✅ |
| `retryRelayTask()` | `POST /api/v1/relay/tasks/{id}/retry` | ✅ |
| `chatCompletion()` | `POST /api/v1/relay/chat/completions` | ✅ |
| `listConfig()` | `GET /api/v1/config/items` | ✅ |
| `computeConfigDiff()` | `POST /api/v1/config/diff` | ✅ |
| `syncConfig()` | `POST /api/v1/config/sync` | ✅ |
| `healthCheck()` | `GET /api/health` | **❌** 端点不存在 |
**对齐率**: 19/20（95%）。唯一不匹配是 `healthCheck()` 调用了不存在的 `/api/health`。
### 9.2 桌面端特性
- **JWT Token 自动刷新**: 80% 生命周期时主动刷新 + visibilitychange 监听
- **会话持久化**: Token 存 OS Keyring（secureStorage），URL/Account 存 localStorage
- **遗留函数清理**: `loadSaaSSession()`/`saveSaaSSession()`/`clearSaaSSession()` 3 个同步版本标记为 `@deprecated`
- **网络重试**: 指数退避 2 次重试（1s, 2s）
- **离线检测**: `isServerReachable()` 状态追踪
### 9.3 桌面端架构不一致（MEDIUM）
**发现**: saas-client.ts 中定义了 `computeConfigDiff()` 和 `syncConfig()` 两个方法，但**桌面端代码中无任何组件或 store 调用它们**。配置迁移向导（ConfigMigrationWizard）实现了自己的 diff/sync 逻辑，不经过 saas-client。
**影响**: MEDIUM。代码冗余 + 维护风险。如果 saas-client 的 API 签名与向导实现不一致，可能出现行为分歧。
### 9.4 桌面端调用路径不一致（LOW）
**发现**: 部分 SaaS 操作通过 `saasStore`（Zustand）编排，其他操作直接调用 `saasClient`。无统一规范约定何时使用哪条路径。
**影响**: LOW。不影响功能正确性，但增加了代码理解和维护成本。
---
## 十、测试覆盖评估
| 模块 | 测试数 | 覆盖内容 |
|------|--------|---------|
| error.rs | 4 | SaasError 变体、IntoResponse |
| config.rs | 4 | 配置加载、环境变量覆盖 |
| middleware.rs | 8 | 速率限制、窗口过期、admin 豁免 |
| csrf.rs | 6 | Origin 验证、路径剥离、dev 绕过 |
| crypto.rs | 10 | 加密/解密、篡改检测、错误密钥 |
| jwt | 3 | Token 创建/验证/过期 |
| password | 2 | 哈希/验证 |
| db.rs | 2 | Schema 初始化、表存在性 |
| relay/service.rs | 37 | 重试逻辑、Token 提取、SSRF 检测（**最佳覆盖**） |
| model_config/service.rs | 10 | Provider/Model/Key CRUD |
| **总计** | **86** | — |
**零测试的 9 个文件**: 5 个 handler 文件、`auth/totp.rs`、`account/service.rs`、`migration/service.rs`、`state.rs`
---
## 十一、修复建议（优先级排序）
### P0 — CRITICAL（安全漏洞）
| # | 问题 | 修复方案 | 工作量 |
|---|------|---------|--------|
| P0-1 | `sync_config` 无权限检查 | `migration/handlers.rs:83` 添加 `check_permission(ctx, "config:write")` | **1 行** |
### P1 — HIGH（功能缺陷）
| # | 问题 | 修复方案 | 工作量 |
|---|------|---------|--------|
| P1-1 | `account_api_keys` 未被 Relay 消费 | Relay handler 查找用户级 Key，回退到 provider 级 Key | 中 |
| P1-2 | Config 模块 5 个端点缺审计日志 | 添加 `log_operation()` 调用 | 小 |
| P1-3 | `sync_config` `created` 计数永远为 0 | INSERT 时递增 `created` | 小 |
| P1-4 | Admin UI 权限过滤逻辑错误 | `layout.tsx:107` 改用 `account.permissions.includes(item.permission)` | **5 行** |
| P1-5 | Admin UI 缺前端路由保护 | 添加 `AuthGuard` 组件检查页面级权限 | 中 |
### P2 — MEDIUM（代码质量）
| # | 问题 | 修复方案 | 工作量 |
|---|------|---------|--------|
| P2-1 | `/api/health` 端点未实现 | 添加健康检查路由 | 小 |
| P2-2 | `chat_completions` 缺 OpenAPI 文档 | `openapi.rs` 添加 `#[utoipa::path]` | 小 |
| P2-3 | 6 个端点缺 OpenAPI 注解 | `openapi.rs` 补充 `#[utoipa::path]` | 中 |
| P2-4 | `AccountPublicPaginatedResponse` 仅 OpenAPI 用 | 保留或统一到 PaginatedResponse | 小 |
| P2-5 | 3 个 Relay 配置字段未使用 | 移除或实现 `max_queue_size`/`max_concurrent`/`batch_window_ms` | 中 |
| P2-6 | `request_hash`/`priority` 列存了没用 | 移除或实现去重/优先级排序 | 中 |
| P2-7 | `pull` 同步方向未实现 | 实现或从类型注释中移除 | 中 |
| P2-8 | 3 个遗留同步函数未清理 | 移除 `loadSaaSSession`/`saveSaaSSession`/`clearSaaSSession` | 小 |
| P2-9 | dashboard_stats 7 次串行查询 | 合并为单次 SQL 查询 | 小 |
| P2-10 | Admin 5 个列表页面分页未连接 API | 将分页状态传递到 API 调用 | 小 |
| P2-11 | `computeConfigDiff`/`syncConfig` saas-client 定义但未使用 | 移除或统一迁移向导调用路径 | 小 |
| P2-12 | Admin UI catch 块无用户可见错误反馈 | 添加全局 Toast 组件 | 小 |
### P3 — LOW（测试补充）
| # | 问题 | 修复方案 | 工作量 |
|---|------|---------|--------|
| P3-1 | auth/account/model_config/migration 缺单元测试 | 添加 handler/service 层测试 | 大 |
---
## 十二、审计结论
### SaaS 后端健康度: **良好（~88%）**
**优势**:
- 功能-代码对齐率 97.7%（43/44 端点）
- 安全基础设施成熟（Argon2 + TOTP + RBAC + AES-256-GCM + CSRF + SSRF 防护）
- Admin UI 覆盖所有管理功能（13 页面）
- 桌面端集成完整（登录/设备/Relay/配置迁移）
- 测试覆盖 86 个单元测试
- 代码质量高：零 TODO/FIXME，错误处理一致
**待改进**:
- 1 个 CRITICAL 安全漏洞（`sync_config` 权限检查缺失）
- 2 个 HIGH 缺陷（用户级 API Key 未被 Relay 消费；Admin 权限过滤逻辑错误）
- 1 个 MEDIUM 功能 Bug（`created` 计数永远为 0）
- Config 模块审计日志完全缺失
- Admin UI 分页未连接 API（5 个页面）
- Admin UI 无前端路由保护
- 5 个配置字段定义但未执行
### 修正 V6 评估
V6 审计将 SaaS 完成度评估为 18%，原因是将 Tauri 端 AI 能力（Agent/Skill/Hand/Pipeline/Memory/Intelligence/Browser/OpenViking）的缺失计入 SaaS 差距。**这是错误的**——SaaS 的设计定位是系统管理（账号/权限/relay），不负责 AI 能力。在正确定位下，SaaS 完成度为 **~88%**（V7 初评 90% 下调 2%，因发现 Admin UI 权限 Bug 和分页未连接），修复 P0-P2 项即可达到 95%+。
---
*审计完成。本报告基于 2026-03-28 代码快照（worktree-saas-backend 分支，commit bc12f68），所有发现均可通过文档中引用的文件路径和行号验证。*

339
docs/features/COMPREHENSIVE_AUDIT_V8.md
View File

@@ -1,339 +0,0 @@
# ZCLAW SaaS+Tauri 系统性功能审计报告 V8
> **审计日期**: 2026-03-29
> **审计范围**: 全量三端审计 — SaaS 后端 + Tauri 桌面端 + Admin 管理后台
> **审计方法**: 五步审计流程 + 十项通用清单 + 五种差距模式 + 安全专项
> **前次审计**: V7 (2026-03-28, 已归档)
---
## 一、执行摘要
| 指标 | 数值 |
|------|------|
| **SaaS API 端点** | 76+ (9 模块, 22+ 数据表) |
| **Tauri 命令** | 150+ (73 个 invoke 调用) |
| **Admin 页面** | 12 (含 login) |
| **文档-代码对齐率** | ~95% |
| **数据流连通率** | 60% (3/5 完整连通, 1 部分连通, 1 断裂) |
| **Dead Code** | 28+ `#[allow(dead_code)]`, 35+ 未调用 API 方法 |
| **安全漏洞** | 1 CRITICAL + 2 HIGH + 2 MEDIUM |
| **差距模式发现** | 12 个 (P0×1, P1×4, P2×4, P3×3) |
| **整体完成度** | **~82%** (核心功能可用，集成链路存在断裂) |
---
## 二、功能清单与完成度矩阵
### 2.1 架构层
| 功能 | 设计目标 | SaaS | Tauri | Admin | 完成度 | 关键差距 |
|------|---------|------|-------|-------|--------|---------|
| 通信层 | 三模式连接 (Kernel/Gateway/SaaS) | N/A | ✅ | N/A | 85% | hand_run 桩命令 |
| 状态管理 | 18 Zustand Store | N/A | N/A | N/A | 80% | 消息不持久化 |
| 安全认证 | Ed25519+JWT+TOTP | ✅ | ✅ | ✅ | 80% | 生物识别/FIDO2 未实现 |
### 2.2 核心功能
| 功能 | 设计目标 | SaaS | Tauri | Admin | 完成度 | 关键差距 |
|------|---------|------|-------|-------|--------|---------|
| 聊天界面 | 流式响应+多模型 | ✅ Relay | ✅ Stream | N/A | 92% | 超长消息卡顿 |
| Agent 分身 | CRUD+模板+切换 | ✅ Template | ✅ Agent | ✅ Template | 85% | 导入/导出未实现 |
| Hands 系统 | 9+ 自主能力 | N/A | ✅ 9 Hands | N/A | 70% | Predictor/Lead 无代码 |
### 2.3 智能层
| 功能 | 设计目标 | SaaS | Tauri | Admin | 完成度 | 关键差距 |
|------|---------|------|-------|-------|--------|---------|
| Agent 记忆 | 跨会话+语义搜索 | N/A | ✅ Viking | N/A | 90% | 大量记忆检索变慢 |
| 身份演化 | SOUL.md+自动改进 | N/A | ✅ | N/A | 70% | Tauri 模式内存存储重启丢失 |
| 反思引擎 | 自动分析+建议 | N/A | ✅ | N/A | 65% | 建议具体性待改进 |
| 心跳巡检 | 定期巡检+主动提醒 | ✅ 设备心跳 | ✅ | N/A | 70% | 持久化调度缺失 |
| 自主授权 | 三级授权+审批 | N/A | ✅ | N/A | 75% | 批量审批未实现 |
| 上下文压缩 | 智能摘要 | N/A | ✅ | N/A | 75% | LLM 增强摘要未使用 |
### 2.4 平台层
| 功能 | 设计目标 | SaaS | Tauri | Admin | 完成度 | 关键差距 |
|------|---------|------|-------|-------|--------|---------|
| 技能系统 | 69 SKILL.md | N/A | ✅ | N/A | 80% | WASM/Native 未实现 |
| 智能路由 | 语义匹配 | N/A | ❌ | N/A | 50% | SemanticSkillRouter 核心未实现 |
| Pipeline DSL | YAML 工作流 | N/A | ✅ | N/A | 90% | 无重大差距 |
| SaaS 平台 | 云端能力 | ✅ | ✅ | ✅ | 88% | SQL 注入+配置单向同步+遥测空转 |
---
## 三、五步审计结果
### 3.1 Step 1: 文档对齐
| 检查项 | 结果 |
|--------|------|
| SaaS API 路由 vs 文档 | ✅ 76+ 端点全部对齐 |
| Tauri 命令 vs 文档 | ✅ 150+ 命令已注册 |
| Admin 页面 vs 文档 | ✅ 12 页面全部存在 |
| 功能文档声称 vs 实际 | ⚠️ 部分功能声称高于实际 (智能路由 50% 声称 Phase 1 完成) |
**对齐率: ~95%**
### 3.2 Step 2: 数据流追踪
| # | 数据流 | 状态 | 断点 |
|---|--------|------|------|
| DF1 | 认证 (Desktop→SaaS) | ✅ 完整 | 无 |
| DF2 | 聊天 Relay (Desktop→SaaS→LLM) | ⚠️ 部分 | chatStore SaaS 模式走 WS 而非 HTTP relay |
| DF3 | 配置同步 (Desktop↔SaaS) | ❌ 单向 | Pull✅, Push/Diff❌ (定义但未调用) |
| DF4 | 设备管理 (Desktop→SaaS) | ✅ 完整 | 心跳不传 OS/version |
| DF5 | 遥测上报 (Desktop→SaaS) | ❌ 断裂 | recordLLMUsage/recordAuditEvent 零调用 |
**连通率: 60% (3/5 完整)**
### 3.3 Step 3: Dead Code 识别
#### Rust `#[allow(dead_code)]` — 28 处
| 分类 | 数量 | 说明 |
|------|------|------|
| Intelligence 模块 | 12 | heartbeat/reflection/identity/compactor 预留给未来 Tauri 命令 |
| Memory 模块 | 3 | persistent.rs 遗留迁移代码 |
| Runtime 驱动 | 4 | 反序列化字段未被访问 |
| Kernel/Pipeline | 4 | 预留功能 (export, intent, stage) |
| lib.rs | 2 | HealthStatus 枚举 + legacy 函数 |
| Growth | 2 | 缓存+存储预留 |
#### 未调用的 SaaS API 方法 — 35+ 个
**需要关注的桌面端方法 (应在 desktop 中使用但未使用)**:
- `healthCheck()` — 未被任何 health check 调用使用
- `listDevices()` — 设备列表未在桌面端展示
- `getRelayTask()` — 单个任务查询未使用
- `computeConfigDiff()` — ❌ 零调用，配置差异计算断裂
- `syncConfig()` — ❌ 零调用，配置推送断裂
**Admin 专用方法 (桌面端不使用是正常的)**:
- Provider/Model/Account/Role/Permission CRUD (~30 个)
- 这些方法在 admin/src/ 中通过独立的 api-client.ts 调用
#### Rust TODO/FIXME — 5 处
| 文件 | 行号 | 内容 |
|------|------|------|
| pipeline_commands.rs | 529 | `// TODO: use actual time` |
| pipeline_commands.rs | 869 | `// TODO: add pattern support` |
| kernel/src/registry.rs | 56 | `// TODO: Track this` |
| kernel/src/export/html.rs | 17 | `// TODO: Implement template-based HTML export` |
| pipeline/src/actions/orchestration.rs | 41 | `// TODO: implement graph storage` |
### 3.4 Step 4: 接口一致性
#### TS 类型差异 — 10+ 组
| 类型对 | 主要差异 |
|--------|---------|
| AccountPublic | admin: 联合类型 role/status; desktop: string |
| OperationLog vs OperationLogInfo | id 类型 string vs number; details 类型不同 |
| ConfigItem vs SaaSConfigItem | current_value 类型不同; desktop 多 created_at/updated_at |
| RelayTask vs RelayTaskInfo | status 联合类型 vs string; desktop 多 max_attempts/created_at |
| PromptTemplate vs PromptTemplateInfo | source/status 联合类型 vs string |
| Provider vs ProviderInfo | admin 有 api_key 字段; desktop 无 |
| Model vs ModelInfo | desktop 多 created_at/updated_at |
### 3.5 Step 5: 端到端验证
| 测试流程 | 结果 | 说明 |
|----------|------|------|
| 用户注册→登录→获取信息 | ✅ | 完整链路通畅 |
| 登录→设备注册→心跳 | ✅ | 降级逻辑正常 |
| 配置 Pull | ✅ | 仅拉取方向 |
| 配置 Push/Diff | ❌ | 方法未调用 |
| Relay chat→SSE | ✅ | llm-service.ts 路径完整 |
| Admin 登录→管理→CRUD | ✅ | 全部页面可操作 |
---
## 四、十项通用审计清单
| # | 审计点 | 结果 | 说明 |
|---|--------|------|------|
| 1 | 代码存在性 | ✅ 95% | 所有文档声明功能有对应代码 |
| 2 | 调用链连通 | ⚠️ 70% | 遥测/配置推送/OTA 链路断裂 |
| 3 | 配置传递 | ✅ 90% | saas-config.toml 端到端有效 |
| 4 | 降级策略 | ✅ 85% | 3 次失败→tauri 模式降级正常 |
| 5 | 错误处理 | ⚠️ 75% | Desktop 401 不自动 logout |
| 6 | 安全审计 | ❌ 60% | SQL 注入 + 权限缺失 |
| 7 | 日志记录 | ⚠️ 70% | migration/telemetry 模块缺 operation_logs |
| 8 | 测试覆盖 | ✅ 80% | SaaS 62 个集成测试, 但覆盖率不足 |
| 9 | 类型一致性 | ⚠️ 70% | 10+ 组类型定义不同步 |
| 10 | 前后端接口匹配 | ⚠️ 75% | 大部分匹配, 部分字段差异 |
---
## 五、五种差距模式
### 5.1 "写了没接" — 5 项确认
| # | 项目 | 位置 | 严重级别 |
|---|------|------|---------|
| G-01 | `recordLLMUsage` / `recordAuditEvent` 零外部调用 | telemetry-collector.ts | **P0** |
| G-02 | `startPromptOTASync` 从未调用 | llm-service.ts | **P1** |
| G-05 | `computeConfigDiff` / `syncConfig` push 未接入 | saas-client.ts | **P1** |
| G-10 | `hand_run_status` / `hand_run_list` 后端桩命令 | kernel_commands.rs | **P3** |
| — | `healthCheck()` 未被 health check 流程调用 | saas-client.ts | **P2** |
### 5.2 "接了没传" — 1 项确认
| # | 项目 | 位置 | 严重级别 |
|---|------|------|---------|
| G-04 | 心跳仅传 device_id, 不传 OS/version | saasStore.ts | **P1** |
### 5.3 "传了没存" — 2 项确认
| # | 项目 | 位置 | 严重级别 |
|---|------|------|---------|
| G-06 | telemetry 端点不写 operation_logs | telemetry/handlers.rs | **P2** |
| G-09 | 心跳不写 operation_logs | account/handlers.rs | **P2** |
### 5.4 "存了没用" — 2 项确认
| # | 项目 | 位置 | 严重级别 |
|---|------|------|---------|
| G-03 | `max_queue_size` / `max_concurrent` relay 未消费 | relay/service.rs | **P1** |
| G-07 | `account_api_keys` 被 relay 绕过 (用 provider_key_pool) | model_config/ | **P2** |
### 5.5 "双系统不同步" — 2 项确认
| # | 项目 | 说明 | 严重级别 |
|---|------|------|---------|
| G-08 | Desktop 401 不自动 logout, Admin 会 | 用户体验不一致 | **P2** |
| G-12 | 双端错误类型不统一 (SaaSApiError vs ApiRequestError) | 不可复用 | **P3** |
---
## 六、安全审计专项
### 6.1 CRITICAL: SQL 注入
**文件**: `crates/zclaw-saas/src/agent_template/service.rs`
全文件使用 `format!()` 直接拼接用户输入到 SQL, 依赖手工 `replace('\'', "''")` 转义。这是项目中**唯一未使用 `$N` 参数化查询**的 service 文件。
**受影响的操作**:
- `list_templates()` — WHERE 条件 (category, source, visibility, status)
- `update_template()` — SET 字段 (description, model, system_prompt, tools, capabilities, visibility, status) + WHERE id
**攻击向量示例**:
```sql
-- category 参数: `' OR 1=1 --` → 绕过 WHERE 条件
-- id 参数: `' OR '1'='1` → 更新所有记录
```
**修复方案**: 改用 `$N` 参数化查询, 参照 `account/service.rs` 和 `model_config/service.rs` 的实现模式。
### 6.2 HIGH: 部分模块使用 format! 构造 SQL (但有 $N 绑定)
**文件**: `prompt/service.rs`, `telemetry/service.rs`
这些文件在 WHERE 条件拼接时使用 `format!()`, 但值通过 `.replace('\'', "''")` 转义。虽然后续使用 `$N` 绑定值, 但 WHERE 条件本身的构造仍依赖手工转义。
### 6.3 HIGH: 配置同步缺少权限检查
`POST /api/v1/config/sync` (migration/handlers.rs) 端点未验证调用者是否有 admin 权限。任何已认证用户都可以推送配置。
### 6.4 MEDIUM: 配额限制未执行
`RelayConfig` 定义了 `max_queue_size` (默认 1000) 和 `max_concurrent_per_provider` (默认 5), 但 `execute_relay` 中未做队列容量和并发控制检查。
### 6.5 MEDIUM: Desktop 401 处理不完整
Desktop 端 `SaaSClient` 在 401 刷新失败后不自动 logout, 可能导致用户卡在过期会话中。Admin 端会自动跳转到登录页。
---
## 七、问题优先级与修复计划
### P0 — 立即修复 (阻塞功能)
| # | 问题 | 修复方案 | 影响范围 | 预估 |
|---|------|---------|---------|------|
| G-01 | 遥测系统全链路空转 | 在 llm-service.ts 的 chatCompletion 回调和 intelligence-hooks 中调用 recordLLMUsage / recordAuditEvent | telemetry-collector.ts, llm-service.ts, intelligence_hooks.rs | 2h |
| SEC-01 | SQL 注入 (agent_template) | 改用 `$N` 参数化查询 | agent_template/service.rs | 2h |
### P1 — 本周修复 (功能断裂)
| # | 问题 | 修复方案 | 影响范围 | 预估 |
|---|------|---------|---------|------|
| G-02 | Prompt OTA 未启动 | 在 saasStore.restoreSession/login 中调用 startPromptOTASync | llm-service.ts, saasStore.ts | 1h |
| G-03 | Relay 无并发限制 | 在 execute_relay 中加入队列容量和并发检查 | relay/service.rs | 2h |
| G-04 | 心跳不传 OS/version | 在 deviceHeartbeat 中携带 platform/app_version | saas-client.ts, account/handlers.rs | 1h |
| G-05 | 配置只能单向拉取 | 在 saasStore 中接入 computeConfigDiff 和 syncConfig push | saasStore.ts, saas-client.ts | 3h |
### P2 — 两周内修复 (质量提升)
| # | 问题 | 修复方案 | 影响范围 | 预估 |
|---|------|---------|---------|------|
| G-06 | Telemetry 端点缺审计日志 | 添加 log_operation 调用 | telemetry/handlers.rs | 1h |
| G-07 | account_api_keys 未被消费 | 明确用途: 要么让 relay 消费, 要么移除 | model_config/, relay/ | 4h |
| G-08 | Desktop 401 不自动 logout | 在 refresh 失败后调用 saasStore.logout() | saas-client.ts | 1h |
| SEC-02 | 配置同步缺权限检查 | 在 migration handler 中添加 admin 权限校验 | migration/handlers.rs | 1h |
### P3 — 长期优化 (技术债)
| # | 问题 | 修复方案 | 影响范围 | 预估 |
|---|------|---------|---------|------|
| G-10 | hand_run 桩命令 | 实现真实的运行状态追踪 | kernel_commands.rs | 3h |
| G-12 | 双端错误类型不统一 | 抽取共享错误类型到 @zclaw/types | admin+desktop | 4h |
| — | 28 处 dead_code | 评估后移除或保留 | desktop/src-tauri/ | 2h |
| — | 10+ 组类型定义差异 | 统一类型定义, 消除不一致 | admin+desktop types | 4h |
---
## 八、三端完成度评估
### SaaS 后端: **88%**
| 模块 | API 路由 | 完成度 | 主要问题 |
|------|---------|--------|---------|
| Auth | 8 | 95% | refresh 缺审计日志 |
| Account | 12 | 90% | dashboard 7 次串行查询 |
| Model Config | 14 | 90% | account_api_keys 未被消费 |
| Relay | 9 | 85% | 无并发限制, SSRF 需复核 |
| Migration | 9 | 70% | push 缺权限, 5 端点缺审计日志 |
| Role | 7 | 95% | 无重大问题 |
| Prompt OTA | 8 | 90% | 桌面端未启动 OTA |
| Agent Template | 5 | 75% | **SQL 注入** |
| Telemetry | 4 | 80% | 桌面端未调用上报函数 |
### Tauri 桌面端: **78%**
| 子系统 | 命令数 | 完成度 | 主要问题 |
|--------|-------|--------|---------|
| Kernel | 29 | 85% | hand_run 桩, scheduled_task 未实现 |
| Pipeline | 13 | 90% | 时间戳占位符 |
| Viking | 13 | 95% | 无重大问题 |
| LLM | 3 | 95% | 无重大问题 |
| Intelligence | 6 | 80% | 多个预留函数 |
| Browser | 23 | 85% | 需要 Fantoccini 运行时 |
| SaaS 集成 | 30+ 方法 | 65% | 35+ 方法未调用, 遥测断裂 |
### Admin 管理后台: **85%**
| 维度 | 完成度 | 主要问题 |
|------|--------|---------|
| 页面覆盖 | 95% | 12 个页面全覆盖 |
| API 调用 | 90% | 分页未连接 API |
| 认证 | 90% | token 刷新逻辑完善 |
| 类型定义 | 75% | 与桌面端不一致 |
---
## 九、关键决策建议
1. **遥测系统** — 必须在聊天回调和智能层 hook 中接入 recordLLMUsage, 否则 SaaS 端的遥测统计页面展示全零数据
2. **SQL 注入** — agent_template/service.rs 必须立即改为参数化查询, 这是生产安全红线
3. **配置同步** — 建议实现双向同步, 当前只能 SaaS→Desktop 单向拉取
4. **类型共享** — 考虑抽取 @zclaw/types 共享包, 消除 admin/desktop 类型不一致
5. **Prompt OTA** — 桌面端必须在登录后启动 OTA 同步, 否则 prompt 更新无法到达客户端
---
*审计报告结束*

308
docs/features/COMPREHENSIVE_AUDIT_V9.md
View File

@@ -1,308 +0,0 @@
# 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 队列

596
docs/features/DEEP_AUDIT_REPORT.md
View File

@@ -1,596 +0,0 @@
# ZCLAW 功能完成度深度审计报告
> **审计日期**: 2026-03-27
> **修复轮次**: 2026-03-27（P0/P1 第一轮修复完成）
> **审计方法**: 五步审计法（文档对齐 → 数据流追踪 → dead_code 识别 → trait 实现 → 端到端验证）
> **审计范围**: 全部 10 个 Rust crate + Tauri 后端 + React 前端 + docs/features 文档
> **独立性声明**: 本报告独立于此前三份审计报告（VERIFICATION_REPORT、FRONTEND_INTEGRATION_AUDIT、FEATURE_AUDIT_REPORT），所有结论均基于代码实际状态得出。
---
## 一、基础数据纠正
### 1.1 现有审计报告的不准确性
| 现有报告 | 声称 | 实际 | 偏差原因 |
|----------|------|------|----------|
| VERIFICATION_REPORT.md | 98.5% (133/135) | ~75% | 包含已删除功能（Team/Swarm），模拟实现标记为可用 |
| FRONTEND_INTEGRATION_AUDIT.md | "无僵尸组件" | 基本准确 | 但遗漏了 kernel-client.ts 中的幽灵调用 |
| FEATURE_AUDIT_REPORT.md | 85% (22/26) | ~60% | SpeechHand/TwitterHand 误判为"可用"，存储双路径未深入验证 |
### 1.2 基础数据事实
| 指标 | 文档声称 | 实际验证 | 差异 |
|------|----------|----------|------|
| Rust crate 数量 | 9 | 10（含 zclaw-pipeline、zclaw-growth） | +2 |
| Zustand Store 数量 | 18+ | 14（gatewayStore 已废弃） | -4 |
| SKILL.md 文件数量 | 78+ | 69 | -9 |
| HAND.toml 文件数量 | 11 | 9（predictor/lead 已删除） | -2 |
| Tauri 命令注册数 | 未明确 | 100+ | — |
| 前端 invoke 调用数 | 未明确 | ~50 独立命令名 | — |
---
## 二、功能完成度矩阵
### 2.1 架构层
| 功能 | 文档声称 | 真实完成度 | 差距模式 | 严重度 |
|------|----------|-----------|----------|--------|
| **通信层** | L4 (85%) | **L4 (85%)** | 无重大差距 | — |
| **状态管理** | L4 (85%) | **L4 (80%)** | gatewayStore 废弃但未清理 | LOW |
| **安全认证** | L4 (80%) | **L4 (80%)** | 无重大差距 | — |
### 2.2 核心功能层
| 功能 | 文档声称 | 真实完成度 | 差距模式 | 严重度 |
|------|----------|-----------|----------|--------|
| **聊天界面** | L4 (85%) | **L4 (85%)** | 流式响应链路完整 | — |
| **Agent 分身** | L4 (90%) | **L4 (85%)** | ~~Tauri 模式下 CRUD 静默失败~~ ✅ 已修复 (H7) | ~~HIGH~~ FIXED |
| **Hands 系统** | L4 (70%) | **L3 (60%)** | ~~审批流程被绕过~~ ✅ 已修复 (H8)；~~幽灵命令~~ ✅ 已修复 (M1)；SpeechHand/TwitterHand 已标记 demo | ~~HIGH~~ PARTIAL |
### 2.3 智能层
| 功能 | 文档声称 | 真实完成度 | 差距模式 | 严重度 |
|------|----------|-----------|----------|--------|
| **Agent 记忆** | L4 (90%) | **L4 (85%)** | ~~双存储路径使用不同数据库~~ ✅ 已修复 (H3) — 统一到 VikingStorage | ~~HIGH~~ FIXED |
| **身份演化** | L2 (70%) | **L2 (70%)** | ~~前端回滚 UI 缺失~~ ✅ 已实现 (IdentityChangeProposal.tsx HistoryItem + restoreSnapshot) | ~~MEDIUM~~ FIXED |
| **反思引擎** | L2 (65%) | **L2 (65%)** | ~~传入空记忆数组~~ ✅ 已修复 (C2)；~~结果未持久化~~ ✅ 已修复 (M4)；~~历史只存单条~~ ✅ 已修复 (M4-补 累积存储)；LLM 分析待接入 | ~~MEDIUM~~ MOSTLY FIXED |
| **心跳引擎** | L2 (70%) | **L2 (60%)** | ~~无持久化~~ ✅ 已修复 (H4)；~~历史重启丢失~~ ✅ 已修复 (心跳历史持久化)；默认禁用(enabled=false)，需前端主动启动 | ~~HIGH~~ MOSTLY FIXED |
| **自主授权** | L2 (75%) | **L2 (70%)** | ~~后端无守卫~~ ✅ 已修复 (M5-补 hand_execute/skill_execute 后端守卫) | ~~MEDIUM~~ FIXED |
| **上下文压缩** | L2 (75%) | **L2 (70%)** | 规则压缩已集成，LLM 压缩存在但默认关闭 | LOW |
### 2.4 扩展层
| 功能 | 文档声称 | 真实完成度 | 差距模式 | 严重度 |
|------|----------|-----------|----------|--------|
| **技能系统** | L3 (80%) | **L3 (75%)** | ~~PromptOnly 不调用 LLM~~ ✅ 已修复 (C1)；现在通过 LlmCompleter 桥接调用 LLM | ~~HIGH~~ FIXED |
| **智能路由** | L1 (15%) | **L1 (10%)** | 语义匹配是桩代码（返回 None），从未实例化 | MEDIUM |
| **Pipeline DSL** | L2 (75%) | **L2 (70%)** | ~~Presentation 层部分缺失~~ ✅ 已修复 (H6)；并行执行实际串行，进度报告粗粒度 | ~~MEDIUM~~ FIXED |
| **OpenViking** | L3 (70%) | **L3 (65%)** | 本地服务器启动慢 | LOW |
| **Browser 自动化** | L3 (80%) | **L3 (80%)** | Fantoccini 集成完整 | — |
| **Channels** | — | **L0 (10%)** | 仅有 ConsoleChannel 测试适配器 | LOW |
### 2.5 总体完成度
| 维度 | 文档声称 | 审计结果 | 修复后 |
|------|----------|----------|--------|
| **整体** | 68% | **~50%** | **~72%** |
| **核心可用** | 85% | **75%** | **~92%** |
| **真实可用** | 100% | **~55%**（排除模拟实现和 PromptOnly 技能后） | **~80%** |
---
## 三、差距清单（按严重度排序）
### 3.1 CRITICAL 严重度（2 项）
#### C1: 技能系统 PromptOnly 模式不调用 LLM，69/69 技能仅返回 prompt 模板 ✅ **已修复**
- **文件**: `crates/zclaw-skills/src/runner.rs:41-44`
- **修复方案**: 定义 `LlmCompleter` trait（`zclaw-skills`），创建 `LlmDriverAdapter` 桥接（`zclaw-kernel`），在 `SkillContext` 中注入 `llm` 字段。`PromptOnlySkill.execute()` 优先调用 LLM 生成结果，无 LLM 时回退到原始 prompt 文本。
- **修复文件**: `skill.rs`, `runner.rs`, `kernel.rs`
- **影响**: 整个技能系统本质上是**prompt 模板库**，不是执行引擎。`skill_execute` 返回的是格式化后的 prompt 文本，不是 AI 生成的内容。技能在 kernel 的 `build_skill_aware_system_prompt()` 中作为系统提示注入 LLM 上下文（这部分是有效的），但直接执行技能本身不产生 AI 输出。
- **差距模式**: 写了没接 — 执行框架完整但核心处理逻辑缺失
- **根因**: PromptOnly 模式设计为"注入 prompt 后由 Agent Loop 的 LLM 调用处理"，而非独立执行。但 `execute_skill` Tauri 命令直接返回 prompt 文本给前端，前端将其作为"执行结果"展示，造成功能完整的假象。
- **解决方案**:
- 短期: 在 PromptOnlySkill 中集成 LLM 调用，将 prompt 发送给 LLM 后返回生成结果
- 或: 在 kernel_commands.rs 的 skill_execute 中，获取 prompt 后通过 kernel 的 LLM driver 生成结果
- 或: 在前端展示时明确标注这是"prompt 模板"而非"执行结果"
#### C2: 反思引擎传入空记忆数组，整个子系统是空操作 ✅ **已修复**
- **文件**: `desktop/src-tauri/src/intelligence_hooks.rs:65`
- **修复方案**: 新增 `query_memories_for_reflection()` 函数，在 `reflect()` 调用前从 VikingStorage 查询最多 50 条 agent 记忆，转换为 `MemoryEntryForAnalysis` 后传入。同时为 `post_conversation_hook` 添加 `user_message` 参数。
- **修复文件**: `intelligence_hooks.rs`, `kernel_commands.rs`
- **影响**: `analyze_patterns()` 对空数组进行阈值检测（task ≥ 5、preference ≥ 5 等），**永远无法触发任何模式检测**。反思引擎的 patterns、improvements、identity_proposals **永远是空的**。整个反思子系统（~500 行代码 + 文档 + UI 组件）实际上**从未产生过任何有意义的输出**。
- **差距模式**: 接了没传 — 反思逻辑完整但调用时传入了空数据
- **根因**: `post_conversation_hook` 应该先从 VikingStorage 获取记忆数据再传给 `reflect()`
- **解决方案**:
- 修复: 在 `reflect()` 调用前查询 VikingStorage 获取当前 agent 的记忆列表
- 示例: `let memories = fetch_agent_memories(agent_id).await; engine.reflect(agent_id, &memories);`
### 3.2 HIGH 严重度（8 项）
#### H1: SpeechHand 完全模拟 ✅ **已标记 demo**
- **文件**: `crates/zclaw-hands/src/hands/speech.rs:236`
- **证据**: `"In real implementation, would call TTS API"` — 返回 `duration_ms: text.len() * 80` 的伪数据
- **差距模式**: 写了没接 — 代码结构完整但无真实 API 调用
- **影响**: 用户触发 SpeechHand 期望得到语音输出，实际只返回 JSON 状态
- **解决方案**:
- 短期: UI 标记为"演示模式"
- 中期: 集成浏览器 Web Speech API（通过 Tauri webview.eval）
- 长期: 实现 Azure/OpenAI/ElevenLabs TTS API
#### H2: TwitterHand 完全模拟 ✅ **已标记 demo**
- **文件**: `crates/zclaw-hands/src/hands/twitter.rs:297-509`
- **证据**: 所有 10+ 个操作返回 `"(simulated)"` JSON，搜索返回空数组
- **差距模式**: 写了没接 — 类型定义完整但无 HTTP 请求
- **影响**: 即使配置了 API Key 也不会生效，返回假数据
- **解决方案**:
- 短期: UI 明确标注"模拟模式"，禁用写操作
- 中期: 实现 Twitter API v2 或改为 Mastodon API
#### H3: 记忆系统双存储路径不同步 ✅ **已修复**
- **修复方案**: 完全重写 `memory_commands.rs`，所有操作统一委派到 VikingStorage (SqliteStorage)。移除了 PersistentMemoryStore 的双写逻辑。保留 PersistentMemory 类型作为前端 API 兼容层，内部通过 `to_persistent()` 转换。
- **修复文件**: `memory_commands.rs`, `viking_commands.rs`, `memory/mod.rs`
- **路径A**: `memory_commands.rs` → `PersistentMemoryStore` → `{app_data_dir}/memory/memories.db`（UI 面板使用）
- **路径B**: `intelligence_hooks.rs` → `VikingStorage` → `{data_dir}/zclaw/memories/memories.db`（聊天流程使用）
- **证据**: 两个路径使用**不同的数据库文件**。`memory_store()` 第88-94行虽有双写逻辑，但 `memory_search()` 优先用 VikingStorage，`intelligence_hooks` 也只用 VikingStorage。`memory_db_path()` 返回的是 PersistentMemoryStore 的路径。
- **差距模式**: 双系统不同步
- **影响**: UI 面板存储的记忆可能无法在聊天时被检索到
- **解决方案**: 统一到 `zclaw-growth` 的 SqliteStorage（已有 FTS5 + TF-IDF + 可选 embedding）
#### H4: 心跳引擎无持久化（已在启动时运行） ✅ **已修复**
- **修复方案**: `record_interaction()` 现在通过 `tokio::spawn` 将交互时间戳持久化到 VikingStorage metadata（key: `heartbeat:last_interaction:{agent_id}`）。`heartbeat_init()` 在初始化时调用 `restore_last_interaction()` 从 VikingStorage 恢复上次交互时间，确保 `idle-greeting` 检查在应用重启后仍能正确工作。
- **修复文件**: `heartbeat.rs`
- **文件**: `desktop/src-tauri/src/intelligence/heartbeat.rs`
- **证据**:
- `HeartbeatConfig::default()` 中 `enabled: false`（第103行），但 `App.tsx:181` 主动调用 `heartbeat.start()`
- `start()` **确实启动了后台 tokio 任务**，每 30 分钟执行一次 tick（第138-180行）
- `record_interaction()` 只写入全局静态 HashMap（第378-382行），不持久化到磁盘
- `history` 存储在内存 `Arc<Mutex<Vec<HeartbeatResult>>>`，重启丢失
- `MEMORY_STATS_CACHE` 需要前端调用 `heartbeat_update_memory_stats` 才能填充，否则 `check_pending_tasks` 和 `check_memory_health` 发出"记忆统计未同步"警告
- **差距模式**: 传了没存
- **影响**: 心跳引擎已运行但所有状态重启后丢失；记忆统计检查需要前端主动同步
- **解决方案**:
- 使用 SQLite 持久化交互记录和心跳历史
- 自动同步记忆统计，不依赖前端手动调用
#### H5: VERIFICATION_REPORT 包含已删除功能 ✅ **已归档**
- **文件**: `docs/features/VERIFICATION_REPORT.md`
- **证据**: 报告验证了 "Multi-Agent Collaboration" 和 "Team/Swarm" 功能，但 commit `c399657` 已删除这些功能
- **差距模式**: 存了没用 — 过时文档误导开发者
- **影响**: 审计结论不可信，98.5% 通过率严重虚高
- **解决方案**: 立即更新或归档此报告，以本审计报告替代
#### H6: Presentation 层部分渲染器缺失 ✅ **已修复**
- **修复方案**:
- Chart: 新增 `ChartRenderer.tsx`，使用 recharts 实现 line/bar/pie/scatter/area 五种图表
- Document: 替换手写 markdown 解析器为 react-markdown + remark-gfm（支持 tables、links、images、inline code）
- Slideshow: 实现完整 slide type 渲染（title/content/image/code/twoColumn），集成 react-markdown
- Whiteboard: 保留占位但添加 "即将推出" 标签
- **修复文件**: `ChartRenderer.tsx`(新)、`DocumentRenderer.tsx`、`SlideshowRenderer.tsx`、`PresentationContainer.tsx`
- **文件**: `desktop/src/components/presentation/`
- **证据**:
- Chart 渲染器**完全缺失** — PresentationAnalyzer 可检测 Chart 类型，但无对应 UI 渲染器，选择 "chart" 会显示默认占位
- Whiteboard 渲染器是**占位文本** — `PresentationContainer.tsx:113-116` 显示 "白板渲染器开发中..."
- Slideshow 渲染器**导航可用但内容渲染是 stub** — 复杂内容显示 "Complex content rendering" 占位，无实际 markdown/代码/图片渲染
- Document 渲染器**手写 markdown 解析器** — 不支持 inline code、links、images、tables、nested lists
- **差距模式**: 写了没接 — 分析器能识别类型但渲染器未实现
- **解决方案**:
- 短期: Chart 用 recharts 库实现，Whiteboard 保持占位但移除 "可用" 标签
- 中期: Slideshow 集成 markdown 渲染库（react-markdown），Document 替换手写解析器
#### H7: Agent Store 接口不匹配 — Tauri 模式下 Agent CRUD 静默失败 ✅ **已修复**
- **修复方案**: 在 `KernelClient` 上添加 `listClones/createClone/deleteClone/updateClone` 适配方法，内部映射到 `listAgents/createAgent/deleteAgent`。
- **修复文件**: `kernel-client.ts`
- **文件**: `desktop/src/store/agentStore.ts:137-204`，`desktop/src/lib/kernel-client.ts`
- **证据**: `agentStore.ts` 调用 `client.listClones()`、`client.createClone()`、`client.deleteClone()` — 这些方法定义在 `GatewayClient` 接口上，但 `KernelClient` **没有这些方法**。KernelClient 只有 `listAgents()`、`createAgent()`、`deleteAgent()`（使用 `agent_list`/`agent_create`/`agent_delete` 命令）。在 Tauri 内核模式下，Agent 管理操作会静默失败。
- **差距模式**: 接了没传 — 前端调用的方法在当前客户端上不存在
- **影响**: Tauri 模式下用户无法创建、列出、删除 Agent
- **解决方案**: agentStore 适配 KernelClient 接口（调用 `listAgents`/`createAgent`/`deleteAgent`）
#### H8: Hand 审批流程被绕过 — needs_approval 从未检查 ✅ **已修复**
- **修复方案**: `hand_execute` 在执行前查询 `list_hands()` 检查 `needs_approval`，如需审批则创建 pending approval 并返回 `pending_approval` 状态。
- **修复文件**: `kernel_commands.rs`
- **文件**: `desktop/src-tauri/src/kernel_commands.rs:805-820`
- **证据**: `hand_execute()` 直接调用 `kernel.execute_hand(&id, input)`，**完全不检查** `needs_approval` 配置。审批系统（`approval_list`、`approval_respond`、`hand_approve`、`hand_cancel`）的 Tauri 命令都存在，但执行 Hand 时从未触发审批流程。
- **差距模式**: 写了没接 — 审批基础设施完整但执行路径不检查
- **影响**: 标记为 `needs_approval: true` 的 Hand（如 browser.HAND.toml）可以直接执行，审批流是死代码
- **解决方案**: 在 `hand_execute` 中检查 `needs_approval`，如需审批则创建审批请求并返回 pending 状态
### 3.2 MEDIUM 严重度（7 项）
#### M1: 3 个幽灵 Tauri 命令调用 ✅ **已修复**
- **修复方案**: 在 `kernel_commands.rs` 注册 `hand_get`（查询 hand 详情）、`hand_run_status`（返回 not_found）、`hand_run_list`（返回空列表）三个桩命令，并在 `lib.rs` 的 `generate_handler!` 中注册。
- **修复文件**: `kernel_commands.rs`, `lib.rs`
- **前端调用** (kernel-client.ts):
- `invoke('hand_get')` — 第618行，try/catch 返回 `{}`
- `invoke('hand_run_status')` — 第641行，try/catch 返回 `{ status: 'unknown' }`
- `invoke('hand_run_list')` — 第680行，try/catch 返回 `{ runs: [] }`
- **后端注册**: 仅有 `hand_list`, `hand_execute`, `hand_approve`, `hand_cancel`
- **差距模式**: 接了没传 — 静默失败
- **解决方案**: 注册显式命令或移除前端调用
#### M2: plugin:tinker|ping 调用不存在的插件
- **文件**: `desktop/src/lib/kernel-client.ts:164`
- **证据**: `await invoke('plugin:tinker|ping')` — 项目中无 tinker 插件
- **差距模式**: 接了没传
- **解决方案**: 移除此调用或实现实际的健康检查
#### M3: hand_approve 忽略 hand_name 参数
- **文件**: `desktop/src-tauri/src/kernel_commands.rs:1109`
- **证据**: `fn hand_approve(_hand_name: String, run_id: String, ...)`
- **差距模式**: 接了没传 — 参数传递但被忽略
- **影响**: 无法按 hand 类型筛选审批
- **解决方案**: 实现按 hand_name + run_id 联合查找
#### M4: 反思引擎结果未反馈到行为 ✅ **已修复（持久化部分）**
- **修复方案**: `reflect()` 完成后通过 `tokio::spawn` 将 ReflectionState 和 ReflectionResult 持久化到 VikingStorage metadata。新增 `restore_state()` 方法在初始化时从 VikingStorage 恢复状态，确保 `conversations_since_reflection` 计数器在重启后保持。`intelligence_hooks` 在首次 `post_conversation_hook` 时通过 `pop_restored_state/result` 消费恢复数据。
- **修复文件**: `reflection.rs`, `intelligence_hooks.rs`
- **文件**: `desktop/src-tauri/src/intelligence/reflection.rs:190-233`
- **证据**: `reflect()` 基于规则检测模式（task ≥ 5、preference ≥ 5、lesson ≥ 5），生成改进建议，但结果仅存入内存 `history: Vec<ReflectionResult>`（最多保留 20 条），不持久化且不用于修改后续行为。**更严重的是，由于 C1 bug，这些结果永远是空的。**
- **差距模式**: 传了没存 + 存了没用
- **影响**: 反思产出（patterns、improvements、identity_proposals）仅记录在日志中，用户看不到，Agent 也不会据此调整行为
- **解决方案**: 先修复 C1（传入真实记忆），再将结果持久化到 SQLite，在 RightPanel 中展示，用于身份演化触发
#### M4b: LLM 压缩器孤立，kernel 只用规则压缩 ✅ **已修复**
- **修复方案**: 在 `zclaw-runtime::compaction` 中新增 `CompactionConfig`、`CompactionOutcome` 和异步 `maybe_compact_with_config()` 函数。AgentLoop 根据 config 中的 `use_llm` 标志选择 LLM 摘要或规则摘要路径。LLM 失败时自动回退到规则摘要。
- **修复文件**: `compaction.rs`、`loop_runner.rs`、`lib.rs`
- **文件**: `desktop/src-tauri/src/intelligence/compactor.rs` vs `crates/zclaw-runtime/src/compaction.rs`
- **证据**: Kernel AgentLoop 使用 `zclaw-runtime::compaction`（纯规则，CJK token 估算），Tauri 的 `compactor_compact_llm`（支持 LLM 摘要）虽然注册为命令但**从未被 kernel 调用**。`use_llm` 配置只影响 Tauri 命令，不影响 kernel 循环。
- **差距模式**: 写了没接
- **影响**: 即使配置 `use_llm: true`，聊天压缩也不会使用 LLM 生成摘要
- **解决方案**: 在 kernel 的 AgentLoop 中集成 LLM 压缩路径
#### M4c: 压缩时记忆刷出是空操作 ✅ **已修复**
- **修复方案**:
- Runtime 层: `maybe_compact_with_config()` 在压缩前调用 `GrowthIntegration.process_conversation()` 提取记忆
- Tauri 层: `compactor_compact` 和 `compactor_compact_llm` 命令在压缩前调用 `flush_old_messages_to_memory()` 将用户消息和助手回复刷出到 VikingStorage
- **修复文件**: `compaction.rs`（runtime）、`compactor.rs`（tauri）
- **文件**: `crates/zclaw-runtime/src/compaction.rs`, `desktop/src-tauri/src/intelligence/compactor.rs`
- **证据**: 两个压缩器都设置 `flushed_memories: 0`，`memory_flush_enabled` 配置存在但**无实现**
- **差距模式**: 写了没接
- **影响**: 长对话压缩时不会自动提取和保存关键记忆
- **解决方案**: 实现压缩时的记忆提取逻辑
#### M5: 自主授权未集成到执行链路
- **文件**: `desktop/src/lib/autonomy-manager.ts`, `desktop/src/components/AutonomyConfig.tsx`
- **证据**: 组件存在且渲染在 RightPanel，但 `canAutoExecute()` 未在 `kernel_commands.rs` 的 hand_execute 或 skill_execute 中被调用
- **差距模式**: 写了没接
- **影响**: 用户配置的自主级别不影响实际执行
- **解决方案**: 在 Tauri 命令层集成自主授权检查
#### M6: Pipeline 语义路由是桩代码
- **文件**: `crates/zclaw-pipeline/src/intent.rs:454-457`
- **证据**: 构建了 LLM prompt 但 `let _ = prompt; // Suppress unused warning` 然后 `return None`
- **差距模式**: 写了没接
- **影响**: Pipeline 只能用关键词匹配触发
- **解决方案**: 接入 LLM driver 实现真正的语义匹配
#### M7: Pipeline 无 YAML 模板文件
- **证据**: `find config/ skills/ hands/` 未找到任何 `.yaml`/`.yml` 文件
- **差距模式**: 存了没用 — 文档声称 5 个模板但文件不存在
- **影响**: 用户无法使用预设的 Pipeline 模板
- **解决方案**: 创建实际可用的 YAML 模板文件
### 3.3 LOW 严重度（6 项）
#### L1: Pipeline 并行执行实际串行
- **文件**: `crates/zclaw-pipeline/src/engine/stage.rs:321-322`
- **证据**: `execute_parallel` 使用 for 循环，注释 "True parallel execution would require Send-safe drivers"
- **差距模式**: 写了没接
#### L2: gatewayStore.ts 废弃但仍被引用
- **文件**: `desktop/src/store/gatewayStore.ts`（@deprecated），`HandApprovalModal.tsx:25` 仍导入
- **差距模式**: 写了没接
#### L3: Wasm/Native 技能模式未实现
- **文件**: `crates/zclaw-skills/src/skill.rs`
- **证据**: SkillMode::Wasm 和 SkillMode::Native 注释为 "not yet implemented, falls back to PromptOnly"
- **差距模式**: 写了没接
#### L4: 28 个 `#[allow(dead_code)]` 标注
- **分布**:
- LLM driver 反序列化字段（anthropic.rs、openai.rs、local.rs、gemini.rs）— 合理
- intelligence 模块预留方法（identity export/import、heartbeat is_running/subscribe、compactor get_config/update_config、reflection get_last_result）— 预留
- export 预留（html template、markdown without_front_matter）— 预留
- `lib.rs` build_staged_runtime_legacy、HealthStatus — 遗留代码
- `intent.rs` DefaultLlmIntentDriver — 桩代码
- `persistent.rs` tags 字段 — 预留
- `browser/session.rs` session_count — 预留
- **建议**: 遗留代码（lib.rs legacy）可删除，其余保留
#### L5: 5 个 TODO 注释
- `registry.rs:56` — message_count tracking
- `orchestration.rs:41` — graph storage
- `pipeline_commands.rs:442` — use actual time
- `pipeline_commands.rs:781` — pattern support
- `html.rs:17` — template-based export
- **建议**: 均为功能增强，非阻塞
#### L6: zclaw-channels 仅有测试适配器
- **文件**: `crates/zclaw-channels/src/adapters/console.rs`
- **证据**: 仅有 ConsoleChannel，无 Discord/Slack/飞书等真实适配器
- **影响**: 低 — 桌面端不依赖外部通道
- **建议**: 维持现状或移除 crate
---
## 四、调用链验证报告
### 4.1 聊天消息流 ✅ 已验证
```
ChatArea.tsx → chatStore.sendStreamMessage()
→ kernel-client.ts sendStreamMessage() → invoke('agent_chat_stream')
→ kernel_commands.rs agent_chat_stream()
→ intelligence_hooks.rs pre_conversation_hook()
→ build_memory_context() → VikingStorage.find() ✅
→ build_identity_prompt() → IdentityManager.build_system_prompt() ✅
→ kernel.agent_chat_stream()
→ loop_runner.rs AgentLoop（compaction threshold 15k）✅
→ LLM driver（4个实现：Anthropic/OpenAI/Gemini/Local）✅
→ intelligence_hooks.rs post_conversation_hook()
→ heartbeat.record_interaction() ✅（仅内存）
→ reflection.record_conversation() + should_reflect() ✅ 已修复 (C2: 传入真实记忆)
→ Tauri events 发射 ✅
→ kernel-client.ts 事件监听 ✅
→ ChatArea.tsx 渲染 ✅
```
### 4.2 Hand 执行流 ⚠️ 部分验证
```
HandList.tsx → handStore.triggerHand()
→ kernel-client.ts triggerHand() → invoke('hand_execute')
→ kernel_commands.rs hand_execute() → kernel.hand_execute()
→ HandRegistry.get() → Hand.execute()
→ [真实] QuizHand: LLM 生成题目 ✅
→ [真实] ResearcherHand: DuckDuckGo 搜索 ✅
→ [真实] CollectorHand: HTML 抓取 ✅
→ [真实] ClipHand: FFmpeg 调用 ✅
→ [真实] SlideshowHand: 状态管理 ✅
→ [真实] WhiteboardHand: 状态管理 ✅
→ [模拟] SpeechHand: 返回伪 JSON ❌
→ [模拟] TwitterHand: 返回 "(simulated)" ❌
→ [委托] BrowserHand: 委托给 Tauri browser commands ✅
→ 审批检查（如 needs_approval）✅ 已修复 (H8)
→ 结果返回
→ handStore 处理结果
→ UI 显示结果
```
### 4.3 记忆存储流 ⚠️ 双路径
```
路径A (UI面板):
MemoryPanel.tsx → intelligence-backend.ts memory_store()
→ invoke('memory_store') → memory_commands.rs
→ PersistentMemoryStore.store() → {app_data}/memory/memories.db
→ VikingStorage.add() → {data_dir}/zclaw/memories/memories.db (双写)
路径B (聊天流程):
intelligence_hooks.rs build_memory_context()
→ VikingStorage.find() → {data_dir}/zclaw/memories/memories.db
```
### 4.4 技能执行流 ⚠️ PromptOnly 不产生 AI 输出
```
SkillMarket.tsx → kernel-client.ts executeSkill()
→ invoke('skill_execute') → kernel_commands.rs skill_execute()
→ kernel.execute_skill() → SkillRegistry → SkillExecutor
→ PromptOnlySkill: 通过 LlmCompleter 调用 LLM 生成内容 ✅ 已修复 (C1)
→ PythonSkill: subprocess 执行 ✅（但无技能使用此模式）
→ ShellSkill: subprocess 执行 ✅（仅 shell-command 使用此模式）
→ WasmSkill → 回退到 PromptOnly ❌
→ NativeSkill → 回退到 PromptOnly ❌
注意: 技能在 kernel 的 build_skill_aware_system_prompt() 中作为上下文注入是有效的，
但通过 skill_execute 命令直接执行时，PromptOnly 不产生 AI 生成内容。
```
### 4.5 Pipeline 执行流 ⚠️ 部分验证
```
PipelinesPanel.tsx → workflowStore.runPipeline()
→ invoke('pipeline_run') → pipeline_commands.rs pipeline_run()
→ StageEngine.execute()
→ Llm stage: 调用 LLM ✅
→ Parallel stage: 实际串行 ❌
→ Sequential stage: 顺序链 ✅
→ Conditional stage: 条件评估 ✅
→ Skill stage: 调用技能系统 ✅
→ Hand stage: 调用 Hand 系统 ✅
→ Http stage: HTTP 请求 ✅
→ SetVar stage: 设置变量 ✅
→ Compose stage: 模板组合 ✅
→ Progress 事件
```
---
## 五、Dead Code 分类清单
### 5.1 真正的死代码（建议删除）
| 位置 | 类型 | 建议 |
|------|------|------|
| `lib.rs` build_staged_runtime_legacy | 遗留函数 | 删除 |
| `lib.rs` HealthStatus enum | 预留枚举 | 删除或实现 |
### 5.2 预留功能（暂时保留）
| 位置 | 类型 | 建议 |
|------|------|------|
| `identity.rs` export_all/import/get_all_proposals | 预留方法 | 保留，添加 Tauri 命令 |
| `heartbeat.rs` is_running/subscribe | 预留方法 | 保留 |
| `compactor.rs` get_config/update_config | 预留方法 | 保留 |
| `reflection.rs` get_last_result | 预留方法 | 保留 |
| `persistent.rs` tags 字段 | 预留字段 | 保留 |
| `browser/session.rs` session_count | 预留方法 | 保留 |
| `html.rs` template/with_template | 预留功能 | 保留 |
| `markdown.rs` without_front_matter | 预留功能 | 保留 |
| `stage.rs` clone_with_drivers | 预留功能 | 保留 |
| `a2a.rs` new() | 预留构造器 | 保留 |
| `sqlite.rs` path 字段 | 预留字段 | 保留 |
| `cache.rs` CacheKey struct | 预留类型 | 保留 |
### 5.3 桩代码（需要实现或明确标注）
| 位置 | 类型 | 建议 |
|------|------|------|
| `intent.rs` DefaultLlmIntentDriver.semantic_match | 桩代码 | 接入 LLM driver |
| `speech.rs` execute_action (Speak) | 模拟实现 | 集成真实 TTS |
| `twitter.rs` 所有 execute_* 方法 | 模拟实现 | 集成真实 API 或标记为演示 |
---
## 六、跨部门专家头脑风暴
### 议题 1: SpeechHand/TwitterHand 是否应该保留在发布版中？
**产品视角**:
- 用户看到"可用"标签会期望真实功能，模拟实现会损害信任
- 建议: 短期在 UI 中标记为"演示/Preview"状态，长期要么实现要么移除
**工程视角**:
- 模拟实现有其价值：验证了类型系统、配置传递、审批流程的正确性
- 可以作为真实实现的骨架，替换核心逻辑即可
- 建议: 保留代码但移除"可用"标签
**安全视角**:
- TwitterHand 的模拟实现不会造成安全问题（无网络请求）
- 但 UI 不应让用户误以为操作已生效
- 建议: 写操作的 UI 按钮必须添加明确提示
**结论**: 保留代码，UI 标记为"演示模式"，写操作添加确认提示
### 议题 2: 双存储路径如何统一？
**架构视角**:
- PersistentMemoryStore（sqlx 直连）和 VikingStorage/zclaw-growth（trait 抽象）本质上是同一个功能的两套实现
- zclaw-growth 的 SqliteStorage 有 FTS5 + TF-IDF + embedding 支持，能力更强
- 统一到 zclaw-growth 是正确的方向
**数据迁移视角**:
- 需要将 PersistentMemoryStore 中已有的数据迁移到 VikingStorage
- `memory_store()` 已有双写逻辑，只需确保搜索也统一使用 VikingStorage
**结论**: 统一到 VikingStorage，删除 PersistentMemoryStore，确保所有搜索路径走同一数据库
### 议题 3: 反思引擎的产出是否有价值？
**AI 研究视角**:
- 当前的 `analyze_patterns()` 基于简单阈值（task ≥ 5），检测粒度粗
- 没有使用 LLM 进行深度分析，无法发现复杂的行为模式
- 但作为 L0 级别的规则检测，它提供了基础的价值
**产品视角**:
- 反思结果目前只存在内存中，用户看不到
- 如果不展示给用户、不影响 Agent 行为，等于不存在
- 建议: 至少在 RightPanel 中展示反思日志
**结论**: 保留规则检测作为基础，将结果持久化并在 UI 中展示，中期升级为 LLM 驱动
### 议题 4: 心跳引擎是否值得维护？
**运维视角**:
- 默认禁用意味着这个功能从未被用户使用过
- 如果没有用户需求，维护它只是增加代码复杂度
- 但作为 Agent 主动性的基础，长期有战略价值
**工程视角**:
- `record_interaction()` 仅写入内存 HashMap，重启丢失
- `tick()` 没有定时器自动执行，需要手动触发
- 建议: 要么完整实现（持久化 + 定时器 + 通知），要么降级为按需触发
**结论**: 将 enabled 默认改为 true，实现 SQLite 持久化，保留定时器但简化检查项
---
## 七、修复优先级矩阵
| 优先级 | ID | 问题 | 工作量 | 建议时间线 | 状态 |
|--------|-----|------|--------|-----------|------|
| **P0** | C1 | PromptOnly 技能不调用 LLM — 集成 LLM driver | 1-2d | **立即** | ✅ 已修复 |
| **P0** | C2 | 反思引擎传入空记忆 — 修复 reflect() 调用 | 1h | **立即** | ✅ 已修复 |
| **P0** | H5 | 更新/归档过时的 VERIFICATION_REPORT | 1h | **立即** | ✅ 已归档 |
| **P1** | H7 | Agent Store 适配 KernelClient 接口 | 1d | 本周 | ✅ 已修复 |
| **P1** | H8 | Hand 执行前检查 needs_approval | 4h | 本周 | ✅ 已修复 |
| **P1** | M1 | 注册 3 个幽灵命令或移除调用 | 2h | 本周 | ✅ 已修复 |
| **P1** | H1 | SpeechHand 标记为演示模式 | 2h | 本周 | ✅ 已标记 |
| **P1** | H2 | TwitterHand 标记为演示模式 | 2h | 本周 | ✅ 已标记 |
| **P1** | H3 | 统一记忆双存储路径 | 2-3d | 本周 | ✅ 已修复 |
| **P1** | H4 | 心跳引擎持久化 + 自动同步记忆统计 | 1-2d | 本周 | ✅ 已修复 |
| **P1** | P7 | Presentation 层缺失 Chart/Whiteboard 渲染器 | 2-3d | 本周 | ✅ 已修复 |
| **P2** | M4b | LLM 压缩器集成到 kernel AgentLoop | 1-2d | 下周 | ✅ 已修复 |
| **P2** | M4c | 实现压缩时的记忆刷出 | 1d | 下周 | ✅ 已修复 |
| **P2** | M4 | 反思结果持久化 + UI 展示 | 2d | 下周 | ✅ 已修复 |
| **P2** | M5 | 自主授权集成到执行链路 | 1-2d | 下周 | ✅ 已修复 |
| **P2** | M3 | hand_approve 使用 hand_name 参数 | 1h | 下周 | ✅ 已修复 |
| **P2** | L2 | 清理 gatewayStore 废弃引用 | 1h | 下周 | ✅ 已确认（仅注释） |
| **P2** | S9 | 消息搜索仅当前会话 — 新增 Global 模式 | 1d | 下周 | ✅ 已修复 |
| **P3** | M6 | 实现语义路由 | 2-3d | 下个迭代 |
| **P3** | L1 | Pipeline 并行执行 | 2d | 下个迭代 |
| **P3** | L3 | Wasm/Native 技能模式 | 3-5d | 长期 |
| **P3** | L4 | 清理死代码标注 | 4h | 长期 |
| **P3** | L5 | 处理 TODO 注释 | 1d | 长期 |
| **P3** | L6 | zclaw-channels 决策 | 评估后决定 | 长期 |
---
## 八、审计命令速查（已验证）
```bash
# Dead code 扫描（已验证 28 处）
rg '#\[allow\(dead_code\)\]' crates/ desktop/src-tauri/ -B 1 -A 3 --type rust
# TODO 扫描（已验证 5 处）
rg 'TODO|FIXME' crates/ desktop/src-tauri/ --type rust -n
# 模拟代码扫描（已确认 speech.rs + twitter.rs）
rg 'simulated|In real implementation' crates/ desktop/src-tauri/ --type rust -n -i
# Tauri 命令交叉验证（已确认 3 个幽灵调用）
rg 'kernel_commands::|pipeline_commands::|viking_commands::|memory_commands::|intelligence::|browser::commands::|secure_storage::|memory::|llm::' desktop/src-tauri/src/lib.rs -o | sort -u
rg "invoke\(['\"]" desktop/src/ --type ts -o | sort -u
```
---
## 九、结论
ZCLAW 的核心架构（通信、状态管理、安全认证、聊天、Agent 管理）是**坚实可靠的**。Rust 核心代码质量高，测试覆盖好，无 `todo!()` 或 `unimplemented!()` 宏。
主要问题集中在：
1. ~~**技能系统 PromptOnly 不调用 LLM**~~ ✅ 已修复 — 通过 LlmCompleter 桥接调用 LLM
2. ~~**反思引擎是空操作**~~ ✅ 已修复 — 传入真实记忆，结果持久化到 VikingStorage
3. ~~**Agent Store 接口不匹配**~~ ✅ 已修复 — KernelClient 添加适配方法
4. ~~**Hand 审批流程被绕过**~~ ✅ 已修复 — 执行前检查 needs_approval
5. ~~**2 个 Hand 是模拟实现**~~ ✅ 已标记 demo 标签
6. ~~**记忆系统双存储路径**~~ ✅ 已统一 — VikingStorage 元数据持久化
7. ~~**心跳引擎**无持久化~~ ✅ 已修复 — 交互时间戳 + 历史数组持久化
8. ~~**LLM 压缩器孤立**~~ ✅ 已修复 — runtime compaction 支持 LLM 摘要 + 记忆刷出
9. ~~**Presentation 层**渲染器缺失~~ ✅ 已修复 — Chart(recharts)、Document(react-markdown)、Slideshow 完整渲染
10. ~~**3 份审计报告**过时~~ ✅ 已归档
11. ~~**自主授权后端无守卫**~~ ✅ 已修复 — hand_execute/skill_execute 接收 autonomy_level 参数
12. ~~**hand_approve 忽略参数**~~ ✅ 已修复 — 使用 hand_name 审计日志
13. ~~**反思历史只存单条**~~ ✅ 已修复 — 累积存储到 reflection:history 数组
14. ~~**身份回滚 UI 缺失**~~ ✅ 已实现 — IdentityChangeProposal.tsx HistoryItem
15. **28 处 dead_code 标注**中大部分是合理的预留功能，少数是遗留代码
16. ~~**剩余 P2/P3 项**: 反思 LLM 分析、语义路由、Pipeline 并行等~~ ✅ 已修复 — 见下方 18-20
17. ~~**消息搜索仅当前会话**~~ ✅ 已修复 — MessageSearch 新增 Global 模式，调用 VikingStorage memory_search 跨会话搜索记忆
18. ~~**反思引擎规则升级为 LLM**~~ ✅ 已修复 — `analyze_patterns_with_llm()` 调用 LLM 做深度行为分析，失败回退规则
19. ~~**语义路由是桩代码**~~ ✅ 已修复 — `RuntimeLlmIntentDriver` 包装 LlmDriver 实现真实语义匹配
20. ~~**Pipeline 并行执行实际串行**~~ ✅ 已修复 — `execute_parallel()` 改用 `buffer_unordered(max_workers)` 真正并行
**累计修复 27 项** (P0×3 + P1×8 + P2×7 + P3×4 + 误判×2 + 审计×3)，系统真实可用率从 ~50% 提升到 ~85%。
---
## 九、v5 审计追加修复（2026-03-27）
v5 审计独立验证了上述 27 项修复，确认 25 项完全到位、2 项部分到位，并新发现 8 项问题。以下为追加修复：
| # | 问题 | 修复方案 | 状态 |
|---|------|---------|------|
| 28 | WhiteboardHand Export 返回伪造 data_url | HAND.toml 添加 `demo = true` + 描述标注 | ✅ 已修复 |
| 29 | Director(907行) + A2A(690行) 孤立 | `#[cfg(feature = "multi-agent")]` 条件编译 + Cargo.toml feature 定义 | ✅ 已修复 |
| 30 | compactor_compact_llm 冗余 Tauri 命令 | 从 `generate_handler!` 移除注册 | ✅ 已修复 |
| 31 | hand_approve hand_name 仅用于日志 | 添加 hand_id 匹配验证 + hand_cancel 同步修复 | ✅ 已修复 |
| 32 | scheduled_task 调度循环未实现 | 更新文档注释标注 PLANNNED | ✅ 已修复 |
**v5 审计后累计修复 32 项**，系统真实可用率 ~85%。孤立代码通过条件编译控制，不影响默认编译。

500
docs/features/FEATURE_AUDIT_REPORT.md
View File

@@ -1,500 +0,0 @@
# ZCLAW 功能完整性审计报告
> **ARCHIVED — 此报告已过时**
>
> 本报告审计于 2026-03-27，仅反映当时的代码状态。
> 截至 2026-03-28，SaaS 平台 (76+ API)、Admin 管理后台等大量功能已上线。
>
> **请参考最新文档** → [README.md](./README.md) | [DEEP_AUDIT_REPORT.md](./DEEP_AUDIT_REPORT.md)
>
> **原始审计信息:**
> **审计日期**: 2026-03-27
> **审计方法**: 五步审计流程 + 10 项通用审计清单
> **审计范围**: docs/features 目录下所有功能文档 vs 实际代码实现
---
## 一、审计摘要
### 1.1 总体完成度
| 分类 | 功能数 | 完整实现 | 部分实现 | 未实现 | 完成率 |
|------|--------|---------|---------|--------|------|
| 核心功能 | 3 | 3 | 0 | 0 | **100%** |
| 智能层 | 6 | 5 | 1 | 0 | **83%** |
| Skills 生态 | 2 | 1 | 1 | 0 | **50%** |
| Pipeline DSL | 1 | 1 | 0 | 0 | **100%** |
| 架构层 | 2 | 2 | 0 | 0 | **100%** |
| 上下文数据库 | 1 | 1 | 0 | 0 | **85%** |
| Hands 系统 | 11 | 9 | 0 | 2 | **82%** |
| **总计** | **26** | **22** | **2** | **2** | **85%** |
### 1.2 关键发现
1. **整体架构健康**: 核心功能完成度高，智能层已完全接入聊天流程
2. **主要差距**: 智能路由系统实现不完整，部分 Hands 未实现
3. **技术债务**: 39 处 `dead_code` 标记，需要评估是否启用或删除
---
## 二、功能详细审计
### 2.1 核心功能 (Core Features)
#### 聊天界面 (Chat Interface)
| 审计项 | 状态 | 说明 |
|--------|------|------|
| 代码存在性 | ✅ | ChatArea.tsx, chatStore.ts |
| 实现完整性 | ✅ | 流式响应、Markdown 渲染、多模型支持 |
| 调用链连通 | ✅ | UI → chatStore → KernelClient → Tauri 命令 |
| 配置传递 | ✅ | 模型配置通过 UI 设置页面完成 |
| 启动恢复 | ✅ | 从 localStorage 恢复配置 |
| 降级策略 | ✅ | 离线模式支持 |
| 数据流闭环 | ✅ | 消息发送 → 流式响应 → 记忆提取 |
| dead_code 清理 | ✅ | 无死代码 |
| 测试覆盖 | ✅ | 30+ 单元测试 |
**完成度**: **95%+** ✅ 生产就绪
---
#### Agent 分身 (Agent Clones)
| 审计项 | 状态 | 说明 |
|--------|------|------|
| 代码存在性 | ✅ | agentStore.ts, CloneManager.tsx |
| 实现完整性 | ✅ | CRUD 完整，SQLite 持久化 |
| 调用链连通 | ✅ | UI → agentStore → Tauri 命令 → zclaw-memory |
| 配置传递 | ✅ | Agent 配置正确存储和恢复 |
| 启动恢复 | ✅ | 从 SQLite 恢复 Agent 列表 |
| 降级策略 | ✅ | 默认 Agent 兜底 |
| 数据流闭环 | ✅ | 创建 → 存储 → 列表 → 切换 |
| dead_code 清理 | ✅ | 无死代码 |
| 测试覆盖 | ✅ | 20+ 单元测试 |
**完成度**: **90%+** ✅ 生产就绪
---
#### Hands 系统 (Hands System)
| 审计项 | 状态 | 说明 |
|--------|------|------|
| 代码存在性 | ✅ | handStore.ts, HandList.tsx, 11 个 HAND.toml |
| 实现完整性 | ⚠️ | 9/11 Rust 后端实现，Predictor/Lead 未实现 |
| 调用链连通 | ✅ | UI → handStore → KernelClient → HandRegistry |
| 配置传递 | ✅ | HAND.toml 正确解析 |
| 启动恢复 | ✅ | Kernel 启动时加载 Hands |
| 降级策略 | ✅ | 未实现的 Hand 显示为不可用 |
| 数据流闭环 | ✅ | 触发 → 审批 → 执行 → 结果 |
| dead_code 清理 | ⚠️ | browser/actions.rs, browser/error.rs, browser/session.rs 标记 dead_code |
| 测试覆盖 | ✅ | 10+ 单元测试 |
**完成度**: **64%** ⚠️ 需完善
**差距模式**: "写了没接" - Predictor 和 Lead 仅有配置文件，无 Rust 实现
---
### 2.2 智能层 (Intelligence Layer)
#### Agent 记忆 (Agent Memory)
| 审计项 | 状态 | 说明 |
|--------|------|------|
| 代码存在性 | ✅ | intelligence-client.ts, memory_commands.rs |
| 实现完整性 | ✅ | SQLite 存储、TF-IDF、Embedding 搜索、L0/L1/L2 |
| 调用链连通 | ✅ | chatStore.sendMessage → memory.buildContext |
| 配置传递 | ✅ | Embedding 配置正确传递到后端 |
| 启动恢复 | ✅ | App.tsx 恢复 Embedding 配置 |
| 降级策略 | ✅ | Embedding 不可用时降级到 TF-IDF |
| 数据流闭环 | ✅ | 存储 → 搜索 → 注入 system prompt |
| dead_code 清理 | ⚠️ | context_builder.rs, extractor.rs 标记 dead_code |
| 双系统一致性 | ⚠️ | SqliteStorage vs PersistentMemoryStore 功能不对等 |
| 测试覆盖 | ✅ | 42 单元测试 |
**完成度**: **95%+** ✅ 生产就绪
**差距模式**: "双系统不同步" - 两套存储系统功能不对等
---
#### 身份演化 (Identity Evolution)
| 审计项 | 状态 | 说明 |
|--------|------|------|
| 代码存在性 | ✅ | intelligence-client.ts, identity.rs |
| 实现完整性 | ✅ | SOUL.md 管理、人格预设、变更提案 |
| 调用链连通 | ✅ | chatStore.sendMessage → identity.buildPrompt |
| 配置传递 | ✅ | 人格预设正确配置 |
| 启动恢复 | ✅ | Agent 创建时生成 SOUL.md |
| 降级策略 | ✅ | 无 SOUL.md 时使用默认人格 |
| 数据流闭环 | ✅ | 创建 → 存储 → 构建 prompt → 注入对话 |
| dead_code 清理 | ⚠️ | identity.rs 部分方法标记 dead_code |
| 测试覆盖 | ✅ | 包含在 intelligence-client.test.ts |
**完成度**: **85%+** ✅ 生产就绪
**差距模式**: "写了没接" - persona_evolver.rs, mesh.rs, pattern_detector.rs, trigger_evaluator.rs 标记 dead_code
---
#### 自我反思引擎 (Reflection Engine)
| 审计项 | 状态 | 说明 |
|--------|------|------|
| 代码存在性 | ✅ | reflection-engine.ts, reflection.rs |
| 实现完整性 | ✅ | 规则模式检测、LLM 深度分析、改进建议生成 |
| 调用链连通 | ✅ | chatStore.onComplete → reflection.recordConversation |
| 配置传递 | ✅ | 反思配置正确传递 |
| 启动恢复 | ✅ | App 启动时初始化 |
| 降级策略 | ✅ | LLM 不可用时跳过反思 |
| 数据流闭环 | ✅ | 记录对话 → 检查触发 → 执行反思 → 生成建议 |
| dead_code 清理 | ⚠️ | reflection.rs 部分方法标记 dead_code |
| 测试覆盖 | ✅ | 包含在 reflection.test.ts |
**完成度**: **80%+** ✅ 生产就绪
---
#### 心跳巡检引擎 (Heartbeat Engine)
| 审计项 | 状态 | 说明 |
|--------|------|------|
| 代码存在性 | ✅ | heartbeat.rs, HeartbeatConfig.tsx |
| 实现完整性 | ✅ | 定时巡检、任务检查、反思触发 |
| 调用链连通 | ✅ | App.tsx → heartbeat.init → heartbeat.start |
| 配置传递 | ✅ | 心跳配置正确传递 |
| 启动恢复 | ✅ | App 启动时自动初始化 |
| 降级策略 | ✅ | 心跳失败时继续运行 |
| 数据流闭环 | ✅ | 初始化 → 启动 → 定时 tick → 生成提醒 |
| dead_code 清理 | ⚠️ | heartbeat.rs 部分方法保留用于 UI |
| 测试覆盖 | ✅ | 包含在 heartbeat.test.ts |
**完成度**: **90%+** ✅ 生产就绪
---
#### 自主授权 (Autonomy Manager)
| 审计项 | 状态 | 说明 |
|--------|------|------|
| 代码存在性 | ✅ | autonomy-manager.ts, AutonomyConfig.tsx |
| 实现完整性 | ✅ | 三级自主级别、风险分级、审批流程 |
| 调用链连通 | ✅ | 各系统调用 canAutoExecute 检查授权 |
| 配置传递 | ✅ | 自主级别配置正确存储 |
| 启动恢复 | ✅ | 从 localStorage 恢复配置 |
| 降级策略 | ✅ | 高风险操作始终需要确认 |
| 数据流闭环 | ✅ | 操作请求 → 风险评估 → 授权检查 → 执行 |
| dead_code 清理 | ✅ | 无死代码 |
| 测试覆盖 | ✅ | 包含在 autonomy-manager.test.ts |
**完成度**: **95%+** ✅ 生产就绪
---
#### 上下文压缩 (Context Compaction)
| 审计项 | 状态 | 说明 |
|--------|------|------|
| 代码存在性 | ✅ | compactor.rs, intelligence-client.ts |
| 实现完整性 | ⚠️ | Token 估算、规则摘要已实现；LLM 摘要未实现 |
| 调用链连通 | ✅ | 内核 AgentLoop 集成 (15k token 阈值) |
| 配置传递 | ✅ | 压缩配置正确传递 |
| 启动恢复 | ✅ | 使用默认配置 |
| 降级策略 | ✅ | LLM 不可用时使用规则摘要 |
| 数据流闭环 | ✅ | 检查阈值 → 压缩 → 生成摘要 → 替换消息 |
| dead_code 清理 | ⚠️ | compactor.rs 标记 dead_code (完整版未启用) |
| 测试覆盖 | ✅ | 包含在 compactor.test.ts |
**完成度**: **85%+** ✅ 生产就绪
**差距模式**: "写了没接" - LLM 摘要生成 (use_llm: true) 未实现
---
### 2.3 Skills 生态 (Skills Ecosystem)
#### Skill 系统 (Skill System)
| 审计项 | 状态 | 说明 |
|--------|------|------|
| 代码存在性 | ✅ | skill-discovery.ts, SkillRegistry (Rust) |
| 实现完整性 | ⚠️ | 78+ SKILL.md、动态扫描、execute_skill 已实现；WASM/Native 模式未实现 |
| 调用链连通 | ✅ | Kernel → SkillRegistry → skill_list/skill_refresh |
| 配置传递 | ✅ | skills_dir 配置正确传递 |
| 启动恢复 | ✅ | Kernel 启动时扫描 skills 目录 |
| 降级策略 | ✅ | PromptOnly 模式作为默认 |
| 数据流闭环 | ✅ | 扫描 → 注册 → 列表 → 执行 |
| dead_code 清理 | ✅ | 无死代码 |
| 测试覆盖 | ✅ | 50+ 单元测试 |
**完成度**: **80%+** ✅ 生产就绪
**差距模式**: "写了没接" - WASM/Native 执行模式、Schema 验证未实现
---
#### 智能路由 (Intelligent Routing)
| 审计项 | 状态 | 说明 |
|--------|------|------|
| 代码存在性 | ⚠️ | 仅有设计文档，无完整实现 |
| 实现完整性 | ⚠️ | 系统提示词注入技能列表已实现；语义路由器未实现 |
| 调用链连通 | ❌ | 无 Embedding 索引，无 LLM 决策 |
| 配置传递 | ❌ | 无配置传递 |
| 启动恢复 | ❌ | 无启动恢复 |
| 降级策略 | ❌ | 无降级策略 |
| 数据流闭环 | ❌ | 仅完成 40% |
| dead_code 清理 | N/A | 无代码 |
| 测试覆盖 | ❌ | 无测试 |
**完成度**: **40%+** ⚠️ 需完善
**差距模式**: "写了没接" - 设计文档完整，实现仅完成 40%
---
### 2.4 Pipeline DSL
#### Pipeline 系统
| 审计项 | 状态 | 说明 |
|--------|------|------|
| 代码存在性 | ✅ | pipeline-client.ts, zclaw-pipeline crate |
| 实现完整性 | ✅ | YAML 解析、执行引擎、状态管理、9 种 Action |
| 调用链连通 | ✅ | PipelinesPanel → pipeline-client → Tauri 命令 |
| 配置传递 | ✅ | Pipeline 配置正确解析 |
| 启动恢复 | ✅ | Kernel 启动时加载 Pipeline |
| 降级策略 | ✅ | 错误时停止执行 |
| 数据流闭环 | ✅ | 解析 → 执行 → 状态更新 → 结果 |
| dead_code 清理 | ✅ | 无死代码 |
| 测试覆盖 | ✅ | 包含在 pipeline.test.ts |
**完成度**: **90%+** ✅ 生产就绪
---
### 2.5 架构层 (Architecture)
#### 通信层 (Communication Layer)
| 审计项 | 状态 | 说明 |
|--------|------|------|
| 代码存在性 | ✅ | kernel-client.ts, gateway-client.ts |
| 实现完整性 | ✅ | 80+ Tauri 命令、双客户端模式 |
| 调用链连通 | ✅ | UI → Store → Client → Tauri 命令 |
| 配置传递 | ✅ | 模型配置正确传递 |
| 启动恢复 | ✅ | 从 localStorage 恢复配置 |
| 降级策略 | ✅ | 离线模式支持 |
| 数据流闭环 | ✅ | 连接 → 配置 → 调用 → 响应 |
| dead_code 清理 | ⚠️ | llm/mod.rs 部分方法标记 dead_code |
| 测试覆盖 | ✅ | 85% 覆盖率 |
**完成度**: **95%+** ✅ 生产就绪
---
#### 状态管理 (State Management)
| 审计项 | 状态 | 说明 |
|--------|------|------|
| 代码存在性 | ✅ | 18+ Zustand Store |
| 实现完整性 | ✅ | 持久化中间件、依赖注入、跨 Store 通信 |
| 调用链连通 | ✅ | 组件 → Store → Client |
| 配置传递 | ✅ | Store 配置正确传递 |
| 启动恢复 | ✅ | 从 localStorage 恢复状态 |
| 降级策略 | ✅ | 默认状态兜底 |
| 数据流闭环 | ✅ | 状态更新 → 持久化 → 恢复 |
| dead_code 清理 | ✅ | 无死代码 |
| 测试覆盖 | ✅ | 85% 覆盖率 |
**完成度**: **95%+** ✅ 生产就绪
---
### 2.6 上下文数据库 (Context Database)
#### OpenViking 集成
| 审计项 | 状态 | 说明 |
|--------|------|------|
| 代码存在性 | ✅ | viking-client.ts, viking_commands.rs |
| 实现完整性 | ✅ | 本地/远程/存储三种模式、L0/L1/L2 分层 |
| 调用链连通 | ✅ | VikingPanel → viking-client → Tauri 命令 |
| 配置传递 | ✅ | Embedding 配置正确传递 |
| 启动恢复 | ✅ | App.tsx 恢复 Embedding 配置 |
| 降级策略 | ✅ | 无 OpenViking 时使用本地存储 |
| 数据流闭环 | ✅ | 添加 → 存储 → 搜索 → 读取 |
| dead_code 清理 | ✅ | 无死代码 |
| 测试覆盖 | ✅ | 85% 覆盖率 |
**完成度**: **85%+** ✅ 生产就绪
---
## 三、差距模式汇总
### 3.1 "写了没接" (Code exists but not integrated)
| 功能/模块 | 文件位置 | 差距描述 | 优先级 |
|-----------|----------|----------|--------|
| Predictor Hand | hands/predictor.HAND.toml | 仅有配置文件，无 Rust 实现 | P2 |
| Lead Hand | hands/lead.HAND.toml | 仅有配置文件，无 Rust 实现 | P2 |
| 智能路由 | docs/features/04-skills-ecosystem/01-intelligent-routing.md | 设计文档完整，实现仅 40% | P1 |
| LLM 摘要生成 | compactor.rs | use_llm: true 配置存在但未实现 | P2 |
| 增量压缩 | compactor.rs | 设计了但未启用 | P3 |
| 压缩预览 | compactor.rs | 设计了但未实现 | P3 |
| persona_evolver.rs | desktop/src-tauri/src/intelligence/ | 完整实现但标记 dead_code | P2 |
| mesh.rs | desktop/src-tauri/src/intelligence/ | 完整实现但标记 dead_code | P2 |
| pattern_detector.rs | desktop/src-tauri/src/intelligence/ | 完整实现但标记 dead_code | P2 |
| trigger_evaluator.rs | desktop/src-tauri/src/intelligence/ | 完整实现但标记 dead_code | P2 |
| validation.rs | desktop/src-tauri/src/intelligence/ | 完整实现但标记 dead_code | P3 |
| context_builder.rs | desktop/src-tauri/src/memory/ | 完整实现但标记 dead_code | P2 |
| WASM 执行模式 | zclaw-skills/src/executor.rs | 设计了但未实现 | P3 |
| Native 执行模式 | zclaw-skills/src/executor.rs | 设计了但未实现 | P3 |
| Schema 验证 | zclaw-skills/src/executor.rs | 解析但未验证 | P3 |
### 3.2 "双系统不同步" (Dual systems not synchronized)
| 系统 | 文件位置 | 差距描述 | 优先级 |
|------|----------|----------|--------|
| SqliteStorage vs PersistentMemoryStore | crates/zclaw-growth vs desktop/src-tauri/src/memory | FTS5/TF-IDF: SqliteStorage 有，PersistentMemoryStore 无 | P1 |
| L0/L1 生成 | crates/zclaw-growth | SqliteStorage 有，PersistentMemoryStore 无 | P1 |
| 导出/导入 | desktop/src-tauri/src/memory | SqliteStorage 无，PersistentMemoryStore 有 | P2 |
### 3.3 "存了没用" (Stored but not used)
| 数据/字段 | 文件位置 | 差距描述 | 优先级 |
|-----------|----------|----------|--------|
| overview 字段 | MemoryEntry | 存储了但搜索时未返回 | P2 |
| L0/L1/L2 渐进加载 | context_builder.rs | 实现了但未启用完整版 | P2 |
---
## 四、dead_code 清理建议
### 4.1 建议启用 (Ready to enable)
| 模块 | 文件 | 理由 |
|------|------|------|
| context_builder.rs | memory/context_builder.rs | 完整的 L0→L1→L2 渐进加载，可提升记忆检索质量 |
| persona_evolver.rs | intelligence/persona_evolver.rs | 人格演化核心功能，可增强 Agent 自我进化能力 |
| pattern_detector.rs | intelligence/pattern_detector.rs | 模式检测是智能化的基础 |
### 4.2 建议保留 (Keep as reserved)
| 模块 | 文件 | 理由 |
|------|------|------|
| heartbeat.rs 部分方法 | intelligence/heartbeat.rs | 保留用于 UI 状态显示 |
| compactor.rs 完整版 | intelligence/compactor.rs | 保留用于未来高级压缩功能 |
| validation.rs | intelligence/validation.rs | 保留用于未来 API 验证 |
### 4.3 建议删除 (Consider removing)
| 模块 | 文件 | 理由 |
|------|------|------|
| browser/actions.rs | browser/actions.rs | 如果不计划使用，可删除减少维护负担 |
| browser/error.rs | browser/error.rs | 如果不计划使用，可删除减少维护负担 |
| browser/session.rs | browser/session.rs | 如果不计划使用，可删除减少维护负担 |
---
## 五、优先修复建议
### 5.1 P0 - 阻塞性问题 (立即修复)
无阻塞性问题
### 5.2 P1 - 重要问题 (1-2 周内修复)
| 问题 | 影响 | 修复建议 |
|------|------|----------|
| 智能路由未完成 | 技能匹配精度低 | 实现 SemanticSkillRouter，完成 Embedding 索引 + LLM 决策 |
| 双存储系统不一致 | 功能不对等 | 统一为一套存储系统，或在 PersistentMemoryStore 补齐缺失能力 |
| context_builder.rs 未启用 | 记忆检索质量低 | 启用完整版 L0→L1→L2 渐进加载 |
### 5.3 P2 - 中等问题 (1-2 月内修复)
| 问题 | 影响 | 修复建议 |
|------|------|----------|
| Predictor/Lead Hand 未实现 | 功能缺失 | 实现 Rust 后端或从文档中移除 |
| LLM 摘要未实现 | 压缩质量有限 | 实现 LLM 驱动摘要生成 |
| persona_evolver.rs 未启用 | Agent 演化能力受限 | 启用并集成到反思流程 |
| mesh.rs 未启用 | 多 Agent 协作受限 | 评估是否需要，如需要则启用 |
### 5.4 P3 - 低优先级 (后续迭代)
| 问题 | 影响 | 修复建议 |
|------|------|----------|
| WASM/Native 执行模式 | 扩展性 | 按需实现 |
| Schema 验证 | 数据质量 | 完善验证逻辑 |
| 增量压缩/压缩预览 | 用户体验 | 按需实现 |
---
## 六、测试覆盖分析
### 6.1 测试覆盖良好的模块
| 模块 | 测试数量 | 覆盖率 |
|------|---------|--------|
| chatStore | 42 tests | ~85% |
| gatewayStore | 35 tests | ~85% |
| agent-memory | 42 tests | ~95% |
| reflection-engine | 包含在 intelligence | ~80% |
| pipeline | 包含在 pipeline.test | ~90% |
### 6.2 测试覆盖不足的模块
| 模块 | 当前状态 | 建议 |
|------|---------|------|
| embedding_adapter.rs | 无测试 | 添加单元测试 |
| memory_commands.rs | 无测试 | 添加集成测试 |
| persistent.rs | 仅 1 个测试 | 扩展测试覆盖 |
| 端到端 embedding + 搜索 | 无测试 | 添加 E2E 测试 |
| 端到端 L0/L1 生成 | 无测试 | 添加 E2E 测试 |
| 智能路由 | 无测试 | 添加测试 |
---
## 七、审计结论
### 7.1 总体评估
ZCLAW 项目整体功能完成度较高 (**85%+**)，核心功能已完全实现并集成。主要差距集中在：
1. **智能路由系统** - 设计完整但实现仅 40%
2. **双存储系统不一致** - SqliteStorage 和 PersistentMemoryStore 功能不对等
3. **部分 Hands 未实现** - Predictor 和 Lead 仅有配置文件
4. **大量 dead_code 模块** - 需要评估是否启用或删除
### 7.2 建议优先级
1. **立即**: 完成智能路由系统实现
2. **短期**: 统一双存储系统或补齐功能
3. **中期**: 实现 Predictor/Lead Hand 或移除文档
4. **持续**: 清理 dead_code，评估是否启用或删除
### 7.3 风险提示
- **技术债务**: 39 处 dead_code 标记需要定期评估
- **测试覆盖**: 部分 E2E 测试缺失，建议补充
- **文档一致性**: 部分功能文档与实现不同步，需要更新
---
## 附录：审计命令速查
```bash
# 搜索 dead_code 标记
rg "allow\(dead_code\)" --type rust
# 搜索未使用的函数
rg "#\[allow(dead_code)\]" crates/ desktop/src-tauri/src/
# 搜索未注册的 Tauri 命令
rg "#\[tauri::command\]" desktop/src-tauri/src/ -l
# 对比 lib.rs 中的 .invoke_handler() 注册列表
# 搜索前端 invoke 调用
rg "invoke\(" desktop/src/ --type ts -l
# 编译检查
cargo check 2>&1 | grep -i "warning\|error"
# 测试
cargo test -p zclaw-growth 2>&1 | tail -5
```
---
**审计人**: Claude AI Agent
**审计日期**: 2026-03-27
**下次审计建议**: 3 个月后或重大版本发布前

324
docs/features/FRONTEND_INTEGRATION_AUDIT.md
View File

@@ -1,324 +0,0 @@
# 前端集成审计报告
> **ARCHIVED — 此报告已过时**
>
> 本报告审计于 2026-03-17，仅反映当时的前端集成状态。
> 截至 2026-03-28，SaaS 集成、Admin 管理后台、TOTP 2FA 等大量前端功能已上线。
>
> **请参考最新文档** → [README.md](./README.md) | [DEEP_AUDIT_REPORT.md](./DEEP_AUDIT_REPORT.md)
>
> **原始审计信息:**
> **审计日期**: 2026-03-17
> **审计范围**: docs/features 目录下所有功能文档 vs 实际前端代码实现
> **审计目的**: 验证功能文档声称的"已实现"是否真正集成到前端 UI
---
## 一、审计摘要
| 分类 | 文档声称成熟度 | 实际集成状态 | 差异等级 |
|------|---------------|-------------|---------|
| 架构层 | L4 | ✅ 已集成 | 无 |
| 核心功能 | L3-L4 | ⚠️ 部分集成 | 中 |
| 智能层 | L4 | ❌ 大部分未集成 | 高 |
| 上下文数据库 | L3-L4 | ⚠️ 部分集成 | 中 |
| Skills 生态 | L4 | ❌ 未集成 | 高 |
| Hands 系统 | L3 | ✅ 已集成 | 低 |
| Tauri 后端 | L4 | ✅ 已集成 | 无 |
---
## 二、详细审计结果
### 2.1 架构层 (Architecture)
| 功能 | 文档 | 实际状态 | 集成位置 |
|------|------|---------|---------|
| 通信层 | L4 已完成 | ✅ 已集成 | `gateway-client.ts`, `tauri-gateway.ts` |
| 状态管理 | L4 已完成 | ✅ 已集成 | `store/*.ts` (13个store文件) |
| 安全认证 | L4 已完成 | ✅ 已集成 | `gatewayStore.ts`, Tauri commands |
**结论**: 架构层文档准确，功能已正确集成。
---
### 2.2 核心功能 (Core Features)
| 功能 | 文档声称 | 实际状态 | 问题 |
|------|---------|---------|------|
| Chat 界面 | L4 已完成 | ✅ 已集成 | `ChatArea.tsx` 正常工作 |
| Agent 分身 | L4 已完成 | ✅ 已集成 | `CloneManager.tsx` + `agentStore.ts` |
| Hands 系统 | L3 成熟 | ✅ 已集成 | 见 2.6 节详细分析 |
| 工作流引擎 | L3 成熟 | ⚠️ 部分集成 | **问题见下方** |
| 团队协作 | L3 成熟 | ✅ 已集成 | `TeamList.tsx` + `TeamCollaborationView.tsx` |
| 多 Agent 协作 | L4 已完成 | ✅ 已集成 | `SwarmDashboard.tsx` |
#### Workflow 系统问题
**文档声称**:
- WorkflowEditor 可视化编辑器
- WorkflowHistory 执行历史
- 多步骤工作流编排
**实际代码**:
```
✅ WorkflowList.tsx - 已集成到 Sidebar
✅ workflowStore.ts - 完整状态管理
✅ SchedulerPanel.tsx - 已集成到 App.tsx
❌ WorkflowEditor.tsx - 存在但未集成到任何视图
❌ WorkflowHistory.tsx - 存在但未集成到任何视图
```
**结论**: Workflow 编辑器和历史组件存在代码但未集成到 UI。
---
### 2.3 智能层 (Intelligence Layer) - ✅ 已集成 (2026-03-17 更新)
| 功能 | 文档声称 | 实际状态 | 问题 |
|------|---------|---------|------|
| Agent 记忆 | L4 已完成 | ✅ 已集成 | `MemoryPanel.tsx` 在 RightPanel 'memory' tab |
| 身份演化 | L4 已完成 | ❓ 未验证 | 需检查后端实现 |
| 上下文压缩 | L4 已完成 | ❓ 未验证 | `context-compactor.ts` 存在 |
| 自我反思 | L4 已完成 | ✅ **已集成** | `ReflectionLog.tsx` 在 RightPanel 'reflection' tab |
| 心跳巡检 | L4 已完成 | ❓ 未验证 | `heartbeat-engine.ts` 存在 |
| 自主授权 | L4 已完成 | ✅ **已集成** | `AutonomyConfig.tsx` 在 RightPanel 'autonomy' tab |
#### 已集成的智能层组件
```
✅ MemoryPanel.tsx - 集成到 RightPanel 'memory' tab
✅ ReflectionLog.tsx - 集成到 RightPanel 'reflection' tab (2026-03-17)
✅ AutonomyConfig.tsx - 集成到 RightPanel 'autonomy' tab (2026-03-17)
✅ ActiveLearningPanel.tsx - 集成到 RightPanel 'learning' tab (2026-03-17)
```
**相关 lib 文件**:
```
✅ agent-memory.ts - 已被 MemoryPanel 使用
✅ reflection-engine.ts - 已被 ReflectionLog 使用
✅ autonomy-manager.ts - 已被 AutonomyConfig 使用
✅ active-learning.ts - 已被 ActiveLearningPanel 使用
✅ vector-memory.ts - 存在但未被 UI 使用
```
**结论**: 智能层核心组件已全部完成前端集成。
---
### 2.4 上下文数据库 (Context Database)
| 功能 | 文档声称 | 实际状态 | 问题 |
|------|---------|---------|------|
| OpenViking 集成 | L4 已完成 | ⚠️ 部分集成 | lib 存在，集成不完整 |
| 向量记忆 | L3 成熟 | ❌ 未集成 | `vector-memory.ts` 存在但未使用 |
| 会话持久化 | L4 已完成 | ✅ 已集成 | `session-persistence.ts` |
| 记忆提取 | L4 已完成 | ❓ 未验证 | `memory-extractor.ts` 存在 |
#### OpenViking 相关文件
```
✅ viking-client.ts - 存在
✅ viking-adapter.ts - 存在
✅ viking-local.ts - 存在
✅ viking-memory-adapter.ts - 存在
✅ viking-server-manager.ts - 存在
❓ 需验证这些是否被实际使用
```
---
### 2.5 Skills 生态 - ✅ 已集成 (2026-03-17 更新)
| 功能 | 文档声称 | 实际状态 | 问题 |
|------|---------|---------|------|
| Skill 系统概述 | L4 已完成 | ✅ 已集成 | SkillMarket 已集成到 Sidebar/App |
| 内置技能 (74个) | L4 已完成 | ❓ 未验证 | 需检查后端 |
| 技能发现 | L4 已完成 | ✅ **已集成** | SkillMarket 组件已使用 |
#### 已集成的 Skills 组件
```
✅ SkillMarket.tsx - 集成到 Sidebar 'skills' tab 和 App.tsx main view (2026-03-17)
✅ Settings/Skills.tsx - 已集成到设置页
```
**相关文件**:
```
✅ skill-discovery.ts - 已被 SkillMarket 使用
✅ skillMarketStore.ts - 存在
```
---
### 2.6 Hands 系统
| 功能 | 文档声称 | 实际状态 | 问题 |
|------|---------|---------|------|
| Hands 概述 (7个) | L3 成熟 | ✅ 已集成 | 完整实现 |
#### 已集成的 Hands 组件
```
✅ HandList.tsx - 集成到 Sidebar
✅ HandsPanel.tsx - 完整的 Hands 管理面板
✅ HandTaskPanel.tsx - 集成到 App.tsx
✅ HandParamsForm.tsx - ✅ 已集成到 HandsPanel 触发流程 (2026-03-17)
✅ HandApprovalModal.tsx - ✅ 已集成到 App.tsx 全局审批 (2026-03-17)
✅ BrowserHand/* - Browser Hand 专用组件
✅ handStore.ts - 完整状态管理
✅ browserHandStore.ts - Browser Hand 状态
```
**结论**: Hands 系统文档准确，功能已完整集成，包括参数表单和审批弹窗。
---
### 2.7 Tauri 后端
| 功能 | 文档声称 | 实际状态 | 问题 |
|------|---------|---------|------|
| ZCLAW 集成 | L4 已完成 | ✅ 已集成 | `tauri-gateway.ts` |
| 安全存储 | L4 已完成 | ✅ 已集成 | `secure-storage.ts` |
| 本地 Gateway | L4 已完成 | ✅ 已集成 | 自动启动逻辑 |
---
## 三、存在但未集成的组件清单
以下组件存在于 `desktop/src/components/` 但**未**被渲染到任何视图：
| 组件 | 文件 | 功能 | 严重程度 |
|------|------|------|---------|
| ~~WorkflowEditor~~ | ~~`WorkflowEditor.tsx`~~ | ~~工作流可视化编辑~~ | ✅ 已集成 |
| ~~WorkflowHistory~~ | ~~`WorkflowHistory.tsx`~~ | ~~执行历史查看~~ | ✅ 已集成 |
| ~~ReflectionLog~~ | ~~`ReflectionLog.tsx`~~ | ~~自我反思日志~~ | ✅ 已集成 |
| ~~AutonomyConfig~~ | ~~`AutonomyConfig.tsx`~~ | ~~自主授权配置~~ | ✅ 已集成 |
| ~~ActiveLearningPanel~~ | ~~`ActiveLearningPanel.tsx`~~ | ~~主动学习面板~~ | ✅ 已集成 |
| ~~SkillMarket~~ | ~~`SkillMarket.tsx`~~ | ~~技能市场~~ | ✅ 已集成 |
| ~~SkillCard~~ | ~~`SkillMarket/SkillCard.tsx`~~ | ~~技能卡片~~ | ✅ 已集成 |
| ~~MemoryGraph~~ | ~~`MemoryGraph.tsx`~~ | ~~记忆图谱可视化~~ | ✅ 已集成到 RightPanel memory tab |
| ~~AuditLogsPanel~~ | ~~`AuditLogsPanel.tsx`~~ | ~~审计日志面板~~ | ✅ 已集成 |
| ~~SecurityLayersPanel~~ | ~~`SecurityLayersPanel.tsx`~~ | ~~安全层面板~~ | ✅ 已集成 |
| ~~TriggersPanel~~ | ~~`TriggersPanel.tsx`~~ | ~~触发器管理~~ | ✅ 已集成到 SchedulerPanel triggers tab |
| ~~ApprovalsPanel~~ | ~~`ApprovalsPanel.tsx`~~ | ~~审批管理面板~~ | ✅ 已集成到 HandsPanel approvals tab |
| ~~TeamOrchestrator~~ | ~~`TeamOrchestrator.tsx`~~ | ~~团队编排器~~ | ✅ 已集成到 App team view orchestrator tab |
| ~~SecurityStatus~~ | ~~`SecurityStatus.tsx`~~ | ~~安全状态显示~~ | ✅ 已集成 |
| HeartbeatConfig | `HeartbeatConfig.tsx` | 心跳配置 | 低 |
| CreateTriggerModal | `CreateTriggerModal.tsx` | 创建触发器弹窗 | 低 |
| ~~FeedbackButton~~ | ~~`Feedback/FeedbackButton.tsx`~~ | ~~反馈按钮~~ | ✅ 已集成到 SettingsLayout |
| ~~FeedbackHistory~~ | ~~`Feedback/FeedbackHistory.tsx`~~ | ~~反馈历史~~ | ✅ 已集成到 SettingsLayout |
| ~~FeedbackModal~~ | ~~`Feedback/FeedbackModal.tsx`~~ | ~~反馈弹窗~~ | ✅ 已集成到 SettingsLayout |
| ~~MessageSearch~~ | ~~`MessageSearch.tsx`~~ | ~~消息搜索~~ | ✅ Sidebar 已有搜索功能 |
| ~~MemoryGraph~~ | ~~`MemoryGraph.tsx`~~ | ~~记忆图谱可视化~~ | ✅ 已集成到 RightPanel memory tab |
| PersonalitySelector | `PersonalitySelector.tsx` | 个性选择器 | 低 |
| ScenarioTags | `ScenarioTags.tsx` | 场景标签 | 低 |
| BrowserHand/* | `BrowserHand/*.tsx` | Browser Hand 组件 | ✅ 已被 HandsPanel 使用 |
| DevQALoop | `DevQALoop.tsx` | 开发 QA 循环 | 低 (开发工具) |
---
## 四、存在但未使用的 lib 文件
以下 lib 文件存在但**未**被 UI 组件直接使用：
| 文件 | 功能 | 状态 |
|------|------|------|
| `reflection-engine.ts` | 自我反思引擎 | ✅ 已被 ReflectionLog 使用 |
| `autonomy-manager.ts` | 自主授权管理 | ✅ 已被 AutonomyConfig 使用 |
| `active-learning.ts` | 主动学习 | ✅ 已被 ActiveLearningPanel 使用 |
| `vector-memory.ts` | 向量记忆 | ❌ 未被 UI 使用 |
| `memory-extractor.ts` | 记忆提取 | ❓ 需验证 |
| `memory-index.ts` | 记忆索引 | ❓ 需验证 |
| `context-compactor.ts` | 上下文压缩 | ❓ 需验证 |
| `heartbeat-engine.ts` | 心跳巡检引擎 | ❓ 需验证 |
| `agent-swarm.ts` | Agent 蜂群 | ❓ 需验证 |
| `skill-discovery.ts` | 技能发现 | ✅ 已被 SkillMarket 使用 |
---
## 五、建议修复优先级
### P0 - 紧急 (影响核心价值) - ✅ 全部完成
1. ~~**集成智能层组件**~~ - ✅ **已完成 (2026-03-17)**
- ~~`ReflectionLog.tsx` → 添加到 RightPanel 或新 tab~~ - ✅ 已集成
- ~~`AutonomyConfig.tsx` → 添加到设置页或 RightPanel~~ - ✅ 已集成
- ~~`ActiveLearningPanel.tsx` → 添加到 RightPanel~~ - ✅ 已集成
2. ~~**集成 Skills 市场**~~ - ✅ **已完成 (2026-03-17)**
- ~~`SkillMarket.tsx` → 添加为新视图或 Sidebar tab~~ - ✅ 已集成
### P1 - 重要 (完善用户体验) - ✅ 全部完成
3. ~~**集成 Workflow 编辑器**~~ - ✅ **已完成 (2026-03-17)**
- ~~`WorkflowEditor.tsx` → 集成到 workflow 视图~~ - ✅ 已集成到 SchedulerPanel workflows tab
- ~~`WorkflowHistory.tsx` → 集成到 workflow 视图~~ - ✅ 已集成到 SchedulerPanel workflows tab
4. ~~**集成安全与审计**~~ - ✅ **已完成 (2026-03-17)**
- ~~`AuditLogsPanel.tsx` → 添加到设置页~~ - ✅ 已集成到 SettingsLayout 'audit' page
- ~~`SecurityLayersPanel.tsx` → 添加到设置页~~ - ✅ 已集成到 SettingsLayout 'security' page
5. ~~**集成 Hands 参数表单和审批弹窗**~~ - ✅ **已完成 (2026-03-17)**
- ~~`HandParamsForm.tsx` → 集成到 HandsPanel 触发流程~~ - ✅ 已集成
- ~~`HandApprovalModal.tsx` → 集成到 App.tsx 全局监听~~ - ✅ 已集成
### P2 - 增强 (锦上添花) - ✅ MemoryGraph、TriggersPanel 已完成
5. **集成其他组件**
- ~~`TriggersPanel.tsx` → 添加到 workflow 视图~~ - ✅ 已集成到 SchedulerPanel (2026-03-18)
- `ApprovalsPanel.tsx` → 添加到 hands 视图
- ~~`MemoryGraph.tsx` → 添加到 memory tab~~ - ✅ 已集成 (2026-03-18)
- `MessageSearch.tsx` → 添加到 ChatArea
---
## 六、文档更新建议
以下文档需要更新以反映实际状态：
| 文档 | 当前声称 | 建议更新 |
|------|---------|---------|
| `02-intelligence-layer/03-reflection-engine.md` | L4 已完成 | ✅ 已更新为 L4 已集成 |
| `02-intelligence-layer/05-autonomy-manager.md` | L4 已完成 | ✅ 已更新为 L4 已集成 |
| `04-skills-ecosystem/00-skill-system.md` | L4 已完成 | ✅ 已更新为 L4 已集成 |
---
## 七、总结
### 实际情况 vs 文档描述
| 指标 | 文档声称 | 实际状态 |
|------|---------|---------|
| 整体成熟度 | 大部分 L4 | ✅ L4 已集成 |
| 智能层 | L4 生产级 | ✅ L4 已集成 (2026-03-17) |
| Skills 生态 | L4 生产级 | ✅ L4 已集成 (2026-03-17) |
| Hands 系统 | L3 成熟 | ✅ 准确 |
| 核心功能 | L3-L4 | ✅ 准确 |
### 核心发现
1. **Hands 系统文档准确** - 声称的功能确实已完整集成，包括参数表单和审批弹窗
2. **智能层已完成集成** - ✅ 反思引擎、自主授权、主动学习已集成到 RightPanel (2026-03-17)
3. **Skills 市场已集成** - ✅ SkillMarket 已集成到 Sidebar/App (2026-03-17)
4. **Hands 参数和审批已集成** - ✅ HandParamsForm 和 HandApprovalModal 已集成 (2026-03-17)
5. **Workflow 编辑器已集成** - ✅ WorkflowEditor 和 WorkflowHistory 已集成到 SchedulerPanel (2026-03-17)
6. **安全与审计已集成** - ✅ AuditLogsPanel 和 SecurityLayersPanel 已集成到 SettingsLayout (2026-03-17)
7. **记忆图谱已集成** - ✅ MemoryGraph 已集成到 RightPanel memory tab (2026-03-18)
8. **触发器面板已集成** - ✅ TriggersPanel 已集成到 SchedulerPanel triggers tab (2026-03-18)
9. **审批面板已集成** - ✅ ApprovalsPanel 已集成到 HandsPanel approvals tab (2026-03-18)
10. **团队编排器已集成** - ✅ TeamOrchestrator 已集成到 App team view orchestrator tab (2026-03-18)
11. **所有组件已集成** - ✅ 无剩余"僵尸组件"
### 建议行动
1. ~~**立即**: 更新文档成熟度评级，反映实际集成状态~~ - ✅ 已完成
2. ~~**短期**: 集成 SkillMarket 和 ActiveLearningPanel~~ - ✅ 已完成 (2026-03-17)
3. ~~**短期**: 集成 HandParamsForm 和 HandApprovalModal~~ - ✅ 已完成 (2026-03-17)
4. ~~**中期**: 集成 Workflow Editor/History 和 安全/审计组件~~ - ✅ 已完成 (2026-03-17)
5. ~~**中期**: 集成 MemoryGraph~~ - ✅ 已完成 (2026-03-18)
6. ~~**中期**: 集成 TriggersPanel~~ - ✅ 已完成 (2026-03-18)
7. ~~**中期**: 集成 ApprovalsPanel~~ - ✅ 已完成 (2026-03-18)
8. ~~**中期**: 集成 TeamOrchestrator~~ - ✅ 已完成 (2026-03-18)
9. **长期**: 建立文档-代码同步机制，避免文档过时

180
docs/features/JOINT_DEBUG_REPORT_V1.md
View File

@@ -1,180 +0,0 @@
# SaaS + Tauri 联合调试测试报告
> **ARCHIVED — 此报告已过时**
>
> 本报告记录 2026-03-28 的联合调试结果。相关修复已全部合并。
>
> **请参考最新文档** → [README.md](./README.md) | [00-saas-overview.md](./08-saas-platform/00-saas-overview.md)
> **测试日期**: 2026-03-28 (原文标注有误)
> **测试环境**: Windows 11 + PostgreSQL 17 + Rust SaaS @ 127.0.0.1:8080
> **测试范围**: SaaS 后端 API + Tauri 桌面端集成层 + Admin 前端
---
## 一、测试执行摘要
| 阶段 | 用例数 | 通过 | 失败 | 发现 | 状态 |
|------|--------|------|------|------|------|
| P0 安全 | 2 | 2 | 0 | 0 | ✅ 已修复验证 |
| A 类功能 | 15 | 13 | 1 | 1 | ✅ models 已修复 |
| B 类数据 | 5 | 3 | 1 | 1 | ⚠ 部分验证 |
| C 类流程 | 5 | N/A | N/A | N/A | ⏸ 服务中断 |
| D 类异常 | 7 | N/A | N/A | N/A | ⚸ 服务中断 |
| Admin 专项 | 2 | 2 | 0 | 0 | ✅ 已修复 |
**总计**: 36 个测试用例, 20 通过, 2 失败, 2 新发现, 12 未执行
---
## 二、已确认通过的测试 (20/36)
### P0 安全修复 — 全部通过 ✅
| ID | 测试项 | 结果 | 详情 |
|----|--------|------|------|
| T-CRIT-01 | `sync_config` 权限检查 | **PASS** | user 角色 → 403 "权限不足: 需要 config:write 权限" |
| T-CRIT-02 | `/api/health` 端点 | **PASS** | 返回 "ok", HTTP 200 |
### A 类功能模块 — 13/15 通过
| ID | 测试项 | 结果 | 详情 |
|----|--------|------|------|
| A-01 | 用户注册 | **PASS** | 201 Created, 返回完整 AccountPublic |
| A-01b | 重复注册 | **PASS** | 409 CONFLICT |
| A-02 | 正确密码登录 | **PASS** | 200 + JWT token + account |
| A-02b | 错误密码登录 | **PASS** | 401 AUTH_ERROR |
| A-02c | GET /auth/me | **PASS** | 返回完整用户信息 |
| A-02d | Token 刷新 | **PASS** | 200 + 新 JWT token |
| A-04a | user 创建 Provider | **PASS** | 403 "权限不足: 需要 provider:manage 权限" |
| A-04b | ~~GET /models~~ | **FAIL→FIXED** | 原 500 (SQL参数错误), → 修复后 200 |
| A-05a | 设备注册 | **PASS** | 200 + UPSERT 语义正确 |
| A-05b | 重复设备注册 | **PASS** | 200, 不重复创建 |
| A-05c | 设备心跳 | **PASS** | 200 |
| A-05d | 设备列表 | **PASS** | 返回注册的设备 |
| A-06a | 密码修改 | **PASS** | 200 + 旧密码失效验证 |
| A-06b | 错误旧密码 | **PASS** | 401 AUTH_ERROR |
| A-07 | API Token 创建/认证 | **PASS** | zclaw_ 前缀 token, /me 正常 |
### B 类数据测试 — 3/5 通过
| ID | 测试项 | 结果 | 详情 |
|----|--------|------|------|
| B-01 | Config seed | **PASS** | 创建 13 个默认配置项 |
| B-02a | Config diff | **PASS** | 返回 conflict 比对正确 |
| B-02b | Config sync push | **PASS** | 返回 {updated, created, skipped} |
| ~~B-02c~~ | ~~`created` 计数修复~~ | **FIXED** | 原 created=0 → 修复后 push 新 key 时 created=1 |
| B-03 | ~~GET /models~~ | **FAIL→FIXED** | SQL 参数绑定错误 500 → 已修复 |
### Admin 专项 — 2/2 通过
| ID | 测试项 | 结果 | 详情 |
|----|--------|------|------|
| E-01 | 权限过滤逻辑 | **PASS** | 已修复: 基于 permissions 数组过滤 |
| E-02 | 分页连接 API | **PASS** | 已确认 5 个页面均传递分页参数 |
---
## 三、发现并修复的 Bug 汇总
### 已修复 (5 项)
| # | 严重性 | 问题 | 文件 | 修复 |
|---|--------|------|------|------|
| 1 | **CRITICAL** | `sync_config` 无权限检查 | [migration/handlers.rs:90](crates/zclaw-saas/src/migration/handlers.rs#L90) | 添加 `check_permission(&ctx, "config:write")` |
| 2 | **HIGH** | `GET /models` SQL 参数绑定错误 | [model_config/service.rs:135](crates/zclaw-saas/src/model_config/service.rs#L135) | `LIMIT $2 OFFSET $3` → `LIMIT $1 OFFSET $2` |
| 3 | **MEDIUM** | `sync_config` merge 分支双重计数 | [migration/service.rs:352](crates/zclaw-saas/src/migration/service.rs#L352) | `skipped += 1` 仅在 `else` 分支执行 |
| 4 | **MEDIUM** | `sync_config` created 计数永远为 0 | [migration/service.rs:311](crates/zclaw-saas/src/migration/service.rs#L311) | push 模式创建新 config_item 时递增 |
| 5 | **HIGH** | Admin 权限过滤逻辑错误 | [layout.tsx:107](admin/src/app/(dashboard)/layout.tsx#L107) | 基于 ROLE_PERMISSIONS 映射过滤 |
### 新发现 (2 项)
| # | 严重性 | 问题 | 详情 |
|---|--------|------|------|
| 6 | **LOW** | 中文 display_name JSON 解析失败 | 注册时 display_name 含中文字符报 "invalid unicode code point"，| 7 | **LOW** | 设备清理 SQL 类型不匹配 | 日志: "操作符不存在: text < timestamp with time zone" |
---
## 四、未执行的测试 (12 项)
服务在测试过程中断（环境限制），以下测试用例留待下次执行：
| 阶段 | 未执行项 |
|------|---------|
| B 类 | Relay 中转流式/非流式、错误码映射、Token 自动刷新 |
| C 类 | 新用户完整旅程、Admin 管理流程、TOTP 2FA、配置迁移向导、多设备管理 |
| D 类 | 断网恢复、Token 过期、上游异常、并发竞争、SSRF 防护、限流、输入验证 |
---
## 五、修复的代码变更清单
### 1. crates/zclaw-saas/src/migration/handlers.rs
```rust
// 修复前: 无权限检查
// 修复后: 添加 check_permission
pub async fn sync_config(...) -> SaasResult<...> {
check_permission(&ctx, "config:write")?; // 新增
...
}
```
### 2. crates/zclaw-saas/src/model_config/service.rs
```rust
// 修复前: LIMIT $2 OFFSET $3 (无 provider_id 时参数不匹配)
// 修复后: LIMIT $1 OFFSET $2
FROM models ORDER BY provider_id, alias LIMIT $1 OFFSET $2
```
### 3. crates/zclaw-saas/src/migration/service.rs
```rust
// 修复 1: created 从不可变变为可变
let mut created = 0i64; // 原: let created = 0i64;
// 修复 2: push 模式下 SaaS 不存在的 key 创建新配置项
} else {
let id = uuid::Uuid::new_v4().to_string();
sqlx::query("INSERT INTO config_items ...")...;
created += 1;
}
// 修复 3: merge 分支双重计数 Bug
} else {
skipped += 1;
}
// 移除了原来在 if let Some 外面的 skipped += 1
```
### 4. admin/src/app/(dashboard)/layout.tsx
```typescript
// 修复: 添加 ROLE_PERMISSIONS 映射和基于权限的过滤逻辑
const ROLE_PERMISSIONS = {
super_admin: ['admin:full', ...],
admin: ['account:admin', 'provider:manage', ...],
user: ['model:read', 'relay:use', 'config:read'],
};
// 使用 account.permissions.includes(item.permission) 过滤
```
---
## 六、遗留问题与建议
### P0 — 需立即修复
无（CRITICAL 已修复）
### P1 — 功能缺陷
| # | 问题 | 建议 |
|---|------|------|
| P1-1 | `account_api_keys` 未被 Relay 消费 | Relay handler 查找用户级 Key，回退到 provider 级 |
| P1-2 | Config 5 端点缺审计日志 | 添加 `log_operation()` 调用 |
| P1-3 | Admin 前端缺路由守卫 | 添加 AuthGuard 组件 |
### P2 — 代码质量
| # | 问题 | 建议 |
|---|------|------|
| P2-1 | 6 个端点缺 OpenAPI 文档 | 补充 `#[utoipa::path]` |
| P2-2 | 设备清理 SQL 类型不匹配 | `last_seen_at` 字段类型修正 |
| P2-3 | 中文 display_name JSON 解析 | UTF-8 编码处理 |
| P2-4 | dashboard_stats 7 次串行查询 | 合并为单次 SQL |
| P2-5 | `computeConfigDiff`/`syncConfig` 未调用 | 统一迁移向导调用路径 |

191
docs/features/MODULE_AUDIT_SUMMARY.md
View File

@@ -1,191 +0,0 @@
# 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 天）
1. **[M4-01]** 统一记忆存储层 — 让前端 memory_search 也查询 SqliteStorage
2. **[M4-02]** 反思引擎接入 LLM — reflection_reflect 传入实际 driver
### 第二阶段：P1 核心功能修复（预计 5-7 天）
3. **[M2-01/02]** 扩展 kernel-agent.ts createClone 字段 + 统一双通路
4. **[M3-01]** hand_execute 返回 run_id
5. **[M3-05]** 实现 timeout_secs 超时保护
6. **[M3-04]** 实现 max_concurrent 并发限制
7. **[M3-03]** browserHandStore 集成审批流程
8. **[M5-01]** 修正 skill-discovery triggers 映射
9. **[M6-01]** 注册 route_intent Tauri 命令
10. **[M6-02]** pipeline_list 支持 v2 格式
11. **[M4-03]** 自动启动心跳引擎
12. **[M4-05]** 前端记忆搜索升级 FTS5
13. **[M11-01]** 修复 blocking_lock 死锁风险
14. **[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 轮审计的创新：
1. 首次以功能领域为主轴追踪完整调用链
2. 首次系统验证参数/类型一致性（发现了 4 处前端参数不匹配）
3. 首次验证边界场景（错误传播、空状态、并发）
4. 建立了模块级健康度基线，未来审计可增量更新

129
docs/features/QA_REVIEW_V1.md
View File

@@ -1,129 +0,0 @@
# ZCLAW 全栈 QA 与代码审查报告
> 日期: 2026-03-31 ~ 2026-04-01
> 审查方法: 模块垂直扫描 (4 Tracks) + 后续测试补充 + 大文件拆分
> 审查范围: Rust 后端 + Admin V2 前端 + Desktop 前端 + 配置/部署
---
## 1. 审查发现与修复汇总
### 1.1 已修复问题
| # | 问题 | 严重级 | 模块 | 状态 |
|---|------|--------|------|------|
| 1 | `relay_enqueue()` 重复调用 (探索阶段报告) | P0 | SaaS 后端 | **误报** — 实际只有一次调用 |
| 2 | 密码策略无复杂度要求 | P2 | SaaS 后端 | **已修复** — 大写+小写+数字验证 |
| 3 | JWT 缺少 `aud` (受众) claim | P3 | SaaS 后端 | **已修复** — `aud: "zclaw-saas"` + 验证 |
| 4 | JWT 缺少 `pwv` (密码版本) | P1 | SaaS 后端 | **已修复** — 用户修改 |
| 5 | 17 处 `println!`/`eprintln!` 生产代码 | P1 | Rust crates | **已修复** — 全部替换为 `tracing::*` |
| 6 | Desktop 49 处 `any` 用法 | P1 | Desktop | **已修复** — gateway-api-types.ts 类型化 |
| 7 | Desktop 80+ 裸 `console.*` 调用 | P1 | Desktop | **已修复** — 26 处替换为 logger |
| 8 | Desktop tsconfig 排除 ErrorBoundary/ErrorAlert | P2 | Desktop | **已修复** — 修复类型错误后移除排除 |
| 9 | Docker Compose 默认密码 + 端口暴露 | P2 | 部署 | **已修复** — 用户进一步加固 |
| 10 | 缺少 `.dockerignore` | P3 | 部署 | **已修复** |
| 11 | Admin V2 测试覆盖不足 (3/10 页面) | P1 | Admin V2 | **已修复** — 71 个测试全部通过 |
### 1.2 确认良好的方面
| 模块 | 良好实践 |
|------|----------|
| Admin V2 | 零 `any` 用法、无 `dangerouslySetInnerHTML`、ErrorBoundary 完善 |
| SaaS 后端 | Argon2id 密码哈希、AES-256-GCM 加密、参数化 SQL、SSRF 防护完善 |
| 认证系统 | HttpOnly + Secure + SameSite=Strict Cookie、refresh token 轮换、pwv 密码版本追踪 |
| RBAC | `admin:full` 超级权限、IDOR 防护、权限缓存 |
---
## 2. 后续工作完成情况
### 2.1 Admin V2 测试补充 (71 个测试，12 个测试文件)
| 测试文件 | 测试数 | 覆盖内容 |
|----------|--------|----------|
| `Accounts.test.tsx` | 已有 | 账号 CRUD |
| `AgentTemplates.test.tsx` | 已有 | 模板管理 |
| `authStore.test.ts` | 已有 | 认证状态 |
| `request.test.ts` | 已有 | HTTP 客户端 |
| `Dashboard.test.tsx` | 8 新增 | 统计数据 + 日志展示 |
| `Login.test.tsx` | 7 新增 | 登录 + TOTP + 错误处理 |
| `Config.test.tsx` | 7 新增 | 配置项 + 分类标签页 |
| `Logs.test.tsx` | 7 新增 | 日志分页 + 筛选 + ErrorState |
| `Relay.test.tsx` | 7 新增 | 中转任务 + 状态标签 |
| `Usage.test.tsx` | 6 新增 | 统计卡片 + 每日/模型表 |
| `Prompts.test.tsx` | 5 新增 | 提示词模板 + CRUD |
| `ModelServices.test.tsx` | 5 新增 | 供应商列表 + 状态标签 |
### 2.2 大文件拆分
| 文件 | 原始行数 | 拆分结果 | 状态 |
|------|----------|----------|------|
| `kernel.rs` | 1486 | 9 个子模块 (mod.rs + adapters/agents/messaging/skills/hands/triggers/approvals/a2a) | **完成** |
| `intelligence-client.ts` | 1475 | 9 个子模块 (index/types/type-conversions/unified-client + 5 个 fallback) | **完成** |
| `db.rs` | 891 | 保持原样 (拆分风险大于收益) | **跳过** |
### 2.3 kernel.rs 拆分详情
```
kernel/
├── mod.rs (~200L) — Kernel struct + boot + 中间件 + 访问器
├── adapters.rs (~95L) — LlmDriverAdapter + KernelSkillExecutor + AgentInbox
├── agents.rs (~100L) — Agent CRUD
├── messaging.rs (~150L) — 消息发送 + 技能提示构建
├── skills.rs (~70L) — 技能管理
├── hands.rs (~200L) — Hand 执行 + 运行追踪
├── triggers.rs (~45L) — 触发器 CRUD
├── approvals.rs (~140L) — 审批管理
└── a2a.rs (~265L) — A2A 多智能体 (cfg multi-agent)
```
### 2.4 intelligence-client.ts 拆分详情
```
intelligence-client/
├── index.ts (~65L) — 统一重导出
├── types.ts (~175L) — 前端类型 + Mesh + Persona Evolver
├── type-conversions.ts (~95L) — 前后端类型转换
├── unified-client.ts (~440L) — 主 intelligenceClient 对象
├── fallback-memory.ts (~165L) — localStorage 内存回退
├── fallback-compactor.ts (~60L) — 压缩回退
├── fallback-reflection.ts (~165L) — 反思回退
├── fallback-identity.ts (~235L) — 身份管理回退
└── fallback-heartbeat.ts (~55L) — 心跳回退
```
---
## 3. 验证结果
| 检查项 | 结果 |
|--------|------|
| `cargo check -p zclaw-saas` | **通过** |
| `cargo check -p zclaw-kernel` | **通过** (runtime 有预存类型问题) |
| `cargo test -p zclaw-saas --lib -- jwt` | **6/6 通过** (含 aud + pwv 测试) |
| Desktop `tsc --noEmit` | **通过** (0 errors) |
| Admin V2 `tsc --noEmit` | **通过** (0 errors) |
| Admin V2 `vitest run` | **71/71 通过** (12 个测试文件) |
---
## 4. 遗留项与后续建议
### 4.1 db.rs 拆分 (891L)
保持原样。原因：
- `init_db()` 是唯一的公共入口，所有 seed/migration 函数都是内部实现
- 函数间有较强耦合（migration 调用 seed_roles，init_db 编排所有步骤）
- 拆分收益有限（不像 kernel.rs 有多个独立领域）
### 4.2 安全增强建议
- Docker Compose 生产部署时考虑 Redis-backed 分布式限流
- 考虑将邮箱验证改为使用 email 验证库
- 生产环境日志写入 WAF
### 4.3 代码质量持续改进
- Desktop 仍有约 50 处裸 `console.*` 调用在非重点文件中
- `zclaw-runtime` 有预存的 `Message` enum 类型错误需修复
- Admin V2 coverage thresholds 已设置 (60%)，持续补充测试达到目标

329
docs/features/SECONDARY_AUDIT_V11.md
View File

@@ -1,329 +0,0 @@
# ZCLAW 深度二次审计补充报告
> **审计日期**: 2026-04-02
> **基线**: V11 全面审计报告（22 项发现）
> **方法**: 5 维并行深度审计
> **新增发现**: 22 项（2 P0 + 9 P1 + 10 P2 + 3 P3 + 1 确认项）
---
## 1. 审计维度
| # | 维度 | 发现数 |
|---|------|--------|
| 1 | Rust crate 交叉依赖 + 编译状态 | 5 |
| 2 | 前端 Store ↔ Tauri 命令参数签名全量比对 | 5 |
| 3 | Sprint 1-4 修复代码质量验证 | 1 |
| 4 | 安全/竞态/资源泄漏扫描 | 9 |
| 5 | 测试覆盖缺口 + admin-v2 API 对齐 | 4 |
---
## 2. 新增 P0 发现（2 项）
### SEC2-P0-01: skill_execute 反序列化崩溃
| 维度 | 详情 |
|------|------|
| **问题** | 前端传递空 `context: {}`，但 Rust `SkillContext` 要求 `agent_id: String` 和 `session_id: String`（非 Option）。空 JSON 无法反序列化。 |
| **前端** | `desktop/src/lib/kernel-skills.ts:110-114` |
| **Rust** | `desktop/src-tauri/src/kernel_commands/skill.rs:290-296` |
| **触发条件** | 用户在前端执行任何 Skill |
| **影响** | 运行时 serde 反序列化失败，Skill 执行必然报错 |
### SEC2-P0-02: TaskTool::default() 潜在 panic
| 维度 | 详情 |
|------|------|
| **问题** | `TaskTool` 实现了 `Default` trait，但 `default()` 调用 `unimplemented!()` |
| **文件** | `crates/zclaw-runtime/src/tool/builtin/task.rs:59` |
| **触发条件** | 任何泛型约束 `T: Default` 触发 `TaskTool::default()` 时 |
| **影响** | 运行时 panic（虽然正常路径使用 `TaskTool::new()` 规避） |
| **建议** | 移除 `impl Default for TaskTool`，或提供合理的默认值 |
---
## 3. 新增 P1 发现（9 项）
### SEC2-P1-01: FactStore trait 零实现
| 维度 | 详情 |
|------|------|
| **问题** | `FactStore` trait 在 `zclaw-memory/src/fact.rs:141` 定义，全 workspace 无任何 `impl FactStore for T`。`MemoryStore` 有同名方法但未实现 trait。`dyn FactStore` 模式完全不可用。 |
| **文件** | `crates/zclaw-memory/src/fact.rs` |
| **影响** | 架构层面功能缺口——trait 接口已定义但无法使用 |
### SEC2-P1-02: agent-templates API 路径缺少 /api/v1 前缀
| 维度 | 详情 |
|------|------|
| **问题** | 前端 saas-client.ts 中 agent-templates 路径缺少 `/api/v1` 前缀 |
| **前端** | `desktop/src/lib/saas-client.ts:376,384`：`'/agent-templates/available'`、`'/agent-templates/${id}/full'` |
| **后端** | 路由注册在 `/api/v1/agent-templates/...` |
| **影响** | 请求发送到错误 URL，必然返回 404 |
### SEC2-P1-03: hand-execution-complete 事件无前端监听
| 维度 | 详情 |
|------|------|
| **问题** | Rust 在 `hand.rs:279` 和 `approval.rs:130` emit `hand-execution-complete`，但前端无任何 `listen()` 调用 |
| **影响** | Hand 异步执行完成后，前端无法收到通知，用户不知道执行结果 |
### SEC2-P1-04: InMemoryStorage RwLock unwrap() 级联 panic 风险
| 维度 | 详情 |
|------|------|
| **问题** | `InMemoryStorage` 中 6 处 `std::sync::RwLock` 的 `.unwrap()`。若锁被 poisoned（某线程 panic），后续所有调用级联崩溃 |
| **文件** | `crates/zclaw-growth/src/viking_adapter.rs:137,143,148,190,202,208,214` |
| **风险** | 低概率但后果严重 |
### SEC2-P1-05: HandRun 持久化错误静默忽略（3 处）
| 维度 | 详情 |
|------|------|
| **问题** | `let _ = memory.save_hand_run(&run).await` 等 3 处 HandRun 持久化错误被忽略 |
| **文件** | `crates/zclaw-kernel/src/kernel/approvals.rs:88,91,120` |
| **影响** | DB 不可用时 run 状态丢失，UI 无法显示执行结果 |
| **建议** | 至少 log warning |
### SEC2-P1-06: FTS 索引更新失败静默忽略（3 处）
| 维度 | 详情 |
|------|------|
| **问题** | 全文搜索索引 DELETE/INSERT 操作失败被 `let _ =` 忽略 |
| **文件** | `crates/zclaw-growth/src/storage/sqlite.rs:384,390,605` |
| **影响** | 搜索结果不一致（stale index） |
### SEC2-P1-07: Worker dispatch 失败静默忽略（4 处）
| 维度 | 详情 |
|------|------|
| **问题** | `let _ = state.worker_dispatcher.dispatch(...)` 4 处忽略 |
| **文件** | `crates/zclaw-saas/src/knowledge/handlers.rs:220,262,331,539` |
| **影响** | embedding 生成等后台任务可能静默丢失 |
### SEC2-P1-08: Desktop 前端零测试
| 维度 | 详情 |
|------|------|
| **问题** | `desktop/src/` 中零个 `.test.ts`/`.test.tsx` 文件，包括 chatStore、agentStore 等核心 store |
| **影响** | 前端任何回归只能通过手工测试发现 |
### SEC2-P1-09: record_key_usage 错误忽略导致计费数据丢失风险
| 维度 | 详情 |
|------|------|
| **问题** | `let _ = record_key_usage(...)` 忽略写入错误 |
| **文件** | `crates/zclaw-saas/src/relay/service.rs:376` |
| **影响** | 可能导致计费数据丢失 |
---
## 4. 新增 P2 发现（10 项）
| ID | 问题 | 文件 |
|----|------|------|
| SEC2-P2-01 | `hmac`/`sha1` 在 zclaw-hands Cargo.toml 中声明但代码零引用 | `crates/zclaw-hands/Cargo.toml` |
| SEC2-P2-02 | `serde_yaml` 版本不一致：desktop 用 0.9，pipeline 用 2（不同 package） | 各 `Cargo.toml` |
| SEC2-P2-03 | `sqlx-postgres v0.7.4` 使用了未来 Rust 版本将拒绝的语法 | `Cargo.lock` |
| SEC2-P2-04 | `generate_embedding.rs:107` embedding 生成被注释掉（`// TODO`） | `crates/zclaw-saas/src/workers/generate_embedding.rs` |
| SEC2-P2-05 | ~10 处 `tokio::spawn` 返回 JoinHandle 未绑定，无法优雅停止 | kernel + saas 多处 |
| SEC2-P2-06 | Telemetry 审计日志批量 INSERT 绑定可能与 SQL 模板不匹配 | `crates/zclaw-saas/src/telemetry/service.rs:205-213` |
| SEC2-P2-07 | Scheduler 串行执行 trigger，长 hand 阻塞后续调度 | `crates/zclaw-kernel/src/scheduler.rs:117-153` |
| SEC2-P2-08 | `format!("FROM {}", table)` 模式虽当前安全（硬编码），但违反防御原则 | `crates/zclaw-saas/src/db.rs:874,880` |
| SEC2-P2-09 | `hand_run_status` 前端传递多余 `handName` 参数（Rust 只接收 `run_id`） | `desktop/src/lib/kernel-hands.ts:95` |
| SEC2-P2-10 | `kernel_apply_saas_config` TOML 写入不支持多行值 | `desktop/src-tauri/src/kernel_commands/lifecycle.rs` |
---
## 5. 新增 P3 发现（3 项）
| ID | 问题 | 文件 |
|----|------|------|
| SEC2-P3-01 | A2A Router 4 个 RwLock 获取顺序未文档化 | `crates/zclaw-protocols/src/a2a.rs:239-245` |
| SEC2-P3-02 | Admin-v2 Role 类型：后端 `is_system` 字段前端未映射，前端 `account_count` 后端无字段 | `admin-v2/src/types/index.ts` vs `role/types.rs` |
| SEC2-P3-03 | Admin-v2 Billing/Knowledge/Roles 三个页面缺测试（Billing、Knowledge 页面 + Roles 新页面） | `admin-v2/tests/` |
---
## 6. 确认项（审计验证结果）
### 6.1 编译状态
- `cargo check --workspace` **编译成功**（33.60s）
- 2 个 warning：`RegisterDeviceRequest` 可见性（P2）、`sqlx-postgres` 未来兼容性（P1）
### 6.2 Sprint 1-4 修复验证
| 修复 | 验证结果 |
|------|---------|
| trigger_update 参数扁平化 | **通过** — 前后端参数完全匹配 |
| SaaS config sync 传播 | **通过** — kernel_apply_saas_config 正确桥接 |
| Deprecated 代码清理 | **通过** — 无残留引用 |
| Admin Roles 页面 | **通过** — API 路径与 SaaS 路由匹配 |
| ToolDefinition 去重 | **通过** — 使用 pub use |
| Knowledge handler 修复 | **通过** — 连接到 service 层 |
| Task 结果持久化 | **通过** — migration + 读写一致 |
### 6.3 Admin-v2 ↔ SaaS API 对齐
**结论：100% 对齐。** 所有 admin-v2 前端调用的 API 端点在后端都有对应路由注册，包括：
- 9 个 knowledge 路径（categories/items/analytics/search/recommend/import/versions/rollback/batch）
- 5 个 role 路径 + 5 个 permission-template 路径
- 6 个 billing 路径
- 2 个 telemetry 路径
### 6.4 Feature Gate 一致性
传播链完全正确：
```
desktop --multi-agent--> zclaw-kernel --multi-agent--> zclaw-protocols --a2a--> [a2a module]
zclaw-skills --wasm--> [wasmtime, wasmtime-wasi]
```
### 6.5 认证覆盖
SaaS 后端三层路由分离无遗漏：公共路由 + 受保护路由 + Relay 独立中间件链。
---
## 7. 测试覆盖统计
### 7.1 Rust 测试分布
| Crate | 测试数 | 关键缺口 |
|-------|--------|----------|
| zclaw-hands | 155 | - |
| zclaw-saas | 92 | 集中在工具函数，handler/scheduler 0 测试 |
| zclaw-growth | 75 | - |
| zclaw-pipeline | 59 | - |
| zclaw-types | 57 | - |
| zclaw-kernel | 52 | capabilities/registry/trigger_manager 0 测试 |
| zclaw-runtime | 42 | - |
| zclaw-memory | 25 | - |
| zclaw-skills | 22 | - |
| zclaw-protocols | 5 | 极低 |
| **总计** | **584** | |
### 7.2 零测试关键模块
| 模块 | 公开函数数 | 严重度 |
|------|-----------|--------|
| kernel_commands/ (41 Tauri 命令) | 41 | P0 |
| browser/commands.rs (23 命令) | 23 | P0 |
| SaaS scheduler.rs | 3 公开函数 | P1 |
| SaaS knowledge/handlers.rs (561 行) | ~15 | P1 |
| SaaS relay/service.rs | ~20 | P1 |
| SaaS billing/ | ~10 | P1 |
| Desktop frontend | 全部 | P1 |
### 7.3 Admin-v2 测试
- **测试框架**: Vitest + jsdom + MSW
- **测试用例**: 322 个
- **覆盖页面**: 10/13（缺失 Billing、Knowledge、Roles）
- **覆盖 service**: 1/17（仅 request.ts）
---
## 8. 积极发现
1. **SQL 参数化规范**：SaaS 层绝大多数 SQL 使用 `sqlx::query(...).bind(...)` 参数化
2. **密钥保护**：JWT secret 使用 `secrecy::SecretString`，API key 日志仅输出 ID
3. **DashMap 死锁已规避**：所有 DashMap RefMut 在 `.await` 前释放
4. **SSE 背压设计**：有界 channel + 信号量限制 + CancellationToken
5. **密码版本控制**：password_version 确保 JWT 失效
6. **MCP Transport**：实现 Drop trait 清理子进程
7. **DB 连接池监控**：30s 周期日志 + 80% 告警
8. **Admin-v2 API 对齐**：所有前端调用都有后端路由对应
---
## 9. 综合风险矩阵（V11 + 二次审计合并）
| 严重度 | V11 原始 | 二次审计新增 | 合计 |
|--------|----------|-------------|------|
| P0 | 1 (误报) | **2** | 2 |
| P1 | 3 | **9** | 12 |
| P2 | 6 | **10** | 16 |
| P3 | 8 | **3** | 11 |
| P4 | 5 | 0 | 5 |
| **总计** | **23** | **24** | **46** |
---
## 10. 支付安全深度审计 V3（2026-04-02）
> **审计范围**: `crates/zclaw-saas/src/billing/` 全部文件（payment.rs, service.rs, handlers.rs, types.rs, mod.rs）
> **审计方法**: 3 维并行（Security Engineer + Code Reviewer + Senior Developer）
> **基线**: V2 审计后的 25 项修复全部落地
### 10.1 审计结论
| 指标 | 结果 |
|------|------|
| **CRITICAL** | **0** |
| **HIGH** | **0** |
| **MEDIUM** | **1**（已修复） |
| **LOW** | **3**（pre-existing / cosmetic） |
### 10.2 已修复项（本次修复）
| ID | 严重度 | 问题 | 修复 |
|----|--------|------|------|
| PAY-FIX-01 | MEDIUM | `truncate_str` 使用 `s.len()`（字节数）判断是否截断，但 `chars().take()` 按字符截断。中文等多字节字符串在 200 字节内但超过 200 字符时截断错误 | 改为先 `chars().collect::<Vec<char>>()` 再按 `.len()` 判断字符数 |
### 10.3 已验证通过的关键安全措施（25 项）
#### 事务与竞态保护（6 项）
- [x] `create_payment` 在事务中创建 invoice + payment（原子性）
- [x] `handle_payment_callback` 使用 `SELECT ... FOR UPDATE` 锁定行（防 TOCTOU）
- [x] `get_or_create_usage` 使用 `INSERT ON CONFLICT DO NOTHING`（防重复创建）
- [x] 金额交叉验证：生产环境 `callback_amount` 为 None 时拒绝
- [x] 幂等保护：已处理的 payment（status != pending）直接返回
- [x] 事务失败时正确 rollback
#### 支付回调安全（6 项）
- [x] Alipay 验签：生产环境强制 RSA2 验签，缺公钥拒绝
- [x] WeChat 解密：AES-256-GCM + nonce 长度校验（12 字节）
- [x] trade_no 缺失时返回错误而非静默忽略
- [x] 日志安全：`sanitize_log` 只保留字母数字和 `-` `_`
- [x] 通用错误对外返回（不泄露内部细节）
- [x] 回调路由正确分离到 public_routes（无需认证）
#### 密钥保护（4 项）
- [x] `PaymentConfig` 自定义 Debug impl，敏感字段显示 `***REDACTED***`
- [x] `alipay_private_key`、`alipay_public_key`、`wechat_api_v3_key` 标记 `skip_serializing`
- [x] JWT 密钥使用 `secrecy::SecretString`
- [x] API key 日志仅输出 ID 不输出值
#### 货币精度（2 项）
- [x] 分→元转换使用整数运算（`amount_cents / 100` + `amount_cents % 100`）
- [x] WeChat 金额保持整数分（无浮点转换）
#### HTML 安全（2 项）
- [x] Mock 支付页面使用 `html_escape()` 转义用户输入
- [x] Mock 确认页面的 `msg` 变量由服务端控制（安全）
#### SQL 安全（3 项）
- [x] 所有 SQL 使用参数化查询（`sqlx::query(...).bind(...)`）
- [x] `increment_dimension` 使用白名单分支（非动态列名）
- [x] `failure_reason` 截断到 200 字符
#### 整体架构（2 项）
- [x] 路由分离：`routes()` 需认证，`callback_routes()` 公开
- [x] 批量递增 `increment_dimension_by` 替代循环查询
### 10.4 剩余 LOW 项（不影响安全，可后续优化）
| ID | 说明 | 建议 |
|----|------|------|
| PAY-LOW-01 | `reqwest::Client::new()` 每次 WeChat 支付创建新实例 | 改为 AppState 中共享 Client |
| PAY-LOW-02 | `BootstrapScreen` 缺少 dark mode 变体 | 添加 `dark:bg-gray-900` |
| PAY-LOW-03 | `aside.w-64.sidebar-open` class 定义但无 JS 切换逻辑 | 添加汉堡菜单或移除 |
### 10.5 审计签名
- **Security Engineer**: 0 CRITICAL, 0 HIGH — 支付链路安全措施完备
- **Code Reviewer**: 25 项修复全部正确实现，无回归
- **Senior Developer**: 1 MEDIUM 已修复（truncate_str），代码质量良好

829
docs/features/SYSTEM_ARCHITECTURE.md
View File

@@ -1,829 +0,0 @@
# ZCLAW 多端系统架构文档
> 版本: 1.3 | 日期: 2026-04-06 | 状态: 已更新 (DeerFlow 2.0 + 安全审计 V1 修复 + Admin V2 迁移)
---
## 目录
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 V2 │ │ SaaS Backend │ │
│ │ (Tauri+React)│ │ (Vite+AntD) │ │ (Axum + PostgreSQL) │ │
│ │ Port: 1420 │ │ Port: 5173 │ │ 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/)~~ |
| 5173 | Vite Dev Server | HTTP | Admin V2 管理后台开发服务 | `pnpm dev` (admin-v2/) |
| 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 19 + TypeScript | 生态丰富，类型安全 |
| 状态管理 | Zustand | 轻量、灵活、无 boilerplate |
| 样式方案 | Tailwind 4 | 原子化 CSS，暗色主题友好 |
| 数据存储 | SQLite (本地) | 离线优先，FTS5 全文搜索 |
### 3.2 Admin V2 管理后台
| 层级 | 技术 | 选型理由 |
|------|------|----------|
| 框架 | React 19 + Vite 8 | 纯 SPA，快速构建 |
| 语言 | TypeScript 5.9 | 类型安全 |
| UI 组件 | Ant Design 6 + Pro Components | 企业级组件库，暗色主题 |
| 状态管理 | Zustand 5 | 轻量灵活 |
| 数据获取 | TanStack React Query 5 | 缓存+去重+自动重验证 |
| 路由 | React Router 7 | SPA 路由 |
| HTTP | Axios | 拦截器 + 401 自动刷新 |
| 样式 | Tailwind CSS v4 | 原子化 CSS |
| 测试 | Vitest + Testing Library + MSW | 完整测试覆盖 |
> **Admin V2 迁移说明**: 从 Next.js + SWR + shadcn/ui 迁移到 Vite + React Query + Ant Design Pro，认证改为 HttpOnly Cookie 模式，11 个管理页面全部重写，含 71 个测试用例。
### 3.3 SaaS 后端
| 层级 | 技术 | 选型理由 |
|------|------|----------|
| Web 框架 | Axum | Rust 高性能异步 Web 框架 |
| 数据库 | PostgreSQL | 关系型，复杂查询支持好 |
| ORM | sqlx | 编译时 SQL 检查，零开销 |
| 认证 | JWT + TOTP | 无状态鉴权 + 双因素认证 |
| 加密 | AES-256-GCM | API Key 加密存储 |
| 后台任务 | Worker trait + mpsc Channel | 异步非阻塞，支持自动重试 |
| 定时任务 | 声明式 Scheduler (TOML) | 无需改代码调整调度时间 |
| 连接池 | sqlx PgPool (50 max / 5 min) | 高并发，自动管理生命周期 |
| 迁移系统 | SQL 文件 + Schema 版本控制 | TIMESTAMPTZ 类型，向后兼容 |
| 多环境 | ZCLAW_ENV (dev/prod/test) | 配置隔离，环境变量覆盖 |
### 3.4 核心运行时 (Rust Workspace)
```
zclaw-types → 基础类型 (AgentId, Message, Error)
zclaw-memory → 存储层 (SQLite, FTS5, TF-IDF, Embeddings)
zclaw-runtime → 运行时 (LLM 驱动, 11 层中间件, 工具, Agent 循环)
zclaw-kernel → 核心协调 (注册, 调度, 事件, 9 Hands, 75 Skills)
zclaw-skills → 技能系统 (SKILL.md 解析, 语义路由, DAG 编排)
zclaw-hands → 自主能力 (9 个内置 Hand 实现)
zclaw-protocols → 协议支持 (MCP, A2A)
zclaw-pipeline → 流水线引擎 (v1/v2 DSL, Smart Presentation)
zclaw-growth → 成长系统 (记忆提取/检索/注入, OpenViking 分层)
zclaw-saas → SaaS 后端 (独立服务, 8080 端口, 131 API)
```
---
## 4. 数据流向
### 4.1 Admin V2 管理后台数据流
```
用户操作 → React UI → React Query → request.ts (Axios) → Vite Proxy → SaaS 后端 (:8080)
↑ ↓
└── React Query Cache ←── JSON Response ←── PostgreSQL (:5432) ←─┘
```
**关键路径:**
- Admin V2 所有请求通过 `vite.config.ts proxy` 代理到 `localhost:8080`
- API 基路径: `/api/v1/*` (前端) → `http://localhost:8080/api/v1/*` (后端)
- React Query 缓存: 自动去重 + stale-while-revalidate 模式
- SSE 端点 (`/relay/chat/completions`) 超时配置 10 分钟
### 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 | 34 | agent_create/chat_stream, skill_execute, hand_execute, trigger, workflow |
| 工作流 | pipeline_commands.rs | 10 | pipeline_run/progress/cancel, route_intent |
| 浏览器自动化 | browser_commands.rs | 22 | navigate/click/fill/screenshot/evaluate |
| 智能层 | intelligence_commands.rs | 35 | memory/identity/reflection/heartbeat/autonomy |
| 持久记忆 | memory_commands.rs | 14 | memory_store/get/search/export/graph |
| Viking 存储 | viking_commands.rs | 13 | viking_add/find/grep/read |
| CLI 工具 | cli_commands.rs | 13 | doctor/health/export/import |
| 安全存储 | secure_storage.rs | 4 | store/get/delete/list |
| LLM 管理 | llm_commands.rs | 3 | list_providers/test_connection |
> **总计**: 177 个 Tauri Commands (160 已接通前端 + 16 个 @reserved 预留 + 1 个未注册)
### 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 V2 浏览器 (localhost:5173) │
│ │
│ ┌──────────┐ React Query ┌──────────────┐ │
│ │ React UI │◄────────────►│ Axios │ │
│ │ 11 页面 │ Cache │ Cookie 认证 │ │
│ └──────────┘ └──────┬───────┘ │
│ │ axios() │
└──────────────────────────────────┼────────────────────────┘
│
Vite Proxy │ /api/* → localhost:8080/api/*
│
┌──────────────────────────────────┼────────────────────────┐
│ SaaS Backend (:8080) │ │
│ ┌──────▼───────┐ │
│ │ Axum Router │ │
│ │ 中间件栈: │ │
│ │ 1. Auth │ │
│ │ 2. RateLimit │ │
│ │ 3. RequestID │ │
│ │ 4. Version │ │
│ └──────┬───────┘ │
│ │ │
│ ┌─────────────▼──────────────┐ │
│ │ Handlers (131 个端点) │ │
│ │ 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 后端配置
#### 配置加载优先级
```
ZCLAW_SAAS_CONFIG (精确路径) > ZCLAW_ENV (环境选择) > ./saas-config.toml (默认)
```
环境配置文件:
- `ZCLAW_ENV=development` -> `config/saas-development.toml`
- `ZCLAW_ENV=production` -> `config/saas-production.toml`
- `ZCLAW_ENV=test` -> `config/saas-test.toml`
环境变量覆盖:
- `ZCLAW_DATABASE_URL` — 覆盖数据库 URL (避免配置文件存密码)
- `ZCLAW_SAAS_JWT_SECRET` — JWT 签名密钥 (生产环境必须设置)
- `ZCLAW_TOTP_ENCRYPTION_KEY` — TOTP/AES-256-GCM 加密密钥 (hex 64 字符)
- `ZCLAW_SAAS_DEV` — 开发模式 (允许使用不安全的默认密钥)
#### 配置结构
```toml
# saas-config.toml
[server]
host = "0.0.0.0"
port = 8080
cors_origins = []
[database]
url = "postgres://postgres:123123@localhost:5432/zclaw"
[auth]
jwt_expiration_hours = 24
totp_issuer = "ZCLAW SaaS"
refresh_token_hours = 168 # 7 天
[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
# 声明式定时任务 (新增)
[[scheduler.jobs]]
name = "cleanup-refresh-tokens"
interval = "1h"
task = "cleanup_refresh_tokens"
run_on_start = false
[[scheduler.jobs]]
name = "cleanup-rate-limit"
interval = "5m"
task = "cleanup_rate_limit"
run_on_start = false
```
#### 连接池参数
| 参数 | 值 | 说明 |
|------|-----|------|
| max_connections | 50 | 最大并发连接数 |
| min_connections | 5 | 最小空闲连接数 |
| acquire_timeout | 10s | 获取连接超时 |
| idle_timeout | 300s | 空闲连接回收 |
| max_lifetime | 1800s | 连接最大生命周期 |
#### Worker 系统
| Worker | 职责 | 触发方式 |
|--------|------|---------|
| LogOperationWorker | 异步写入操作日志 | Handler 派发 |
| CleanupRefreshTokensWorker | 清理过期 Refresh Token | Scheduler 定时 |
| CleanupRateLimitWorker | 清理过期限流条目 | Scheduler 定时 |
| RecordUsageWorker | 记录 Token 用量 | Relay Handler 派发 |
| UpdateLastUsedWorker | 更新 Key 最后使用时间 | Relay Handler 派发 |
| AggregateUsageWorker | 日/月用量聚合 | Scheduler 定时 |
| GenerateEmbeddingWorker | 知识条目 embedding 生成 | Handler 派发 |
#### SQL 迁移系统
- Schema 版本: **v8**
- 迁移目录: `crates/zclaw-saas/migrations/`
- 时间戳类型: **TIMESTAMPTZ** (新库)，向后兼容 TEXT (旧库)
- 迁移文件按文件名排序执行
---
## 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 消耗、延迟、成功率
- 按天聚合: 请求量、设备活跃度
- 审计摘要: 操作类型 + 结果
---
> **文档统计**: 131 个 API 端点 | 5 个通信通道 | 12 种权限 | 4 个独立服务 | 7 个 Workers | 声明式 Scheduler | SQL Schema v8

296
docs/features/V11_GAP_ANALYSIS.md
View File

@@ -1,296 +0,0 @@
# ZCLAW V11 差距分析报告
> **生成日期**: 2026-04-02
> **审计基线**: V10 AUDIT_TRACKER + V11 全面扫描
---
## 1. 五种差距模式总览
| 模式 | 数量 | 最高严重度 |
|------|------|-----------|
| 写了没接 | 8 项 | P3 |
| 接了没传 | 2 项 | **P1** |
| 传了没存 | 2 项 | P3 |
| 存了没用 | 3 项 | **P2** |
| 双系统不同步 | 5 项 | P3 |
---
## 2. 模式 1: "写了没接" (Wrote but Not Connected)
### 2.1 audit-logger.ts — 170 行完全孤立
**文件**: `desktop/src/lib/audit-logger.ts`
**严重度**: P3
完整的前端审计日志系统，包含 `FrontendAuditEntry` 类型、`AuditLogger` 类（log/logSuccess/logFailure/getLogs/clearLogs/exportLogs）、导出单例。
**验证**:
```bash
grep -rn "from.*audit-logger\|import.*audit-logger" desktop/src/ --include="*.ts" --include="*.tsx"
# 结果: 0 匹配
```
**影响**: 审计日志功能完全不可用，用户无法追溯操作历史。
**建议**:
- 方案 A: 在关键组件（ApprovalsPanel, AutonomyConfig, SecurityStore）中接入
- 方案 B: 如果当前不需要，标记为 `@internal reserved` 并从 barrel export 中移除
---
### 2.2 OFP 能力 — 类型定义无消费者
**文件**: `crates/zclaw-types/src/capability.rs:28-32`
**严重度**: P4
```rust
OfpDiscover,
OfpConnect { peer: String },
OfpAdvertise,
```
`Capability::grants()` 方法将这些变体匹配到 `_ => false`，意味着它们无法被授予或验证。
**建议**: 移除或添加 `// Reserved for OpenFang Protocol` 注释。
---
### 2.3 Director (multi-agent) — Feature-gated 912 行
**文件**: `crates/zclaw-kernel/src/director.rs`
**严重度**: P4 (保持 V10 DEAD-04)
22 个 `cfg(feature = "multi-agent")` 条目，完整的 Director 实现（5 种调度策略）。未在 Cargo.toml 中启用。
**建议**: 延后到产品路线图中多 Agent 功能启动时启用。
---
### 2.4 saas-admin.ts — 30 方法零消费者
**文件**: `desktop/src/lib/saas-admin.ts`
**严重度**: P2
30 个 Admin API 包装方法（providers/models/keys/accounts/tokens/roles/permissions），但：
- Desktop 前端不调用这些方法
- Admin-v2 有自己的 Axios service 层，不使用 saas-admin.ts
**文件头注释** (line 7-9):
> "Reserved for future admin UI (Next.js admin dashboard)."
**建议**: 删除整个文件，admin-v2 已有独立实现。避免维护两套代码。
---
### 2.5 Feature-gated 代码汇总
| 特性 | Crate | 代码量 | 状态 |
|------|-------|--------|------|
| multi-agent | zclaw-kernel | 22 cfg sites | 未启用 |
| a2a | zclaw-protocols | 2 cfg sites | 未启用 |
| wasm | zclaw-skills | 4 cfg sites | 未启用 |
---
### 2.6 62 个 Tauri 命令无前端调用
**分布**:
| 模块 | 未调用命令数 | 备注 |
|------|-------------|------|
| viking_commands | 11 | 完整 Viking 模块无 UI |
| pipeline_commands | 11 | 完整 Pipeline 模块无直接 invoke |
| gateway::commands | 11 | Gateway 连接管理 |
| classroom_commands | 7 (8 中仅 1 个被调用) | Classroom 功能 |
| LLM commands | 3 | llm_complete, embedding_create, embedding_providers |
| memory extractor | 2 | extract_session_memories, extract_and_store_memories |
| agent commands | 3 | export, import, agent_chat |
| kernel lifecycle | 2 | kernel_init, kernel_shutdown |
| 其他 | 12 | health, hand_run_cancel, scheduled_task 等 |
**注意**: pipeline 和 classroom 的 invoke 调用可能通过 store 或 client lib 间接调用，但 grep 未找到匹配。需手动验证。
---
## 3. 模式 2: "接了没传" (Connected but Not Passed)
### 3.1 trigger_update 参数嵌套问题 ⚠️ P1
**前端**: `desktop/src/lib/kernel-triggers.ts:99`
```typescript
return await invoke<TriggerItem>('trigger_update', { id, updates });
// updates = { name, enabled, handId, triggerType }
```
**Rust**: `desktop/src-tauri/src/kernel_commands/trigger.rs:183-189`
```rust
pub async fn trigger_update(
state: State<'_, KernelState>,
id: String,
name: Option<String>, // 期望扁平参数
enabled: Option<bool>,
hand_id: Option<String>,
) -> Result<TriggerResponse, String>
```
**问题**: 前端传递 `{ id, updates: { name, ... } }` 嵌套结构，但 Rust 期望 `{ id, name, enabled, hand_id }` 扁平参数。Tauri 的 serde 反序列化会忽略嵌套的 `updates` 对象，导致 name/enabled/hand_id 始终为 `None`。
**此外**: Rust 硬编码 `trigger_type: None`（trigger.rs:198），前端传递的 `triggerType` 永远被丢弃。
**影响**: Trigger 更新功能静默失败 — 用户修改 trigger 配置后不会生效。
**修复方案**: 前端改为扁平传递：
```typescript
await invoke('trigger_update', { id, name: updates.name, enabled: updates.enabled, handId: updates.handId });
```
---
### 3.2 hand_execute 参数名映射
**前端**: `desktop/src/lib/kernel-hands.ts:82`
```typescript
const result = await invoke('hand_execute', {
id: name, // 前端字段名 "id"
input: params || {},
...(autonomyLevel ? { autonomyLevel } : {}),
});
```
需验证 Rust 端是否接受 `id` 还是 `hand_name`。Tauri 自动做 camelCase ↔ snake_case 转换，但如果 Rust 使用 `name` 而前端使用 `id`，可能导致映射失败。
---
## 4. 模式 3: "传了没存" (Passed but Not Stored)
### 4.1 定时任务执行结果未持久化
**文件**: `crates/zclaw-saas/src/scheduler.rs:147-225`
`execute_scheduled_task` 执行任务后只更新 `last_run_at`、`next_run_at`、`run_count`，但不存储执行结果（成功/失败、输出、错误消息）。
`scheduled_tasks` 表 schema 缺少 `last_result`/`last_error` 列。
**影响**: 无法查看定时任务历史执行结果，无法诊断失败原因。
**建议**: 添加 `last_result TEXT` 和 `last_error TEXT` 列到 scheduled_tasks 表。
---
### 4.2 前端审计日志滞留 localStorage
`audit-logger.ts` 写入 localStorage，但无路径发送到后端或展示在 UI。数据在 `MAX_LOCAL_LOGS = 500` 条后循环覆盖。
---
## 5. 模式 4: "存了没用" (Stored but Not Used)
### 5.1 prompt_sync_status 表 — 零读取
**迁移**: `20260329000001_initial_schema.sql:244`
数据由 OTA 同步流程写入，但全代码库中无 `SELECT FROM prompt_sync_status`。
**可能原因**: OTA check 端点直接比较版本号而不查询此表。
**建议**: 移除死表，或实现读取路径。
---
### 5.2 telemetry_reports 表 — 零读取
**迁移**: `20260329000001_initial_schema.sql:305`
数据通过 telemetry 批量上报写入，但无查询路径。
**可能原因**: Admin dashboard 统计数据从 usage_records 聚合，不从此表读取。
**建议**: 实现读取端点供 admin-v2 telemetry 页面使用。
---
### 5.3 key_usage_window 表 — 零读取
**迁移**: `20260329000001_initial_schema.sql:274`
写入用于限流窗口追踪，但无 SELECT 查询。限流中间件可能使用内存中的 DashMap 而非数据库查询。
**建议**: 确认是否仍需要此表，或改用纯内存方案。
---
## 6. 模式 5: "双系统不同步" (Dual System Out of Sync)
### 6.1 Desktop ↔ Admin-v2 类型名称不一致（13+ 组）
| Admin-v2 名称 | Desktop 名称 | 实际差异 |
|---------------|-------------|----------|
| `AccountPublic` | `SaaSAccountInfo` | 命名 + llm_routing required/optional |
| `Provider` | `ProviderInfo` | 仅命名 |
| `Model` | `ModelInfo` | 仅命名 |
| `RelayTask` | `RelayTaskInfo` | 仅命名 |
| `ConfigItem` | `SaaSConfigItem` | 仅命名 |
| `OperationLog` | `OperationLogInfo` | 仅命名 |
| `PromptTemplate` | `PromptTemplateInfo` | 仅命名 |
| `PromptVersion` | `PromptVersionInfo` | 仅命名 |
| `AgentTemplate` | `AgentTemplateFull` | 命名 + 字段差异（admin 多 5 个字段） |
| `ApiError` | `SaaSErrorResponse` | 命名 + admin 多 status 字段 |
| `LoginResponse` | `SaaSLoginResponse` | 结构差异（cookie vs token） |
| `TokenInfo` | `TokenInfo` | nullability 差异 |
| `PaginatedResponse` | `PaginatedResponse` | **一致** |
### 6.2 有意义的字段差异
**AccountPublic.llm_routing**:
- Desktop: `llm_routing?: 'relay' | 'local'` (optional)
- Admin: `llm_routing: 'relay' | 'local'` (required)
**TokenInfo nullability**:
- Desktop: `last_used_at: string | null`, `expires_at: string | null`
- Admin: `last_used_at?: string`, `expires_at?: string`
**PromptVariable.type**:
- Desktop: `type: string`
- Admin: `type: 'string' | 'number' | 'select' | 'boolean'`
**AgentTemplate 字段差异**:
- Admin 额外: `visibility`, `status`, `current_version`, `version`, `capabilities`
- Desktop 缺少以上字段
### 6.3 文档数字不一致
| 指标 | 实际值 | 文档值 | 差异文件 |
|------|--------|--------|----------|
| Skills | 76 | 66/75/77 | SYSTEM_ARCHITECTURE.md, roadmap.md, troubleshooting.md |
| Hands | 9 目录 | 11 (CLAUDE.md) | CLAUDE.md 列出 11 个 Hand 配置 |
| Tauri 命令 | 175 | 58+ / 130+ | 06-tauri-backend/00-backend-integration.md |
| SaaS 路由 | 58 | 72+ | 08-saas-platform/00-saas-overview.md |
| Stores | 15 | 14 | 00-architecture/02-state-management.md |
---
## 7. Dead Code 完整清单
| 项 | 位置 | 行数 | 严重度 | 建议 |
|----|------|------|--------|------|
| audit-logger.ts | desktop/src/lib/ | 170 | P3 | 接入或删除 |
| saas-admin.ts | desktop/src/lib/ | 234 | P2 | 删除（admin-v2 已替代） |
| extract_structured_facts() | crates/zclaw-runtime/src/growth.rs:224 | ~30 | P4 | 删除 deprecated 方法 |
| secure-storage sync 方法 | desktop/src/lib/secure-storage.ts:309-325 | ~20 | P4 | 删除 |
| OFP 能力变体 | crates/zclaw-types/src/capability.rs:28-32 | 5 | P4 | 注释或移除 |
| Director feature-gated | crates/zclaw-kernel/src/director.rs | 912 | P4 | 保持，等路线图激活 |
| A2A feature-gated | crates/zclaw-protocols/src/a2a.rs | ~400 | P4 | 保持，等路线图激活 |
| WASM feature-gated | crates/zclaw-skills/src/wasm_runner.rs | ~200 | P4 | 保持，等路线图激活 |
---
## 8. Deprecated 代码状态
| 函数 | 位置 | 调用者 | 操作 |
|------|------|--------|------|
| `extract_structured_facts()` | growth.rs:224 | 0 | 删除 |
| `getStoredGatewayToken()` | gateway-storage.ts:129 | **3 活跃调用** | 先迁移调用者再删除 |
| `setStoredGatewayToken()` | gateway-storage.ts:196 | **1 活跃调用** | 先迁移调用者再删除 |
| `getSync()/setSync()/deleteSync()` | secure-storage.ts:309-325 | 0 | 删除 |

209
docs/features/V11_REMEDIATION_PLAN.md
View File

@@ -1,209 +0,0 @@
# ZCLAW V11 修复优先级计划
> **生成日期**: 2026-04-02
> **关联审计**: COMPREHENSIVE_AUDIT_V11.md + V11_GAP_ANALYSIS.md
---
## Sprint 分配建议
### Sprint 1 (P1 — 紧急修复)
#### V11-P1-01: trigger_update 参数修复
- **影响**: Trigger 配置更新静默失败
- **修复复杂度**: 低（1 文件修改）
- **文件**: `desktop/src/lib/kernel-triggers.ts:99`
- **方案**: 将嵌套 `updates` 对象展开为扁平参数
```typescript
// 修复前:
await invoke('trigger_update', { id, updates });
// 修复后:
await invoke('trigger_update', {
id,
name: updates.name,
enabled: updates.enabled,
handId: updates.handId,
});
```
- **同时修复**: Rust 端添加 `trigger_type` 参数支持（trigger.rs:183-189）
- **验证**: 修改 trigger 配置后检查 Kernel 状态
#### V11-P1-02: SaaS 配置同步传播
- **影响**: SaaS 管理员修改配置后不影响 Kernel 运行时
- **修复复杂度**: 中（需要新增 Tauri 命令或事件机制）
- **方案**:
- 选项 A: saasStore.pullConfig 完成后调用 Tauri command 通知 Kernel 重新加载配置
- 选项 B: Kernel 定期检查配置文件变更（watcher）
- 选项 C: 明确记录为 "前端缓存同步，不影响 Kernel"
- **建议**: 先选 C（文档对齐），后续迭代实现 A
- **验证**: 在 SaaS 后台修改配置 → 检查 Kernel 日志是否反映变更
#### V11-P1-03: 孤立 SQL 表处理
- **影响**: 数据写入但无法读取，浪费存储
- **修复复杂度**: 低
- **方案**:
- `prompt_sync_status`: 实现读取查询（OTA 端点需要）
- `telemetry_reports`: 添加 admin-v2 查询端点
- `key_usage_window`: 确认是否需要（限流可能已改用内存方案）
- **验证**: `grep -rn "SELECT.*FROM.*<table>" crates/zclaw-saas/src/` 有结果
---
### Sprint 2 (P2 — 高优先级)
#### V11-P2-01: 删除 saas-admin.ts
- **修复复杂度**: 低（删除 1 文件 + saas-client.ts 中的 install 调用）
- **前置条件**: 确认 admin-v2 完全不依赖此文件
- **验证**: admin-v2 所有页面功能正常
#### V11-P2-02: Role/Permission 管理
- **选项 A**: 为 admin-v2 添加 roles service 和页面
- **选项 B**: 移除 SaaS role 路由（如果当前不需要 RBAC）
- **建议**: 评估业务需求后决定
#### V11-P2-03: 迁移 deprecated gateway-storage 调用者
- **文件**: `gateway-client.ts:44,71,211`, `configStore.ts:252`
- **方案**: 将 sync 方法调用替换为 async 版本
- **验证**: Gateway 连接功能测试
#### V11-P2-04: ToolDefinition 去重
- **文件**: `zclaw-runtime/src/driver/mod.rs:94`
- **方案**: 重导出 `zclaw-types::tool::ToolDefinition`
- **验证**: `cargo build` 通过
#### V11-P2-05: 未调用 Tauri 命令评估
- **62 个命令**需逐一评估：
- classroom_*: 确认 classroomStore 是否真正调用（可能是 store 中调用的）
- pipeline_*: 确认 workflowStore 是否调用
- gateway_*: 确认是否有侧车进程调用
- viking_*: 确认 Settings 页面是否调用
- **验证**: 对每个命令 grep `invoke('command_name'`
#### V11-P2-06: SQL LIMIT 添加
- **文件**: `migration/service.rs`, `knowledge/service.rs`
- **方案**: 为 config_items SELECT 添加 LIMIT 1000，knowledge_categories 添加 LIMIT 100
- **验证**: SQL 执行计划验证
---
### Sprint 3 (P3 — 中优先级)
#### V11-P3-01: audit-logger 接入
- **方案**: 在 ApprovalsPanel、AutonomyConfig、chatStore 的关键操作中添加 logAudit 调用
- **或**: 标记为 reserved 并从 index 导出中移除
#### V11-P3-02: OFP 能力处理
- **方案**: 添加 `// Reserved for OpenFang Protocol` 注释或移除变体
#### V11-P3-03: 移除 deprecated extract_structured_facts
- **方案**: 删除 growth.rs:224 的 deprecated 方法
- **验证**: `cargo build` 通过
#### V11-P3-04: SaaS knowledge stub 实现
- **文件**: knowledge/handlers.rs:91,293,321
- **方案**: 实现真正的分页查询、回滚、推荐算法
- **验证**: admin-v2 Knowledge 页面功能测试
#### V11-P3-05: 定时任务执行结果持久化
- **方案**: 添加 last_result/last_error 列到 scheduled_tasks 表
- **迁移**: 新增 SQL migration
- **验证**: 创建定时任务 → 执行 → 检查结果是否存储
#### V11-P3-06 ~ P3-08: 其他清理
- 移除 secure-storage sync 方法
- 启用 embedding 生成或注释
- 清理 config 预留参数注释
---
### Sprint 4 (P4 — 低优先级 / 文档)
#### V11-P4-01: ContentBlock 命名规范
- **方案**: 为每个 crate 的 ContentBlock 添加 crate 前缀注释
- `zclaw_types::ContentBlock` = LLM 消息内容
- `zclaw_hands::ContentBlock` = 幻灯片渲染
- `zclaw_protocols::ContentBlock` = MCP 协议格式
#### V11-P4-02: 类型名称统一
- **方案**: 建立共享类型包 `@zclaw/types` 或使用 OpenAPI schema 生成
- 13+ 类型名称不一致需要协调
#### V11-P4-03: 文档数字更新
- Skills: 76
- Hands: 9 目录（CLAUDE.md 应更新 "11" → "9 目录 + 2 禁用配置"）
- Tauri 命令: 175
- SaaS 路由: 58
- Stores: 15
#### V11-P4-04/05: Feature-gated 代码保持现状
- Director/A2A/WASM: 等产品路线图决定
- Embedding 生成: 等 OpenViking 集成完成后启用
---
## 依赖关系图
```
V11-P1-01 (trigger_update 修复)
└── 无依赖，可独立完成
V11-P1-02 (配置同步传播)
└── 依赖设计决策（选项 A/B/C）
V11-P1-03 (孤立表处理)
└── V11-P2-06 (SQL LIMIT) 可同时处理
V11-P2-01 (删除 saas-admin.ts)
└── V11-P2-04 (ToolDefinition 去重) 可同时完成
V11-P2-03 (迁移 deprecated 调用)
└── 需要先确认 async 版本稳定性
V11-P3-04 (knowledge stub 实现)
└── 依赖 V11-P1-03（确认表用途后实现读取）
V11-P4-02 (类型统一)
└── 长期任务，不阻塞其他修复
```
---
## 修复工作量估算
| Sprint | 项数 | 预估工作量 | 风险等级 |
|--------|------|-----------|----------|
| Sprint 1 (P1) | 3 | 中 | 高（P1-02 需设计决策） |
| Sprint 2 (P2) | 6 | 高 | 中（P2-05 工作量大） |
| Sprint 3 (P3) | 8 | 中 | 低 |
| Sprint 4 (P4) | 5 | 低 | 低 |
---
## 验证检查清单
### 编译验证
```bash
cargo build --workspace
pnpm tsc --noEmit
```
### 功能验证
- [ ] 创建/更新/删除 Trigger → 检查 Kernel 状态
- [ ] SaaS 后台修改配置 → 检查 desktop 前端行为
- [ ] Admin-v2 Knowledge 页面 CRUD
- [ ] 定时任务执行 → 检查结果存储
- [ ] Agent 审批 → Hand 自动执行
- [ ] Pipeline 运行 → 完成事件通知
### 回归验证
```bash
# Rust 测试
cargo test --workspace
# 前端测试
pnpm vitest run
# Admin-v2 测试
cd admin-v2 && pnpm test
```

331
docs/features/VERIFICATION_REPORT.md
View File

@@ -1,331 +0,0 @@
# ZCLAW 功能验证报告
> **⚠️ ARCHIVED — 此报告已过时**
>
> 本报告验证于 2026-03-24 (v0.2.5)，声称 98.5% 通过率。
> 经 2026-03-27 深度审计确认：报告包含已删除功能（Team/Swarm），
> 模拟实现被标记为可用，多项结论不准确。
>
> **请以最新审计报告为准** → [DEEP_AUDIT_REPORT.md](./DEEP_AUDIT_REPORT.md)
---
> **验证日期**: 2026-03-24
> **验证版本**: v0.2.5
> **验证范围**: 所有已实现功能的完整性、可用性验证
---
## 一、验证概述
### 1.1 验证统计
| 模块 | 验证点 | 通过 | 失败 | 通过率 |
|------|--------|------|------|--------|
| 架构层 | 45 | 45 | 0 | 100% |
| 核心功能 | 17 | 17 | 0 | 100% |
| 智能层 | 36 | 36 | 0 | 100% |
| 技能系统 | 10 | 10 | 0 | 100% |
| Hands 系统 | 15 | 13 | 2 | 87% |
| 后端集成 | 12 | 12 | 0 | 100% |
| **总计** | **135** | **133** | **2** | **98.5%** |
### 1.2 总体结论
✅ **ZCLAW v0.2.5 功能验证通过**
- 所有核心功能完整可用
- 前后端正确集成
- 数据持久化机制正确
- 2 个已知问题（非阻塞）
---
## 二、Phase 1: 架构层验证
### 2.1 通信层验证 ✅
#### 2.1.1 LLM Driver 实现
| Driver | 文件 | 状态 | 支持的 Provider |
|--------|------|------|----------------|
| OpenAiDriver | `crates/zclaw-runtime/src/driver/openai.rs` | ✅ | OpenAI, Kimi, Qwen, DeepSeek, Zhipu |
| AnthropicDriver | `crates/zclaw-runtime/src/driver/anthropic.rs` | ✅ | Anthropic (Claude) |
| GeminiDriver | `crates/zclaw-runtime/src/driver/gemini.rs` | ✅ | Google Gemini |
| LocalDriver | `crates/zclaw-runtime/src/driver/local.rs` | ✅ | Ollama, Local |
**验证方法**: 代码审查 `driver/mod.rs`
```rust
// 验证的 Driver 配置
pub enum DriverConfig {
Anthropic { api_key: SecretString },
OpenAi { api_key: SecretString, base_url: Option<String> },
Gemini { api_key: SecretString },
Local { base_url: String },
}
```
#### 2.1.2 Tauri 命令实现
| 命令 | 状态 | 说明 |
|------|------|------|
| `kernel_init` | ✅ | 初始化内部 Kernel |
| `kernel_status` | ✅ | 获取 Kernel 状态 |
| `kernel_shutdown` | ✅ | 关闭 Kernel |
| `agent_create` | ✅ | 创建 Agent |
| `agent_list` | ✅ | 列出所有 Agent |
| `agent_get` | ✅ | 获取 Agent 详情 |
| `agent_delete` | ✅ | 删除 Agent |
| `agent_chat` | ✅ | 发送非流式消息 |
| `agent_chat_stream` | ✅ | 发送流式消息 |
| `skill_list` | ✅ | 列出技能 |
| `skill_refresh` | ✅ | 刷新技能目录 |
| `skill_execute` | ✅ | 执行技能 |
| `hand_list` | ✅ | 列出 Hands |
| `hand_execute` | ✅ | 执行 Hand |
**验证方法**: 代码审查 `kernel_commands.rs` (685 行)
#### 2.1.3 流式响应实现
| 事件类型 | 状态 | 说明 |
|---------|------|------|
| `Delta` | ✅ | 文本增量 |
| `ToolStart` | ✅ | 工具调用开始 |
| `ToolEnd` | ✅ | 工具调用结束 |
| `Complete` | ✅ | 流式完成 |
| `Error` | ✅ | 错误处理 |
**验证方法**: 代码审查 `StreamChatEvent` 枚举
---
### 2.2 状态管理验证 ✅
#### 2.2.1 Store 实现
| Store | 文件 | 持久化 | 状态 |
|-------|------|--------|------|
| chatStore | `desktop/src/store/chatStore.ts` | ✅ `zclaw-chat-storage` | ✅ |
| configStore | `desktop/src/store/configStore.ts` | ✅ | ✅ |
| connectionStore | `desktop/src/store/connectionStore.ts` | ❌ | ✅ |
| agentStore | `desktop/src/store/agentStore.ts` | ❌ | ✅ |
| handStore | `desktop/src/store/handStore.ts` | ❌ | ✅ |
| offlineStore | `desktop/src/store/offlineStore.ts` | ✅ | ✅ |
| sessionStore | `desktop/src/store/sessionStore.ts` | ❌ | ✅ |
| securityStore | `desktop/src/store/securityStore.ts` | ❌ | ✅ |
| workflowStore | `desktop/src/store/workflowStore.ts` | ❌ | ✅ |
| teamStore | `desktop/src/store/teamStore.ts` | ❌ | ✅ |
| gatewayStore | `desktop/src/store/gatewayStore.ts` | ❌ | ✅ |
| memoryGraphStore | `desktop/src/store/memoryGraphStore.ts` | ❌ | ✅ |
| activeLearningStore | `desktop/src/store/activeLearningStore.ts` | ❌ | ✅ |
| browserHandStore | `desktop/src/store/browserHandStore.ts` | ❌ | ✅ |
| skillMarketStore | `desktop/src/store/skillMarketStore.ts` | ❌ | ✅ |
**总计**: 16 个 Store (与文档一致)
#### 2.2.2 chatStore 持久化验证
```typescript
// 验证的持久化配置
{
name: 'zclaw-chat-storage',
partialize: (state) => ({
conversations: state.conversations,
currentModel: state.currentModel,
currentAgentId: state.currentAgent?.id,
currentConversationId: state.currentConversationId,
}),
onRehydrateStorage: () => (state) => {
// Date 对象恢复
// streaming 状态清除
}
}
```
✅ **验证通过**: partialize 和 onRehydrateStorage 正确实现
---
### 2.3 安全认证验证 ✅
| 验证项 | 状态 | 说明 |
|--------|------|------|
| 密钥生成 | ✅ | Ed25519 密钥对 |
| Keyring 集成 | ✅ | Windows DPAPI / macOS Keychain / Linux Secret Service |
| 降级策略 | ✅ | AES-GCM 加密 localStorage |
---
## 三、Phase 2: 核心功能验证
### 3.1 聊天界面 ✅
| 组件 | 文件 | 状态 |
|------|------|------|
| 聊天区域 | `ChatArea.tsx` | ✅ |
| 消息渲染 | `MessageItem.tsx` | ✅ |
| 输入框 | `ChatInput.tsx` | ✅ |
### 3.2 Agent 管理 ✅
| 组件 | 文件 | 状态 |
|------|------|------|
| Agent 创建向导 | `AgentOnboardingWizard.tsx` | ✅ |
| 人格预设 | `personality-presets.ts` | ✅ |
| 身份客户端 | `intelligence-client.ts` | ✅ |
### 3.3 多 Agent 协作 ✅
| 组件 | 文件 | 状态 |
|------|------|------|
| 协作仪表板 | `SwarmDashboard.tsx` | ✅ |
| 协作引擎 | `agent-swarm.ts` | ✅ |
| Swarm 类型 | `types/swarm.ts` | ✅ |
---
## 四、Phase 3: 智能层验证
### 4.1 后端 Rust 实现 ✅
| 模块 | 文件 | 状态 |
|------|------|------|
| 记忆命令 | `memory_commands.rs` | ✅ |
| 身份管理 | `intelligence/identity.rs` | ✅ |
| 反思引擎 | `intelligence/reflection.rs` | ✅ |
| 心跳引擎 | `intelligence/heartbeat.rs` | ✅ |
| 上下文压缩 | `intelligence/compactor.rs` | ✅ |
### 4.2 前端 UI 集成 ✅
| 组件 | 文件 | RightPanel Tab | 状态 |
|------|------|----------------|------|
| 记忆面板 | `MemoryPanel.tsx` | 'memory' | ✅ |
| 记忆图谱 | `MemoryGraph.tsx` | - | ✅ |
| 反思日志 | `ReflectionLog.tsx` | 'reflection' | ✅ |
| 自主配置 | `AutonomyConfig.tsx` | 'autonomy' | ✅ |
| 身份变更提案 | `IdentityChangeProposal.tsx` | 'identity' | ✅ |
**验证方法**: Grep 搜索 RightPanel.tsx 中的组件导入
---
## 五、Phase 4: 技能系统验证
### 5.1 技能发现 ✅
| 验证项 | 文档值 | 实际值 | 状态 |
|--------|--------|--------|------|
| SKILL.md 文件数 | 77 | **69** | ⚠️ 差异 |
**说明**: 文档记录 77 个技能，实际扫描发现 69 个。需要更新文档或补充缺失技能。
### 5.2 技能分类 ✅
| 分类 | 数量 | 代表技能 |
|------|------|---------|
| 开发工程 | 15 | senior-developer, frontend-developer, backend-architect |
| 营销/社媒 | 12 | twitter-engager, xiaohongshu-specialist, tiktok-strategist |
| 管理/PM | 8 | senior-pm, project-shepherd, agents-orchestrator |
| 数据分析 | 5 | analytics-reporter, data-analysis |
| 设计/UX | 5 | ui-designer, ux-architect |
### 5.3 execute_skill 工具 ✅
| 验证项 | 状态 |
|--------|------|
| Tauri 命令 | ✅ `skill_execute` |
| 上下文传递 | ✅ `SkillContext` |
| 结果返回 | ✅ `SkillResult` |
---
## 六、Phase 5: Hands 系统验证
### 6.1 Rust 实现 (9/11) ✅
| Hand | Rust 文件 | TOML 配置 | 状态 |
|------|----------|-----------|------|
| browser | `browser.rs` | ✅ | ✅ 可用 |
| researcher | `researcher.rs` | ✅ | ✅ 可用 |
| collector | `collector.rs` | ✅ | ✅ 可用 |
| slideshow | `slideshow.rs` | ✅ | ✅ 可用 |
| speech | `speech.rs` | ✅ | ✅ 可用 |
| quiz | `quiz.rs` | ✅ | ✅ 可用 |
| whiteboard | `whiteboard.rs` | ✅ | ✅ 可用 |
| clip | `clip.rs` | ✅ | ⚠️ 需 FFmpeg |
| twitter | `twitter.rs` | ✅ | ⚠️ 需 API Key |
### 6.2 未实现 (2/11) ❌
| Hand | TOML 配置 | Rust 实现 | 状态 |
|------|-----------|----------|------|
| predictor | ✅ | ❌ | 待实现 |
| lead | ✅ | ❌ | 待实现 |
---
## 七、Phase 6: 后端集成验证
### 7.1 Kernel 集成 ✅
| 验证项 | 状态 |
|--------|------|
| 内部 Kernel | ✅ `Kernel::boot()` |
| 多 LLM 支持 | ✅ 8+ Provider |
| Agent 生命周期 | ✅ spawn/kill |
| 流式响应 | ✅ Tauri events |
| MCP 协议 | ✅ 已实现 |
### 7.2 浏览器自动化 ✅
| 命令 | 状态 |
|------|------|
| `browser_create_session` | ✅ |
| `browser_navigate` | ✅ |
| `browser_click` | ✅ |
| `browser_type` | ✅ |
| `browser_screenshot` | ✅ |
| `browser_execute_script` | ✅ |
| `browser_scrape_page` | ✅ |
---
## 八、发现的问题
### 8.1 数据差异
| 问题 | 严重程度 | 说明 |
|------|---------|------|
| 技能数量差异 | 低 | 文档 77，实际 69 |
| Hands 未完成 | 低 | 2/11 未实现 (predictor, lead) |
### 8.2 建议修复
1. **更新文档**: 将技能数量从 77 更新为 69
2. **实现缺失 Hands**: predictor 和 lead 的 Rust 实现
---
## 九、验证结论
### 9.1 通过标准
| 指标 | 标准 | 实际 | 结果 |
|------|------|------|------|
| 功能完整性 | ≥ 95% | 98.5% | ✅ 通过 |
| 关键功能 | 100% | 100% | ✅ 通过 |
| 无阻塞性问题 | 0 High | 0 | ✅ 通过 |
| 数据持久化 | 100% | 100% | ✅ 通过 |
### 9.2 最终结论
**ZCLAW v0.2.5 功能验证通过** ✅
所有核心功能完整可用，前后端正确集成，数据持久化机制正确。发现的 2 个问题均为非阻塞性问题，不影响系统正常使用。
---
*验证报告生成时间: 2026-03-24*

256
docs/features/brainstorming-notes.md
View File

@@ -1,256 +0,0 @@
# ZCLAW 头脑风暴记录
> **日期**: 2026-03-16
> **参与者**: Claude AI Agent
> **目标**: 基于功能全景分析，探索未来发展方向
---
## 一、功能增强方向
### 1.1 智能层深化
| 想法 | 价值 | 难度 | 优先级 |
|------|------|------|--------|
| **记忆图谱** | 可视化记忆关系 | 中 | P2 |
| **主动学习** | 从用户行为学习 | 高 | P1 |
| **情感理解** | 识别用户情绪 | 高 | P2 |
| **预测行动** | 预测用户需求 | 高 | P1 |
**记忆图谱详细设计**:
```
用户 ──提到──► 项目A
│ │
└──偏好──► 简洁回答
│
└──应用于──► 项目A相关任务
```
**主动学习机制**:
1. 监控用户操作模式
2. 识别重复行为
3. 提出自动化建议
4. 学习用户反馈
### 1.2 协作能力扩展
| 想法 | 描述 | 价值 |
|------|------|------|
| **技能组合** | 多技能自动组合 | 复杂任务处理 |
| **竞标模式** | Agent 竞争执行 | 最优分配 |
| **投票决策** | 多 Agent 投票 | 集体智慧 |
| **专家咨询** | 按需调用专家 | 专业保障 |
**技能组合示例**:
```
任务: 设计并实现登录页面
│
├──► ux-architect: 设计交互流程
├──► ui-designer: 设计视觉元素
├──► frontend-developer: 实现代码
└──► security-engineer: 安全审查
```
### 1.3 自主能力增强
| 想法 | 描述 | 风险 |
|------|------|------|
| **自动任务分解** | AI 自动拆解任务 | 中 |
| **自我调试** | 自动发现和修复 bug | 高 |
| **知识自更新** | 自动学习新知识 | 中 |
| **性能自优化** | 自动调整配置 | 低 |
---
## 二、用户体验优化
### 2.1 交互体验
| 改进点 | 当前状态 | 目标状态 |
|--------|---------|---------|
| 流式响应 | 300ms 延迟 | <100ms |
| 记忆命中 | 75% | 90%+ |
| 技能发现 | 关键词匹配 | 语义理解 |
**交互优化想法**:
1. **打字动画优化**: 更自然的打字效果
2. **思考过程可视化**: 展示 Agent 思考过程
3. **快速操作**: 常用操作一键触达
4. **上下文悬浮**: 鼠标悬浮显示详细信息
### 2.2 视觉体验
| 改进点 | 描述 |
|--------|------|
| **主题系统** | 支持更多主题（暗色、亮色、高对比度） |
| **动画系统** | 流畅的页面过渡动画 |
| **图标系统** | 统一的图标风格 |
| **布局系统** | 可自定义的面板布局 |
### 2.3 反馈机制
| 类型 | 描述 |
|------|------|
| **即时反馈** | 操作后立即响应 |
| **进度反馈** | 长任务显示进度 |
| **结果反馈** | 任务完成通知 |
| **错误反馈** | 清晰的错误提示和恢复建议 |
---
## 三、技术架构演进
### 3.1 性能优化
| 优化方向 | 措施 | 预期收益 |
|---------|------|---------|
| **渲染优化** | 虚拟列表、懒加载 | 大数据流畅 |
| **网络优化** | 请求合并、缓存 | 减少延迟 |
| **存储优化** | 压缩、索引 | 减少占用 |
| **计算优化** | Web Worker、WASM | 不阻塞 UI |
### 3.2 可扩展性
| 扩展点 | 当前机制 | 改进方向 |
|--------|---------|---------|
| **技能系统** | SKILL.md 文件 | 支持动态加载 |
| **Hand 系统** | HAND.toml 文件 | 支持插件市场 |
| **主题系统** | Tailwind CSS | 支持用户自定义 |
| **协议系统** | 固定协议 | 支持协议扩展 |
### 3.3 可维护性
| 方向 | 措施 |
|------|------|
| **测试覆盖** | 保持 80%+ 覆盖率 |
| **文档完善** | 所有功能有文档 |
| **类型安全** | 严格的 TypeScript |
| **代码规范** | ESLint + Prettier |
---
## 四、商业化可能性
### 4.1 差异化卖点
| 卖点 | 竞争力 | 可行性 |
|------|--------|--------|
| **本地优先** | ⭐⭐⭐⭐⭐ | 高 |
| **记忆系统** | ⭐⭐⭐⭐ | 高 |
| **多 Agent 协作** | ⭐⭐⭐⭐ | 高 |
| **自主授权** | ⭐⭐⭐ | 中 |
| **技能生态** | ⭐⭐⭐⭐ | 中 |
### 4.2 产品化方向
| 方向 | 描述 | 目标用户 |
|------|------|---------|
| **个人版** | 单用户本地部署 | 个人开发者 |
| **团队版** | 多用户协作 | 小团队 |
| **企业版** | 安全合规、私有部署 | 企业 |
| **专业版** | 特定领域优化 | 专业用户 |
### 4.3 变现模式
| 模式 | 描述 | 可行性 |
|------|------|--------|
| **订阅制** | 按月/年收费 | 中 |
| **功能解锁** | 基础免费，高级收费 | 高 |
| **技能市场** | 技能交易抽成 | 低 |
| **企业支持** | 技术支持服务 | 高 |
---
## 五、待讨论问题汇总
### 5.1 产品层面
1. **目标用户定位**: 个人 vs 团队 vs 企业？
2. **核心价值主张**: 效率 vs 隐私 vs 智能？
3. **竞品差异化**: vs ChatGPT vs Claude vs Cursor？
### 5.2 技术层面
1. **记忆存储**: 本地 vs 云端 vs 混合？
2. **模型策略**: 单一模型 vs 多模型切换？
3. **安全策略**: 完全本地 vs 可选同步？
### 5.3 商业层面
1. **开源策略**: 完全开源 vs 核心闭源？
2. **定价策略**: 免费 vs 付费 vs 混合？
3. **推广策略**: 开发者优先 vs 企业优先？
---
## 六、行动计划
### 6.1 短期 (1-2 周)
- [ ] 完善功能文档
- [ ] 优化记忆检索算法
- [ ] 添加用户反馈入口
### 6.2 中期 (1-2 月)
- [ ] 实现技能市场 MVP
- [ ] 优化多 Agent 协作体验
- [ ] 添加更多 Hands
### 6.3 长期 (3-6 月)
- [ ] 企业版功能规划
- [ ] 云端同步功能
- [ ] 移动端适配
---
## 七、风险评估
### 7.1 技术风险
| 风险 | 概率 | 影响 | 缓解措施 |
|------|------|------|---------|
| LLM API 变更 | 中 | 高 | 抽象层隔离 |
| 性能瓶颈 | 中 | 中 | 监控和优化 |
| 安全漏洞 | 低 | 高 | 安全审计 |
### 7.2 产品风险
| 风险 | 概率 | 影响 | 缓解措施 |
|------|------|------|---------|
| 用户需求变化 | 高 | 中 | 敏捷迭代 |
| 竞品压力 | 高 | 中 | 差异化定位 |
| 采用率低 | 中 | 高 | 用户调研 |
### 7.3 商业风险
| 风险 | 概率 | 影响 | 缓解措施 |
|------|------|------|---------|
| 变现困难 | 中 | 高 | 多元化收入 |
| 成本失控 | 中 | 中 | 成本监控 |
| 合规问题 | 低 | 高 | 法务咨询 |
---
## 八、灵感收集
### 8.1 用户反馈期望
- "希望 Agent 能记住更多上下文"
- "协作功能很强大，但 UI 可以更直观"
- "本地运行很安心，但希望能同步到其他设备"
### 8.2 竞品启发
- **Cursor**: 代码补全体验
- **Claude**: 长上下文处理
- **Perplexity**: 搜索增强
### 8.3 未来愿景
> ZCLAW 成为开发者的 AI 伙伴，不仅理解代码，更理解开发者的意图和偏好，在保护隐私的前提下，提供智能、自主、可信的 AI 能力。
---
*文档结束*