aa6a9cbd84
Some checks failed
CI / Lint & TypeCheck (push) Has been cancelled
CI / Unit Tests (push) Has been cancelled
CI / Build Frontend (push) Has been cancelled
CI / Rust Check (push) Has been cancelled
CI / Security Scan (push) Has been cancelled
CI / E2E Tests (push) Has been cancelled
refactor: 统一Hands系统常量到单个源文件 refactor: 更新Hands中文名称和描述 fix: 修复技能市场在连接状态变化时重新加载 fix: 修复身份变更提案的错误处理逻辑 docs: 更新多个功能文档的验证状态和实现位置 docs: 更新Hands系统文档 test: 添加测试文件验证工作区路径
822 lines
30 KiB
Markdown
822 lines
30 KiB
Markdown
# 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)
|
||
|
||
```rust
|
||
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)
|
||
|
||
```rust
|
||
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)
|
||
|
||
```rust
|
||
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 命令
|
||
|
||
```rust
|
||
/// 初始化内部 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 命令
|
||
|
||
```rust
|
||
/// 创建 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 数据结构
|
||
|
||
```rust
|
||
/// 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 初始化流程
|
||
|
||
```rust
|
||
// 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 状态管理
|
||
|
||
```rust
|
||
// Kernel 状态包装器
|
||
pub type KernelState = Arc<Mutex<Option<Kernel>>>;
|
||
|
||
// 创建 Kernel 状态
|
||
pub fn create_kernel_state() -> KernelState {
|
||
Arc::new(Mutex::new(None))
|
||
}
|
||
```
|
||
|
||
### 4.3 lib.rs 注册
|
||
|
||
```rust
|
||
// 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 创建
|
||
|
||
```rust
|
||
// 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
|
||
|
||
```typescript
|
||
// 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 集成
|
||
|
||
```typescript
|
||
// 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
|
||
// ...
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 七、与旧架构对比
|
||
|
||
| 特性 | 旧架构 (外部 OpenFang) | 新架构 (内部 Kernel) |
|
||
|------|----------------------|---------------------|
|
||
| 后端进程 | 独立 OpenFang 进程 | 内置 zclaw-kernel |
|
||
| 通信方式 | WebSocket/HTTP | Tauri 命令 |
|
||
| 模型配置 | TOML 文件 | UI 设置页面 |
|
||
| 启动时间 | 依赖外部进程 | 即时启动 |
|
||
| 安装包 | 需要额外运行时 | 单一安装包 |
|
||
| 进程管理 | 需要 openfang 命令 | 自动管理 |
|
||
|
||
---
|
||
|
||
## 八、实际效果
|
||
|
||
### 8.1 已实现功能
|
||
|
||
- [x] 内部 Kernel 集成
|
||
- [x] 多 LLM Provider 支持 (7+)
|
||
- [x] UI 模型配置
|
||
- [x] Agent 生命周期管理
|
||
- [x] 消息发送和响应
|
||
- [x] **流式响应 (Streaming)** - 通过 Tauri 事件 `stream:chunk`
|
||
- [x] **MCP 协议支持** - JSON-RPC 传输层
|
||
- [x] **Browser Hand** - Fantoccini WebDriver 集成
|
||
- [x] **智能层后端** - Memory, Heartbeat, Reflection, Identity
|
||
- [x] 连接状态管理
|
||
- [x] 错误处理
|
||
- [x] 安全存储 (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 周）
|
||
- [x] ~~添加真正的流式响应支持~~ ✅ 已完成
|
||
- [ ] 完善 MCP 协议工具验证
|
||
- [ ] Browser Hand 稳定性增强
|
||
|
||
### 10.3 中期计划（1-2 月）
|
||
- [ ] Agent 持久化存储优化
|
||
- [ ] 会话历史管理增强
|
||
- [ ] 更多 Hand 能力实现
|
||
|
||
- [ ] 多 Agent 并发支持
|
||
|
||
### 10.4 长期愿景
|
||
- [ ] 多 Agent 并发支持
|
||
- [ ] Agent 间通信
|
||
- [ ] 工作流引擎集成
|
||
- [ ] 分布式 Kernel 支持
|
||
|
||
---
|
||
|
||
**最后更新**: 2026-03-24### 9.1 短期计划（1-2 周）
|
||
- [x] ~~添加真正的流式响应支持~~ ✅ 已完成
|
||
- [ ] 完善 MCP 协议工具验证
|
||
|
||
### 9.2 中期计划（1-2 月）
|
||
- [ ] Agent 持久化存储
|
||
- [ ] 会话历史管理
|
||
- [ ] 更多 Hand 能力实现
|
||
|
||
### 9.3 长期愿景
|
||
- [ ] 多 Agent 并发支持
|
||
- [ ] Agent 间通信
|
||
- [ ] 工作流引擎集成
|
||
|
||
---
|
||
|
||
**最后更新**: 2026-03-24
|