zclaw_openfang/docs/plans/immutable-imagining-naur.md

ZClaw: 从 ZCLAW 迁移到 ZCLAW 可行性方案

规划日期: 2026-03-13 目标: 制定从 ZCLAW 到 ZCLAW 的渐进式迁移策略，实现平稳过渡

---

一、背景与动机

1.1 当前架构 (ZCLAW)

┌─────────────────────────────────────────────────────────────────┐
│                    ZClaw Desktop (当前)                         │
├─────────────────────────────────────────────────────────────────┤
│   React 19 UI → Zustand Store → GatewayClient → ZCLAW       │
│   技术栈: Tauri 2.0 + TypeScript + Node.js Gateway              │
│   内存: >1GB | 启动: 2-5s | 安装: 500MB                          │
└─────────────────────────────────────────────────────────────────┘

1.2 目标架构 (ZCLAW)

┌─────────────────────────────────────────────────────────────────┐
│                    ZClaw Desktop (ZCLAW)                     │
├─────────────────────────────────────────────────────────────────┤
│   React 19 UI → Zustand Store → ZCLAWClient → ZCLAW      │
│   技术栈: Tauri 2.0 + TypeScript + Rust Gateway                 │
│   内存: ~40MB | 启动: 180ms | 安装: 32MB                         │
└─────────────────────────────────────────────────────────────────┘

1.3 迁移动机

维度	ZCLAW	ZCLAW	提升
启动速度	5.98s	180ms	33x 更快
内存占用	394MB	40MB	90% 更少
安装大小	500MB	32MB	94% 更小
安全防护	3 层	16 层	企业级安全
通道支持	20+	40+	覆盖更广
自主能力	无	7 Hands	从被动到主动

---

二、核心差异分析

2.1 协议差异

方面	ZCLAW	ZCLAW
WebSocket URL	ws://127.0.0.1:18789	ws://127.0.0.1:4200/ws
协议格式	自定义 JSON 帧	标准 JSON + gRPC
认证方式	Ed25519 设备签名	Ed25519 + JWT

2.2 配置差异

方面	ZCLAW	ZCLAW
配置目录	~/.zclaw/	~/.zclaw/
配置格式	YAML/JSON	TOML
插件系统	TypeScript (index.ts)	SKILL.md + WASM

2.3 API 差异

功能	ZCLAW RPC	ZCLAW API
发送消息	agent	chat / /api/chat
列出 Agent	zclaw.clones.list	GET /api/agents
获取配置	config.get	GET /api/config
触发技能	插件系统	skill_trigger
Hand 自动化	❌ 无	hand_trigger
Workflow	❌ 基础	workflow_execute

---

三、迁移策略：渐进式双轨

3.1 策略原则

1. 双版本并行: 保持 ZCLAW 可用，同时开发 ZCLAW
2. 适配层抽象: 通过接口隔离后端差异
3. 功能对等优先: 先保证核心功能，再添加新特性
4. 灰度发布: Beta 测试验证后全面切换

3.2 迁移阶段

Phase 1 (2周): 基础设施 ──────────────────────────────────────────►
Phase 2 (2周): 客户端实现 ────────────────────────────────────────►
Phase 3 (2周): 状态迁移 ──────────────────────────────────────────►
Phase 4 (3周): 插件迁移 ──────────────────────────────────────────►
Phase 5 (2周): Tauri 后端 ────────────────────────────────────────►
Phase 6 (3周): UI 增强 ───────────────────────────────────────────►
Phase 7 (2周): 测试验证 ──────────────────────────────────────────►
────────────────────────────────────────────────────────────────────
总工期: 16 周 (约 4 个月)

---

四、详细实施计划

Phase 1: 基础设施 (Week 1-2)

目标: 建立迁移基础架构

关键任务:

1. 创建 GatewayBackend 接口抽象
2. 创建 ZCLAWClient 骨架
3. 配置双后端切换机制
4. 设置 ZCLAW 开发环境

交付物:

• desktop/src/lib/types/gateway-backend.ts - 接口定义
• desktop/src/lib/zclaw-client.ts - 客户端骨架
• desktop/src/lib/backend-factory.ts - 后端工厂

Phase 2: 客户端实现 (Week 3-4)

目标: 完整实现 ZCLAW 客户端

关键文件: gateway-client.ts

修改内容:

// 1. 抽取接口
interface GatewayBackend {
  connect(): Promise<void>;
  disconnect(): void;
  chat(message: string, opts?: ChatOptions): Promise<{runId: string}>;
  onStream(callback: StreamCallback): () => void;
  // ... 其他方法
}

// 2. ZCLAW 实现 (现有代码重构)
class ZCLAWBackend implements GatewayBackend { ... }

// 3. ZCLAW 实现 (新建)
class ZCLAWBackend implements GatewayBackend {
  private ws: WebSocket;
  private url = 'ws://127.0.0.1:4200/ws';

  async connect(): Promise<void> {
    // ZCLAW 认证协议
  }

  async chat(message: string, opts?: ChatOptions): Promise<{runId: string}> {
    // ZCLAW chat 格式
  }
}

Phase 3: 状态迁移 (Week 5-6)

目标: 更新状态管理层支持双后端

关键文件: gatewayStore.ts

修改内容:

interface GatewayStore {
  // 新增
  backendType: 'zclaw' | 'zclaw';
  switchBackend(type: 'zclaw' | 'zclaw'): void;

  // 修改 connect 方法
  connect: async (url?, token?) => {
    const backend = getBackendFactory().create(get().backendType);
    await backend.connect(url, token);
  }
}

Phase 4: 插件迁移 (Week 7-9)

目标: 迁移现有插件到 ZCLAW 格式

插件	当前格式	目标格式	复杂度
zclaw-chinese-models	TypeScript	TOML 配置	中
zclaw-feishu	TypeScript	Rust/WASM	高
zclaw-ui	TypeScript RPC	REST API	高

迁移方案:

plugins/
├── zclaw-chinese-models/
│   ├── zclaw.plugin.json  → 删除
│   └── index.ts              → 转换为 providers.toml
│
├── zclaw-feishu/
│   └── index.ts              → 迁移到 ZCLAW channels
│
└── zclaw-ui/
    └── index.ts              → 拆分为 REST 端点

Phase 5: Tauri 后端 (Week 10-11)

目标: 更新 Rust 后端支持 ZCLAW

关键文件: lib.rs

修改内容:

// 新增 ZCLAW 命令
#[tauri::command]
async fn zclaw_status() -> Result<ZCLAWStatus, String> { ... }

#[tauri::command]
async fn zclaw_start() -> Result<(), String> { ... }

#[tauri::command]
async fn zclaw_stop() -> Result<(), String> { ... }

// 新增配置迁移命令
#[tauri::command]
async fn migrate_to_zclaw() -> Result<MigrationResult, String> { ... }

Phase 6: UI 增强 (Week 12-14)

目标: 添加 ZCLAW 特有的 UI 功能

新增组件:

1. HandsPanel.tsx - Hands 管理界面
2. WorkflowEditor.tsx - 工作流编辑器
3. TriggerManager.tsx - 触发器管理
4. AuditLogs.tsx - 审计日志查看

修改组件:

1. SettingsLayout.tsx - 添加后端切换选项
2. General.tsx - 添加 ZCLAW 配置项

Phase 7: 测试验证 (Week 15-16)

目标: 全面测试和验证

测试范围:

• 单元测试: 新客户端、适配层
• 集成测试: 端到端消息流
• 性能测试: 启动时间、内存占用
• 迁移测试: 配置迁移正确性

---

五、风险评估与缓解

5.1 技术风险

风险	级别	缓解措施
协议不兼容	高	创建适配层，保持双后端
插件迁移复杂	高	分阶段迁移，保持 TypeScript 桥接
ZCLAW 不成熟	中	持续关注上游，建立社区联系
配置格式差异	中	构建自动迁移工具

5.2 运营风险

风险	级别	缓解措施
用户困惑	中	清晰文档，渐进发布
数据丢失	高	自动备份，非破坏性迁移
支持负担	中	FAQ，故障排除指南

5.3 回滚策略

// 环境变量切换
const USE_OPENFANG = process.env.ZCLAW_USE_OPENFANG === 'true';

// localStorage 切换
const backendType = localStorage.getItem('zclaw-backend') || 'zclaw';

// 一键回滚
function rollbackToZCLAW() {
  localStorage.setItem('zclaw-backend', 'zclaw');
  window.location.reload();
}

---

六、验证方案

6.1 功能验证清单

核心功能:

• WebSocket 连接和认证
• 消息发送和流式接收
• Agent/Clone CRUD 操作
• 频道管理 (飞书)
• 技能加载和执行
• 使用统计
• 配置管理

ZCLAW 新特性:

• Hand 触发 (Clip, Lead, Researcher 等)
• Workflow 执行
• 16 层安全验证
• 审计日志访问

6.2 性能基准

指标	ZCLAW 基线	ZCLAW 目标
冷启动	5.98s	< 500ms
空闲内存	394MB	< 100MB
聊天延迟	100ms	< 50ms
安装大小	500MB	< 100MB

---

七、关键文件清单

文件	修改类型	说明
gateway-client.ts	重构	抽取接口，创建 ZCLAW 实现
gatewayStore.ts	修改	添加后端切换逻辑
chatStore.ts	修改	适配新事件格式
lib.rs	扩展	添加 ZCLAW 管理命令
zclaw-ui/index.ts	迁移	转换为 REST API
zclaw-chinese-models/index.ts	迁移	转换为 TOML 配置
zclaw-feishu/index.ts	迁移	使用 ZCLAW channel

---

八、时间线总结

阶段	周期	开始	结束	关键交付物
Phase 1	2周	Week 1	Week 2	ZCLAWClient 骨架
Phase 2	2周	Week 3	Week 4	完整客户端 + 流式处理
Phase 3	2周	Week 5	Week 6	更新后的 stores
Phase 4	3周	Week 7	Week 9	迁移后的插件
Phase 5	2周	Week 10	Week 11	Rust ZCLAW 支持
Phase 6	3周	Week 12	Week 14	Hands/Workflow UI
Phase 7	2周	Week 15	Week 16	测试套件，验证报告

总工期: 16 周 (约 4 个月)

---

九、结论与建议

9.1 核心价值

┌─────────────────────────────────────────────────────────────────┐
│                                                                 │
│   🚀 性能：33x 启动速度 + 90% 内存节省                          │
│                                                                 │
│   🔒 安全：16 层纵深防御 + 金融级合规                           │
│                                                                 │
│   🤖 智能：Hands 自主系统 + Workflow 引擎                       │
│                                                                 │
│   📈 商业：企业市场拓展 + 定价提升空间                          │
│                                                                 │
│   ⚠️  成本：16 周 (4个月) 迁移周期                              │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

9.2 决策建议

目标	建议
追求企业市场	✅ 强烈建议迁移
追求差异化竞争	✅ 建议迁移
目标是内容创作者/销售	✅ 强烈建议迁移
资源有限	⚠️ 渐进评估
追求快速迭代	⚠️ 保持 ZCLAW，关注 ZCLAW

9.3 下一步行动

1. 立即: 确认迁移决策，分配资源
2. Week 1: 创建 GatewayBackend 接口
3. Week 2: 搭建 ZCLAW 开发环境
4. Week 3-4: 实现 ZCLAWClient

---

规划日期: 2026-03-13 版本: v1.0