ai/synapse

Fork 0

Files

lychang 88b606b9ca 灵隙(synapse) v1.0.0 版本

2026-06-27 22:17:15 +08:00

43 KiB

Raw Blame History

灵隙 Synapse 协议实现细节文档

本文档描述 Synapse 协议栈的具体实现规范，作为核心协议文档的补充。

版本：1.0.0 | 更新日期：2026-06-27

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

数据结构：

// 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分钟）
}

拓扑管理：

// 拓扑类型
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)`	验证令牌有效性

身份结构：

// 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             // 过期时间
}

签名算法：

// 支持的签名算法
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)`	比较推理链严密性

共识类型：

type ConsensusType string
const (
    ConsensusMajority      = "majority"       // 多数投票（>50%）
    ConsensusSupermajority = "supermajority"  // 绝对多数（>67%）
    ConsensusUnanimity     = "unanimity"      // 一致同意（100%）
    ConsensusWeighted      = "weighted"       // 加权投票
    ConsensusRanked        = "ranked"         // 排序投票
)

投票结构：

// 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             // 得票率
}

推理镜面：

// 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)`	添加重试条目

队列配置：

// 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"        // 死信
)

重试机制：

// 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)

缓冲配置：

// 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)`	检查所有组件健康状态

追踪结构：

// 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"  // 已取消
)

指标类型：

type MetricType string
const (
    MetricCounter   = "counter"    // 计数器（累加）
    MetricGauge     = "gauge"      // 计量器（瞬时值）
    MetricHistogram = "histogram"  // 直方图（分布）
)

健康状态：

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)`	发放奖励

账户与交易：

// 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"             // 惩罚
)

定价规则：

// 基础价格（默认）
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)`	回滚协议升级

熔断器：

// 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：再次失败

治理级别：

type GovernanceLevel int
const (
    GovLevelNormal    = iota  // 正常运行
    GovLevelWatch             // 观察模式（记录但不限制）
    GovLevelRestricted        // 受限模式（限流）
    GovLevelEmergency         // 紧急模式（仅白名单）
    GovLevelShutdown          // 停机模式（全部拒绝）
)

2. 内容类型系统

Synapse 协议支持多种内容类型的传输，适用于不同场景的数据交互。

2.1 传输模式

type TransferMode string
const (
    TransferInline    = "inline"    // 内嵌传输（base64 编码）
    TransferURL       = "url"       // URL 引用传输
    TransferStreaming = "streaming" // 流式传输
    TransferMultipart = "multipart" // Multipart 表单传输
)

// 文件大小阈值判断
// size <= 1MB → inline
// size > 1MB → url 或 streaming

2.2 内容编码

type ContentEncoding string
const (
    EncodingNone    = "none"      // 无编码
    EncodingBase64  = "base64"    // Base64 编码
    EncodingGzip    = "gzip"      // Gzip 压缩
    EncodingDeflate = "deflate"   // Deflate 压缩
)

2.3 内容类型定义

文本内容：

type TextContent struct {
    ContentBase
    Charset  string  `json:"charset"`             // 字符集（"utf-8"）
    Language string  `json:"language,omitempty"`  // 语言
    Data     string  `json:"data"`                // 文本数据
}

JSON 内容：

type JSONContent struct {
    ContentBase
    Schema    string `json:"schema,omitempty"`     // Schema 标识
    SchemaURL string `json:"schema_url,omitempty"` // Schema URL
    Data      any    `json:"data"`                 // JSON 数据
}

代码内容：

type CodeContent struct {
    ContentBase
    Language     string   `json:"language"`              // 编程语言
    Version      string   `json:"version,omitempty"`     // 语言版本
    Dependencies []string `json:"dependencies,omitempty"` // 依赖列表
    Data         string   `json:"data"`                  // 代码内容
}

文件内容：

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
}

内容包（多文件）：

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 类型常量

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 核心接口

type CapabilitiesProvider interface {
    GetCapabilities(ctx context.Context) (*AgentCapabilities, error)
    GetSupportedInterfaces() []ImplementedInterface
    GetTaskTypeCapabilities(taskType string) (*SupportedTaskType, error)
}

3.2 能力描述结构

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 接口分类与合规级别

接口分类：

type InterfaceCategory string
const (
    CategoryCore       = "core"       // 核心接口（身份、消息处理）
    CategoryP2P        = "p2p"        // P2P 接口（任务处理、回调）
    CategoryGroup      = "group"      // 群组接口（子任务、投票）
    CategoryHiL        = "hil"        // HiL 接口（人工决策、升级）
    CategoryTransport  = "transport"  // 传输接口（HTTP、流式）
    CategorySecurity   = "security"   // 安全接口（认证、幂等）
    CategoryManagement = "management" // 管理接口（配置、监控）
)

合规级别：

// 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：

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：

service SynapseMessageService {
  rpc SendMessage(SendMessageRequest) returns (SendMessageResponse);
  rpc StreamMessages(stream SynapseMessage) returns (stream SynapseMessage);
  rpc ReceiveCallback(google.protobuf.Empty) returns (stream SynapseMessage);
}

能力服务 CapabilitiesService：

service CapabilitiesService {
  rpc GetCapabilities(google.protobuf.Empty) returns (CapabilitiesResponse);
  rpc QueryAgent(QueryAgentRequest) returns (CapabilitiesResponse);
  rpc ListAgents(google.protobuf.Empty) returns (ListAgentsResponse);
}

群组服务 GroupService：

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：

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 状态流转

type HILStatus string
const (
    HILStatusPending   = "pending"    // 待处理
    HILStatusWaiting   = "waiting"    // 等待人工响应
    HILStatusDeciding  = "deciding"   // 人工正在决策
    HILStatusApproved  = "approved"   // 已批准
    HILStatusRejected  = "rejected"   // 已拒绝
    HILStatusTimeout   = "timeout"    // 超时
    HILStatusEscalated = "escalated"  // 已升级
)

5.3 HiL 请求结构

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 升级判定规则

// 需要人工介入的原因代码
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 人工响应结构

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 错误响应结构

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 扩展字段定义

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 群组目标类型

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 传输模式枚举

type TransportMode string
const (
    TransportModeCallback TransportMode = "callback" // 异步回调（Webhook）
    TransportModePolling  TransportMode = "polling"  // 异步轮询
    TransportModeSync     TransportMode = "sync"     // 同步等待
    TransportModeHybrid   TransportMode = "hybrid"   // 回调 + 轮询兜底
)

8.2 传输偏好配置

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 类型

// 任务状态响应
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 流式传输类型

// 流数据块
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 使用示例：

// 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、02-p2p-protocol.md、03-group-protocol.md、04-caller-protocol.md

43 KiB Raw Blame History Unescape Escape

灵隙 Synapse 协议实现细节文档

目录

1. 七大组件层详细规范

1.1 灵脉 Meridian - 寻址与路由层

1.2 灵玺 Sigil - 身份与凭证层

1.3 灵鉴 Speculum - 共识与裁决层

1.4 灵泊 Harbor - 异步队列与暂存层

1.5 灵瞰 Panorama - 可观测与度量层

1.6 灵衡 Libra - 价值结算与激励层

1.7 灵枢 Pivot - 紧急制动与治理层

2. 内容类型系统

2.1 传输模式

2.2 内容编码

2.3 内容类型定义

2.4 MIME 类型常量

3. 能力声明系统

3.1 核心接口

3.2 能力描述结构

3.3 接口分类与合规级别

3.4 标准接口注册表

4. gRPC 传输协议

4.1 Proto 定义位置

4.2 服务定义

4.3 HTTP 路由映射

5. 人工介入（HiL）三级升级机制

5.1 升级级别定义

5.2 HiL 状态流转

5.3 HiL 请求结构

5.4 升级判定规则

5.5 人工响应结构

6. 数字分段错误码系统

6.1 错误码分段

6.2 具体错误码定义

6.3 错误响应结构

7. 消息扩展字段

7.1 扩展字段定义

7.2 群组目标类型

7.3 字段用途说明

8. 传输模式定义

8.1 传输模式枚举

8.2 传输偏好配置

8.3 轮询 API 类型

8.4 流式传输类型

附录：SDK 结构

43 KiB

Raw Blame History