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

Design: OpenFang 集成策略论证

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

问题陈述

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

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

现状架构

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

通信方式：

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

集成方案对比

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

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

Effort: S Risk: Low Pros:

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

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

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

Effort: XL Risk: High Pros:

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

Approach C: gRPC Service 集成（推荐）

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

Effort: M Risk: Medium Pros:

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

核心问题分析

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

推荐方案

Approach C: gRPC Service 集成

理由：

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

下一步行动

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

待解决问题

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

成功标准

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