zclaw_openfang/wiki/chat.md

title, updated, status, tags

title	updated	status	tags
聊天系统	2026-04-11	active	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 种实现共享同一套回调:

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

代码逻辑

发送消息流

入口: streamStore.sendMessage(content) → store/chat/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 拆分 (5 Store)

原来 908 行的 ChatStore 已拆分为:

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

前端 Tauri 命令映射

kernel_chat / agent_chat / agent_chat_stream  → 发送消息
cancel_stream                                  → 取消流式响应

模型切换

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/store/chat/artifactStore.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 主聊天循环