217 lines
12 KiB
Markdown
217 lines
12 KiB
Markdown
# 灵隙 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*
|