# 灵隙 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*