2f5e9f1755
5.4 KiB
title, updated, status
| title | updated | status |
|---|---|---|
| ZCLAW 项目知识库 | 2026-04-19 | active |
ZCLAW 项目知识库
面向中文用户的 AI Agent 桌面客户端。管家模式 + 多模型 + 7 自主能力 + 75 技能。 使用方式: 找到你要处理的模块，读对应页面，直接开始工作。 数据来源: 2026-04-19 代码全量扫描验证，非文档推测。
项目画像
| 维度 | 值 |
|---|---|
| 定位 | AI Agent 桌面客户端 (Tauri 2.x) |
| 技术栈 | Rust 10 crates + src-tauri (~102K行, 357 .rs文件) + React 19 + TypeScript + PostgreSQL |
| 阶段 | 发布前稳定化，功能冻结中 |
关键数字（2026-04-19 代码验证）
| 指标 | 值 | 验证方式 |
|---|---|---|
| Rust Crates | 10 + src-tauri | ls crates/zclaw-*/Cargo.toml |
| Rust 代码 | 101,967 行 (80,754 crates + 21,213 src-tauri, 357 .rs文件) | wc -l (2026-04-19 验证) |
| Rust 测试 | 987 (640 #[test] + 347 #[tokio::test]) | grep '#\[test\]' 含 src-tauri (2026-04-19 验证) |
| Rust 测试通过 | 797 workspace (sqlx 0.8 升级后) | cargo test --workspace --exclude zclaw-saas |
| Tauri 命令 | 190 定义 | grep '#\[.*tauri::command' (2026-04-16 验证) |
| 前端 invoke 调用 | 104 处 / 91 唯一命令 | grep invoke( desktop/src/ (2026-04-19 验证) |
| @reserved 标注 | 97 个 (孤儿命令 ~0) | grep @reserved src-tauri/ (2026-04-19 验证) |
| SaaS .route() | 137 个 | grep .route( crates/zclaw-saas/ (2026-04-16 验证) |
| SaaS 模块 | 16 个目录 | ls crates/zclaw-saas/src/*/ (2026-04-19 验证) |
| SKILL 目录 | 75 个 | ls -d skills/*/ |
| HAND 配置 | 6 TOML + 1 系统内部 (_reminder) = 7 注册 | ls hands/*.HAND.toml + kernel registry |
| Pipeline YAML | 18 个 (8 目录) | find pipelines/ -name "*.yaml" (2026-04-19 验证) |
| Zustand Store | 25 个 (.ts, 含子目录 saas/5) | find desktop/src/store/ (2026-04-19 验证) |
| React 组件 | 102 个 (.tsx/.ts, 11 子目录) | find desktop/src/components/ (2026-04-19 验证) |
| Admin V2 页面 | 17 个 (.tsx) | ls admin-v2/src/pages/ (2026-04-19 验证) |
| 中间件 | 15 层 runtime + 10 层 SaaS HTTP | chain.register 计数 (2026-04-19 验证) |
| 前端 lib/ | 75 个 .ts (71 顶层 + workflow-builder/3 + tests/1) | find desktop/src/lib/ (2026-04-19 验证) |
| SQL 迁移 | 38 文件 (21 up + 17 down) / 42 CREATE TABLE | ls crates/zclaw-saas/migrations/*.sql (2026-04-19 验证) |
| Intelligence | 16 个 .rs 文件 | ls src-tauri/src/intelligence/ (2026-04-19 验证) |
| Cargo Warnings | 0 (非 SaaS) | cargo check --workspace --exclude zclaw-saas |
| TODO/FIXME | 前端 1 + Rust 1 = 2 | grep TODO/FIXME (2026-04-19 验证) |
| dead_code | 0 个 | grep '#\[dead_code\]' (2026-04-19 验证) |
模块导航树
ZCLAW
├── [[routing]] 客户端路由 — 5分支+降级，SaaS Relay是主路径
│ └── [[chat]] 聊天系统 — 3种ChatStream，Store拆为4+1
│
├── [[saas]] SaaS平台 — 认证/Token池/计费/Admin，Tauri的中枢
│ ├── 认证 JWT + Cookie + Token池 RPM/TPM轮换
│ ├── 计费 配额实时递增 + Alipay/WeChat
│ └── Admin V2 17页管理后台
│
├── [[butler]] 管家模式 — 默认交互范式，语义路由+冷启动+痛点
│
├── [[middleware]] 中间件链 — 15层runtime + 10层SaaS HTTP
│
├── [[memory]] 记忆管道 — 对话→提取→FTS5+TF-IDF→检索→注入+进化引擎
│
├── [[hands-skills]] Hands(7注册) + Skills(75) + MCP — 自主能力+语义技能+外部工具协议
│
├── [[pipeline]] Pipeline DSL — YAML+DAG执行器+18模板
│
├── [[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: 为什么中间件是15层runtime？ → 按优先级分6类: 78进化(Evolution) → 80-99路由+脱敏(Butler/DataMasking) → 100-199上下文(Compaction/Memory/Title) → 200-399能力(SkillIndex/DanglingTool/ToolError/ToolOutputGuard) → 400-599安全(Guardrail/LoopGuard/SubagentLimit) → 600-799遥测(TrajectoryRecorder/TokenCalibration)。另有 10 层 SaaS HTTP 中间件 (限流/认证/配额/CORS/日志等)。
Q: zclaw-growth 的进化引擎做什么？ → EvolutionEngine 负责从对话历史中检测行为模式变化，生成进化候选项（如新技能建议、工作流优化），通过 EvolutionMiddleware@78 注入 system prompt。配合 FeedbackCollector、PatternAggregator、QualityGate、SkillGenerator、WorkflowComposer 形成自我改进闭环。
数字真相源:
docs/TRUTH.md— 如有冲突以代码实际为准