zclaw_openfang/docs/features/06-tauri-backend/00-backend-integration.md

ZCLAW Tauri 后端集成

分类: Tauri 后端 优先级: P0 - 决定性 成熟度: L4 - 生产 最后更新: 2026-04-06 验证状态: 代码已验证 架构: 内部 Kernel，无需外部进程

---

一、功能概述

1.1 基本信息

ZCLAW Tauri 后端是桌面应用的核心，集成内部 ZCLAW Kernel，提供 Agent 生命周期管理、流式消息处理、技能/Hand 执行、Pipeline 工作流、记忆操作等全部能力。

属性	值
分类	Tauri 后端
优先级	P0
成熟度	L4
依赖	Tauri Runtime 2.x, zclaw-kernel crate
Tauri 命令总数	177 (160 @connected + 16 @reserved + 1 unregistered identity_init)
Rust Crates	10 个 (types, memory, runtime, kernel, skills, hands, protocols, pipeline, growth, saas)

1.2 相关文件

文件	路径	用途
主入口	desktop/src-tauri/src/lib.rs	命令注册、状态初始化
Kernel 命令	desktop/src-tauri/src/kernel_commands.rs	Kernel/Agent/Hand/Skill/Trigger/Approval 命令
智能层钩子	desktop/src-tauri/src/intelligence_hooks.rs	pre/post 聊天钩子 (记忆/身份/反思/心跳)
Pipeline 命令	desktop/src-tauri/src/pipeline_commands.rs	Pipeline 运行 + 意图路由 + Presentation 分析
Viking 命令	desktop/src-tauri/src/viking_commands.rs	记忆存储操作 (13 个命令)
LLM 命令	desktop/src-tauri/src/llm/mod.rs	LLM 补全 + Embedding
Kernel 实现	crates/zclaw-kernel/src/kernel.rs	Kernel 核心实现

---

二、架构设计

2.1 Crate 依赖关系

                    zclaw-types          (L1: 基础类型, 95%)
                           |
                    zclaw-memory         (L2: SQLite 存储层, 90%)
                           |
                    zclaw-runtime        (L3: LLM 运行时 + 工具, 90%)
                           |
                    zclaw-kernel         (L4: 核心协调, 85%)
                           |
        +-----------+---------+----------+----------+---------+
        |           |         |          |          |         |
    zclaw-skills  zclaw-hands  zclaw-protocols  zclaw-pipeline  zclaw-growth
     (80%)        (85%)       (75%)           (90%)          (95%)
        |           |         |          |          |
        +-----------+---------+----------+----------+---------+
                           |
                    zclaw-saas            (独立运行, Axum + PostgreSQL)

2.2 各 Crate 职责

Crate	层级	职责	主要模块
zclaw-types	L1	基础类型	AgentId, SessionId, Message, ZclawError (18 变体), Capability (12 种), Event (20+ 种)
zclaw-memory	L2	SQLite 存储层	Session 持久化, KV Store, Schema 管理
zclaw-runtime	L3	LLM 运行时	4 个 Driver (Anthropic/OpenAI/Gemini/Local), 5 个内置工具, AgentLoop, LoopGuard, Compaction
zclaw-kernel	L4	核心协调	Agent 注册/调度, EventBus, SkillRegistry, HandRegistry (11 Hands), TriggerManager, Approval
zclaw-skills	L5	技能系统	SKILL.md 解析, 76 个技能, PromptOnly/Python/Shell 三种模式
zclaw-hands	L5	自主能力	Hand trait, 11 个 Hand (9 启用: Browser/Slideshow/Speech/Quiz/Whiteboard/Researcher/Collector/Clip/Twitter; 2 禁用: Predictor/Lead)
zclaw-protocols	L5	协议支持	MCP (stdio transport), A2A (基础协议定义)
zclaw-pipeline	L5	工作流 DSL	YAML 声明式, 状态管理, 5 类模板
zclaw-growth	L5	记忆增长	SqliteStorage + FTS5 + TF-IDF + MemoryExtractor
zclaw-saas	独立	SaaS 后端	Axum + PostgreSQL, 12 个模块, 131 API 路由, 34 数据表

2.3 核心工具实现

工具	路径	功能	安全特性
file_read	tool/builtin/file_read.rs	文件读取	PathValidator, utf-8/ascii/binary(base64)
file_write	tool/builtin/file_write.rs	文件写入	create/overwrite/append 模式, base64
shell_exec	tool/builtin/shell_exec.rs	Shell 命令执行	命令白名单, 阻止列表, 超时, shlex
web_fetch	tool/builtin/web_fetch.rs	网页抓取	SSRF 防护, 10MB 限制, 危险 Header 阻断
execute_skill	tool/builtin/execute_skill.rs	技能执行	桥接 SkillExecutor, 自主级别守卫

---

三、Tauri 命令分类

3.1 Kernel 命令 (34 个)

核心管理:

命令	说明	状态
kernel_init	初始化 Kernel (配置变更检测 + 自动重启)	✅
kernel_status	获取状态 (初始化/Agent 数/模型信息)	✅
kernel_shutdown	优雅关闭	✅

Agent 管理:

命令	说明	状态
agent_create	Builder 模式创建 Agent (支持 workspace)	✅
agent_list	列出所有 Agent	✅
agent_get	单个 Agent 查找 (ID 验证)	✅
agent_delete	终止 Agent	✅

聊天:

命令	说明	状态
agent_chat	同步聊天	✅
agent_chat_stream	流式聊天 (pre/post 智能钩子 + session 复用)	✅

技能:

命令	说明	状态
skill_list	列出已发现技能	✅
skill_refresh	重新扫描技能目录	✅
skill_execute	执行技能 (自主级别守卫: supervised/assisted/autonomous)	✅

Hands:

命令	说明	状态
hand_list	列出已注册 Hands	✅
hand_execute	执行 Hand (自主级别守卫 + 审批门)	✅
hand_get	获取单个 Hand	✅
hand_approve	审批 Hand (跨 Hand 验证防攻击)	✅
hand_cancel	取消 Hand (跨 Hand 验证)	✅
hand_run_status	运行状态	⚠️ 桩命令
hand_run_list	运行列表	⚠️ 桩命令
hand_run_cancel	取消 Hand 运行	✅

Trigger:

命令	说明	状态
trigger_list	列出所有触发器	✅
trigger_get	获取触发器	✅
trigger_create	创建 (支持 Schedule/Event/Webhook/MessagePattern/FileSystem/Manual)	✅
trigger_update	更新 (name, enabled, hand_id)	✅
trigger_delete	删除	✅
trigger_execute	手动执行	✅

审批 + 定时任务:

命令	说明	状态
approval_list	列出待审批	✅
approval_respond	审批/拒绝 (含理由)	✅
scheduled_task_create	创建定时任务 (基于 Trigger)	✅
scheduled_task_list	列出定时任务	✅

A2A (Agent-to-Agent) 通信:

命令	说明	状态
agent_a2a_send	Agent 间发送消息	✅
agent_a2a_broadcast	广播消息	✅
agent_a2a_discover	发现其他 Agent	✅
agent_a2a_delegate_task	委派任务	✅

3.2 Pipeline 命令 (10 个)

命令	说明	状态
pipeline_list	列出 Pipeline (支持分类/行业过滤)	✅
pipeline_get	获取单个 Pipeline	✅
pipeline_run	后台执行 (事件发射)	✅
pipeline_progress	运行进度跟踪	✅
pipeline_cancel	取消运行	✅
pipeline_result	最终结果	✅
pipeline_runs	列出所有运行	✅
pipeline_refresh	重新扫描 Pipeline 目录	✅
route_intent	意图路由 (关键词匹配 → LLM 语义匹配 → 建议)	✅
analyze_presentation	Presentation 数据分析	✅

适配器: RuntimeLlmAdapter (LLM 桥接), PipelineSkillDriver (技能桥接), PipelineHandDriver (Hand 桥接)

3.3 Viking/记忆命令 (13 个)

命令	说明	状态
viking_status	健康检查 + 存储查询	✅
viking_add	存储记忆条目	✅
viking_add_with_metadata	存储 (含关键词 + 重要性)	✅
viking_find	语义搜索 (scope/limit)	✅
viking_grep	FTS5 模式匹配 (行级结果)	✅
viking_ls	按前缀列出记忆	✅
viking_read	多级读取 (L0 摘要/L1 概览/L2 全文)	✅
viking_remove	删除记忆条目	✅
viking_tree	记忆树结构	✅
viking_inject_prompt	Token 预算控制注入	✅
viking_configure_embedding	配置 Embedding (SqliteStorage + PersistentMemoryStore)	✅
viking_configure_summary_driver	配置 L0/L1 摘要生成	✅
viking_store_with_summaries	存储 + 后台 L0/L1 摘要生成	✅

3.4 LLM/Embedding 命令 (3 个)

命令	说明	状态
llm_complete	OpenAI 兼容聊天补全	✅
embedding_create	Embedding 生成	✅
embedding_providers	列出可用 Embedding Provider	✅

3.5 Browser 自动化命令 (22 个)

命令	说明	状态
browser_create_session	创建浏览器会话 (Fantoccini WebDriver)	✅
browser_close_session	关闭会话	✅
browser_list_sessions	列出所有活跃会话	✅
browser_get_session	获取会话详情	✅
browser_navigate	导航到 URL	✅
browser_back	浏览器后退	✅
browser_forward	浏览器前进	✅
browser_refresh	刷新页面	✅
browser_get_url	获取当前 URL	✅
browser_get_title	获取页面标题	✅
browser_find_element	查找单个元素 (CSS/XPath)	✅
browser_find_elements	查找多个元素	✅
browser_click	点击元素	✅
browser_type	输入文本	✅
browser_get_text	获取元素文本	✅
browser_get_attribute	获取元素属性	✅
browser_wait_for_element	等待元素出现	✅
browser_execute_script	执行 JavaScript	✅
browser_screenshot	页面截图	✅
browser_element_screenshot	元素截图	✅
browser_get_source	获取页面源码	✅
browser_scrape_page	抓取页面结构化数据	✅
browser_fill_form	批量填写表单	✅

3.6 Intelligence 智能层命令 (35 个)

Heartbeat Engine (10 个):

命令	说明	状态
heartbeat_init	初始化心跳引擎	✅
heartbeat_start	启动心跳定时器	✅
heartbeat_stop	停止心跳	✅
heartbeat_tick	手动执行一次巡检	✅
heartbeat_get_config	获取当前配置	✅
heartbeat_update_config	更新配置	✅
heartbeat_get_history	获取历史记录	✅
heartbeat_update_memory_stats	更新记忆统计	✅
heartbeat_record_correction	记录纠正事件	✅
heartbeat_record_interaction	记录交互事件	✅

Context Compactor (4 个):

命令	说明	状态
compactor_estimate_tokens	估算文本 Token 数	✅
compactor_estimate_messages_tokens	估算消息列表 Token 数	✅
compactor_check_threshold	检查是否需要压缩	✅
compactor_compact	执行上下文压缩	✅

Reflection Engine (6 个):

命令	说明	状态
reflection_init	初始化反思引擎	✅
reflection_record_conversation	记录对话用于反思	✅
reflection_should_reflect	检查是否应触发反思	✅
reflection_reflect	执行反思分析	✅
reflection_get_history	获取反思历史	✅
reflection_get_state	获取引擎状态	✅

Agent Identity Manager (15 个):

命令	说明	状态
identity_get	获取 Agent 所有身份文件	✅
identity_get_file	读取单个身份文件	✅
identity_build_prompt	构建完整人格 Prompt	✅
identity_update_user_profile	更新用户画像	✅
identity_append_user_profile	追加用户画像内容	✅
identity_propose_change	创建身份变更提案	✅
identity_approve_proposal	批准变更提案	✅
identity_reject_proposal	拒绝变更提案	✅
identity_get_pending_proposals	获取待审批提案	✅
identity_update_file	更新身份文件 (自动创建快照)	✅
identity_get_snapshots	获取版本快照列表	✅
identity_restore_snapshot	恢复到指定快照	✅
identity_list_agents	列出所有 Agent 身份	✅
identity_delete_agent	删除 Agent 身份数据	✅

3.7 Memory 持久化命令 (14 个)

Memory Persistence (13 个):

命令	说明	状态
memory_init	初始化记忆存储	✅
memory_store	存储记忆条目	✅
memory_get	获取单条记忆	✅
memory_search	搜索记忆 (关键词+语义)	✅
memory_delete	删除单条记忆	✅
memory_delete_all	清空所有记忆	✅
memory_stats	记忆统计信息	✅
memory_export	导出记忆数据	✅
memory_import	导入记忆数据	✅
memory_db_path	获取数据库路径	✅
memory_configure_embedding	配置 Embedding	✅
memory_is_embedding_configured	检查 Embedding 配置状态	✅
memory_build_context	构建记忆上下文	✅

Memory Extraction (2 个):

命令	说明	状态
extract_session_memories	从会话提取记忆	✅
extract_and_store_memories	提取并存储记忆	✅

Context Builder (1 个):

命令	说明	状态
estimate_content_tokens	估算内容 Token 数	✅

3.8 ZCLAW CLI Wrapper 命令 (13 个)

命令	说明	状态
zclaw_status	Gateway 状态查询 (JSON)	✅
zclaw_start	启动 Gateway	✅
zclaw_stop	停止 Gateway	✅
zclaw_restart	重启 Gateway	✅
zclaw_local_auth	读取本地认证 Token	✅
zclaw_prepare_for_tauri	更新 Tauri Origins 配置	✅
zclaw_approve_device_pairing	批准设备配对请求	✅
zclaw_doctor	运行诊断	✅
zclaw_health_check	综合健康检查 (进程+端口+延迟)	✅
zclaw_process_list	ZCLAW 进程列表	✅
zclaw_process_logs	进程日志查询	✅
zclaw_version	版本信息查询	✅
zclaw_ping	快速存活检查	✅

3.9 Secure Storage 命令 (4 个)

命令	说明	状态
secure_store_set	存储密钥到 OS Keyring/Keychain	✅
secure_store_get	从 OS Keyring/Keychain 读取密钥	✅
secure_store_delete	从 OS Keyring/Keychain 删除密钥	✅
secure_store_is_available	检查 OS Keyring/Keychain 可用性	✅

3.10 智能层钩子 (intelligence_hooks.rs)

钩子	说明	集成点
pre_conversation_hook()	VikingStorage 记忆检索 (FTS5+TF-IDF+Embedding) → SOUL.md 身份增强 system prompt	agent_chat_stream
post_conversation_hook()	心跳记录 + 反思引擎 (阈值触发, 查询最多 50 条记忆)	agent_chat_stream

---

四、LLM Provider 支持

Provider	Driver	协议	特性
kimi	OpenAiDriver	OpenAI 兼容	reasoning_content (思维链)
qwen	OpenAiDriver	OpenAI 兼容	DashScope, reasoning_content
deepseek	OpenAiDriver	OpenAI 兼容	reasoning_content
zhipu	OpenAiDriver	OpenAI 兼容	BigModel
openai	OpenAiDriver	OpenAI	原生支持
anthropic	AnthropicDriver	Anthropic	content_block_delta, API 2023-06-01
gemini	GeminiDriver	Gemini REST v1beta	functionDeclarations, [thinking] 标记
local	LocalDriver	OpenAI 兼容	Ollama/LM Studio/vLLM, 连接诊断

Embedding Providers: OpenAI, Zhipu, Doubao, Qwen, DeepSeek, Local/TF-IDF

---

五、关键设计模式

5.1 能力安全模型

• 12 种 Capability 细粒度权限 (ToolInvoke, MemoryRead/Write, NetConnect, ShellExec, AgentSpawn/Message/Kill, OfpDiscover/Connect/Advertise)
• CapabilitySet.validate_inheritance() 安全继承验证
• CapabilityManager.validate() 阻止危险组合 (ToolAll+AgentKill, ToolAll+ShellExec(*))

5.2 LoopGuard 循环防护

• SHA256 检测重复工具调用
• warn(3) → block(5) → circuit_breaker(30) 三级阈值

5.3 上下文压缩 (Compaction)

• CJK 感知 Token 估算
• 规则 + LLM 双模式摘要
• 15k Token 阈值自动触发

5.4 自主级别守卫

• supervised: 所有操作需审批
• assisted: Shell/Python 需审批
• autonomous: 全部自动执行

5.5 Kernel Boot 注册

11 个 Hands 在 Kernel::boot() 中编程式注册: 9 启用: Browser, Slideshow, Speech, Quiz (含 LlmQuizGenerator), Whiteboard, Researcher, Collector, Clip, Twitter 2 禁用: Predictor, Lead (无 Rust 实现)

---

六、演化路线

已完成

• 内部 Kernel 集成
• 8 个 LLM Provider 支持 (含 Gemini)
• 流式响应 (Tauri 事件 stream:chunk)
• 智能层全部后端 (Memory, Heartbeat, Reflection, Identity, Compaction)
• Pipeline DSL + Smart Presentation
• Agent Growth System
• SaaS 云端模式
• Browser 自动化 (Fantoccini, 22 个 Tauri 命令)
• Secure Storage (OS Keyring/Keychain)
• A2A Agent-to-Agent 通信

短期计划

• hand_run_status/run_list 真实实现
• scheduled_task_create 自动执行
• MCP 协议工具验证增强

中期计划

• WASM/Native SkillMode 实现
• A2A 协议完整实现
• Agent 持久化存储优化

---

最后更新: 2026-04-06