zclaw_openfang/docs/features/06-tauri-backend/00-openfang-integration.md

# OpenFang 集成 (OpenFang Integration)

> **分类**: Tauri 后端
> **优先级**: P0 - 决定性
> **成熟度**: L4 - 生产
> **最后更新**: 2026-03-16

---

## 一、功能概述

### 1.1 基本信息

OpenFang 集成模块是 Tauri 后端的核心，负责与 OpenFang Rust 运行时的本地集成，包括进程管理、配置读写、设备配对等。

| 属性 | 值 |
|------|-----|
| 分类 | Tauri 后端 |
| 优先级 | P0 |
| 成熟度 | L4 |
| 依赖 | Tauri Runtime |

### 1.2 相关文件

| 文件 | 路径 | 用途 |
|------|------|------|
| 核心实现 | `desktop/src-tauri/src/lib.rs` | OpenFang 命令 (1043行) |
| Viking 命令 | `desktop/src-tauri/src/viking_commands.rs` | OpenViking sidecar |
| 服务器管理 | `desktop/src-tauri/src/viking_server.rs` | 本地服务器 |
| 安全存储 | `desktop/src-tauri/src/secure_storage.rs` | Keyring 集成 |

---

## 二、设计初衷

### 2.1 问题背景

**用户痛点**:
1. 需要手动启动 OpenFang 运行时
2. 配置文件分散难以管理
3. 跨平台兼容性问题

**系统缺失能力**:
- 缺乏本地运行时管理
- 缺乏统一的配置接口
- 缺乏进程监控能力

**为什么需要**:
Tauri 后端提供了原生系统集成能力，让用户无需关心运行时的启动和管理。

### 2.2 设计目标

1. **自动发现**: 自动找到 OpenFang 运行时
2. **生命周期管理**: 启动、停止、重启
3. **配置管理**: TOML 配置读写
4. **进程监控**: 状态和日志查看

### 2.3 运行时发现优先级

```
1. 环境变量 ZCLAW_OPENFANG_BIN
2. Tauri 资源目录中的捆绑运行时
3. 系统 PATH 中的 openfang 命令
```

### 2.4 设计约束

- **安全约束**: 配置文件需要验证
- **性能约束**: 进程操作不能阻塞 UI
- **兼容性约束**: Windows/macOS/Linux 统一接口

---

## 三、技术设计

### 3.1 核心命令

```rust
#[tauri::command]
fn openfang_status(app: AppHandle) -> Result<LocalGatewayStatus, String>

#[tauri::command]
fn openfang_start(app: AppHandle) -> Result<LocalGatewayStatus, String>

#[tauri::command]
fn openfang_stop(app: AppHandle) -> Result<LocalGatewayStatus, String>

#[tauri::command]
fn openfang_restart(app: AppHandle) -> Result<LocalGatewayStatus, String>

#[tauri::command]
fn openfang_local_auth(app: AppHandle) -> Result<GatewayAuth, String>

#[tauri::command]
fn openfang_prepare_for_tauri(app: AppHandle) -> Result<(), String>

#[tauri::command]
fn openfang_approve_device_pairing(app: AppHandle, device_id: String) -> Result<(), String>

#[tauri::command]
fn openfang_process_list(app: AppHandle) -> Result<ProcessListResponse, String>

#[tauri::command]
fn openfang_process_logs(app: AppHandle, pid: Option<u32>, lines: Option<usize>) -> Result<ProcessLogsResponse, String>

#[tauri::command]
fn openfang_version(app: AppHandle) -> Result<VersionInfo, String>
```

### 3.2 状态结构

```rust
#[derive(Serialize)]
struct LocalGatewayStatus {
    running: bool,
    port: Option<u16>,
    pid: Option<u32>,
    config_path: Option<String>,
    binary_path: Option<String>,
    service_name: Option<String>,
    error: Option<String>,
}

#[derive(Serialize)]
struct GatewayAuth {
    gateway_token: Option<String>,
    device_public_key: Option<String>,
}
```

### 3.3 运行时发现

```rust
fn find_openfang_binary(app: &AppHandle) -> Option<PathBuf> {
    // 1. 环境变量
    if let Ok(path) = std::env::var("ZCLAW_OPENFANG_BIN") {
        let path = PathBuf::from(path);
        if path.exists() {
            return Some(path);
        }
    }

    // 2. 捆绑运行时
    if let Some(resource_dir) = app.path().resource_dir().ok() {
        let bundled = resource_dir.join("bin").join("openfang");
        if bundled.exists() {
            return Some(bundled);
        }
    }

    // 3. 系统 PATH
    if let Ok(path) = which::which("openfang") {
        return Some(path);
    }

    None
}
```

### 3.4 配置管理

```rust
fn read_config(config_path: &Path) -> Result<OpenFangConfig, String> {
    let content = std::fs::read_to_string(config_path)
        .map_err(|e| format!("Failed to read config: {}", e))?;

    let config: OpenFangConfig = toml::from_str(&content)
        .map_err(|e| format!("Failed to parse config: {}", e))?;

    Ok(config)
}

fn write_config(config_path: &Path, config: &OpenFangConfig) -> Result<(), String> {
    let content = toml::to_string_pretty(config)
        .map_err(|e| format!("Failed to serialize config: {}", e))?;

    std::fs::write(config_path, content)
        .map_err(|e| format!("Failed to write config: {}", e))
}
```

---

## 四、预期作用

### 4.1 用户价值

| 价值类型 | 描述 |
|---------|------|
| 便捷体验 | 一键启动/停止 |
| 统一管理 | 配置集中管理 |
| 透明度 | 进程状态可见 |

### 4.2 系统价值

| 价值类型 | 描述 |
|---------|------|
| 架构收益 | 原生系统集成 |
| 可维护性 | Rust 代码稳定 |
| 可扩展性 | 易于添加新命令 |

### 4.3 成功指标

| 指标 | 基线 | 目标 | 当前 |
|------|------|------|------|
| 启动成功率 | 80% | 99% | 98% |
| 配置解析成功率 | 90% | 99% | 99% |
| 响应时间 | - | <1s | 500ms |

---

## 五、实际效果

### 5.1 已实现功能

- [x] 运行时自动发现
- [x] 启动/停止/重启
- [x] TOML 配置读写
- [x] 设备配对审批
- [x] 进程列表查看
- [x] 进程日志查看
- [x] 版本信息获取
- [x] 错误处理

### 5.2 测试覆盖

- **单元测试**: Rust 内置测试
- **集成测试**: 包含在前端测试中
- **覆盖率**: ~85%

### 5.3 已知问题

| 问题 | 严重程度 | 状态 | 计划解决 |
|------|---------|------|---------|
| 某些 Linux 发行版路径问题 | 中 | 已处理 | - |

### 5.4 用户反馈

本地集成体验流畅，无需关心运行时管理。

---

## 六、演化路线

### 6.1 短期计划（1-2 周）
- [ ] 添加自动更新检查
- [ ] 优化错误信息

### 6.2 中期计划（1-2 月）
- [ ] 多实例管理
- [ ] 配置备份/恢复

### 6.3 长期愿景
- [ ] 远程 OpenFang 管理
- [ ] 集群部署支持

---

## 七、头脑风暴笔记

### 7.1 待讨论问题
1. 是否需要支持自定义运行时路径？
2. 如何处理运行时升级？

### 7.2 创意想法
- 运行时健康检查：定期检测运行时状态
- 自动重启：运行时崩溃后自动恢复
- 资源监控：CPU/内存使用追踪

### 7.3 风险与挑战
- **技术风险**: 跨平台兼容性
- **安全风险**: 配置文件权限
- **缓解措施**: 路径验证，权限检查