synapse/docs/v1/00_index.md

灵隙 Synapse 协议栈 v1

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

---

协议结构

本版本协议按抽象层设计，只定义"实现什么功能"和"数据格式"，不涉及具体实现细节。

docs/v1/
├── index.md                 # 本文件（协议索引）
├── raw-protocol.md          # 原始协议（基础层）
├── a2a-protocol.md          # A2A 协议（点对点）
├── a2n-protocol.md          # A2N 协议（群组协作）
├── p2a-protocol.md          # P2A 协议（外部调用）
├── identity-protocol-draft.md # 去中心化身份与寻址（草案）
│
├── components.md            # 七大组件层（灵脉/灵玺/灵鉴/灵泊/灵瞰/灵衡/灵枢）
├── content-system.md        # 内容类型系统
├── capabilities-system.md   # 能力声明系统
├── grpc-transport.md        # gRPC 传输协议
├── hil-mechanism.md         # HiL 三级升级机制
├── error-codes.md           # 数字分段错误码系统
├── message-extensions.md    # 消息扩展字段
└── transport-modes.md       # 传输模式定义

---

文档分类

v1 版本文档分为三层：

协议层（抽象层）

定义"实现什么功能"和"数据格式"，不涉及具体实现细节：

编号	文档	说明
00	00_index.md	协议索引
01	01_raw-protocol.md	原始协议（公共基础）
02	02_a2a-protocol.md	A2A 协议（点对点）
03	03_a2n-protocol.md	A2N 协议（群组协作）
04	04_p2a-protocol.md	P2A 协议（外部调用）
05	05_identity-protocol-draft.md	去中心化身份与寻址（草案）

实现层

每个文档对应一个独立的功能模块：

文档	对应模块
components.md	七大组件层（灵脉/灵玺/灵鉴/灵泊/灵瞰/灵衡/灵枢）
content-system.md	内容类型系统
capabilities-system.md	能力声明系统
grpc-transport.md	gRPC 传输协议
hil-mechanism.md	HiL 三级升级机制
error-codes.md	数字分段错误码系统
message-extensions.md	消息扩展字段
transport-modes.md	传输模式定义

---

协议对比

协议	代号	参与方	核心功能
原始协议	Raw	-	消息信封、身份、签名
A2A 协议	P2P	Agent ↔ Agent	任务提交、进度同步、信息补全、HiL
A2N 协议	Group	1 Coordinator + N Worker	群组管理、任务拆分合并、投票共识
P2A 协议	Caller	外部 → Agent	REST API、回调/轮询

---

消息类型前缀

前缀	协议	说明
p2p:	A2A	点对点消息（17 种）
group:	A2N	群组内消息（20+ 种）
inter_group:	A2N	跨群组消息（升级）
caller:	P2A	外部调用消息（内部转换）

---

与 v0 版本的差异

对比项	v0 版本	v1 版本
内容定位	混合抽象层和实现层	协议层 + 独立实现层
数据格式	嵌入大量 JSON 示例	表格化字段定义
实现细节	包含 Go struct、算法实现	独立实现层文档
七大组件	一个文档混合包含	独立为组件层规范
SDK	三个子包（p2a/a2a/a2n）	单包，通过 Protocol 参数区分
文件数量	8 个	14 个（5 协议 + 8 实现 + 1 草案）

---

版本历史

版本	日期	变更说明
v1.0.0	2026-06-27	重构为抽象层协议 + 独立实现层文档，继承 v0 全部内容
v0.x	2026-06-27	初始版本（混合抽象层与实现层）