# ZCLAW 独立化架构重构计划 ## Context ### 问题背景 1. **外部进程不稳定** - OpenFang 作为独立进程运行，启动失败、版本兼容问题频发 2. **代码分散** - ZCLAW 和 OpenFang 逻辑分离，维护困难 3. **分发复杂** - 用户安装需要额外配置 OpenFang 运行时 4. **技术债务** - 架构需要清理，希望借此机会彻底解决 ### 目标 将 ZCLAW 从"基于 OpenFang 定制"转变为**完全独立的 AI Agent 桌面系统**： - 代码所有权：所有代码在 ZCLAW 仓库 - 架构自主：完全自由设计 - 品牌独立：无 OpenFang/OpenClaw 痕迹 - 技术栈独立：选择最适合的技术 ### 策略 **混合策略**：核心能力自研，通用能力借鉴设计，代码层面完全原创 --- ## Architecture ### Crate 结构 ``` ZCLAW/ ├── crates/ # Rust Workspace │ │ │ ├── zclaw-types/ # L1: 基础类型（无依赖） │ │ ├── AgentId, SessionId, Message │ │ ├── Capability, Tool, Event │ │ ├── Config, Error │ │ └── 共享 trait 定义 │ │ │ ├── zclaw-memory/ # L2: 存储层（依赖 types） │ │ ├── KV Store（Agent 配置、状态） │ │ ├── Session Manager（对话历史） │ │ ├── Semantic Search（向量搜索） │ │ └── SQLite 持久化 │ │ │ ├── zclaw-runtime/ # L3: 运行时（依赖 types, memory） │ │ ├── LLM Drivers（Anthropic, OpenAI, Gemini, Local） │ │ ├── Tool Runner（23 个内置工具） │ │ ├── Agent Loop（消息循环、流式处理） │ │ ├── Loop Guard（防循环） │ │ └── Session Compactor（上下文压缩） │ │ │ ├── zclaw-kernel/ # L4: 核心协调（依赖所有下层） │ │ ├── Agent Registry（注册、生命周期） │ │ ├── Scheduler（配额、调度） │ │ ├── Capability Manager（权限） │ │ ├── Event Bus（事件发布） │ │ ├── Workflow Engine（工作流） │ │ ├── Trigger Engine（触发器） │ │ └── Supervisor（健康监控） │ │ │ ├── zclaw-skills/ # 技能系统 │ │ ├── Skill Loader（TOML/SKILL.md 解析） │ │ ├── Skill Runner（Python/WASM/PromptOnly） │ │ └── Bundled Skills（内置技能） │ │ │ ├── zclaw-hands/ # Hands 自主能力 │ │ ├── Browser Hand（整合现有 browser/） │ │ ├── Collector Hand │ │ ├── Researcher Hand │ │ └── 其他 Hands │ │ │ ├── zclaw-channels/ # 通道适配器 │ │ ├── Channel Trait │ │ ├── Telegram/Discord/Slack 等 │ │ └── Bridge Manager │ │ │ └── zclaw-protocols/ # 协议支持 │ ├── MCP Client/Server │ └── A2A Protocol │ ├── desktop/ │ ├── src-tauri/ # Tauri 应用 │ │ ├── src/ │ │ │ ├── lib.rs # 主入口，Kernel 初始化 │ │ │ ├── commands/ # Tauri 命令封装 │ │ │ ├── intelligence/ # 已有智能层（保留） │ │ │ ├── browser/ # 已有浏览器（保留，后续整合到 zclaw-hands） │ │ │ └── state.rs # 应用状态 │ │ └── Cargo.toml # 依赖内部 crates │ └── src/ # React 前端（保持不变） │ └── Cargo.toml # Workspace 定义 ``` ### 依赖关系 ``` zclaw-types (无依赖) ↑ zclaw-memory (→ types) ↑ zclaw-runtime (→ types, memory) ↑ zclaw-kernel (→ types, memory, runtime) ↑ desktop/src-tauri (→ kernel, skills, hands, channels, protocols) ``` --- ## Core Modules ### zclaw-types ```rust // 核心 ID 类型 pub struct AgentId(Uuid); pub struct SessionId(Uuid); pub struct ToolId(String); // 消息类型 pub enum Message { User { content: String }, Assistant { content: String, thinking: Option }, ToolUse { tool: ToolId, input: Value }, ToolResult { tool: ToolId, output: Value, error: bool }, } // Agent 配置 pub struct AgentConfig { pub id: AgentId, pub name: String, pub model: ModelConfig, pub system_prompt: String, pub capabilities: Vec, pub tools: Vec, } // 能力定义 pub enum Capability { ToolInvoke(String), MemoryRead(String), MemoryWrite(String), NetConnect(String), ShellExec(String), AgentSpawn, AgentMessage(String), } // 统一错误类型 pub enum ZclawError { NotFound(String), PermissionDenied(String), LlmError(String), ToolError(String), StorageError(String), } ``` ### zclaw-memory ```rust pub struct MemoryStore { db: Arc>, } impl MemoryStore { // Agent 配置持久化 pub async fn save_agent(&self, agent: &AgentConfig) -> Result<()>; pub async fn load_agent(&self, id: &AgentId) -> Result>; pub async fn list_agents(&self) -> Result>; // 会话管理 pub async fn create_session(&self, agent_id: &AgentId) -> Result; pub async fn get_session(&self, id: &SessionId) -> Result>; pub async fn append_message(&self, session: &SessionId, msg: Message) -> Result<()>; // KV 存储 pub async fn store(&self, agent: &AgentId, key: &str, value: &Value) -> Result<()>; pub async fn recall(&self, agent: &AgentId, key: &str) -> Result>; // 语义搜索 pub async fn embed(&self, text: &str) -> Result>; pub async fn search_similar(&self, query: &str, limit: usize) -> Result>; } ``` ### zclaw-runtime ```rust // LLM 驱动 trait #[async_trait] pub trait LlmDriver: Send + Sync { async fn complete(&self, req: CompletionRequest) -> Result; async fn stream(&self, req: CompletionRequest) -> Result>; } // 内置驱动实现 pub struct AnthropicDriver { api_key: SecretString } pub struct OpenAiDriver { api_key: SecretString, base_url: String } pub struct GeminiDriver { api_key: SecretString } pub struct LocalDriver { base_url: String } // Ollama/LMStudio // Agent 循环 pub struct AgentLoop { driver: Arc, tools: Vec, memory: Arc, loop_guard: LoopGuard, } impl AgentLoop { pub async fn run(&self, session: SessionId, input: String) -> Result; pub async fn run_streaming(&self, session: SessionId, input: String) -> Result>; } ``` ### zclaw-kernel ```rust pub struct Kernel { registry: AgentRegistry, scheduler: Scheduler, capabilities: CapabilityManager, events: EventBus, workflows: WorkflowEngine, triggers: TriggerEngine, supervisor: Supervisor, memory: Arc, } impl Kernel { pub async fn boot(config: KernelConfig) -> Result; // Agent 生命周期 pub async fn spawn_agent(&self, config: AgentConfig) -> Result; pub async fn kill_agent(&self, id: &AgentId) -> Result<()>; pub async fn list_agents(&self) -> Result>; // 消息处理 pub async fn send_message(&self, agent: &AgentId, msg: String) -> Result; pub async fn send_message_stream(&self, agent: &AgentId, msg: String) -> Result>; // 工作流 pub async fn run_workflow(&self, workflow_id: &str, input: Value) -> Result; // 事件 pub fn subscribe(&self) -> broadcast::Receiver; } ``` --- ## Tauri Integration ### 启动流程 ```rust // desktop/src-tauri/src/lib.rs #[cfg_attr(mobile, tauri::mobile_entry_point)] pub fn run() { tauri::Builder::default() .setup(|app| { // 1. 初始化内核 let runtime = tokio::runtime::Runtime::new().unwrap(); let kernel = runtime.block_on(async { Kernel::boot(KernelConfig::load().await?).await }).expect("Kernel boot failed"); // 2. 存储到应用状态 app.manage(Arc::new(kernel)); app.manage(runtime); Ok(()) }) .invoke_handler(tauri::generate_handler![ // Agent 命令 agent_spawn, agent_kill, agent_list, agent_chat, agent_chat_stream, // 配置命令 config_get, config_update, // 工作流命令 workflow_list, workflow_run, // 技能命令 skill_list, skill_install, // Hands 命令 hand_trigger, hand_status, // 记忆命令 memory_store, memory_recall, memory_search, // 智能层命令（保留） heartbeat_start, heartbeat_stop, reflection_reflect, identity_get, ]) .run(tauri::generate_context!()) } ``` ### 关键变化 | 之前 | 之后 | |------|------| | 外部 OpenFang 进程 | 内部 Kernel 单例 | | WebSocket 连接 localhost:4200 | 直接 Tauri 命令调用 | | 启动脚本管理进程 | Tauri 应用内自动初始化 | | 两个代码仓库 | 单一 ZCLAW 仓库 | --- ## Migration Phases ### 阶段 0：准备（1 周）✅ 已完成 **目标**：workspace 编译通过 **任务**： - [x] 创建 `crates/` 目录 - [x] 创建根 `Cargo.toml` workspace 配置 - [x] 创建各 crate 骨架（`zclaw-types`, `zclaw-memory`, `zclaw-runtime`, `zclaw-kernel`） - [x] 更新 `desktop/src-tauri/Cargo.toml` 加入 workspace - [x] 验证 `cargo build` 成功 ### 阶段 1：基础设施（2-3 周）✅ 已完成 **目标**：可以存储和加载 Agent 配置 **任务**： - [x] **zclaw-types** - 定义 AgentId, SessionId, ToolId - 定义 Message 枚举 - 定义 AgentConfig 结构 - 定义 Capability 枚举 - 定义 ZclawError - [x] **zclaw-memory** - SQLite schema 设计（agents, sessions, kv, embeddings） - 实现 MemoryStore - Agent 配置 CRUD - Session 管理 - KV 存储 - 基础语义搜索（可选：延后到阶段 4） ### 阶段 2：核心运行时（3-4 周）✅ 已完成 **目标**：可以与 LLM 对话并调用工具 **任务**： - [x] **zclaw-runtime** - LlmDriver trait 定义 - AnthropicDriver 实现 - OpenAiDriver 实现（含 OpenAI-compatible providers） - GeminiDriver 实现 - LocalDriver 实现（Ollama/LMStudio） - Tool trait 和基础工具实现（file_read, file_write, shell_exec, web_fetch） - AgentLoop 实现 - LoopGuard 实现（防循环） - 流式响应支持 ### 阶段 3：内核集成（2-3 周）✅ 已完成 **目标**：Tauri 应用可以创建 Agent 并对话 **任务**： - [x] **zclaw-kernel** - AgentRegistry 实现 - Scheduler 实现（基础版） - CapabilityManager 实现 - EventBus 实现 - Kernel 主结构 - boot() 初始化流程 - [x] **desktop/src-tauri** - lib.rs 集成 Kernel (kernel_commands 模块) - Tauri 命令封装（kernel_init, agent_create, agent_chat 等） - 保留外部 OpenFang 命令作为备选方案 - 前端适配（待实现） ### 阶段 4：扩展能力（4-6 周）✅ 已完成 **目标**：技能、Hands、通道功能正常 **任务**： - [x] **zclaw-skills** - Skill manifest 定义 - SKILL.md 解析器 - SkillRunner trait - PromptOnly 技能执行 - Python 技能执行（subprocess 隔离） - 内置技能移植 - [x] **zclaw-hands** - Hand/Trigger trait 定义 - HandRegistry/TriggerRegistry 实现 - 整合现有 browser/ 模块（待完整移植） - Collector Hand - Researcher Hand - 其他 Hands - [x] **zclaw-channels** - Channel trait 定义 - ChannelBridge 管理器 - Telegram 适配器（骨架） - Discord 适配器（骨架） - Slack 适配器（骨架） - Console 适配器（测试用） - [x] **zclaw-protocols** - MCP Client 实现 - MCP Server 实现（待完善） - A2A 协议支持（可选） ### 阶段 5：清理与优化（2-3 周）✅ 已完成 **目标**：无外部依赖，单安装包可运行 **任务**： - [x] 移除 `resources/openfang-runtime/` - [x] 移除 `start-all.ps1` 中的 OpenFang 启动逻辑 - [x] 更新 tauri.conf.json 移除外部运行时引用 - [x] 更新 CLAUDE.md 反映新架构 - [x] 修复 UTF-8 边界问题 (compactor.rs) - [x] Rust 测试验证 (26/26 通过) - [x] E2E 测试验证 (161/161 通过) - [x] 性能优化 (Release LTO 配置) - [x] 发布准备 (NSIS 安装包生成成功) --- ## Verification ### 阶段验收标准 | 阶段 | 验收命令/方法 | |------|--------------| | 0 | `cargo build` 成功 | | 1 | 运行单元测试验证 MemoryStore CRUD | | 2 | CLI 测试：与 LLM 对话，工具调用正常 | | 3 | `pnpm tauri dev` 启动应用，UI 可创建 Agent 并对话 | | 4 | 技能加载、Hand 触发、通道消息正常 | | 5 | 全新机器安装单一安装包可运行 | ### 最终验证清单 - [ ] `pnpm start:dev` 启动 Tauri 应用，无需外部进程 - [ ] 可创建、配置、删除 Agent - [ ] 可与 Agent 对话，流式响应正常 - [ ] 工具调用正常（文件读写、网络请求） - [ ] 技能加载和执行正常 - [ ] Hands 触发正常（浏览器自动化等） - [ ] 智能层功能正常（心跳、反思、身份） - [ ] 打包后的安装程序可独立运行 --- ## Critical Files ### 需要修改的文件 - `Cargo.toml` - 添加 workspace 配置 - `desktop/src-tauri/Cargo.toml` - 加入 workspace，更新依赖 - `desktop/src-tauri/src/lib.rs` - Kernel 初始化，命令注册 - `start-all.ps1` - 移除 OpenFang 启动逻辑 - `CLAUDE.md` - 更新架构说明 ### 需要创建的文件 - `crates/zclaw-types/Cargo.toml` - `crates/zclaw-types/src/lib.rs` - `crates/zclaw-memory/Cargo.toml` - `crates/zclaw-memory/src/lib.rs` - `crates/zclaw-runtime/Cargo.toml` - `crates/zclaw-runtime/src/lib.rs` - `crates/zclaw-kernel/Cargo.toml` - `crates/zclaw-kernel/src/lib.rs` - `crates/zclaw-skills/Cargo.toml` - `crates/zclaw-skills/src/lib.rs` - `crates/zclaw-hands/Cargo.toml` - `crates/zclaw-hands/src/lib.rs` - `crates/zclaw-channels/Cargo.toml` - `crates/zclaw-channels/src/lib.rs` - `crates/zclaw-protocols/Cargo.toml` - `crates/zclaw-protocols/src/lib.rs` ### 需要删除的文件（阶段 5） - `desktop/src-tauri/resources/openfang-runtime/` - 整个目录 --- ## Reference ### OpenFang 架构参考 OpenFang 是成熟的 Rust workspace，包含 14 个 crate： - `openfang-types` - 共享类型 - `openfang-memory` - SQLite 存储 - `openfang-runtime` - LLM 驱动、工具、Agent 循环 - `openfang-kernel` - 核心协调器 - `openfang-api` - HTTP API（ZCLAW 不需要，用 Tauri 命令替代） - `openfang-channels` - 40 个通道适配器 - `openfang-skills` - 60 个技能 - `openfang-desktop` - Tauri 桌面应用 ### 设计借鉴点 1. **分层架构** - types → memory → runtime → kernel 2. **LLM Driver 抽象** - 统一 trait，多 provider 实现 3. **能力系统** - Capability 枚举，权限检查 4. **Agent Loop** - 消息循环、工具调用、流式处理 5. **Loop Guard** - 防止 Agent 陷入循环 6. **WASM 沙箱** - 技能安全执行（可选） ### ZCLAW 独特价值 1. **智能层** - heartbeat, compactor, reflection, identity（已实现） 2. **中文优先** - 面向中文用户优化 3. **简化的架构** - 去除不需要的 HTTP API 层 4. **Tauri 原生集成** - 无进程间通信开销