18 KiB
18 KiB
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 进行了完整的架构重构。
✅ 新增: 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 发送
agentRPC, 创建流式占位消息 - 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 渲染 — 轻量级渲染器：代码块 (带语言标签), 内联代码, 粗体, 斜体, 链接
- 新对话按钮 — 头部右侧显示 "新对话" 按钮 (SquarePen 图标)
- placeholder 更新: "发送给 ZCLAW（Shift+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中间件集成 localStoragepartialize仅保存 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.tsxclassName 模板字面量 - 修复
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 向量搜索集成
🚀 启动命令
# 后端开发
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