docs(wiki): 全量代码验证驱动更新 — 10页基于实际扫描非文档推测
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

关键数字修正:
- Rust 74.5K行(原66K), Tauri命令 183(原182), SaaS路由 121
- 前端组件 104, lib/ 85文件, Store 17+4子store
- TODO/FIXME 仅 8 个(前端4+Rust4)

内容增强:
- 中间件完整14层注册清单含注册条件和优先级分类
- Store完整目录结构, Pipeline完整目录树
- Hands测试分布, Memory 16个Tauri命令列表
- 管家模式: 关键词路由→语义路由(TF-IDF)修正
- 代码健康度指标新增
This commit is contained in:
iven
2026-04-11 01:05:15 +08:00
parent 36a1c87d87
commit b3f97d6525
12 changed files with 415 additions and 132 deletions

View File

@@ -8,34 +8,51 @@ status: active
> 面向中文用户的 AI Agent 桌面客户端。管家模式 + 多模型 + 9 自主能力 + 75 技能。
> **使用方式**: 找到你要处理的模块,读对应页面,直接开始工作。
> **数据来源**: 2026-04-11 代码全量扫描验证,非文档推测。
## 项目画像
| 维度 | 值 |
|------|-----|
| 定位 | AI Agent 桌面客户端 (Tauri 2.x) |
| 技术栈 | Rust 10 crates (~66K行) + React 19 + TypeScript + PostgreSQL |
| 技术栈 | Rust 10 crates (~74.5K行) + React 19 + TypeScript + PostgreSQL |
| 阶段 | 发布前稳定化,功能冻结中 |
## 关键数字
## 关键数字2026-04-11 代码验证)
Rust Crates: 10 | 测试: 822 | Tauri 命令: 182 | SaaS API: 140 | Store: 18 | 中间件: 14 | Hands: 9 | Skills: 75 | Pipeline: 17
| 指标 | 值 | 验证方式 |
|------|-----|----------|
| Rust Crates | 10 | `ls crates/zclaw-*/Cargo.toml` |
| Rust 代码 | 74,487 行 | `find crates/ -name "*.rs" \| xargs wc -l` |
| Rust #[test] | 431 个 | `grep '#\[test\]' crates/**/*.rs` |
| Tauri 命令 | 183 (含5 feature-gated) | `lib.rs generate_handler![]` 注册 |
| 前端 invoke 调用 | 105 处 | `grep invoke( desktop/src/` |
| SaaS .route() | 121 个 | `grep .route( crates/zclaw-saas/` |
| 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 | `ls desktop/src/store/` |
| React 组件 | 104 个 (.tsx/.ts) | `find desktop/src/components/` |
| Admin V2 页面 | 15 个 (.tsx) | `ls admin-v2/src/pages/` |
| 中间件 | 14 层 (含1个条件注册) | `kernel/mod.rs create_middleware_chain` |
| 前端 lib/ | 85 个 .ts | `find desktop/src/lib/` |
| TODO/FIXME | 前端 4 + Rust 4 = 8 | `grep TODO/FIXME` |
## 模块导航树
```
ZCLAW
├── [[routing]] 客户端路由 — 4分支决策SaaS Relay是主路径
│ └── [[chat]] 聊天系统 — 3种ChatStreamSaaS Token Pool是主路径
│ └── [[chat]] 聊天系统 — 3种ChatStreamStore拆为4+1
├── [[saas]] SaaS平台 — 认证/Token池/计费/AdminTauri的中枢
│ ├── 认证 JWT + Cookie + Token池 RPM/TPM轮换
│ ├── 计费 配额实时递增 + Alipay/WeChat
│ └── Admin V2 15页管理后台
├── [[butler]] 管家模式 — 默认交互范式,4域路由+冷启动+痛点
├── [[butler]] 管家模式 — 默认交互范式,语义路由+冷启动+痛点
├── [[middleware]] 中间件链 — 14层DataMasking→ButlerRouter→TrajectoryRecorder
├── [[middleware]] 中间件链 — 14层按优先级分类注册
├── [[memory]] 记忆管道 — 对话→提取→FTS5+TF-IDF→检索→注入
@@ -54,9 +71,12 @@ ZCLAW
→ 因为 SaaS Token Pool 集中管理 API Key支持用量追踪、计费、模型白名单。直连是降级后备。
**Q: 为什么有3种 ChatStream**
→ GatewayClient(WS) 用于外部进程KernelClient(Tauri Event) 用于桌面端SaaSRelay(SSE) 用于浏览器。Tauri 桌面端的 KernelClient 通过 `baseUrl` 指向 SaaS relay 实现间接中转。
→ GatewayClient(WS) 用于外部进程KernelClient(Tauri Event) 用于桌面端SaaSRelayGatewayClient(SSE) 用于浏览器。Tauri 桌面端的 KernelClient 通过 `baseUrl` 指向 SaaS relay 实现间接中转。
**Q: 为什么管家模式是默认?**
→ 面向医院行政等非技术用户,4域关键词分类+痛点积累+方案生成,降低使用门槛。
→ 面向医院行政等非技术用户,语义路由(75技能TF-IDF)+痛点积累+方案生成,降低使用门槛。
> 数字真相源: `docs/TRUTH.md` — 如有冲突以 TRUTH.md 为准
**Q: 为什么中间件是14层**
→ 按优先级分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 仅在有技能时注册。
> 数字真相源: `docs/TRUTH.md` — 如有冲突以代码实际为准