cc工作前备份

docs/deviation-analysis.md

@@ -0,0 +1,310 @@
+# 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 + 技术文章的深度分析*