e790cf171a
Some checks failed
CI / Lint & TypeCheck (push) Has been cancelled
CI / Unit Tests (push) Has been cancelled
CI / Build Frontend (push) Has been cancelled
CI / Rust Check (push) Has been cancelled
CI / Security Scan (push) Has been cancelled
CI / E2E Tests (push) Has been cancelled
受 Karpathy LLM Wiki 启发，将分散在 docs/ + memory/ + CLAUDE.md 的项目知识 编译为 8 个结构化 wiki 页面，解决新会话冷启动时上下文浪费问题。 - wiki/index.md: 主索引入口 (~200行)，CLAUDE.md @import 自动加载 - wiki/architecture.md: 系统架构编译 (crate依赖/客户端路由/聊天流/LLM驱动) - wiki/module-status.md: 9个子系统状态 + Hands详情 + 测试覆盖 - wiki/data-flows.md: 6条核心数据流 (聊天/路由/记忆/认证/管家/Pipeline) - wiki/development.md: 开发规范 (闭环工作法/验证命令/提交规范) - wiki/known-issues.md: 缺陷状态 (P0/P1已修复，P2待处理) - wiki/file-map.md: 代码库文件地图 (crates/desktop/admin-v2/docs) - wiki/log.md: Append-only 变更日志 - CLAUDE.md: 添加 @wiki/index.md + §8.3 收尾流程增加 wiki 维护步骤
97 lines
3.3 KiB
Markdown
97 lines
3.3 KiB
Markdown
---
|
||
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 为准
|