From 3d614d743c324b4593c44ed1f677513ca020af23 Mon Sep 17 00:00:00 2001 From: iven Date: Sun, 22 Mar 2026 08:58:01 +0800 Subject: [PATCH] docs: update Phase 4 status to completed --- plans/tender-drifting-chipmunk.md | 510 ++++++++++++++++++++++++++++++ 1 file changed, 510 insertions(+) create mode 100644 plans/tender-drifting-chipmunk.md diff --git a/plans/tender-drifting-chipmunk.md b/plans/tender-drifting-chipmunk.md new file mode 100644 index 0000000..83ba111 --- /dev/null +++ b/plans/tender-drifting-chipmunk.md @@ -0,0 +1,510 @@ +# 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 周） + +**目标**：无外部依赖，单安装包可运行 + +**任务**： +- [ ] 移除 `resources/openfang-runtime/` +- [ ] 移除 `start-all.ps1` 中的 OpenFang 启动逻辑 +- [ ] 更新所有文档 +- [ ] 更新 CLAUDE.md +- [ ] 性能优化 +- [ ] 测试覆盖 +- [ ] 发布准备 + +--- + +## 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 原生集成** - 无进程间通信开销