网关协议
Gateway 使用 WebSocket 作为主要通信协议。本文档定义了帧格式、消息类型和通信模式。
连接
WebSocket 端点：
text
ws://127.0.0.1:18789/ws (本地)
wss://gateway.example.com/ws (远程 TLS)帧格式
所有 WebSocket 帧（Frame）使用 JSON 编码，包含以下公共字段：
json
{
"type": "message-type",
"id": "msg_unique_id",
"timestamp": "2025-01-15T10:30:00Z",
"payload": {}
}| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
type | string | ✅ | 消息类型标识 |
id | string | ✅ | 消息唯一 ID |
timestamp | string | ❌ | ISO 8601 时间戳 |
payload | object | ❌ | 消息负载 |
消息类型
连接管理
| 类型 | 方向 | 说明 |
|---|---|---|
connect | Client → Gateway | 认证连接请求 |
hello-ok | Gateway → Client | 认证成功 |
unauthorized | Gateway → Client | 认证失败 |
ping | 双向 | 心跳检测 |
pong | 双向 | 心跳响应 |
disconnect | 双向 | 优雅断开 |
会话管理
| 类型 | 方向 | 说明 |
|---|---|---|
session-create | Client → Gateway | 创建新会话 |
session-created | Gateway → Client | 会话创建成功 |
session-resume | Client → Gateway | 恢复已有会话 |
session-end | 双向 | 结束会话 |
对话消息
| 类型 | 方向 | 说明 |
|---|---|---|
user-message | Client → Gateway | 用户消息 |
assistant-message | Gateway → Client | 助手回复 |
assistant-delta | Gateway → Client | 流式回复增量 |
message-complete | Gateway → Client | 回复完成 |
工具调用
| 类型 | 方向 | 说明 |
|---|---|---|
tool-call | Gateway → Client | 请求执行工具 |
tool-result | Client → Gateway | 工具执行结果 |
tool-approve | Client → Gateway | 批准工具执行 |
tool-deny | Client → Gateway | 拒绝工具执行 |
请求 / 响应模式
认证流程
json
// 1. Client → Gateway: connect
{
"type": "connect",
"id": "msg_001",
"payload": {
"token": "your-token",
"clientId": "device_abc",
"clientName": "MacBook Pro",
"version": "1.0"
}
}
// 2. Gateway → Client: hello-ok
{
"type": "hello-ok",
"id": "msg_002",
"payload": {
"sessionId": "sess_xyz",
"gatewayVersion": "0.5.0",
"capabilities": ["streaming", "tools"]
}
}对话流程
json
// 1. Client → Gateway: user-message
{
"type": "user-message",
"id": "msg_010",
"payload": {
"sessionId": "sess_xyz",
"content": "请帮我写一个 Python 脚本",
"model": "gpt-4o"
}
}
// 2. Gateway → Client: assistant-delta (流式)
{
"type": "assistant-delta",
"id": "msg_011",
"payload": {
"sessionId": "sess_xyz",
"delta": "好的，",
"index": 0
}
}
// 3. Gateway → Client: assistant-delta (继续)
{
"type": "assistant-delta",
"id": "msg_012",
"payload": {
"sessionId": "sess_xyz",
"delta": "我来帮你写一个脚本",
"index": 1
}
}
// 4. Gateway → Client: message-complete
{
"type": "message-complete",
"id": "msg_013",
"payload": {
"sessionId": "sess_xyz",
"usage": {
"promptTokens": 25,
"completionTokens": 150,
"totalTokens": 175
}
}
}工具调用流程
json
// 1. Gateway → Client: tool-call
{
"type": "tool-call",
"id": "msg_020",
"payload": {
"sessionId": "sess_xyz",
"toolCallId": "tc_001",
"toolName": "read_file",
"arguments": {
"path": "/src/main.py"
},
"requiresApproval": false
}
}
// 2. Client → Gateway: tool-result
{
"type": "tool-result",
"id": "msg_021",
"payload": {
"toolCallId": "tc_001",
"result": "print('hello world')",
"success": true
}
}事件类型
Gateway 会主动推送（Push）以下事件：
| 事件 | 说明 |
|---|---|
channel-status | Channel 状态变更（连接/断开） |
session-timeout | 会话超时警告 |
config-reload | 配置已重新加载 |
gateway-shutdown | Gateway 即将关闭 |
json
{
"type": "event",
"id": "evt_001",
"payload": {
"event": "channel-status",
"channel": "openai-main",
"status": "connected"
}
}错误处理
错误消息格式：
json
{
"type": "error",
"id": "err_001",
"payload": {
"code": "rate_limit_exceeded",
"message": "Too many requests. Please retry after 30 seconds.",
"retryAfter": 30
}
}| 错误码 | 说明 |
|---|---|
unauthorized | 认证失败 |
session_not_found | 会话不存在 |
rate_limit_exceeded | 速率限制 |
model_not_available | 模型不可用 |
tool_execution_failed | 工具执行失败 |
internal_error | 内部错误 |
重试策略
收到 rate_limit_exceeded 时，使用 retryAfter 字段指定的秒数进行退避重试（Backoff Retry）。