zclaw_openfang/wiki/data-flows.md

---
title: 核心数据流
updated: 2026-04-11
status: active
tags: [data-flow, architecture]
---

# 核心数据流

> 从 [[index]] 导航到此处。架构细节见 [[architecture]]

## 主数据流

```
用户操作 → React UI → Zustand Store → Tauri invoke() → zclaw-kernel → LLM/Tools/Skills/Hands
```

这是 ZCLAW 最核心的一条数据通路。所有用户交互都经过这条链路。

## 聊天消息流

```
用户输入
  → streamStore.sendMessage(content)
    → effectiveSessionKey = conversationStore.sessionKey || uuid()
    → effectiveAgentId = resolveGatewayAgentId(currentAgent)
    → client.chatStream(content, callbacks, options)
      → [KernelClient] Tauri invoke('kernel_chat', ...)
        → Kernel → loop_runner → LLM Driver
        → 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 → SSE stream
      → [GatewayClient] WebSocket send → onmessage 回调
  → 5 分钟超时守护 (kernel-chat.ts:76)
```

## 客户端路由决策流

```
connectionStore.connect(url?, token?)
  │
  ├── Admin 模式? → localStorage('zclaw-saas-account').llm_routing
  │     ├── "relay" → SaaS Relay
  │     └── "local" → Kernel (adminForcedLocal=true)
  │
  ├── SaaS 模式? → localStorage('zclaw-connection-mode') === 'saas'
  │     → health check SaaS
  │       ├── 可达 → Tauri: KernelClient + SaaS baseUrl
  │       │         Browser: SaaSRelayGatewayClient (SSE)
  │       └── 不可达 → 降级到本地 Kernel
  │
  ├── Tauri 桌面? → isTauriRuntime() === true
  │     → KernelClient + 自定义模型配置
  │
  └── Fallback → GatewayClient via WebSocket/REST
```

## 记忆管道流

```
对话发生
  → extraction_adapter (LLM 提取: 偏好/知识/经验)
    → MemoryEntry { agent_id, memory_type, content, keywords }
    → SqliteStorage.store()
      → FTS5 全文索引 + TF-IDF 权重计算
      → (可选) EmbeddingClient.embed() → 向量存储 [未激活]

查询时:
  → MemoryRetriever.retrieve(query, agent_id)
    → QueryAnalyzer: 意图分类 + 关键词提取 + 同义词扩展 (CJK)
    → SemanticScorer: TF-IDF 匹配 + (可选) embedding 相似度
    → 返回 top-k 相关记忆

注入时:
  → PromptInjector.inject(system_prompt, memories)
    → token 预算控制
    → 格式化为结构化上下文块
    → 插入到 system prompt 中
```

## SaaS 认证流

```
用户登录
  → POST /api/v1/auth/login { email, password }
  → 验证 (Argon2id + OsRng 盐)
  → 签发 JWT (Claims: user_id, role, pwv)
  → set_auth_cookies():
      zclaw_access_token  (path:/api, 2h TTL, HttpOnly)
      zclaw_refresh_token (path:/api/v1/auth, 7d TTL, HttpOnly)
  → 前端: saasStore 存储 → OS keyring 存 JWT

Token 刷新:
  → POST /api/v1/auth/refresh
  → 验证 refresh_token (单次使用，旧 token 撤销到 DB)
  → 签发新 access + refresh token

密码修改:
  → 更新 password_version (pwv)
  → 所有旧 JWT 自动失效 (Claims.pwv != DB.pwv)
```

## 管家模式流

```
用户消息
  → ButlerRouter 中间件
    → 关键词 4 域分类: healthcare / data_report / policy / meeting
    → 增强 system prompt (领域专用指令)
  → LLM 响应
  → PainAggregator 提取痛点
    → PainStorage (内存 Vec 热缓存 + SQLite 持久)
  → SolutionGenerator
    → 基于痛点生成解决方案提案

冷启动:
  idle → (检测新用户) → greeting_sent → waiting_response → completed
```

## Pipeline 执行流

```
YAML Pipeline 定义
  → PipelineExecutor.load(yaml)
  → 构建 DAG (按依赖排序)
  → 逐步执行:
    → ActionRegistry.resolve(action_type)
    → 执行 action → PipelineRun.step_results
    → 全部完成 → PipelineRun.status = Completed
  → 17 个行业模板在 pipelines/ 目录
```

## Hands 触发流

```
UI 触发 → handStore.trigger(handName, params)
  → Tauri invoke('hand_trigger', { handName, params })
    → Kernel → Hand 执行
    → needs_approval? → 等待 approvalStore 确认
    → 执行结果 → Tauri Event emit
    → handStore 更新状态 + 记录日志
```

→ 架构组件见 [[architecture]]
→ 模块状态见 [[module-status]]