# ZCLAW Desktop 新会话提示词

## 当前状态

### 已完成的工作 (2026-03-14)

1. **OpenFang 连接适配** ✅
   - ZCLAW Desktop 已成功连接 OpenFang (端口 50051)
   - 对话功能测试通过，AI 响应正常

2. **WebSocket 流式聊天** ✅ (新完成)
   - 实现了 `chatStream()` 方法支持流式响应
   - 添加了 `onDelta`, `onTool`, `onHand`, `onComplete`, `onError` 回调
   - Vite 代理已启用 WebSocket 支持 (`ws: true`)
   - chatStore 优先使用流式 API，REST API 作为 fallback

3. **动态 Agent 选择** ✅ (新完成)
   - 添加了 `setDefaultAgentId()` 和 `getDefaultAgentId()` 方法
   - loadClones 时自动设置第一个可用 Agent 为默认

### 关键修改

| 文件 | 修改内容 |
|------|----------|
| `gateway-client.ts` | 添加 `chatStream()`, `cancelStream()`, `setDefaultAgentId()` |
| `chatStore.ts` | sendMessage 优先使用流式 API |
| `gatewayStore.ts` | loadClones 自动设置默认 Agent |
| `vite.config.ts` | 启用 WebSocket 代理 |

### OpenFang vs OpenClaw 协议差异

| 方面 | OpenClaw | OpenFang |
|------|----------|----------|
| 端口 | 18789 | **50051** |
| 聊天 API | `/api/chat` | `/api/agents/{id}/message` |
| WebSocket | `/` (单一连接) | `/api/agents/{id}/ws` (流式) |
| 连接方式 | WebSocket 握手 | REST API 健康检查 |

### 运行环境

- **OpenFang**: `~/.openfang/` (config.toml, .env)
- **OpenClaw**: `~/.openclaw/` (openclaw.json, devices/)
- **ZCLAW 前端**: `http://localhost:1420` (Vite)
- **默认 Agent**: 动态获取第一个可用 Agent

### localStorage 配置

```javascript
localStorage.setItem('zclaw-backend', 'openfang');
localStorage.setItem('zclaw_gateway_url', 'ws://127.0.0.1:50051/ws');
```

---

## 待完成工作

### 优先级 P1 - 功能完善

1. **Hands 面板** - UI 已存在，需要验证 API 连接
2. **Workflow 管理** - UI 已存在，需要验证 API 连接
3. **审计日志** - Merkle 哈希链审计查看

### 优先级 P2 - 优化

4. **后端切换优化** - 代理配置应动态切换 (OpenClaw: 18789, OpenFang: 50051)
5. **错误处理** - 更友好的错误提示
6. **连接状态显示** - 显示 OpenFang 版本号

---

## 快速启动命令

```bash
# 启动 OpenFang
cd "desktop/src-tauri/resources/openfang-runtime" && ./openfang.exe start

# 启动 Vite 开发服务器
cd desktop && pnpm dev

# 检查 OpenFang 状态
./openfang.exe status

# 测试 API
curl http://127.0.0.1:50051/api/health
curl http://127.0.0.1:50051/api/agents
```

---

## 关键文件路径

| 文件 | 用途 |
|------|------|
| `desktop/src/lib/gateway-client.ts` | Gateway 通信客户端 (WebSocket + REST) |
| `desktop/src/store/gatewayStore.ts` | Gateway 状态管理 |
| `desktop/src/store/chatStore.ts` | 聊天状态管理 |
| `desktop/src/components/Settings/General.tsx` | 后端切换设置 |
| `desktop/vite.config.ts` | Vite 代理配置 |
| `docs/openfang-technical-reference.md` | OpenFang 技术文档 |

---

## 新会话起始提示

```
请继续 ZCLAW Desktop 的开发工作。

当前状态：
- OpenFang REST API 聊天已可用 ✅
- WebSocket 流式聊天已实现 ✅
- 动态 Agent 选择已实现 ✅

首要任务建议：
1. 验证 Hands/Workflow 面板 API 连接
2. 实现审计日志面板
3. 优化后端切换逻辑
```