580 lines
17 KiB
Markdown
580 lines
17 KiB
Markdown
# 灵隙协议实现规范：传输模式定义
|
||
|
||
> 版本：1.0.0 | 层级：实现层
|
||
|
||
---
|
||
|
||
## 1. 传输模式枚举
|
||
|
||
传输模式（TransportMode）定义了任务通信的传输方式。Synapse 协议支持四种传输模式，适配不同的网络环境和业务场景。
|
||
|
||
### 1.1 模式定义
|
||
|
||
```go
|
||
// TransportMode 定义任务通信的传输模式
|
||
type TransportMode string
|
||
|
||
const (
|
||
// TransportModeCallback - 异步回调模式
|
||
// 任务完成后通过 Webhook 回调通知结果
|
||
TransportModeCallback TransportMode = "callback"
|
||
|
||
// TransportModePolling - 异步轮询模式
|
||
// 调用方主动轮询获取任务状态和结果
|
||
TransportModePolling TransportMode = "polling"
|
||
|
||
// TransportModeSync - 同步模式
|
||
// 调用方阻塞等待任务完成，直接返回结果
|
||
TransportModeSync TransportMode = "sync"
|
||
|
||
// TransportModeHybrid - 混合模式
|
||
// 优先使用回调，回调失败时启用轮询作为兜底
|
||
TransportModeHybrid TransportMode = "hybrid"
|
||
)
|
||
```
|
||
|
||
### 1.2 模式对比
|
||
|
||
| 模式 | 枚举值 | 通信方向 | 实时性 | 适用场景 |
|
||
|------|--------|----------|--------|----------|
|
||
| 回调（Callback） | `callback` | 服务端 → 调用方 | 高 | 网络可达、期望实时通知 |
|
||
| 轮询（Polling） | `polling` | 调用方 → 服务端 | 中 | 调用方主动拉取、服务端不主动推送 |
|
||
| 同步（Sync） | `sync` | 双向阻塞 | 最高 | 短耗时任务、需要即时响应 |
|
||
| 混合（Hybrid） | `hybrid` | 双向 + 兜底 | 高 | 生产环境、容错要求高的场景 |
|
||
|
||
### 1.3 模式选择建议
|
||
|
||
| 条件 | 推荐模式 |
|
||
|------|----------|
|
||
| 任务耗时 < 5s | `sync` — 直接同步等待 |
|
||
| 任务耗时 5s~5min，回调端点可达 | `callback` — 异步回调 |
|
||
| 任务耗时 5s~5min，回调端点不可达 | `polling` — 轮询拉取 |
|
||
| 生产环境，需要高可靠性 | `hybrid` — 回调 + 轮询兜底 |
|
||
| 任务耗时 > 5min | `polling` 或 `hybrid` — 长时间异步 |
|
||
|
||
---
|
||
|
||
## 2. 传输偏好配置
|
||
|
||
### 2.1 传输偏好结构
|
||
|
||
```go
|
||
// TransportPreferences 定义任务的传输偏好配置
|
||
type TransportPreferences struct {
|
||
// Preferred - 首选传输模式
|
||
Preferred TransportMode `json:"preferred"`
|
||
|
||
// Fallback - 兜底传输模式，当首选模式不可用时使用
|
||
Fallback TransportMode `json:"fallback,omitempty"`
|
||
|
||
// CallbackEndpoint - 回调端点 URL
|
||
// 仅当 Preferred 或 Fallback 为 callback/hybrid 时生效
|
||
CallbackEndpoint string `json:"callback_endpoint,omitempty"`
|
||
|
||
// PollingInterval - 轮询间隔（秒）
|
||
// 仅当 Preferred 或 Fallback 为 polling/hybrid 时生效
|
||
PollingInterval int `json:"polling_interval,omitempty"`
|
||
|
||
// ProgressUpdates - 是否接收进度更新
|
||
// 为 true 时，服务端会在任务执行过程中推送进度事件
|
||
ProgressUpdates bool `json:"progress_updates"`
|
||
|
||
// ProgressInterval - 进度更新最小间隔（秒）
|
||
// 控制进度通知的频率，避免频繁推送
|
||
ProgressInterval int `json:"progress_interval,omitempty"`
|
||
}
|
||
```
|
||
|
||
### 2.2 字段说明
|
||
|
||
| 字段 | 类型 | 必需 | 默认值 | 说明 |
|
||
|------|------|------|--------|------|
|
||
| `preferred` | `TransportMode` | 是 | `callback` | 首选传输模式 |
|
||
| `fallback` | `TransportMode` | 否 | `polling` | 兜底模式，首选不可用时回退 |
|
||
| `callback_endpoint` | `string` | 条件必填 | `""` | 回调 URL，callback/hybrid 模式必需 |
|
||
| `polling_interval` | `int` | 否 | `5` | 轮询间隔（秒），最小 1 |
|
||
| `progress_updates` | `bool` | 否 | `true` | 是否启用进度推送 |
|
||
| `progress_interval` | `int` | 否 | `10` | 进度更新间隔（秒） |
|
||
|
||
### 2.3 默认配置
|
||
|
||
```go
|
||
// DefaultTransportPreferences 返回默认传输偏好配置
|
||
//
|
||
// 默认值说明：
|
||
// - 首选回调模式（callback），兜底轮询（polling）
|
||
// - 轮询间隔 5 秒
|
||
// - 启用进度更新，最小间隔 10 秒
|
||
func DefaultTransportPreferences() *TransportPreferences {
|
||
return &TransportPreferences{
|
||
Preferred: TransportModeCallback,
|
||
Fallback: TransportModePolling,
|
||
PollingInterval: 5,
|
||
ProgressUpdates: true,
|
||
ProgressInterval: 10,
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2.4 配置示例
|
||
|
||
**纯回调模式：**
|
||
|
||
```go
|
||
prefs := &TransportPreferences{
|
||
Preferred: TransportModeCallback,
|
||
CallbackEndpoint: "https://my-service.com/callback",
|
||
ProgressUpdates: true,
|
||
ProgressInterval: 5,
|
||
}
|
||
```
|
||
|
||
**纯轮询模式：**
|
||
|
||
```go
|
||
prefs := &TransportPreferences{
|
||
Preferred: TransportModePolling,
|
||
PollingInterval: 3,
|
||
ProgressUpdates: false,
|
||
}
|
||
```
|
||
|
||
**混合模式（生产推荐）：**
|
||
|
||
```go
|
||
prefs := &TransportPreferences{
|
||
Preferred: TransportModeCallback,
|
||
Fallback: TransportModePolling,
|
||
CallbackEndpoint: "https://my-service.com/callback",
|
||
PollingInterval: 5,
|
||
ProgressUpdates: true,
|
||
ProgressInterval: 10,
|
||
}
|
||
```
|
||
|
||
**同步模式：**
|
||
|
||
```go
|
||
prefs := &TransportPreferences{
|
||
Preferred: TransportModeSync,
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 轮询 API 类型
|
||
|
||
轮询 API 为调用方提供主动拉取任务状态的能力。所有 Agent 端必须实现以下类型以支持轮询传输模式。
|
||
|
||
### 3.1 任务状态响应
|
||
|
||
```go
|
||
// TaskStatusResponse 任务状态轮询响应
|
||
//
|
||
// 调用方通过此结构获取单个任务的当前状态。
|
||
// 成功时 Success 为 true，Task 字段包含任务详情；
|
||
// 失败时 Success 为 false，Error 字段包含错误信息。
|
||
type TaskStatusResponse struct {
|
||
Success bool `json:"success"`
|
||
Task *TaskInfo `json:"task,omitempty"`
|
||
Error *SynapseError `json:"error,omitempty"`
|
||
}
|
||
```
|
||
|
||
### 3.2 任务信息
|
||
|
||
```go
|
||
// TaskInfo 任务详细信息
|
||
//
|
||
// 描述一个异步任务的完整状态，包括进度、结果和
|
||
// 错误信息。ETag 字段用于增量查询，避免重复传输
|
||
// 未变更的数据。
|
||
type TaskInfo struct {
|
||
// ID - 任务唯一标识
|
||
ID string `json:"id"`
|
||
|
||
// Type - 任务类型，如 "text_generation", "image_analysis"
|
||
Type string `json:"type"`
|
||
|
||
// Status - 任务状态
|
||
// 可选值: pending, running, completed, failed, cancelled
|
||
Status string `json:"status"`
|
||
|
||
// Progress - 任务进度百分比（0-100）
|
||
Progress int `json:"progress"`
|
||
|
||
// Message - 当前状态的人类可读描述
|
||
Message string `json:"message,omitempty"`
|
||
|
||
// CreatedAt - 任务创建时间
|
||
CreatedAt Timestamp `json:"created_at"`
|
||
|
||
// UpdatedAt - 任务最后更新时间
|
||
UpdatedAt Timestamp `json:"updated_at"`
|
||
|
||
// ETA - 预计完成时间（可选）
|
||
ETA *Timestamp `json:"eta,omitempty"`
|
||
|
||
// Result - 任务执行结果
|
||
// 当 Status 为 completed 时此字段有效
|
||
Result any `json:"result,omitempty"`
|
||
|
||
// Error - 任务执行错误
|
||
// 当 Status 为 failed 时此字段有效
|
||
Error *SynapseError `json:"error,omitempty"`
|
||
|
||
// ETag - 实体标签，用于增量查询和缓存
|
||
// 客户端可在后续请求中携带此值以获取变更数据
|
||
ETag string `json:"etag,omitempty"`
|
||
}
|
||
```
|
||
|
||
### 3.3 任务状态枚举
|
||
|
||
| 状态值 | 说明 | 可转换至 |
|
||
|--------|------|----------|
|
||
| `pending` | 任务已提交，等待执行 | `running` |
|
||
| `running` | 任务正在执行中 | `completed`, `failed`, `cancelled` |
|
||
| `completed` | 任务执行成功，Result 可用 | —（终态） |
|
||
| `failed` | 任务执行失败，Error 可用 | —（终态） |
|
||
| `cancelled` | 任务已被取消 | —（终态） |
|
||
|
||
### 3.4 任务列表响应
|
||
|
||
```go
|
||
// TaskListResponse 任务列表响应
|
||
//
|
||
// 支持分页查询，调用方可使用 Limit 和 Offset
|
||
// 参数控制返回结果的数量和偏移量。
|
||
type TaskListResponse struct {
|
||
Success bool `json:"success"`
|
||
Tasks []TaskInfo `json:"tasks"`
|
||
Total int `json:"total"`
|
||
Limit int `json:"limit"`
|
||
Offset int `json:"offset"`
|
||
HasMore bool `json:"has_more"`
|
||
}
|
||
```
|
||
|
||
**分页参数说明：**
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `total` | `int` | 符合条件的任务总数 |
|
||
| `limit` | `int` | 本次请求的限制数量 |
|
||
| `offset` | `int` | 本次请求的偏移量 |
|
||
| `has_more` | `bool` | 是否还有更多数据 |
|
||
|
||
### 3.5 任务事件
|
||
|
||
```go
|
||
// TaskEvent 任务事件
|
||
//
|
||
// 表示任务执行过程中产生的事件，用于事件流推送
|
||
// 和增量状态更新。
|
||
type TaskEvent struct {
|
||
// ID - 事件唯一标识
|
||
ID string `json:"id"`
|
||
|
||
// Type - 事件类型
|
||
// 可选值: status_update, progress, log, error, complete
|
||
Type string `json:"type"`
|
||
|
||
// Timestamp - 事件发生时间
|
||
Timestamp Timestamp `json:"timestamp"`
|
||
|
||
// Data - 事件数据
|
||
// 不同类型的事件携带不同的数据结构
|
||
Data any `json:"data"`
|
||
}
|
||
```
|
||
|
||
### 3.6 事件类型说明
|
||
|
||
| 事件类型 | 触发时机 | Data 内容 |
|
||
|----------|----------|-----------|
|
||
| `status_update` | 任务状态变更 | 包含新状态和状态变更原因 |
|
||
| `progress` | 进度更新 | 包含当前进度值（0-100）和描述 |
|
||
| `log` | 任务产生日志输出 | 日志文本内容 |
|
||
| `error` | 任务执行出错 | 错误代码和错误消息 |
|
||
| `complete` | 任务完成 | 任务执行结果 |
|
||
|
||
### 3.7 任务事件流响应
|
||
|
||
```go
|
||
// TaskEventsResponse 任务事件流响应
|
||
//
|
||
// 支持基于游标的分页，调用方可使用 Next 游标
|
||
// 持续拉取后续事件。
|
||
type TaskEventsResponse struct {
|
||
Success bool `json:"success"`
|
||
Since string `json:"since"`
|
||
Events []TaskEvent `json:"events"`
|
||
HasMore bool `json:"has_more"`
|
||
Next string `json:"next_cursor,omitempty"`
|
||
}
|
||
```
|
||
|
||
**游标使用流程：**
|
||
|
||
1. 首次请求不带 `since` 参数，获取当前所有事件
|
||
2. 响应中返回 `next_cursor` 作为下一页游标
|
||
3. 后续请求携带 `since=next_cursor` 获取后续事件
|
||
4. 当 `has_more` 为 `false` 时，表示已无新事件
|
||
|
||
### 3.8 轮询 API 端点约定
|
||
|
||
| 端点 | 方法 | 请求参数 | 响应类型 | 说明 |
|
||
|------|------|----------|----------|------|
|
||
| `/v1/tasks/{taskID}` | GET | — | `TaskStatusResponse` | 查询单个任务状态 |
|
||
| `/v1/tasks` | GET | `limit, offset, status` | `TaskListResponse` | 查询任务列表 |
|
||
| `/v1/tasks/{taskID}/events` | GET | `since` | `TaskEventsResponse` | 查询任务事件流 |
|
||
|
||
---
|
||
|
||
## 4. 流式传输类型
|
||
|
||
流式传输用于实时传输大文件或持续生成的数据，如音频流、视频流、长文本生成等场景。
|
||
|
||
### 4.1 流数据块
|
||
|
||
```go
|
||
// StreamChunk 流式传输数据块
|
||
//
|
||
// 每次传输一个数据块，Sequence 字段保证数据块
|
||
// 的顺序。当 Final 为 true 时，表示流传输结束，
|
||
// 客户端可开始组装完整数据。
|
||
type StreamChunk struct {
|
||
// TaskID - 任务 ID，标识所属任务
|
||
TaskID string `json:"task_id"`
|
||
|
||
// Sequence - 块序列号，从 1 开始递增
|
||
// 用于客户端排序和校验丢包
|
||
Sequence int64 `json:"sequence"`
|
||
|
||
// ChunkType - 数据块类型
|
||
// 可选值: text, binary, audio, video
|
||
ChunkType string `json:"chunk_type"`
|
||
|
||
// Data - 数据块内容
|
||
// 二进制数据使用 base64 编码传输
|
||
Data string `json:"data"`
|
||
|
||
// Final - 是否为最后一个数据块
|
||
// 为 true 时表示流传输结束
|
||
Final bool `json:"final"`
|
||
|
||
// Timestamp - 数据块时间戳
|
||
Timestamp Timestamp `json:"timestamp"`
|
||
}
|
||
```
|
||
|
||
### 4.2 数据块类型说明
|
||
|
||
| ChunkType | 说明 | Data 编码 | 适用场景 |
|
||
|-----------|------|-----------|----------|
|
||
| `text` | 文本数据 | UTF-8 字符串 | 流式文本生成、日志输出 |
|
||
| `binary` | 二进制数据 | Base64 | 文件传输、二进制协议数据 |
|
||
| `audio` | 音频数据 | Base64 | 实时语音、音频流处理 |
|
||
| `video` | 视频数据 | Base64 | 实时视频、视频流处理 |
|
||
|
||
### 4.3 流完成通知
|
||
|
||
```go
|
||
// StreamComplete 流传输完成通知
|
||
//
|
||
// 当所有数据块传输完毕后发送，包含完整数据的
|
||
// 校验和，供客户端验证数据完整性。
|
||
type StreamComplete struct {
|
||
// TaskID - 任务 ID
|
||
TaskID string `json:"task_id"`
|
||
|
||
// TotalChunks - 总数据块数
|
||
// 客户端可据此验证是否收到所有数据块
|
||
TotalChunks int64 `json:"total_chunks"`
|
||
|
||
// FullContentChecksum - 完整数据校验和
|
||
// 格式: "sha256:<hex>"，用于完整性校验
|
||
FullContentChecksum string `json:"full_content_checksum"`
|
||
|
||
// Result - 任务执行结果（可选）
|
||
// 流传输完成后携带的最终结果
|
||
Result any `json:"result,omitempty"`
|
||
}
|
||
```
|
||
|
||
### 4.4 流式传输生命周期
|
||
|
||
```
|
||
调用方 服务端
|
||
| |
|
||
|-- POST /v1/tasks/submit --->|
|
||
| (TransportMode: sync) | 启动异步任务
|
||
| |
|
||
|<--- StreamChunk{seq:1} -----| 数据块 1
|
||
|<--- StreamChunk{seq:2} -----| 数据块 2
|
||
|<--- StreamChunk{seq:3} -----| 数据块 3
|
||
|<--- StreamChunk{seq:4} -----| 数据块 4（Final=true）
|
||
|<--- StreamComplete ---------| 完成通知
|
||
| |
|
||
|
||
客户端收到 StreamComplete 后：
|
||
1. 确认 TotalChunks == 实际收到的块数
|
||
2. 计算完整数据的 SHA256 校验和
|
||
3. 对比 FullContentChecksum 验证完整性
|
||
4. 读取 Result 获取任务执行结果
|
||
```
|
||
|
||
### 4.5 校验和验证
|
||
|
||
```go
|
||
// ValidateStreamChecksum 验证流式传输数据的完整性
|
||
//
|
||
// 客户端在收到 StreamComplete 后应调用此函数
|
||
// 验证收到的数据是否完整。
|
||
func ValidateStreamChecksum(receivedChecksum, computedChecksum string) bool {
|
||
return receivedChecksum == computedChecksum
|
||
}
|
||
```
|
||
|
||
### 4.6 传输模式与流式传输的组合规则
|
||
|
||
| 传输模式 | 是否支持流式 | 说明 |
|
||
|----------|-------------|------|
|
||
| `callback` | 否 | 回调模式仅通知结果，不承载流数据 |
|
||
| `polling` | 否 | 轮询模式通过分块获取，非实时流 |
|
||
| `sync` | 是 | 同步模式下可实时流式返回数据 |
|
||
| `hybrid` | 是（回调阶段） | 混合模式中回调路径支持流式 |
|
||
|
||
---
|
||
|
||
## 5. 传输模式交互流程
|
||
|
||
### 5.1 回调模式（Callback）
|
||
|
||
```
|
||
调用方 Agent
|
||
| |
|
||
|--- SubmitTask ------------>| 提交任务
|
||
| (callback_endpoint: URL) |
|
||
| | Agent 处理任务
|
||
| |---> HTTP POST --->| 调用方回调端点
|
||
| (异步回调) |<--- 200 OK -------| 回调响应
|
||
| |
|
||
| [处理完成] |
|
||
```
|
||
|
||
### 5.2 轮询模式（Polling）
|
||
|
||
```
|
||
调用方 Agent
|
||
| |
|
||
|--- SubmitTask ------------>| 提交任务
|
||
| |
|
||
|--- GET /v1/tasks/{id} ---->| 轮询状态（间隔 5s）
|
||
|<--- TaskInfo(status=running)|
|
||
|--- GET /v1/tasks/{id} ---->|
|
||
|<--- TaskInfo(status=running)|
|
||
|--- GET /v1/tasks/{id} ---->|
|
||
|<--- TaskInfo(status=completed, result=...)
|
||
| |
|
||
```
|
||
|
||
### 5.3 同步模式（Sync）
|
||
|
||
```
|
||
调用方 Agent
|
||
| |
|
||
|--- SubmitTask + Sync ----->| 提交任务
|
||
| | Agent 立即处理
|
||
|<-- Result (同步返回) -------| 直接返回结果
|
||
| |
|
||
```
|
||
|
||
### 5.4 混合模式（Hybrid）
|
||
|
||
```
|
||
调用方 Agent
|
||
| |
|
||
|--- SubmitTask ------------>| 提交任务
|
||
| (preferred: callback, |
|
||
| fallback: polling) |
|
||
| | Agent 处理任务
|
||
| |
|
||
| [回调成功] |
|
||
|<-- AsyncCallback -----------| 回调通知结果
|
||
| |
|
||
| [回调失败] |
|
||
|--- GET /v1/tasks/{id} ---->| 轮询兜底
|
||
|<-- TaskInfo(result=...) ----| 获取结果
|
||
| |
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 错误处理
|
||
|
||
### 6.1 SynapseError 结构
|
||
|
||
```go
|
||
// SynapseError 协议错误信息
|
||
type SynapseError struct {
|
||
Code int `json:"code"`
|
||
Message string `json:"message"`
|
||
}
|
||
```
|
||
|
||
### 6.2 传输模式相关错误码
|
||
|
||
| 错误码 | 名称 | 说明 |
|
||
|--------|------|------|
|
||
| `4001` | `CALLBACK_FAILED` | 回调端点不可达或返回非 2xx |
|
||
| `4002` | `POLLING_TIMEOUT` | 轮询超时，任务未在预期时间内完成 |
|
||
| `4003` | `INVALID_CALLBACK_ENDPOINT` | 回调端点 URL 格式无效 |
|
||
| `4004` | `MODE_NOT_SUPPORTED` | Agent 不支持请求的传输模式 |
|
||
| `4005` | `STREAM_SEQUENCE_GAP` | 流式传输出现序列号跳变 |
|
||
|
||
---
|
||
|
||
## 附录：Go 类型汇总
|
||
|
||
```go
|
||
// 传输模式枚举
|
||
type TransportMode string
|
||
const (
|
||
TransportModeCallback TransportMode = "callback"
|
||
TransportModePolling TransportMode = "polling"
|
||
TransportModeSync TransportMode = "sync"
|
||
TransportModeHybrid TransportMode = "hybrid"
|
||
)
|
||
|
||
// 传输偏好配置
|
||
type TransportPreferences struct {
|
||
Preferred TransportMode `json:"preferred"`
|
||
Fallback TransportMode `json:"fallback,omitempty"`
|
||
CallbackEndpoint string `json:"callback_endpoint,omitempty"`
|
||
PollingInterval int `json:"polling_interval,omitempty"`
|
||
ProgressUpdates bool `json:"progress_updates"`
|
||
ProgressInterval int `json:"progress_interval,omitempty"`
|
||
}
|
||
|
||
func DefaultTransportPreferences() *TransportPreferences { ... }
|
||
|
||
// 轮询 API 类型
|
||
type TaskStatusResponse struct { ... }
|
||
type TaskInfo struct { ... }
|
||
type TaskListResponse struct { ... }
|
||
type TaskEvent struct { ... }
|
||
type TaskEventsResponse struct { ... }
|
||
|
||
// 流式传输类型
|
||
type StreamChunk struct { ... }
|
||
type StreamComplete struct { ... }
|
||
```
|
||
|
||
---
|
||
|
||
> 本文档对应代码实现在 [types/content.go](file:///e:/code/go/synapse/types/content.go) 中。
|
||
>
|
||
> 参考源文档：[06-implementation-details.md §8](file:///e:/code/go/synapse/docs/v0/06-implementation-details.md#L1144)
|