zclaw_openfang/wiki/index.md

title, updated, status

title	updated	status
ZCLAW 项目知识库	2026-04-14	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 命令	183 定义	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 组件	105 个 (.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/	76 个 .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 — 如有冲突以代码实际为准