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

ZCLAW Kernel 集成

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

---

一、功能概述

1.1 基本信息

ZCLAW Kernel 集成模块是 Tauri 后端的核心，负责与内部 ZCLAW Kernel 的集成，包括 Agent 生命周期管理、消息处理、模型配置、流式响应等。

属性	值
分类	Tauri 后端
优先级	P0
成熟度	L4
依赖	Tauri Runtime, zclaw-kernel crate
Tauri 命令数	100+

1.2 相关文件

文件	路径	用途
主入口	desktop/src-tauri/src/lib.rs	命令注册、状态初始化
Kernel 命令	desktop/src-tauri/src/kernel_commands.rs	Kernel 命令封装
智能层命令	desktop/src-tauri/src/intelligence/	智能层 Tauri 命令
Memory 命令	desktop/src-tauri/src/memory_commands.rs	内存管理命令
Browser 命令	desktop/src-tauri/src/browser/	Browser Hand 实现
MCP 协议	desktop/src-tauri/src/mcp/	MCP JSON-RPC 实现
LLM 模块	desktop/src-tauri/src/llm/	LLM Driver 实现
Kernel 配置	crates/zclaw-kernel/src/config.rs	配置结构定义
Kernel 实现	crates/zclaw-kernel/src/lib.rs	Kernel 核心实现

---

二、架构设计

2.1 设计背景

用户痛点:

1. 外部进程启动失败、版本兼容问题频发
2. 配置文件分散难以管理
3. 分发复杂，需要额外配置运行时

解决方案:

• 将 ZCLAW Kernel 直接集成到 Tauri 应用中
• 通过 UI 配置模型，无需编辑配置文件
• 单一安装包，开箱即用

2.2 架构概览

┌─────────────────────────────────────────────────────────────────┐
│                      Tauri 桌面应用                              │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │  前端 (React + TypeScript)                              │   │
│  │                                                         │   │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐     │   │
│  │  │ ModelsAPI   │  │ ChatStore   │  │ Connection  │     │   │
│  │  │ (UI 配置)   │  │ (消息管理)  │  │ Store       │     │   │
│  │  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘     │   │
│  │         │                │                │             │   │
│  │         └────────────────┼────────────────┘             │   │
│  │                          │                              │   │
│  │                          ▼                              │   │
│  │              ┌─────────────────────┐                   │   │
│  │              │   KernelClient      │                   │   │
│  │              │   (Tauri invoke)    │                   │   │
│  │              └──────────┬──────────┘                   │   │
│  └─────────────────────────┼──────────────────────────────┘   │
│                            │                                   │
│                            │ Tauri Commands                    │
│                            │                                   │
│  ┌─────────────────────────┼──────────────────────────────┐   │
│  │  后端 (Rust)            │                              │   │
│  │                         ▼                              │   │
│  │  ┌────────────────────────────────────────────────┐    │   │
│  │  │  kernel_commands.rs                            │    │   │
│  │  │  ├─ kernel_init                                │    │   │
│  │  │  ├─ kernel_status                              │    │   │
│  │  │  ├─ kernel_shutdown                            │    │   │
│  │  │  ├─ agent_create                               │    │   │
│  │  │  ├─ agent_list                                 │    │   │
│  │  │  ├─ agent_get                                  │    │   │
│  │  │  ├─ agent_delete                               │    │   │
│  │  │  └─ agent_chat                                 │    │   │
│  │  └────────────────────┬───────────────────────────┘    │   │
│  │                       │                                 │   │
│  │                       ▼                                 │   │
│  │  ┌────────────────────────────────────────────────┐    │   │
│  │  │  zclaw-kernel crate                            │    │   │
│  │  │  ├─ Kernel::boot()                             │    │   │
│  │  │  ├─ spawn_agent()                              │    │   │
│  │  │  ├─ kill_agent()                               │    │   │
│  │  │  ├─ list_agents()                              │    │   │
│  │  │  └─ send_message()                             │    │   │
│  │  └────────────────────┬───────────────────────────┘    │   │
│  │                       │                                 │   │
│  │                       ▼                                 │   │
│  │  ┌────────────────────────────────────────────────┐    │   │
│  │  │  zclaw-runtime crate                           │    │   │
│  │  │  ├─ AnthropicDriver                            │    │   │
│  │  │  ├─ OpenAiDriver                               │    │   │
│  │  │  ├─ GeminiDriver                               │    │   │
│  │  │  └─ LocalDriver                                │    │   │
│  │  └────────────────────────────────────────────────┘    │   │
│  └─────────────────────────────────────────────────────────┘   │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

2.3 Crate 依赖

ZCLAW Rust Workspace 包含 8 个 crate，采用分层架构：

                    ┌─────────────┐
                    │ zclaw-types │ (L1 - 基础类型)
                    └──────┬──────┘
                           │
          ┌────────────────┼────────────────┐
          │                │                │
          ▼                ▼                ▼
   ┌─────────────┐  ┌──────────────┐  ┌────────────────┐
   │zclaw-memory │  │zclaw-runtime │  │zclaw-protocols │
   │(L2-存储层)  │  │(L3-LLM运行时)│  │(MCP/A2A协议)   │
   └──────┬──────┘  └──────┬───────┘  └───────┬────────┘
          │                │                  │
          └────────────────┼──────────────────┘
                           │
                           ▼
                    ┌─────────────┐
                    │zclaw-kernel │ (L4 - 核心协调器)
                    └──────┬──────┘
                           │
        ┌──────────────────┼──────────────────┐
        │                  │                  │
        ▼                  ▼                  ▼
 ┌─────────────┐   ┌─────────────┐   ┌───────────────┐
 │zclaw-skills │   │ zclaw-hands │   │zclaw-channels │
 │(技能系统)   │   │(自主能力)   │   │(通道适配器)   │
 └─────────────┘   └─────────────┘   └───────────────┘

2.4 各 Crate 职责

Crate	层级	职责	主要模块
zclaw-types	L1	基础类型	AgentId, Message, Error, Capability, Event
zclaw-memory	L2	SQLite 存储层	Session 持久化, KV Store, Schema
zclaw-runtime	L3	LLM 运行时	Driver 抽象, Tool Registry, AgentLoop, LoopGuard
zclaw-protocols	L3	协议支持	MCP JSON-RPC, A2A Agent-to-Agent
zclaw-kernel	L4	核心协调	Agent 注册/调度, EventBus, Director, SkillRegistry
zclaw-skills	L5	技能系统	SKILL.md 解析, SkillRunner, execute_skill
zclaw-hands	L5	自主能力	Hand trait, Trigger 系统, 9 个 Hand 实现
zclaw-channels	L5	通道适配器	Telegram, Discord, Slack, Console

2.5 核心工具实现

工具	路径	功能	状态
execute_skill	crates/zclaw-runtime/src/tool/builtin/execute_skill.rs	动态执行 SKILL.md 技能	✅ 已实现
file_read	crates/zclaw-runtime/src/tool/builtin/file_read.rs	文件读取	✅ 已实现
file_write	crates/zclaw-runtime/src/tool/builtin/file_write.rs	文件写入	✅ 已实现
shell_exec	crates/zclaw-runtime/src/tool/builtin/shell_exec.rs	Shell 命令执行	✅ 已实现
web_fetch	crates/zclaw-runtime/src/tool/builtin/web_fetch.rs	网页抓取	✅ 已实现

---

六、Tauri 命令分类

6.1 内部 Kernel 命令 (推荐)

命令	说明	状态
kernel_init	初始化内部 Kernel	✅
kernel_status	获取 Kernel 状态	✅
kernel_shutdown	关闭 Kernel	✅
agent_create	创建 Agent	✅
agent_list	列出所有 Agent	✅
agent_get	获取 Agent 详情	✅
agent_delete	删除 Agent	✅
agent_chat	发送消息 (同步)	✅
agent_chat_stream	发送消息 (流式)	✅
skill_list	列出技能	✅
skill_refresh	刷新技能目录	✅
skill_execute	执行技能	✅
hand_list	列出 Hands	✅
hand_execute	执行 Hand	✅

6.2 记忆系统命令

命令	说明	状态
memory_init	初始化记忆存储	✅
memory_store	存储记忆	✅
memory_get	获取记忆	✅
memory_search	搜索记忆	✅
memory_delete	删除记忆	✅
memory_stats	记忆统计	✅
memory_export	导出记忆	✅
memory_import	导入记忆	✅

6.3 智能层命令

心跳引擎:

命令	说明
heartbeat_init	初始化心跳
heartbeat_start	启动心跳
heartbeat_stop	停止心跳
heartbeat_tick	手动触发
heartbeat_get_config	获取配置

上下文压缩:

命令	说明
compactor_estimate_tokens	估算 Token
compactor_check_threshold	检查阈值
compactor_compact	执行压缩

反思引擎:

命令	说明
reflection_init	初始化反思
reflection_should_reflect	检查是否需要反思
reflection_reflect	执行反思
reflection_get_history	获取历史

身份管理:

命令	说明
identity_get	获取身份文件
identity_build_prompt	构建系统提示
identity_propose_change	提出变更提案
identity_approve_proposal	批准提案

6.4 浏览器自动化命令

命令	说明	状态
browser_create_session	创建会话	✅
browser_navigate	导航	✅
browser_click	点击	✅
browser_type	输入	✅
browser_screenshot	截图	✅
browser_execute_script	执行 JS	✅
browser_scrape_page	抓取页面	✅

6.5 安全存储命令

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

---

三、核心类型设计

3.1 消息类型 (Message)

pub enum Message {
    User { content: String },
    Assistant { content: String, thinking: Option<String> },
    ToolUse { id: String, tool: ToolId, input: Value },
    ToolResult { tool_call_id: String, tool: ToolId, output: Value, is_error: bool },
    System { content: String },
}

3.2 能力系统 (Capability)

pub enum Capability {
    ToolInvoke { name: String },
    ToolAll,
    MemoryRead { scope: String },
    MemoryWrite { scope: String },
    NetConnect { host: String },
    ShellExec { pattern: String },
    AgentSpawn,
    AgentMessage { pattern: String },
    AgentKill { pattern: String },
    OfpDiscover,
    OfpConnect { peer: String },
    OfpAdvertise,
}

3.3 流式响应 (StreamChunk)

pub enum StreamChunk {
    TextDelta { delta: String },
    ThinkingDelta { delta: String },
    ToolUseStart { id: String, name: String },
    ToolUseDelta { id: String, delta: String },
    ToolUseEnd { id: String, input: Value },
    Complete { input_tokens: u32, output_tokens: u32, stop_reason: String },
    Error { message: String },
}

---

四、关键设计模式

4.1 能力安全模型

• 基于细粒度权限控制
• CapabilitySet 检查工具调用、内存读写权限

4.2 异步 Trait 抽象

• LlmDriver trait 支持多 Provider
• McpClient trait 支持 MCP 协议
• A2aClient trait 支持 Agent 间通信

4.3 并发数据结构

• DashMap 用于无锁并发访问
• EventBus 使用 broadcast channel

4.4 循环保护 (LoopGuard)

• SHA256 检测重复工具调用
• 防止 Agent 陷入无限循环

---

五、Tauri 命令

3.1 Kernel 命令

/// 初始化内部 ZCLAW Kernel
#[tauri::command]
pub async fn kernel_init(
    state: State<'_, KernelState>,
    config_request: Option<KernelConfigRequest>,
) -> Result<KernelStatusResponse, String>

/// 获取 Kernel 状态
#[tauri::command]
pub async fn kernel_status(
    state: State<'_, KernelState>,
) -> Result<KernelStatusResponse, String>

/// 关闭 Kernel
#[tauri::command]
pub async fn kernel_shutdown(
    state: State<'_, KernelState>,
) -> Result<(), String>

3.2 Agent 命令

/// 创建 Agent
#[tauri::command]
pub async fn agent_create(
    state: State<'_, KernelState>,
    request: CreateAgentRequest,
) -> Result<CreateAgentResponse, String>

/// 列出所有 Agent
#[tauri::command]
pub async fn agent_list(
    state: State<'_, KernelState>,
) -> Result<Vec<AgentInfo>, String>

/// 获取 Agent 详情
#[tauri::command]
pub async fn agent_get(
    state: State<'_, KernelState>,
    agent_id: String,
) -> Result<Option<AgentInfo>, String>

/// 删除 Agent
#[tauri::command]
pub async fn agent_delete(
    state: State<'_, KernelState>,
    agent_id: String,
) -> Result<(), String>

/// 发送消息
#[tauri::command]
pub async fn agent_chat(
    state: State<'_, KernelState>,
    request: ChatRequest,
) -> Result<ChatResponse, String>

3.3 数据结构

/// Kernel 配置请求
pub struct KernelConfigRequest {
    pub provider: String,      // kimi | qwen | deepseek | zhipu | openai | anthropic | local
    pub model: String,         // 模型 ID
    pub api_key: Option<String>,
    pub base_url: Option<String>,
    pub api_protocol: String,  // openai | anthropic
}

/// Kernel 状态响应
pub struct KernelStatusResponse {
    pub initialized: bool,
    pub agent_count: usize,
    pub database_url: Option<String>,
    pub default_provider: Option<String>,
    pub default_model: Option<String>,
}

/// Agent 创建请求
pub struct CreateAgentRequest {
    pub name: String,
    pub description: Option<String>,
    pub system_prompt: Option<String>,
    pub provider: String,
    pub model: String,
    pub max_tokens: u32,
    pub temperature: f32,
}

/// 流式聊天事件 (通过 Tauri 事件发送)
pub enum StreamChatEvent {
    Delta { delta: String },
    ToolStart { name: String, input: serde_json::Value },
    ToolEnd { name: String, output: serde_json::Value },
    Complete { input_tokens: u32, output_tokens: u32 },
    Error { message: String },
}

/// 聊天请求
pub struct ChatRequest {
    pub agent_id: String,
    pub message: String,
}

/// 聊天响应
pub struct ChatResponse {
    pub content: String,
    pub input_tokens: u32,
    pub output_tokens: u32,
}

---

四、Kernel 初始化

4.1 初始化流程

// desktop/src-tauri/src/kernel_commands.rs

pub async fn kernel_init(
    state: State<'_, KernelState>,
    config_request: Option<KernelConfigRequest>,
) -> Result<KernelStatusResponse, String> {
    let mut kernel_lock = state.lock().await;

    // 如果已初始化，返回当前状态
    if kernel_lock.is_some() {
        let kernel = kernel_lock.as_ref().unwrap();
        return Ok(KernelStatusResponse { ... });
    }

    // 构建配置
    let mut config = zclaw_kernel::config::KernelConfig::default();

    if let Some(req) = &config_request {
        config.default_provider = req.provider.clone();
        config.default_model = req.model.clone();

        // 根据 Provider 设置 API Key
        match req.provider.as_str() {
            "kimi" => {
                if let Some(key) = &req.api_key {
                    config.kimi_api_key = Some(key.clone());
                }
                if let Some(url) = &req.base_url {
                    config.kimi_base_url = url.clone();
                }
            }
            "qwen" => {
                if let Some(key) = &req.api_key {
                    config.qwen_api_key = Some(key.clone());
                }
                if let Some(url) = &req.base_url {
                    config.qwen_base_url = url.clone();
                }
            }
            // ... 其他 Provider
            _ => {}
        }
    }

    // 启动 Kernel
    let kernel = Kernel::boot(config.clone())
        .await
        .map_err(|e| format!("Failed to initialize kernel: {}", e))?;

    *kernel_lock = Some(kernel);

    Ok(KernelStatusResponse {
        initialized: true,
        agent_count: 0,
        database_url: Some(config.database_url),
        default_provider: Some(config.default_provider),
        default_model: Some(config.default_model),
    })
}

4.2 Kernel 状态管理

// Kernel 状态包装器
pub type KernelState = Arc<Mutex<Option<Kernel>>>;

// 创建 Kernel 状态
pub fn create_kernel_state() -> KernelState {
    Arc::new(Mutex::new(None))
}

4.3 lib.rs 注册

// desktop/src-tauri/src/lib.rs

#[cfg_attr(mobile, tauri::mobile_entry_point)]
pub fn run() {
    tauri::Builder::default()
        .setup(|app| {
            // 注册 Kernel 状态
            app.manage(kernel_commands::create_kernel_state());
            Ok(())
        })
        .invoke_handler(tauri::generate_handler![
            // Kernel 命令
            kernel_commands::kernel_init,
            kernel_commands::kernel_status,
            kernel_commands::kernel_shutdown,
            // Agent 命令
            kernel_commands::agent_create,
            kernel_commands::agent_list,
            kernel_commands::agent_get,
            kernel_commands::agent_delete,
            kernel_commands::agent_chat,
        ])
        .run(tauri::generate_context!())
}

---

五、LLM Provider 支持

5.1 支持的 Provider

Provider	实现方式	Base URL
kimi	OpenAiDriver	https://api.kimi.com/coding/v1
qwen	OpenAiDriver	https://dashscope.aliyuncs.com/compatible-mode/v1
deepseek	OpenAiDriver	https://api.deepseek.com/v1
zhipu	OpenAiDriver	https://open.bigmodel.cn/api/paas/v4
openai	OpenAiDriver	https://api.openai.com/v1
anthropic	AnthropicDriver	https://api.anthropic.com
gemini	GeminiDriver	https://generativelanguage.googleapis.com
local	LocalDriver	http://localhost:11434/v1

5.2 Driver 创建

// crates/zclaw-kernel/src/config.rs

impl KernelConfig {
    pub fn create_driver(&self) -> Result<Arc<dyn LlmDriver>> {
        let driver: Arc<dyn LlmDriver> = match self.default_provider.as_str() {
            "kimi" => {
                let key = self.kimi_api_key.clone()
                    .ok_or_else(|| ZclawError::ConfigError("KIMI_API_KEY not set".into()))?;
                Arc::new(OpenAiDriver::with_base_url(
                    SecretString::new(key),
                    self.kimi_base_url.clone(),
                ))
            }
            "qwen" => {
                let key = self.qwen_api_key.clone()
                    .ok_or_else(|| ZclawError::ConfigError("QWEN_API_KEY not set".into()))?;
                Arc::new(OpenAiDriver::with_base_url(
                    SecretString::new(key),
                    self.qwen_base_url.clone(),
                ))
            }
            // ... 其他 Provider
            _ => return Err(ZclawError::ConfigError(
                format!("Unknown provider: {}", self.default_provider)
            )),
        };
        Ok(driver)
    }
}

---

六、前端集成

6.1 双模式架构

前端支持两种通信模式：

┌─────────────────────────────────────────────────────────────┐
│                    前端 (React + TypeScript)                  │
├─────────────────────────────────────────────────────────────┤
│  connectionStore.ts                                          │
│  ┌─────────────────┐    ┌─────────────────┐                 │
│  │  KernelClient   │    │  GatewayClient  │                 │
│  │  (Tauri invoke) │    │  (WebSocket)    │                 │
│  └────────┬────────┘    └────────┬────────┘                 │
│           │                      │                            │
└───────────┼──────────────────────┼────────────────────────────┘
            │                      │
    ┌───────▼───────┐      ┌──────▼──────┐
    │  Tauri IPC    │      │  WebSocket  │
    │  Commands     │      │  / REST API │
    └───────┬───────┘      └──────┬──────┘
            │                     │
┌───────────▼─────────────────────▼───────────────────────────┐
│                     后端 (Rust)                               │
└─────────────────────────────────────────────────────────────┘

6.2 KernelClient

// desktop/src/lib/kernel-client.ts

export class KernelClient {
  private config: KernelConfig = {};

  setConfig(config: KernelConfig): void {
    this.config = config;
  }

  async connect(): Promise<void> {
    // 验证配置
    if (!this.config.provider || !this.config.model || !this.config.apiKey) {
      throw new Error('请先在"模型与 API"设置页面配置模型');
    }

    // 初始化 Kernel
    const status = await invoke<KernelStatus>('kernel_init', {
      configRequest: {
        provider: this.config.provider,
        model: this.config.model,
        apiKey: this.config.apiKey,
        baseUrl: this.config.baseUrl || null,
      },
    });

    // 创建默认 Agent
    const agents = await this.listAgents();
    if (agents.length === 0) {
      const agent = await this.createAgent({
        name: 'Default Agent',
        provider: this.config.provider,
        model: this.config.model,
      });
      this.defaultAgentId = agent.id;
    }
  }

  async chat(message: string, opts?: ChatOptions): Promise<ChatResponse> {
    return invoke<ChatResponse>('agent_chat', {
      request: {
        agentId: opts?.agentId || this.defaultAgentId,
        message,
      },
    });
  }
}

6.2 ConnectionStore 集成

// desktop/src/store/connectionStore.ts

connect: async (url?: string, token?: string) => {
  const useInternalKernel = isTauriRuntime();

  if (useInternalKernel) {
    const kernelClient = getKernelClient();
    const modelConfig = getDefaultModelConfig();

    if (!modelConfig) {
      throw new Error('请先在"模型与 API"设置页面添加自定义模型配置');
    }

    kernelClient.setConfig({
      provider: modelConfig.provider,
      model: modelConfig.model,
      apiKey: modelConfig.apiKey,
      baseUrl: modelConfig.baseUrl,
    });

    await kernelClient.connect();
    set({ client: kernelClient, gatewayVersion: '0.2.0-internal' });
    return;
  }

  // 非 Tauri 环境，使用外部 Gateway
  // ...
}

---

七、与旧架构对比

特性	旧架构 (外部 ZCLAW)	新架构 (内部 Kernel)
后端进程	独立 ZCLAW 进程	内置 zclaw-kernel
通信方式	WebSocket/HTTP	Tauri 命令
模型配置	TOML 文件	UI 设置页面
启动时间	依赖外部进程	即时启动
安装包	需要额外运行时	单一安装包
进程管理	需要 zclaw 命令	自动管理

---

八、实际效果

8.1 已实现功能

• 内部 Kernel 集成
• 多 LLM Provider 支持 (7+)
• UI 模型配置
• Agent 生命周期管理
• 消息发送和响应
• 流式响应 (Streaming) - 通过 Tauri 事件 stream:chunk
• MCP 协议支持 - JSON-RPC 传输层
• Browser Hand - Fantoccini WebDriver 集成
• 智能层后端 - Memory, Heartbeat, Reflection, Identity
• 连接状态管理
• 错误处理
• 安全存储 (OS Keyring)

8.2 测试覆盖

• 单元测试: Rust 内置测试
• 集成测试: E2E 测试覆盖
• 覆盖率: ~85%

---

---

十、演化路线

10.1 発能层后端完成度

模块	Phase	状态
Memory System	Phase 1	✅ 完成
Heartbeat Engine	Phase 2	✅ 完成
Context Compactor	Phase 2	✅ 完成
Reflection Engine	Phase 3	✅ 完成
Agent Identity	Phase 3	✅ 完成

10.2 短期计划（1-2 周）

• 添加真正的流式响应支持 ✅ 已完成
• 完善 MCP 协议工具验证
• Browser Hand 稳定性增强

10.3 中期计划（1-2 月）

• Agent 持久化存储优化

• 会话历史管理增强

• 更多 Hand 能力实现

• 多 Agent 并发支持

10.4 长期愿景

• 多 Agent 并发支持
• Agent 间通信
• 工作流引擎集成
• 分布式 Kernel 支持

---

最后更新: 2026-03-24### 9.1 短期计划（1-2 周）

• 添加真正的流式响应支持 ✅ 已完成
• 完善 MCP 协议工具验证

9.2 中期计划（1-2 月）

• Agent 持久化存储
• 会话历史管理
• 更多 Hand 能力实现

9.3 长期愿景

• 多 Agent 并发支持
• Agent 间通信
• 工作流引擎集成

---

最后更新: 2026-03-24