281 lines
11 KiB
Markdown
281 lines
11 KiB
Markdown
# 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 依赖关系
|
||
|
||
```text
|
||
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
|
||
|
||
---
|
||
|
||
## 六、演化路线
|
||
|
||
### 已完成
|
||
- [x] 内部 Kernel 集成
|
||
- [x] 8 个 LLM Provider 支持 (含 Gemini)
|
||
- [x] 流式响应 (Tauri 事件 stream:chunk)
|
||
- [x] 智能层全部后端 (Memory, Heartbeat, Reflection, Identity, Compaction)
|
||
- [x] Pipeline DSL + Smart Presentation
|
||
- [x] Agent Growth System
|
||
- [x] SaaS 云端模式
|
||
|
||
### 短期计划
|
||
- [ ] hand_run_status/run_list 真实实现
|
||
- [ ] scheduled_task_create 自动执行
|
||
- [ ] MCP 协议工具验证增强
|
||
|
||
### 中期计划
|
||
- [ ] WASM/Native SkillMode 实现
|
||
- [ ] A2A 协议完整实现
|
||
- [ ] Agent 持久化存储优化
|
||
|
||
---
|
||
|
||
**最后更新**: 2026-03-28
|