907 lines
22 KiB
Markdown
907 lines
22 KiB
Markdown
# Bridge 平台协议规范
|
||
|
||
> 版本：1.0-draft
|
||
> 状态：草案 — 实现前可能调整
|
||
|
||
## 概述
|
||
|
||
Bridge 协议允许使用**任何编程语言**编写的外部平台适配器在运行时通过 WebSocket 动态接入 cc-connect，无需编写 Go 代码或重新编译二进制文件。
|
||
|
||
### 架构
|
||
|
||
```
|
||
┌──────────────────────────────────────────────────────┐
|
||
│ cc-connect │
|
||
│ │
|
||
│ ┌────────────┐ ┌────────────┐ ┌────────────────┐ │
|
||
│ │ Telegram │ │ 飞书 │ │ BridgePlatform │ │
|
||
│ │ (原生) │ │ (原生) │ │ (WebSocket) │ │
|
||
│ └─────┬──────┘ └─────┬──────┘ └───────┬────────┘ │
|
||
│ │ │ │ │
|
||
│ └──────────────┴────────────────┘ │
|
||
│ │ │
|
||
│ ┌─────┴─────┐ │
|
||
│ │ Engine │ │
|
||
│ └───────────┘ │
|
||
└──────────────────────────────────────────────────────┘
|
||
│ WebSocket
|
||
┌──────────┴───────────┐
|
||
│ │
|
||
┌──────────┴──────┐ ┌───────────┴─────┐
|
||
│ Python 适配器 │ │ Node.js 适配器 │
|
||
│ (微信公众号等) │ │ (自定义聊天等) │
|
||
└─────────────────┘ └─────────────────┘
|
||
```
|
||
|
||
`BridgePlatform` 是 cc-connect 内置的一个平台实现，它：
|
||
|
||
1. 暴露 WebSocket 端点供外部适配器连接。
|
||
2. 将 WebSocket 消息转换为 `core.Platform` 接口调用。
|
||
3. 将 Engine 的回复通过同一个 WebSocket 连接推送回适配器。
|
||
|
||
---
|
||
|
||
## 连接
|
||
|
||
### 端点
|
||
|
||
```
|
||
ws://<host>:<port>/bridge/ws
|
||
```
|
||
|
||
端口和路径通过 `config.toml` 配置：
|
||
|
||
```toml
|
||
[bridge]
|
||
enabled = true
|
||
port = 9810
|
||
path = "/bridge/ws" # 可选，默认 "/bridge/ws"
|
||
token = "your-secret" # 认证密钥，必填
|
||
```
|
||
|
||
### 认证
|
||
|
||
适配器连接时必须通过以下方式之一进行身份验证：
|
||
|
||
| 方式 | 示例 |
|
||
|------|------|
|
||
| URL 查询参数 | `ws://host:9810/bridge/ws?token=your-secret` |
|
||
| 请求头 | `Authorization: Bearer your-secret` |
|
||
| 请求头 | `X-Bridge-Token: your-secret` |
|
||
|
||
未认证的连接将被拒绝并返回 HTTP 401。
|
||
|
||
### 连接生命周期
|
||
|
||
```
|
||
适配器 cc-connect
|
||
│ │
|
||
│──── WebSocket 连接 ─────────────→│ (携带 token)
|
||
│ │
|
||
│──── register ──────────────────→│ (声明平台名和能力)
|
||
│←─── register_ack ──────────────│ (确认或拒绝)
|
||
│ │
|
||
│←──→ message / reply 消息交换 ──→│ (双向)
|
||
│ │
|
||
│──── ping ──────────────────────→│ (心跳保活，建议 30 秒)
|
||
│←─── pong ──────────────────────│
|
||
│ │
|
||
│──── close ─────────────────────→│ (优雅断开)
|
||
```
|
||
|
||
---
|
||
|
||
## 消息协议
|
||
|
||
所有消息均为 JSON 对象，必须包含 `type` 字段。协议使用 WebSocket 文本帧传输（每帧一个 JSON 对象）。
|
||
|
||
### 适配器 → cc-connect
|
||
|
||
#### `register`
|
||
|
||
连接后必须发送的第一条消息。声明适配器身份和支持的能力。
|
||
|
||
```json
|
||
{
|
||
"type": "register",
|
||
"platform": "wechat",
|
||
"capabilities": ["text", "image", "file", "audio", "card", "buttons", "typing", "update_message", "preview"],
|
||
"metadata": {
|
||
"version": "1.0.0",
|
||
"description": "微信公众号适配器"
|
||
}
|
||
}
|
||
```
|
||
|
||
**字段说明：**
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `type` | string | 是 | `"register"` |
|
||
| `platform` | string | 是 | 唯一平台名称（小写字母、数字、连字符）。用于组成 session key。 |
|
||
| `capabilities` | string[] | 是 | 支持的能力列表（见[能力声明](#能力声明)）。 |
|
||
| `metadata` | object | 否 | 自由格式的元信息，用于日志/调试。 |
|
||
|
||
#### `message`
|
||
|
||
将用户消息传递给引擎。
|
||
|
||
```json
|
||
{
|
||
"type": "message",
|
||
"msg_id": "msg-001",
|
||
"session_key": "wechat:user123:user123",
|
||
"user_id": "user123",
|
||
"user_name": "Alice",
|
||
"content": "你好，你能做什么？",
|
||
"reply_ctx": "conv-abc-123",
|
||
"images": [],
|
||
"files": [],
|
||
"audio": null
|
||
}
|
||
```
|
||
|
||
**字段说明：**
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `type` | string | 是 | `"message"` |
|
||
| `msg_id` | string | 是 | 平台消息 ID，用于追踪。 |
|
||
| `session_key` | string | 是 | 唯一会话标识。格式：`{platform}:{scope}:{user}`。由适配器定义组合方式。 |
|
||
| `user_id` | string | 是 | 用户在平台上的唯一标识。 |
|
||
| `user_name` | string | 否 | 显示名称。 |
|
||
| `content` | string | 是 | 文本内容。 |
|
||
| `reply_ctx` | string | 是 | 不透明的上下文字符串，适配器需要它来路由回复。cc-connect 会在每个回复中原样回传。 |
|
||
| `images` | Image[] | 否 | 附带的图片（见[图片对象](#图片对象)）。 |
|
||
| `files` | File[] | 否 | 附带的文件（见[文件对象](#文件对象)）。 |
|
||
| `audio` | Audio | 否 | 语音消息（见[音频对象](#音频对象)）。 |
|
||
|
||
#### `card_action`
|
||
|
||
用户点击了卡片上的按钮或选择了选项。
|
||
|
||
```json
|
||
{
|
||
"type": "card_action",
|
||
"session_key": "wechat:user123:user123",
|
||
"action": "cmd:/new",
|
||
"reply_ctx": "conv-abc-123"
|
||
}
|
||
```
|
||
|
||
**字段说明：**
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `type` | string | 是 | `"card_action"` |
|
||
| `session_key` | string | 是 | 触发操作的会话。 |
|
||
| `action` | string | 是 | 按钮的回调值（如 `"cmd:/new"`、`"nav:/model"`、`"act:/heartbeat pause"`）。 |
|
||
| `reply_ctx` | string | 是 | 用于路由响应的回复上下文。 |
|
||
|
||
#### `preview_ack`
|
||
|
||
确认预览消息已创建，返回用于后续更新的 handle。
|
||
|
||
```json
|
||
{
|
||
"type": "preview_ack",
|
||
"ref_id": "preview-req-001",
|
||
"preview_handle": "platform-msg-id-789"
|
||
}
|
||
```
|
||
|
||
#### `ping`
|
||
|
||
心跳保活。cc-connect 回应 `pong`。
|
||
|
||
```json
|
||
{
|
||
"type": "ping",
|
||
"ts": 1710000000000
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### cc-connect → 适配器
|
||
|
||
#### `register_ack`
|
||
|
||
确认或拒绝注册。
|
||
|
||
```json
|
||
{
|
||
"type": "register_ack",
|
||
"ok": true,
|
||
"error": ""
|
||
}
|
||
```
|
||
|
||
#### `reply`
|
||
|
||
发送完整回复消息给用户。
|
||
|
||
```json
|
||
{
|
||
"type": "reply",
|
||
"session_key": "wechat:user123:user123",
|
||
"reply_ctx": "conv-abc-123",
|
||
"content": "我可以帮你完成编码任务！",
|
||
"format": "text"
|
||
}
|
||
```
|
||
|
||
**字段说明：**
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `type` | string | 是 | `"reply"` |
|
||
| `session_key` | string | 是 | 目标会话。 |
|
||
| `reply_ctx` | string | 是 | 来自原始消息的回传。 |
|
||
| `content` | string | 是 | 回复文本内容。 |
|
||
| `format` | string | 否 | `"text"`（默认）或 `"markdown"`。 |
|
||
|
||
#### `reply_stream`
|
||
|
||
流式增量内容，用于实时打字预览。仅在适配器声明了 `"preview"` 能力时发送。
|
||
|
||
```json
|
||
{
|
||
"type": "reply_stream",
|
||
"session_key": "wechat:user123:user123",
|
||
"reply_ctx": "conv-abc-123",
|
||
"delta": "部分内容...",
|
||
"full_text": "累积的完整文本...",
|
||
"preview_handle": "platform-msg-id-789",
|
||
"done": false
|
||
}
|
||
```
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `delta` | string | 自上次流式消息以来的新增文本。 |
|
||
| `full_text` | string | 完整累积文本。适配器可用于"替换整条消息"的更新方式。 |
|
||
| `preview_handle` | string | 由 `preview_ack` 返回的 handle。首条流式消息时为空。 |
|
||
| `done` | bool | 最后一条流式消息时为 `true`。 |
|
||
|
||
#### `preview_start`
|
||
|
||
请求适配器创建初始预览消息（用于流式输出）。
|
||
|
||
```json
|
||
{
|
||
"type": "preview_start",
|
||
"ref_id": "preview-req-001",
|
||
"session_key": "wechat:user123:user123",
|
||
"reply_ctx": "conv-abc-123",
|
||
"content": "思考中..."
|
||
}
|
||
```
|
||
|
||
适配器应发送消息后回应 `preview_ack`，包含平台消息 ID。
|
||
|
||
#### `update_message`
|
||
|
||
请求适配器原地编辑已有消息。用于流式预览更新。
|
||
|
||
```json
|
||
{
|
||
"type": "update_message",
|
||
"session_key": "wechat:user123:user123",
|
||
"preview_handle": "platform-msg-id-789",
|
||
"content": "更新后的文本内容..."
|
||
}
|
||
```
|
||
|
||
#### `delete_message`
|
||
|
||
请求适配器删除消息（如清理预览消息）。
|
||
|
||
```json
|
||
{
|
||
"type": "delete_message",
|
||
"session_key": "wechat:user123:user123",
|
||
"preview_handle": "platform-msg-id-789"
|
||
}
|
||
```
|
||
|
||
#### `card`
|
||
|
||
发送结构化卡片给用户。仅在适配器声明了 `"card"` 能力时发送；否则 cc-connect 会降级为 `reply`，内容使用 `card.RenderText()` 生成的纯文本。
|
||
|
||
```json
|
||
{
|
||
"type": "card",
|
||
"session_key": "wechat:user123:user123",
|
||
"reply_ctx": "conv-abc-123",
|
||
"card": {
|
||
"header": {
|
||
"title": "模型选择",
|
||
"color": "blue"
|
||
},
|
||
"elements": [
|
||
{
|
||
"type": "markdown",
|
||
"content": "请选择一个模型："
|
||
},
|
||
{
|
||
"type": "actions",
|
||
"buttons": [
|
||
{"text": "GPT-4", "btn_type": "primary", "value": "cmd:/model switch gpt-4"},
|
||
{"text": "Claude", "btn_type": "default", "value": "cmd:/model switch claude"}
|
||
],
|
||
"layout": "row"
|
||
},
|
||
{
|
||
"type": "divider"
|
||
},
|
||
{
|
||
"type": "note",
|
||
"text": "当前模型：gpt-4"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
完整卡片元素参见[卡片 Schema](#卡片-schema)。
|
||
|
||
#### `buttons`
|
||
|
||
发送带有内联按钮的消息。仅在适配器声明了 `"buttons"` 能力时发送。
|
||
|
||
```json
|
||
{
|
||
"type": "buttons",
|
||
"session_key": "wechat:user123:user123",
|
||
"reply_ctx": "conv-abc-123",
|
||
"content": "允许执行工具：bash(rm -rf /tmp/old)？",
|
||
"buttons": [
|
||
[
|
||
{"text": "✅ 允许", "data": "perm:req-123:allow"},
|
||
{"text": "❌ 拒绝", "data": "perm:req-123:deny"}
|
||
]
|
||
]
|
||
}
|
||
```
|
||
|
||
`buttons` 是二维数组：每个内层数组是一行按钮。
|
||
|
||
#### `typing_start`
|
||
|
||
请求适配器显示"正在输入"指示器。
|
||
|
||
```json
|
||
{
|
||
"type": "typing_start",
|
||
"session_key": "wechat:user123:user123",
|
||
"reply_ctx": "conv-abc-123"
|
||
}
|
||
```
|
||
|
||
#### `typing_stop`
|
||
|
||
请求适配器隐藏"正在输入"指示器。
|
||
|
||
```json
|
||
{
|
||
"type": "typing_stop",
|
||
"session_key": "wechat:user123:user123",
|
||
"reply_ctx": "conv-abc-123"
|
||
}
|
||
```
|
||
|
||
#### `audio`
|
||
|
||
发送语音/音频消息。仅在适配器声明了 `"audio"` 能力时发送。
|
||
|
||
```json
|
||
{
|
||
"type": "audio",
|
||
"session_key": "wechat:user123:user123",
|
||
"reply_ctx": "conv-abc-123",
|
||
"data": "<base64 编码的音频数据>",
|
||
"format": "mp3"
|
||
}
|
||
```
|
||
|
||
#### `image`
|
||
|
||
发送图片给用户。仅在适配器声明了 `"image"` 能力时发送。
|
||
|
||
```json
|
||
{
|
||
"type": "image",
|
||
"session_key": "wechat:user123:user123",
|
||
"reply_ctx": "conv-abc-123",
|
||
"data": "<base64 编码的图片数据>",
|
||
"mime_type": "image/png",
|
||
"file_name": "screenshot.png"
|
||
}
|
||
```
|
||
|
||
#### `file`
|
||
|
||
发送文件给用户。仅在适配器声明了 `"file"` 能力时发送。
|
||
|
||
```json
|
||
{
|
||
"type": "file",
|
||
"session_key": "wechat:user123:user123",
|
||
"reply_ctx": "conv-abc-123",
|
||
"data": "<base64 编码的文件数据>",
|
||
"mime_type": "application/pdf",
|
||
"file_name": "report.pdf"
|
||
}
|
||
```
|
||
|
||
#### `pong`
|
||
|
||
对 `ping` 的回应。
|
||
|
||
```json
|
||
{
|
||
"type": "pong",
|
||
"ts": 1710000000000
|
||
}
|
||
```
|
||
|
||
#### `error`
|
||
|
||
通知适配器服务端错误。
|
||
|
||
```json
|
||
{
|
||
"type": "error",
|
||
"code": "session_not_found",
|
||
"message": "找不到给定 key 的活跃会话"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 数据 Schema
|
||
|
||
### 能力声明
|
||
|
||
| 能力 | 说明 | 启用的消息类型 |
|
||
|------|------|--------------|
|
||
| `text` | 基础文本消息（必须） | `message`、`reply` |
|
||
| `image` | 收发图片 | `message.images`、`image` 回复 |
|
||
| `file` | 收发文件 | `message.files`、`file` 回复 |
|
||
| `audio` | 收发语音消息 | `message.audio`、`audio` 回复 |
|
||
| `card` | 结构化富卡片渲染 | `card` 回复 |
|
||
| `buttons` | 可点击的内联按钮 | `buttons` 回复、`card_action` |
|
||
| `typing` | 正在输入指示器 | `typing_start`、`typing_stop` |
|
||
| `update_message` | 编辑已有消息 | `update_message` |
|
||
| `preview` | 流式预览（需要 `update_message`） | `preview_start`、`reply_stream` |
|
||
| `delete_message` | 删除消息 | `delete_message` |
|
||
| `reconstruct_reply` | 可从 session_key 重建回复上下文 | 启用定时任务/心跳消息 |
|
||
|
||
如果未声明某个能力，cc-connect 会自动降级：
|
||
- 没有 `card` → 卡片通过 `RenderText()` 渲染为纯文本。
|
||
- 没有 `buttons` → 按钮被省略或渲染为文本提示。
|
||
- 没有 `preview` → 禁用流式预览；只发送最终回复。
|
||
- 没有 `typing` → 跳过输入指示器。
|
||
|
||
### 图片对象
|
||
|
||
```json
|
||
{
|
||
"mime_type": "image/png",
|
||
"data": "<base64 编码>",
|
||
"file_name": "screenshot.png"
|
||
}
|
||
```
|
||
|
||
### 文件对象
|
||
|
||
```json
|
||
{
|
||
"mime_type": "application/pdf",
|
||
"data": "<base64 编码>",
|
||
"file_name": "report.pdf"
|
||
}
|
||
```
|
||
|
||
### 音频对象
|
||
|
||
```json
|
||
{
|
||
"mime_type": "audio/ogg",
|
||
"data": "<base64 编码>",
|
||
"format": "ogg",
|
||
"duration": 5
|
||
}
|
||
```
|
||
|
||
### 卡片 Schema
|
||
|
||
卡片由可选的 header 和元素列表组成：
|
||
|
||
```json
|
||
{
|
||
"header": {
|
||
"title": "卡片标题",
|
||
"color": "blue"
|
||
},
|
||
"elements": [ ... ]
|
||
}
|
||
```
|
||
|
||
**支持的颜色：** `blue`、`green`、`red`、`orange`、`purple`、`grey`、`turquoise`、`violet`、`indigo`、`wathet`、`yellow`、`carmine`。
|
||
|
||
#### 元素类型
|
||
|
||
**Markdown 文本**
|
||
```json
|
||
{"type": "markdown", "content": "**加粗** 和 _斜体_"}
|
||
```
|
||
|
||
**分割线**
|
||
```json
|
||
{"type": "divider"}
|
||
```
|
||
|
||
**操作按钮行**
|
||
```json
|
||
{
|
||
"type": "actions",
|
||
"buttons": [
|
||
{"text": "点我", "btn_type": "primary", "value": "cmd:/do-something"}
|
||
],
|
||
"layout": "row"
|
||
}
|
||
```
|
||
|
||
`btn_type`：`"primary"`、`"default"`、`"danger"`。
|
||
`layout`：`"row"`（默认）、`"equal_columns"`。
|
||
|
||
**列表项（描述 + 按钮）**
|
||
```json
|
||
{
|
||
"type": "list_item",
|
||
"text": "GPT-4 — 最强模型",
|
||
"btn_text": "选择",
|
||
"btn_type": "primary",
|
||
"btn_value": "cmd:/model switch gpt-4"
|
||
}
|
||
```
|
||
|
||
**下拉选择器**
|
||
```json
|
||
{
|
||
"type": "select",
|
||
"placeholder": "选择一个模型",
|
||
"options": [
|
||
{"text": "GPT-4", "value": "cmd:/model switch gpt-4"},
|
||
{"text": "Claude", "value": "cmd:/model switch claude"}
|
||
],
|
||
"init_value": "cmd:/model switch gpt-4"
|
||
}
|
||
```
|
||
|
||
**脚注**
|
||
```json
|
||
{
|
||
"type": "note",
|
||
"text": "提示：使用 /help 查看所有命令",
|
||
"tag": "可选的机器标签"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## Session Key 格式
|
||
|
||
Session key 遵循以下格式：
|
||
|
||
```
|
||
{platform}:{scope}:{user_id}
|
||
```
|
||
|
||
- **platform**：注册时的 `platform` 名称（如 `wechat`）。
|
||
- **scope**：分组范围 — 可以是群/频道 ID，也可以与 `user_id` 相同（一对一私聊）。
|
||
- **user_id**：用户在平台上的唯一标识。
|
||
|
||
示例：
|
||
- `wechat:user123:user123` — 私聊
|
||
- `wechat:group456:user123` — 用户在群聊中
|
||
- `matrix:room789:alice` — Matrix 聊天室
|
||
|
||
适配器负责构建一致的 session key。
|
||
|
||
---
|
||
|
||
## 会话管理 REST API
|
||
|
||
除了用于实时消息的 WebSocket 协议外，Bridge Server 还在同一端口上暴露 HTTP REST 端点用于会话管理。适配器可以通过这些接口列出、创建、切换和删除会话，无需单独配置管理 API。
|
||
|
||
### 认证
|
||
|
||
使用与 WebSocket 连接相同的 token：
|
||
|
||
| 方式 | 示例 |
|
||
|------|------|
|
||
| Header | `Authorization: Bearer your-secret` |
|
||
| Query 参数 | `?token=your-secret` |
|
||
|
||
### 响应格式
|
||
|
||
所有响应使用统一的信封格式：
|
||
|
||
```json
|
||
{"ok": true, "data": { ... }}
|
||
{"ok": false, "error": "错误信息"}
|
||
```
|
||
|
||
### 端点
|
||
|
||
所有端点相对于 Bridge Server 基础 URL（如 `http://localhost:9810`）。
|
||
|
||
#### GET /bridge/sessions
|
||
|
||
列出指定 session key 的所有会话。
|
||
|
||
**Query 参数：**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `session_key` | string | 是 | 要查询会话的 session key（如 `wechat:user123:user123`）。 |
|
||
|
||
**响应：**
|
||
|
||
```json
|
||
{
|
||
"ok": true,
|
||
"data": {
|
||
"sessions": [
|
||
{
|
||
"id": "s1",
|
||
"name": "default",
|
||
"history_count": 12
|
||
},
|
||
{
|
||
"id": "s2",
|
||
"name": "work",
|
||
"history_count": 5
|
||
}
|
||
],
|
||
"active_session_id": "s1"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
#### POST /bridge/sessions
|
||
|
||
创建新的命名会话。
|
||
|
||
**请求体：**
|
||
|
||
```json
|
||
{
|
||
"session_key": "wechat:user123:user123",
|
||
"name": "work"
|
||
}
|
||
```
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `session_key` | string | 是 | 用户的 session key。 |
|
||
| `name` | string | 否 | 人类可读的会话名称。默认为 `"default"`。 |
|
||
|
||
**响应：**
|
||
|
||
```json
|
||
{
|
||
"ok": true,
|
||
"data": {
|
||
"id": "s3",
|
||
"name": "work",
|
||
"message": "session created"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
#### GET /bridge/sessions/{id}
|
||
|
||
获取会话详情及消息历史。
|
||
|
||
**Query 参数：**
|
||
|
||
| 参数 | 类型 | 默认值 | 说明 |
|
||
|------|------|--------|------|
|
||
| `session_key` | string | （必填） | 用于定位项目上下文的 session key。 |
|
||
| `history_limit` | int | 50 | 返回的最大历史条数。 |
|
||
|
||
**响应：**
|
||
|
||
```json
|
||
{
|
||
"ok": true,
|
||
"data": {
|
||
"id": "s1",
|
||
"name": "default",
|
||
"history": [
|
||
{"role": "user", "content": "你好"},
|
||
{"role": "assistant", "content": "你好！有什么可以帮你的？"}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
#### DELETE /bridge/sessions/{id}
|
||
|
||
删除会话及其历史记录。
|
||
|
||
**Query 参数：**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `session_key` | string | 是 | 用于定位项目上下文的 session key。 |
|
||
|
||
**响应：**
|
||
|
||
```json
|
||
{
|
||
"ok": true,
|
||
"data": {
|
||
"message": "session deleted"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
#### POST /bridge/sessions/switch
|
||
|
||
切换指定 session key 的活跃会话。
|
||
|
||
**请求体：**
|
||
|
||
```json
|
||
{
|
||
"session_key": "wechat:user123:user123",
|
||
"target": "s2"
|
||
}
|
||
```
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `session_key` | string | 是 | Session key。 |
|
||
| `target` | string | 是 | 要切换到的会话 ID 或名称。 |
|
||
|
||
**响应：**
|
||
|
||
```json
|
||
{
|
||
"ok": true,
|
||
"data": {
|
||
"message": "session switched",
|
||
"active_session_id": "s2"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 错误处理
|
||
|
||
### 断线重连
|
||
|
||
WebSocket 连接断开时，适配器应：
|
||
|
||
1. 使用指数退避等待（起始 1 秒，最大 60 秒）。
|
||
2. 重新连接并发送新的 `register` 消息。
|
||
3. 恢复正常运行 — cc-connect 独立于连接维护会话状态。
|
||
|
||
### 消息顺序
|
||
|
||
单个 WebSocket 连接内的消息是有序的。cc-connect 按 session key 顺序处理适配器消息。
|
||
|
||
### 超时
|
||
|
||
- **Ping 间隔**：适配器应至少每 30 秒发送一次 `ping`。
|
||
- **连接超时**：cc-connect 在 90 秒没有收到 ping 后关闭空闲连接。
|
||
- **回复超时**：如果 agent 耗时过长，cc-connect 可能发送错误回复。适配器不需要特殊处理。
|
||
|
||
---
|
||
|
||
## 配置示例
|
||
|
||
```toml
|
||
[bridge]
|
||
enabled = true
|
||
port = 9810
|
||
token = "一个强随机密钥"
|
||
|
||
# 可选：限制哪些适配器可以连接（按平台名称）。
|
||
# 默认：允许所有已注册的适配器。
|
||
# allow_platforms = ["wechat", "matrix"]
|
||
```
|
||
|
||
不需要为每个适配器单独配置项目 — 适配器默认关联到**默认项目**，或在 `register` 消息中指定 `project` 字段绑定到特定项目。
|
||
|
||
---
|
||
|
||
## SDK 开发指南
|
||
|
||
开发适配器时，请遵循以下原则：
|
||
|
||
1. **保持无状态** — 适配器应该是一个轻量的协议转换层。所有会话状态存储在 cc-connect 中。
|
||
2. **处理断线重连** — 网络故障是正常的，实现指数退避重试。
|
||
3. **如实声明能力** — 只声明你的平台实际支持的能力。
|
||
4. **忠实使用 `reply_ctx`** — 始终原样回传原始消息中的 `reply_ctx`。
|
||
5. **二进制数据用 Base64** — 图片、文件和音频通过 base64 编码字符串传输。
|
||
6. **记录错误而非崩溃** — 收到未知消息类型时，记录日志并继续运行。
|
||
|
||
### 最小适配器示例（Python 伪代码）
|
||
|
||
```python
|
||
import asyncio
|
||
import json
|
||
import websockets
|
||
|
||
async def main():
|
||
uri = "ws://localhost:9810/bridge/ws?token=your-secret"
|
||
async with websockets.connect(uri) as ws:
|
||
# 1. 注册
|
||
await ws.send(json.dumps({
|
||
"type": "register",
|
||
"platform": "my-chat",
|
||
"capabilities": ["text", "buttons"]
|
||
}))
|
||
ack = json.loads(await ws.recv())
|
||
assert ack["ok"], f"注册失败: {ack['error']}"
|
||
|
||
# 2. 启动消息循环
|
||
async def recv_loop():
|
||
async for raw in ws:
|
||
msg = json.loads(raw)
|
||
if msg["type"] == "reply":
|
||
send_to_chat_platform(msg["reply_ctx"], msg["content"])
|
||
elif msg["type"] == "buttons":
|
||
send_buttons_to_chat(msg["reply_ctx"], msg["content"], msg["buttons"])
|
||
# ... 处理其他类型
|
||
|
||
async def send_loop():
|
||
while True:
|
||
chat_msg = await get_next_chat_message()
|
||
await ws.send(json.dumps({
|
||
"type": "message",
|
||
"msg_id": chat_msg.id,
|
||
"session_key": f"my-chat:{chat_msg.user_id}:{chat_msg.user_id}",
|
||
"user_id": chat_msg.user_id,
|
||
"user_name": chat_msg.user_name,
|
||
"content": chat_msg.text,
|
||
"reply_ctx": chat_msg.conversation_id
|
||
}))
|
||
|
||
await asyncio.gather(recv_loop(), send_loop())
|
||
|
||
asyncio.run(main())
|
||
```
|
||
|
||
---
|
||
|
||
## 版本管理
|
||
|
||
协议版本通过 `register` 消息的 `metadata.protocol_version` 声明。当前版本为 `1`。cc-connect 会拒绝不兼容版本的连接，并在 `register_ack` 中返回错误。
|
||
|
||
```json
|
||
{
|
||
"type": "register",
|
||
"platform": "my-chat",
|
||
"capabilities": ["text"],
|
||
"metadata": {
|
||
"protocol_version": 1
|
||
}
|
||
}
|
||
```
|