264 lines
9.4 KiB
Markdown
264 lines
9.4 KiB
Markdown
# ZCLAW v2 开发 - 新会话提示词
|
||
|
||
## 项目状态概览
|
||
|
||
ZCLAW v2 是基于 OpenClaw 的定制化 AI Agent 平台（类似 AutoClaw/QClaw），使用 Tauri 2.0 桌面 + OpenClaw Gateway 架构。
|
||
|
||
**当前进度**: Phase 1-3.5 已完成 ✅
|
||
**下一步**: Phase 4 - OpenClaw 真实集成测试（QQ官方插件 + 飞书）
|
||
|
||
---
|
||
|
||
## Phase 1-3 已完成工作
|
||
|
||
### ✅ Phase 1: 后端 Gateway 层 + 插件 + Skills
|
||
- **src/gateway/** — GatewayManager (子进程管理), GatewayWsClient (WebSocket Protocol v3)
|
||
- **plugins/zclaw-chinese-models/** — 智谱GLM/通义千问/Kimi/MiniMax Provider 插件
|
||
- **plugins/zclaw-feishu/** — 飞书 Channel 插件 (OAuth token 管理 + 消息发送)
|
||
- **plugins/zclaw-ui/** — UI 扩展 RPC (分身CRUD/统计/配置/工作区)
|
||
- **skills/** — chinese-writing + feishu-docs (SKILL.md 格式)
|
||
- **config/** — openclaw.default.json + SOUL/AGENTS/IDENTITY/USER.md
|
||
- **scripts/setup.ts** — 首次设置脚本 (检测OpenClaw → 复制配置 → 注册插件)
|
||
|
||
### ✅ Phase 2: 前端 Settings 页面体系
|
||
- **desktop/src/components/Settings/** — 10个设置页面对标 AutoClaw
|
||
- SettingsLayout (左侧导航 + 右侧内容)
|
||
- General, UsageStats, ModelsAPI, MCPServices, Skills, IMChannels, Workspace, Privacy, About
|
||
- **App.tsx** — main/settings 视图切换
|
||
- **构建修复** — Tailwind v4, BOM 清除, TypeScript 0 errors
|
||
|
||
### ✅ Phase 3: 聊天对接 + 分身管理
|
||
- **desktop/src/store/chatStore.ts** — Gateway WS 集成 (sendMessage → agent RPC, initStreamListener → delta/tool/lifecycle)
|
||
- **desktop/src/components/ChatArea.tsx** — 流式输出 + 工具调用展示 + 模型选择器 + 连接状态
|
||
- **desktop/src/components/CloneManager.tsx** — 分身 CRUD (创建表单 + 列表 + 删除)
|
||
- **desktop/src/components/Sidebar.tsx** — 3标签 (分身/IM频道/定时任务) + CloneManager 集成
|
||
|
||
### ✅ Phase 3.5: 前端质量提升
|
||
- **App.tsx** — Gateway 自动连接 (启动时 silent connect)
|
||
- **RightPanel.tsx** — 重写为实时数据面板 (连接状态/会话统计/分身/用量/插件/系统信息)
|
||
- **ChatArea.tsx** — 多行 textarea 输入 + Markdown 渲染 (代码块/粗体/斜体/链接) + 新对话按钮
|
||
- **chatStore.ts** — 对话会话管理 + Zustand persist (localStorage 持久化对话历史 + currentModel)
|
||
- **ConversationList.tsx** (新) — 对话历史列表 + 标题自动提取 + 相对时间
|
||
- **Sidebar.tsx** — 四标签 (对话/分身/频道/任务), 全部使用真实组件
|
||
- **ChannelList.tsx** (新) — IM 频道列表 (飞书/QQ 状态探测 + 配置入口)
|
||
- **TaskList.tsx** (新) — Heartbeat 定时任务列表 (状态图标/cron 表达式/执行时间)
|
||
- **gatewayStore.ts** — 新增 channels/scheduledTasks 状态 + loadChannels/loadScheduledTasks
|
||
- **gateway-client.ts** — 新增 listChannels() + getFeishuStatus() + listScheduledTasks()
|
||
- **Settings/General.tsx** — 接入真实 Gateway 连接数据 + 连接/断开按钮
|
||
- **Settings/ModelsAPI.tsx** — 接入 chatStore 模型切换 + Gateway 连接状态
|
||
|
||
**编译状态**: TypeScript 0 errors, Vite build ✅ (1766 modules, 268KB JS + 26KB CSS)
|
||
|
||
---
|
||
|
||
## Phase 4: OpenClaw 集成测试 (下一步工作)
|
||
|
||
### 重要提示：避免封号
|
||
**前期只对接 QQ (官方插件) 和 飞书**，微信暂缓。
|
||
|
||
### 任务清单
|
||
|
||
#### 1. 安装 OpenClaw
|
||
```bash
|
||
# Windows
|
||
iwr -useb https://openclaw.ai/install.ps1 | iex
|
||
|
||
# 验证安装
|
||
openclaw --version
|
||
openclaw doctor
|
||
```
|
||
|
||
#### 2. 配置 QQ 机器人 (使用官方插件)
|
||
```bash
|
||
# 安装 OpenClaw 开源社区 QQBot 插件
|
||
openclaw plugins install @tencent-connect/openclaw-qqbot@latest
|
||
|
||
# 配置绑定 QQ 机器人
|
||
openclaw channels add --channel qqbot --token "1903376513:Z5UkttjPxLZbVFxW"
|
||
|
||
# 重启 Gateway
|
||
openclaw gateway restart
|
||
```
|
||
|
||
#### 3. 配置飞书 Channel
|
||
```bash
|
||
# 运行 ZCLAW 设置脚本
|
||
cd g:\ZClaw
|
||
pnpm setup
|
||
|
||
# 手动配置飞书插件 (如果 setup 脚本未自动注册)
|
||
openclaw plugins register ./plugins/zclaw-feishu
|
||
|
||
# 编辑 ~/.openclaw/openclaw.json 添加飞书配置
|
||
# channels.feishu.appId, appSecret, verificationToken, encryptKey
|
||
```
|
||
|
||
#### 4. 注册 ZCLAW 自定义插件
|
||
```bash
|
||
cd g:\ZClaw
|
||
|
||
# 注册中文模型 Provider
|
||
openclaw plugins register ./plugins/zclaw-chinese-models
|
||
|
||
# 注册 UI 扩展 RPC
|
||
openclaw plugins register ./plugins/zclaw-ui
|
||
|
||
# 重启 Gateway
|
||
openclaw gateway restart
|
||
```
|
||
|
||
#### 5. 测试 Gateway 连接
|
||
```bash
|
||
# 启动 Gateway (如果未运行)
|
||
openclaw gateway
|
||
|
||
# 在另一个终端启动 ZCLAW 前端
|
||
cd g:\ZClaw\desktop
|
||
pnpm dev
|
||
|
||
# 访问 http://localhost:1420
|
||
# 点击右下角齿轮 → 设置 → 通用 → 查看 Gateway 连接状态
|
||
```
|
||
|
||
#### 6. 测试中文模型调用
|
||
- 在聊天区域发送消息
|
||
- 点击模型选择器切换到 glm-5 / qwen3.5-plus / kimi-k2.5 / minimax-m2.5
|
||
- 观察流式输出效果
|
||
- 检查工具调用是否正常显示
|
||
|
||
#### 7. 测试飞书消息收发
|
||
- 在飞书中 @机器人 发送消息
|
||
- 观察 Gateway 日志和前端消息列表
|
||
- 测试从前端发送消息到飞书
|
||
|
||
#### 8. 测试 QQ 消息收发
|
||
- 在 QQ 中 @机器人 发送消息
|
||
- 观察 Gateway 日志
|
||
- 测试双向消息流
|
||
|
||
---
|
||
|
||
## 关键文件路径
|
||
|
||
### 配置文件
|
||
- `g:\ZClaw\config\openclaw.default.json` — OpenClaw 默认配置模板
|
||
- `~\.openclaw\openclaw.json` — OpenClaw 用户配置 (运行时生成)
|
||
- `g:\ZClaw\config\SOUL.md` — ZCLAW 人格定义
|
||
|
||
### 插件目录
|
||
- `g:\ZClaw\plugins\zclaw-chinese-models\` — 中文模型 Provider
|
||
- `g:\ZClaw\plugins\zclaw-feishu\` — 飞书 Channel
|
||
- `g:\ZClaw\plugins\zclaw-ui\` — UI 扩展 RPC
|
||
|
||
### 前端代码
|
||
- `g:\ZClaw\desktop\src\store\gatewayStore.ts` — Gateway 状态管理
|
||
- `g:\ZClaw\desktop\src\store\chatStore.ts` — 聊天状态管理
|
||
- `g:\ZClaw\desktop\src\lib\gateway-client.ts` — Gateway WebSocket 客户端
|
||
|
||
### 后端代码
|
||
- `g:\ZClaw\src\gateway\manager.ts` — Gateway 子进程管理
|
||
- `g:\ZClaw\src\gateway\ws-client.ts` — Node.js WebSocket 客户端
|
||
|
||
---
|
||
|
||
## 常见问题排查
|
||
|
||
### Gateway 连接失败
|
||
1. 检查 Gateway 是否运行: `openclaw status`
|
||
2. 检查端口占用: `netstat -ano | findstr 18789`
|
||
3. 查看 Gateway 日志: `openclaw gateway` (前台运行查看输出)
|
||
4. 检查防火墙设置
|
||
|
||
### 插件未加载
|
||
1. 验证插件注册: `openclaw plugins list`
|
||
2. 检查插件 manifest: `g:\ZClaw\plugins\*/plugin.json`
|
||
3. 查看 Gateway 启动日志中的插件加载信息
|
||
4. 确认 `~\.openclaw\openclaw.json` 中 `plugins.load.paths` 包含插件路径
|
||
|
||
### 飞书消息收发失败
|
||
1. 检查 `openclaw.json` 中飞书配置 (appId, appSecret, verificationToken)
|
||
2. 验证 OAuth token 是否有效: 查看 Gateway 日志中的 token 刷新记录
|
||
3. 检查飞书机器人权限配置
|
||
4. 确认回调 URL 配置正确
|
||
|
||
### QQ 消息收发失败
|
||
1. 验证 QQBot 插件安装: `openclaw plugins list | findstr qqbot`
|
||
2. 检查 token 格式: `"botAppId:token"`
|
||
3. 查看 Gateway 日志中的 QQ 连接状态
|
||
4. 确认 QQ 机器人已启用并在线
|
||
|
||
---
|
||
|
||
## 开发命令速查
|
||
|
||
```bash
|
||
# 后端 (Gateway 层)
|
||
cd g:\ZClaw
|
||
pnpm install
|
||
pnpm setup # 运行设置脚本
|
||
pnpm build # 编译 TypeScript
|
||
npx tsc --noEmit # 类型检查
|
||
|
||
# 前端 (Tauri Desktop)
|
||
cd g:\ZClaw\desktop
|
||
pnpm install
|
||
pnpm dev # 启动 Vite dev server (http://localhost:1420)
|
||
pnpm build # 构建生产版本
|
||
npx tsc --noEmit # 类型检查
|
||
|
||
# OpenClaw 命令
|
||
openclaw gateway # 启动 Gateway (前台)
|
||
openclaw gateway restart # 重启 Gateway
|
||
openclaw status # 查看状态
|
||
openclaw doctor # 诊断工具
|
||
openclaw plugins list # 列出已安装插件
|
||
openclaw plugins install <pkg> # 安装插件
|
||
openclaw plugins register <path> # 注册本地插件
|
||
openclaw channels add --channel <type> --token <token> # 添加 IM 频道
|
||
openclaw configure # 交互式配置
|
||
```
|
||
|
||
---
|
||
|
||
## 参考文档
|
||
|
||
- **架构设计**: `g:\ZClaw\docs\architecture-v2.md`
|
||
- **偏离分析**: `g:\ZClaw\docs\deviation-analysis.md`
|
||
- **进度报告**: `g:\ZClaw\PROGRESS.md`
|
||
- **AutoClaw 界面参考**: `g:\ZClaw\docs\autoclaw界面\` (13张截图)
|
||
|
||
---
|
||
|
||
## 预期成果
|
||
|
||
完成 Phase 4 后，应达到以下状态：
|
||
|
||
1. ✅ OpenClaw Gateway 正常运行并连接到前端
|
||
2. ✅ QQ 机器人可以收发消息 (使用官方 @tencent-connect/openclaw-qqbot 插件)
|
||
3. ✅ 飞书机器人可以收发消息 (使用自定义 zclaw-feishu 插件)
|
||
4. ✅ 中文模型 (GLM/Qwen/Kimi/MiniMax) 可以正常调用
|
||
5. ✅ 前端聊天区域显示流式输出 + 工具调用
|
||
6. ✅ 分身管理功能正常 (创建/列表/删除)
|
||
7. ✅ Settings 页面所有配置项可用
|
||
|
||
---
|
||
|
||
## 注意事项
|
||
|
||
1. **避免封号**: 前期只对接 QQ (官方插件) 和飞书，微信暂缓
|
||
2. **QQ 使用官方插件**: `@tencent-connect/openclaw-qqbot@latest`，不要自己实现
|
||
3. **飞书使用自定义插件**: `plugins/zclaw-feishu/` 已实现 OAuth + 消息发送
|
||
4. **API Key 安全**: 不要在代码中硬编码 API Key，使用 `openclaw configure` 或环境变量
|
||
5. **Gateway 日志**: 前台运行 `openclaw gateway` 可以实时查看日志，便于调试
|
||
6. **插件热重载**: 修改插件代码后需要 `openclaw gateway restart`
|
||
|
||
---
|
||
|
||
## 后续 Phase 5 规划
|
||
|
||
- [ ] Tauri Rust sidecar (在 Tauri 中管理 Gateway 子进程)
|
||
- [ ] 更多 Skills 开发 (代码生成、文档写作、数据分析等)
|
||
- [ ] 微信 Channel Plugin (待 OpenClaw 官方支持或社区插件成熟后)
|
||
- [ ] 打包发布 (Windows/macOS/Linux)
|
||
- [ ] 性能优化 + 错误处理增强
|