Files
synapse/docs/v1/00-index.md
2026-06-27 22:17:15 +08:00

113 lines
4.5 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 灵隙 Synapse 协议栈 v1
> 版本:1.0.0
> 更新日期:2026-06-27
---
## 协议结构
本版本协议按抽象层设计,只定义"实现什么功能"和"数据格式",不涉及具体实现细节。
```
docs/v1/
├── 00-index.md # 本文件(协议索引)
├── 01-raw-protocol.md # 原始协议(基础层)
├── 02-a2a-protocol.md # A2A 协议(点对点)
├── 03-a2n-protocol.md # A2N 协议(群组协作)
└── 04-p2a-protocol.md # P2A 协议(外部调用)
```
---
## 协议概览
### 层级关系
```
┌─────────────────────────────────────┐
│ P2A 协议(外部调用入口) │
│ 04-p2a-protocol.md │
└─────────────────────────────────────┘
│
│ 封装
▼
┌─────────────────────────────────────────────────────┐
│ A2A 协议(点对点任务协作) │
│ 02-a2a-protocol.md │
└─────────────────────────────────────────────────────┘
│
│ 复用单播
▼
┌─────────────────────────────────────────────────────┐
│ A2N 协议(群组协作) │
│ 03-a2n-protocol.md │
└─────────────────────────────────────────────────────┘
│
│ 继承
▼
┌─────────────────────────────────────────────────────┐
│ 原始协议(公共基础) │
│ 01-raw-protocol.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、算法实现 | 仅定义接口要求 |
| 七大组件 | 无协议规范 | 待补充独立文档 |
| 文件数量 | 8 个 | 4 个核心协议 |
---
## 后续补充
以下内容待补充为独立实现文档(不属于协议抽象层):
- 七大组件详细规范(灵脉、灵玺、灵鉴、灵泊、灵瞰、灵衡、灵枢)
- 内容类型系统(TextContent、FileContent 等)
- 能力声明系统
- gRPC 传输协议
- HiL 三级升级机制
- 数字分段错误码完整定义
---
## 版本历史
| 版本 | 日期 | 变更说明 |
|------|------|---------|
| v1.0.0 | 2026-06-27 | 重构为抽象层协议,分离实现细节 |
| v0.x | 2026-06-27 | 初始版本(混合抽象层与实现层) |