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 维护步骤
148 lines
4.5 KiB
Markdown
148 lines
4.5 KiB
Markdown
---
|
||
title: 系统架构
|
||
updated: 2026-04-11
|
||
status: active
|
||
tags: [architecture, core]
|
||
---
|
||
|
||
# 系统架构
|
||
|
||
> 从 [[index]] 导航到此处。详细架构参考: `docs/ARCHITECTURE_BRIEF.md`
|
||
|
||
## Crate 依赖关系
|
||
|
||
```
|
||
zclaw-types (L1: 基础类型, 无依赖)
|
||
↑
|
||
zclaw-memory (L2: SQLite, KV, 会话)
|
||
↑
|
||
zclaw-runtime (L3: 4 Driver, 7 工具, 14 中间件)
|
||
↑
|
||
zclaw-kernel (L4: 182 Tauri 命令, 核心协调)
|
||
↑
|
||
zclaw-saas (独立: Axum + PostgreSQL, 端口 8080)
|
||
↑
|
||
desktop/src-tauri (集成: kernel + skills + hands + protocols)
|
||
```
|
||
|
||
并行 crates (不依赖 runtime):
|
||
- `zclaw-skills` — 75 SKILL.md 解析 + 语义路由
|
||
- `zclaw-hands` — 9 自主能力
|
||
- `zclaw-protocols` — MCP 完整 + A2A feature-gated
|
||
- `zclaw-pipeline` — Pipeline DSL v1/v2 + DAG 执行器
|
||
- `zclaw-growth` — 记忆增长 (FTS5 + TF-IDF + Embedding trait)
|
||
|
||
## 客户端路由 (4 分支)
|
||
|
||
```
|
||
getClient()
|
||
├── [1] Admin 路由: localStorage llm_routing → relay/local
|
||
├── [2] SaaS Relay: SaaS不可达→降级到本地 Kernel
|
||
├── [3] Local Kernel: Tauri 内置 (桌面端默认)
|
||
└── [4] External Gateway: WebSocket/REST fallback
|
||
```
|
||
|
||
关键文件: `desktop/src/store/connectionStore.ts:844`
|
||
|
||
## 聊天流 (3 种实现)
|
||
|
||
| 实现 | 传输 | 场景 |
|
||
|------|------|------|
|
||
| GatewayClient | WebSocket | 外部 Gateway 进程 |
|
||
| KernelClient | Tauri Event | 内置 Kernel (默认) |
|
||
| SaaSRelay | HTTP SSE | 浏览器端 SaaS 中继 |
|
||
|
||
统一回调: `{ onDelta, onThinkingDelta, onTool, onHand, onComplete, onError }`
|
||
5 分钟超时守护: `desktop/src/lib/kernel-chat.ts:76`
|
||
|
||
## LLM 驱动 (4 + 3)
|
||
|
||
### Rust Driver
|
||
|
||
| Driver | 文件 | 协议 |
|
||
|--------|------|------|
|
||
| AnthropicDriver | `crates/zclaw-runtime/src/driver/anthropic.rs` | Anthropic Messages |
|
||
| OpenAiDriver | `crates/zclaw-runtime/src/driver/openai.rs` | OpenAI Chat |
|
||
| GeminiDriver | `crates/zclaw-runtime/src/driver/gemini.rs` | Google Gemini |
|
||
| LocalDriver | `crates/zclaw-runtime/src/driver/local.rs` | Ollama |
|
||
|
||
### 国内兼容 (通过 OpenAI 协议 + base_url)
|
||
|
||
| Provider | base_url |
|
||
|----------|----------|
|
||
| DeepSeek | `https://api.deepseek.com` |
|
||
| Qwen/GLM | `https://dashscope.aliyuncs.com/compatible-mode/v1` |
|
||
| Moonshot | `https://api.moonshot.cn/v1` |
|
||
|
||
API Key → OS keyring (`secure-storage.ts`)
|
||
|
||
## 管家模式 (默认激活)
|
||
|
||
```
|
||
用户消息 → ButlerRouter (4域关键词分类) → 增强 system prompt → LLM
|
||
↓
|
||
PainAggregator → PainStorage (内存+SQLite)
|
||
↓
|
||
SolutionGenerator (痛点→方案)
|
||
```
|
||
|
||
- 冷启动: idle → greeting_sent → waiting_response → completed
|
||
- UI 双模式: simple (纯聊天, 默认) / professional (完整功能)
|
||
- ButlerRouter 文件: `crates/zclaw-runtime/src/middleware/butler_router.rs`
|
||
|
||
## 记忆管道 (闭环)
|
||
|
||
```
|
||
对话 → extraction_adapter (LLM 提取)
|
||
→ FTS5 全文索引 + TF-IDF 权重
|
||
→ 检索 (查询时召回)
|
||
→ 注入 system prompt (token 预算控制)
|
||
```
|
||
|
||
- EmbeddingClient trait 已定义但未激活
|
||
- zclaw-saas 有 pgvector HNSW 索引就绪，embedding 生成 deferred
|
||
|
||
## SaaS 认证
|
||
|
||
| 数据 | 存储 |
|
||
|------|------|
|
||
| JWT Token | OS Keyring |
|
||
| 账户信息 | localStorage |
|
||
| Cookie | HttpOnly + Secure + SameSite=Strict |
|
||
|
||
- JWT password_version: 改密码→所有旧 JWT 失效
|
||
- Token 池: RPM/TPM 限流轮换
|
||
- SaaS unreachable → 自动降级本地 Kernel
|
||
|
||
## 中间件链 (14 层)
|
||
|
||
关键中间件:
|
||
- DataMasking@90 — 请求前数据脱敏
|
||
- ButlerRouter — 4域关键词分类 + system prompt 增强
|
||
- TrajectoryRecorder@650 — 轨迹记录压缩
|
||
|
||
## 关键文件速查
|
||
|
||
### 前端
|
||
|
||
| 文件 | 职责 |
|
||
|------|------|
|
||
| `desktop/src/store/connectionStore.ts` | 客户端路由 |
|
||
| `desktop/src/store/chat/streamStore.ts` | 流式消息编排 |
|
||
| `desktop/src/store/chat/conversationStore.ts` | 会话管理 |
|
||
| `desktop/src/store/saasStore.ts` | SaaS 认证 |
|
||
| `desktop/src/store/uiModeStore.ts` | 简洁/专业模式 |
|
||
| `desktop/src/hooks/use-cold-start.ts` | 管家冷启动 |
|
||
|
||
### 后端
|
||
|
||
| 文件 | 职责 |
|
||
|------|------|
|
||
| `crates/zclaw-kernel/src/kernel/mod.rs` | Kernel 启动 |
|
||
| `crates/zclaw-runtime/src/loop_runner.rs` | 主聊天循环 |
|
||
| `crates/zclaw-saas/src/auth/handlers.rs` | SaaS 认证 |
|
||
| `desktop/src-tauri/src/lib.rs` | Tauri 命令注册 |
|
||
|
||
→ 数据流细节见 [[data-flows]]
|
||
→ 模块状态见 [[module-status]]
|