docs: add comprehensive development documentation

DEVELOPMENT.md

@@ -0,0 +1,712 @@
+# 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