zclaw_openfang/docs/archive/architecture-v2.md

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 协议通信：

连接握手

// 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 张界面截图进行功能对标。