iven/zclaw_openfang
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
73ff5e8c5ecdbaffc06092befc53ec448232e2bd
zclaw_openfang/docs/features/06-tauri-backend/00-backend-integration.md
iven b7ec317d2c
Some checks failed
CI / Lint & TypeCheck (push) Has been cancelled
Details
CI / Unit Tests (push) Has been cancelled
Details
CI / Build Frontend (push) Has been cancelled
Details
CI / Rust Check (push) Has been cancelled
Details
CI / Security Scan (push) Has been cancelled
Details
CI / E2E Tests (push) Has been cancelled
Details
docs: 更新功能文档 — 反映架构重构成果 
- docs/features/README.md — 技能数 69→70, Hands 11个, 成熟度更新
- 智能层文档成熟度上调 (身份演化 L3, 反思引擎 L3)
- 后端集成文档更新 SaaS 迁移系统说明
- 知识库添加架构重构记录
2026-03-29 19:42:37 +08:00

439 lines
18 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# ZCLAW Tauri 后端集成
> **分类**: Tauri 后端
> **优先级**: P0 - 决定性
> **成熟度**: L4 - 生产
> **最后更新**: 2026-03-29
> **验证状态**: 代码已验证
> **架构**: 内部 Kernel，无需外部进程
---
## 一、功能概述
### 1.1 基本信息
ZCLAW Tauri 后端是桌面应用的核心，集成内部 ZCLAW Kernel，提供 Agent 生命周期管理、流式消息处理、技能/Hand 执行、Pipeline 工作流、记忆操作等全部能力。
| 属性 | 值 |
|------|-----|
| 分类 | Tauri 后端 |
| 优先级 | P0 |
| 成熟度 | L4 |
| 依赖 | Tauri Runtime 2.x, zclaw-kernel crate |
| Tauri 命令总数 | **130+** (kernel 34 + pipeline 10 + browser 22 + intelligence 35 + memory 14 + cli 13 + viking 13 + llm 3 + secure_storage 4) |
| 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 (11 Hands), TriggerManager, Approval |
| zclaw-skills | L5 | 技能系统 | SKILL.md 解析, 70 个技能, 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, 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 命令 (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 实现)
---
## 六、演化路线
### 已完成
- [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 云端模式
- [x] Browser 自动化 (Fantoccini, 22 个 Tauri 命令)
- [x] Secure Storage (OS Keyring/Keychain)
- [x] A2A Agent-to-Agent 通信
### 短期计划
- [ ] hand_run_status/run_list 真实实现
- [ ] scheduled_task_create 自动执行
- [ ] MCP 协议工具验证增强
### 中期计划
- [ ] WASM/Native SkillMode 实现
- [ ] A2A 协议完整实现
- [ ] Agent 持久化存储优化
---
**最后更新**: 2026-03-29
Reference in New Issue View Git Blame Copy Permalink