iven/zclaw_openfang
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
07079293f48e09e291402171daace4bd0d33675d
zclaw_openfang/docs/archive/openclaw-legacy/deviation-analysis.md
iven 07079293f4 feat(hands): restructure Hands UI with Chinese localization 
Major changes:
- Add HandList.tsx component for left sidebar
- Add HandTaskPanel.tsx for middle content area
- Restructure Sidebar tabs: 分身/HANDS/Workflow
- Remove Hands tab from RightPanel
- Localize all UI text to Chinese
- Archive legacy OpenClaw documentation
- Add Hands integration lessons document
- Update feature checklist with new components

UI improvements:
- Left sidebar now shows Hands list with status icons
- Middle area shows selected Hand's tasks and results
- Consistent styling with Tailwind CSS
- Chinese status labels and buttons

Documentation:
- Create docs/archive/openclaw-legacy/ for old docs
- Add docs/knowledge-base/hands-integration-lessons.md
- Update docs/knowledge-base/feature-checklist.md
- Update docs/knowledge-base/README.md

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-14 23:16:32 +08:00

12 KiB
Raw Blame History

ZCLAW 偏离分析报告

日期: 2026-03-11
目的: 对标 QClaw / AutoClaw / OpenClaw，分析当前项目是否偏离初衷

一、三大产品深度理解

1. OpenClaw — 开源核心 (GitHub 28万+ Stars)

OpenClaw 是一个本地优先的 AI 代理平台，不是简单的聊天机器人，而是一个能真正操控电脑执行任务的系统。

核心架构:

组件 说明
Gateway Node.js 进程，是整个系统的核心控制面板，管理 sessions、channels、tools、events
Channel Plugins IM 渠道适配器 — WhatsApp, Telegram, Slack, Discord, iMessage 等 10+ 种
心跳引擎 (Heartbeat) 定期唤醒，检查 HEARTBEAT.md 任务清单，主动执行预定任务
持久化身份 SOUL.md(性格)、MEMORY.md(长期记忆)、AGENTS.md(角色配置) — 纯文本，Git 可控
Skills 系统 SKILL.md 文件 + 脚本，三级渐进式披露，100+ 预配置技能
MCP 支持 模型上下文协议，JSON-RPC 2.0，扩展外部工具 (File System, Web Fetch, DB 等)
核心工具 bash(命令行)、read/write(文件系统)、browser(浏览器控制)
插件体系 Channel / Memory / Tool / Provider 四类插件
存储 默认 SQLite，支持向量存储、知识图谱

关键设计哲学:

  • 本地优先: 所有数据和执行都在本地
  • 透明可控: 纯文本配置，用户能完全掌控 AI 的"大脑"
  • 执行而非建议: 不是只出主意，而是真正动手做事
  • 自我进化: Agent 可修改自身指令、改进工作流

2. QClaw — 腾讯产品化封装

QClaw 不是腾讯从零重写的框架，而是围绕 OpenClaw 做的一次产品化封装。

核心卖点:

  • 一键安装: 下载即用，无需配置环境
  • 微信 + QQ 双端接入: 腾讯核心优势，在微信/QQ中直接对话指挥电脑
  • 内置国产模型: Kimi, MiniMax, GLM, DeepSeek + 自定义模型
  • 5000+ Skills 生态: ClawHub、GitHub 等丰富生态
  • 持续记忆: 记住偏好和上下文
  • 本地部署: 操控文件、浏览器、邮件

使用场景:

  • 远程操作电脑文件/网页
  • 社媒自动运营
  • GitHub 项目自动开发
  • 学术论文自动整理
  • 每日天气定时提醒

3. AutoClaw — 智谱 AutoGLM 定制版 (v0.2.12)

基于 OpenClaw 的智谱定制版，核心是飞书集成。

从 13 张界面截图提取的完整功能架构:

主界面布局

  • 左侧栏 3 个 Tab: 分身 / IM频道 / 定时任务
  • 中间: 聊天区域 + 发送框 + 模型选择器 (glm-5)
  • 右侧: 代码/文件区域 + Agent 面板

设置系统 (10 个页面)

页面 功能
通用 账号安全、主题(白色/Neon Noir)、开机自启、显示工具调用
用量统计 会话数/消息数/总Token，按模型分类统计
积分详情 积分总量、消耗/获得明细
模型与API 内置模型(Pony-Alpha-2) + 自定义模型(glm-5/qwen3.5-plus/kimi-k2.5/MiniMax-M2.5) + Gateway URL (ws://127.0.0.1:18789)
MCP 服务 File System / Web Fetch + 快速添加(Brave Search, SQLite)
技能 SKILL.md 文件管理，额外技能目录 (~/.opencode/skills)
IM 频道 添加/管理频道，快速添加飞书
工作区 项目目录、文件访问限制、自动保存上下文、文件监听、从OpenClaw迁移
数据与隐私 本地数据路径、优化计划
提交反馈 / 关于 反馈表单、版本信息

核心概念

  • 分身 (Clone): 每个分身是独立的 Agent 实例，有自己的配置和对话历史
  • 快速配置: 名字、角色、昵称、使用场景(编程/写作/产品/数据分析/设计/运维/研发/营销)
  • Gateway WebSocket 连接: ws://127.0.0.1:18789 — 这是 OpenClaw Gateway 的连接方式
  • 工作区: 默认 ~/.openclaw-autoclaw/workspace，文件访问沙盒

二、当前 ZCLAW 项目现状

已有的代码 (37 文件, 2378 行)

模块 内容
src/config/ Zod 配置管理
src/utils/ Logger + ID 生成器
src/db/ SQLite Schema (8表) + BaseDAO
src/core/ai/ 智谱GLM + OpenAI Provider + AIManager
src/core/multi-agent/ MessageBus + BaseAgent + Planner/Executor/Combiner + Orchestrator
src/core/remote-execution/ 并发队列 + 任务管理
src/core/task-orchestration/ 拓扑排序 + 计划执行
src/core/memory/ 内存记忆 + 用户画像
src/core/proactive/ node-cron 定时任务
src/im/ IM Gateway + 飞书适配器
src/api/ ZClawAPI for Tauri
src/app.ts ZClawApp 主类
desktop/ Tauri + React 三栏布局

三、偏离分析 — 核心问题

🔴 严重偏离

1. 架构根本性偏离 — 没有基于 OpenClaw

问题: 项目初衷是"学习 QClaw 跟 AutoClaw，打造结合 Tauri + OpenClaw 的系统"，但当前代码完全没有 OpenClaw 的影子。

  • OpenClaw 的核心是 Gateway (Node.js 进程 + WebSocket)
  • QClaw 和 AutoClaw 都是围绕 OpenClaw 做封装
  • 我们的 ZCLAW 却从零自己发明了一套架构 (RemoteExecutionEngine / TaskOrchestrator / AgentOrchestrator)
  • 这些自创系统不是 OpenClaw 的概念，等于在重造轮子

应该: 直接集成 OpenClaw Gateway，或至少学习其架构模式来构建

2. Skills 系统完全缺失

问题: Skills 是 OpenClaw/QClaw/AutoClaw 的核心扩展机制。

  • OpenClaw 有 100+ 预配置技能
  • QClaw 有 5000+ Skills 生态
  • AutoClaw 截图显示有完整的技能管理界面
  • Skills 基于 SKILL.md 文件，三级渐进式披露，解决 Token 成本
  • 我们的 src/skills/ 目录是空的，完全没有实现

3. MCP (模型上下文协议) 完全缺失

问题: MCP 是现代 AI Agent 的标准工具扩展协议。

  • AutoClaw 内置: File System、Web Fetch，可快速添加 Brave Search、SQLite
  • OpenClaw 原生支持 MCP
  • 我们完全没有 MCP 支持

4. 工具执行层是"假的"

问题: OpenClaw 能真正操控电脑 — 执行 Shell 命令、读写文件、控制浏览器。

  • 我们的 BrowserAgent / FileAgent / TerminalAgent 实际上是用 AI 模拟输出结果
  • 没有任何真实的命令执行、文件操作或浏览器控制能力
  • 用户期望"操控电脑完成任务"，我们只能"假装操作然后编结果"

🟡 方向偏离

5. "多Agent协作" vs "分身(Clone)"概念错位

问题:

  • AutoClaw 的"分身"是独立的 Agent 实例，每个分身有自己的名字、角色、记忆、对话
  • 我们的"多 Agent"是面向任务拆解的 (Planner → Executor → Combiner)
  • 这是两种完全不同的概念

AutoClaw 的分身: 像是雇了多个助手，每个负责不同领域
我们的多 Agent: 像是一个任务流水线，Planner 规划 → Executor 执行 → Combiner 汇总

6. 持久化方式偏离

问题:

  • OpenClaw 用纯文本文件: SOUL.md, MEMORY.md, AGENTS.md — 透明、Git 可控
  • 我们用 SQLite 数据库表
  • 数据库不是错的，但缺少 OpenClaw 的透明可控理念
  • 用户无法像 Git 那样管理 AI 的"大脑"

7. 心跳引擎缺失

问题:

  • OpenClaw 的核心特色是心跳引擎 — 定期唤醒，检查 HEARTBEAT.md，主动执行任务
  • 这是"主动服务"的真正含义
  • 我们的 ProactiveServiceSystem 只是简单的 node-cron 定时器包装

8. 工作区 (Workspace) 概念缺失

问题:

  • AutoClaw 有完整的工作区管理: 项目目录、文件访问沙盒、上下文自动保存、文件监听
  • 这是 Agent 安全执行的基础
  • 我们完全没有工作区概念

🟢 方向正确

功能 评价
左侧栏三个 Tab (分身/IM频道/定时任务) ✅ 与 AutoClaw 布局一致
多模型 Provider 支持 ✅ 但需加 Gateway WebSocket 连接
IM 网关 + 飞书适配器 ✅ 但应更像 OpenClaw Channel Plugin
定时任务 ✅ 需升级为心跳引擎模式
SQLite 数据库 ✅ OpenClaw 也用 SQLite，但需补充纯文本文件
Tauri 桌面应用 ✅ 与目标一致 (QClaw用Electron, 我们用Tauri更好)
配置管理 (.env) ✅ 需要但方向对

四、偏离程度评估

整体偏离程度: ████████░░ 75%

核心原因: 项目从**"基于 OpenClaw 做 Tauri 封装"变成了"从零自建 AI Agent 框架"**。

这就像是：

  • 目标是造一辆"基于丰田平台的改装车"
  • 实际上在从零造发动机、底盘和变速箱
  • 造出来的还跟丰田的规格不兼容

五、修正建议

方案 A: 直接集成 OpenClaw（推荐）

OpenClaw Gateway (npm install openclaw)
      ↕ WebSocket (ws://127.0.0.1:18789)
Tauri Desktop App (我们的前端)
      ↕ Tauri Commands
React UI (学习 AutoClaw 的界面设计)

步骤:

  1. 安装 OpenClaw 作为依赖（或子进程启动）
  2. 通过 WebSocket 连接 OpenClaw Gateway
  3. Tauri 前端做 UI 封装（学 AutoClaw 的设计）
  4. 添加自定义 Channel Plugin (微信/QQ/飞书)
  5. 添加自定义 Skills
  6. 添加 MCP 服务管理

优点: 直接获得 OpenClaw 的全部能力 (真实工具执行、Skills 生态、MCP 等)
缺点: 学习成本，依赖外部项目

方案 B: 学习架构重构（折中）

保留 Tauri + 自己的后端，但按 OpenClaw 的架构模式重构：

  1. 重构为 Gateway 模式: 把我们的后端重构为 OpenClaw 风格的 Gateway
  2. 实现 Skills 系统: SKILL.md 文件 + 渐进式披露
  3. 实现 MCP 支持: JSON-RPC 2.0 工具扩展协议
  4. 实现真实工具: bash 命令执行、文件读写、浏览器控制 (Playwright)
  5. 实现分身系统: 每个分身 = 独立 Agent 实例 + 独立配置/记忆
  6. 实现心跳引擎: HEARTBEAT.md + 定期检查 + 主动执行
  7. 实现工作区: 项目沙盒 + 文件监听 + 上下文保存
  8. 补充纯文本持久化: SOUL.md + MEMORY.md + AGENTS.md

优点: 深度学习理解架构，自主可控
缺点: 工作量大，可能重复造轮子

方案 C: 混合方案（务实）

  • OpenClaw 作为执行引擎（子进程运行或 WebSocket 连接）
  • Tauri 做桌面 UI 封装（仿 AutoClaw 界面）
  • 自己实现差异化功能（微信接入、中文 Skills、国产模型优化）

六、需要保留 vs 需要重写 vs 需要新建

✅ 保留

  • src/config/ — 配置管理（调整 key 名称对标 OpenClaw）
  • src/utils/ — Logger + ID 生成器
  • src/db/ — SQLite 层（OpenClaw 也用 SQLite）
  • src/core/ai/ — 多模型 Provider（补充 Gateway 连接方式）
  • src/im/ — IM 网关（重构为 Channel Plugin 模式）
  • desktop/ — Tauri 前端（大幅扩展界面）

🔄 重写

  • src/core/multi-agent/ → 重构为分身 (Clone) 系统
  • src/core/remote-execution/ → 重构为真实工具执行层 (bash/file/browser)
  • src/core/task-orchestration/ → 简化，交给 LLM 自主规划
  • src/core/proactive/ → 重构为心跳引擎
  • src/core/memory/ → 补充纯文本文件 (MEMORY.md)
  • src/app.ts → 重构为 Gateway 模式

🆕 新建

  • src/skills/ — Skills 系统（SKILL.md 加载/解析/注册）
  • src/mcp/ — MCP 协议支持
  • src/tools/ — 真实工具执行 (bash, file, browser via Playwright)
  • src/workspace/ — 工作区管理（沙盒、文件监听、上下文保存）
  • src/gateway/ — WebSocket Gateway 服务
  • 前端设置页面（通用/用量统计/模型API/MCP/技能/IM/工作区/隐私）

七、结论

当前项目已经严重偏离了"学习 QClaw/AutoClaw + 基于 OpenClaw"的初衷。

核心问题不在于代码质量（代码是可以编译的），而在于架构方向：我们在自己发明一套 AI Agent 框架，而不是基于 OpenClaw 做 Tauri 封装。

建议选择方案后，优先做以下事情：

  1. 深入研究 OpenClaw 源码和 Gateway 架构
  2. 确定是直接集成还是学习重构
  3. 实现 Skills 系统和 MCP 支持
  4. 实现真实工具执行能力
  5. 按 AutoClaw 界面设计前端

本报告基于 QClaw 官网、AutoClaw 官网 + 13张界面截图、OpenClaw GitHub + 技术文章的深度分析