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