# 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 启动失败时提供有意义的错误信息
- [ ] 评估三种方案的维护成本