---
title: 聊天系统
updated: 2026-04-11
status: active
tags: [module, chat, stream]
---

# 聊天系统

> 从 [[index]] 导航。关联模块: [[routing]] [[saas]] [[butler]]

## 设计思想

**核心问题: 3 种运行环境需要 3 种 ChatStream 实现。**

| 环境 | 实现 | 传输 | 为什么 |
|------|------|------|--------|
| 桌面端 (Tauri) | KernelClient | Tauri Event | 内置 Kernel，但 baseUrl 可指向 SaaS relay |
| 桌面端 (Tauri + SaaS) | KernelClient + relay | Tauri Event → SaaS | 主路径: Token Pool 中转 |
| 浏览器端 | SaaSRelayGatewayClient | HTTP SSE | 无 Tauri 运行时 |
| 外部 Gateway | GatewayClient | WebSocket | 独立进程部署 |

**统一接口**: 3 种实现共享同一套回调:

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

## 代码逻辑

### 发送消息流

入口: `streamStore.sendMessage(content)` → `streamStore.ts`

```
sendMessage(content)
  → effectiveSessionKey = conversationStore.sessionKey || uuid()
  → effectiveAgentId = resolveGatewayAgentId(currentAgent)
  → client.chatStream(content, callbacks, { sessionKey, agentId, chatMode })
    → KernelClient: Tauri invoke('kernel_chat', ...)
      → Kernel → loop_runner → LLM Driver
        → 如果 baseUrl 指向 SaaS relay → 请求发往 Token Pool → LLM
        → 如果 baseUrl 指向 LLM 直连 → 请求直接发往 LLM
      → Tauri Event emit('chat-response-delta', ...)
        → onDelta(text) → streamStore 追加 delta
        → onTool(tool) → toolStore 更新
        → onHand(hand) → handStore 更新
        → onComplete() → conversationStore 持久化
    → SaaSRelay: HTTP POST /api/v1/relay/chat/completions → SSE
    → GatewayClient: WebSocket send → onmessage
  → 5 分钟超时守护 (kernel-chat.ts:76) 防止流挂起
```

### Store 拆分 (4 Store)

原来 908 行的 ChatStore 已拆分为:

| Store | 文件 | 职责 |
|-------|------|------|
| streamStore | `store/chat/streamStore.ts` | 流式消息编排、发送、取消 |
| conversationStore | `store/chat/conversationStore.ts` | 会话管理、当前模型 |
| messageStore | `store/chat/messageStore.ts` | 消息持久化 |
| chatStore | `store/chat/chatStore.ts` | 聊天通用状态 |

### 模型切换

```
UI 选择模型 → conversationStore.currentModel = newModel
  → 下次 sendMessage 时，connectionStore 读取 currentModel
  → SaaS 模式: relay 白名单验证 → 可用则切换
  → 本地模式: 直接使用用户配置的模型
```

## 关联模块

- [[routing]] — 路由决定使用哪种 client
- [[saas]] — Token Pool 提供模型和 API Key
- [[butler]] — ButlerRouter 中间件增强 system prompt
- [[middleware]] — 消息经过 14 层中间件处理
- [[memory]] — 对话内容可能触发记忆提取

## 关键文件

| 文件 | 职责 |
|------|------|
| `desktop/src/store/chat/streamStore.ts` | 流式消息编排 |
| `desktop/src/store/chat/conversationStore.ts` | 会话管理 |
| `desktop/src/lib/kernel-chat.ts` | Kernel ChatStream (Tauri) |
| `desktop/src/lib/saas-relay-client.ts` | SaaS Relay ChatStream |
| `desktop/src/lib/gateway-client.ts` | Gateway ChatStream (WS) |
| `desktop/src/components/ChatArea.tsx` | 聊天区域 UI |
| `crates/zclaw-runtime/src/loop_runner.rs` | Rust 主聊天循环 |