# ZCLAW 架构概览

> **永久最新参考文档** — 每次重大变更后由 auto-sync 更新。
> 最后更新: 2026-04-09
> 详细功能文档见 [docs/features/](features/README.md)

---

## 1. 管家模式 (Butler Mode)

管家模式是 ZCLAW 的核心交互范式，默认激活。

### 架构组件

| 组件 | 文件 | 职责 |
|------|------|------|
| ButlerRouter | `crates/zclaw-runtime/src/middleware/butler_router.rs` | 关键词4域分类 (healthcare/data_report/policy/meeting)，增强 system prompt |
| PainStorage | `crates/zclaw-kernel/src/intelligence/pain_storage.rs` | 痛点双写 (内存 Vec 热缓存 + SQLite 持久层)，全局 `PAIN_STORAGE` 单例 |
| SolutionGenerator | `crates/zclaw-kernel/src/intelligence/solution_generator.rs` | 基于痛点生成解决方案提案 |
| Cold Start Hook | `desktop/src/hooks/use-cold-start.ts` | 4阶段: idle→greeting_sent→waiting_response→completed |
| UI Mode Store | `desktop/src/store/uiModeStore.ts` | 双模式切换: 'simple'(默认, 纯聊天) / 'professional'(完整功能) |
| SimpleSidebar | `desktop/src/components/SimpleSidebar.tsx` | 简洁模式侧边栏 |

### 数据流

```
用户消息 → ButlerRouter (关键词分类) → 增强 system prompt → LLM → 响应
                                                              ↓
                                              PainAggregator → PainStorage (内存+SQLite双写)
                                                              ↓
                                              SolutionGenerator (基于痛点生成提案)
```

---

## 2. 聊天流 (ChatStream)

3 种 ChatStream 实现，由 `getClient()` 路由决定使用哪种。

### 实现对比

| 实现 | 类 | 传输协议 | 使用场景 |
|------|------|----------|----------|
| GatewayClient.chatStream | `desktop/src/lib/gateway-client.ts` | WebSocket | 外部 ZCLAW Gateway 进程 |
| KernelClient.chatStream | `desktop/src/lib/kernel-chat.ts` | Tauri Event | 内置 Kernel (桌面端默认) |
| SaaSRelay.chatStream | `desktop/src/lib/saas-relay-client.ts` | HTTP SSE | 浏览器端 SaaS 中继 |

### 统一回调接口

所有实现共享相同的 callback 结构:

```ts
{ onDelta, onThinkingDelta, onTool, onHand, onComplete, onError }
```

### StreamStore 发送流程

```
streamStore.sendMessage(content)
  → effectiveSessionKey = conversationStore.sessionKey || crypto.randomUUID()
  → effectiveAgentId = resolveGatewayAgentId(currentAgent)
  → client.chatStream(content, callbacks, { sessionKey, agentId, chatMode... })
  → 5-minute timeout guard (kernel-chat.ts:76) 防止流挂起
```

---

## 3. LLM 驱动 (Provider Drivers)

### 4 个 Rust Driver

| Driver | 文件 | 协议 |
|--------|------|------|
| AnthropicDriver | `crates/zclaw-runtime/src/driver/anthropic.rs` | Anthropic Messages API |
| OpenAiDriver | `crates/zclaw-runtime/src/driver/openai.rs` | OpenAI Chat Completions API |
| GeminiDriver | `crates/zclaw-runtime/src/driver/gemini.rs` | Google Gemini API |
| LocalDriver | `crates/zclaw-runtime/src/driver/local.rs` | Ollama (localhost:11434) |

### Driver Factory

```
LlmConfig::create_driver()
  match api_protocol:
    Anthropic → AnthropicDriver (base_url 为空时用原生 SDK)
    OpenAI    → OpenAiDriver (base_url 可指向兼容端点)
```

### 国内 Provider (通过 OpenAI 兼容协议)

| Provider | base_url |
|----------|----------|
| DeepSeek | `https://api.deepseek.com` |
| Qwen/GLM | `https://dashscope.aliyuncs.com/compatible-mode/v1` |
| Moonshot | `https://api.moonshot.cn/v1` |

### 前端模型配置

```
CustomModel { id, name, provider, apiKey, apiProtocol, baseUrl }
```

API Key 存储在 OS keyring (非 localStorage)，通过 `secure-storage.ts` 管理。

---

## 4. 客户端路由 (Client Routing)

### 路由决策树

```
connectionStore.connect(url?, token?)
  │
  ├── [1] Admin 路由: localStorage('zclaw-saas-account').llm_routing
  │     relay → SaaS Relay 模式
  │     local  → Kernel 模式 (adminForcedLocal=true)
  │
  ├── [2] SaaS Relay: localStorage('zclaw-connection-mode') === 'saas'
  │     health check → 不可达时降级到本地 Kernel
  │     Tauri: KernelClient + SaaS baseUrl
  │     Browser: SaaSRelayGatewayClient (SSE)
  │
  ├── [3] Local Kernel: isTauriRuntime() === true
  │     KernelClient + 自定义模型配置
  │
  └── [4] External Gateway (fallback)
        GatewayClient via WebSocket/REST
```

### 客户端类型

| 客户端 | 传输 | 用途 |
|--------|------|------|
| GatewayClient | WebSocket + REST | 外部 Gateway 进程 |
| KernelClient | Tauri invoke() | 内置 Kernel |
| SaaSRelayGatewayClient | HTTP SSE | 浏览器端 SaaS 中继 |

`getClient()` 定义在 `connectionStore.ts:844`，所有 Store 通过 `initializeStores()` (store/index.ts:94) 获取共享 client 实例。

---

## 5. SaaS 认证 (Token Pool)

### 会话存储

| 数据 | 存储位置 | Key |
|------|----------|-----|
| JWT Token | OS Keyring | `zclaw-saas-token` |
| SaaS URL | localStorage | `zclaw-saas-url` |
| 账户信息 | localStorage | `zclaw-saas-account` |
| 连接模式 | localStorage | `zclaw-connection-mode` |

### Cookie 认证

后端通过 `set_auth_cookies()` (saas/auth/handlers.rs) 设置:
- `zclaw_access_token` (path: /api, 2h TTL)
- `zclaw_refresh_token` (path: /api/v1/auth, 7d TTL)
- Secure: dev=false, prod=true | SameSite=Strict | HttpOnly=true

### Token 池与限流

SaaS Relay 端点实施 RPM/TPM 限流轮换:
- JWT password_version: 密码修改后所有已签发 JWT 自动失效
- SaaS unreachable 时 `connectionStore.ts:456-466` 自动降级到本地 Kernel

---

## 6. 记忆管道 (Memory Pipeline)

### 闭环架构

```
用户对话 → extraction_adapter (LLM提取关键信息)
         → FTS5 全文索引 + TF-IDF 权重计算
         → 检索 (查询时召回相关记忆)
         → 注入系统提示 (提供给 LLM 上下文)
```

### 关键组件

| 组件 | 位置 | 职责 |
|------|------|------|
| GrowthCrate | `crates/zclaw-growth/` | FTS5 + TF-IDF 核心 |
| ExtractionAdapter | `crates/zclaw-kernel/` | 从对话提取结构化信息 |
| TauriExtractionDriver | `desktop/src-tauri/` | 桥接前端与后端提取 |
| MemoryStore | `desktop/src/store/` | 前端记忆状态管理 |

### 存储

- 对话记忆: SQLite (zclaw-memory crate)
- 向量嵌入: PostgreSQL + pgvector 0.8.2 (zclaw-saas)
- API Key: OS keyring (secure-storage.ts)

---

## 7. Pipeline DSL

### 架构

```
YAML Pipeline 定义
  → PipelineExecutor (crates/zclaw-pipeline/src/executor.rs)
  → DAG 运行器 (按依赖顺序执行步骤)
  → ActionRegistry (步骤动作注册)
  → PipelineRun { status, current_step, step_results, outputs }
```

### 运行状态

```rust
enum RunStatus { Pending, Running, Completed, Failed, Cancelled }
```

### 前端集成

| 组件 | 文件 |
|------|------|
| PipelineClient | `desktop/src/lib/pipeline-client.ts` |
| usePipelineRun hook | React 状态管理 |
| Pipeline Tauri 命令 | `desktop/src-tauri/src/pipeline_commands/` |

### 模板

17 个 YAML 模板覆盖 10 大行业 (汕头玩具/服装设计/医疗等)，位于 `pipelines/` 目录。

---

## 8. Hands 自主能力系统

### 9 个启用的 Hands

| Hand | 能力 | 关键依赖 |
|------|------|----------|
| Browser | 浏览器自动化 | WebDriver |
| Collector | 数据收集聚合 | — |
| Researcher | 深度研究 | LLM |
| Clip | 视频处理 | FFmpeg |
| Twitter | Twitter 自动化 | OAuth 1.0a (写操作) |
| Whiteboard | 白板演示 | — (导出开发中) |
| Slideshow | 幻灯片生成 | — |
| Speech | 语音合成 | Browser TTS |
| Quiz | 测验生成 | — |

### 触发流程

```
UI 触发 → handStore → Tauri invoke('hand_trigger')
  → Kernel → Hand 执行
  → needs_approval? → 等待用户审批 → approvalStore
  → 执行日志记录
```

### 配置

每个 Hand 通过 `hands/<Name>/HAND.toml` 配置，包含:
- enabled 状态
- 参数定义
- needs_approval 标记
- 依赖声明

---

## 9. 中间件链 (12 层)

运行时注册顺序 (优先级 0-100):

```
DataMasking@90 → ButlerRouter → (其他10层) → LLM 调用
```

DataMasking (优先级 90) 在请求发送前执行数据脱敏。ButlerRouter 在消息流中注入领域分类的 system prompt 增强。

---

## 10. 关键文件路径速查

### 前端核心

| 文件 | 职责 |
|------|------|
| `desktop/src/store/connectionStore.ts` | 客户端路由、连接模式、模型配置 |
| `desktop/src/store/index.ts` | Store 协调器、共享 client 注入 |
| `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` | 管家冷启动 hook |

### 后端核心

| 文件 | 职责 |
|------|------|
| `crates/zclaw-kernel/src/kernel/mod.rs` | Kernel 启动序列 |
| `crates/zclaw-kernel/src/config.rs` | LLM 配置 + Driver 工厂 |
| `crates/zclaw-runtime/src/loop_runner.rs` | 主聊天循环 (迭代工具使用) |
| `crates/zclaw-runtime/src/middleware/butler_router.rs` | 管家路由器 |
| `crates/zclaw-kernel/src/intelligence/pain_storage.rs` | 痛点持久化 |
| `crates/zclaw-saas/src/auth/handlers.rs` | SaaS 认证端点 |
| `crates/zclaw-pipeline/src/executor.rs` | Pipeline 执行器 |
| `desktop/src-tauri/src/lib.rs` | Tauri 命令注册 (182个) |