# ZClaw ZCLAW 迁移 - 新会话提示词

> **更新日期**: 2026-03-13 (Session 4)
> **状态**: Phase 1-7 基本完成

---

## 当前状态

### ✅ 已完成

1. **ZCLAW 打包架构** (Phase 1-2) ✅
   - 创建 `prepare-zclaw-runtime.mjs` 跨平台下载脚本
   - 更新 Rust `lib.rs` 支持二进制运行时
   - 配置 Tauri 打包 `resources/zclaw-runtime/`
   - 验证构建成功

2. **ZCLAW 特性 UI 组件** ✅
   - `HandsPanel.tsx` - Hands 管理界面 (含审批流程)
   - `WorkflowList.tsx` - 工作流列表
   - `SecurityStatus.tsx` - 16层安全状态
   - `TriggersPanel.tsx` - 触发器管理
   - `AuditLogsPanel.tsx` - 审计日志 (已集成到 RightPanel)

3. **状态管理更新** ✅
   - `gatewayStore.ts` 添加 ZCLAW 类型定义
   - `gateway-config.ts` 配置管理
   - `loadHands()`, `loadWorkflows()`, `loadTriggers()`, `loadSecurityStatus()` 方法
   - `approveHand()`, `cancelHand()`, `cancelWorkflow()` 方法
   - `isLoading` 状态管理
   - `connect()` 后自动加载 ZCLAW 数据

4. **Gateway Client** ✅
   - `gateway-client.ts` 已适配 ZCLAW 协议
   - WebSocket 连接到 `ws://127.0.0.1:4200/ws`
   - REST API 调用 `/api/*` 端点
   - Ed25519 设备认证 + JWT
   - Hand 审批/取消 API

5. **后端切换功能** ✅
   - `Settings/General.tsx` 添加后端类型选择器
   - 支持 ZCLAW (TypeScript) 和 ZCLAW (Rust) 切换
   - localStorage 持久化 `zclaw-backend`

6. **Tauri 后端完善** (Phase 5) ✅
   - `zclaw_process_list` - 列出 ZCLAW 进程
   - `zclaw_process_logs` - 获取进程日志
   - `zclaw_version` - 获取版本信息
   - 前端 `tauri-gateway.ts` 适配

7. **Hand 审批流程** (Phase 6.1) ✅
   - `approveHand()` / `cancelHand()` API
   - `HandsPanel.tsx` 审批 UI (批准/拒绝按钮)
   - 运行中取消执行功能

8. **测试基础设施** (Phase 7) ✅
   - `tests/fixtures/zclaw-mock-server.ts` - 完整 Mock Server
   - 支持 REST API 和 WebSocket 模拟
   - `tests/desktop/integration/zclaw-api.test.ts` - 34 个集成测试
   - 所有 63 个桌面端测试全部通过

9. **构建脚本修复** ✅
   - `tauri-build-bundled.mjs` 更新为使用 `prepare-zclaw-runtime.mjs`

### 📋 可选后续工作

| Phase | 任务 | 状态 |
|-------|------|------|
| Phase 7.3 | E2E 测试 (Playwright) | 可选 |
| - | CSP 配置 (生产环境) | 可选 |
| - | chinese-writing 插件迁移 | 待定 |

---

## 关键架构

### 打包结构

```
ZClaw-Desktop-Setup.exe
├── desktop.exe           # Tauri 应用
└── resources/
    └── zclaw-runtime/
        ├── zclaw.exe  # 57MB ZCLAW 二进制
        ├── zclaw.cmd  # Windows 启动脚本
        ├── zclaw.sh   # Unix 启动脚本
        └── runtime-manifest.json
```

### 运行时解析优先级

1. `ZCLAW_BIN` 环境变量
2. 打包的 `zclaw-runtime/` 目录
3. 系统 PATH (`zclaw`)

### 端点和协议

| 项目 | ZCLAW (旧) | ZCLAW (新) |
|------|---------------|---------------|
| WebSocket | `ws://127.0.0.1:18789` | `ws://127.0.0.1:4200/ws` |
| REST API | 无 | `http://127.0.0.1:4200/api` |
| 配置格式 | JSON | TOML |
| 配置目录 | `~/.zclaw/` | `~/.zclaw/` |

---

## 测试

### 运行测试

```bash
# 所有桌面端测试 (63 个)
pnpm vitest run tests/desktop/

# 仅集成测试 (34 个)
pnpm vitest run tests/desktop/integration/

# 单元测试
pnpm vitest run tests/desktop/chatStore.test.ts
pnpm vitest run tests/desktop/gatewayStore.test.ts
```

### Mock Server

Mock Server (`tests/fixtures/zclaw-mock-server.ts`) 提供：

- **REST API**: 所有 `/api/*` 端点
- **WebSocket**: `/ws` 路径握手
- **可配置数据**: Hands, Workflows, Triggers, Agents, Security Layers
- **审计日志**: 可添加自定义日志条目

---

## 下一步工作

### 优先级 1: 真实 ZCLAW 集成测试

```bash
# 1. 启动 ZCLAW
cd desktop/src-tauri/resources/zclaw-runtime
./zclaw.exe gateway start

# 2. 运行 Tauri 开发模式
pnpm tauri:dev

# 3. 验证连接
# - WebSocket 连接到 4200 端口
# - 消息发送和接收
# - Hands/Workflow 功能
```

### 优先级 2: 插件迁移 (chinese-writing)

将 `plugins/zclaw-chinese-models` 中的模型配置迁移到 ZCLAW TOML 格式。

参考: `config/chinese-providers.toml`

---

## 构建命令

```bash
# 开发
pnpm tauri:dev

# 生产构建 (自动下载 ZCLAW)
pnpm tauri:build:bundled

# 手动准备运行时
pnpm prepare:zclaw-runtime
```

---

## 参考文档

- 迁移计划: `plans/immutable-imagining-naur.md`
- ZCLAW 技术参考: `docs/zclaw-technical-reference.md`
- 运行时 README: `desktop/src-tauri/resources/zclaw-runtime/README.md`
- ZCLAW GitHub: https://github.com/RightNow-AI/zclaw

---

## 新会话提示词模板

```
我正在开发 ZClaw Desktop，一个从 ZCLAW 迁移到 ZCLAW 的 AI Agent 桌面客户端。

当前状态:
- Phase 1-7 基本完成
- 63 个测试全部通过
- Mock Server 集成测试可用

请阅读 docs/new-session-prompt-zclaw-migration.md 了解详细上下文，然后继续以下工作:
[具体任务]
```