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

# ZCLAW 项目知识库

> 面向中文用户的 AI Agent 桌面客户端。管家模式 + 多模型 + 9 自主能力 + 75 技能。

## 一句话画像

Rust 10 crates (~66K行) + React 19 + Tauri 2.x + PostgreSQL + Axum。发布前稳定化阶段，功能冻结中。

## 关键数字

| 维度 | 数量 |
|------|------|
| Rust Crates | 10 |
| Rust 代码 | ~66,000 行 |
| Rust 测试 | 822 (684 workspace + 138 SaaS) |
| Tauri 命令 | 182 (92 有前端调用, 20 @reserved, 70 孤儿) |
| SaaS API | 140 端点 |
| SaaS 数据表 | 34 |
| Zustand Store | 18 |
| React 组件 | ~135 |
| 中间件层 | 14 |
| SKILL.md | 75 |
| Hands | 9 启用 + 2 禁用 |
| Pipeline 模板 | 17 YAML |
| LLM Provider | 8 |

## 核心架构 → [[architecture]]

- **客户端路由**: Admin / SaaS Relay / Local Kernel / External Gateway
- **聊天流**: GatewayClient(WS) / KernelClient(Tauri Event) / SaaSRelay(HTTP SSE)
- **LLM 驱动**: Anthropic / OpenAI / Gemini / Local + 国内 3 家(DeepSeek/Qwen/Moonshot)
- **管家模式**: ButlerRouter 4域分类 + 冷启动 4阶段 + 双模式UI

## 子系统状态 → [[module-status]]

| 子系统 | 状态 | 说明 |
|--------|------|------|
| 管家模式 (Butler) | 活跃 | ButlerRouter + 冷启动 + 简洁UI + 痛点持久化 |
| Hermes 管线 | 活跃 | ExperienceStore + UserProfiler + NlScheduleParser + TrajectoryRecorder |
| 聊天流 (ChatStream) | 稳定 | 3 种实现，5min 超时守护 |
| 记忆管道 (Memory) | 稳定 | 对话→提取→FTS5+TF-IDF→检索→注入 |
| SaaS 认证 (Auth) | 稳定 | Token池 RPM/TPM 轮换 + JWT pwv 失效 |
| Pipeline DSL | 稳定 | 17 模板 + DAG 执行器 |
| Hands 系统 | 稳定 | 9 启用 |
| 技能系统 | 稳定 | 75 SKILL.md + 语义路由 |
| 中间件链 | 稳定 | 14 层 (含 DataMasking@90, ButlerRouter, TrajectoryRecorder@650) |

## 核心数据流 → [[data-flows]]

```
用户操作 → React UI → Zustand Store → Tauri Commands → Kernel → LLM/Tools/Skills/Hands
```

- 4 种 LLM Driver，国内兼容通过 base_url
- SaaS unreachable 时自动降级到本地 Kernel
- 记忆闭环: 对话 → extraction → FTS5+TF-IDF → 检索 → 注入 system prompt

## 开发须知 → [[development]]

- **闭环工作法**: 定位→修复→验证→提交→文档，每步不可跳过
- **功能冻结**: 禁止新增 SaaS API / SKILL.md / Tauri 命令 / 中间件 / admin 页面
- **验证命令**: `cargo check --workspace` / `pnpm tsc --noEmit` / `pnpm vitest run`

## 已知问题 → [[known-issues]]

- 所有 P0/P1 已修复
- 10 项 P2 代码质量问题待处理
- 70 个 Tauri 命令孤儿（无前端调用且无 @reserved）

## 文件地图 → [[file-map]]

关键路径速查，按 `crates/` / `desktop/src/` / `admin-v2/` 组织。

## 变更日志 → [[log]]

Append-only 操作记录。

---

## 给新会话的快速引导

1. 先读本文件 (你正在读)
2. 需要了解架构 → 读 [[architecture]]
3. 需要了解某模块状态 → 读 [[module-status]]
4. 需要了解数据流 → 读 [[data-flows]]
5. 需要开发 → 读 [[development]]
6. 需要知道有哪些 bug → 读 [[known-issues]]
7. 需要找文件 → 读 [[file-map]]

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