107 lines
5.0 KiB
Markdown
107 lines
5.0 KiB
Markdown
# 灵隙 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](00_index.md) | 协议索引 |
|
||
| 01 | [01_raw-protocol.md](01_raw-protocol.md) | 原始协议（公共基础） |
|
||
| 02 | [02_a2a-protocol.md](02_a2a-protocol.md) | A2A 协议（点对点） |
|
||
| 03 | [03_a2n-protocol.md](03_a2n-protocol.md) | A2N 协议（群组协作） |
|
||
| 04 | [04_p2a-protocol.md](04_p2a-protocol.md) | P2A 协议（外部调用） |
|
||
| 05 | [05_identity-protocol-draft.md](05_identity-protocol-draft.md) | 去中心化身份与寻址（草案） |
|
||
|
||
### 实现层
|
||
|
||
每个文档对应一个独立的功能模块：
|
||
|
||
| 文档 | 对应模块 |
|
||
|--------------------------------------------------|-----------------------------|
|
||
| [components.md](components.md) | 七大组件层（灵脉/灵玺/灵鉴/灵泊/灵瞰/灵衡/灵枢） |
|
||
| [content-system.md](content-system.md) | 内容类型系统 |
|
||
| [capabilities-system.md](capabilities-system.md) | 能力声明系统 |
|
||
| [grpc-transport.md](grpc-transport.md) | gRPC 传输协议 |
|
||
| [hil-mechanism.md](hil-mechanism.md) | HiL 三级升级机制 |
|
||
| [error-codes.md](error-codes.md) | 数字分段错误码系统 |
|
||
| [message-extensions.md](message-extensions.md) | 消息扩展字段 |
|
||
| [transport-modes.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 | 初始版本（混合抽象层与实现层） | |