灵隙(synapse) v1.0.0 版本

This commit is contained in:
lychang
2026-06-28 03:24:26 +08:00
parent 88b606b9ca
commit 812f68d5aa
48 changed files with 5566 additions and 1499 deletions

107
docs/v1/00_index.md Normal file
View File

@@ -0,0 +1,107 @@
# 灵隙 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 | 初始版本(混合抽象层与实现层) |