# 灵隙协议族（Synapse Protocol Suite） - 解决方案白皮书

> 版本：1.0.0  
> 日期：2026-06-27  
> 状态：草案  
> 前置阅读：[灵隙原始协议（Synapse Raw Protocol）](./01-synapse-raw-protocol.md)

---

## 目录

1. [概述](#1-概述)
2. [方案一：Agent 发现与广播机制](#2-方案一agent-发现与广播机制)
3. [方案二：身份认证与信任体系](#3-方案二身份认证与信任体系)
4. [方案三：协议缺失内容补全](#4-方案三协议缺失内容补全)
5. [分阶段实施路线图](#5-分阶段实施路线图)
6. [技术选型建议](#6-技术选型建议)

---

## 1. 概述

### 1.1 背景

当前灵隙协议族（Synapse Protocol Suite）定义了 Agent 之间"怎么说话"（消息格式、任务流程），但缺少：

- **怎么找到对方** — Agent 发现与广播机制
- **怎么相信对方** — 身份认证与信任体系
- **怎么规模化协作** — 路由、调度、激励等基础设施

本文档针对上述问题给出完整的解决方案。

### 1.2 设计原则

| 原则 | 说明 |
|------|------|
| **渐进式** | 从简单到复杂，每阶段都可用 |
| **可插拔** | 组件可替换，不绑定具体实现 |
| **传输无关** | 不依赖特定底层网络 |
| **安全优先** | 身份认证是基础设施，不是可选功能 |
| **向后兼容** | 不破坏现有协议，增量扩展 |

---

## 2. 方案一：Agent 发现与广播机制

### 2.1 整体架构

```
┌─────────────────────────────────────────────────────────────────────┐
│                      Agent 发现与广播层                             │
├─────────────────────┬─────────────────────┬─────────────────────────┤
│   集中式目录服务      │   分布式 Gossip      │   组播/广播            │
│   (Directory)        │   (Gossip)          │   (Multicast)          │
│  ┌───────────────┐  │  ┌───────────────┐  │  ┌────────────────┐   │
│  │  注册/注销     │  │  │  消息泛洪      │  │  │  子网内广播      │   │
│  │  能力索引      │  │  │  状态同步      │  │  │  邻居发现       │   │
│  │  名字解析      │  │  │  节点发现      │  │  │  本地心跳       │   │
│  └───────────────┘  │  └───────────────┘  │  └────────────────┘   │
└─────────────────────┴─────────────────────┴─────────────────────────┘
```

### 2.2 模式一：集中式目录服务（推荐首选）

#### 2.2.1 架构说明

引入 **Agent Directory Service（ADS）** 作为中心化的 Agent 目录服务，类似 DNS。

```
Agent A ──注册──▶ ┌─────────────┐ ◀──注册── Agent B
                  │  Directory  │
Agent C ──查询──▶ │  Service    │ ◀──心跳── Agent D
                  └─────────────┘
                       │
                       ▼
                  能力索引
                  在线状态
                  端点地址
```

#### 2.2.2 核心接口

**注册协议（Agent → Directory）：**

| 操作 | 消息类型 | 说明 |
|------|---------|------|
| 注册 | `dir:register` | Agent 上线时注册自身信息 |
| 注销 | `dir:unregister` | Agent 下线时注销 |
| 心跳 | `dir:heartbeat` | 定期上报存活状态 |
| 更新能力 | `dir:update_capabilities` | 能力变化时更新 |

**查询协议（Agent → Directory）：**

| 操作 | 消息类型 | 说明 |
|------|---------|------|
| 按 ID 查询 | `dir:query_by_id` | 根据 AgentID 查端点 |
| 按能力查询 | `dir:query_by_capability` | 找具备某能力的 Agent |
| 列表查询 | `dir:list` | 分页列出所有 Agent |
| 批量查询 | `dir:batch_query` | 批量查询多个 Agent |

#### 2.2.3 注册数据结构

```json
{
  "agent_id": "agent-001",
  "agent_name": "视频生成Agent",
  "system_id": "video-system",
  "endpoint": "https://agent-001.example.com/synapse/callback",
  "version": "1.0.0",
  "capabilities": [
    {
      "type": "video_generation",
      "name": "视频生成",
      "description": "根据脚本生成视频",
      "max_concurrent": 10,
      "avg_latency_ms": 5000
    }
  ],
  "transports": ["http", "grpc"],
  "status": "online",
  "last_heartbeat": "2026-06-27T10:00:00Z",
  "trust_score": 85,
  "public_key": "-----BEGIN PUBLIC KEY-----\n..."
}
```

#### 2.2.4 优缺点

| 优点 | 缺点 |
|------|------|
| 查询效率高（O(1)） | 单点故障风险 |
| 支持复杂查询（按能力、按系统等） | 中心节点需信任 |
| 易于管理和监控 | 扩展性有上限 |
| 实现简单 | 存在注册/注销时序问题 |

---

### 2.3 模式二：分布式 Gossip 协议（可选扩展）

#### 2.3.1 架构说明

无中心节点，Agent 之间通过 Gossip 协议（epidemic protocol）扩散状态信息，类似比特币网络的节点发现。

```
Agent A ──gossip──▶ Agent B ──gossip──▶ Agent D
   │                  │
   └──gossip──▶ Agent C ──gossip──▶ Agent E
```

#### 2.3.2 核心机制

| 机制 | 说明 |
|------|------|
| **Peer Sampling** | 每个 Agent 维护一个部分视图（partial view） |
| **Active Push** | 定期随机选几个节点推送本地状态 |
| **Passive Pull** | 收到推送后，有概率回传自身状态 |
| **TTL** | 消息有存活跳数，防止无限扩散 |
| **Deduplication** | 消息 ID 去重，避免重复处理 |

#### 2.3.3 Gossip 消息格式

```json
{
  "type": "gossip:state",
  "from": "agent-001",
  "view": [
    {"agent_id": "agent-002", "endpoint": "...", "capabilities": [...], "timestamp": "..."},
    {"agent_id": "agent-003", "endpoint": "...", "capabilities": [...], "timestamp": "..."},
    {"agent_id": "agent-004", "endpoint": "...", "capabilities": [...], "timestamp": "..."}
  ],
  "ttl": 5,
  "msg_id": "msg-xxx"
}
```

#### 2.3.4 优缺点

| 优点 | 缺点 |
|------|------|
| 完全去中心化 | 查询效率低（需本地构建视图） |
| 容错性强 | 状态最终一致，有延迟 |
| 可无限扩展 | 实现复杂度高 |
| 无单点故障 | 网络流量大 |

---

### 2.4 模式三：本地组播/邻居发现（局域网场景）

适用于同一内网/集群内的 Agent 快速发现。

#### 2.4.1 机制

| 机制 | 说明 |
|------|------|
| **UDP 组播** | 定期在组播地址发送广播 |
| **mDNS/DNS-SD** | 类似 Apple Bonjour 的服务发现 |
| **ARP/NDP** | 链路层发现（不推荐） |

#### 2.4.2 适用场景

- 边缘计算集群
- 同一机房内的 Agent 集群
- 本地开发测试环境

---

### 2.5 广播机制设计

#### 2.5.1 广播类型

| 广播范围 | 消息类型前缀 | 说明 |
|---------|-------------|------|
| 全网广播 | `global:` | 所有在线 Agent |
| 系统广播 | `system:` | 同一 system_id 内 |
| 群组广播 | `group:` | 同一群组内（已有） |
| 能力组广播 | `cap:` | 具备某能力的 Agent |

#### 2.5.2 广播实现

**集中式模式下：**
- 由 Directory Service 转发广播消息
- 支持按条件过滤（按能力、按系统等）

**分布式模式下：**
- 通过 Gossip 协议泛洪
- TTL 控制扩散范围
- 消息 ID 去重

---

### 2.6 心跳与存活检测

#### 2.6.1 心跳机制

```
Agent ───heartbeat──▶ Directory
        (每30秒)

Directory 判定离线：
  - 连续 3 次未收到心跳 → 标记为 offline
  - 离线 24 小时 → 自动注销
```

#### 2.6.2 主动探测

```
Directory ───ping──▶ Agent
            ◀──pong──
```

用于验证 Agent 是否真的在线（防止心跳伪造）。

---

## 3. 方案二：身份认证与信任体系

### 3.1 三层身份架构

```
┌─────────────────────────────────────────────────┐
│  Layer 3: 信任评分 (Trust Score)                │
│  声誉系统、历史行为、第三方评价                   │
├─────────────────────────────────────────────────┤
│  Layer 2: 身份验证 (Authentication)            │
│  签名验证、证书校验、DID 验证                    │
├─────────────────────────────────────────────────┤
│  Layer 1: 身份标识 (Identity)                  │
│  AgentID + 公钥 / 证书 / DID                    │
└─────────────────────────────────────────────────┘
```

### 3.2 Layer 1：身份标识方案

#### 3.2.1 方案 A：公钥身份（推荐基础版）

**核心思想**：AgentID = 公钥哈希（类似比特币地址）

```
AgentID = base58(sha256(public_key)[:20])
例：agent-1A2B3C4D5E6F...
```

**优点：**
- 自包含，不需要中心 CA
- 公钥可验证身份
- 实现简单

**缺点：**
- 身份无法撤销（私钥泄露 = 身份被盗）
- 没有人类可读的名字
- 无法关联真实世界身份

**适用场景**：内部系统、测试环境、信任度要求不高的场景

#### 3.2.2 方案 B：PKI 证书体系

**核心思想**：引入 CA（Certificate Authority）颁发证书

```
CA 根证书
   ├── 系统A证书
   │   ├── Agent-001 证书
   │   └── Agent-002 证书
   └── 系统B证书
       └── Agent-003 证书
```

**优点：**
- 成熟的工业标准
- 支持证书撤销（CRL/OCSP）
- 有层级信任关系

**缺点：**
- 需要信任中心化 CA
- 证书管理复杂
- 跨 CA 互操作需要桥接

**适用场景**：企业内部、有明确信任中心的场景

#### 3.2.3 方案 C：区块链 DID（去中心化身份）

**核心思想**：身份上链，链上存公钥和属性，类似 W3C DID 标准。

```
链上存储：
  DID → {
    "publicKey": "...",
    "controller": "...",
    "authentication": [...],
    "service": [...],
    "revoked": false,
    "timestamp": "..."
  }
```

**三种实现路径：**

| 路径 | 说明 | 适用场景 |
|------|------|---------|
| **公链 DID** | 使用以太坊/Solana 等公链 | 开放生态、跨组织协作 |
| **联盟链 DID** | 多机构共建联盟链 | 行业联盟、政企合作 |
| **私有链 DID** | 单组织内部链 | 企业内部、对性能要求高 |

**优点：**
- 去中心化，无单点故障
- 身份可验证、可追溯
- 支持跨系统互认
- 不可篡改的身份历史

**缺点：**
- 链上操作有延迟
- 需要支付 Gas 费（公链）
- 实现复杂度高
- 隐私保护需额外设计

---

### 3.3 Layer 2：身份验证方案

#### 3.3.1 消息签名验证

所有灵隙消息必须签名，签名方式：

```
签名内容 = SHA256(message_id + sender + receiver + payload + timestamp)
签名 = Sign(private_key, 签名内容)
验证 = Verify(public_key, 签名内容, 签名)
```

#### 3.3.2 签名放置位置

| 位置 | 说明 |
|------|------|
| 消息体内 | `signature` 字段 |
| HTTP Header | `X-Synapse-Signature` |
| gRPC Metadata | `x-synapse-signature` |

#### 3.3.3 防重放攻击

```
每个消息有唯一 message_id + timestamp
接收方维护已处理 message_id 缓存（如最近 1 小时）
timestamp 与本地时间差超过 5 分钟 → 拒绝
```

---

### 3.4 Layer 3：信任评分体系

#### 3.4.1 信任分维度

| 维度 | 权重 | 说明 |
|------|------|------|
| 任务完成率 | 30% | 历史任务成功 / 总任务数 |
| 任务质量 | 25% | 结果评分、返工率 |
| 响应速度 | 15% | 平均响应时间 |
| 在线稳定性 | 15% | 在线时长 / 总时长 |
| 历史信誉 | 15% | 其他 Agent 的评价 |

#### 3.4.2 信任分计算

```
trust_score = Σ(维度_i × 权重_i)

范围：0 - 100
等级：
  90-100  S 级  高度可信
  75-89   A 级  可信
  60-74   B 级  一般可信
  40-59   C 级  谨慎使用
  0-39    D 级  不可信
```

#### 3.4.3 信任传递

```
A 信任 B（评分 90）
B 信任 C（评分 85）
A 对 C 的初始信任 = 90 × 85% × 衰减因子 = 约 68
```

**注意**：信任传递有衰减，防止信任污染。

---

### 3.5 区块链适用性决策树

```
是否需要跨组织协作？
├── 否 → 用 PKI 或公钥身份（简单高效）
└── 是 → 是否有共同信任的中心机构？
        ├── 是 → 用 PKI 体系（成熟可靠）
        └── 否 → 是否需要不可篡改的审计？
                ├── 是 → 考虑联盟链 DID
                └── 否 → 公钥身份 + 声誉系统可能够用
```

---

## 4. 方案三：协议缺失内容补全

### 4.1 第一优先级补全（核心基础设施）

#### 4.1.1 Agent 发现协议（ADS - Agent Discovery Service）

**新增消息类型：**

| 消息类型 | 方向 | 说明 |
|---------|------|------|
| `dir:register` | Agent → Directory | 注册 Agent |
| `dir:unregister` | Agent → Directory | 注销 Agent |
| `dir:heartbeat` | Agent → Directory | 心跳 |
| `dir:update_capabilities` | Agent → Directory | 更新能力 |
| `dir:query_by_id` | Agent → Directory | 按 ID 查询 |
| `dir:query_by_capability` | Agent → Directory | 按能力查询 |
| `dir:list` | Agent → Directory | 列表查询 |
| `dir:query_result` | Directory → Agent | 查询结果 |

**新增数据结构：** `AgentDirectoryEntry`, `CapabilityIndex`, `QueryFilter`

#### 4.1.2 身份认证规范

**新增消息类型：**

| 消息类型 | 说明 |
|---------|------|
| `auth:challenge` | 身份挑战 |
| `auth:response` | 挑战响应 |
| `auth:cert_exchange` | 证书交换 |

**新增内容：**
- 标准签名算法列表（Ed25519, ECDSA P-256, RSA 2048）
- 消息签名格式规范
- 防重放攻击机制
- 身份验证流程规范

#### 4.1.3 心跳与存活检测

**新增消息类型：**

| 消息类型 | 说明 |
|---------|------|
| `net:ping` | 存活探测 |
| `net:pong` | 存活响应 |
| `net:offline_notify` | 下线通知 |

**规范内容：**
- 心跳间隔（默认 30 秒）
- 超时判定（连续 3 次未收到 → 离线）
- 离线通知机制

#### 4.1.4 统一错误码体系

**错误分类：**

| 错误码前缀 | 类别 | 示例 |
|-----------|------|------|
| `msg_` | 消息层 | msg_invalid_format, msg_signature_invalid |
| `auth_` | 认证层 | auth_failed, auth_expired, auth_forbidden |
| `task_` | 任务层 | task_not_found, task_timeout, task_cancelled |
| `cap_` | 能力层 | cap_lacking, cap_busy, cap_not_supported |
| `group_` | 群组层 | group_not_found, group_full, group_permission_denied |
| `dir_` | 目录层 | dir_agent_not_found, dir_query_failed |
| `net_` | 网络层 | net_timeout, net_offline, net_unreachable |
| `sys_` | 系统层 | sys_internal_error, sys_not_implemented |

---

### 4.2 第二优先级补全（重要功能）

#### 4.2.1 能力匹配与任务路由

**功能：**
- 智能选择最合适的 Agent 执行任务
- 支持负载均衡（按并发数、响应速度、信任分）
- 支持任务失败自动重试/转发

**新增消息类型：**
- `router:submit_task` - 提交给路由器自动选择执行者
- `router:forward` - 任务转发

#### 4.2.2 全网广播协议

**新增消息类型：**

| 消息类型 | 说明 |
|---------|------|
| `global:broadcast` | 全网广播 |
| `system:broadcast` | 系统内广播 |
| `cap:broadcast` | 能力组广播 |

**规范内容：**
- 广播范围定义
- TTL 与去重机制
- 广播风暴防护

#### 4.2.3 版本协商机制

**功能：**
- Agent 之间协商使用的协议版本
- 向后兼容处理
- 能力降级策略

**新增消息类型：**
- `meta:version_query` - 查询支持的版本
- `meta:version_negotiate` - 版本协商

#### 4.2.4 幂等性保证

**规范内容：**
- 幂等键（Idempotency Key）机制
- 重复消息处理规范
- 任务级幂等 vs 消息级幂等

---

### 4.3 第三优先级补全（增强功能）

#### 4.3.1 流式输出协议

**功能：**
- 长任务实时进度推送
- 生成式 AI 的 token 流式输出
- WebSocket/SSE 传输支持

#### 4.3.2 批量任务协议

**功能：**
- 一次性提交多个同类型任务
- 批量状态查询
- 批量结果收集

#### 4.3.3 支付与激励机制

**功能：**
- 任务定价与结算
- Token 或积分系统
- 智能合约自动结算（区块链场景）

#### 4.3.4 群组发现协议

**功能：**
- 按主题/任务类型查找群组
- 推荐加入合适的群组
- 群组热度/活跃度排名

---

### 4.4 安全相关补全

#### 4.4.1 端到端加密

**规范内容：**
- 密钥协商（ECDH）
- 对称加密载荷（AES-GCM）
- 前向保密（PFS）

#### 4.4.2 权限委托

**功能：**
- Agent A 委托 Agent B 代表自己执行任务
- 委托令牌（Delegation Token）
- 委托范围与时效控制

#### 4.4.3 审计日志标准

**规范内容：**
- 统一审计日志格式
- 关键操作必须记录
- 日志完整性保护（哈希链）

---

## 5. 分阶段实施路线图

### 5.1 Phase 0：基础版（MVP） - 预计 2 周

**目标**：协议可用，能跑通基本流程

**内容：**
- [x] 灵隙点对点任务协议（已完成）
- [x] A2N 群组协作协议（已完成）
- [x] P2A 外部调用协议（已完成）
- [x] 三套协议的 SDK 实现（已完成）

---

### 5.2 Phase 1：发现与身份 - 预计 4 周

**目标**：Agent 能互相找到对方，能验证对方身份

**新增协议模块：**

| 模块 | 说明 | 优先级 |
|------|------|--------|
| Agent 目录服务协议 | 集中式 ADS | P0 |
| 公钥身份规范 | Ed25519 签名验证 | P0 |
| 心跳与存活检测 | 30 秒心跳，3 次超时判定离线 | P0 |
| 统一错误码体系 | 8 大类错误码 | P0 |
| 防重放攻击 | message_id + timestamp | P0 |

**输出物：**
- 新协议文档：`06-agent-discovery.md`
- 新协议文档：`07-authentication.md`
- 代码：`discovery/` 包（目录服务客户端）
- 代码：`auth/` 包（签名验证工具）
- 更新 types 包：新增消息类型和错误码

---

### 5.3 Phase 2：路由与广播 - 预计 4 周

**目标**：支持智能任务路由和全网广播

**新增协议模块：**

| 模块 | 说明 | 优先级 |
|------|------|--------|
| 任务路由协议 | 按能力 + 负载 + 信任分选择执行者 | P1 |
| 全网广播协议 | 基于目录服务的广播转发 | P1 |
| 版本协商机制 | 协议版本兼容 | P1 |
| 幂等性保证 | 幂等键 + 去重 | P1 |

**输出物：**
- 新协议文档：`08-routing-and-broadcast.md`
- 代码：`routing/` 包增强（增加能力路由）
- 更新目录服务：支持广播转发

---

### 5.4 Phase 3：信任与激励 - 预计 6 周

**目标**：建立信任体系，支持规模化协作

**新增协议模块：**

| 模块 | 说明 | 优先级 |
|------|------|--------|
| 信任评分体系 | 5 维度信任分计算 | P2 |
| 流式输出协议 | WebSocket/SSE 流式进度 | P2 |
| 批量任务协议 | 批量提交/查询/收集 | P2 |
| 群组发现协议 | 群组搜索与推荐 | P2 |
| SLA 协议 | 服务等级承诺 | P3 |

**输出物：**
- 新协议文档：`09-trust-and-reputation.md`
- 代码：`trust/` 包（信任评分引擎）

---

### 5.5 Phase 4：高级特性 - 预计 8 周+

**目标**：企业级、生产级完整功能

**新增协议模块：**

| 模块 | 说明 | 优先级 |
|------|------|--------|
| 端到端加密 | ECDH + AES-GCM | P3 |
| 权限委托 | 委托令牌机制 | P3 |
| 支付与激励 | Token/积分系统 | P3 |
| 区块链 DID 集成 | 可选模块 | P4 |
| 审计日志标准 | 统一审计格式 | P3 |
| Gossip 协议 | 分布式发现（可选） | P4 |

---

## 6. 技术选型建议

### 6.1 目录服务存储选型

| 方案 | 适用场景 | 优点 | 缺点 |
|------|---------|------|------|
| **Redis** | 中小规模 | 高性能，支持 TTL | 数据量受限 |
| **PostgreSQL** | 中大规模 | 复杂查询，持久化 | 需运维 |
| **Elasticsearch** | 大规模 + 全文检索 | 强大的搜索能力 | 运维复杂 |

**推荐**：先用 Redis（简单快），规模大了再迁 PostgreSQL。

---

### 6.2 签名算法选型

| 算法 | 安全性 | 性能 | 密钥长度 | 推荐度 |
|------|--------|------|---------|--------|
| Ed25519 | 高 | 快 | 256 位 | ⭐⭐⭐⭐⭐ 首选 |
| ECDSA P-256 | 高 | 中 | 256 位 | ⭐⭐⭐⭐ 兼容 |
| RSA 2048 | 中 | 慢 | 2048 位 | ⭐⭐ 仅兼容 |

**推荐**：默认 Ed25519，需要兼容旧系统时支持 ECDSA。

---

### 6.3 区块链选型（如果需要）

| 场景 | 推荐方案 | 说明 |
|------|---------|------|
| 企业内部 | **私有链（Hyperledger Fabric）** | 可控，高性能，无 Gas 费 |
| 行业联盟 | **联盟链（FISCO BCOS / ChainMaker）** | 多机构共建，合规 |
| 开放生态 | **公链（以太坊 / Solana）** | 完全开放，需 Gas 费 |
| 简单原型 | **模拟链（数据库模拟）** | 先验证逻辑，再上真链 |

**推荐**：90% 的场景用不到真区块链，先用数据库模拟验证业务逻辑。

---

## 7. 总结与建议

### 7.1 核心建议

1. **先集中后分布**：先用集中式目录服务，简单高效；规模大了再考虑分布式
2. **先公钥后区块链**：先用公钥身份解决 80% 的问题，真的需要了再上链
3. **先 MVP 后完善**：先跑通核心流程，再逐步加高级功能
4. **标准接口可替换**：目录服务、身份系统都做成可插拔的，方便未来升级

### 7.2 下一步行动

| 序号 | 行动 | 负责人 | 产出 |
|------|------|--------|------|
| 1 | 评审本方案，确认 Phase 1 范围 | 架构组 | 确认后的方案 |
| 2 | 设计目录服务 API 详细规范 | 协议组 | `06-agent-discovery.md` |
| 3 | 设计身份认证详细规范 | 协议组 | `07-authentication.md` |
| 4 | 实现目录服务原型 | 开发组 | 可运行的 ADS 服务 |
| 5 | 更新 SDK 支持发现和认证 | 开发组 | 新版 SDK |

---

## 附录：相关文档索引

| 文档 | 说明 |
|------|------|
| [01-synapse-raw-protocol.md](./01-synapse-raw-protocol.md) | 灵隙原始协议（Synapse Raw Protocol）（纲领） |
| [02-a2a-protocol.md](./02-a2a-protocol.md) | A2A 协议（P2P 任务） |
| [03-a2n-protocol.md](./03-a2n-protocol.md) | A2N 协议（群组协作） |
| [04-p2a-protocol.md](./04-p2a-protocol.md) | P2A 协议（外部调用） |
| [05-sdk-implementation.md](./05-sdk-implementation.md) | SDK 实现说明 |
| **本文档** | **解决方案白皮书** |