# 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)
- [ ] 性能优化 + 错误处理增强