zclaw_openfang/wiki/architecture.md

title, updated, status, tags

title	updated	status	tags
系统架构	2026-04-11	active	architecture core

系统架构

从 index 导航到此处。详细架构参考: docs/ARCHITECTURE_BRIEF.md

Crate 依赖关系

zclaw-types          (L1: 基础类型, 无依赖)
    ↑
zclaw-memory         (L2: SQLite, KV, 会话)
    ↑
zclaw-runtime        (L3: 4 Driver, 7 工具, 14 中间件)
    ↑
zclaw-kernel         (L4: 182 Tauri 命令, 核心协调)
    ↑
zclaw-saas           (独立: Axum + PostgreSQL, 端口 8080)
    ↑
desktop/src-tauri    (集成: kernel + skills + hands + protocols)

并行 crates (不依赖 runtime):

• zclaw-skills — 75 SKILL.md 解析 + 语义路由
• zclaw-hands — 9 自主能力
• zclaw-protocols — MCP 完整 + A2A feature-gated
• zclaw-pipeline — Pipeline DSL v1/v2 + DAG 执行器
• zclaw-growth — 记忆增长 (FTS5 + TF-IDF + Embedding trait)

客户端路由 (4 分支)

getClient()
  ├── [1] Admin 路由: localStorage llm_routing → relay/local
  ├── [2] SaaS Relay: SaaS不可达→降级到本地 Kernel
  ├── [3] Local Kernel: Tauri 内置 (桌面端默认)
  └── [4] External Gateway: WebSocket/REST fallback

关键文件: desktop/src/store/connectionStore.ts:844

聊天流 (3 种实现)

实现	传输	场景
GatewayClient	WebSocket	外部 Gateway 进程
KernelClient	Tauri Event	内置 Kernel (默认)
SaaSRelay	HTTP SSE	浏览器端 SaaS 中继

统一回调: { onDelta, onThinkingDelta, onTool, onHand, onComplete, onError } 5 分钟超时守护: desktop/src/lib/kernel-chat.ts:76

LLM 驱动 (4 + 3)

Rust Driver

Driver	文件	协议
AnthropicDriver	crates/zclaw-runtime/src/driver/anthropic.rs	Anthropic Messages
OpenAiDriver	crates/zclaw-runtime/src/driver/openai.rs	OpenAI Chat
GeminiDriver	crates/zclaw-runtime/src/driver/gemini.rs	Google Gemini
LocalDriver	crates/zclaw-runtime/src/driver/local.rs	Ollama

国内兼容 (通过 OpenAI 协议 + base_url)

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

API Key → OS keyring (secure-storage.ts)

管家模式 (默认激活)

用户消息 → ButlerRouter (4域关键词分类) → 增强 system prompt → LLM
                                                              ↓
                                              PainAggregator → PainStorage (内存+SQLite)
                                                              ↓
                                              SolutionGenerator (痛点→方案)

• 冷启动: idle → greeting_sent → waiting_response → completed
• UI 双模式: simple (纯聊天, 默认) / professional (完整功能)
• ButlerRouter 文件: crates/zclaw-runtime/src/middleware/butler_router.rs

记忆管道 (闭环)

对话 → extraction_adapter (LLM 提取)
     → FTS5 全文索引 + TF-IDF 权重
     → 检索 (查询时召回)
     → 注入 system prompt (token 预算控制)

• EmbeddingClient trait 已定义但未激活
• zclaw-saas 有 pgvector HNSW 索引就绪，embedding 生成 deferred

SaaS 认证

数据	存储
JWT Token	OS Keyring
账户信息	localStorage
Cookie	HttpOnly + Secure + SameSite=Strict

• JWT password_version: 改密码→所有旧 JWT 失效
• Token 池: RPM/TPM 限流轮换
• SaaS unreachable → 自动降级本地 Kernel

中间件链 (14 层)

关键中间件:

• DataMasking@90 — 请求前数据脱敏
• ButlerRouter — 4域关键词分类 + system prompt 增强
• TrajectoryRecorder@650 — 轨迹记录压缩

关键文件速查

前端

文件	职责
desktop/src/store/connectionStore.ts	客户端路由
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	管家冷启动

后端

文件	职责
crates/zclaw-kernel/src/kernel/mod.rs	Kernel 启动
crates/zclaw-runtime/src/loop_runner.rs	主聊天循环
crates/zclaw-saas/src/auth/handlers.rs	SaaS 认证
desktop/src-tauri/src/lib.rs	Tauri 命令注册

→ 数据流细节见 data-flows → 模块状态见 module-status