36a1c87d87
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
问题: 旧 wiki 按文档类型组织（architecture/data-flows/file-map）， 修复 Butler Router 需要读 4 个文件才能拼凑全貌。 且 SaaS Relay 主路径 vs 本地降级的优先级描述不准确。 重构为模块化结构，每个模块页自包含： - 设计思想: 为什么这样设计 - 代码逻辑: 数据流 + 关键代码 - 关联模块: 依赖关系 新增模块页: - routing.md: 客户端路由 (明确 SaaS Relay 是主路径，不是本地模式) - chat.md: 聊天系统 (3种实现 + Token Pool 中转机制) - butler.md: 管家模式 (路由/冷启动/痛点/双模式UI) - memory.md: 记忆管道 (提取→FTS5→检索→注入) - saas.md: SaaS平台 (认证/Token池/计费/Admin) - middleware.md: 中间件链 (14层 + 优先级) - hands-skills.md: Hands(9) + Skills(75) - pipeline.md: Pipeline DSL 删除旧文件: architecture.md, data-flows.md, module-status.md, file-map.md (内容已分布到对应模块页中) 添加 .gitignore 排除 Obsidian 工作区状态文件
63 lines
2.5 KiB
Markdown
63 lines
2.5 KiB
Markdown
---
|
||
title: ZCLAW 项目知识库
|
||
updated: 2026-04-11
|
||
status: active
|
||
---
|
||
|
||
# ZCLAW 项目知识库
|
||
|
||
> 面向中文用户的 AI Agent 桌面客户端。管家模式 + 多模型 + 9 自主能力 + 75 技能。
|
||
> **使用方式**: 找到你要处理的模块，读对应页面，直接开始工作。
|
||
|
||
## 项目画像
|
||
|
||
| 维度 | 值 |
|
||
|------|-----|
|
||
| 定位 | AI Agent 桌面客户端 (Tauri 2.x) |
|
||
| 技术栈 | Rust 10 crates (~66K行) + React 19 + TypeScript + PostgreSQL |
|
||
| 阶段 | 发布前稳定化，功能冻结中 |
|
||
|
||
## 关键数字
|
||
|
||
Rust Crates: 10 | 测试: 822 | Tauri 命令: 182 | SaaS API: 140 | Store: 18 | 中间件: 14 | Hands: 9 | Skills: 75 | Pipeline: 17
|
||
|
||
## 模块导航树
|
||
|
||
```
|
||
ZCLAW
|
||
├── [[routing]] 客户端路由 — 4分支决策，SaaS Relay是主路径
|
||
│ └── [[chat]] 聊天系统 — 3种ChatStream，SaaS Token Pool是主路径
|
||
│
|
||
├── [[saas]] SaaS平台 — 认证/Token池/计费/Admin，Tauri的中枢
|
||
│ ├── 认证 JWT + Cookie + Token池 RPM/TPM轮换
|
||
│ ├── 计费 配额实时递增 + Alipay/WeChat
|
||
│ └── Admin V2 15页管理后台
|
||
│
|
||
├── [[butler]] 管家模式 — 默认交互范式，4域路由+冷启动+痛点
|
||
│
|
||
├── [[middleware]] 中间件链 — 14层，DataMasking→ButlerRouter→TrajectoryRecorder
|
||
│
|
||
├── [[memory]] 记忆管道 — 对话→提取→FTS5+TF-IDF→检索→注入
|
||
│
|
||
├── [[hands-skills]] Hands(9) + Skills(75) — 自主能力+语义技能路由
|
||
│
|
||
├── [[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) 用于桌面端，SaaSRelay(SSE) 用于浏览器。Tauri 桌面端的 KernelClient 通过 `baseUrl` 指向 SaaS relay 实现间接中转。
|
||
|
||
**Q: 为什么管家模式是默认？**
|
||
→ 面向医院行政等非技术用户，4域关键词分类+痛点积累+方案生成，降低使用门槛。
|
||
|
||
> 数字真相源: `docs/TRUTH.md` — 如有冲突以 TRUTH.md 为准
|