# ZCLAW 系统真相文档

> **更新日期**: 2026-04-15
> **数据来源**: V11 全面审计 + 二次审计 + V12 模块化端到端审计 + 代码全量扫描验证 + 功能测试 Phase 1-5 + 发布前功能测试 Phase 3 + 发布前全面测试代码级审计 + 2026-04-11 代码验证 + V13 系统性功能审计 2026-04-12 + V13 审计修复 2026-04-13 + 发布前冲刺 Day1 2026-04-15
> **规则**: 此文档是唯一真相源。所有其他文档如果与此冲突，以此为准。

---

## 1. 量化指标（已验证）

| 指标 | 实际值 | 验证方式 |
|------|--------|----------|
| Rust Crates | 10 个 (编译通过) | `cargo check --workspace` |
| Rust 代码行数 | ~77,000 (crates) + ~61,400 (src-tauri) = ~138,400 | wc -l (2026-04-12 V13 验证) |
| Rust 单元测试 | 433 个 (#[test]) + 368 个 (#[tokio::test]) = 801 | `grep '#\[test\]' crates/` + `grep '#\[tokio::test\]'` (2026-04-12 V13 验证) |
| Cargo Warnings (非 SaaS) | **0 个** (仅 sqlx-postgres 外部依赖 1 个) | `cargo check --workspace --exclude zclaw-saas` (2026-04-15 清零) |
| Rust 测试运行通过 | 684 workspace + 138 SaaS = 822 | Hermes 4 Chunk `cargo test --workspace` 2026-04-09 |
| Tauri 命令 | 182 个 (2026-04-15 发布前冲刺验证) | `grep '#\[.*tauri::command'` |
| **Tauri 命令有前端调用** | **95 处** | `grep invoke( desktop/src/` (2026-04-15 验证) |
| **Tauri 命令已标注 @reserved** | **89 个** | Rust 源码 @reserved 标注 (2026-04-15 全量标注) |
| **Tauri 命令孤儿 (无调用+无标注)** | **0 个** | 182 - 95 invoke处 - 89 @reserved = 0 (2026-04-15 清零) |
| SKILL.md 文件 | 75 个 | `ls skills/*.md \| wc -l` |
| Hands 启用 | 9 个 | Browser/Collector/Researcher/Clip/Twitter/Whiteboard/Slideshow/Speech/Quiz（均有 HAND.toml） |
| Hands 禁用 | 2 个 | Predictor, Lead（概念定义存在，无 TOML 配置文件或 Rust 实现） |
| Pipeline 模板 | 17 个 YAML | `pipelines/` 目录全量统计（含 _templates/ 和 design-shantou/ 子目录） |
| SaaS API 端点 | 136 个 .route() | `grep .route( crates/zclaw-saas/` (2026-04-12 V13 验证) |
| SaaS 路由模块 | 12 个 + industry | account/agent_template/auth/billing/knowledge/migration/model_config/prompt/relay/role/scheduled_task/telemetry/industry（scheduled_task: 后端 5 CRUD + Admin V2 前端 service/page/route/nav） |
| SaaS 数据表 | 34 个（含 saas_schema_version） | CREATE TABLE 全量统计 |
| SaaS Workers | 7 个 | log_operation/cleanup_rate_limit/cleanup_refresh_tokens/record_usage/update_last_used/aggregate_usage/generate_embedding |
| LLM Provider | 8 个 | Kimi/Qwen/DeepSeek/Zhipu/OpenAI/Anthropic/Gemini/Local |
| Zustand Store | 21 个 | find desktop/src/store/ -name "*.ts" (2026-04-12 V13 验证) |
| React 组件 | 104 个 (.tsx/.ts) | find desktop/src/components/ (2026-04-11 验证) |
| 前端 TypeScript 测试 | 31 个文件 (6 store + 5 lib + 1 config + 1 stabilization + 18 E2E spec) | Phase 3-4 全量 |
| 前端 lib | 83 个 .ts | find desktop/src/lib/ (2026-04-11 验证) |
| 前端测试运行通过 | 344 passed + 1 skipped | `pnpm vitest run` (2026-04-15 验证) |
| 生产构建 | **通过** (14.8s, 0 require 残留) | `pnpm build` (2026-04-15 验证) |
| Admin V2 页面 | 15 个 | admin-v2/src/pages/ 全量统计（含 ScheduledTasks、ConfigSync） |
| 桌面端设置页面 | 19 个 | SettingsLayout.tsx tabs: 通用/用量统计/积分详情/模型与API/MCP服务/技能/IM频道/工作区/数据与隐私/安全存储/SaaS平台/订阅与计费/语义记忆/安全状态/审计日志/定时任务/心跳配置/提交反馈/关于 |
| Admin V2 测试 | 17 个文件 (61 tests) | vitest 统计 |
| 中间件层 | 15 层 | 运行时注册（含 DataMasking@90, ButlerRouter@500, TrajectoryRecorder@650 — V13注册） |

---

## 2. 端到端可用功能

以下功能经过代码验证，从前端到后端完整连通：

### 2.1 确认可用

| 功能 | 路径 | 验证状态 |
|------|------|----------|
| 智能对话 | UI → chatStore → Tauri → Kernel → LLM Driver → 流式返回 | ✅ 代码完整 |
| Agent 分身管理 | UI → agentStore → Tauri → Kernel | ✅ 代码完整 |
| 模型切换 | UI → Settings → config.toml → Kernel | ✅ 代码完整 |
| Hand 触发 | UI → handStore → Tauri → Kernel → Hand 执行 | ✅ 代码完整 |
| Hand 审批 | UI → approvalStore → Tauri → Kernel | ✅ 代码完整 |
| 记忆搜索 | UI → memoryStore → Tauri → Growth → FTS5 | ✅ 代码完整 |
| 配置读写 | UI → Settings → config.toml | ✅ 代码完整 |
| SaaS 登录/注册 | UI → saasStore → SaaS API → PostgreSQL | ✅ 代码完整 |
| SaaS 配置同步 | UI → saasStore → SaaS API → Store 更新 | ✅ 代码完整 |
| Admin V2 管理 | admin-v2 → SaaS API → PostgreSQL | ✅ 代码完整 |
| 支付集成 | Admin → SaaS → Alipay/WeChat API | ✅ 代码完整 |

### 2.2 有已知缺陷

> **2026-04-03 更新**: 以下 P0/P1 缺陷已全部修复（详见 §3.1/3.2），本节保留仅作历史记录。

| 功能 | 原问题 | 修复状态 |
|------|--------|----------|
| Skill 执行 | 前端传空 context → Rust 反序列化失败 | ✅ 已修复 (SEC2-P0-01) |
| Hand 异步结果 | Rust emit 事件但前端无 listen() | ✅ 已修复 (SEC2-P1-03) |
| Agent 模板 | API 路径缺 /api/v1 前缀 → 404 | ✅ 已修复 (SEC2-P1-02) |
| Trigger 更新 | 参数格式不匹配 → 静默失败 | ✅ 已修复 (V11-P1-01) |

### 2.3 已实现但未接通前端

| 功能 | Rust 状态 | 前端状态 |
|------|-----------|----------|
| Pipeline 执行 | DSL 引擎完整 | **已接通前端** (8 个 invoke 调用匹配 8 个 Rust 命令，已确认可用) |
| Viking 适配 | FTS5 + TF-IDF | 5 个孤立 invoke 已清理，新增 addWithMetadata/storeWithSummaries 方法 + UI |
| Classroom | 27 个命令 | 7 个命令无前端调用（classroom_list/generation_progress 等已标注 @reserved） |
| Browser Hand | 22 个命令 | 部分无前端调用 |
| Multi-agent Director | 912 行 (feature-gated) | 未启用 |

### 2.4 前端孤立 invoke 调用（已清理）

Viking 5 个孤立 invoke 调用已于 2026-04-03 清理移除：
- `viking_add_inline`, `viking_server_start`, `viking_server_status`, `viking_server_stop`, `viking_server_restart`

当前无已知前端孤立 invoke 调用。

---

## 3. 已知缺陷清单

### 3.1 P0 — 必然崩溃

| ID | 问题 | 状态 |
|----|------|------|
| SEC2-P0-01 | skill_execute 反序列化崩溃 | **已修复** — kernel-skills.ts 注入真实 agentId/sessionId，workingDir 改为 null |
| SEC2-P0-02 | TaskTool::default() panic | **已修复** — 移除 impl Default |

### 3.2 P1 — 功能失效

| ID | 问题 | 状态 |
|----|------|------|
| SEC2-P1-01 | FactStore trait 零实现 | **已修复** — 移除死 trait，保留值类型 |
| SEC2-P1-02 | agent-templates 路径错误 | **已修复** — saas-client.ts 已添加 /api/v1 |
| SEC2-P1-03 | hand-execution-complete 无监听 | **已修复** — ChatArea 添加 Tauri 事件监听 + streamStore.cancelStream 补全 |
| SEC2-P1-04 | InMemoryStorage RwLock unwrap 级联 | **已修复** — 7 处改为 .expect() |
| SEC2-P1-05~07 | HandRun 持久化静默忽略 (3处) | **已修复** — tracing::warn! |
| SEC2-P1-08 | FTS 索引更新静默失败 | **已修复** — tracing::warn! |
| SEC2-P1-09 | Worker dispatch 静默失败 | **已修复** — tracing::warn! |

### 3.3 P1.5 — 代码质量补充修复

| ID | 问题 | 状态 |
|----|------|------|
| SEC2-P1.5-01 | Capability _ => false 通配符 | **已修复** — 3 个方法改为穷举匹配，grants() 保留通配符+注释说明 |
| SEC2-P1.5-02 | billing let _ = ... ? 冗余模式 | **已修复** — 移除冗余 let _ = |
| SEC2-P1.5-03 | relay SSE 错误路径 send 失败未记录 | **已修复** — 改为 if let Err + tracing::debug! |
| SEC2-P1.5-04 | WASM runner 缺少状态注解 | **已修复** — 添加 active module 说明 |
| SEC2-P1.5-05 | Tauri 命令无连接状态标注 | **已修复** — 177 个命令完整审计（160 @connected / 16 @reserved / 1 未注册 identity_init） |
| SEC2-P1.5-06 | extract_token_usage 静默丢弃解析错误 | **已修复** — 添加 tracing::debug! |
| SEC2-P1.5-07 | relay current_key_id 防御性 unwrap | **已修复** — 改为 ok_or_else 返回内部错误 |

### 3.3 P2 — 代码质量

| ID | 问题 |
|----|------|
| SEC2-P2-01~10 | 10 项代码质量问题（详见二次审计） |

---

## 4. 死代码清单

| 文件/目录 | 行数 | 状态 | 建议 |
|-----------|------|------|------|
| `desktop/src/lib/audit-logger.ts` | 170 | **已删除** | - |
| `desktop/src/lib/saas-admin.ts` | 234 | 已在之前清理中删除 | - |
| `desktop/src/lib/gateway-reconnect.ts` | ~100 | **已删除** (零生产引用) | - |
| `admin/` | 整目录 | **已删除** (空目录壳) | - |
| `admin-temp-dir/` | 整目录 | **已删除** | - |
| `crates/zclaw-channels/` | Cargo.toml only | 已在之前清理中删除 | - |
| `docs/analysis/ISSUE-TRACKER.md` | - | **已删除** | - |
| Director multi-agent | 912 | feature-gated off + 已注解 | 保留 |
| A2A 协议 | ~400 | feature-gated off + 已注解 | 保留 |
| WASM runner | ~200 | **Active module** + 已注解 | 保留 |
| `crates/zclaw-saas/src/webhook/` | ~400 | **死代码**: 未在 lib.rs pub mod 注册，未在 main.rs merge()，无前端调用 | 删除 |
| `crates/zclaw-saas/src/workers/webhook_delivery.rs` | ~160 | **死代码**: 未在 workers/mod.rs pub mod 注册 | 删除 |
| `admin-v2/src/components/StatusTag.tsx` | ~20 | **孤立组件**: 从未被导入 | 删除 |

---

## 4.5 近期前端改进 (2026-04-03)

| 改进 | 说明 |
|------|------|
| Pipeline 前端接通 | 8 个前端 invoke 调用匹配 8 个 Rust 命令，完整可用 |
| Viking 孤立调用清理 | 5 个无后端实现的 invoke 已移除 |
| Viking 新方法 | `addWithMetadata`, `storeWithSummaries` 新增，含 UI |
| api-fallbacks 标记 | `_isFallback` markers + `console.warn` logging |
| MessageSearch 恢复 | ChatArea 头部搜索按钮，功能完整 |
| scheduled_task Admin V2 | 后端 5 CRUD 端点完成，Admin V2 前端 service + page + route + nav 已添加 |

---

## 5. 文档漂移记录

以下文档中的数字已与实际不符，需要校准（2026-04-03 已全部修正）：

| 文档 | 过时内容 | 正确值 | 状态 |
|------|----------|--------|------|
| CLAUDE.md (旧版) | "React 18" | React 19 | ✅ 已修正 |
| CLAUDE.md (旧版) | "Tailwind CSS" | Tailwind 4 | ✅ 已修正 |
| CLAUDE.md (旧版) | "Next.js (admin/)" | Vite + Ant Design Pro (admin-v2/) | ✅ 已修正 |
| features/README.md | SaaS API: 58 | 131 | ✅ 已修正 |
| features/README.md | Tauri 命令: 175 | 171 | ✅ 已修正 |
| features/README.md | SaaS Workers: 5 | 7 | ✅ 已修正 |
| features/README.md | SKILL: 76 | 75 | ✅ 已修正 |
| docs/README.md | Crates: 8 | 10 | ✅ 已修正 |

---

## 6. 更新日志

| 日期 | 更新内容 |
|------|----------|
| 2026-04-02 | 初始创建，基于 V11 全面审计 + 二次审计数据 |
| 2026-04-02 | P0 全部修复 (SEC2-P0-01/02)；P1 全部修复 (SEC2-P1-01~09) |
| 2026-04-02 | P1.5 代码质量修复：capability 穷举匹配、SaaS 静默错误、WASM 注解、Tauri 命令标注 |
| 2026-04-02 | 深度审计后修正：8 个 Tauri 标注误标、4 处 SaaS let _ = 清理、TRUTH.md 路由数 58→93 |
| 2026-04-02 | 二次深度审计：(1) 再修正 11 个 Tauri 标注 (147 connected / 24 reserved = 171) (2) 修正文档数字 SKILL 75/Stores 18/Admin 13 (3) relay extract_token_usage + current_key_id 防御性修复 (4) 记录 5 个前端孤立 invoke 调用 |
| 2026-04-02 | 构建验证通过：cargo check ✅ + tsc --noEmit ✅ |
| 2026-04-03 | 数字全面验证校准：SaaS API 93→131 (新增 knowledge 23 + billing 10 + role 11 等模块增长)、Rust 测试 584→383、React 组件 ~50→~135、前端测试 21→23、SaaS Workers 5→7 (新增 aggregate_usage/generate_embedding)、SaaS 路由模块 10→12、数据表 25→34 |
| 2026-04-03 | 前端改进记录：(1) Pipeline 8 invoke 接通前端 (2) Viking 5 孤立 invoke 清理 + 2 新方法+UI (3) api-fallbacks _isFallback 标记 + console.warn 日志 (4) MessageSearch 恢复到 ChatArea (5) scheduled_task Admin V2 完整接入 (service+page+route+nav) |
| 2026-04-04 | V12 模块化审计后更新：(1) Pipeline 模板 10→17 YAML (2) Hands 禁用说明细化（无 TOML/Rust 实现） (3) SEC2-P1-01 FactStore 标记 FALSE_POSITIVE (4) V11-P1-03 SQL 表标记 FALSE_POSITIVE (5) M11-02 map_err 已修复 (6) M4-04 深层 WONTFIX |
| 2026-04-05 | Admin V2 页面数 14→15（新增 ConfigSync 页面）；桌面端设置页面确认为 19 个 |
| 2026-04-06 | 全面一致性审查：(1) Tauri 命令 177→183 (grep 重新验证) (2) SaaS API 131→130 (webhook 5 路由已定义但未挂载) (3) 删除 webhook 死代码模块 + webhook_delivery worker (4) admin-v2 权限模型修复 (6+ permission key 补全) (5) Logs.tsx 代码重复消除 (6) 清理未使用 service 方法 (agent-templates/billing/roles) |
| 2026-04-07 | 管家能力激活：(1) Tauri 命令 183→189 (+6: 5 butler + 1 butler_delegate_task) (2) multi-agent feature 默认启用 (3) Director butler_delegate + ExpertTask (4) ButlerPanel UI 3 区 (洞察/方案/记忆) (5) 人格检测器 personality_detector.rs (6) DataMaskingMiddleware@90 |
| 2026-04-07 | 功能测试 Phase 1-5 全部完成：(1) Phase 1 SaaS 68 tests (2) Phase 2 Admin V2 61 tests (3) Phase 3 Store 单元 112 tests (4) Phase 4 E2E 场景 47 tests (5) Phase 5 全量回归 1048 tests 全通过 (580 Rust + 138 SaaS + 330 Desktop)。修复 4 个生产 bug：usage/telemetry SQL timestamptz 类型转换缺失、config seed 断言、key_value 长度校验 |
| 2026-04-09 | Hermes Intelligence Pipeline 4 Chunk 完成：(1) Chunk1 ExperienceStore+Extractor (10 tests) (2) Chunk2 UserProfileStore+Profiler (14 tests) (3) Chunk3 NlScheduleParser (16 tests) (4) Chunk4 TrajectoryRecorder+Compressor (18 tests)。中间件 13→14 层 (+TrajectoryRecorder@650)。Schema v2→v4 (user_profiles + trajectory tables)。全量 684 tests 0 failed |
| 2026-04-10 | 发布前修复批次：(1) ButlerRouter 语义路由 — SemanticSkillRouter TF-IDF 替代关键词，75 技能参与路由 (2) P1-04 AuthGuard 竞态 — 三态守卫 + cookie 先验证 (3) P2-03 限流 — Cross 测试共享 token (4) P1-02 浏览器聊天 — Playwright SaaS fixture。BREAKS.md 全部 P0/P1/P2 已修复 |
| 2026-04-11 | 发布前数字校准：(1) Rust 代码 66K→74.6K (2) Rust 测试 537→798 (#[test] 431 + #[tokio::test] 367) (3) Tauri 命令 182→184 (4) 前端 invoke 92→105 (5) @reserved 20→33 (6) SaaS .route() 140→122 (7) Zustand Store 18→20 (8) React 组件 135→104 (9) 前端 lib 85→83 (10) Cargo.toml 版本 0.1.0→0.9.0-beta.1 |
| 2026-04-12 | V13 系统性功能审计数字校准：(1) Tauri 命令 184→191 (2) 前端 invoke 105→106 (3) @reserved 33→24 (Butler/MCP已接通) (4) 孤儿命令 ~46→~61 (5) Rust 测试 798→801 (433+368) (6) SaaS .route() 122→136 (7) Zustand Store 20→21 (8) dead_code 76→43 (9) Rust LOC crates ~74.6K→~77K |