refactor: 统一项目名称从OpenFang到ZCLAW
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。包括:
- 配置文件中的项目名称
- 代码注释和文档引用
- 环境变量和路径
- 类型定义和接口名称
- 测试用例和模拟数据

同时优化部分代码结构,移除未使用的模块,并更新相关依赖项。
This commit is contained in:
iven
2026-03-27 07:36:03 +08:00
parent 4b08804aa9
commit 0d4fa96b82
226 changed files with 7288 additions and 5788 deletions

View File

@@ -1,78 +1,78 @@
# Design: OpenFang 集成策略论证
# Design: ZCLAW 集成策略论证
Generated by /office-hours on 2026-03-22
Branch: unknown
Repo: ZClaw_openfang
Repo: ZClaw_zclaw
Status: DRAFT
Mode: Builder
## 问题陈述
当前 ZCLAW 依赖外部 OpenFang 二进制作为运行时后端,导致:
1. 需要管理 OpenFang 二进制文件的下载、安装、版本兼容性
2. OpenFang 进程崩溃或锁定会影响 ZCLAW 全部功能
当前 ZCLAW 依赖外部 ZCLAW 二进制作为运行时后端,导致:
1. 需要管理 ZCLAW 二进制文件的下载、安装、版本兼容性
2. ZCLAW 进程崩溃或锁定会影响 ZCLAW 全部功能
3. 两个独立进程间通过 WebSocket/REST 通信,引入复杂性和潜在故障点
4. 调试困难 - 问题可能在 ZCLAW 或 OpenFang 任何一侧
4. 调试困难 - 问题可能在 ZCLAW 或 ZCLAW 任何一侧
## 现状架构
```
ZCLAW Desktop (Tauri/Rust)
├── React Frontend (端口 1420)
└── OpenFang Gateway (端口 50051) ← 外部进程
└── ZCLAW Gateway (端口 50051) ← 外部进程
```
通信方式:
- Tauri Commands → 启动/停止 OpenFang 进程
- WebSocket → 前端与 OpenFang 对话
- Tauri Commands → 启动/停止 ZCLAW 进程
- WebSocket → 前端与 ZCLAW 对话
- REST API → 健康检查、配置
## 集成方案对比
### Approach A: 保持现状(外部进程)
**Summary:** 继续使用外部 OpenFang 二进制,通过进程管理集成
**Summary:** 继续使用外部 ZCLAW 二进制,通过进程管理集成
**Effort:** S
**Risk:** Low
**Pros:**
- OpenFang 可以独立开发和升级
- 不用重新编译 OpenFang 核心代码
- ZCLAW 可以独立开发和升级
- 不用重新编译 ZCLAW 核心代码
- 职责分离清晰
**Cons:**
- 依赖管理复杂(版本、下载、锁文件)
- 两个进程通信引入延迟和故障点
- 用户需要安装两个组件
### Approach B: 源码集成(OpenFang 作为 Tauri Submodule
### Approach B: 源码集成(ZCLAW 作为 Tauri Submodule
**Summary:**OpenFang 源码作为 git submodule在构建时静态编译进 Tauri 应用
**Summary:**ZCLAW 源码作为 git submodule在构建时静态编译进 Tauri 应用
**Effort:** XL
**Risk:** High
**Pros:**
- 单个二进制,简化分发
- 版本锁定,完全可控
- 可以深度定制 OpenFang 行为
- 可以深度定制 ZCLAW 行为
**Cons:**
- OpenFang 代码库庞大(~50万行 Rust
- ZCLAW 代码库庞大(~50万行 Rust
- 编译时间大幅增加
- 升级困难 - 需要手动同步 submodule
- 失去 OpenFang 独立升级的灵活性
- 失去 ZCLAW 独立升级的灵活性
### Approach C: gRPC Service 集成(推荐)
**Summary:**OpenFang 核心功能封装为 Rust crate/ZCLAW library通过内部 API 调用而非进程通信
**Summary:**ZCLAW 核心功能封装为 Rust crate/ZCLAW library通过内部 API 调用而非进程通信
**Effort:** M
**Risk:** Medium
**Pros:**
- 保留 OpenFang 作为独立模块(可用作其他项目的库)
- 保留 ZCLAW 作为独立模块(可用作其他项目的库)
- 去掉进程启动/管理复杂性
- 同一进程内通信,无网络开销
- 可以精确控制 OpenFang API 表面
- 可以精确控制 ZCLAW API 表面
**Cons:**
- 仍然需要编译 OpenFang 源码
- 仍然需要编译 ZCLAW 源码
- API 版本管理需要同步
- 深度集成可能失去某些运行时灵活性
@@ -80,7 +80,7 @@ ZCLAW Desktop (Tauri/Rust)
| 问题 | 根因 | 解决方案 |
|------|------|----------|
| 数据库锁 | 多个 OpenFang 进程争用 | 确保单实例 + 正确清理 |
| 数据库锁 | 多个 ZCLAW 进程争用 | 确保单实例 + 正确清理 |
| 启动失败 | Tauri 命令未正确调用 | 修复 IPC 调用链 |
| 版本兼容 | 外部二进制 | 版本锁定 + 自动化下载 |
@@ -91,23 +91,23 @@ ZCLAW Desktop (Tauri/Rust)
理由:
1. 平衡了"完全独立"和"深度集成"的优缺点
2. 可以逐步迁移 - 先解决启动问题,再考虑集成深度
3. 保留 OpenFang 可测试性和可插拔性
3. 保留 ZCLAW 可测试性和可插拔性
## 下一步行动
1. **立即修复**:诊断并修复当前 OpenFang 启动失败问题
1. **立即修复**:诊断并修复当前 ZCLAW 启动失败问题
2. **短期**:添加启动失败时的详细错误日志
3. **中期**:评估 gRPC 集成工作量
4. **长期**:根据实际使用情况决定集成深度
## 待解决问题
1. OpenFang 为何拒绝启动?(数据库锁的根因是什么?)
2. Tauri 是否正确检测并处理 OpenFang 启动失败?
3. 用户实际使用场景是否需要 OpenFang 独立运行?
1. ZCLAW 为何拒绝启动?(数据库锁的根因是什么?)
2. Tauri 是否正确检测并处理 ZCLAW 启动失败?
3. 用户实际使用场景是否需要 ZCLAW 独立运行?
## 成功标准
- [ ] `pnpm start:dev` 能可靠启动完整服务栈
- [ ] OpenFang 启动失败时提供有意义的错误信息
- [ ] ZCLAW 启动失败时提供有意义的错误信息
- [ ] 评估三种方案的维护成本