0d4fa96b82
Some checks failed
CI / Lint & TypeCheck (push) Has been cancelled
CI / Unit Tests (push) Has been cancelled
CI / Build Frontend (push) Has been cancelled
CI / Rust Check (push) Has been cancelled
CI / Security Scan (push) Has been cancelled
CI / E2E Tests (push) Has been cancelled
重构所有代码和文档中的项目名称，将OpenFang统一更新为ZCLAW。包括： - 配置文件中的项目名称 - 代码注释和文档引用 - 环境变量和路径 - 类型定义和接口名称 - 测试用例和模拟数据 同时优化部分代码结构，移除未使用的模块，并更新相关依赖项。
114 lines
3.3 KiB
Markdown
114 lines
3.3 KiB
Markdown
# 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 启动失败时提供有意义的错误信息
|
||
- [ ] 评估三种方案的维护成本
|