---
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]]