zclaw/DEVELOPMENT.md

ZCLAW 完整开发文档

版本: v1.0
日期: 2026-03-11
状态: 开发前梳理

---

📋 项目概述

核心定位

ZCLAW 是什么？

• 基于 OpenClaw 的 AI 代理平台
• 不是重新造轮子，而是扩展 OpenClaw 的能力
• 目标：随时随地、一个 IM 入口搞定一切

与 OpenClaw 的关系

OpenClaw (基础能力层) ↓ ZCLAW (增强层) ↓ 场景化解决方案

关键理解：

• OpenClaw 提供：浏览器控制、文件操作、终端命令、记忆系统、技能系统
• ZCLAW 提供：远程执行、任务编排、多 Agent 协作、持续记忆、主动服务
• ZCLAW 复用 OpenClaw SDK，不是重写

---

🎯 用户的核心需求

1. 远程操控

场景： 用户在地铁上 → 手机发微信 → 家里电脑执行任务 → 结果返回微信

痛点：

• 必须坐在电脑前才能用 OpenClaw
• 手机只能查看，不能操控
• 无法随时随地处理任务

解决方案：

• IM 消息触达 → Gateway → 本地执行 → 结果回流 IM

2. 复杂任务自动化

场景： 用户："帮我做市场调研" ZCLAW：自动拆解 10 步 → 逐步执行 → 完整报告

痛点：

• 单步命令无法完成复杂任务
• 需要人工拆解和协调
• 没有进度可视化

解决方案：

• AI 规划任务
• 多步骤编排
• 进度实时推送

3. 持续记忆

场景： 用户上次说"我喜欢简洁的回复" ZCLAW 记住 → 下次自动简洁回复

痛点：

• 每次对话都是新的，没有记忆
• 需要重复说明偏好
• 无法跨会话学习

解决方案：

• 用户画像存储
• 行为模式学习
• 跨会话记忆

4. 主动服务

场景： 设置每天 8 点推送天气 ZCLAW：主动推送，无需询问

痛点：

• 只能被动响应
• 无法设置定时任务
• 缺少主动提醒

解决方案：

• Cron 定时任务
• 主动消息推送
• 智能提醒

---

🏗️ 技术架构

整体架构

┌─────────────────────────────────────────────────────────────┐ │ 用户入口层 │ │ 飞书 | 企业微信 | Telegram | QQ | Tauri 桌面端 │ └────────────────────┬────────────────────────────────────────┘ │ ┌────────────────────▼────────────────────────────────────────┐ │ ZCLAW 网关层 │ │ - 消息路由 │ │ - 认证授权 │ │ - 限流控制 │ └────────────────────┬────────────────────────────────────────┘ │ ┌────────────────────▼────────────────────────────────────────┐ │ ZCLAW 核心系统层 │ │ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ 远程执行系统 │ │ 任务编排引擎 │ │ 多Agent协作 │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ 持续记忆系统 │ │ 主动服务系统 │ │ 上下文回流 │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │ │ └────────────────────┬────────────────────────────────────────┘ │ ┌────────────────────▼────────────────────────────────────────┐ │ OpenClaw 基础能力层 │ │ 浏览器 | 文件系统 | 终端 | AI模型 | Skills | 记忆 │ └────────────────────┬────────────────────────────────────────┘ │ ┌────────────────────▼────────────────────────────────────────┐ │ 数据存储层 │ │ SQLite (结构化) | sqlite-vec (向量) | Redis (缓存) │ └─────────────────────────────────────────────────────────────┘

核心系统详解

1. 远程执行系统

职责：

• 设备注册与管理
• 任务队列调度
• 执行状态同步
• 结果推送

关键接口： ` ypescript interface RemoteExecutionSystem { // 设备管理 registerDevice(device: Device): Promise; heartbeat(deviceId: string): Promise;

// 任务管理 submitTask(task: Task): Promise; cancelTask(taskId: string): Promise;

// 状态同步 getStatus(taskId: string): Promise; subscribe(taskId: string, handler: StatusHandler): void;

// 结果推送 pushResult(taskId: string, result: Result): Promise; } `

数据模型： ` ypescript interface Device { id: string; name: string; userId: string; platform: 'macos' | 'windows' | 'linux'; capabilities: string[]; status: 'online' | 'offline' | 'busy'; lastHeartbeat: Date; }

interface Task { id: string; userId: string; deviceId: string; channel: string; // 来源渠道（飞书/微信/...） type: 'immediate' | 'scheduled'; priority: 'high' | 'normal' | 'low'; payload: any; status: TaskStatus; result?: any; createdAt: Date; startedAt?: Date; completedAt?: Date; } `

实现要点：

• 使用 BullMQ 任务队列（支持优先级、重试、延迟）
• WebSocket 实时状态同步
• 多渠道结果推送（飞书/微信/...）

2. 任务编排引擎

职责：

• 任务规划（AI 拆解）
• 多步骤编排
• 依赖管理
• 进度可视化
• 错误恢复

关键接口： ypescript interface TaskOrchestrationEngine { plan(goal: string, context: Context): Promise<TaskPlan>; execute(plan: TaskPlan): Promise<ExecutionResult>; getProgress(planId: string): Promise<Progress>; pause(planId: string): Promise<void>; resume(planId: string): Promise<void>; cancel(planId: string): Promise<void>; }

AI 规划 Prompt： ` 你是一个任务规划专家。请将以下目标拆解为可执行步骤：

目标: {goal}

可用工具:

• browser: 浏览器操作（访问网页、截图、填表）
• file: 文件操作（读写、搜索、整理）
• terminal: 终端命令（代码执行、系统操作）
• api: API 调用（搜索、查询、推送）

上下文: {context}

要求:

1. 每个步骤明确、可执行
2. 标注步骤之间的依赖关系
3. 标注每个步骤需要的工具

输出格式 (JSON): { "steps": [ { "id": "step_1", "description": "步骤描述", "tool": "browser", "params": {...}, "dependencies": [] } ] } `

执行流程： `

1. AI 规划 → 生成任务图
2. 拓扑排序 → 确定执行顺序
3. 检查依赖 → 等待前置步骤
4. 执行步骤 → 调用 OpenClaw 工具
5. 更新上下文 → 传递结果
6. 推送进度 → IM 渠道
7. 错误恢复 → 重试/跳过/失败 `

3. 多 Agent 协作系统

职责：

• Agent 生命周期管理
• 任务分配
• Agent 间通信
• 结果整合

Agent 类型： ypescript type AgentType = | 'planner' // 规划 Agent | 'browser' // 浏览器 Agent | 'file' // 文件 Agent | 'terminal' // 终端 Agent | 'combiner' // 整合 Agent | 'custom'; // 自定义 Agent

协作模式： 用户："做市场调研" ↓ Planner Agent：拆解任务 ↓ ┌─────────┬─────────┬─────────┐ │Browser │ Browser │ Browser │ ← 并行执行 │Agent │ Agent │ Agent │ └─────────┴─────────┴─────────┘ ↓ Combiner Agent：整合结果 ↓ 最终报告 → 推送给用户

4. 持续记忆系统

职责：

• 用户画像管理
• 行为模式学习
• 长期记忆存储
• 关系图谱构建
• 主动推荐

数据模型： ` ypescript interface UserProfile { userId: string;

// 偏好记忆 preferences: { language: 'zh' | 'en'; model: string; responseStyle: 'concise' | 'detailed'; timezone: string; };

// 上下文记忆 contexts: { lastTopic: string; ongoingTasks: Task[]; recentFiles: string[]; };

// 行为模式 patterns: { activeHours: number[]; frequentCommands: string[]; preferredChannels: string[]; }; } `

实现要点：

• SQLite 存储结构化数据
• sqlite-vec 向量搜索
• 定期分析用户行为模式

5. 主动服务系统

职责：

• 定时任务调度
• 智能提醒
• 主动推荐
• 异常预警

关键接口： ` ypescript interface ProactiveServiceSystem { scheduleTask(task: ScheduledTask): Promise; cancelTask(taskId: string): Promise; listTasks(userId: string): Promise<ScheduledTask[]>;

// 智能提醒 smartReminder(): Promise;

// 主动推荐 proactiveRecommendation(userId: string): Promise; } `

定时任务示例： ypescript const task: ScheduledTask = { id: 'daily_weather', userId: 'user_123', channel: 'feishu', schedule: { type: 'daily', time: '08:00', timezone: 'Asia/Shanghai', }, task: { type: 'weather', prompt: '推送今天的天气', }, status: 'active', };

---

🎨 Tauri 桌面端设计

界面布局

┌────────────────────────────────────────────────────────────────┐ │ ZCLAW 🦞 [分身] [IM 频道] [定时任务] [—] [□] [×] │ ├──────────────┬──────────────────────────┬─────────────────────┤ │ │ │ │ │ 左侧边栏 │ 中间对话区域 │ 右侧边栏 │ │ (240px) │ (自适应) │ (320px) │ │ │ │ │ │ ┌──────────┐ │ ┌──────────────────────┐ │ ┌─────────────────┐ │ │ │ Agent 列表│ │ │ 消息列表 │ │ │ 任务进度 │ │ │ │ │ │ │ │ │ │ │ │ │ │ 🦞 ZCLAW │ │ │ 🦞: 收到消息... │ │ │ ████████░░ 80% │ │ │ │ 🔍 沉思 │ │ │ │ │ │ │ │ │ │ 🌐 浏览器 │ │ │ 👤: 做市场调研 │ │ │ 今日统计 │ │ │ │ 📊 监控 │ │ │ │ │ │ • 任务: 8 │ │ │ └──────────┘ │ │ 🦞: 正在规划... │ │ │ • 成功: 6 │ │ │ │ │ │ │ │ │ │ │ ┌──────────┐ │ ┌──────────────────────┐ │ │ 下一步行动 │ │ │ │ 用户信息 │ │ │ 输入框 │ │ │ ☐ 初始化项目 │ │ │ └──────────┘ │ └──────────────────────┘ │ │ ☐ 集成 SDK │ │ │ │ │ └─────────────────┘ │ └──────────────┴──────────────────────────┴─────────────────────┘

技术栈

• 框架: Tauri 2.0 (Rust + React)
• 前端: React 18 + TypeScript
• 样式: Tailwind CSS
• 图标: Lucide React
• 状态: Zustand
• 构建: Vite

核心组件

1. Sidebar (左侧边栏)

• Agent 列表
• IM 频道列表
• 定时任务列表
• 用户信息

2. ChatArea (中间对话区域)

• 消息列表
• 消息气泡（用户/AI）
• 输入框
• 模型选择器

3. RightPanel (右侧边栏)

• 任务进度条
• 今日统计
• 下一步行动
• 文件预览

与 OpenClaw 的集成

` ypescript // OpenClaw 客户端 class OpenClawClient { private rpcUrl: string;

async send(message: string): Promise { const response = await fetch(this.rpcUrl, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ message, sessionId: this.sessionId, }), });

return response.json();

} } `

---

📅 开发计划

阶段 1: MVP (Week 1-2)

目标: 最小可用版本

功能	优先级	工作量
项目初始化	P0	0.5 天
远程执行系统基础	P0	2 天
飞书集成	P0	1 天
基础 IM 消息处理	P0	1 天
Tauri 桌面端基础	P0	2 天
持续记忆基础	P0	1 天
测试 & 优化	P0	1 天

交付物:

• ✅ 远程执行系统可用
• ✅ 飞书可发送消息并执行
• ✅ Tauri 桌面端可运行
• ✅ 基础记忆功能

阶段 2: 增强 (Week 3-4)

目标: 完善核心功能

功能	优先级	工作量
任务编排引擎	P1	3 天
多 Agent 协作	P1	3 天
企业微信集成	P1	1 天
Telegram 集成	P1	1 天
主动服务系统	P1	2 天

交付物:

• ✅ 复杂任务可拆解执行
• ✅ 多 Agent 可协作
• ✅ 多 IM 渠道支持
• ✅ 定时任务可用

阶段 3: 场景化 (Week 5-6)

目标: 场景解决方案

功能	优先级	工作量
社媒运营方案	P2	3 天
学术研究方案	P2	2 天
自动开发方案	P2	3 天
文档 & 优化	P2	2 天

交付物:

• ✅ 3 个场景化方案
• ✅ 完整文档
• ✅ 用户测试

---

🔧 技术栈详解

后端

类别	技术	版本	用途
语言	TypeScript	5.x	类型安全
运行时	Node.js	22 LTS	稳定
框架	OpenClaw SDK	latest	复用基础能力
数据库	SQLite	9.x	本地存储
向量	sqlite-vec	0.1.x	向量搜索
队列	BullMQ	5.x	任务队列
缓存	Redis (可选)	7.x	缓存
定时	node-cron	3.x	Cron 调度
IM	Koishi	4.x	IM 集成

前端 (Tauri)

类别	技术	版本	用途
框架	Tauri	2.0	桌面应用
前端	React	18	UI 框架
样式	Tailwind CSS	4.x	快速开发
图标	Lucide React	latest	图标库
状态	Zustand	5.x	状态管理
构建	Vite	7.x	构建工具

---

📂 项目结构

G:\ZClaw/ ├── src/ # 后端代码 │ ├── core/ # 核心系统 │ │ ├── remote-execution/ # 远程执行 │ │ ├── task-orchestration/ # 任务编排 │ │ ├── multi-agent/ # 多 Agent 协作 │ │ ├── memory/ # 持续记忆 │ │ └── proactive/ # 主动服务 │ ├── im/ # IM 集成 │ │ ├── feishu/ # 飞书 │ │ ├── wecom/ # 企业微信 │ │ ├── telegram/ # Telegram │ │ └── koishi/ # Koishi 适配器 │ ├── skills/ # 场景化 Skills │ │ ├── social-media/ # 社媒运营 │ │ ├── research/ # 学术研究 │ │ └── development/ # 自动开发 │ ├── api/ # API 接口 │ ├── db/ # 数据库 │ └── index.ts # 入口 │ ├── desktop/ # Tauri 桌面端 │ ├── src/ │ │ ├── components/ # React 组件 │ │ ├── hooks/ # React Hooks │ │ ├── store/ # Zustand Store │ │ ├── utils/ # 工具函数 │ │ ├── App.tsx # 主应用 │ │ └── main.tsx # 入口 │ ├── src-tauri/ # Rust 后端 │ │ ├── src/ │ │ │ ├── main.rs # 入口 │ │ │ ├── commands.rs # Tauri 命令 │ │ │ └── openclaw.rs # OpenClaw 集成 │ │ ├── Cargo.toml │ │ └── tauri.conf.json │ ├── package.json │ └── vite.config.ts │ ├── tests/ # 测试 ├── docs/ # 文档 ├── package.json # 后端依赖 ├── tsconfig.json # TS 配置 ├── README.md # 项目说明 └── PROGRESS.md # 开发进度

---

🚀 快速开始

后端开发

`ash

1. 安装依赖

cd G:\ZClaw pnpm install

2. 配置环境变量

cp .env.example .env

编辑 .env 填入 API keys

3. 启动开发服务器

pnpm dev

4. 运行测试

pnpm test `

Tauri 桌面端

`ash

1. 安装依赖

cd G:\ZClaw\desktop pnpm install

2. 启动开发服务器

pnpm tauri dev

3. 构建生产版本

pnpm tauri build `

---

🎯 成功指标

技术指标

指标	目标
响应延迟 (P95)	< 3s
可用性 (SLA)	> 99%
任务成功率	> 95%
并发用户数	> 100

产品指标

指标	目标
DAU (MVP)	> 100
用户留存 (7日)	> 40%
任务完成率	> 90%
NPS	> 50

---

📝 关键决策

决策 1: 渐进式开发

• 理由: 快速验证，降低风险
• 方案: MVP → 增强 → 场景化

决策 2: 复用 OpenClaw

• 理由: 不重复造轮子
• 方案: 使用 OpenClaw SDK

决策 3: Tauri 桌面端

• 理由: 跨平台、性能好
• 方案: Tauri 2.0 + React

决策 4: Koishi IM 集成

• 理由: 成熟的 IM 适配器
• 方案: Koishi + 自定义插件

---

⚠️ 风险与缓解

风险	概率	影响	缓解措施
OpenClaw SDK 不稳定	中	高	多 Provider fallback
IM 平台封号	中	高	使用官方 API、合规使用
性能瓶颈	中	中	异步处理、缓存优化
需求变更	高	中	敏捷开发、MVP 优先

---

📚 参考资料

• [OpenClaw 文档](C:\Program Files\AutoClaw\resources\gateway\openclaw\docs)
• Tauri 文档
• Koishi 文档
• BullMQ 文档

---

维护者: ZCLAW 团队
最后更新: 2026-03-11 22:10