# 灵隙 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 | 初始版本（混合抽象层与实现层）               |