# 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<void>;
  heartbeat(deviceId: string): Promise<DeviceStatus>;
  
  // 任务管理
  submitTask(task: Task): Promise<string>;
  cancelTask(taskId: string): Promise<void>;
  
  // 状态同步
  getStatus(taskId: string): Promise<TaskStatus>;
  subscribe(taskId: string, handler: StatusHandler): void;
  
  // 结果推送
  pushResult(taskId: string, result: Result): Promise<void>;
}
`

**数据模型**：
`	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<void>;
  cancelTask(taskId: string): Promise<void>;
  listTasks(userId: string): Promise<ScheduledTask[]>;
  
  // 智能提醒
  smartReminder(): Promise<void>;
  
  // 主动推荐
  proactiveRecommendation(userId: string): Promise<void>;
}
`

**定时任务示例**：
`	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<Response> {
    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 文档](https://tauri.app)
- [Koishi 文档](https://koishi.chat)
- [BullMQ 文档](https://docs.bullmq.io)

---

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