---
title: ZCLAW 项目知识库
updated: 2026-04-14
status: active
---

# ZCLAW 项目知识库

> 面向中文用户的 AI Agent 桌面客户端。管家模式 + 多模型 + 9 自主能力 + 75 技能。
> **使用方式**: 找到你要处理的模块，读对应页面，直接开始工作。
> **数据来源**: 2026-04-14 代码全量扫描验证，非文档推测。

## 项目画像

| 维度 | 值 |
|------|-----|
| 定位 | AI Agent 桌面客户端 (Tauri 2.x) |
| 技术栈 | Rust 10 crates + src-tauri (~77K行, 274 .rs文件) + React 19 + TypeScript + PostgreSQL |
| 阶段 | 发布前稳定化，功能冻结中 |

## 关键数字（2026-04-15 代码验证）

| 指标 | 值 | 验证方式 |
|------|-----|----------|
| Rust Crates | 10 + src-tauri | `ls crates/zclaw-*/Cargo.toml` |
| Rust 代码 | 77,444 行 (274 .rs文件) | `find crates/ src-tauri/ -name "*.rs"` |
| Rust 测试 | 774 (433 #[test] + 341 #[tokio::test]) | `grep '#\[test\]' / '#\[tokio::test\]'` |
| Tauri 命令 | 182 定义 | `grep '#\[tauri::command\]'` |
| 前端 invoke 调用 | 95 处 | `grep invoke( desktop/src/` |
| SaaS .route() | 137 个 | `grep .route( crates/zclaw-saas/` |
| SaaS 模块 | 16 个目录 (含 industry) | `ls crates/zclaw-saas/src/*/` |
| SKILL 目录 | 75 个 | `ls -d skills/*/` |
| HAND 配置 | 9 个 (TOML) | `ls hands/*.HAND.toml` |
| Pipeline YAML | 17 个 | `find pipelines/ -name "*.yaml"` |
| Zustand Store | 17 文件 + chat/4子store = 21 (含 industryStore) | `find desktop/src/store/` |
| React 组件 | 104 个 (.tsx/.ts) | `find desktop/src/components/` |
| Admin V2 页面 | 17 个 (.tsx) | `ls admin-v2/src/pages/` |
| 中间件 | 14 层 runtime + 10 层 SaaS HTTP | `kernel/mod.rs` + `zclaw-saas middleware` |
| 前端 lib/ | 85 个 .ts | `find desktop/src/lib/` |
| SQL 迁移 | 20 文件 / 42 CREATE TABLE | `ls crates/zclaw-saas/migrations/*.sql` |
| @reserved 标注 | 89 个 (孤儿命令 0) | `grep @reserved desktop/src-tauri/src/` |
| Cargo Warnings | 0 (非 SaaS, 仅 sqlx 外部) | `cargo check --workspace --exclude zclaw-saas` |
| TODO/FIXME | 前端 1 + Rust 3 = 4 | `grep TODO/FIXME` |

## 模块导航树

```
ZCLAW
├── [[routing]]        客户端路由 — 4分支决策，SaaS Relay是主路径
│   └── [[chat]]       聊天系统 — 3种ChatStream，Store拆为4+1
│
├── [[saas]]           SaaS平台 — 认证/Token池/计费/Admin，Tauri的中枢
│   ├── 认证           JWT + Cookie + Token池 RPM/TPM轮换
│   ├── 计费           配额实时递增 + Alipay/WeChat
│   └── Admin V2       15页管理后台
│
├── [[butler]]         管家模式 — 默认交互范式，语义路由+冷启动+痛点
│
├── [[middleware]]     中间件链 — 14层runtime + 10层SaaS HTTP
│
├── [[memory]]         记忆管道 — 对话→提取→FTS5+TF-IDF→检索→注入
│
├── [[hands-skills]]   Hands(9) + Skills(75) + MCP — 自主能力+语义技能+外部工具协议
│
├── [[pipeline]]       Pipeline DSL — YAML+DAG执行器+17行业模板
│
├── [[development]]    开发规范 — 闭环工作法/验证命令/提交规范
├── [[known-issues]]   已知问题 — P0/P1已修复，P2待处理
└── [[log]]            变更日志 — append-only
```

## 核心架构决策（为什么这样设计）

**Q: 为什么 Tauri 不直连 LLM？**
→ 因为 SaaS Token Pool 集中管理 API Key，支持用量追踪、计费、模型白名单。直连是降级后备。

**Q: 为什么有3种 ChatStream？**
→ GatewayClient(WS) 用于外部进程，KernelClient(Tauri Event) 用于桌面端，SaaSRelayGatewayClient(SSE) 用于浏览器。Tauri 桌面端的 KernelClient 通过 `baseUrl` 指向 SaaS relay 实现间接中转。

**Q: 为什么管家模式是默认？**
→ 面向医院行政等非技术用户，语义路由(75技能TF-IDF)+痛点积累+方案生成，降低使用门槛。

**Q: 为什么中间件是14层runtime？**
→ 按优先级分4类: 100-199上下文(compaction/memory) → 200-399能力(skill/guardrail) → 400-599安全(loop_guard/data_masking) → 600-799遥测(token/title/trajectory)。Kernel `create_middleware_chain()` 条件注册，skill_index 仅在有技能时注册。另有 10 层 SaaS HTTP 中间件 (限流/认证/配额/CORS/日志等)。

> 数字真相源: `docs/TRUTH.md` — 如有冲突以代码实际为准