synapse/docs/v0/01-synapse-raw-protocol.md

灵隙原始协议（Synapse Raw Protocol）

版本：1.0.0
状态：草案
类型：纲领性文档

---

1. 协议愿景

灵隙（Synapse，原 Agent-to-Agent）协议旨在定义一套通用的、可扩展的智能体间通信标准，使不同系统、不同厂商、不同能力的智能体能够在统一的协议框架下进行协作、交易与能力组合。

本协议是灵隙协议族（Synapse Protocol Suite）的原始纲领，定义核心设计理念、架构原则与术语体系，为所有衍生协议提供顶层指导。

---

2. 核心设计理念

2.1 去中心化对等（Peer-to-Peer）

• 所有 Agent 在协议层面地位平等，无中心化控制节点
• 每个 Agent 既是服务提供者，也是服务消费者
• Agent 间直接通信，不依赖中间 broker（传输层可选择不同实现）

2.2 能力驱动（Capability-Driven）

• 通信以能力为核心，而非以身份为核心
• Agent 声明自身能力，按需发现与调用
• 能力可组合、可分解、可升级

2.3 任务导向（Task-Oriented）

• 所有交互围绕"任务"展开
• 任务有明确的生命周期、状态机与超时机制
• 任务支持拆分、合并、委派与协作

2.4 人类可介入（Human-in-the-Loop）

• 协议原生支持人类介入决策
• Agent 可主动请求人类判断
• 人类决策优先于 Agent 自动决策
• 支持多级升级（escalation）机制

2.5 群组协作（Group Collaboration）

• 支持多 Agent 组成临时或永久群组
• 群组内有角色分工与权限控制
• 支持任务拆分-执行-合并的 MapReduce 模式
• 支持投票、共识等群体决策机制

2.6 传输无关（Transport Agnostic）

• 协议语义与底层传输分离
• 支持 HTTP/2、gRPC、WebSocket、消息队列等多种传输
• 支持回调（Callback）、轮询（Polling）、同步（Sync）、混合（Hybrid）等多种交互模式

2.7 安全可信（Secure & Trustworthy）

• 消息级签名与验证
• Agent 身份认证与信任等级
• 支持加密传输
• 可审计、可追溯

---

3. 协议分层架构

┌─────────────────────────────────────────┐
│              应用层 (Application)        │
│  业务逻辑、工作流、领域特定逻辑           │
├─────────────────────────────────────────┤
│              协议层 (Protocol)           │
├─────────────┬───────────────────────────┤
│  A2A 协议 │  A2N 组群协议             │  ← 本协议族
│  (P2P)      │  (Group)                 │
├─────────────┴───────────────────────────┤
│              传输层 (Transport)          │
│  HTTP / gRPC / WebSocket / MQ ...       │
├─────────────────────────────────────────┤
│              网络层 (Network)            │
│  TCP / UDP / QUIC ...                   │
└─────────────────────────────────────────┘

3.1 协议族构成

协议名称	缩写	描述	适用场景
灵隙原始协议（Synapse Raw Protocol）	A2A-Raw	顶层纲领，定义理念、术语、原则	指导所有协议设计
A2A 协议	A2A-Base	点对点任务协作协议	两个 Agent 间的任务交互
A2N 组群协议	A2N-Group	多 Agent 群组协作协议	多个 Agent 协同完成任务
P2A 调用协议	P2A-Caller	非 Agent 调用者接入协议	普通服务/前端调用 Agent 能力

---

4. 核心概念与术语

4.1 Agent（智能体）

能够自主感知环境、做出决策并执行动作的计算实体。

属性：

• agent_id：Agent 唯一标识
• system_id：所属系统标识
• endpoint：通信端点地址
• capabilities：能力清单
• trust_level：信任等级

4.2 Task（任务）

Agent 间协作的基本单位，具有明确的输入、输出与生命周期。

属性：

• task_id：任务唯一标识
• task_type：任务类型
• payload：任务载荷
• status：任务状态
• priority：优先级
• deadline：截止时间

4.3 Message（消息）

Agent 间通信的基本单位。

属性：

• message_id：消息唯一标识
• type：消息类型
• sender：发送方
• receiver：接收方（P2P）
• group_id：群组标识（群组）
• payload：消息载荷
• correlation_id：关联标识（用于请求-响应关联）
• timestamp：时间戳
• signature：签名

4.4 Capability（能力）

Agent 能够执行的任务类型的声明。

属性：

• type：能力对应的任务类型
• name：能力名称
• description：能力描述
• input_schema：输入参数 schema
• output_schema：输出结果 schema
• estimated_time：预估耗时

4.5 Group（群组）

由多个 Agent 组成的协作单元。

属性：

• group_id：群组唯一标识
• name：群组名称
• topology：拓扑结构
• members：成员列表
• roles：角色定义
• status：群组状态

4.6 Human-in-the-Loop（人在回路）

在 Agent 协作过程中，人类可介入进行决策的机制。

关键概念：

• escalation：升级（将问题提交给人类）
• decision：决策（人类做出的判断）
• resume：恢复（人类决策后继续执行）

---

5. 设计原则

5.1 简约性（Simplicity）

• 核心机制保持简单
• 复杂功能通过组合基础机制实现
• 可选功能通过能力声明来协商

5.2 可扩展性（Extensibility）

• 消息类型可扩展
• 能力类型可扩展
• 传输方式可扩展
• 通过版本号与能力协商保证向后兼容

5.3 容错性（Fault Tolerance）

• 网络不可靠是常态
• 消息可能丢失、重复、延迟
• Agent 可能故障、离线
• 协议必须有重试、超时、降级机制

5.4 可观测性（Observability）

• 所有交互可追踪
• 任务状态可查询
• 支持日志、指标、链路追踪

5.5 互操作性（Interoperability）

• 不同语言、不同框架的 Agent 可互操作
• 协议规范优先于具体实现
• 提供标准测试用例验证兼容性

---

6. 消息模型总则

6.1 统一消息信封

所有协议共享统一的消息信封结构，具体载荷由消息类型决定。

UnifiedSynapseMessage
├── id              // 消息ID
├── version         // 协议版本
├── type            // 消息类型
├── sender          // 发送方 AgentEndpoint
├── receiver?       // 接收方（P2P 时）
├── group_id?       // 群组ID（群组时）
├── correlation_id  // 关联ID
├── reply_to?       // 回复的消息ID
├── payload         // 消息载荷（JSON）
├── priority?       // 优先级
├── signature?      // 签名
├── timestamp       // 发送时间
└── expires_at?     // 过期时间

6.2 消息命名规范

• 使用 领域:动作 格式
• 全小写，用下划线分隔
• 示例：p2p:task_request, group:create, hil:decision

6.3 请求-响应模式

• 请求消息必须携带唯一 id
• 响应消息通过 reply_to 关联请求
• 支持 ACK/NACK 机制
• 超时未收到响应应重试或报错

---

7. 任务生命周期总则

7.1 状态机

         ┌──────────┐
         │  pending  │  待确认
         └────┬─────┘
              │ 确认/拒绝
        ┌─────┴──────┐
        ▼            ▼
   ┌─────────┐  ┌──────────┐
   │confirmed│  │ rejected │  已拒绝（终态）
   └────┬────┘  └──────────┘
        │ 开始执行
        ▼
   ┌──────────┐
   │executing │  执行中
   └────┬─────┘
        │ 信息缺失
   ┌────▼─────┐
   │info_needed│ 需要信息
   └────┬─────┘
        │ 信息补充
        ▼
   回到 executing
        │
        ├──────────────┐
        │ 需人类决策    │
        ▼              ▼
   ┌──────────┐  ┌───────────┐
   │need_human│  │ 各种终态   │
   └────┬─────┘  └───────────┘
        │ 人类决策
        ▼
   回到 executing
        │
   ┌────┴────┬─────────┐
   ▼         ▼         ▼
completed  failed  cancelled
（完成）   （失败）  （取消）

7.2 终态

• completed：成功完成
• failed：执行失败
• cancelled：被取消
• rejected：被拒绝

---

8. 安全模型总则

8.1 身份认证

• 每个 Agent 有唯一身份
• 支持 HMAC、JWT、OAuth2 等多种认证方式
• 信任等级机制

8.2 消息完整性

• 消息签名机制
• 防止篡改与伪造

8.3 机密性

• 支持端到端加密
• 敏感载荷加密传输

8.4 访问控制

• 基于信任等级的权限控制
• 群组内基于角色的权限控制

---

9. 非目标

以下内容不在本原始协议的讨论范围内：

1. 具体传输协议的实现细节 - 由各传输层实现定义
2. 特定领域的任务类型 - 由应用层或领域扩展定义
3. Agent 内部实现架构 - 仅定义对外接口与行为
4. 具体编程语言绑定 - 语言无关，可多语言实现
5. UI/UX 设计 - 人机界面不在协议范围内

---

10. 参考实现

本协议族的参考实现位于：dp-headless/synapse/

模块	对应协议	文件路径
types 包	公共类型定义	types/
p2p 包	A2A 协议	p2p/
group 包	A2N 组群协议	group/
externalapi 包	P2A 调用协议	externalapi/
sdk 包	P2A 客户端 SDK	sdk/

---

附录 A：协议演进

本原始协议作为顶层指导，保持相对稳定。各具体协议可独立版本化演进，但需遵循本协议定义的核心原则。

版本历史：

• v1.0.0：初始版本，定义核心概念与设计原则