# 通信层 (Communication Layer)

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

---

## 一、功能概述

### 1.1 基本信息

通信层是 ZCLAW 与 OpenFang Kernel 之间的核心桥梁，负责所有网络通信和协议适配。

| 属性 | 值 |
|------|-----|
| 分类 | 架构层 |
| 优先级 | P0 |
| 成熟度 | L4 |
| 依赖 | 无 |

### 1.2 相关文件

| 文件 | 路径 | 用途 |
|------|------|------|
| 核心实现 | `desktop/src/lib/gateway-client.ts` | WebSocket/REST 客户端 |
| 类型定义 | `desktop/src/types/agent.ts` | Agent 相关类型 |
| 测试文件 | `tests/desktop/gatewayStore.test.ts` | 集成测试 |
| HTTP 助手 | `desktop/src/lib/request-helper.ts` | 重试/超时/取消 |

---

## 二、设计初衷

### 2.1 问题背景

**用户痛点**:
1. OpenClaw 使用 TypeScript，OpenFang 使用 Rust，协议差异大
2. WebSocket 和 REST 需要统一管理
3. 认证机制复杂（Ed25519 + JWT）
4. 网络不稳定时需要自动重连和降级

**系统缺失能力**:
- 缺乏统一的协议适配层
- 缺乏智能的连接管理
- 缺乏安全的凭证存储

**为什么需要**:
ZCLAW 需要同时支持 OpenClaw (旧) 和 OpenFang (新) 两种后端，且需要处理 WebSocket 流式通信和 REST API 两种协议。

### 2.2 设计目标

1. **协议统一**: WebSocket 优先，REST 降级
2. **认证安全**: Ed25519 设备认证 + JWT 会话令牌
3. **连接可靠**: 自动重连、候选 URL 解析、心跳保活
4. **状态同步**: 连接状态实时反馈给 UI

### 2.3 竞品参考

| 项目 | 参考点 |
|------|--------|
| OpenClaw | WebSocket 流式协议设计 |
| NanoClaw | 轻量级 HTTP 客户端 |
| ZeroClaw | 边缘场景连接策略 |

### 2.4 设计约束

- **技术约束**: 必须支持浏览器和 Tauri 双环境
- **兼容性约束**: 同时支持 OpenClaw (18789) 和 OpenFang (4200/50051)
- **安全约束**: API Key 不能明文存储

---

## 三、技术设计

### 3.1 核心接口

```typescript
interface GatewayClient {
  // 连接管理
  connect(url?: string, token?: string): Promise<void>;
  disconnect(): void;
  isConnected(): boolean;

  // 聊天
  chat(message: string, options?: ChatOptions): Promise<ChatResponse>;
  chatStream(message: string, options?: ChatOptions): Promise<void>;

  // Agent 管理
  listAgents(): Promise<Agent[]>;
  listClones(): Promise<Clone[]>;
  createClone(clone: CloneConfig): Promise<Clone>;

  // Hands 管理
  listHands(): Promise<Hand[]>;
  triggerHand(handId: string, input: any): Promise<HandRun>;
  approveHand(runId: string, approved: boolean): Promise<void>;

  // 工作流
  listWorkflows(): Promise<Workflow[]>;
  executeWorkflow(workflowId: string): Promise<WorkflowRun>;
}
```

### 3.2 数据流

```
UI 组件
    │
    ▼
Zustand Store (chatStore, connectionStore)
    │
    ▼
GatewayClient
    │
    ├──► WebSocket (ws://127.0.0.1:50051/ws)
    │       │
    │       └──► 流式事件 (assistant, tool, hand, workflow)
    │
    └──► REST API (/api/*)
            │
            └──► Vite Proxy → OpenFang Kernel
```

### 3.3 状态管理

```typescript
type ConnectionState =
  | 'disconnected'   // 未连接
  | 'connecting'     // 连接中
  | 'connected'      // 已连接
  | 'error';         // 连接错误
```

### 3.4 关键算法

**URL 候选解析顺序**:
1. 显式传入的 URL
2. 本地 Gateway (Tauri 运行时)
3. 快速配置中的 Gateway URL
4. 存储的历史 URL
5. 默认 URL (`ws://127.0.0.1:50051/ws`)
6. 备选 URL 列表

---

## 四、预期作用

### 4.1 用户价值

| 价值类型 | 描述 |
|---------|------|
| 效率提升 | 流式响应，无需等待完整响应 |
| 体验改善 | 连接状态实时可见，断线自动重连 |
| 能力扩展 | 支持 OpenFang 全部 API |

### 4.2 系统价值

| 价值类型 | 描述 |
|---------|------|
| 架构收益 | 协议适配与业务逻辑解耦 |
| 可维护性 | 单一入口，易于调试 |
| 可扩展性 | 新 API 只需添加方法 |

### 4.3 成功指标

| 指标 | 基线 | 目标 | 当前 |
|------|------|------|------|
| 连接成功率 | 70% | 99% | 98% |
| 平均延迟 | 500ms | 100ms | 120ms |
| 重连时间 | 10s | 2s | 1.5s |

---

## 五、实际效果

### 5.1 已实现功能

- [x] WebSocket 连接管理
- [x] REST API 降级
- [x] Ed25519 设备认证
- [x] JWT Token 支持
- [x] URL 候选解析
- [x] 流式事件处理
- [x] 请求重试机制
- [x] 超时和取消

### 5.2 测试覆盖

- **单元测试**: 15+ 项
- **集成测试**: gatewayStore.test.ts
- **覆盖率**: ~85%

### 5.3 已知问题

| 问题 | 严重程度 | 状态 | 计划解决 |
|------|---------|------|---------|
| 无重大问题 | - | - | - |

### 5.4 用户反馈

连接稳定性好，流式响应体验流畅。

---

## 六、演化路线

### 6.1 短期计划（1-2 周）
- [ ] 优化重连策略，添加指数退避

### 6.2 中期计划（1-2 月）
- [ ] 支持多 Gateway 负载均衡

### 6.3 长期愿景
- [ ] 支持分布式 Gateway 集群

---

## 七、头脑风暴笔记

### 7.1 待讨论问题
1. 是否需要支持 gRPC 协议？
2. 离线模式如何处理？

### 7.2 创意想法
- 智能协议选择：根据网络条件自动选择 WebSocket/REST
- 连接池管理：复用连接，减少握手开销

### 7.3 风险与挑战
- **技术风险**: WebSocket 兼容性问题
- **缓解措施**: REST 降级兜底