zclaw_openfang/docs/ARCHITECTURE_BRIEF.md

ZCLAW 架构概览

永久最新参考文档 — 每次重大变更后由 auto-sync 更新。 最后更新: 2026-04-09 详细功能文档见 docs/features/

---

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 结构:

{ 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 }

运行状态

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个)