zclaw_openfang/docs/archive/new-session-prompt-openfang-migration.md

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/

---

测试

运行测试

# 所有桌面端测试 (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 集成测试

# 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

---

构建命令

# 开发
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 了解详细上下文，然后继续以下工作:
[具体任务]