iven/zclaw_openfang
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
5fdf96c3f5b6deac2133c1e855f23a1c92d9106c
zclaw_openfang/docs/features/06-tauri-backend/00-backend-integration.md
iven 5fdf96c3f5 chore: 提交所有工作进度 — SaaS 后端增强、Admin UI、桌面端集成 
包含大量 SaaS 平台改进、Admin 管理后台更新、桌面端集成完善、
文档同步、测试文件重构等内容。为 QA 测试准备干净工作树。
2026-03-29 10:46:41 +08:00

11 KiB
Raw Blame History

ZCLAW Tauri 后端集成

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

一、功能概述

1.1 基本信息

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

属性 值
分类 Tauri 后端
优先级 P0
成熟度 L4
依赖 Tauri Runtime 2.x, zclaw-kernel crate
Tauri 命令总数 58+ (kernel 29 + pipeline 13 + viking 13 + llm 3)
Rust Crates 11 个 (types, memory, runtime, kernel, skills, hands, protocols, pipeline, growth, channels, 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)
                    zclaw-channels        (L5: 通道适配, 规划中)

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 (9 Hands), TriggerManager, Approval
zclaw-skills L5 技能系统 SKILL.md 解析, 69 个技能, PromptOnly/Python/Shell 三种模式
zclaw-hands L5 自主能力 Hand trait, 9 个 Hand (Browser/Slideshow/Speech/Quiz/Whiteboard/Researcher/Collector/Clip/Twitter)
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, 9 个模块, 76+ API 路由
zclaw-channels L5 通道适配器 ConsoleChannel (测试)

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 命令 (29 个)

核心管理:

命令 说明 状态
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 运行列表 ⚠️ 桩命令

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 列出定时任务 ✅

3.2 Pipeline 命令 (13 个)

命令 说明 状态
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 智能层钩子 (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 注册

9 个 Hands 在 Kernel::boot() 中编程式注册: Browser, Slideshow, Speech, Quiz (含 LlmQuizGenerator), Whiteboard, Researcher, Collector, Clip, Twitter

六、演化路线

已完成

  • 内部 Kernel 集成
  • 8 个 LLM Provider 支持 (含 Gemini)
  • 流式响应 (Tauri 事件 stream:chunk)
  • 智能层全部后端 (Memory, Heartbeat, Reflection, Identity, Compaction)
  • Pipeline DSL + Smart Presentation
  • Agent Growth System
  • SaaS 云端模式

短期计划

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

中期计划

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

最后更新: 2026-03-28