Files
zclaw_openfang/PROGRESS.md
2026-03-12 00:23:42 +08:00

451 lines
18 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# ZCLAW 开发进度报告
**日期**: 2026-03-11 23:15
**状态**: ✅ v2 架构重构完成 — 基于 OpenClaw 定制化
---
## 🔄 v2 架构重构 (2026-03-11)
### 背景
通过深度研究 QClaw (腾讯)、AutoClaw (智谱 v0.2.12)、OpenClaw (GitHub 28万+ Stars)
发现 v1 代码偏离初衷约 75% — 自创架构而非基于 OpenClaw。v2 进行了完整的架构重构。
详见: [偏离分析报告](docs/deviation-analysis.md) | [v2 架构设计](docs/architecture-v2.md)
### ✅ 新增: OpenClaw Gateway 集成层 (src/gateway/)
- **manager.ts**: Gateway 子进程管理 — 启动/停止/健康检查/自动重启
- **ws-client.ts**: Node.js WebSocket 客户端 — 完整 Gateway Protocol v3 握手/请求/事件
- **index.ts**: 统一导出
### ✅ 新增: 自定义 OpenClaw 插件 (plugins/)
#### @zclaw/chinese-models — 中文模型 Provider
- 智谱 GLM (glm-5, glm-4.7, glm-4-plus, glm-4-flash)
- 通义千问 Qwen (qwen3.5-plus, qwen-max, qwen-vl-max)
- Kimi 月之暗面 (kimi-k2.5, moonshot-v1-128k)
- MiniMax (minimax-m2.5, abab6.5s-chat)
#### @zclaw/feishu — 飞书 Channel Plugin
- OAuth tenant_access_token 自动管理
- 发送文本/富文本消息
- 多账户支持
- 自定义 RPC: feishu.status
#### @zclaw/ui — UI 扩展 RPC
- zclaw.clones.list/create/update/delete — 分身管理
- zclaw.stats.usage/sessions — 用量统计 (读取 JSONL sessions)
- zclaw.config.quick — 快速配置
- zclaw.workspace.info — 工作区信息
- zclaw.plugins.status — 插件状态
### ✅ 新增: 自定义 Skills (skills/)
- **chinese-writing** — 中文写作助手 (SKILL.md)
- **feishu-docs** — 飞书文档操作 (SKILL.md)
### ✅ 新增: OpenClaw 配置模板 (config/)
- **openclaw.default.json** — 预配置中文模型 + 插件路径 + Skills 目录
- **SOUL.md** — ZCLAW 人格定义
- **AGENTS.md** — Agent 操作规范
- **IDENTITY.md** — Agent 身份 (🦞 小龙虾)
- **USER.md** — 默认用户偏好
### ✅ 新增: 前端 Gateway 客户端 (desktop/src/)
- **lib/gateway-client.ts** — 浏览器 WebSocket 客户端 (Gateway Protocol v3)
- **store/gatewayStore.ts** — Zustand 状态管理 (连接/分身/统计)
### ✅ 新增: 设置脚本 (scripts/)
- **setup.ts** — 首次设置: 检测 OpenClaw → 复制配置 → 注册插件 → 创建工作区
### ✅ 编译验证
- TypeScript: **0 errors** (新架构代码)
- 依赖精简: 移除 bullmq/ioredis/better-sqlite3/koishi, 保留 ws + zod
---
## 📊 代码统计 (v2)
| 类别 | 文件数 | 说明 |
|------|--------|------|
| Gateway 层 | 3 | manager.ts, ws-client.ts, index.ts |
| 插件 | 6 | 3 plugins × (index.ts + plugin.json) |
| Skills | 2 | 2 × SKILL.md |
| 配置 | 5 | 1 JSON + 4 MD |
| 前端新增 | 2 | gateway-client.ts, gatewayStore.ts |
| 脚本 | 1 | setup.ts |
| **合计新增** | **19** | v2 新架构文件 |
---
## ✅ Phase 2: 前端 Settings 页面体系 (2026-03-11 23:26)
### Settings 页面 (对标 AutoClaw 10 个页面)
- **SettingsLayout.tsx** — 左侧导航 + 右侧内容的双栏布局
- **General.tsx** — 账号安全 + Gateway 连接状态 + 主题/自启/工具调用
- **UsageStats.tsx** — 会话数/消息数/Token 汇总 + 按模型进度条
- **ModelsAPI.tsx** — 内置/自定义模型列表 + Gateway URL 配置
- **MCPServices.tsx** — MCP 服务列表 + 启停 + 快速添加模板
- **Skills.tsx** — 技能列表 + 额外目录配置 + 筛选标签
- **IMChannels.tsx** — IM 频道管理 + 快速添加飞书
- **Workspace.tsx** — 项目目录 + 文件访问限制 + 自动保存 + 文件监听
- **Privacy.tsx** — 本地数据路径 + 优化计划开关 + 备案信息
- **About.tsx** — 版本信息 + 检查更新 + 更新日志
### App.tsx 重构
- main / settings 视图切换
- Sidebar ⚙ 按钮 → onOpenSettings → SettingsLayout
- SettingsLayout ← 返回 → main view
### 构建修复
- 修复 RightPanel.tsx 未使用 CheckSquare import
- 修复 Tailwind v4: 安装 @tailwindcss/vite, 替换 @tailwind@import "tailwindcss"
- 修复根 package.json UTF-8 BOM 导致 PostCSS config 解析失败
- **Vite build: ✅ 成功** (1761 modules, 239 KB JS + 23 KB CSS)
- **TypeScript: ✅ 0 errors** (backend + frontend 双项目)
---
## ✅ Phase 3: 聊天对接 + 分身管理 (2026-03-11 23:34)
### chatStore 重构 → Gateway WebSocket
- **sendMessage()** — 通过 Gateway WS 发送 `agent` RPC, 创建流式占位消息
- **initStreamListener()** — 监听 `agent` 事件, 实时追加 assistant delta / tool call / lifecycle
- 支持 session key 连续对话
- Gateway 未连接时优雅降级 (错误显示在气泡中)
### ChatArea 重构
- **流式输出** — assistant 消息带闪烁光标, 实时追加 delta
- **工具调用展示** — `tool` 类型消息, 显示工具名 + 输入 + 输出 (Terminal 图标)
- **模型选择器** — 下拉菜单切换 glm-5 / qwen3.5-plus / kimi-k2.5 / minimax-m2.5
- **连接状态** — 顶部显示 Gateway 连接状态 (绿点/灰点)
- **自动滚动** — 新消息自动滚到底部
- 输入区: 流式回复时禁用, Enter 发送, Shift+Enter 换行
### 分身管理 UI (CloneManager)
- **CloneManager.tsx** — 完整 CRUD: 创建表单 (名称/角色/场景标签) + 列表 + 悬浮删除
- **集成到 Sidebar** — 分身/IM 频道/定时任务 三标签, 分身标签使用 CloneManager
- **Sidebar 重构** — Gateway 连接状态显示在用户区, IM 频道和定时任务占位页
### 编译验证
- **TypeScript: ✅ 0 errors** (backend + frontend)
- **Vite build: ✅ 成功** (1762 modules, 247 KB JS + 24 KB CSS)
---
## ✅ Phase 3.5: 前端质量提升 (2026-03-11 23:42)
### Gateway 自动连接
- **App.tsx** — 启动时自动尝试连接 Gateway (silent fail不阻塞 UI)
- 导入 `useGatewayStore`useEffect 在 `disconnected` 状态下触发 `connect()`
### RightPanel 重写 → 实时数据
- **RightPanel.tsx** — 从全硬编码改为从 gatewayStore/chatStore 读取真实数据
- Gateway 连接状态 (绿色/灰色卡片, 地址/版本/当前模型)
- 手动重连按钮 (Gateway 未连接时显示)
- 当前会话统计 (用户消息/助手回复/工具调用/总数)
- 分身列表 (从 Gateway 加载)
- 用量统计 (总会话/消息/Token)
- 插件状态 (名称 + 运行状态)
- 系统信息 (版本/协议/平台)
- 刷新按钮 (一键重新加载所有数据)
### ChatArea 升级
- **多行输入** — `<input>``<textarea>` 自动伸缩 (minHeight 24px, maxHeight 160px)
- **Markdown 渲染** — 轻量级渲染器:代码块 (带语言标签), 内联代码, **粗体**, *斜体*, [链接](url)
- **新对话按钮** — 头部右侧显示 "新对话" 按钮 (SquarePen 图标)
- placeholder 更新: "发送给 ZCLAWShift+Enter 换行)"
### 对话会话管理
- **chatStore** 新增:
- `Conversation` 类型 (id/title/messages/sessionKey/createdAt/updatedAt)
- `conversations[]` + `currentConversationId` 状态
- `newConversation()` — 保存当前对话到历史, 开启新对话
- `switchConversation(id)` — 切换到历史对话 (自动保存当前)
- `deleteConversation(id)` — 删除历史对话
- `deriveTitle()` — 从第一条用户消息自动提取标题
- **ConversationList.tsx** (新组件) — 对话历史列表
- 当前活跃对话高亮显示
- 历史对话: 标题 + 消息数 + 相对时间
- 悬浮删除按钮
- 新对话按钮
### Sidebar 重构 → 四标签
- **4 标签**: 对话 / 分身 / 频道 / 任务
- TABS 配置化 (key/label/icon 数组)
- 对话标签使用 ConversationList
- 频道标签使用 ChannelList (新组件)
### IM 频道管理
- **gateway-client.ts** 新增: `listChannels()`, `getFeishuStatus()` 方法
- **gatewayStore** 新增:
- `ChannelInfo` 类型 + `channels[]` 状态
- `loadChannels()` — 先尝试 Gateway channels.list, 回退到单独探测飞书/QQ
- **ChannelList.tsx** (新组件) — 频道列表
- 显示已配置频道 (飞书/QQ) 及状态
- 未配置频道灰色占位提示
- "打开设置" 快捷入口
- 刷新按钮
### 对话历史持久化
- **chatStore** — Zustand `persist` 中间件集成 localStorage
- `partialize` 仅保存 conversations + currentModel (排除 streaming/transient 状态)
- `onRehydrateStorage` 正确处理 Date JSON 反序列化, 清除残留 streaming 标记
- 存储 key: `zclaw-chat-storage`
### 定时任务管理
- **gateway-client.ts** 新增: `listScheduledTasks()` 方法
- **gatewayStore** 新增:
- `ScheduledTask` 类型 (id/name/schedule/status/lastRun/nextRun/description)
- `scheduledTasks[]` 状态 + `loadScheduledTasks()`
- **TaskList.tsx** (新组件) — Heartbeat 任务列表
- 按状态图标着色 (运行中/暂停/完成/错误)
- 显示 cron 表达式 + 上次/下次执行时间
- 刷新按钮 + Gateway 未连接提示
### Settings 页面接入真实数据
- **General.tsx** 重写:
- Gateway 连接状态面板 (状态灯/地址/版本/当前模型/错误)
- 连接/断开按钮 (connect/disconnect)
- Toggle 组件 CSS 修复 (flex-shrink-0 + transition-all)
- **ModelsAPI.tsx** 重写:
- 中文模型列表从 chatStore 读取 currentModel, 点击切换
- Gateway URL 输入框 + 连接状态 + 重新连接按钮
- 每个模型显示 Provider 来源
### 编译验证 (最终)
- **TypeScript: ✅ 0 errors** (backend + frontend)
- **Vite build: ✅ 成功** (1766 modules, 268 KB JS + 26 KB CSS)
- **Dev server: ✅** (http://127.0.0.1:1420, 422ms 启动)
---
## 📋 下一步
### Phase 4: 真实集成测试
- [ ] 安装 OpenClaw 并验证 Gateway 连接
- [ ] 测试自定义插件注册
- [ ] 测试飞书 Channel 收发消息
- [ ] 测试中文模型调用
- [ ] 验证前端自动连接 + 数据加载
### Phase 5: 高级功能
- [ ] 微信/QQ Channel Plugin
- [ ] 更多 Skills 开发
- [ ] Tauri Rust sidecar (Gateway 子进程管理)
- [ ] 打包发布
- [ ] 对话历史持久化 (localStorage / IndexedDB)
---
## 🔗 v1 旧代码 (归档)
以下代码位于 src/core/, src/db/, src/config/ 等目录,
已从 tsconfig 编译范围中排除,保留供参考。
v1 进度详情如下:
---
**原 v1 进度 (2026-03-11 22:30)**
**状态**: v1 架构已归档,保留供参考
---
## 📦 本次完成工作
### Phase 1: 基础修复 + 基础设施
#### ✅ Bug 修复
- 修复全部后端文件的**模板字符串损坏**engine.ts, orchestrator.ts, memory.ts, proactive.ts
- 修复 `Sidebar.tsx` 缺失 React import 和 className 模板字面量
- 修复 `ChatArea.tsx` className 模板字面量
- 修复 `tsconfig.json` 添加 `@types/node` 支持
- 修复 `package.json` 移除不存在的 `@openclaw/sdk`
#### ✅ 配置管理系统 (src/config/)
- Zod Schema 驱动的类型安全配置
- 支持环境变量 + 默认值 fallback
- 涵盖: AI Provider / Database / Server / IM / Execution / Memory / Logging
- `.env.example` 完整配置模板
#### ✅ 工具函数 (src/utils/)
- **logger.ts**: 分级彩色日志系统 (debug/info/warn/error),模块化 createLogger
- **id.ts**: crypto.randomBytes 安全 ID 生成器,支持前缀
- **index.ts**: 统一导出
#### ✅ 数据库层 (src/db/)
- **schema.ts**: 完整 SQLite Schema — 8 张表 + 8 个索引
- users / devices / tasks / task_plans / memory_events / scheduled_tasks / conversations / agents
- **database.ts**: WAL 模式、BaseDAO 泛型 CRUD、事务支持
- **依赖安装**: better-sqlite3 + sqlite-vec + @types/better-sqlite3
---
### Phase 2: 全新系统
#### ✅ AI 模型集成层 (src/core/ai/)
- **types.ts**: ChatMessage / ChatRequest / ChatResponse / StreamChunk / EmbeddingRequest / AIProvider 接口
- **providers/zhipu.ts**: 智谱 GLM Provider — chat + stream + embed
- **providers/openai.ts**: OpenAI 兼容 Provider — 支持任意 baseUrl
- **manager.ts**: 统一 AI 管理器
- 多 Provider 自动 fallback
- 便捷方法: ask() / chatWithHistory() / askJson()
- 流式输出支持
#### ✅ 多 Agent 协作系统 (src/core/multi-agent/) — **全新**
- **types.ts**: AgentType / AgentConfig / AgentTask / AgentResult / MultiAgentPlan
- **message-bus.ts**: Agent 间消息总线 — 订阅/发布/广播/消息日志
- **base-agent.ts**: Agent 抽象基类 — 生命周期管理/消息处理/状态追踪
- **agents/planner-agent.ts**: 规划 Agent — AI 驱动任务拆解
- **agents/executor-agent.ts**: 4 种执行 Agent (Browser/File/Terminal/AIAnalysis)
- **agents/combiner-agent.ts**: 结果整合 Agent — 生成报告
- **orchestrator.ts**: Agent 编排器 — 完整的 Plan→Execute→Combine 工作流
- 自动规划任务
- 拓扑排序依赖执行
- 上下文传递
- 进度回调
#### ✅ IM 网关层 (src/im/) — **全新**
- **types.ts**: IMMessage / IMAdapter / IMSendOptions 接口
- **gateway.ts**: 统一消息路由 — 适配器注册/消息转发/多渠道管理
- **adapters/feishu.ts**: 飞书适配器 — OAuth认证/消息收发/Mock模式
---
### Phase 3: 核心系统升级 + 应用集成
#### ✅ 远程执行系统升级
- 集成 Logger 结构化日志
- 使用 generateId 安全ID
- **新增**: 并发控制 (maxConcurrent) + 优先级队列
- **新增**: listDevices() / listTasks() / getStats()
#### ✅ 任务编排引擎升级
- 集成 Logger + generateId
- **新增**: listPlans() 查询接口
#### ✅ 持续记忆系统升级
- 集成 Logger + generateId
- **新增**: 自动创建用户画像 + getEventCount()
#### ✅ 主动服务系统升级
- 集成 Logger + generateId
- **新增**: node-cron 集成 + toCronExpression() 时间转换
#### ✅ 应用主类 (src/app.ts) — **全新**
- ZClawApp: 统一协调 7 大系统的启动/路由/关闭
- 消息路由: IM → 记忆 → 复杂度判断 → AI对话/多Agent协作 → 回复
- 优雅退出: SIGINT/SIGTERM 处理
#### ✅ API 层 (src/api/) — **全新**
- ZClawAPI: 供 Tauri 前端调用的完整接口
- 覆盖: 聊天 / 任务 / 多Agent / 记忆 / 定时任务 / 系统状态
#### ✅ 入口重写 (src/index.ts)
- 完整启动流程 + 全模块导出 + 优雅退出
---
## 📊 代码统计
| 类别 | 文件数 | 代码行数 | 说明 |
|------|--------|----------|------|
| **后端源码** | 37 | ~2378 行 | 7 大核心系统 + 基础设施 |
| **Tauri 前端** | 7 | ~700 行 | 3 组件 + 状态管理 (已修复) |
| **配置文件** | 5 | ~100 行 | TS/Tailwind/Vite/env |
| **总计** | **49** | **~3178 行** | TypeScript 零错误编译 |
**相比上一版本**: 文件 22→49 (+123%), 代码 1400→3178 (+127%)
---
## 🏗️ 项目结构
```
G:\ZClaw/
├── src/ # 后端代码 (37 files, 2378 lines)
│ ├── index.ts # ✅ 入口 + 启动流程
│ ├── app.ts # ✅ ZClawApp 主类 (NEW)
│ ├── config/ # ✅ 配置管理 (NEW)
│ │ └── index.ts # Zod Schema + 环境变量
│ ├── utils/ # ✅ 工具函数 (NEW)
│ │ ├── logger.ts # 分级彩色日志
│ │ ├── id.ts # 安全 ID 生成
│ │ └── index.ts
│ ├── db/ # ✅ 数据库层 (NEW)
│ │ ├── schema.ts # 8 张表 + 索引
│ │ ├── database.ts # SQLite WAL + BaseDAO
│ │ └── index.ts
│ ├── core/ # 核心系统
│ │ ├── ai/ # ✅ AI 集成 (NEW)
│ │ │ ├── types.ts # 统一 AI 类型
│ │ │ ├── providers/zhipu.ts # 智谱 GLM
│ │ │ ├── providers/openai.ts # OpenAI 兼容
│ │ │ ├── manager.ts # 多 Provider 管理
│ │ │ └── index.ts
│ │ ├── multi-agent/ # ✅ 多Agent协作 (NEW)
│ │ │ ├── types.ts # Agent 类型体系
│ │ │ ├── message-bus.ts # 消息总线
│ │ │ ├── base-agent.ts # Agent 基类
│ │ │ ├── agents/planner.ts # 规划 Agent
│ │ │ ├── agents/executor.ts # 4种执行 Agent
│ │ │ ├── agents/combiner.ts # 整合 Agent
│ │ │ ├── orchestrator.ts # Agent 编排器
│ │ │ └── index.ts
│ │ ├── remote-execution/ # ✅ 远程执行 (升级)
│ │ ├── task-orchestration/ # ✅ 任务编排 (升级)
│ │ ├── memory/ # ✅ 持续记忆 (升级)
│ │ └── proactive/ # ✅ 主动服务 (升级)
│ ├── im/ # ✅ IM 网关 (NEW)
│ │ ├── types.ts # IM 抽象接口
│ │ ├── gateway.ts # 统一消息路由
│ │ ├── adapters/feishu.ts # 飞书适配器
│ │ └── index.ts
│ ├── api/ # ✅ API 层 (NEW)
│ │ └── index.ts # Tauri Commands 接口
│ └── skills/ # ⏳ 场景 Skills (待开发)
├── desktop/ # Tauri 桌面端 (已修复)
├── .env.example # ✅ 环境变量模板 (NEW)
├── package.json # ✅ 依赖已安装
├── tsconfig.json # ✅ 类型配置已修复
└── PROGRESS.md # 本文件
```
---
## 🎯 下一步行动
### 本周 (Week 1)
- [ ] 配置 AI API Key测试完整对话流程
- [ ] 测试 Tauri 桌面端 (`pnpm tauri dev`)
- [ ] 前端连接 API 层 (Tauri Commands)
- [ ] 集成 OpenClaw SDK 到远程执行系统
### 下周 (Week 2)
- [ ] 飞书真实接入测试
- [ ] 端到端流程: 手机发消息 → 电脑执行 → 结果返回
- [ ] 场景 Skills 开发 (社媒运营/学术研究)
- [ ] sqlite-vec 向量搜索集成
---
## 🚀 启动命令
```bash
# 后端开发
cd G:\ZClaw
cp .env.example .env # 填入 API Keys
pnpm dev
# Tauri 桌面端
cd G:\ZClaw\desktop
pnpm tauri dev
```
---
**维护者**: ZCLAW 团队
**最后更新**: 2026-03-11 22:30