1307 lines
43 KiB
Markdown
1307 lines
43 KiB
Markdown
# 灵隙 Synapse 协议实现细节文档
|
||
|
||
> 本文档描述 Synapse 协议栈的具体实现规范，作为核心协议文档的补充。
|
||
>
|
||
> 版本：1.0.0 | 更新日期：2026-06-27
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
1. [七大组件层详细规范](#1-七大组件层详细规范)
|
||
2. [内容类型系统](#2-内容类型系统)
|
||
3. [能力声明系统](#3-能力声明系统)
|
||
4. [gRPC 传输协议](#4-grpc-传输协议)
|
||
5. [人工介入（HiL）三级升级机制](#5-人工介入hil三级升级机制)
|
||
6. [数字分段错误码系统](#6-数字分段错误码系统)
|
||
7. [消息扩展字段](#7-消息扩展字段)
|
||
8. [传输模式定义](#8-传输模式定义)
|
||
|
||
---
|
||
|
||
## 1. 七大组件层详细规范
|
||
|
||
灵隙协议栈的七大组件层构成了协议的核心基础设施。每层都有独立的职责和接口。
|
||
|
||
### 1.1 灵脉 Meridian - 寻址与路由层
|
||
|
||
**定位**：Agent 之间虽有空隙（灵隙），但暗中有能量流动的轨迹（脉）。此层负责维护全局路由表。
|
||
|
||
**核心功能**：
|
||
|
||
| 功能 | 方法 | 说明 |
|
||
|-----|------|------|
|
||
| Agent 注册 | `Register(endpoint)` | Agent "通脉"入网 |
|
||
| Agent 注销 | `Unregister(agentID)` | Agent "断脉"离场 |
|
||
| Agent 查询 | `GetAgent(agentID)` | 获取 Agent 端点信息 |
|
||
| Agent 列表 | `ListAgents()` | 列出所有活跃 Agent |
|
||
| 心跳保活 | `Heartbeat(agentID)` | 刷新 Agent TTL |
|
||
| 按能力查找 | `FindByCapability(capability)` | 查找具备特定能力的 Agent |
|
||
|
||
**数据结构**：
|
||
|
||
```go
|
||
// AgentEndpoint - Agent 端点信息
|
||
type AgentEndpoint struct {
|
||
AgentID string // Agent 唯一标识
|
||
AgentName string // Agent 名称
|
||
SystemID string // 所属系统 ID
|
||
Endpoint string // 回调端点 URL
|
||
Version string // Agent 版本
|
||
Capabilities []string // 能力标签列表
|
||
Metadata map[string]interface{} // 扩展元数据
|
||
}
|
||
|
||
// RegistryConfig - 注册表配置
|
||
type RegistryConfig struct {
|
||
DefaultTTL time.Duration // 默认存活时间（5分钟）
|
||
}
|
||
```
|
||
|
||
**拓扑管理**：
|
||
|
||
```go
|
||
// 拓扑类型
|
||
type TopologyType string
|
||
const (
|
||
TopologyStar = "star" // 星型拓扑（中心协调）
|
||
TopologyMesh = "mesh" // 网状拓扑（全互联）
|
||
TopologyRing = "ring" // 环形拓扑（环形传递）
|
||
TopologyTree = "tree" // 树形拓扑（层级管理）
|
||
TopologyHybrid = "hybrid" // 混合拓扑
|
||
)
|
||
|
||
// 拓扑管理接口
|
||
type TopologyManager interface {
|
||
CreateTopology(id, name string, topologyType TopologyType) *NetworkTopology
|
||
AddNode(topologyID, nodeID string) error
|
||
AddEdge(topologyID, from, to string) error
|
||
GetNeighbors(topologyID, nodeID string) ([]string, error)
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 1.2 灵玺 Sigil - 身份与凭证层
|
||
|
||
**定位**：皇帝的玉玺是最高凭证。每个 Agent 的初始身份都需经过"铸玺"过程，每一次交互都要"验玺"。
|
||
|
||
**核心功能**：
|
||
|
||
| 功能 | 方法 | 说明 |
|
||
|-----|------|------|
|
||
| 创建身份 | `CreateIdentity(agentID, ...)` | "铸玺" - 创建身份凭证 |
|
||
| 获取身份 | `GetIdentity(agentID)` | 获取 Agent 身份信息 |
|
||
| 撤销身份 | `RevokeIdentity(agentID)` | "废玺" - 撤销身份 |
|
||
| 检查撤销 | `IsRevoked(agentID)` | 检查身份是否已撤销 |
|
||
| 签名消息 | `SignMessage(msg)` | 对消息签名 |
|
||
| 验证签名 | `VerifySignature(msg)` | 验证消息签名 |
|
||
| 颁发令牌 | `IssueToken(agentID, ...)` | 颁发认证令牌 |
|
||
| 验证令牌 | `ValidateToken(signedToken)` | 验证令牌有效性 |
|
||
|
||
**身份结构**：
|
||
|
||
```go
|
||
// AgentIdentity - Agent 身份凭证
|
||
type AgentIdentity struct {
|
||
AgentID string // Agent 唯一标识
|
||
AgentName string // Agent 名称
|
||
SystemID string // 所属系统 ID
|
||
PublicKey string // 公钥（可选）
|
||
PrivateKey string // 私钥（本地保存）
|
||
AuthSecret string // HMAC 密钥
|
||
Roles []string // 角色列表
|
||
Permissions []string // 权限列表
|
||
CreatedAt time.Time // 创建时间
|
||
ExpiresAt *time.Time // 过期时间
|
||
RevokedAt *time.Time // 撤销时间
|
||
}
|
||
|
||
// AuthToken - 认证令牌
|
||
type AuthToken struct {
|
||
TokenID string // 令牌 ID
|
||
AgentID string // 所属 Agent
|
||
SystemID string // 所属系统
|
||
Roles []string // 角色列表
|
||
IssuedAt time.Time // 颁发时间
|
||
ExpiresAt time.Time // 过期时间
|
||
}
|
||
```
|
||
|
||
**签名算法**：
|
||
|
||
```go
|
||
// 支持的签名算法
|
||
type SignatureAlgorithm string
|
||
const (
|
||
AlgHMACSHA256 SignatureAlgorithm = "HMAC-SHA256" // 默认
|
||
AlgHMACSHA512 SignatureAlgorithm = "HMAC-SHA512" // 可选
|
||
)
|
||
|
||
// 签名内容格式
|
||
// signature_content = sender_id | receiver_id | timestamp | payload_json
|
||
```
|
||
|
||
---
|
||
|
||
### 1.3 灵鉴 Speculum - 共识与裁决层
|
||
|
||
**定位**：古有"以史为鉴"，今有"以智为鉴"。此层通过对比推理链的严密性来达成共识，如青天明镜。
|
||
|
||
**核心功能**：
|
||
|
||
| 功能 | 方法 | 说明 |
|
||
|-----|------|------|
|
||
| 发起投票 | `InitiateVote(...)` | 创建投票议题 |
|
||
| 提交投票 | `SubmitVote(voteID, voterID, optionID, reasoning)` | 提交投票 |
|
||
| 关闭投票 | `CloseVote(voteID)` | 关闭并统计结果 |
|
||
| 获取投票 | `GetVote(voteID)` | 获取投票信息 |
|
||
| 仲裁争议 | `Arbitrate(ctx, dispute)` | 仲裁争议 |
|
||
| 提交推理链 | `SubmitReasoning(chain)` | 提交推理链到镜面 |
|
||
| 比较推理链 | `CompareReasonings(chainIDs)` | 比较推理链严密性 |
|
||
|
||
**共识类型**：
|
||
|
||
```go
|
||
type ConsensusType string
|
||
const (
|
||
ConsensusMajority = "majority" // 多数投票（>50%）
|
||
ConsensusSupermajority = "supermajority" // 绝对多数（>67%）
|
||
ConsensusUnanimity = "unanimity" // 一致同意（100%）
|
||
ConsensusWeighted = "weighted" // 加权投票
|
||
ConsensusRanked = "ranked" // 排序投票
|
||
)
|
||
```
|
||
|
||
**投票结构**：
|
||
|
||
```go
|
||
// Vote - 投票
|
||
type Vote struct {
|
||
VoteID string // 投票 ID
|
||
Question string // 投票问题
|
||
Options []VoteOption // 投票选项
|
||
Type ConsensusType // 共识类型
|
||
Initiator string // 发起者
|
||
Participants []string // 参与者列表
|
||
Votes map[string]string // voter_id -> option_id
|
||
Weights map[string]float64 // voter_id -> 权重
|
||
Status VoteStatus // 投票状态
|
||
Deadline time.Time // 截止时间
|
||
Result *VoteResult // 投票结果
|
||
Reasoning map[string]string // voter_id -> 推理理由
|
||
}
|
||
|
||
// VoteResult - 投票结果
|
||
type VoteResult struct {
|
||
Winner string // 获胜选项
|
||
WinOption VoteOption // 获胜选项详情
|
||
VoteCounts map[string]int // 选项 -> 票数
|
||
Passed bool // 是否通过
|
||
Margin float64 // 得票率
|
||
}
|
||
```
|
||
|
||
**推理镜面**：
|
||
|
||
```go
|
||
// ReasoningChain - 推理链
|
||
type ReasoningChain struct {
|
||
ChainID string // 推理链 ID
|
||
AgentID string // Agent ID
|
||
Topic string // 推理主题
|
||
Steps []ReasoningStep // 推理步骤
|
||
Score float64 // 推理得分
|
||
SubmittedAt time.Time // 提交时间
|
||
}
|
||
|
||
// ReasoningStep - 推理步骤
|
||
type ReasoningStep struct {
|
||
StepID string // 步骤 ID
|
||
Description string // 步骤描述
|
||
Evidence []string // 证据列表
|
||
Confidence float64 // 置信度（0-1）
|
||
Next []string // 下一步 ID 列表
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 1.4 灵泊 Harbor - 异步队列与暂存层
|
||
|
||
**定位**："泊"为船舶停靠。数据包遇风浪（网络抖动）时暂泊于此，待风平浪静再启航。
|
||
|
||
**核心功能**：
|
||
|
||
| 功能 | 方法 | 说明 |
|
||
|-----|------|------|
|
||
| 消息入队 | `Enqueue(msg, target, priority)` | 消息入队（支持优先级） |
|
||
| 消息出队 | `Dequeue()` | 消息出队 |
|
||
| 标记送达 | `MarkDelivered(msgID)` | 标记消息已送达 |
|
||
| 标记失败 | `MarkFailed(msgID, err)` | 标记消息失败（触发重试） |
|
||
| 缓冲消息 | `BufferMessage(agentID, msg)` | 为离线 Agent 缓冲消息 |
|
||
| 清空缓冲 | `FlushBuffer(agentID)` | Agent 上线后清空缓冲 |
|
||
| 添加重试 | `AddRetry(msg, target)` | 添加重试条目 |
|
||
|
||
**队列配置**：
|
||
|
||
```go
|
||
// QueueConfig - 队列配置
|
||
type QueueConfig struct {
|
||
MaxSize int // 最大队列大小（10000）
|
||
DefaultMaxRetries int // 默认最大重试次数（5）
|
||
DefaultRetryDelay time.Duration // 默认重试延迟（30s）
|
||
}
|
||
|
||
// 队列消息状态
|
||
type QueuedStatus string
|
||
const (
|
||
QueuedPending = "pending" // 待处理
|
||
QueuedProcessing = "processing" // 处理中
|
||
QueuedDelivered = "delivered" // 已送达
|
||
QueuedFailed = "failed" // 失败
|
||
QueuedDead = "dead" // 死信
|
||
)
|
||
```
|
||
|
||
**重试机制**：
|
||
|
||
```go
|
||
// RetryConfig - 重试配置
|
||
type RetryConfig struct {
|
||
MaxRetries int // 最大重试次数（5）
|
||
BaseDelay time.Duration // 基础延迟（1s）
|
||
MaxDelay time.Duration // 最大延迟（5min）
|
||
JitterFactor float64 // 抖动因子（0.1）
|
||
}
|
||
|
||
// 重试延迟算法：指数退避 + 抖动
|
||
// delay = min(BaseDelay * 2^(retryCount-1), MaxDelay) * (1 ± JitterFactor)
|
||
```
|
||
|
||
**缓冲配置**：
|
||
|
||
```go
|
||
// BufferConfig - 缓冲配置
|
||
type BufferConfig struct {
|
||
MaxPerAgent int // 每个 Agent 最大缓冲数（1000）
|
||
MaxAge time.Duration // 消息最大存活时间（24h）
|
||
CleanupInterval time.Duration // 清理间隔（1h）
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 1.5 灵瞰 Panorama - 可观测与度量层
|
||
|
||
**定位**：居高临下，俯瞰全局。如"天眼"般记录每一帧交互的耗时、置信度与资源消耗。
|
||
|
||
**核心功能**：
|
||
|
||
| 功能 | 方法 | 说明 |
|
||
|-----|------|------|
|
||
| 开始追踪 | `StartTrace(traceID, name, agentID)` | 创建追踪链路 |
|
||
| 开始跨度 | `StartSpan(traceID, parentSpanID, name, agentID)` | 创建子跨度 |
|
||
| 结束跨度 | `EndSpan(traceID, spanID, status, err)` | 结束跨度 |
|
||
| 添加日志 | `AddSpanLog(traceID, spanID, message, fields)` | 添加跨度日志 |
|
||
| 记录指标 | `RecordMetric(name, type, value, labels)` | 记录指标 |
|
||
| 递增计数 | `IncrementCounter(name, labels, delta)` | 递增计数器 |
|
||
| 设置计量 | `SetGauge(name, labels, value)` | 设置计量值 |
|
||
| 健康检查 | `CheckAll(ctx)` | 检查所有组件健康状态 |
|
||
|
||
**追踪结构**：
|
||
|
||
```go
|
||
// Trace - 追踪链路
|
||
type Trace struct {
|
||
TraceID string // 追踪 ID
|
||
RootSpan *Span // 根跨度
|
||
Spans map[string]*Span // 跨度集合
|
||
StartTime time.Time // 开始时间
|
||
EndTime *time.Time // 结束时间
|
||
Metadata map[string]interface{} // 元数据
|
||
}
|
||
|
||
// Span - 追踪跨度
|
||
type Span struct {
|
||
SpanID string // 跨度 ID
|
||
TraceID string // 所属追踪 ID
|
||
ParentID string // 父跨度 ID
|
||
Name string // 跨度名称
|
||
Service string // 服务名
|
||
AgentID string // Agent ID
|
||
StartTime time.Time // 开始时间
|
||
EndTime *time.Time // 结束时间
|
||
Duration time.Duration // 持续时间
|
||
Status SpanStatus // 跨度状态
|
||
Tags map[string]string // 标签
|
||
Logs []SpanLog // 日志
|
||
Attributes map[string]interface{} // 属性
|
||
}
|
||
|
||
// SpanStatus - 跨度状态
|
||
type SpanStatus string
|
||
const (
|
||
SpanStatusPending = "pending" // 待定
|
||
SpanStatusRunning = "running" // 运行中
|
||
SpanStatusSuccess = "success" // 成功
|
||
SpanStatusFailed = "failed" // 失败
|
||
SpanStatusCancelled = "cancelled" // 已取消
|
||
)
|
||
```
|
||
|
||
**指标类型**：
|
||
|
||
```go
|
||
type MetricType string
|
||
const (
|
||
MetricCounter = "counter" // 计数器（累加）
|
||
MetricGauge = "gauge" // 计量器（瞬时值）
|
||
MetricHistogram = "histogram" // 直方图（分布）
|
||
)
|
||
```
|
||
|
||
**健康状态**：
|
||
|
||
```go
|
||
type HealthStatus string
|
||
const (
|
||
HealthStatusHealthy = "healthy" // 健康
|
||
HealthStatusDegraded = "degraded" // 降级
|
||
HealthStatusUnhealthy = "unhealthy" // 不健康
|
||
HealthStatusUnknown = "unknown" // 未知
|
||
)
|
||
```
|
||
|
||
---
|
||
|
||
### 1.6 灵衡 Libra - 价值结算与激励层
|
||
|
||
**定位**：权衡利弊，计量公平。将 Agent 间的"智力贡献"与"资源消耗"通证化，动态定价。
|
||
|
||
**核心功能**：
|
||
|
||
| 功能 | 方法 | 说明 |
|
||
|-----|------|------|
|
||
| 创建账户 | `CreateAccount(agentID)` | 为 Agent 创建账户 |
|
||
| 获取余额 | `GetBalance(agentID)` | 查询账户余额 |
|
||
| 转账 | `Transfer(from, to, amount, ...)` | 执行转账 |
|
||
| 设置价格 | `SetPrice(taskType, capability, price)` | 设置任务价格 |
|
||
| 获取价格 | `GetPrice(taskType)` | 获取任务价格 |
|
||
| 计算成本 | `CalculateCost(taskType, complexity, duration)` | 计算任务成本 |
|
||
| 结算任务 | `SettleTask(taskID, ...)` | 结算单个任务 |
|
||
| 结算群组任务 | `SettleGroupTask(taskID, ...)` | 结算群组任务（分摊费用） |
|
||
| 奖励 | `Reward(agentID, amount, reason)` | 发放奖励 |
|
||
|
||
**账户与交易**：
|
||
|
||
```go
|
||
// Account - 账户
|
||
type Account struct {
|
||
AgentID string // Agent ID
|
||
Balance map[string]float64 // 余额（currency -> amount）
|
||
CreatedAt time.Time // 创建时间
|
||
Metadata map[string]interface{} // 元数据
|
||
}
|
||
|
||
// Transaction - 交易记录
|
||
type Transaction struct {
|
||
TxID string // 交易 ID
|
||
Type TransactionType // 交易类型
|
||
FromAgentID string // 发送方
|
||
ToAgentID string // 接收方
|
||
Amount float64 // 金额
|
||
Currency string // 货币（"SYN"）
|
||
Description string // 描述
|
||
TaskID string // 关联任务 ID
|
||
Timestamp time.Time // 时间戳
|
||
Status TransactionStatus // 交易状态
|
||
}
|
||
|
||
// TransactionType - 交易类型
|
||
type TransactionType string
|
||
const (
|
||
TxTaskExecution = "task_execution" // 任务执行
|
||
TxDataSharing = "data_sharing" // 数据共享
|
||
TxAPIInvocation = "api_invocation" // API 调用
|
||
TxGroupContribution = "group_contribution" // 群组贡献
|
||
TxDeposit = "deposit" // 充值
|
||
TxWithdraw = "withdraw" // 提现
|
||
TxReward = "reward" // 奖励
|
||
TxPenalty = "penalty" // 惩罚
|
||
)
|
||
```
|
||
|
||
**定价规则**：
|
||
|
||
```go
|
||
// 基础价格（默认）
|
||
var BasePrice = map[string]float64{
|
||
"text_generation": 1.0,
|
||
"image_generation": 5.0,
|
||
"video_generation": 20.0,
|
||
"audio_generation": 3.0,
|
||
"analysis": 2.0,
|
||
"translation": 1.5,
|
||
}
|
||
|
||
// 成本计算公式
|
||
// cost = basePrice * complexityFactor + durationFactor
|
||
// complexityFactor = complexity * 0.5
|
||
// durationFactor = duration_seconds * 0.01
|
||
```
|
||
|
||
---
|
||
|
||
### 1.7 灵枢 Pivot - 紧急制动与治理层
|
||
|
||
**定位**：取自《灵枢经》。这是整个协议的"总闸"与"方向盘"，不轻易触发，但触发时能以最小代价重置网络状态。
|
||
|
||
**核心功能**：
|
||
|
||
| 功能 | 方法 | 说明 |
|
||
|-----|------|------|
|
||
| 允许请求 | `Allow()` | 检查熔断器是否允许请求 |
|
||
| 记录成功 | `RecordSuccess()` | 记录成功（用于恢复） |
|
||
| 记录失败 | `RecordFailure()` | 记录失败（触发熔断） |
|
||
| 获取状态 | `State()` | 获取熔断器状态 |
|
||
| 重置 | `Reset()` | 重置熔断器 |
|
||
| 设置治理级别 | `SetLevel(level)` | 设置治理级别 |
|
||
| 封禁 Agent | `BanAgent(agentID, reason)` | 封禁 Agent |
|
||
| 解封 Agent | `UnbanAgent(agentID)` | 解封 Agent |
|
||
| 紧急停止 | `EmergencyStop(reason)` | 一键熔断所有 |
|
||
| 恢复正常 | `Resume()` | 恢复正常模式 |
|
||
| 应用升级 | `ApplyUpgrade(version)` | 应用协议升级 |
|
||
| 回滚升级 | `RollbackUpgrade(version)` | 回滚协议升级 |
|
||
|
||
**熔断器**：
|
||
|
||
```go
|
||
// CircuitBreaker - 熔断器
|
||
type CircuitBreaker struct {
|
||
name string // 熔断器名称
|
||
state CircuitState // 状态
|
||
failureCount int // 失败计数
|
||
successCount int // 成功计数（半开状态）
|
||
threshold int // 失败阈值（5）
|
||
timeout time.Duration // 熔断超时（30s）
|
||
}
|
||
|
||
// CircuitState - 熔断器状态
|
||
type CircuitState string
|
||
const (
|
||
CircuitClosed = "closed" // 关闭：正常流通
|
||
CircuitOpen = "open" // 打开：熔断，拒绝请求
|
||
CircuitHalfOpen = "half_open" // 半开：尝试恢复
|
||
)
|
||
|
||
// 状态转换规则：
|
||
// Closed -> Open：失败次数 >= threshold
|
||
// Open -> HalfOpen：超过 timeout 时间
|
||
// HalfOpen -> Closed：连续成功 3 次
|
||
// HalfOpen -> Open：再次失败
|
||
```
|
||
|
||
**治理级别**：
|
||
|
||
```go
|
||
type GovernanceLevel int
|
||
const (
|
||
GovLevelNormal = iota // 正常运行
|
||
GovLevelWatch // 观察模式（记录但不限制）
|
||
GovLevelRestricted // 受限模式（限流）
|
||
GovLevelEmergency // 紧急模式（仅白名单）
|
||
GovLevelShutdown // 停机模式（全部拒绝）
|
||
)
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 内容类型系统
|
||
|
||
Synapse 协议支持多种内容类型的传输，适用于不同场景的数据交互。
|
||
|
||
### 2.1 传输模式
|
||
|
||
```go
|
||
type TransferMode string
|
||
const (
|
||
TransferInline = "inline" // 内嵌传输（base64 编码）
|
||
TransferURL = "url" // URL 引用传输
|
||
TransferStreaming = "streaming" // 流式传输
|
||
TransferMultipart = "multipart" // Multipart 表单传输
|
||
)
|
||
|
||
// 文件大小阈值判断
|
||
// size <= 1MB → inline
|
||
// size > 1MB → url 或 streaming
|
||
```
|
||
|
||
### 2.2 内容编码
|
||
|
||
```go
|
||
type ContentEncoding string
|
||
const (
|
||
EncodingNone = "none" // 无编码
|
||
EncodingBase64 = "base64" // Base64 编码
|
||
EncodingGzip = "gzip" // Gzip 压缩
|
||
EncodingDeflate = "deflate" // Deflate 压缩
|
||
)
|
||
```
|
||
|
||
### 2.3 内容类型定义
|
||
|
||
**文本内容**：
|
||
|
||
```go
|
||
type TextContent struct {
|
||
ContentBase
|
||
Charset string `json:"charset"` // 字符集（"utf-8"）
|
||
Language string `json:"language,omitempty"` // 语言
|
||
Data string `json:"data"` // 文本数据
|
||
}
|
||
```
|
||
|
||
**JSON 内容**：
|
||
|
||
```go
|
||
type JSONContent struct {
|
||
ContentBase
|
||
Schema string `json:"schema,omitempty"` // Schema 标识
|
||
SchemaURL string `json:"schema_url,omitempty"` // Schema URL
|
||
Data any `json:"data"` // JSON 数据
|
||
}
|
||
```
|
||
|
||
**代码内容**：
|
||
|
||
```go
|
||
type CodeContent struct {
|
||
ContentBase
|
||
Language string `json:"language"` // 编程语言
|
||
Version string `json:"version,omitempty"` // 语言版本
|
||
Dependencies []string `json:"dependencies,omitempty"` // 依赖列表
|
||
Data string `json:"data"` // 代码内容
|
||
}
|
||
```
|
||
|
||
**文件内容**：
|
||
|
||
```go
|
||
type FileContent struct {
|
||
ContentBase
|
||
Name string `json:"name"` // 文件名
|
||
Role string `json:"role,omitempty"` // 角色（"reference", "result", "attachment"）
|
||
Description string `json:"description,omitempty"` // 描述
|
||
|
||
// Inline 传输
|
||
Data string `json:"data,omitempty"` // base64 编码
|
||
|
||
// URL 传输
|
||
URL string `json:"url,omitempty"` // URL
|
||
URLExpiresAt *Timestamp `json:"url_expires_at,omitempty"` // 过期时间
|
||
DownloadMethod string `json:"download_method,omitempty"` // GET/POST/signed_url
|
||
RangeSupported bool `json:"range_supported,omitempty"` // 是否支持范围请求
|
||
|
||
// 元数据
|
||
Width int `json:"width,omitempty"` // 宽度（图片/视频）
|
||
Height int `json:"height,omitempty"` // 高度
|
||
Duration float64 `json:"duration,omitempty"` // 时长（音视频）
|
||
Resolution string `json:"resolution,omitempty"` // 分辨率
|
||
ThumbnailURL string `json:"thumbnail_url,omitempty"` // 缩略图 URL
|
||
}
|
||
```
|
||
|
||
**内容包（多文件）**：
|
||
|
||
```go
|
||
type ContentBundle struct {
|
||
ID string `json:"id"` // 包 ID
|
||
Name string `json:"name,omitempty"` // 包名
|
||
Description string `json:"description,omitempty"` // 描述
|
||
Items []ContentBundleItem `json:"items"` // 内容项列表
|
||
TotalSize int64 `json:"total_size,omitempty"` // 总大小
|
||
CreatedAt Timestamp `json:"created_at"` // 创建时间
|
||
}
|
||
|
||
type ContentBundleItem struct {
|
||
ID string `json:"id"` // 项 ID
|
||
Role string `json:"role"` // 角色（main, reference, attachment, thumbnail）
|
||
Content any `json:"content"` // 内容对象
|
||
}
|
||
```
|
||
|
||
### 2.4 MIME 类型常量
|
||
|
||
```go
|
||
const (
|
||
MIMEJSON = "application/json"
|
||
MIMETextPlain = "text/plain"
|
||
MIMETextMarkdown = "text/markdown"
|
||
MIMETextHTML = "text/html"
|
||
MIMETextCSV = "text/csv"
|
||
MIMEImageJPEG = "image/jpeg"
|
||
MIMEImagePNG = "image/png"
|
||
MIMEImageWebP = "image/webp"
|
||
MIMEImageGIF = "image/gif"
|
||
MIMEImageSVG = "image/svg+xml"
|
||
MIMEVideoMP4 = "video/mp4"
|
||
MIMEVideoWebM = "video/webm"
|
||
MIMEAudioMP3 = "audio/mpeg"
|
||
MIMEAudioWAV = "audio/wav"
|
||
MIMEAudioAAC = "audio/aac"
|
||
MIMEPDF = "application/pdf"
|
||
MIMEOctetStream = "application/octet-stream"
|
||
MIMEMultipartForm = "multipart/form-data"
|
||
)
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 能力声明系统
|
||
|
||
每个 Agent 必须实现 `CapabilitiesProvider` 接口，以便其他 Agent 查询其能力。
|
||
|
||
### 3.1 核心接口
|
||
|
||
```go
|
||
type CapabilitiesProvider interface {
|
||
GetCapabilities(ctx context.Context) (*AgentCapabilities, error)
|
||
GetSupportedInterfaces() []ImplementedInterface
|
||
GetTaskTypeCapabilities(taskType string) (*SupportedTaskType, error)
|
||
}
|
||
```
|
||
|
||
### 3.2 能力描述结构
|
||
|
||
```go
|
||
type AgentCapabilities struct {
|
||
AgentID string `json:"agent_id"`
|
||
AgentName string `json:"agent_name"`
|
||
SystemID string `json:"system_id"`
|
||
ProtocolVersion string `json:"protocol_version"`
|
||
|
||
SupportedTaskTypes []SupportedTaskType `json:"supported_task_types"`
|
||
SupportedContentTypes []string `json:"supported_content_types"`
|
||
SupportedTransportModes []TransportMode `json:"supported_transport_modes"`
|
||
|
||
// 限制
|
||
MaxFileSize int64 `json:"max_file_size"`
|
||
MaxConcurrentTasks int `json:"max_concurrent_tasks"`
|
||
MaxTaskDuration int `json:"max_task_duration_seconds"`
|
||
|
||
// 特性支持
|
||
SupportProgressUpdates bool `json:"support_progress_updates"`
|
||
SupportStreaming bool `json:"support_streaming"`
|
||
SupportHiL bool `json:"support_hil"`
|
||
SupportGroups bool `json:"support_groups"`
|
||
}
|
||
|
||
type SupportedTaskType struct {
|
||
Type string `json:"type"`
|
||
Name string `json:"name"`
|
||
Description string `json:"description"`
|
||
EstimatedTime string `json:"estimated_time"` // 如 "30s-2min"
|
||
InputSchema string `json:"input_schema,omitempty"`
|
||
OutputSchema string `json:"output_schema,omitempty"`
|
||
Capabilities []string `json:"capabilities,omitempty"`
|
||
}
|
||
```
|
||
|
||
### 3.3 接口分类与合规级别
|
||
|
||
**接口分类**：
|
||
|
||
```go
|
||
type InterfaceCategory string
|
||
const (
|
||
CategoryCore = "core" // 核心接口（身份、消息处理）
|
||
CategoryP2P = "p2p" // P2P 接口（任务处理、回调）
|
||
CategoryGroup = "group" // 群组接口（子任务、投票）
|
||
CategoryHiL = "hil" // HiL 接口（人工决策、升级）
|
||
CategoryTransport = "transport" // 传输接口（HTTP、流式）
|
||
CategorySecurity = "security" // 安全接口（认证、幂等）
|
||
CategoryManagement = "management" // 管理接口（配置、监控）
|
||
)
|
||
```
|
||
|
||
**合规级别**：
|
||
|
||
```go
|
||
// basic：必须实现
|
||
// complete：推荐实现
|
||
// advanced：可选实现
|
||
|
||
const (
|
||
ComplianceBasic = "basic"
|
||
ComplianceComplete = "complete"
|
||
ComplianceAdvanced = "advanced"
|
||
)
|
||
```
|
||
|
||
### 3.4 标准接口注册表
|
||
|
||
系统预定义的标准接口列表（详见 `capabilities/provider.go`）：
|
||
|
||
| 接口名 | 分类 | 合规级别 | 说明 |
|
||
|------|------|---------|------|
|
||
| AgentIdentity | core | basic | Agent 身份信息 |
|
||
| MessageHandler | core | basic | 消息处理 |
|
||
| CapabilitiesProvider | core | basic | 能力声明 |
|
||
| P2PTaskHandler | p2p | basic | P2P 任务处理 |
|
||
| CallbackSender | p2p | complete | 回调发送 |
|
||
| CallbackReceiver | p2p | basic | 回调接收端点 |
|
||
| TaskStatusProvider | p2p | complete | 任务状态查询 |
|
||
| GroupTaskHandler | group | advanced | 群组任务处理 |
|
||
| GroupManager | group | advanced | 群组管理 |
|
||
| VotingHandler | group | advanced | 投票处理 |
|
||
| HILHandler | hil | complete | HiL 决策处理 |
|
||
| EscalationHandler | hil | advanced | 升级处理 |
|
||
| HTTPTransport | transport | basic | HTTP 传输 |
|
||
| MultipartTransport | transport | complete | Multipart 文件传输 |
|
||
| HybridTransport | transport | complete | 混合传输（回调+轮询） |
|
||
| StreamingTransport | transport | advanced | 流式传输 |
|
||
| Authenticator | security | basic | 认证签名 |
|
||
| IdempotencyHandler | security | basic | 幂等性处理 |
|
||
|
||
---
|
||
|
||
## 4. gRPC 传输协议
|
||
|
||
Synapse 协议支持 HTTP REST 和 gRPC 双传输模式，通过 gRPC Gateway 实现 HTTP/gRPC 双端点。
|
||
|
||
### 4.1 Proto 定义位置
|
||
|
||
```
|
||
proto/synapse.proto
|
||
```
|
||
|
||
### 4.2 服务定义
|
||
|
||
**任务服务 TaskService**：
|
||
|
||
```protobuf
|
||
service TaskService {
|
||
rpc SubmitTask(SubmitTaskRequest) returns (SubmitTaskResponse);
|
||
rpc SubmitTaskWithFiles(SubmitTaskWithFilesRequest) returns (SubmitTaskResponse);
|
||
rpc GetTask(GetTaskRequest) returns (TaskStatusResponse);
|
||
rpc GetTaskStatus(GetTaskRequest) returns (TaskStatusResponse);
|
||
rpc ListTasks(ListTasksRequest) returns (ListTasksResponse);
|
||
rpc CancelTask(CancelTaskRequest) returns (CancelTaskResponse);
|
||
rpc StreamTaskStatus(stream TaskStatusStreamRequest) returns (stream TaskStatusUpdate);
|
||
}
|
||
```
|
||
|
||
**消息服务 SynapseMessageService**：
|
||
|
||
```protobuf
|
||
service SynapseMessageService {
|
||
rpc SendMessage(SendMessageRequest) returns (SendMessageResponse);
|
||
rpc StreamMessages(stream SynapseMessage) returns (stream SynapseMessage);
|
||
rpc ReceiveCallback(google.protobuf.Empty) returns (stream SynapseMessage);
|
||
}
|
||
```
|
||
|
||
**能力服务 CapabilitiesService**：
|
||
|
||
```protobuf
|
||
service CapabilitiesService {
|
||
rpc GetCapabilities(google.protobuf.Empty) returns (CapabilitiesResponse);
|
||
rpc QueryAgent(QueryAgentRequest) returns (CapabilitiesResponse);
|
||
rpc ListAgents(google.protobuf.Empty) returns (ListAgentsResponse);
|
||
}
|
||
```
|
||
|
||
**群组服务 GroupService**：
|
||
|
||
```protobuf
|
||
service GroupService {
|
||
rpc CreateGroup(CreateGroupRequest) returns (CreateGroupResponse);
|
||
rpc JoinGroup(JoinGroupRequest) returns (JoinGroupResponse);
|
||
rpc LeaveGroup(LeaveGroupRequest) returns (LeaveGroupResponse);
|
||
rpc DisbandGroup(DisbandGroupRequest) returns (DisbandGroupResponse);
|
||
rpc ListGroupMembers(ListGroupMembersRequest) returns (ListGroupMembersResponse);
|
||
rpc StreamGroupMessages(stream SynapseMessage) returns (stream SynapseMessage);
|
||
}
|
||
```
|
||
|
||
**健康服务 HealthService**：
|
||
|
||
```protobuf
|
||
service HealthService {
|
||
rpc HealthCheck(google.protobuf.Empty) returns (HealthCheckResponse);
|
||
}
|
||
```
|
||
|
||
### 4.3 HTTP 路由映射
|
||
|
||
通过 `google.api.http` 注解实现 REST API：
|
||
|
||
| gRPC 方法 | HTTP 路由 |
|
||
|----------|----------|
|
||
| SubmitTask | POST `/api/v1/synapse/task` |
|
||
| SubmitTaskWithFiles | POST `/api/v1/synapse/task/multipart` |
|
||
| GetTask | GET `/api/v1/synapse/task/{task_id}` |
|
||
| GetTaskStatus | GET `/api/v1/synapse/task/{task_id}/status` |
|
||
| ListTasks | GET `/api/v1/synapse/tasks` |
|
||
| CancelTask | POST `/api/v1/synapse/task/{task_id}/cancel` |
|
||
| GetCapabilities | GET `/api/v1/synapse/capabilities` |
|
||
| QueryAgent | GET `/api/v1/synapse/agents/{agent_id}` |
|
||
| ListAgents | GET `/api/v1/synapse/agents` |
|
||
| CreateGroup | POST `/api/v1/synapse/group` |
|
||
| JoinGroup | POST `/api/v1/synapse/group/{group_id}/join` |
|
||
| LeaveGroup | POST `/api/v1/synapse/group/{group_id}/leave` |
|
||
| DisbandGroup | POST `/api/v1/synapse/group/{group_id}/disband` |
|
||
| ListGroupMembers | GET `/api/v1/synapse/group/{group_id}/members` |
|
||
| HealthCheck | GET `/api/v1/synapse/health` |
|
||
|
||
---
|
||
|
||
## 5. 人工介入（HiL）三级升级机制
|
||
|
||
Synapse 协议支持三级人工介入升级机制，根据决策的重要性和紧急程度分级处理。
|
||
|
||
### 5.1 升级级别定义
|
||
|
||
| 级别 | 名称 | 默认超时 | 适用场景 |
|
||
|-----|------|---------|---------|
|
||
| Level 1 | Agent 建议 + 人确认 | 24 小时 | 信息缺失、创意方向、用户主动请求 |
|
||
| Level 2 | 必须人工决策 | 12 小时（紧急 2 小时） | 品牌风格、合规、能力不足、高风险 |
|
||
| Level 3 | 专家/管理层决策 | 72 小时 | 战略决策、重大争议、跨系统冲突 |
|
||
|
||
### 5.2 HiL 状态流转
|
||
|
||
```go
|
||
type HILStatus string
|
||
const (
|
||
HILStatusPending = "pending" // 待处理
|
||
HILStatusWaiting = "waiting" // 等待人工响应
|
||
HILStatusDeciding = "deciding" // 人工正在决策
|
||
HILStatusApproved = "approved" // 已批准
|
||
HILStatusRejected = "rejected" // 已拒绝
|
||
HILStatusTimeout = "timeout" // 超时
|
||
HILStatusEscalated = "escalated" // 已升级
|
||
)
|
||
```
|
||
|
||
### 5.3 HiL 请求结构
|
||
|
||
```go
|
||
type HILRequest struct {
|
||
ID string // 请求 ID
|
||
TaskID string // 关联任务 ID
|
||
EscalationType string // P2P, GROUP, INTER_GROUP
|
||
EscalationLevel int // 1, 2, 3
|
||
Reason HILReason // 介入原因
|
||
Context HILContext // 决策上下文
|
||
Options []HILOption // 可选方案
|
||
SuggestedValue any // Agent 建议值
|
||
Deadline time.Time // 截止时间
|
||
Status HILStatus // 当前状态
|
||
Response *HILResponse // 人工响应
|
||
}
|
||
|
||
type HILReason struct {
|
||
Code string // 原因代码
|
||
Message string // 原因描述
|
||
}
|
||
|
||
type HILOption struct {
|
||
Field string // 字段名
|
||
Value any // 候选值
|
||
Label string // 显示标签
|
||
ProsCons string // 优缺点分析
|
||
Confidence int // Agent 置信度（0-100）
|
||
}
|
||
```
|
||
|
||
### 5.4 升级判定规则
|
||
|
||
```go
|
||
// 需要人工介入的原因代码
|
||
var hilRequiredCodes = map[string]bool{
|
||
"BRAND_STYLE": true, // 品牌风格
|
||
"CREATIVE_DIRECTION": true, // 创意方向
|
||
"COMPLIANCE": true, // 合规要求
|
||
"CAPABILITY_LACKING": true, // 能力不足
|
||
"USER_REQUESTED": true, // 用户请求
|
||
"HIGH_COST_RISK": true, // 高成本风险
|
||
}
|
||
|
||
// 升级级别判定
|
||
var levelMap = map[string]int{
|
||
"INFO_MISSING": 1, // Level 1
|
||
"CREATIVE_DIRECTION": 1,
|
||
"BRAND_STYLE": 2, // Level 2
|
||
"COMPLIANCE": 2,
|
||
"CAPABILITY_LACKING": 2,
|
||
"HIGH_COST_RISK": 2,
|
||
"RESOURCE_DEADLOCK": 2,
|
||
"STRATEGIC_DECISION": 3, // Level 3
|
||
}
|
||
```
|
||
|
||
### 5.5 人工响应结构
|
||
|
||
```go
|
||
type HILResponse struct {
|
||
DecisionID string // 决策 ID
|
||
UserID string // 决策用户 ID
|
||
UserName string // 用户名
|
||
UserRole string // 用户角色
|
||
Action string // approve/reject/modify/select
|
||
Decision HILDecision // 决策内容
|
||
Notes string // 备注
|
||
Timestamp time.Time // 时间戳
|
||
}
|
||
|
||
type HILDecision struct {
|
||
ApprovedFields map[string]interface{} // 批准的字段
|
||
ModifiedFields map[string]interface{} // 修改的字段
|
||
SelectedOption any // 选择的选项
|
||
RejectionReason string // 拒绝原因
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 数字分段错误码系统
|
||
|
||
Synapse 协议使用数字分段错误码，便于程序化处理和国际化。
|
||
|
||
### 6.1 错误码分段
|
||
|
||
| 分段范围 | 类别 | 说明 |
|
||
|---------|------|------|
|
||
| 1000-1999 | SYSTEM_ERROR | 系统错误 |
|
||
| 2000-2999 | TASK_ERROR | 任务错误 |
|
||
| 3000-3999 | INFO_ERROR | 信息错误 |
|
||
| 4000-4999 | CAPABILITY_ERROR | 能力错误 |
|
||
| 5000-5999 | SECURITY_ERROR | 安全错误 |
|
||
| 6000-6999 | COMMUNICATION_ERROR | 通信错误 |
|
||
| 7000-7999 | GROUP_ERROR | 群组错误 |
|
||
| 8000-8999 | HIL_ERROR | HiL 错误 |
|
||
| 9000-9999 | VALIDATION_ERROR | 验证错误 |
|
||
|
||
### 6.2 具体错误码定义
|
||
|
||
**系统错误（1000-1999）**：
|
||
|
||
| 错误码 | 名称 | 说明 |
|
||
|-----|------|------|
|
||
| 1000 | ErrSystemError | 系统错误 |
|
||
| 1001 | ErrInternalError | 内部错误 |
|
||
| 1002 | ErrMaintenance | 系统维护中 |
|
||
|
||
**任务错误（2000-2999）**：
|
||
|
||
| 错误码 | 名称 | 说明 |
|
||
|-----|------|------|
|
||
| 2001 | ErrTaskNotFound | 任务不存在 |
|
||
| 2002 | ErrTaskAlreadyCompleted | 任务已完成 |
|
||
| 2003 | ErrTaskCancelled | 任务已取消 |
|
||
| 2004 | ErrTaskTimeout | 任务超时 |
|
||
| 2005 | ErrTaskInvalidParams | 任务参数无效 |
|
||
|
||
**信息错误（3000-3999）**：
|
||
|
||
| 错误码 | 名称 | 说明 |
|
||
|-----|------|------|
|
||
| 3001 | ErrRequiredFieldMissing | 必填字段缺失 |
|
||
| 3002 | ErrInvalidFieldFormat | 字段格式无效 |
|
||
| 3003 | ErrInfoNotProvided | 信息未提供 |
|
||
|
||
**能力错误（4000-4999）**：
|
||
|
||
| 错误码 | 名称 | 说明 |
|
||
|-----|------|------|
|
||
| 4001 | ErrUnsupportedTaskType | 不支持的任务类型 |
|
||
| 4002 | ErrCapabilityLacking | 能力不足 |
|
||
| 4003 | ErrResourceBusy | 资源繁忙 |
|
||
| 4004 | ErrQuotaExceeded | 配额超限 |
|
||
|
||
**安全错误（5000-5999）**：
|
||
|
||
| 错误码 | 名称 | 说明 |
|
||
|-----|------|------|
|
||
| 5001 | ErrAuthFailed | 认证失败 |
|
||
| 5002 | ErrSignatureInvalid | 签名无效 |
|
||
| 5003 | ErrPermissionDenied | 权限不足 |
|
||
| 5004 | ErrPolicyViolation | 策略违规 |
|
||
|
||
**通信错误（6000-6999）**：
|
||
|
||
| 错误码 | 名称 | 说明 |
|
||
|-----|------|------|
|
||
| 6001 | ErrEndpointUnreachable | 端点不可达 |
|
||
| 6002 | ErrCallbackFailed | 回调失败 |
|
||
| 6003 | ErrMessageFormatInvalid | 消息格式无效 |
|
||
| 6004 | ErrTTLExpired | TTL 过期 |
|
||
|
||
**群组错误（7000-7999）**：
|
||
|
||
| 错误码 | 名称 | 说明 |
|
||
|-----|------|------|
|
||
| 7001 | ErrGroupNotFound | 群组不存在 |
|
||
| 7002 | ErrGroupNotActive | 群组未激活 |
|
||
| 7003 | ErrMemberNotFound | 成员不存在 |
|
||
| 7004 | ErrNotGroupMember | 不是群组成员 |
|
||
| 7005 | ErrConsensusNotReached | 未达成共识 |
|
||
| 7006 | ErrRoleNotFound | 角色不存在 |
|
||
| 7007 | ErrAlreadyMember | 已是成员 |
|
||
| 7008 | ErrGroupFull | 群组已满 |
|
||
|
||
**HiL 错误（8000-8999）**：
|
||
|
||
| 错误码 | 名称 | 说明 |
|
||
|-----|------|------|
|
||
| 8001 | ErrHumanTimeout | 人工决策超时 |
|
||
| 8002 | ErrHumanDeclined | 人工拒绝 |
|
||
| 8003 | ErrEscalationLevel | 升级级别错误 |
|
||
|
||
**验证错误（9000-9999）**：
|
||
|
||
| 错误码 | 名称 | 说明 |
|
||
|-----|------|------|
|
||
| 9001 | ErrInvalidParams | 参数无效 |
|
||
|
||
### 6.3 错误响应结构
|
||
|
||
```go
|
||
type SynapseError struct {
|
||
Code SynapseErrorCode `json:"code"` // 数字错误码
|
||
Category string `json:"category"` // 错误类别
|
||
Message string `json:"message"` // 错误描述
|
||
Details any `json:"details,omitempty"` // 详情
|
||
RetryAfter *int `json:"retry_after,omitempty"` // 重试等待（秒）
|
||
Timestamp Timestamp `json:"timestamp"` // 时间戳
|
||
}
|
||
|
||
type ErrorResponse struct {
|
||
Success bool `json:"success"`
|
||
Error *SynapseError `json:"error"`
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 7. 消息扩展字段
|
||
|
||
统一消息信封 `UnifiedSynapseMessage` 包含扩展字段，用于支持高级功能。
|
||
|
||
### 7.1 扩展字段定义
|
||
|
||
```go
|
||
type UnifiedSynapseMessage struct {
|
||
// 基础字段（协议定义）
|
||
ID string `json:"id"`
|
||
Version string `json:"version"`
|
||
Type string `json:"type"`
|
||
Sender AgentEndpoint `json:"sender"`
|
||
Receiver *AgentEndpoint `json:"receiver,omitempty"`
|
||
CorrelationID string `json:"correlation_id,omitempty"`
|
||
ReplyTo string `json:"reply_to,omitempty"`
|
||
GroupID string `json:"group_id,omitempty"`
|
||
Payload json.RawMessage `json:"payload"`
|
||
Timestamp Timestamp `json:"timestamp"`
|
||
Signature string `json:"signature,omitempty"`
|
||
|
||
// 扩展字段（实现补充）
|
||
ConversationID string `json:"conversation_id,omitempty"` // 会话 ID
|
||
TTL int `json:"ttl,omitempty"` // 消息存活时间（秒）
|
||
Broadcast bool `json:"broadcast,omitempty"` // 是否广播
|
||
Encrypt bool `json:"encrypt,omitempty"` // 是否加密
|
||
TargetType GroupTargetType `json:"target_type,omitempty"` // 群组目标类型
|
||
TargetIDs []string `json:"target_ids,omitempty"` // 目标 ID 列表
|
||
SignatureAlgorithm string `json:"signature_algorithm,omitempty"` // 签名算法
|
||
}
|
||
```
|
||
|
||
### 7.2 群组目标类型
|
||
|
||
```go
|
||
type GroupTargetType string
|
||
const (
|
||
TargetTypeAll GroupTargetType = "all" // 所有成员
|
||
TargetTypeRole GroupTargetType = "role" // 按角色
|
||
TargetTypeSpecific GroupTargetType = "specific" // 指定成员
|
||
)
|
||
```
|
||
|
||
### 7.3 字段用途说明
|
||
|
||
| 字段 | 用途 |
|
||
|-----|------|
|
||
| `conversation_id` | 关联同一会话的多条消息，用于多轮对话场景 |
|
||
| `ttl` | 消息存活时间，过期后由灵泊（Harbor）清理 |
|
||
| `broadcast` | 广播标识，用于群组消息广播 |
|
||
| `encrypt` | 加密标识，指示 payload 已加密 |
|
||
| `target_type` + `target_ids` | 精确控制群组消息的目标范围 |
|
||
| `signature_algorithm` | 明确签名算法，默认 HMAC-SHA256 |
|
||
|
||
---
|
||
|
||
## 8. 传输模式定义
|
||
|
||
Synapse 协议支持多种传输模式，适配不同的网络环境和业务场景。
|
||
|
||
### 8.1 传输模式枚举
|
||
|
||
```go
|
||
type TransportMode string
|
||
const (
|
||
TransportModeCallback TransportMode = "callback" // 异步回调（Webhook）
|
||
TransportModePolling TransportMode = "polling" // 异步轮询
|
||
TransportModeSync TransportMode = "sync" // 同步等待
|
||
TransportModeHybrid TransportMode = "hybrid" // 回调 + 轮询兜底
|
||
)
|
||
```
|
||
|
||
### 8.2 传输偏好配置
|
||
|
||
```go
|
||
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 {
|
||
return &TransportPreferences{
|
||
Preferred: TransportModeCallback,
|
||
Fallback: TransportModePolling,
|
||
PollingInterval: 5,
|
||
ProgressUpdates: true,
|
||
ProgressInterval: 10,
|
||
}
|
||
}
|
||
```
|
||
|
||
### 8.3 轮询 API 类型
|
||
|
||
```go
|
||
// 任务状态响应
|
||
type TaskStatusResponse struct {
|
||
Success bool `json:"success"`
|
||
Task *TaskInfo `json:"task,omitempty"`
|
||
Error *SynapseError `json:"error,omitempty"`
|
||
}
|
||
|
||
// 任务信息
|
||
type TaskInfo struct {
|
||
ID string `json:"id"`
|
||
Type string `json:"type"`
|
||
Status string `json:"status"`
|
||
Progress int `json:"progress"` // 0-100
|
||
Message string `json:"message,omitempty"`
|
||
CreatedAt Timestamp `json:"created_at"`
|
||
UpdatedAt Timestamp `json:"updated_at"`
|
||
ETA *Timestamp `json:"eta,omitempty"`
|
||
Result any `json:"result,omitempty"`
|
||
Error *SynapseError `json:"error,omitempty"`
|
||
ETag string `json:"etag,omitempty"` // 用于增量查询
|
||
}
|
||
|
||
// 任务列表响应
|
||
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"`
|
||
}
|
||
|
||
// 任务事件
|
||
type TaskEvent struct {
|
||
ID string `json:"id"`
|
||
Type string `json:"type"` // status_update, progress, log, error, complete
|
||
Timestamp Timestamp `json:"timestamp"`
|
||
Data any `json:"data"`
|
||
}
|
||
|
||
// 任务事件流响应
|
||
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"`
|
||
}
|
||
```
|
||
|
||
### 8.4 流式传输类型
|
||
|
||
```go
|
||
// 流数据块
|
||
type StreamChunk struct {
|
||
TaskID string `json:"task_id"`
|
||
Sequence int64 `json:"sequence"`
|
||
ChunkType string `json:"chunk_type"` // text, binary, audio, video
|
||
Data string `json:"data"` // base64（二进制）
|
||
Final bool `json:"final"`
|
||
Timestamp Timestamp `json:"timestamp"`
|
||
}
|
||
|
||
// 流完成通知
|
||
type StreamComplete struct {
|
||
TaskID string `json:"task_id"`
|
||
TotalChunks int64 `json:"total_chunks"`
|
||
FullContentChecksum string `json:"full_content_checksum"`
|
||
Result any `json:"result,omitempty"`
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 附录：SDK 结构
|
||
|
||
SDK 统一为一个包，包含三个子包对应三种协议：
|
||
|
||
```
|
||
sdk/
|
||
├── doc.go # SDK 包文档
|
||
├── p2a/ # P2A 协议客户端（外部调用）
|
||
│ └── client.go
|
||
├── a2a/ # A2A 协议客户端（点对点）
|
||
│ └── client.go
|
||
└── a2n/ # A2N 协议客户端（群组）
|
||
│ └── client.go
|
||
```
|
||
|
||
**SDK 使用示例**：
|
||
|
||
```go
|
||
// P2A：外部调用方
|
||
import "synapse/sdk/p2a"
|
||
|
||
client := p2a.NewClient("http://agent-endpoint")
|
||
resp, err := client.SubmitTask(ctx, &p2a.TaskRequest{
|
||
TaskType: "text_generation",
|
||
Payload: payload,
|
||
})
|
||
|
||
// A2A：Agent 点对点通信
|
||
import "synapse/sdk/a2a"
|
||
|
||
client := a2a.NewClient(myEndpoint, config)
|
||
err := client.SendTaskRequest(ctx, targetEndpoint, taskPayload)
|
||
|
||
// A2N：Agent 群组协作
|
||
import "synapse/sdk/a2n"
|
||
|
||
client := a2n.NewClient(myEndpoint, config)
|
||
err := client.JoinGroup(ctx, groupID)
|
||
err := client.SubmitVote(ctx, voteID, optionID)
|
||
```
|
||
|
||
---
|
||
|
||
**文档结束**
|
||
|
||
> 本实现细节文档与核心协议文档共同构成 Synapse 协议的完整规范。
|
||
> 核心协议文档：[01-synapse-raw-protocol.md](01-synapse-raw-protocol.md)、[02-p2p-protocol.md](02-p2p-protocol.md)、[03-group-protocol.md](03-group-protocol.md)、[04-caller-protocol.md](04-caller-protocol.md) |