chore: cleanup phase 5, remove external runtime dependencies

docs/design/openfang-integration-strategy.md

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