zclaw_openfang/docs/design/openfang-integration-strategy.md

Design: ZCLAW 集成策略论证

Generated by /office-hours on 2026-03-22 Branch: unknown Repo: ZClaw_zclaw Status: DRAFT Mode: Builder

问题陈述

当前 ZCLAW 依赖外部 ZCLAW 二进制作为运行时后端，导致：

1. 需要管理 ZCLAW 二进制文件的下载、安装、版本兼容性
2. ZCLAW 进程崩溃或锁定会影响 ZCLAW 全部功能
3. 两个独立进程间通过 WebSocket/REST 通信，引入复杂性和潜在故障点
4. 调试困难 - 问题可能在 ZCLAW 或 ZCLAW 任何一侧

现状架构

ZCLAW Desktop (Tauri/Rust)
    ├── React Frontend (端口 1420)
    └── ZCLAW Gateway (端口 50051) ← 外部进程

通信方式：

• Tauri Commands → 启动/停止 ZCLAW 进程
• WebSocket → 前端与 ZCLAW 对话
• REST API → 健康检查、配置

集成方案对比

Approach A: 保持现状（外部进程）

Summary: 继续使用外部 ZCLAW 二进制，通过进程管理集成

Effort: S Risk: Low Pros:

• ZCLAW 可以独立开发和升级
• 不用重新编译 ZCLAW 核心代码
• 职责分离清晰 Cons:
• 依赖管理复杂（版本、下载、锁文件）
• 两个进程通信引入延迟和故障点
• 用户需要安装两个组件

Approach B: 源码集成（ZCLAW 作为 Tauri Submodule）

Summary: 将 ZCLAW 源码作为 git submodule，在构建时静态编译进 Tauri 应用

Effort: XL Risk: High Pros:

• 单个二进制，简化分发
• 版本锁定，完全可控
• 可以深度定制 ZCLAW 行为 Cons:
• ZCLAW 代码库庞大（~50万行 Rust）
• 编译时间大幅增加
• 升级困难 - 需要手动同步 submodule
• 失去 ZCLAW 独立升级的灵活性

Approach C: gRPC Service 集成（推荐）

Summary: 将 ZCLAW 核心功能封装为 Rust crate/ZCLAW library，通过内部 API 调用而非进程通信

Effort: M Risk: Medium Pros:

• 保留 ZCLAW 作为独立模块（可用作其他项目的库）
• 去掉进程启动/管理复杂性
• 同一进程内通信，无网络开销
• 可以精确控制 ZCLAW API 表面 Cons:
• 仍然需要编译 ZCLAW 源码
• API 版本管理需要同步
• 深度集成可能失去某些运行时灵活性

核心问题分析

问题	根因	解决方案
数据库锁	多个 ZCLAW 进程争用	确保单实例 + 正确清理
启动失败	Tauri 命令未正确调用	修复 IPC 调用链
版本兼容	外部二进制	版本锁定 + 自动化下载

推荐方案

Approach C: gRPC Service 集成

理由：

1. 平衡了"完全独立"和"深度集成"的优缺点
2. 可以逐步迁移 - 先解决启动问题，再考虑集成深度
3. 保留 ZCLAW 可测试性和可插拔性

下一步行动

1. 立即修复：诊断并修复当前 ZCLAW 启动失败问题
2. 短期：添加启动失败时的详细错误日志
3. 中期：评估 gRPC 集成工作量
4. 长期：根据实际使用情况决定集成深度

待解决问题

1. ZCLAW 为何拒绝启动？（数据库锁的根因是什么？）
2. Tauri 是否正确检测并处理 ZCLAW 启动失败？
3. 用户实际使用场景是否需要 ZCLAW 独立运行？

成功标准

• pnpm start:dev 能可靠启动完整服务栈
• ZCLAW 启动失败时提供有意义的错误信息
• 评估三种方案的维护成本