12 KiB
12 KiB
灵隙 Synapse 协议栈架构说明
灵隙通万智，脉动定乾坤。
Synapse connects myriad wisdoms; the Meridian settles the cosmos.
一、架构总览
灵隙协议栈采用 分层 + 组件化 设计，从下到上共分四层：
┌─────────────────────────────────────────────────────────┐
│ 组合协议层 (Composite Protocols) │
│ ┌─────────┐ ┌─────────┐ ┌──────────┐ ┌─────────┐ │
│ │ A2N群组 │ │ 工作流 │ │ 联邦学习 │ │ ... │ │
│ └────┬────┘ └────┬────┘ └─────┬────┘ └────┬────┘ │
└───────┼─────────────┼──────────────┼──────────────┼──────┘
│ │ │ │
┌───────▼─────────────▼──────────────▼──────────────▼──────┐
│ 组件层 (Pluggable Components) │
│ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ 灵脉 Meridian - 寻址与路由 │ │
│ │ 灵玺 Sigil - 身份与凭证 │ │
│ │ 灵鉴 Speculum - 共识与裁决 │ │
│ │ 灵泊 Harbor - 异步队列与暂存 │ │
│ │ 灵瞰 Panorama - 可观测与度量 │ │
│ │ 灵衡 Libra - 价值结算与激励 │ │
│ │ 灵枢 Pivot - 紧急制动与治理 │ │
│ └─────────────────────────────────────────────────┘ │
└──────────────────────────┬───────────────────────────────┘
│
┌──────────────────────────▼───────────────────────────────┐
│ 基础协议层 (Base Protocols) │
│ │
│ ┌─────────────────┐ ┌────────────────────────┐ │
│ │ P2A 协议 │ │ A2A 协议 │ │
│ │ 外部调用 → Agent│ │ Agent ↔ Agent (点对点)│ │
│ └─────────────────┘ └────────────────────────┘ │
└──────────────────────────┬───────────────────────────────┘
│
┌──────────────────────────▼───────────────────────────────┐
│ 传输层 (Transport Layer) │
│ HTTP / gRPC / WebSocket / ... │
└──────────────────────────────────────────────────────────┘
二、命名体系
核心命名
| 层级 | 英文 | 中文 | 释义 |
|---|---|---|---|
| 协议栈总名 | Synapse | 灵隙 | 突触，神经细胞间的连接缝隙。既有生物神经的精密感，又有"灵光一现的缝隙"的东方禅意。 |
七大组件
| 组件 | 英文代号 | 中文名 | 对应场景 | 释义 |
|---|---|---|---|---|
| 寻址与路由层 | Meridian | 灵脉 (Líng Mài) | Agent 发现与拓扑连接 | 取中医"经脉"之意。Agent 之间虽有空隙（灵隙），但暗中有能量流动的轨迹（脉）。此层负责维护全局路由表，让新 Agent "通脉"入网，旧 Agent "断脉"离场。 |
| 身份与凭证层 | Sigil | 灵玺 (Líng Xǐ) | 防伪、授权与零信任 | 皇帝的玉玺是最高凭证。每个 Agent 的初始身份都需经过"铸玺"过程，每一次交互都要"验玺"，确保穿透零信任边界后的每一次握手都正统且不可篡改。 |
| 共识与裁决层 | Speculum | 灵鉴 (Líng Jiàn) | 多 Agent 辩论、投票与冲突解决 | 古有"以史为鉴"，今有"以智为鉴"。此层不是粗暴的少数服从多数，而是让各方 Agent 将推理过程"照"进公共镜面，通过对比逻辑链的严密性来达成共识。 |
| 异步队列与暂存层 | Harbor | 灵泊 (Líng Bó) | 离线缓冲、任务积压与重试 | "泊"为船舶停靠。数据包如远行之舟，遇风浪（网络抖动）时暂泊于此，待风平浪静（目标就绪）再启航。不丢包、不超时。 |
| 可观测与度量层 | Panorama | 灵瞰 (Líng Kàn) | 全链路追踪、日志与健康度 | 居高临下，俯瞰全局。此层不参与业务交互，却如"天眼"般记录每一帧交互的耗时、置信度与资源消耗，让黑盒群体智能变为白盒可解释的图景。 |
| 价值结算与激励层 | Libra | 灵衡 (Líng Héng) | Agent 间的资源兑换、Token 支付 | 权衡利弊，计量公平。此层负责将 Agent 间的"智力贡献"与"资源消耗"通证化，动态定价，让多智能体经济具备自驱的盈亏平衡。 |
| 紧急制动与治理层 | Pivot | 灵枢 (Líng Shū) | 协议升级、熔断与伦理闸门 | 取自《灵枢经》（黄帝内经下半部），讲的是针灸经络之枢纽。这是整个协议的"总闸"与"方向盘"，不轻易触发，但触发时能以最小代价重置整个网络状态。 |
三、目录结构
synapse/
│
├── types/ # 核心类型定义
│ ├── types.go # 消息结构、Agent端点、任务负载等
│ ├── errors.go # 错误码与错误类型
│ └── content.go # 内容格式定义
│
├── transport/ # 传输层
│ ├── transport.go # 传输接口与HTTP传输实现
│ └── multipart_polling.go # 多部分轮询传输
│
├── meridian/ # 灵脉 - 寻址与路由层
│ └── meridian.go # Agent注册发现、消息路由、拓扑管理
│
├── sigil/ # 灵玺 - 身份与凭证层
│ └── sigil.go # 身份管理、签名验证、授权令牌
│
├── p2p/ # A2A 协议 - Agent间点对点通信
│ └── protocol.go # P2P消息处理器、任务管理
│
├── externalapi/ # P2A 协议 - 外部调用API
│ └── handler.go # REST API处理器
│
├── group/ # A2N 协议 - 群组协作 (组合协议)
│ └── protocol.go # 群组管理、任务拆分合并、投票
│
├── speculum/ # 灵鉴 - 共识与裁决层
│ └── speculum.go # 共识引擎、仲裁机制、推理镜面
│
├── harbor/ # 灵泊 - 异步队列与暂存层
│ └── harbor.go # 消息队列、离线缓冲、重试管理
│
├── panorama/ # 灵瞰 - 可观测与度量层
│ └── panorama.go # 链路追踪、指标收集、健康检查
│
├── libra/ # 灵衡 - 价值结算与激励层
│ └── libra.go # 账本记账、定价引擎、结算系统
│
├── pivot/ # 灵枢 - 紧急制动与治理层
│ └── pivot.go # 熔断器、治理管理、协议升级
│
├── capabilities/ # 能力声明
│ └── provider.go # 能力提供器接口与标准接口
│
├── hil/ # 人工介入 (Human-in-the-Loop)
│ └── protocol.go # HiL协议处理
│
├── routing/ # 旧版路由（将迁移至 meridian）
│ └── router.go # 消息路由器（保留兼容）
│
├── grpcapi/ # gRPC API
│ ├── server.go # gRPC服务端
│ ├── client.go # gRPC客户端
│ ├── synapse.pb.go # Protobuf生成代码
│ └── synapse_grpc.pb.go # gRPC生成代码
│
├── proto/ # Protobuf定义
│ └── synapse.proto # 协议定义文件
│
├── sdk/ # SDK
│ ├── doc.go # SDK包文档
│ ├── p2p/ # A2A SDK - P2P点对点通信
│ │ └── client.go
│ ├── group/ # A2N SDK - 群组协作
│ │ └── client.go
│ └── caller/ # P2A SDK - 外部调用
│ └── client.go
│
├── docs/ # 协议文档
│ ├── 01-synapse-raw-protocol.md
│ ├── 02-p2p-protocol.md
│ ├── 03-group-protocol.md
│ ├── 04-caller-protocol.md
│ ├── 05-sdk-implementation.md
│ └── 06-solutions-whitepaper.md
│
├── examples/ # 示例代码
│ ├── p2p_demo/ # P2P通讯示例
│ └── group_demo/ # Group群组示例
│
├── go.mod
├── go.sum
└── MIGRATION.md
四、设计原则
1. 内核极简，组件扩展
- 基础协议层（P2A + A2A） 是最小内核，只定义消息格式和基本交互
- 七大组件 是可插拔能力，按需加载
- 组合协议层 通过装配不同组件生成高级协议
2. 命名统一，东方美学
- 所有组件统一"灵"字前缀：灵脉、灵玺、灵鉴、灵泊、灵瞰、灵衡、灵枢
- 英文代号各有出处：Meridian（经脉）、Sigil（纹章）、Speculum（镜鉴）、Harbor（港湾）、Panorama（全景）、Libra（天平）、Pivot（枢轴）
3. 接口清晰，松耦合
每个组件都定义清晰的接口，组件之间通过接口交互，而非直接依赖。
五、组合协议示例
A2N 群组协议 = A2A + 灵鉴 + 灵脉 + 灵泊
A2N (群组协作)
├── A2A 协议 # 基础点对点通信
├── 灵鉴 Speculum # 投票与共识
├── 灵脉 Meridian # 成员发现与拓扑
├── 灵泊 Harbor # 消息队列与离线缓冲
└── 灵瞰 Panorama # （可选）可观测性
联邦学习协议 = A2A + 灵鉴 + 灵衡 + 灵枢
联邦学习
├── A2A 协议 # 基础通信
├── 灵鉴 Speculum # 模型聚合共识
├── 灵衡 Libra # 贡献度计量与激励
└── 灵枢 Pivot # 训练中止与治理
六、Slogan
灵隙通万智，脉动定乾坤。
（Synapse connects myriad wisdoms; the Meridian settles the cosmos.）
灵隙 Synapse 协议栈 v1.0.0