329 lines
10 KiB
Markdown
329 lines
10 KiB
Markdown
# 灵隙原始协议（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：初始版本，定义核心概念与设计原则
|