0d4fa96b82
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
重构所有代码和文档中的项目名称，将OpenFang统一更新为ZCLAW。包括： - 配置文件中的项目名称 - 代码注释和文档引用 - 环境变量和路径 - 类型定义和接口名称 - 测试用例和模拟数据 同时优化部分代码结构，移除未使用的模块，并更新相关依赖项。
328 lines
16 KiB
Markdown
328 lines
16 KiB
Markdown
# ZCLAW v2 架构设计 — 基于 ZCLAW 定制化
|
||
|
||
**日期**: 2026-03-11
|
||
**定位**: 像 AutoClaw 一样，对 ZCLAW 进行定制化封装，打造 Tauri 桌面版
|
||
|
||
---
|
||
|
||
## 一、架构总览
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ ZCLAW (Tauri App) │
|
||
│ ┌──────────────────────────────────────────────────┐ │
|
||
│ │ React 19 + TailwindCSS │ │
|
||
│ │ ┌────────┐ ┌────────┐ ┌────────┐ ┌──────────┐ │ │
|
||
│ │ │ 分身Tab │ │IM频道 │ │定时任务│ │ 设置页面 │ │ │
|
||
│ │ └────────┘ └────────┘ └────────┘ └──────────┘ │ │
|
||
│ │ ┌──────────────────────────────────────────┐ │ │
|
||
│ │ │ 聊天区域 + 工具调用展示 │ │ │
|
||
│ │ └──────────────────────────────────────────┘ │ │
|
||
│ └──────────────────────────────────────────────────┘ │
|
||
│ │ Tauri Commands │
|
||
│ ┌──────────────────────────────────────────────────┐ │
|
||
│ │ Rust Sidecar / Bridge │ │
|
||
│ │ • 管理 ZCLAW Gateway 子进程生命周期 │ │
|
||
│ │ • WebSocket 客户端连接 Gateway │ │
|
||
│ │ • 转发 Gateway 事件到前端 │ │
|
||
│ └──────────────────────────────────────────────────┘ │
|
||
└─────────────────────────────────────────────────────────┘
|
||
│ WebSocket (ws://127.0.0.1:18789)
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ ZCLAW Gateway (Node.js daemon) │
|
||
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌───────────┐ │
|
||
│ │ Agent │ │ Skills │ │ Sessions │ │ Heartbeat │ │
|
||
│ │ Runtime │ │ System │ │ Manager │ │ Engine │ │
|
||
│ └──────────┘ └──────────┘ └──────────┘ └───────────┘ │
|
||
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌───────────┐ │
|
||
│ │ Tools │ │ Memory │ │ MCP │ │ Provider │ │
|
||
│ │ (bash/ │ │ (SQLite/ │ │ Server │ │ (models) │ │
|
||
│ │ file/ │ │ LanceDB)│ │ │ │ │ │
|
||
│ │ browse) │ │ │ │ │ │ │ │
|
||
│ └──────────┘ └──────────┘ └──────────┘ └───────────┘ │
|
||
│ ┌──────────────────────────────────────────────────┐ │
|
||
│ │ Channel Plugins (IM 渠道) │ │
|
||
│ │ WhatsApp │ Telegram │ Discord │ Slack │ ... │ │
|
||
│ └──────────────────────────────────────────────────┘ │
|
||
│ ┌──────────────────────────────────────────────────┐ │
|
||
│ │ ZCLAW Custom Plugins (我们的) │ │
|
||
│ │ @zclaw/feishu │ @zclaw/wechat │ @zclaw/qq │ │
|
||
│ │ @zclaw/chinese-models (GLM/Qwen/Kimi/MiniMax) │ │
|
||
│ └──────────────────────────────────────────────────┘ │
|
||
└─────────────────────────────────────────────────────────┘
|
||
│
|
||
┌──────────┴──────────┐
|
||
│ Bootstrap Files │
|
||
│ AGENTS.md │
|
||
│ SOUL.md │
|
||
│ IDENTITY.md │
|
||
│ USER.md │
|
||
│ TOOLS.md │
|
||
└─────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 二、核心设计决策
|
||
|
||
### 1. ZCLAW 作为执行引擎
|
||
|
||
**不重新发明轮子**。ZCLAW 已经实现了：
|
||
- ✅ 真实工具执行 (bash/file/browser)
|
||
- ✅ Skills 系统 (SKILL.md + 渐进式披露)
|
||
- ✅ MCP 协议支持
|
||
- ✅ 心跳引擎 (Heartbeat)
|
||
- ✅ 持久记忆 (SQLite + LanceDB)
|
||
- ✅ Agent 运行时 (Session/Queue/Streaming)
|
||
- ✅ 10+ IM 渠道适配器
|
||
- ✅ 插件体系 (Channel/Tool/Memory/Provider)
|
||
|
||
我们只需要：**包装 + 定制 + 中文化**
|
||
|
||
### 2. Tauri 作为桌面壳
|
||
|
||
AutoClaw 用的是自己的桌面框架，QClaw 用 Electron。我们用 **Tauri 2.0** (Rust + React)：
|
||
- 更小体积 (~10MB vs Electron ~150MB)
|
||
- 更好性能 (Rust native)
|
||
- 系统级集成能力
|
||
- 管理 ZCLAW Gateway 子进程
|
||
|
||
### 3. 自定义插件做差异化
|
||
|
||
通过 ZCLAW 的 Plugin API 添加中国特色功能：
|
||
|
||
| 插件 | 功能 |
|
||
|------|------|
|
||
| `@zclaw/feishu` | 飞书 Channel Plugin |
|
||
| `@zclaw/wechat` | 微信 Channel Plugin (通过 WeCom API 或 itchat 桥接) |
|
||
| `@zclaw/qq` | QQ Channel Plugin |
|
||
| `@zclaw/chinese-models` | 中文模型 Provider (智谱GLM/通义千问/Kimi/MiniMax) |
|
||
| `@zclaw/zclaw-ui` | 自定义 Gateway RPC 方法供 Tauri UI 调用 |
|
||
|
||
---
|
||
|
||
## 三、项目结构 (重构后)
|
||
|
||
```
|
||
ZClaw/
|
||
├── desktop/ # Tauri 2.0 桌面应用
|
||
│ ├── src-tauri/ # Rust 后端
|
||
│ │ ├── src/
|
||
│ │ │ ├── main.rs # Tauri 入口
|
||
│ │ │ ├── gateway.rs # ZCLAW Gateway 子进程管理
|
||
│ │ │ ├── ws_client.rs # WebSocket 客户端
|
||
│ │ │ └── commands.rs # Tauri Commands (前端调用)
|
||
│ │ ├── Cargo.toml
|
||
│ │ └── tauri.conf.json
|
||
│ ├── src/ # React 前端
|
||
│ │ ├── App.tsx
|
||
│ │ ├── main.tsx
|
||
│ │ ├── index.css
|
||
│ │ ├── components/
|
||
│ │ │ ├── Sidebar.tsx # 左侧栏 (分身/IM/定时)
|
||
│ │ │ ├── ChatArea.tsx # 聊天区域 + 工具调用展示
|
||
│ │ │ ├── RightPanel.tsx # 右侧面板
|
||
│ │ │ └── Settings/ # 设置页面 (对标 AutoClaw)
|
||
│ │ │ ├── General.tsx # 通用设置
|
||
│ │ │ ├── UsageStats.tsx # 用量统计
|
||
│ │ │ ├── ModelsAPI.tsx # 模型与 API
|
||
│ │ │ ├── MCPServices.tsx # MCP 服务管理
|
||
│ │ │ ├── Skills.tsx # 技能管理
|
||
│ │ │ ├── IMChannels.tsx # IM 频道管理
|
||
│ │ │ ├── Workspace.tsx # 工作区设置
|
||
│ │ │ ├── Privacy.tsx # 数据与隐私
|
||
│ │ │ └── About.tsx # 关于
|
||
│ │ ├── store/
|
||
│ │ │ ├── chatStore.ts # 聊天状态
|
||
│ │ │ ├── gatewayStore.ts # Gateway 连接状态
|
||
│ │ │ └── settingsStore.ts # 设置状态
|
||
│ │ └── lib/
|
||
│ │ ├── gateway-client.ts # WebSocket 客户端封装
|
||
│ │ └── protocol.ts # Gateway 协议类型定义
|
||
│ └── package.json
|
||
│
|
||
├── plugins/ # ZCLAW 自定义 ZCLAW 插件
|
||
│ ├── zclaw-feishu/ # 飞书频道插件
|
||
│ │ ├── index.ts
|
||
│ │ ├── plugin.json # 插件清单
|
||
│ │ └── README.md
|
||
│ ├── zclaw-wechat/ # 微信频道插件
|
||
│ │ ├── index.ts
|
||
│ │ └── plugin.json
|
||
│ ├── zclaw-qq/ # QQ 频道插件
|
||
│ │ ├── index.ts
|
||
│ │ └── plugin.json
|
||
│ ├── zclaw-chinese-models/ # 中文模型 Provider 插件
|
||
│ │ ├── index.ts
|
||
│ │ ├── providers/
|
||
│ │ │ ├── zhipu.ts # 智谱 GLM
|
||
│ │ │ ├── qwen.ts # 通义千问
|
||
│ │ │ ├── kimi.ts # Moonshot Kimi
|
||
│ │ │ └── minimax.ts # MiniMax
|
||
│ │ └── plugin.json
|
||
│ └── zclaw-ui/ # UI 扩展 RPC 插件
|
||
│ ├── index.ts
|
||
│ └── plugin.json
|
||
│
|
||
├── skills/ # ZCLAW 自定义 Skills
|
||
│ ├── chinese-writing/ # 中文写作技能
|
||
│ │ └── SKILL.md
|
||
│ ├── weibo-automation/ # 微博自动化技能
|
||
│ │ └── SKILL.md
|
||
│ └── feishu-docs/ # 飞书文档操作技能
|
||
│ └── SKILL.md
|
||
│
|
||
├── config/ # ZCLAW 默认配置
|
||
│ ├── zclaw.default.json # 预设的 ZCLAW 配置
|
||
│ ├── SOUL.md # 默认人格
|
||
│ ├── AGENTS.md # 默认 Agent 指令
|
||
│ ├── IDENTITY.md # 默认身份
|
||
│ └── USER.md # 默认用户配置
|
||
│
|
||
├── scripts/ # 构建/安装脚本
|
||
│ ├── setup.ts # 首次设置脚本
|
||
│ ├── install-zclaw.ts # ZCLAW 安装检测
|
||
│ └── register-plugins.ts # 注册自定义插件
|
||
│
|
||
├── docs/
|
||
│ ├── architecture-v2.md # 本文件
|
||
│ ├── deviation-analysis.md # 偏离分析报告
|
||
│ ├── DEVELOPMENT.md
|
||
│ └── autoclaw界面/ # AutoClaw 参考截图
|
||
│
|
||
├── package.json # 根项目管理
|
||
├── tsconfig.json
|
||
└── README.md
|
||
```
|
||
|
||
---
|
||
|
||
## 四、与 AutoClaw 功能对标
|
||
|
||
### AutoClaw 设置页面 → ZCLAW 实现方式
|
||
|
||
| AutoClaw 功能 | ZCLAW 实现 |
|
||
|---|---|
|
||
| **通用** (账号/主题/开机启动/工具调用显示) | Tauri 窗口设置 + Gateway config |
|
||
| **用量统计** (会话/消息/Token 按模型分) | 读取 ZCLAW sessions JSONL + 统计 |
|
||
| **积分详情** | 自定义积分系统 (可选) |
|
||
| **模型与API** (内置+自定义模型+Gateway URL) | `zclaw config` + Provider Plugin |
|
||
| **MCP 服务** (File System/Web Fetch/+添加) | 读取 ZCLAW MCP 配置 + UI 管理 |
|
||
| **技能** (SKILL.md 管理/额外目录) | 读取 Skills 目录 + UI 管理 |
|
||
| **IM 频道** (添加/管理/快速添加飞书) | Channel Plugin 配置 UI |
|
||
| **工作区** (项目目录/文件限制/上下文保存/文件监听) | `agents.defaults.workspace` + sandbox 配置 |
|
||
| **数据与隐私** (本地路径/优化计划) | ZCLAW 数据目录 + 隐私配置 |
|
||
| **提交反馈** | 自定义反馈表单 |
|
||
| **关于** (版本/更新) | 显示 ZCLAW + ZCLAW 版本 |
|
||
|
||
### AutoClaw 主界面 → ZCLAW 对标
|
||
|
||
| 功能 | 实现 |
|
||
|---|---|
|
||
| **左侧 - 分身 Tab** | 通过 `agents.list` 配置管理多个 Agent |
|
||
| **左侧 - IM 频道 Tab** | 通过 `channels.*` 配置显示已连接频道 |
|
||
| **左侧 - 定时任务 Tab** | 通过 heartbeat + cron 事件显示 |
|
||
| **中间 - 聊天区域** | WebSocket 订阅 `agent` stream 事件 |
|
||
| **中间 - 模型选择器** | 通过 `agents.defaults.models` 配置 |
|
||
| **右侧 - 代码/文件面板** | 显示 Agent 工具调用结果 (file/bash output) |
|
||
| **快速配置弹窗** | 修改 IDENTITY.md + SOUL.md + USER.md |
|
||
|
||
---
|
||
|
||
## 五、WebSocket 通信协议
|
||
|
||
ZCLAW Tauri 客户端通过标准 ZCLAW Gateway 协议通信：
|
||
|
||
### 连接握手
|
||
```json
|
||
// 1. 服务器发送 challenge
|
||
{"type": "event", "event": "connect.challenge", "payload": {"nonce": "...", "ts": 1737264000000}}
|
||
|
||
// 2. 客户端发送 connect
|
||
{"type": "req", "id": "1", "method": "connect", "params": {
|
||
"minProtocol": 3, "maxProtocol": 3,
|
||
"client": {"id": "zclaw-tauri", "version": "0.1.0", "platform": "windows", "mode": "operator"},
|
||
"role": "operator",
|
||
"scopes": ["operator.read", "operator.write"],
|
||
"auth": {"token": "..."}
|
||
}}
|
||
|
||
// 3. 服务器回复 hello-ok
|
||
{"type": "res", "id": "1", "ok": true, "payload": {"type": "hello-ok", "protocol": 3}}
|
||
```
|
||
|
||
### 核心 RPC 方法
|
||
```
|
||
agent → 发送消息给 Agent (触发 Agent Loop)
|
||
agent.wait → 等待 Agent 运行完成
|
||
send → 通过 IM 频道发送消息
|
||
health → 健康检查
|
||
status → 获取 Gateway 状态
|
||
system-presence → 系统状态
|
||
```
|
||
|
||
### 事件订阅
|
||
```
|
||
agent → Agent 流式输出 (assistant/tool/lifecycle)
|
||
chat → 聊天消息
|
||
presence → 在线状态
|
||
health → 健康状态
|
||
heartbeat → 心跳
|
||
cron → 定时任务
|
||
tick → 定时心跳
|
||
```
|
||
|
||
---
|
||
|
||
## 六、开发分期
|
||
|
||
### Phase 1: 基础连通 (当前优先)
|
||
1. 安装 ZCLAW 并验证 Gateway 可运行
|
||
2. 创建 Tauri 项目结构 (保留现有 desktop/)
|
||
3. 实现 Gateway 子进程管理 (Rust sidecar)
|
||
4. 实现 WebSocket 客户端连接
|
||
5. 前端显示 Gateway 状态 + 基础聊天
|
||
|
||
### Phase 2: 自定义插件
|
||
1. 实现 `@zclaw/chinese-models` Provider Plugin (智谱GLM/Qwen/Kimi)
|
||
2. 实现 `@zclaw/feishu` Channel Plugin
|
||
3. 注册插件到 ZCLAW Gateway
|
||
|
||
### Phase 3: 完整 UI
|
||
1. 实现设置页面体系 (对标 AutoClaw 10 个页面)
|
||
2. 实现分身管理 UI
|
||
3. 实现 Skills 管理 UI
|
||
4. 实现 MCP 服务管理 UI
|
||
|
||
### Phase 4: 高级功能
|
||
1. 微信/QQ Channel Plugin
|
||
2. 自定义 Skills 开发
|
||
3. 工作区管理
|
||
4. 打包发布
|
||
|
||
---
|
||
|
||
## 七、与之前代码的关系
|
||
|
||
### 可复用
|
||
- `desktop/` 前端组件 (需大幅扩展)
|
||
- `plugins/zclaw-chinese-models/` 可复用之前的 AI Provider 代码 (zhipu.ts/openai.ts)
|
||
- `plugins/zclaw-feishu/` 可复用之前的飞书适配器代码
|
||
|
||
### 废弃
|
||
- `src/core/remote-execution/` → ZCLAW 自带工具执行
|
||
- `src/core/task-orchestration/` → ZCLAW Agent Loop 自带
|
||
- `src/core/multi-agent/` → 改为 ZCLAW agents.list 多 Agent
|
||
- `src/core/memory/` → ZCLAW Memory Plugin 自带
|
||
- `src/core/proactive/` → ZCLAW Heartbeat Engine 自带
|
||
- `src/im/gateway.ts` → ZCLAW Channel 系统自带
|
||
- `src/app.ts` → ZCLAW Gateway 就是 app
|
||
- `src/api/` → 通过 WebSocket + Tauri Commands 替代
|
||
- `src/db/` → ZCLAW 自带 SQLite
|
||
- `src/config/` → ZCLAW 配置系统替代
|
||
|
||
---
|
||
|
||
*本架构设计基于对 ZCLAW 官方文档 (docs.zclaw.ai) 的深度研究，
|
||
参考 AutoClaw v0.2.12 的 13 张界面截图进行功能对标。*
|