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](desktop/src/lib/gateway-client.ts)

**修改内容**:
```typescript
// 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](desktop/src/store/gatewayStore.ts)

**修改内容**:
```typescript
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](desktop/src-tauri/src/lib.rs)

**修改内容**:
```rust
// 新增 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 回滚策略

```typescript
// 环境变量切换
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](desktop/src/lib/gateway-client.ts) | 重构 | 抽取接口，创建 ZCLAW 实现 |
| [gatewayStore.ts](desktop/src/store/gatewayStore.ts) | 修改 | 添加后端切换逻辑 |
| [chatStore.ts](desktop/src/store/chatStore.ts) | 修改 | 适配新事件格式 |
| [lib.rs](desktop/src-tauri/src/lib.rs) | 扩展 | 添加 ZCLAW 管理命令 |
| [zclaw-ui/index.ts](plugins/zclaw-ui/index.ts) | 迁移 | 转换为 REST API |
| [zclaw-chinese-models/index.ts](plugins/zclaw-chinese-models/index.ts) | 迁移 | 转换为 TOML 配置 |
| [zclaw-feishu/index.ts](plugins/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*