灵隙(synapse) v1.0.0 版本
This commit is contained in:
@@ -51,16 +51,16 @@ v1 版本文档分为三层:
|
||||
|
||||
每个文档对应一个独立的功能模块:
|
||||
|
||||
| 文档 | 对应模块 |
|
||||
|--------------------------------------------------|-----------------------------|
|
||||
| [components.md](../implement/components.md) | 七大组件层(灵脉/灵玺/灵鉴/灵泊/灵瞰/灵衡/灵枢) |
|
||||
| [content-system.md](../implement/content-system.md) | 内容类型系统 |
|
||||
| [capabilities-system.md](../implement/capabilities-system.md) | 能力声明系统 |
|
||||
| [grpc-transport.md](../implement/grpc-transport.md) | gRPC 传输协议 |
|
||||
| [hil-mechanism.md](../implement/hil-mechanism.md) | HiL 三级升级机制 |
|
||||
| [error-codes.md](../implement/error-codes.md) | 数字分段错误码系统 |
|
||||
| [message-extensions.md](../implement/message-extensions.md) | 消息扩展字段 |
|
||||
| [transport-modes.md](../implement/transport-modes.md) | 传输模式定义 |
|
||||
| 文档 | 对应模块 |
|
||||
|--------------------------------------------------------------|-----------------------------|
|
||||
| [components.md](../02-guide/components.md) | 七大组件层(灵脉/灵玺/灵鉴/灵泊/灵瞰/灵衡/灵枢) |
|
||||
| [content-system.md](../02-guide/content-system.md) | 内容类型系统 |
|
||||
| [capabilities-system.md](../02-guide/capabilities-system.md) | 能力声明系统 |
|
||||
| [grpc-transport.md](../02-guide/grpc-transport.md) | gRPC 传输协议 |
|
||||
| [hil-mechanism.md](../02-guide/hil-mechanism.md) | HiL 三级升级机制 |
|
||||
| [error-codes.md](../02-guide/error-codes.md) | 数字分段错误码系统 |
|
||||
| [message-extensions.md](../02-guide/message-extensions.md) | 消息扩展字段 |
|
||||
| [transport-modes.md](../02-guide/transport-modes.md) | 传输模式定义 |
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -16,23 +16,23 @@
|
||||
|
||||
### 2.1 核心功能
|
||||
|
||||
| 功能 | 说明 |
|
||||
|-----|------|
|
||||
| 统一消息信封 | 所有协议共用的消息格式 |
|
||||
| 身份标识 | Agent 端点定义 |
|
||||
| 时间戳 | 统一时间格式(RFC3339) |
|
||||
| 消息签名 | HMAC 签名验证机制 |
|
||||
| 关联机制 | correlation_id / reply_to 消息关联 |
|
||||
| 协议版本 | 版本标识与兼容性 |
|
||||
| 功能 | 说明 |
|
||||
|--------|--------------------------------|
|
||||
| 统一消息信封 | 所有协议共用的消息格式 |
|
||||
| 身份标识 | Agent 端点定义 |
|
||||
| 时间戳 | 统一时间格式(RFC3339) |
|
||||
| 消息签名 | HMAC 签名验证机制 |
|
||||
| 关联机制 | correlation_id / reply_to 消息关联 |
|
||||
| 协议版本 | 版本标识与兼容性 |
|
||||
|
||||
### 2.2 扩展功能
|
||||
|
||||
| 功能 | 说明 |
|
||||
|-----|------|
|
||||
| 会话关联 | conversation_id 多轮对话关联 |
|
||||
| 消息存活 | TTL 消息过期机制 |
|
||||
| 广播标识 | broadcast 广播消息标记 |
|
||||
| 加密标识 | encrypt 消息加密标记 |
|
||||
| 功能 | 说明 |
|
||||
|------|----------------------------|
|
||||
| 会话关联 | conversation_id 多轮对话关联 |
|
||||
| 消息存活 | TTL 消息过期机制 |
|
||||
| 广播标识 | broadcast 广播消息标记 |
|
||||
| 加密标识 | encrypt 消息加密标记 |
|
||||
| 签名算法 | signature_algorithm 签名算法声明 |
|
||||
|
||||
---
|
||||
@@ -43,51 +43,51 @@
|
||||
|
||||
所有协议消息必须使用统一信封格式:
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|:----:|------|
|
||||
| `id` | string | ✓ | 消息唯一标识(UUID) |
|
||||
| `version` | string | ✓ | 协议版本(如 "1.0.0") |
|
||||
| `type` | string | ✓ | 消息类型(格式:`协议:类型`,如 `p2p:task_request`) |
|
||||
| `sender` | AgentEndpoint | ✓ | 发送方端点 |
|
||||
| `receiver` | AgentEndpoint | - | 接收方端点(广播时可为空) |
|
||||
| `payload` | object | ✓ | 消息载荷(具体结构由消息类型定义) |
|
||||
| `timestamp` | string | ✓ | 时间戳(RFC3339 格式) |
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|-------------|---------------|:--:|---------------------------------------|
|
||||
| `id` | string | ✓ | 消息唯一标识(UUID) |
|
||||
| `version` | string | ✓ | 协议版本(如 "1.0.0") |
|
||||
| `type` | string | ✓ | 消息类型(格式:`协议:类型`,如 `p2p:task_request`) |
|
||||
| `sender` | AgentEndpoint | ✓ | 发送方端点 |
|
||||
| `receiver` | AgentEndpoint | - | 接收方端点(广播时可为空) |
|
||||
| `payload` | object | ✓ | 消息载荷(具体结构由消息类型定义) |
|
||||
| `timestamp` | string | ✓ | 时间戳(RFC3339 格式) |
|
||||
|
||||
### 3.2 关联字段
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|:----:|------|
|
||||
| `correlation_id` | string | - | 关联 ID(用于请求-响应关联) |
|
||||
| `reply_to` | string | - | 回复的消息 ID |
|
||||
| `group_id` | string | - | 群组 ID(群组消息必填) |
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------------------|--------|:--:|------------------|
|
||||
| `correlation_id` | string | - | 关联 ID(用于请求-响应关联) |
|
||||
| `reply_to` | string | - | 回复的消息 ID |
|
||||
| `group_id` | string | - | 群组 ID(群组消息必填) |
|
||||
|
||||
### 3.3 安全字段
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|:----:|------|
|
||||
| `signature` | string | - | HMAC 签名(签名算法由 signature_algorithm 指定) |
|
||||
| `signature_algorithm` | string | - | 签名算法(默认 "HMAC-SHA256") |
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|-----------------------|--------|:--:|---------------------------------------|
|
||||
| `signature` | string | - | HMAC 签名(签名算法由 signature_algorithm 指定) |
|
||||
| `signature_algorithm` | string | - | 签名算法(默认 "HMAC-SHA256") |
|
||||
|
||||
### 3.4 扩展字段
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `conversation_id` | string | 会话 ID(多轮对话关联) |
|
||||
| `ttl` | integer | 消息存活时间(秒) |
|
||||
| `broadcast` | boolean | 是否广播消息 |
|
||||
| `encrypt` | boolean | payload 是否加密 |
|
||||
| 字段 | 类型 | 说明 |
|
||||
|-------------------|---------|---------------|
|
||||
| `conversation_id` | string | 会话 ID(多轮对话关联) |
|
||||
| `ttl` | integer | 消息存活时间(秒) |
|
||||
| `broadcast` | boolean | 是否广播消息 |
|
||||
| `encrypt` | boolean | payload 是否加密 |
|
||||
|
||||
### 3.5 Agent 端点
|
||||
|
||||
Agent 身份标识结构:
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|:----:|------|
|
||||
| `agent_id` | string | ✓ | Agent 唯一标识 |
|
||||
| `agent_name` | string | - | Agent 名称 |
|
||||
| `system_id` | string | ✓ | 所属系统标识 |
|
||||
| `endpoint` | string | ✓ | 回调端点 URL |
|
||||
| `version` | string | - | Agent 版本 |
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|--------------|--------|:--:|------------|
|
||||
| `agent_id` | string | ✓ | Agent 唯一标识 |
|
||||
| `agent_name` | string | - | Agent 名称 |
|
||||
| `system_id` | string | ✓ | 所属系统标识 |
|
||||
| `endpoint` | string | ✓ | 回调端点 URL |
|
||||
| `version` | string | - | Agent 版本 |
|
||||
|
||||
---
|
||||
|
||||
@@ -96,6 +96,7 @@ Agent 身份标识结构:
|
||||
### 4.1 签名算法
|
||||
|
||||
支持算法:
|
||||
|
||||
- `HMAC-SHA256`(默认)
|
||||
- `HMAC-SHA512`
|
||||
|
||||
@@ -112,6 +113,7 @@ signature_content = sender_id | receiver_id | timestamp | payload_json
|
||||
### 4.3 签名验证
|
||||
|
||||
接收方必须:
|
||||
|
||||
1. 提取 sender 的认证密钥
|
||||
2. 使用相同算法重新计算签名
|
||||
3. 比对签名是否一致
|
||||
@@ -120,12 +122,12 @@ signature_content = sender_id | receiver_id | timestamp | payload_json
|
||||
|
||||
## 5. 协议类型前缀
|
||||
|
||||
| 前缀 | 协议 | 说明 |
|
||||
|------|------|------|
|
||||
| `p2p:` | A2A 协议 | 点对点消息 |
|
||||
| `group:` | A2N 协议 | 群组内消息 |
|
||||
| `inter_group:` | A2N 协议 | 跨群组消息 |
|
||||
| `caller:` | P2A 协议 | 外部调用消息 |
|
||||
| 前缀 | 协议 | 说明 |
|
||||
|----------------|--------|--------|
|
||||
| `p2p:` | A2A 协议 | 点对点消息 |
|
||||
| `group:` | A2N 协议 | 群组内消息 |
|
||||
| `inter_group:` | A2N 协议 | 跨群组消息 |
|
||||
| `caller:` | P2A 协议 | 外部调用消息 |
|
||||
|
||||
---
|
||||
|
||||
@@ -134,6 +136,7 @@ signature_content = sender_id | receiver_id | timestamp | payload_json
|
||||
格式:`协议前缀:消息类型`
|
||||
|
||||
示例:
|
||||
|
||||
- `p2p:task_request` - A2A 协议的任务请求
|
||||
- `group:vote` - A2N 协议的投票消息
|
||||
- `inter_group:escalate` - A2N 协议的跨群组升级
|
||||
|
||||
@@ -13,6 +13,7 @@
|
||||
A2A 协议定义两个 Agent 之间进行点对点任务协作的规范,包括任务提交、进度同步、信息补全、人类介入、能力发现等核心交互。
|
||||
|
||||
**适用场景**:
|
||||
|
||||
- 单个任务请求与响应
|
||||
- 任务状态实时同步
|
||||
- 任务取消
|
||||
@@ -20,6 +21,7 @@ A2A 协议定义两个 Agent 之间进行点对点任务协作的规范,包括
|
||||
- 人类介入决策
|
||||
|
||||
**非适用场景**:
|
||||
|
||||
- 多 Agent 群组协作(参见 A2N 协议)
|
||||
- 非 Agent 调用方接入(参见 P2A 协议)
|
||||
|
||||
@@ -29,44 +31,44 @@ A2A 协议定义两个 Agent 之间进行点对点任务协作的规范,包括
|
||||
|
||||
### 2.1 任务管理
|
||||
|
||||
| 功能 | 说明 |
|
||||
|-----|------|
|
||||
| 任务提交 | 请求方向执行方提交任务 |
|
||||
| 任务确认 | 执行方接受任务 |
|
||||
| 功能 | 说明 |
|
||||
|------|---------------|
|
||||
| 任务提交 | 请求方向执行方提交任务 |
|
||||
| 任务确认 | 执行方接受任务 |
|
||||
| 任务拒绝 | 执行方拒绝任务(附带原因) |
|
||||
| 任务取消 | 请求方中途取消任务 |
|
||||
| 任务进度 | 执行方实时上报进度 |
|
||||
| 任务完成 | 执行方上报成功结果 |
|
||||
| 任务失败 | 执行方上报失败原因 |
|
||||
| 任务取消 | 请求方中途取消任务 |
|
||||
| 任务进度 | 执行方实时上报进度 |
|
||||
| 任务完成 | 执行方上报成功结果 |
|
||||
| 任务失败 | 执行方上报失败原因 |
|
||||
|
||||
### 2.2 信息补全
|
||||
|
||||
| 功能 | 说明 |
|
||||
|-----|------|
|
||||
| 功能 | 说明 |
|
||||
|------|------------------|
|
||||
| 信息请求 | 执行方发现缺少必要信息时请求补充 |
|
||||
| 信息提供 | 请求方提供补充信息 |
|
||||
| 信息提供 | 请求方提供补充信息 |
|
||||
|
||||
### 2.3 人类介入(HiL)
|
||||
|
||||
| 功能 | 说明 |
|
||||
|-----|------|
|
||||
| HiL 请求 | 执行方请求人类决策 |
|
||||
| 功能 | 说明 |
|
||||
|--------|-------------|
|
||||
| HiL 请求 | 执行方请求人类决策 |
|
||||
| HiL 响应 | 请求方返回人类决策结果 |
|
||||
|
||||
### 2.4 能力发现
|
||||
|
||||
| 功能 | 说明 |
|
||||
|-----|------|
|
||||
| 功能 | 说明 |
|
||||
|------|----------------|
|
||||
| 能力查询 | 查询对方支持的任务类型和能力 |
|
||||
| 能力响应 | 返回能力清单 |
|
||||
| 能力响应 | 返回能力清单 |
|
||||
|
||||
### 2.5 保活与确认
|
||||
|
||||
| 功能 | 说明 |
|
||||
|-----|------|
|
||||
| 心跳 | 双向心跳保活 |
|
||||
| ACK | 任务级确认 |
|
||||
| 消息 ACK | 消息级确认 |
|
||||
| 功能 | 说明 |
|
||||
|---------|---------------|
|
||||
| 心跳 | 双向心跳保活 |
|
||||
| ACK | 任务级确认 |
|
||||
| 消息 ACK | 消息级确认 |
|
||||
| 消息 NACK | 消息级否定确认(附带错误) |
|
||||
|
||||
---
|
||||
@@ -77,45 +79,45 @@ A2A 协议定义两个 Agent 之间进行点对点任务协作的规范,包括
|
||||
|
||||
### 3.1 任务类消息
|
||||
|
||||
| 消息类型 | 方向 | 说明 |
|
||||
|---------|------|------|
|
||||
| `p2p:task_request` | 请求方 → 执行方 | 提交任务请求 |
|
||||
| `p2p:task_confirm` | 执行方 → 请求方 | 确认接受任务 |
|
||||
| `p2p:task_reject` | 执行方 → 请求方 | 拒绝任务 |
|
||||
| 消息类型 | 方向 | 说明 |
|
||||
|--------------------------|-----------|--------|
|
||||
| `p2p:task_request` | 请求方 → 执行方 | 提交任务请求 |
|
||||
| `p2p:task_confirm` | 执行方 → 请求方 | 确认接受任务 |
|
||||
| `p2p:task_reject` | 执行方 → 请求方 | 拒绝任务 |
|
||||
| `p2p:task_status_update` | 执行方 → 请求方 | 任务进度更新 |
|
||||
| `p2p:task_complete` | 执行方 → 请求方 | 任务完成 |
|
||||
| `p2p:task_failed` | 执行方 → 请求方 | 任务失败 |
|
||||
| `p2p:task_cancel` | 请求方 → 执行方 | 取消任务 |
|
||||
| `p2p:task_ack` | 双向 | 任务级确认 |
|
||||
| `p2p:task_complete` | 执行方 → 请求方 | 任务完成 |
|
||||
| `p2p:task_failed` | 执行方 → 请求方 | 任务失败 |
|
||||
| `p2p:task_cancel` | 请求方 → 执行方 | 取消任务 |
|
||||
| `p2p:task_ack` | 双向 | 任务级确认 |
|
||||
|
||||
### 3.2 信息类消息
|
||||
|
||||
| 消息类型 | 方向 | 说明 |
|
||||
|---------|------|------|
|
||||
| `p2p:task_need_info` | 执行方 → 请求方 | 请求补充信息 |
|
||||
| 消息类型 | 方向 | 说明 |
|
||||
|--------------------------|-----------|--------|
|
||||
| `p2p:task_need_info` | 执行方 → 请求方 | 请求补充信息 |
|
||||
| `p2p:task_info_provided` | 请求方 → 执行方 | 提供补充信息 |
|
||||
|
||||
### 3.3 HiL 类消息
|
||||
|
||||
| 消息类型 | 方向 | 说明 |
|
||||
|---------|------|------|
|
||||
| 消息类型 | 方向 | 说明 |
|
||||
|-----------------------|-----------|--------|
|
||||
| `p2p:task_need_human` | 执行方 → 请求方 | 请求人类介入 |
|
||||
| `p2p:human_decision` | 请求方 → 执行方 | 人类决策结果 |
|
||||
| `p2p:human_decision` | 请求方 → 执行方 | 人类决策结果 |
|
||||
|
||||
### 3.4 能力类消息
|
||||
|
||||
| 消息类型 | 方向 | 说明 |
|
||||
|---------|------|------|
|
||||
| `p2p:capability_query` | 双向 | 查询对方能力 |
|
||||
| 消息类型 | 方向 | 说明 |
|
||||
|---------------------------|----|--------|
|
||||
| `p2p:capability_query` | 双向 | 查询对方能力 |
|
||||
| `p2p:capability_response` | 双向 | 返回能力清单 |
|
||||
|
||||
### 3.5 保活与确认类消息
|
||||
|
||||
| 消息类型 | 方向 | 说明 |
|
||||
|---------|------|------|
|
||||
| `p2p:heartbeat` | 双向 | 心跳保活 |
|
||||
| `p2p:ack` | 双向 | 通用确认 |
|
||||
| `p2p:nack` | 双向 | 通用否定确认 |
|
||||
| 消息类型 | 方向 | 说明 |
|
||||
|-----------------|----|--------|
|
||||
| `p2p:heartbeat` | 双向 | 心跳保活 |
|
||||
| `p2p:ack` | 双向 | 通用确认 |
|
||||
| `p2p:nack` | 双向 | 通用否定确认 |
|
||||
|
||||
---
|
||||
|
||||
@@ -123,22 +125,22 @@ A2A 协议定义两个 Agent 之间进行点对点任务协作的规范,包括
|
||||
|
||||
### 4.1 状态定义
|
||||
|
||||
| 状态 | 说明 |
|
||||
|------|------|
|
||||
| `idle` | 空闲(初始状态) |
|
||||
| `pending` | 待确认(已发送请求) |
|
||||
| `confirmed` | 已确认(执行方接受) |
|
||||
| `executing` | 执行中 |
|
||||
| `info_needed` | 需要信息 |
|
||||
| `info_provided` | 信息已提供 |
|
||||
| `need_human` | 需要人类介入 |
|
||||
| `human_deciding` | 人类决策中 |
|
||||
| `human_approved` | 人类已批准 |
|
||||
| `human_rejected` | 人类已拒绝 |
|
||||
| `completed` | 已完成(终态) |
|
||||
| `failed` | 已失败(终态) |
|
||||
| `cancelled` | 已取消(终态) |
|
||||
| `rejected` | 已拒绝(终态) |
|
||||
| 状态 | 说明 |
|
||||
|------------------|------------|
|
||||
| `idle` | 空闲(初始状态) |
|
||||
| `pending` | 待确认(已发送请求) |
|
||||
| `confirmed` | 已确认(执行方接受) |
|
||||
| `executing` | 执行中 |
|
||||
| `info_needed` | 需要信息 |
|
||||
| `info_provided` | 信息已提供 |
|
||||
| `need_human` | 需要人类介入 |
|
||||
| `human_deciding` | 人类决策中 |
|
||||
| `human_approved` | 人类已批准 |
|
||||
| `human_rejected` | 人类已拒绝 |
|
||||
| `completed` | 已完成(终态) |
|
||||
| `failed` | 已失败(终态) |
|
||||
| `cancelled` | 已取消(终态) |
|
||||
| `rejected` | 已拒绝(终态) |
|
||||
|
||||
### 4.2 状态流转
|
||||
|
||||
@@ -236,86 +238,86 @@ idle → pending → confirmed → executing → completed
|
||||
|
||||
### 6.1 task_request 载荷
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|:----:|------|
|
||||
| `task_id` | string | ✓ | 任务唯一标识(请求方生成) |
|
||||
| `task_type` | string | ✓ | 任务类型 |
|
||||
| `payload` | object | ✓ | 任务参数(结构由 task_type 决定) |
|
||||
| `priority` | string | - | 优先级:`low`/`normal`/`high`/`urgent` |
|
||||
| `transport_preferences` | object | - | 传输偏好(回调/轮询等) |
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|-------------------------|--------|:--:|------------------------------------|
|
||||
| `task_id` | string | ✓ | 任务唯一标识(请求方生成) |
|
||||
| `task_type` | string | ✓ | 任务类型 |
|
||||
| `payload` | object | ✓ | 任务参数(结构由 task_type 决定) |
|
||||
| `priority` | string | - | 优先级:`low`/`normal`/`high`/`urgent` |
|
||||
| `transport_preferences` | object | - | 传输偏好(回调/轮询等) |
|
||||
|
||||
### 6.2 task_confirm 载荷
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|:----:|------|
|
||||
| `task_id` | string | ✓ | 任务标识 |
|
||||
| `estimated_time` | string | - | 预估耗时(如 "30s-2min") |
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------------------|--------|:--:|--------------------|
|
||||
| `task_id` | string | ✓ | 任务标识 |
|
||||
| `estimated_time` | string | - | 预估耗时(如 "30s-2min") |
|
||||
|
||||
### 6.3 task_reject 载荷
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|:----:|------|
|
||||
| `task_id` | string | ✓ | 任务标识 |
|
||||
| `reason` | object | ✓ | 拒绝原因(含错误码和描述) |
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|-----------|--------|:--:|---------------|
|
||||
| `task_id` | string | ✓ | 任务标识 |
|
||||
| `reason` | object | ✓ | 拒绝原因(含错误码和描述) |
|
||||
|
||||
### 6.4 task_status_update 载荷
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|:----:|------|
|
||||
| `task_id` | string | ✓ | 任务标识 |
|
||||
| `status` | string | ✓ | 当前状态 |
|
||||
| `progress` | integer | - | 进度百分比(0-100) |
|
||||
| `message` | string | - | 状态说明 |
|
||||
| `eta` | string | - | 预估完成时间 |
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------------|---------|:--:|--------------|
|
||||
| `task_id` | string | ✓ | 任务标识 |
|
||||
| `status` | string | ✓ | 当前状态 |
|
||||
| `progress` | integer | - | 进度百分比(0-100) |
|
||||
| `message` | string | - | 状态说明 |
|
||||
| `eta` | string | - | 预估完成时间 |
|
||||
|
||||
### 6.5 task_complete 载荷
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|:----:|------|
|
||||
| `task_id` | string | ✓ | 任务标识 |
|
||||
| `result` | object | ✓ | 任务结果(结构由 task_type 决定) |
|
||||
| `summary` | string | - | 结果摘要 |
|
||||
| `metadata` | object | - | 结果元数据 |
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------------|--------|:--:|------------------------|
|
||||
| `task_id` | string | ✓ | 任务标识 |
|
||||
| `result` | object | ✓ | 任务结果(结构由 task_type 决定) |
|
||||
| `summary` | string | - | 结果摘要 |
|
||||
| `metadata` | object | - | 结果元数据 |
|
||||
|
||||
### 6.6 task_failed 载荷
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|:----:|------|
|
||||
| `task_id` | string | ✓ | 任务标识 |
|
||||
| `error` | object | ✓ | 错误信息(错误码 + 描述 + 详情) |
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|-----------|--------|:--:|---------------------|
|
||||
| `task_id` | string | ✓ | 任务标识 |
|
||||
| `error` | object | ✓ | 错误信息(错误码 + 描述 + 详情) |
|
||||
|
||||
### 6.7 task_need_info 载荷
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|:----:|------|
|
||||
| `task_id` | string | ✓ | 任务标识 |
|
||||
| `missing_fields` | array | ✓ | 缺失的字段列表 |
|
||||
| `reason` | string | ✓ | 缺失原因 |
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------------------|--------|:--:|---------|
|
||||
| `task_id` | string | ✓ | 任务标识 |
|
||||
| `missing_fields` | array | ✓ | 缺失的字段列表 |
|
||||
| `reason` | string | ✓ | 缺失原因 |
|
||||
|
||||
### 6.8 task_info_provided 载荷
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|:----:|------|
|
||||
| `task_id` | string | ✓ | 任务标识 |
|
||||
| `provided_info` | object | ✓ | 补充的信息 |
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|-----------------|--------|:--:|-------|
|
||||
| `task_id` | string | ✓ | 任务标识 |
|
||||
| `provided_info` | object | ✓ | 补充的信息 |
|
||||
|
||||
### 6.9 task_need_human 载荷
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|:----:|------|
|
||||
| `task_id` | string | ✓ | 任务标识 |
|
||||
| `escalation_level` | integer | ✓ | 升级级别(1/2/3) |
|
||||
| `reason` | object | ✓ | 介入原因 |
|
||||
| `options` | array | - | 可选方案列表 |
|
||||
| `suggested_value` | object | - | Agent 建议值 |
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|--------------------|---------|:--:|-------------|
|
||||
| `task_id` | string | ✓ | 任务标识 |
|
||||
| `escalation_level` | integer | ✓ | 升级级别(1/2/3) |
|
||||
| `reason` | object | ✓ | 介入原因 |
|
||||
| `options` | array | - | 可选方案列表 |
|
||||
| `suggested_value` | object | - | Agent 建议值 |
|
||||
|
||||
### 6.10 human_decision 载荷
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|:----:|------|
|
||||
| `task_id` | string | ✓ | 任务标识 |
|
||||
| `decision` | object | ✓ | 决策内容 |
|
||||
| `decided_by` | object | ✓ | 决策者信息(用户 ID + 角色) |
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|--------------|--------|:--:|-------------------|
|
||||
| `task_id` | string | ✓ | 任务标识 |
|
||||
| `decision` | object | ✓ | 决策内容 |
|
||||
| `decided_by` | object | ✓ | 决策者信息(用户 ID + 角色) |
|
||||
|
||||
---
|
||||
|
||||
@@ -323,8 +325,8 @@ idle → pending → confirmed → executing → completed
|
||||
|
||||
参见数字分段错误码系统(1000-9999):
|
||||
|
||||
| 分段 | 类别 |
|
||||
|------|------|
|
||||
| 分段 | 类别 |
|
||||
|-----------|------|
|
||||
| 1000-1999 | 系统错误 |
|
||||
| 2000-2999 | 任务错误 |
|
||||
| 3000-3999 | 信息错误 |
|
||||
@@ -338,12 +340,12 @@ idle → pending → confirmed → executing → completed
|
||||
|
||||
Agent 实现 A2A 协议时必须提供:
|
||||
|
||||
| 接口 | 说明 |
|
||||
|------|------|
|
||||
| 接口 | 说明 |
|
||||
|-------|------------------|
|
||||
| 消息处理器 | 接收并处理 p2p:* 类型消息 |
|
||||
| 任务处理器 | 执行具体任务逻辑 |
|
||||
| 回调发送器 | 发送进度、完成、失败等回调 |
|
||||
| 状态查询 | 支持任务状态查询 |
|
||||
| 任务处理器 | 执行具体任务逻辑 |
|
||||
| 回调发送器 | 发送进度、完成、失败等回调 |
|
||||
| 状态查询 | 支持任务状态查询 |
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -13,6 +13,7 @@
|
||||
A2N 协议定义多个 Agent 组成群组进行协同工作的规范,包括群组管理、任务拆分与合并、群体决策、角色与权限、升级机制等。
|
||||
|
||||
**适用场景**:
|
||||
|
||||
- 复杂任务的拆分与并行执行(MapReduce 模式)
|
||||
- 多 Agent 协同完成单一目标
|
||||
- 群体投票与共识决策
|
||||
@@ -20,6 +21,7 @@ A2N 协议定义多个 Agent 组成群组进行协同工作的规范,包括群
|
||||
- 分级升级机制
|
||||
|
||||
**依赖关系**:
|
||||
|
||||
- 群组内成员间的单播通信复用 A2A 协议
|
||||
|
||||
---
|
||||
@@ -28,53 +30,53 @@ A2N 协议定义多个 Agent 组成群组进行协同工作的规范,包括群
|
||||
|
||||
### 2.1 群组管理
|
||||
|
||||
| 功能 | 说明 |
|
||||
|-----|------|
|
||||
| 群组创建 | Coordinator 创建群组,定义拓扑结构 |
|
||||
| 群组解散 | Coordinator 解散群组 |
|
||||
| 加入群组 | Agent 主动申请加入 |
|
||||
| 离开群组 | 成员主动离开 |
|
||||
| 邀请加入 | Coordinator 或成员邀请其他 Agent |
|
||||
| 接受邀请 | 被邀请者接受邀请 |
|
||||
| 拒绝邀请 | 被邀请者拒绝邀请 |
|
||||
| 成员更新通知 | 成员变动时广播通知 |
|
||||
| 角色变更 | Coordinator 调整成员角色 |
|
||||
| 群组冻结 | 暂停群组活动 |
|
||||
| 群组解冻 | 恢复群组活动 |
|
||||
| 功能 | 说明 |
|
||||
|--------|---------------------------|
|
||||
| 群组创建 | Coordinator 创建群组,定义拓扑结构 |
|
||||
| 群组解散 | Coordinator 解散群组 |
|
||||
| 加入群组 | Agent 主动申请加入 |
|
||||
| 离开群组 | 成员主动离开 |
|
||||
| 邀请加入 | Coordinator 或成员邀请其他 Agent |
|
||||
| 接受邀请 | 被邀请者接受邀请 |
|
||||
| 拒绝邀请 | 被邀请者拒绝邀请 |
|
||||
| 成员更新通知 | 成员变动时广播通知 |
|
||||
| 角色变更 | Coordinator 调整成员角色 |
|
||||
| 群组冻结 | 暂停群组活动 |
|
||||
| 群组解冻 | 恢复群组活动 |
|
||||
|
||||
### 2.2 群组通信
|
||||
|
||||
| 功能 | 说明 |
|
||||
|-----|------|
|
||||
| 广播 | 发送给所有成员 |
|
||||
| 组播 | 发送给指定成员列表 |
|
||||
| 单播 | 群内点对点(复用 A2A) |
|
||||
| 消息中继 | 通过其他成员转发消息 |
|
||||
| 功能 | 说明 |
|
||||
|------|---------------|
|
||||
| 广播 | 发送给所有成员 |
|
||||
| 组播 | 发送给指定成员列表 |
|
||||
| 单播 | 群内点对点(复用 A2A) |
|
||||
| 消息中继 | 通过其他成员转发消息 |
|
||||
|
||||
### 2.3 任务协作
|
||||
|
||||
| 功能 | 说明 |
|
||||
|-----|------|
|
||||
| 任务拆分 | Coordinator 将大任务拆分为子任务 |
|
||||
| 任务分配 | 子任务分配给指定 Worker |
|
||||
| 子任务进度 | Worker 上报子任务进度 |
|
||||
| 结果合并 | Coordinator 合并子任务结果 |
|
||||
| 功能 | 说明 |
|
||||
|-------|------------------------|
|
||||
| 任务拆分 | Coordinator 将大任务拆分为子任务 |
|
||||
| 任务分配 | 子任务分配给指定 Worker |
|
||||
| 子任务进度 | Worker 上报子任务进度 |
|
||||
| 结果合并 | Coordinator 合并子任务结果 |
|
||||
|
||||
### 2.4 共识投票
|
||||
|
||||
| 功能 | 说明 |
|
||||
|-----|------|
|
||||
| 功能 | 说明 |
|
||||
|------|-----------------------------|
|
||||
| 发起投票 | Coordinator 或 Reviewer 发起投票 |
|
||||
| 提交投票 | 成员提交选项及理由 |
|
||||
| 达成共识 | 公布投票结果 |
|
||||
| 提交投票 | 成员提交选项及理由 |
|
||||
| 达成共识 | 公布投票结果 |
|
||||
|
||||
### 2.5 升级机制
|
||||
|
||||
| 功能 | 说明 |
|
||||
|-----|------|
|
||||
| 共识僵局升级 | 投票无法达成共识时升级给人类 |
|
||||
| 子任务阻塞升级 | 子任务阻塞时升级给人类 |
|
||||
| 跨群组升级 | 升级到更高层级群组 |
|
||||
| 功能 | 说明 |
|
||||
|---------|----------------|
|
||||
| 共识僵局升级 | 投票无法达成共识时升级给人类 |
|
||||
| 子任务阻塞升级 | 子任务阻塞时升级给人类 |
|
||||
| 跨群组升级 | 升级到更高层级群组 |
|
||||
|
||||
---
|
||||
|
||||
@@ -82,52 +84,52 @@ A2N 协议定义多个 Agent 组成群组进行协同工作的规范,包括群
|
||||
|
||||
### 3.1 群组管理消息(前缀 `group:`)
|
||||
|
||||
| 消息类型 | 说明 |
|
||||
|---------|------|
|
||||
| `group:create` | 创建群组 |
|
||||
| `group:disband` | 解散群组 |
|
||||
| `group:join` | 加入群组 |
|
||||
| `group:leave` | 离开群组 |
|
||||
| `group:invite` | 邀请加入 |
|
||||
| `group:accept_invite` | 接受邀请 |
|
||||
| `group:reject_invite` | 拒绝邀请 |
|
||||
| 消息类型 | 说明 |
|
||||
|-----------------------|--------|
|
||||
| `group:create` | 创建群组 |
|
||||
| `group:disband` | 解散群组 |
|
||||
| `group:join` | 加入群组 |
|
||||
| `group:leave` | 离开群组 |
|
||||
| `group:invite` | 邀请加入 |
|
||||
| `group:accept_invite` | 接受邀请 |
|
||||
| `group:reject_invite` | 拒绝邀请 |
|
||||
| `group:member_update` | 成员更新通知 |
|
||||
| `group:role_change` | 角色变更 |
|
||||
| `group:role_change` | 角色变更 |
|
||||
|
||||
### 3.2 群组通信消息(前缀 `group:`)
|
||||
|
||||
| 消息类型 | 说明 |
|
||||
|---------|------|
|
||||
| 消息类型 | 说明 |
|
||||
|-------------------|----------|
|
||||
| `group:broadcast` | 广播(所有成员) |
|
||||
| `group:multicast` | 组播(指定成员) |
|
||||
| `group:direct` | 群内单播 |
|
||||
| `group:relay` | 消息中继 |
|
||||
| `group:direct` | 群内单播 |
|
||||
| `group:relay` | 消息中继 |
|
||||
|
||||
### 3.3 任务协作消息(前缀 `group:`)
|
||||
|
||||
| 消息类型 | 说明 |
|
||||
|---------|------|
|
||||
| `group:task_split` | 任务拆分 |
|
||||
| `group:task_assign` | 任务分配 |
|
||||
| `group:task_merge` | 结果合并 |
|
||||
| 消息类型 | 说明 |
|
||||
|-----------------------|-------|
|
||||
| `group:task_split` | 任务拆分 |
|
||||
| `group:task_assign` | 任务分配 |
|
||||
| `group:task_merge` | 结果合并 |
|
||||
| `group:task_progress` | 子任务进度 |
|
||||
|
||||
### 3.4 共识投票消息(前缀 `group:`)
|
||||
|
||||
| 消息类型 | 说明 |
|
||||
|---------|------|
|
||||
| `group:vote` | 发起投票 |
|
||||
| 消息类型 | 说明 |
|
||||
|---------------------|------|
|
||||
| `group:vote` | 发起投票 |
|
||||
| `group:vote_submit` | 提交投票 |
|
||||
| `group:consensus` | 达成共识 |
|
||||
| `group:consensus` | 达成共识 |
|
||||
|
||||
### 3.5 HiL 升级消息(前缀 `group:` / `inter_group:`)
|
||||
|
||||
| 消息类型 | 说明 |
|
||||
|---------|------|
|
||||
| `group:consensus_escalate` | 共识僵局升级给人类 |
|
||||
| `group:subtask_escalate` | 子任务阻塞升级给人类 |
|
||||
| `group:human_decision` | 人类决策结果 |
|
||||
| `inter_group:escalate` | 跨群组升级 |
|
||||
| 消息类型 | 说明 |
|
||||
|----------------------------|------------|
|
||||
| `group:consensus_escalate` | 共识僵局升级给人类 |
|
||||
| `group:subtask_escalate` | 子任务阻塞升级给人类 |
|
||||
| `group:human_decision` | 人类决策结果 |
|
||||
| `inter_group:escalate` | 跨群组升级 |
|
||||
|
||||
---
|
||||
|
||||
@@ -135,49 +137,49 @@ A2N 协议定义多个 Agent 组成群组进行协同工作的规范,包括群
|
||||
|
||||
### 4.1 群组拓扑结构
|
||||
|
||||
| 拓扑类型 | 说明 | 适用场景 |
|
||||
|---------|------|---------|
|
||||
| `star` | 星型,中心 coordinator 协调 | 简单任务分发 |
|
||||
| `mesh` | 网状,成员间可直接通信 | 对等协作 |
|
||||
| `chain` | 链式,流水线模式 | 顺序处理 |
|
||||
| `hierarchical` | 层级型,多层管理 | 大型复杂任务 |
|
||||
| `fullmesh` | 全连接网状 | 高可靠协作 |
|
||||
| 拓扑类型 | 说明 | 适用场景 |
|
||||
|----------------|----------------------|--------|
|
||||
| `star` | 星型,中心 coordinator 协调 | 简单任务分发 |
|
||||
| `mesh` | 网状,成员间可直接通信 | 对等协作 |
|
||||
| `chain` | 链式,流水线模式 | 顺序处理 |
|
||||
| `hierarchical` | 层级型,多层管理 | 大型复杂任务 |
|
||||
| `fullmesh` | 全连接网状 | 高可靠协作 |
|
||||
|
||||
### 4.2 成员角色
|
||||
|
||||
| 角色 | 说明 | 权限 |
|
||||
|------|------|------|
|
||||
| 角色 | 说明 | 权限 |
|
||||
|---------------|-----|------------------------|
|
||||
| `coordinator` | 协调者 | 创建/解散群组、任务拆分、发起投票、角色变更 |
|
||||
| `worker` | 工作者 | 执行子任务、提交结果、投票 |
|
||||
| `reviewer` | 审核者 | 审核结果、发起投票、升级请求 |
|
||||
| `observer` | 观察者 | 只读,查看进度 |
|
||||
| `worker` | 工作者 | 执行子任务、提交结果、投票 |
|
||||
| `reviewer` | 审核者 | 审核结果、发起投票、升级请求 |
|
||||
| `observer` | 观察者 | 只读,查看进度 |
|
||||
|
||||
### 4.3 群组状态
|
||||
|
||||
| 状态 | 说明 |
|
||||
|------|------|
|
||||
| `creating` | 创建中 |
|
||||
| `active` | 活跃 |
|
||||
| `frozen` | 冻结(不可执行新任务) |
|
||||
| `disbanded` | 已解散(终态) |
|
||||
| 状态 | 说明 |
|
||||
|-------------|-------------|
|
||||
| `creating` | 创建中 |
|
||||
| `active` | 活跃 |
|
||||
| `frozen` | 冻结(不可执行新任务) |
|
||||
| `disbanded` | 已解散(终态) |
|
||||
|
||||
### 4.4 合并策略
|
||||
|
||||
| 策略 | 说明 |
|
||||
|------|------|
|
||||
| 策略 | 说明 |
|
||||
|-----------------|-----------|
|
||||
| `first_success` | 首个成功结果即返回 |
|
||||
| `majority` | 多数结果合并 |
|
||||
| `weighted` | 按权重加权合并 |
|
||||
| `custom` | 自定义合并逻辑 |
|
||||
| `majority` | 多数结果合并 |
|
||||
| `weighted` | 按权重加权合并 |
|
||||
| `custom` | 自定义合并逻辑 |
|
||||
|
||||
### 4.5 共识类型
|
||||
|
||||
| 类型 | 说明 |
|
||||
|------|------|
|
||||
| `majority` | 多数投票(>50%) |
|
||||
| 类型 | 说明 |
|
||||
|-----------------|------------|
|
||||
| `majority` | 多数投票(>50%) |
|
||||
| `supermajority` | 绝对多数(>67%) |
|
||||
| `unanimity` | 一致同意(100%) |
|
||||
| `weighted` | 加权投票 |
|
||||
| `unanimity` | 一致同意(100%) |
|
||||
| `weighted` | 加权投票 |
|
||||
|
||||
---
|
||||
|
||||
@@ -245,20 +247,20 @@ Coordinator 所有成员
|
||||
### 6.2 流程步骤
|
||||
|
||||
1. **任务拆分阶段**
|
||||
- Coordinator 接收原始任务
|
||||
- 将任务拆分为多个子任务
|
||||
- 为每个子任务指定执行的 Worker
|
||||
- 定义合并策略
|
||||
- Coordinator 接收原始任务
|
||||
- 将任务拆分为多个子任务
|
||||
- 为每个子任务指定执行的 Worker
|
||||
- 定义合并策略
|
||||
|
||||
2. **并行执行阶段**
|
||||
- 各 Worker 并行执行子任务
|
||||
- 定期上报进度
|
||||
- 子任务完成后上报结果
|
||||
- 各 Worker 并行执行子任务
|
||||
- 定期上报进度
|
||||
- 子任务完成后上报结果
|
||||
|
||||
3. **结果合并阶段**
|
||||
- Coordinator 收集所有子任务结果
|
||||
- 按合并策略合并结果
|
||||
- 返回最终结果
|
||||
- Coordinator 收集所有子任务结果
|
||||
- 按合并策略合并结果
|
||||
- 返回最终结果
|
||||
|
||||
---
|
||||
|
||||
@@ -280,59 +282,59 @@ Coordinator 所有成员
|
||||
|
||||
### 8.1 群组创建载荷
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|:----:|------|
|
||||
| `group_id` | string | ✓ | 群组唯一标识 |
|
||||
| `group_name` | string | - | 群组名称 |
|
||||
| `topology` | string | ✓ | 拓扑结构 |
|
||||
| `config` | object | - | 群组配置 |
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|--------------|--------|:--:|--------|
|
||||
| `group_id` | string | ✓ | 群组唯一标识 |
|
||||
| `group_name` | string | - | 群组名称 |
|
||||
| `topology` | string | ✓ | 拓扑结构 |
|
||||
| `config` | object | - | 群组配置 |
|
||||
|
||||
### 8.2 群组配置
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `max_members` | integer | 最大成员数 |
|
||||
| `vote_threshold` | float | 投票阈值 |
|
||||
| `default_consensus_type` | string | 默认共识类型 |
|
||||
| 字段 | 类型 | 说明 |
|
||||
|--------------------------|---------|--------|
|
||||
| `max_members` | integer | 最大成员数 |
|
||||
| `vote_threshold` | float | 投票阈值 |
|
||||
| `default_consensus_type` | string | 默认共识类型 |
|
||||
|
||||
### 8.3 子任务结构
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|:----:|------|
|
||||
| `subtask_id` | string | ✓ | 子任务标识 |
|
||||
| `description` | string | ✓ | 子任务描述 |
|
||||
| `assigned_to` | string | ✓ | 执行者 Agent ID |
|
||||
| `dependencies` | array | - | 依赖的子任务 ID 列表 |
|
||||
| `status` | string | ✓ | 子任务状态 |
|
||||
| `payload` | object | ✓ | 子任务参数 |
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|----------------|--------|:--:|--------------|
|
||||
| `subtask_id` | string | ✓ | 子任务标识 |
|
||||
| `description` | string | ✓ | 子任务描述 |
|
||||
| `assigned_to` | string | ✓ | 执行者 Agent ID |
|
||||
| `dependencies` | array | - | 依赖的子任务 ID 列表 |
|
||||
| `status` | string | ✓ | 子任务状态 |
|
||||
| `payload` | object | ✓ | 子任务参数 |
|
||||
|
||||
### 8.4 投票载荷
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|:----:|------|
|
||||
| `vote_id` | string | ✓ | 投票标识 |
|
||||
| `question` | string | ✓ | 投票问题 |
|
||||
| `options` | array | ✓ | 选项列表 |
|
||||
| `consensus_type` | string | ✓ | 共识类型 |
|
||||
| `deadline` | string | - | 截止时间 |
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------------------|--------|:--:|------|
|
||||
| `vote_id` | string | ✓ | 投票标识 |
|
||||
| `question` | string | ✓ | 投票问题 |
|
||||
| `options` | array | ✓ | 选项列表 |
|
||||
| `consensus_type` | string | ✓ | 共识类型 |
|
||||
| `deadline` | string | - | 截止时间 |
|
||||
|
||||
### 8.5 投票提交载荷
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|:----:|------|
|
||||
| `vote_id` | string | ✓ | 投票标识 |
|
||||
| `voter_id` | string | ✓ | 投票者 ID |
|
||||
| `option_id` | string | ✓ | 选择的选项 |
|
||||
| `reasoning` | string | - | 投票理由 |
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|-------------|--------|:--:|--------|
|
||||
| `vote_id` | string | ✓ | 投票标识 |
|
||||
| `voter_id` | string | ✓ | 投票者 ID |
|
||||
| `option_id` | string | ✓ | 选择的选项 |
|
||||
| `reasoning` | string | - | 投票理由 |
|
||||
|
||||
### 8.6 共识结果载荷
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|:----:|------|
|
||||
| `vote_id` | string | ✓ | 投票标识 |
|
||||
| `winner` | string | ✓ | 获胜选项 |
|
||||
| `vote_counts` | object | ✓ | 各选项票数 |
|
||||
| `passed` | boolean | ✓ | 是否通过阈值 |
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|---------------|---------|:--:|--------|
|
||||
| `vote_id` | string | ✓ | 投票标识 |
|
||||
| `winner` | string | ✓ | 获胜选项 |
|
||||
| `vote_counts` | object | ✓ | 各选项票数 |
|
||||
| `passed` | boolean | ✓ | 是否通过阈值 |
|
||||
|
||||
---
|
||||
|
||||
@@ -340,21 +342,21 @@ Coordinator 所有成员
|
||||
|
||||
### 9.1 升级场景
|
||||
|
||||
| 场景 | 消息类型 | 说明 |
|
||||
|------|---------|------|
|
||||
| 共识僵局 | `group:consensus_escalate` | 投票超时未达成共识 |
|
||||
| 子任务阻塞 | `group:subtask_escalate` | 子任务执行受阻 |
|
||||
| 跨群组 | `inter_group:escalate` | 升级到上级群组 |
|
||||
| 场景 | 消息类型 | 说明 |
|
||||
|-------|----------------------------|-----------|
|
||||
| 共识僵局 | `group:consensus_escalate` | 投票超时未达成共识 |
|
||||
| 子任务阻塞 | `group:subtask_escalate` | 子任务执行受阻 |
|
||||
| 跨群组 | `inter_group:escalate` | 升级到上级群组 |
|
||||
|
||||
### 9.2 升级载荷
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|:----:|------|
|
||||
| `escalation_id` | string | ✓ | 升级标识 |
|
||||
| `escalation_type` | string | ✓ | 升级类型 |
|
||||
| `escalation_level` | integer | ✓ | 升级级别(1/2/3) |
|
||||
| `context` | object | ✓ | 升级上下文 |
|
||||
| `options` | array | - | 可选方案 |
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|--------------------|---------|:--:|-------------|
|
||||
| `escalation_id` | string | ✓ | 升级标识 |
|
||||
| `escalation_type` | string | ✓ | 升级类型 |
|
||||
| `escalation_level` | integer | ✓ | 升级级别(1/2/3) |
|
||||
| `context` | object | ✓ | 升级上下文 |
|
||||
| `options` | array | - | 可选方案 |
|
||||
|
||||
---
|
||||
|
||||
@@ -362,16 +364,16 @@ Coordinator 所有成员
|
||||
|
||||
群组错误码分段:7000-7999
|
||||
|
||||
| 错误码 | 名称 | 说明 |
|
||||
|------|------|------|
|
||||
| 7001 | 群组不存在 | |
|
||||
| 7002 | 群组未激活 | |
|
||||
| 7003 | 成员不存在 | |
|
||||
| 7004 | 不是群组成员 | |
|
||||
| 7005 | 未达成共识 | |
|
||||
| 7006 | 角色不存在 | |
|
||||
| 7007 | 已是成员 | |
|
||||
| 7008 | 群组已满 | |
|
||||
| 错误码 | 名称 | 说明 |
|
||||
|------|--------|----|
|
||||
| 7001 | 群组不存在 | |
|
||||
| 7002 | 群组未激活 | |
|
||||
| 7003 | 成员不存在 | |
|
||||
| 7004 | 不是群组成员 | |
|
||||
| 7005 | 未达成共识 | |
|
||||
| 7006 | 角色不存在 | |
|
||||
| 7007 | 已是成员 | |
|
||||
| 7008 | 群组已满 | |
|
||||
|
||||
---
|
||||
|
||||
@@ -379,12 +381,12 @@ Coordinator 所有成员
|
||||
|
||||
Agent 实现 A2N 协议时必须提供:
|
||||
|
||||
| 接口 | 说明 |
|
||||
|------|------|
|
||||
| 接口 | 说明 |
|
||||
|---------|---------------|
|
||||
| 群组管理处理器 | 处理群组创建、加入、离开等 |
|
||||
| 子任务处理器 | 执行分配的子任务 |
|
||||
| 投票处理器 | 处理投票相关消息 |
|
||||
| 升级处理器 | 处理升级请求 |
|
||||
| 子任务处理器 | 执行分配的子任务 |
|
||||
| 投票处理器 | 处理投票相关消息 |
|
||||
| 升级处理器 | 处理升级请求 |
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -15,12 +15,14 @@ P2A 协议定义**非 Agent 调用方**(如普通后端服务、前端应用
|
||||
本协议将 A2A 协议的复杂性封装起来,提供简洁的 RESTful API,使调用方无需了解 A2A 协议细节即可使用 Agent 能力。
|
||||
|
||||
**适用场景**:
|
||||
|
||||
- 前端应用直接调用 Agent 能力
|
||||
- 后端业务系统集成 Agent 服务
|
||||
- 第三方开发者通过 API 接入
|
||||
- 无需实现完整 A2A 协议的调用方
|
||||
|
||||
**设计原则**:
|
||||
|
||||
- **简单易用**:标准 RESTful API,JSON 格式
|
||||
- **两种模式**:回调模式 + 轮询模式,调用方按需选择
|
||||
- **认证简单**:API Key 认证,无需 HMAC 签名
|
||||
@@ -33,44 +35,44 @@ P2A 协议定义**非 Agent 调用方**(如普通后端服务、前端应用
|
||||
|
||||
### 2.1 任务提交
|
||||
|
||||
| 功能 | 说明 |
|
||||
|-----|------|
|
||||
| JSON 提交 | application/json 格式提交任务 |
|
||||
| Multipart 提交 | 带文件上传的任务提交 |
|
||||
| 功能 | 说明 |
|
||||
|--------------|-------------------------|
|
||||
| JSON 提交 | application/json 格式提交任务 |
|
||||
| Multipart 提交 | 带文件上传的任务提交 |
|
||||
|
||||
### 2.2 任务查询
|
||||
|
||||
| 功能 | 说明 |
|
||||
|-----|------|
|
||||
| 功能 | 说明 |
|
||||
|------|---------------|
|
||||
| 任务详情 | 获取完整任务信息(含结果) |
|
||||
| 任务状态 | 简化版状态查询 |
|
||||
| 任务列表 | 分页查询任务列表 |
|
||||
| 任务状态 | 简化版状态查询 |
|
||||
| 任务列表 | 分页查询任务列表 |
|
||||
|
||||
### 2.3 任务控制
|
||||
|
||||
| 功能 | 说明 |
|
||||
|-----|------|
|
||||
| 功能 | 说明 |
|
||||
|------|-----------|
|
||||
| 任务取消 | 取消正在执行的任务 |
|
||||
|
||||
### 2.4 能力查询
|
||||
|
||||
| 功能 | 说明 |
|
||||
|-----|------|
|
||||
| 功能 | 说明 |
|
||||
|------|------------------|
|
||||
| 能力清单 | 获取 Agent 支持的任务类型 |
|
||||
|
||||
### 2.5 通知机制
|
||||
|
||||
| 功能 | 说明 |
|
||||
|-----|------|
|
||||
| 功能 | 说明 |
|
||||
|------|--------------|
|
||||
| 回调通知 | 任务完成后主动回调调用方 |
|
||||
| 轮询查询 | 调用方主动查询状态 |
|
||||
| 轮询查询 | 调用方主动查询状态 |
|
||||
|
||||
### 2.6 认证
|
||||
|
||||
| 功能 | 说明 |
|
||||
|-----|------|
|
||||
| API Key 认证 | X-API-Key 头部认证 |
|
||||
| 回调验证 | X-Callback-Token 验证回调来源 |
|
||||
| 功能 | 说明 |
|
||||
|------------|-------------------------|
|
||||
| API Key 认证 | X-API-Key 头部认证 |
|
||||
| 回调验证 | X-Callback-Token 验证回调来源 |
|
||||
|
||||
---
|
||||
|
||||
@@ -80,15 +82,15 @@ P2A 协议定义**非 Agent 调用方**(如普通后端服务、前端应用
|
||||
|
||||
### 3.1 端点清单
|
||||
|
||||
| 方法 | 路径 | 说明 |
|
||||
|------|------|------|
|
||||
| POST | `/task` | 提交任务(JSON) |
|
||||
| POST | `/task/multipart` | 提交任务(带文件上传) |
|
||||
| GET | `/task/{task_id}` | 获取任务详情 |
|
||||
| GET | `/task/{task_id}/status` | 获取任务状态(简化版) |
|
||||
| GET | `/tasks` | 获取任务列表 |
|
||||
| POST | `/task/{task_id}/cancel` | 取消任务 |
|
||||
| GET | `/capabilities` | 获取能力清单 |
|
||||
| 方法 | 路径 | 说明 |
|
||||
|------|--------------------------|-------------|
|
||||
| POST | `/task` | 提交任务(JSON) |
|
||||
| POST | `/task/multipart` | 提交任务(带文件上传) |
|
||||
| GET | `/task/{task_id}` | 获取任务详情 |
|
||||
| GET | `/task/{task_id}/status` | 获取任务状态(简化版) |
|
||||
| GET | `/tasks` | 获取任务列表 |
|
||||
| POST | `/task/{task_id}/cancel` | 取消任务 |
|
||||
| GET | `/capabilities` | 获取能力清单 |
|
||||
|
||||
---
|
||||
|
||||
@@ -96,13 +98,13 @@ P2A 协议定义**非 Agent 调用方**(如普通后端服务、前端应用
|
||||
|
||||
P2A 协议使用简化状态(5 种):
|
||||
|
||||
| 状态 | 说明 |
|
||||
|------|------|
|
||||
| `received` | 已接收 |
|
||||
| `processing` | 处理中 |
|
||||
| `completed` | 已完成(终态) |
|
||||
| `failed` | 已失败(终态) |
|
||||
| `cancelled` | 已取消(终态) |
|
||||
| 状态 | 说明 |
|
||||
|--------------|---------|
|
||||
| `received` | 已接收 |
|
||||
| `processing` | 处理中 |
|
||||
| `completed` | 已完成(终态) |
|
||||
| `failed` | 已失败(终态) |
|
||||
| `cancelled` | 已取消(终态) |
|
||||
|
||||
状态流转:
|
||||
|
||||
@@ -119,6 +121,7 @@ received → processing → completed
|
||||
### 5.1 API Key 认证
|
||||
|
||||
传递方式:
|
||||
|
||||
- HTTP Header:`X-API-Key: {api_key}`
|
||||
- URL Query:`?api_key={api_key}`
|
||||
|
||||
@@ -134,26 +137,26 @@ received → processing → completed
|
||||
|
||||
### 6.1 任务提交请求(JSON)
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|:----:|------|
|
||||
| `task_type` | string | ✓ | 任务类型(如 `text_generation`) |
|
||||
| `payload` | object | ✓ | 任务参数(结构由 task_type 决定) |
|
||||
| `external_task_id` | string | - | 调用方的任务 ID,用于关联 |
|
||||
| `priority` | string | - | 优先级:`low`/`normal`/`high`/`urgent`,默认 `normal` |
|
||||
| `callback_url` | string | - | 回调 URL,不提供则需轮询 |
|
||||
| `callback_token` | string | - | 回调验证 token |
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|--------------------|--------|:--:|------------------------------------------------|
|
||||
| `task_type` | string | ✓ | 任务类型(如 `text_generation`) |
|
||||
| `payload` | object | ✓ | 任务参数(结构由 task_type 决定) |
|
||||
| `external_task_id` | string | - | 调用方的任务 ID,用于关联 |
|
||||
| `priority` | string | - | 优先级:`low`/`normal`/`high`/`urgent`,默认 `normal` |
|
||||
| `callback_url` | string | - | 回调 URL,不提供则需轮询 |
|
||||
| `callback_token` | string | - | 回调验证 token |
|
||||
|
||||
### 6.2 任务提交请求(Multipart)
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|:----:|------|
|
||||
| `task_type` | string | ✓ | 任务类型 |
|
||||
| `payload` | string(JSON) | ✓ | 任务参数(JSON 字符串) |
|
||||
| `external_task_id` | string | - | 外部任务 ID |
|
||||
| `priority` | string | - | 优先级 |
|
||||
| `callback_url` | string | - | 回调 URL |
|
||||
| `callback_token` | string | - | 回调 token |
|
||||
| `file` | file | - | 上传的文件(可多个) |
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|--------------------|--------------|:--:|----------------|
|
||||
| `task_type` | string | ✓ | 任务类型 |
|
||||
| `payload` | string(JSON) | ✓ | 任务参数(JSON 字符串) |
|
||||
| `external_task_id` | string | - | 外部任务 ID |
|
||||
| `priority` | string | - | 优先级 |
|
||||
| `callback_url` | string | - | 回调 URL |
|
||||
| `callback_token` | string | - | 回调 token |
|
||||
| `file` | file | - | 上传的文件(可多个) |
|
||||
|
||||
---
|
||||
|
||||
@@ -161,77 +164,77 @@ received → processing → completed
|
||||
|
||||
### 7.1 任务提交响应
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `success` | boolean | 是否成功 |
|
||||
| `task_id` | string | 服务端生成的任务 ID |
|
||||
| `status` | string | 初始状态(通常为 `received`) |
|
||||
| `message` | string | 提示信息 |
|
||||
| `error` | object | 错误信息(失败时) |
|
||||
| 字段 | 类型 | 说明 |
|
||||
|-----------|---------|----------------------|
|
||||
| `success` | boolean | 是否成功 |
|
||||
| `task_id` | string | 服务端生成的任务 ID |
|
||||
| `status` | string | 初始状态(通常为 `received`) |
|
||||
| `message` | string | 提示信息 |
|
||||
| `error` | object | 错误信息(失败时) |
|
||||
|
||||
### 7.2 任务详情响应
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| 字段 | 类型 | 说明 |
|
||||
|-----------|---------|------|
|
||||
| `success` | boolean | 是否成功 |
|
||||
| `task` | object | 任务详情 |
|
||||
| `error` | object | 错误信息 |
|
||||
| `task` | object | 任务详情 |
|
||||
| `error` | object | 错误信息 |
|
||||
|
||||
### 7.3 任务详情结构
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `id` | string | 任务 ID |
|
||||
| `type` | string | 任务类型 |
|
||||
| `status` | string | 任务状态 |
|
||||
| `progress` | integer | 进度百分比(0-100) |
|
||||
| `message` | string | 状态说明 |
|
||||
| `created_at` | string | 创建时间(RFC3339) |
|
||||
| `updated_at` | string | 更新时间(RFC3339) |
|
||||
| `completed_at` | string | 完成时间(RFC3339) |
|
||||
| `eta` | string | 预估完成时间 |
|
||||
| `result` | object | 任务结果(结构由 task_type 决定) |
|
||||
| `error` | object | 错误信息 |
|
||||
| 字段 | 类型 | 说明 |
|
||||
|----------------|---------|------------------------|
|
||||
| `id` | string | 任务 ID |
|
||||
| `type` | string | 任务类型 |
|
||||
| `status` | string | 任务状态 |
|
||||
| `progress` | integer | 进度百分比(0-100) |
|
||||
| `message` | string | 状态说明 |
|
||||
| `created_at` | string | 创建时间(RFC3339) |
|
||||
| `updated_at` | string | 更新时间(RFC3339) |
|
||||
| `completed_at` | string | 完成时间(RFC3339) |
|
||||
| `eta` | string | 预估完成时间 |
|
||||
| `result` | object | 任务结果(结构由 task_type 决定) |
|
||||
| `error` | object | 错误信息 |
|
||||
|
||||
### 7.4 任务列表响应
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `success` | boolean | 是否成功 |
|
||||
| `tasks` | array | 任务列表 |
|
||||
| `total` | integer | 总数 |
|
||||
| `limit` | integer | 每页数量 |
|
||||
| `offset` | integer | 偏移量 |
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------------|---------|-------|
|
||||
| `success` | boolean | 是否成功 |
|
||||
| `tasks` | array | 任务列表 |
|
||||
| `total` | integer | 总数 |
|
||||
| `limit` | integer | 每页数量 |
|
||||
| `offset` | integer | 偏移量 |
|
||||
| `has_more` | boolean | 是否有更多 |
|
||||
|
||||
### 7.5 能力清单响应
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `agent_id` | string | Agent 唯一标识 |
|
||||
| `agent_name` | string | Agent 名称 |
|
||||
| `protocol_version` | string | 协议版本 |
|
||||
| `supported_task_types` | array | 支持的任务类型列表 |
|
||||
| `supported_content_types` | array | 支持的内容类型 |
|
||||
| `max_file_size` | integer | 最大文件大小(字节) |
|
||||
| `max_concurrent_tasks` | integer | 最大并发任务数 |
|
||||
| `max_task_duration` | integer | 最大任务时长(秒) |
|
||||
| `support_progress_updates` | boolean | 是否支持进度更新 |
|
||||
| `support_streaming` | boolean | 是否支持流式传输 |
|
||||
| `support_hil` | boolean | 是否支持人类介入 |
|
||||
| `support_groups` | boolean | 是否支持群组协作 |
|
||||
| 字段 | 类型 | 说明 |
|
||||
|----------------------------|---------|------------|
|
||||
| `agent_id` | string | Agent 唯一标识 |
|
||||
| `agent_name` | string | Agent 名称 |
|
||||
| `protocol_version` | string | 协议版本 |
|
||||
| `supported_task_types` | array | 支持的任务类型列表 |
|
||||
| `supported_content_types` | array | 支持的内容类型 |
|
||||
| `max_file_size` | integer | 最大文件大小(字节) |
|
||||
| `max_concurrent_tasks` | integer | 最大并发任务数 |
|
||||
| `max_task_duration` | integer | 最大任务时长(秒) |
|
||||
| `support_progress_updates` | boolean | 是否支持进度更新 |
|
||||
| `support_streaming` | boolean | 是否支持流式传输 |
|
||||
| `support_hil` | boolean | 是否支持人类介入 |
|
||||
| `support_groups` | boolean | 是否支持群组协作 |
|
||||
|
||||
### 7.6 任务类型能力
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `type` | string | 任务类型标识 |
|
||||
| `name` | string | 任务类型名称 |
|
||||
| `description` | string | 描述 |
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------------------|--------|--------------------|
|
||||
| `type` | string | 任务类型标识 |
|
||||
| `name` | string | 任务类型名称 |
|
||||
| `description` | string | 描述 |
|
||||
| `estimated_time` | string | 预估耗时(如 "30s-2min") |
|
||||
| `input_schema` | string | 输入 Schema |
|
||||
| `output_schema` | string | 输出 Schema |
|
||||
| `capabilities` | array | 所需能力列表 |
|
||||
| `input_schema` | string | 输入 Schema |
|
||||
| `output_schema` | string | 输出 Schema |
|
||||
| `capabilities` | array | 所需能力列表 |
|
||||
|
||||
---
|
||||
|
||||
@@ -241,40 +244,40 @@ received → processing → completed
|
||||
|
||||
当任务完成时,服务端向调用方提供的 `callback_url` 发送回调:
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `task_id` | string | 任务 ID |
|
||||
| `external_task_id` | string | 外部任务 ID(如有) |
|
||||
| `status` | string | 任务状态 |
|
||||
| `progress` | integer | 进度 |
|
||||
| `result` | object | 任务结果 |
|
||||
| `error` | object | 错误信息 |
|
||||
| `timestamp` | string | 时间戳(RFC3339) |
|
||||
| 字段 | 类型 | 说明 |
|
||||
|--------------------|---------|--------------|
|
||||
| `task_id` | string | 任务 ID |
|
||||
| `external_task_id` | string | 外部任务 ID(如有) |
|
||||
| `status` | string | 任务状态 |
|
||||
| `progress` | integer | 进度 |
|
||||
| `result` | object | 任务结果 |
|
||||
| `error` | object | 错误信息 |
|
||||
| `timestamp` | string | 时间戳(RFC3339) |
|
||||
|
||||
### 8.2 回调 Header
|
||||
|
||||
| Header | 说明 |
|
||||
|--------|------|
|
||||
| Header | 说明 |
|
||||
|--------------------|------------------------------------|
|
||||
| `X-Callback-Token` | 回调验证 token(如调用方提供了 callback_token) |
|
||||
| `Content-Type` | `application/json` |
|
||||
| `Content-Type` | `application/json` |
|
||||
|
||||
---
|
||||
|
||||
## 9. 错误响应结构
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| 字段 | 类型 | 说明 |
|
||||
|-----------|---------|-------|
|
||||
| `success` | boolean | false |
|
||||
| `error` | object | 错误详情 |
|
||||
| `error` | object | 错误详情 |
|
||||
|
||||
错误详情结构:
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `code` | integer | 数字错误码 |
|
||||
| `category` | string | 错误类别 |
|
||||
| `message` | string | 错误描述 |
|
||||
| `details` | object | 详细信息 |
|
||||
| 字段 | 类型 | 说明 |
|
||||
|---------------|---------|-----------|
|
||||
| `code` | integer | 数字错误码 |
|
||||
| `category` | string | 错误类别 |
|
||||
| `message` | string | 错误描述 |
|
||||
| `details` | object | 详细信息 |
|
||||
| `retry_after` | integer | 重试等待时间(秒) |
|
||||
|
||||
---
|
||||
@@ -284,6 +287,7 @@ received → processing → completed
|
||||
### 10.1 回调模式
|
||||
|
||||
调用方提供 `callback_url`:
|
||||
|
||||
- 任务状态变化时主动回调
|
||||
- 无需轮询
|
||||
- 适用于实时性要求高的场景
|
||||
@@ -291,6 +295,7 @@ received → processing → completed
|
||||
### 10.2 轮询模式
|
||||
|
||||
调用方不提供 `callback_url`:
|
||||
|
||||
- 需主动调用 `/task/{task_id}/status` 查询
|
||||
- 适用于无法接收回调的场景
|
||||
- 推荐轮询间隔:5-10 秒
|
||||
@@ -298,6 +303,7 @@ received → processing → completed
|
||||
### 10.3 混合模式
|
||||
|
||||
调用方提供 `callback_url`,同时支持轮询:
|
||||
|
||||
- 回调为主,轮询兜底
|
||||
- 适用于高可靠性场景
|
||||
|
||||
@@ -311,13 +317,13 @@ received → processing → completed
|
||||
|
||||
P2A 协议是 A2A 协议的"简化入口":
|
||||
|
||||
| P2A API | A2A 消息映射 |
|
||||
|---------|-------------|
|
||||
| POST `/task` | `p2p:task_request` |
|
||||
| GET `/task/{id}` | 内部状态查询 |
|
||||
| POST `/task/{id}/cancel` | `p2p:task_cancel` |
|
||||
| GET `/capabilities` | `p2p:capability_query` + `p2p:capability_response` |
|
||||
| 回调发送 | `p2p:task_complete` / `p2p:task_failed` 等 |
|
||||
| P2A API | A2A 消息映射 |
|
||||
|--------------------------|----------------------------------------------------|
|
||||
| POST `/task` | `p2p:task_request` |
|
||||
| GET `/task/{id}` | 内部状态查询 |
|
||||
| POST `/task/{id}/cancel` | `p2p:task_cancel` |
|
||||
| GET `/capabilities` | `p2p:capability_query` + `p2p:capability_response` |
|
||||
| 回调发送 | `p2p:task_complete` / `p2p:task_failed` 等 |
|
||||
|
||||
---
|
||||
|
||||
@@ -325,11 +331,11 @@ P2A 协议是 A2A 协议的"简化入口":
|
||||
|
||||
实现 P2A 协议的服务端必须提供:
|
||||
|
||||
| 接口 | 说明 |
|
||||
|------|------|
|
||||
| 任务接收端点 | 接收任务提交请求 |
|
||||
| 任务查询端点 | 提供任务状态和结果查询 |
|
||||
| 任务取消端点 | 支持任务取消 |
|
||||
| 能力查询端点 | 提供能力清单 |
|
||||
| 回调发送器 | 支持向调用方回调 |
|
||||
| 接口 | 说明 |
|
||||
|---------|--------------------|
|
||||
| 任务接收端点 | 接收任务提交请求 |
|
||||
| 任务查询端点 | 提供任务状态和结果查询 |
|
||||
| 任务取消端点 | 支持任务取消 |
|
||||
| 能力查询端点 | 提供能力清单 |
|
||||
| 回调发送器 | 支持向调用方回调 |
|
||||
| A2A 转换器 | 将 P2A 请求转换为 A2A 消息 |
|
||||
@@ -18,6 +18,7 @@
|
||||
### 1.1 问题陈述
|
||||
|
||||
现有协议假设存在中心化的注册表(如灵脉 Meridian),但在以下场景中:
|
||||
|
||||
- 临时 P2P 网络
|
||||
- 跨组织协作
|
||||
- 离线/断网环境
|
||||
@@ -27,13 +28,13 @@
|
||||
|
||||
### 1.2 设计目标
|
||||
|
||||
| 目标 | 说明 |
|
||||
|-----|------|
|
||||
| 目标 | 说明 |
|
||||
|-------|-----------------|
|
||||
| 身份可验证 | AgentID 无法伪造或冒用 |
|
||||
| 去中心化 | 无需中心化注册表 |
|
||||
| 高可用 | 无单点故障 |
|
||||
| 可扩展 | 支持大规模 Agent 网络 |
|
||||
| 可读性 | 支持人类可读别名(可选) |
|
||||
| 去中心化 | 无需中心化注册表 |
|
||||
| 高可用 | 无单点故障 |
|
||||
| 可扩展 | 支持大规模 Agent 网络 |
|
||||
| 可读性 | 支持人类可读别名(可选) |
|
||||
|
||||
---
|
||||
|
||||
@@ -52,41 +53,41 @@ AgentID = {namespace}:{key_hash}:{alias}
|
||||
did:synapse:abc123def456:chat-bot
|
||||
```
|
||||
|
||||
| 部分 | 格式 | 说明 |
|
||||
|------|------|------|
|
||||
| namespace | string | 命名空间(如 `synapse`) |
|
||||
| key_hash | base58 | 公钥哈希的前 16 字节 |
|
||||
| alias | string(可选) | 人类可读别名 |
|
||||
| 部分 | 格式 | 说明 |
|
||||
|-----------|------------|-------------------|
|
||||
| namespace | string | 命名空间(如 `synapse`) |
|
||||
| key_hash | base58 | 公钥哈希的前 16 字节 |
|
||||
| alias | string(可选) | 人类可读别名 |
|
||||
|
||||
### 2.2 生成算法
|
||||
|
||||
```go
|
||||
func GenerateAgentID(privateKey []byte, namespace string, alias string) string {
|
||||
// 1. 从私钥派生公钥
|
||||
publicKey := crypto.GeneratePublicKey(privateKey)
|
||||
|
||||
// 2. 计算公钥哈希
|
||||
hash := sha3.Sum256(publicKey)
|
||||
|
||||
// 3. 取前 16 字节,Base58 编码
|
||||
keyHash := base58.Encode(hash[:16])
|
||||
|
||||
// 4. 组装完整 ID
|
||||
if alias != "" {
|
||||
return fmt.Sprintf("%s:%s:%s", namespace, keyHash, alias)
|
||||
}
|
||||
return fmt.Sprintf("%s:%s", namespace, keyHash)
|
||||
// 1. 从私钥派生公钥
|
||||
publicKey := crypto.GeneratePublicKey(privateKey)
|
||||
|
||||
// 2. 计算公钥哈希
|
||||
hash := sha3.Sum256(publicKey)
|
||||
|
||||
// 3. 取前 16 字节,Base58 编码
|
||||
keyHash := base58.Encode(hash[:16])
|
||||
|
||||
// 4. 组装完整 ID
|
||||
if alias != "" {
|
||||
return fmt.Sprintf("%s:%s:%s", namespace, keyHash, alias)
|
||||
}
|
||||
return fmt.Sprintf("%s:%s", namespace, keyHash)
|
||||
}
|
||||
```
|
||||
|
||||
### 2.3 ID 特性
|
||||
|
||||
| 特性 | 说明 |
|
||||
|------|------|
|
||||
| 唯一性 | 相同公钥 → 相同 key_hash → 相同 AgentID |
|
||||
| 不可伪造 | 无法在没有私钥的情况下生成有效 AgentID |
|
||||
| 可验证 | 任何人都可以用公钥验证 AgentID 真实性 |
|
||||
| 不可预测 | 私钥随机生成,key_hash 不可预测 |
|
||||
| 特性 | 说明 |
|
||||
|------|---------------------------------|
|
||||
| 唯一性 | 相同公钥 → 相同 key_hash → 相同 AgentID |
|
||||
| 不可伪造 | 无法在没有私钥的情况下生成有效 AgentID |
|
||||
| 可验证 | 任何人都可以用公钥验证 AgentID 真实性 |
|
||||
| 不可预测 | 私钥随机生成,key_hash 不可预测 |
|
||||
|
||||
---
|
||||
|
||||
@@ -120,10 +121,10 @@ func GenerateAgentID(privateKey []byte, namespace string, alias string) string {
|
||||
|
||||
```go
|
||||
type SignedMessage struct {
|
||||
Message *UnifiedSynapseMessage // 原始消息
|
||||
Signature []byte // 签名
|
||||
PublicKey []byte // 公钥
|
||||
AgentID string // Agent 标识
|
||||
Message *UnifiedSynapseMessage // 原始消息
|
||||
Signature []byte // 签名
|
||||
PublicKey []byte // 公钥
|
||||
AgentID string // Agent 标识
|
||||
}
|
||||
```
|
||||
|
||||
@@ -139,11 +140,11 @@ signature_content =
|
||||
|
||||
### 3.4 签名算法
|
||||
|
||||
| 算法 | 说明 |
|
||||
|------|------|
|
||||
| Ed25519 | 默认,高效且安全 |
|
||||
| ECDSA-P256 | 兼容性选项 |
|
||||
| RSA-2048 | 遗留系统兼容 |
|
||||
| 算法 | 说明 |
|
||||
|------------|----------|
|
||||
| Ed25519 | 默认,高效且安全 |
|
||||
| ECDSA-P256 | 兼容性选项 |
|
||||
| RSA-2048 | 遗留系统兼容 |
|
||||
|
||||
---
|
||||
|
||||
@@ -151,11 +152,11 @@ signature_content =
|
||||
|
||||
### 4.1 发现机制选择
|
||||
|
||||
| 场景 | 推荐机制 |
|
||||
|------|---------|
|
||||
| 小规模(<100 Agent) | 广播查询 |
|
||||
| 中规模(100-10000) | 分层 DHT |
|
||||
| 大规模(>10000) | 完整 Kademlia |
|
||||
| 场景 | 推荐机制 |
|
||||
|-----------------|-------------|
|
||||
| 小规模(<100 Agent) | 广播查询 |
|
||||
| 中规模(100-10000) | 分层 DHT |
|
||||
| 大规模(>10000) | 完整 Kademlia |
|
||||
|
||||
### 4.2 广播查询协议
|
||||
|
||||
@@ -201,26 +202,26 @@ Agent A 想知道 Agent B 的 Endpoint:
|
||||
|
||||
### 4.4 DHT 消息类型
|
||||
|
||||
| 消息类型 | 说明 |
|
||||
|---------|------|
|
||||
| `dht:ping` | 节点存活探测 |
|
||||
| `dht:store` | 存储 Agent 记录 |
|
||||
| `dht:find_node` | 查找附近节点 |
|
||||
| 消息类型 | 说明 |
|
||||
|------------------|-------------|
|
||||
| `dht:ping` | 节点存活探测 |
|
||||
| `dht:store` | 存储 Agent 记录 |
|
||||
| `dht:find_node` | 查找附近节点 |
|
||||
| `dht:find_value` | 查找 Agent 记录 |
|
||||
| `dht:notify` | 通知记录更新 |
|
||||
| `dht:notify` | 通知记录更新 |
|
||||
|
||||
### 4.5 Agent 记录结构
|
||||
|
||||
```go
|
||||
type AgentRecord struct {
|
||||
AgentID string // Agent 唯一标识
|
||||
Alias string // 人类可读别名(可选)
|
||||
Endpoint string // 网络地址
|
||||
PublicKey []byte // 公钥
|
||||
TTL int64 // 记录有效期(秒)
|
||||
Version uint64 // 版本号(递增)
|
||||
Signature []byte // Agent 对以上字段的签名
|
||||
Timestamp int64 // 发布时间戳
|
||||
AgentID string // Agent 唯一标识
|
||||
Alias string // 人类可读别名(可选)
|
||||
Endpoint string // 网络地址
|
||||
PublicKey []byte // 公钥
|
||||
TTL int64 // 记录有效期(秒)
|
||||
Version uint64 // 版本号(递增)
|
||||
Signature []byte // Agent 对以上字段的签名
|
||||
Timestamp int64 // 发布时间戳
|
||||
}
|
||||
```
|
||||
|
||||
@@ -263,6 +264,7 @@ record_signature_content =
|
||||
```
|
||||
|
||||
**核心思想**:
|
||||
|
||||
- Agent 在区块链智能合约中注册身份
|
||||
- 注册需要质押一定数量的代币作为保证金
|
||||
- 心跳通过交易上链更新
|
||||
@@ -449,13 +451,13 @@ did:synapse:{method-specific-id}
|
||||
|
||||
**DID 方法**:
|
||||
|
||||
| 方法 | 说明 |
|
||||
|------|------|
|
||||
| `did:synapse:ethereum` | 基于以太坊链上注册表 |
|
||||
| `did:synapse:polygon` | 基于 Polygon 链 |
|
||||
| `did:synapse:solana` | 基于 Solana 链 |
|
||||
| `did:synapse:key` | 基于公钥的离链 DID |
|
||||
| `did:synapse:dht` | 基于 DHT 的离链 DID |
|
||||
| 方法 | 说明 |
|
||||
|------------------------|----------------|
|
||||
| `did:synapse:ethereum` | 基于以太坊链上注册表 |
|
||||
| `did:synapse:polygon` | 基于 Polygon 链 |
|
||||
| `did:synapse:solana` | 基于 Solana 链 |
|
||||
| `did:synapse:key` | 基于公钥的离链 DID |
|
||||
| `did:synapse:dht` | 基于 DHT 的离链 DID |
|
||||
|
||||
**DID Document 示例**:
|
||||
|
||||
@@ -466,18 +468,25 @@ did:synapse:{method-specific-id}
|
||||
"https://www.w3.org/ns/synapse/v1"
|
||||
],
|
||||
"id": "did:synapse:ethereum:0x1234abcd5678",
|
||||
"verificationMethod": [{
|
||||
"id": "did:synapse:ethereum:0x1234abcd5678#keys-1",
|
||||
"type": "EcdsaSecp256k1VerificationKey2019",
|
||||
"controller": "did:synapse:ethereum:0x1234abcd5678",
|
||||
"publicKeyHex": "02b3..."
|
||||
}],
|
||||
"service": [{
|
||||
"id": "did:synapse:ethereum:0x1234abcd5678#synapse-agent",
|
||||
"type": "SynapseAgent",
|
||||
"serviceEndpoint": "https://agent-01.example.com/api/synapse"
|
||||
}],
|
||||
"synapse:capabilities": ["text_generation", "image_generation"],
|
||||
"verificationMethod": [
|
||||
{
|
||||
"id": "did:synapse:ethereum:0x1234abcd5678#keys-1",
|
||||
"type": "EcdsaSecp256k1VerificationKey2019",
|
||||
"controller": "did:synapse:ethereum:0x1234abcd5678",
|
||||
"publicKeyHex": "02b3..."
|
||||
}
|
||||
],
|
||||
"service": [
|
||||
{
|
||||
"id": "did:synapse:ethereum:0x1234abcd5678#synapse-agent",
|
||||
"type": "SynapseAgent",
|
||||
"serviceEndpoint": "https://agent-01.example.com/api/synapse"
|
||||
}
|
||||
],
|
||||
"synapse:capabilities": [
|
||||
"text_generation",
|
||||
"image_generation"
|
||||
],
|
||||
"synapse:agentName": "智能写作助手",
|
||||
"synapse:version": "1.0.0"
|
||||
}
|
||||
@@ -485,14 +494,14 @@ did:synapse:{method-specific-id}
|
||||
|
||||
### 4.1.4 区块链平台选择
|
||||
|
||||
| 平台 | 优点 | 缺点 | 适合场景 |
|
||||
|------|------|------|---------|
|
||||
| Ethereum | 生态最大、安全最高 | Gas 贵、延迟高 | 高价值交易、核心 Agent |
|
||||
| Polygon | 低 Gas、快确认 | 中心化程度较高 | 中等价值、大量 Agent |
|
||||
| Solana | 高吞吐、低延迟 | 稳定性偶有问题 | 高频心跳场景 |
|
||||
| 联盟链 | 可控、隐私好 | 需要许可机制 | 企业内部、联盟合作 |
|
||||
| L2 (Arbitrum) | 低 Gas、安全继承 | 复杂度较高 | 通用场景 |
|
||||
| 本地私链 | 完全可控、零成本 | 信任范围有限 | 测试、内部系统 |
|
||||
| 平台 | 优点 | 缺点 | 适合场景 |
|
||||
|---------------|------------|-----------|----------------|
|
||||
| Ethereum | 生态最大、安全最高 | Gas 贵、延迟高 | 高价值交易、核心 Agent |
|
||||
| Polygon | 低 Gas、快确认 | 中心化程度较高 | 中等价值、大量 Agent |
|
||||
| Solana | 高吞吐、低延迟 | 稳定性偶有问题 | 高频心跳场景 |
|
||||
| 联盟链 | 可控、隐私好 | 需要许可机制 | 企业内部、联盟合作 |
|
||||
| L2 (Arbitrum) | 低 Gas、安全继承 | 复杂度较高 | 通用场景 |
|
||||
| 本地私链 | 完全可控、零成本 | 信任范围有限 | 测试、内部系统 |
|
||||
|
||||
### 4.1.5 混合架构(推荐)
|
||||
|
||||
@@ -526,43 +535,43 @@ did:synapse:{method-specific-id}
|
||||
|
||||
```go
|
||||
type HybridLookup struct {
|
||||
// L1: 本地缓存(内存,TTL 1分钟)
|
||||
LocalCache map[string]*AgentRecord
|
||||
|
||||
// L2: DHT 网络(分钟级一致性)
|
||||
DHT DHTClient
|
||||
|
||||
// L3: 区块链(最终一致性源)
|
||||
Blockchain BlockchainClient
|
||||
// L1: 本地缓存(内存,TTL 1分钟)
|
||||
LocalCache map[string]*AgentRecord
|
||||
|
||||
// L2: DHT 网络(分钟级一致性)
|
||||
DHT DHTClient
|
||||
|
||||
// L3: 区块链(最终一致性源)
|
||||
Blockchain BlockchainClient
|
||||
}
|
||||
|
||||
func (h *HybridLookup) Find(agentID string) (*AgentRecord, error) {
|
||||
// 1. 查本地缓存
|
||||
if record, ok := h.LocalCache.Get(agentID); ok {
|
||||
if record.IsFresh() {
|
||||
return record, nil
|
||||
}
|
||||
}
|
||||
|
||||
// 2. 查 DHT
|
||||
if record, err := h.DHT.FindValue(agentID); err == nil {
|
||||
// 验证签名
|
||||
if record.VerifySignature() {
|
||||
h.LocalCache.Set(agentID, record)
|
||||
return record, nil
|
||||
}
|
||||
}
|
||||
|
||||
// 3. 查区块链(最终源)
|
||||
if record, err := h.Blockchain.Lookup(agentID); err == nil {
|
||||
// 验证链上签名(已由链上合约验证过)
|
||||
h.LocalCache.Set(agentID, record)
|
||||
// 广播到 DHT 加速后续查询
|
||||
h.DHT.Store(agentID, record)
|
||||
return record, nil
|
||||
}
|
||||
|
||||
return nil, ErrAgentNotFound
|
||||
// 1. 查本地缓存
|
||||
if record, ok := h.LocalCache.Get(agentID); ok {
|
||||
if record.IsFresh() {
|
||||
return record, nil
|
||||
}
|
||||
}
|
||||
|
||||
// 2. 查 DHT
|
||||
if record, err := h.DHT.FindValue(agentID); err == nil {
|
||||
// 验证签名
|
||||
if record.VerifySignature() {
|
||||
h.LocalCache.Set(agentID, record)
|
||||
return record, nil
|
||||
}
|
||||
}
|
||||
|
||||
// 3. 查区块链(最终源)
|
||||
if record, err := h.Blockchain.Lookup(agentID); err == nil {
|
||||
// 验证链上签名(已由链上合约验证过)
|
||||
h.LocalCache.Set(agentID, record)
|
||||
// 广播到 DHT 加速后续查询
|
||||
h.DHT.Store(agentID, record)
|
||||
return record, nil
|
||||
}
|
||||
|
||||
return nil, ErrAgentNotFound
|
||||
}
|
||||
```
|
||||
|
||||
@@ -570,13 +579,13 @@ func (h *HybridLookup) Find(agentID string) (*AgentRecord, error) {
|
||||
|
||||
区块链还可实现链上治理功能:
|
||||
|
||||
| 功能 | 说明 |
|
||||
|------|------|
|
||||
| 功能 | 说明 |
|
||||
|------|---------------------------|
|
||||
| 质押机制 | Agent 注册需质押代币,恶意行为被 slash |
|
||||
| 信誉评分 | 链上可查的 Agent 信誉分 |
|
||||
| 服务定价 | 智能合约自动结算任务费用 |
|
||||
| 争议仲裁 | 链上投票仲裁 Agent 纠纷 |
|
||||
| 协议升级 | 通过 DAO 投票决定协议升级 |
|
||||
| 信誉评分 | 链上可查的 Agent 信誉分 |
|
||||
| 服务定价 | 智能合约自动结算任务费用 |
|
||||
| 争议仲裁 | 链上投票仲裁 Agent 纠纷 |
|
||||
| 协议升级 | 通过 DAO 投票决定协议升级 |
|
||||
|
||||
---
|
||||
|
||||
@@ -584,12 +593,12 @@ func (h *HybridLookup) Find(agentID string) (*AgentRecord, error) {
|
||||
|
||||
### 5.1 冲突场景
|
||||
|
||||
| 场景 | 说明 |
|
||||
|------|------|
|
||||
| 同一公钥注册多个别名 | 允许(同一 Agent 的多个别名) |
|
||||
| 不同公钥生成相同 AgentID | 不可能(公钥哈希唯一) |
|
||||
| 伪造他人 AgentID | 不可能(无法伪造签名) |
|
||||
| Endpoint 欺骗 | 需要额外验证 |
|
||||
| 场景 | 说明 |
|
||||
|------------------|--------------------|
|
||||
| 同一公钥注册多个别名 | 允许(同一 Agent 的多个别名) |
|
||||
| 不同公钥生成相同 AgentID | 不可能(公钥哈希唯一) |
|
||||
| 伪造他人 AgentID | 不可能(无法伪造签名) |
|
||||
| Endpoint 欺骗 | 需要额外验证 |
|
||||
|
||||
### 5.2 Endpoint 绑定验证
|
||||
|
||||
@@ -611,33 +620,33 @@ func (h *HybridLookup) Find(agentID string) (*AgentRecord, error) {
|
||||
```go
|
||||
// 挑战消息
|
||||
type Challenge struct {
|
||||
ChallengeID string // 挑战 ID
|
||||
Nonce []byte // 随机数
|
||||
Timestamp int64 // 发送时间
|
||||
ChallengeID string // 挑战 ID
|
||||
Nonce []byte // 随机数
|
||||
Timestamp int64 // 发送时间
|
||||
}
|
||||
|
||||
// 响应消息
|
||||
type ChallengeResponse struct {
|
||||
ChallengeID string // 对应的挑战 ID
|
||||
Nonce []byte // 原样返回的随机数
|
||||
Signature []byte // 对 Nonce 的签名
|
||||
ChallengeID string // 对应的挑战 ID
|
||||
Nonce []byte // 原样返回的随机数
|
||||
Signature []byte // 对 Nonce 的签名
|
||||
}
|
||||
|
||||
// 验证流程
|
||||
func VerifyEndpoint(endpoint string, publicKey []byte, challenge *Challenge) bool {
|
||||
// 1. 发送挑战到 Endpoint
|
||||
resp := SendChallenge(endpoint, challenge)
|
||||
|
||||
// 2. 验证响应
|
||||
if resp.ChallengeID != challenge.ChallengeID {
|
||||
return false // 挑战 ID 不匹配
|
||||
}
|
||||
if !bytes.Equal(resp.Nonce, challenge.Nonce) {
|
||||
return false // Nonce 被篡改
|
||||
}
|
||||
|
||||
// 3. 验证签名
|
||||
return crypto.Verify(publicKey, challenge.Nonce, resp.Signature)
|
||||
// 1. 发送挑战到 Endpoint
|
||||
resp := SendChallenge(endpoint, challenge)
|
||||
|
||||
// 2. 验证响应
|
||||
if resp.ChallengeID != challenge.ChallengeID {
|
||||
return false // 挑战 ID 不匹配
|
||||
}
|
||||
if !bytes.Equal(resp.Nonce, challenge.Nonce) {
|
||||
return false // Nonce 被篡改
|
||||
}
|
||||
|
||||
// 3. 验证签名
|
||||
return crypto.Verify(publicKey, challenge.Nonce, resp.Signature)
|
||||
}
|
||||
```
|
||||
|
||||
@@ -678,40 +687,40 @@ func VerifyEndpoint(endpoint string, publicKey []byte, challenge *Challenge) boo
|
||||
|
||||
### 6.2 生命周期消息
|
||||
|
||||
| 状态 | 说明 | 触发条件 |
|
||||
|------|------|---------|
|
||||
| offline | 离线 | 初始状态或主动注销 |
|
||||
| online | 上线中 | 注册完成,等待首次心跳 |
|
||||
| active | 活跃 | 定期心跳维持 |
|
||||
| 状态 | 说明 | 触发条件 |
|
||||
|------------|-----|-----------------|
|
||||
| offline | 离线 | 初始状态或主动注销 |
|
||||
| online | 上线中 | 注册完成,等待首次心跳 |
|
||||
| active | 活跃 | 定期心跳维持 |
|
||||
| refreshing | 刷新中 | 更新 Endpoint 或别名 |
|
||||
| suspended | 挂起 | 心跳超时,未注销 |
|
||||
| offline | 离线 | 注销或永久离线 |
|
||||
| suspended | 挂起 | 心跳超时,未注销 |
|
||||
| offline | 离线 | 注销或永久离线 |
|
||||
|
||||
### 6.3 消息类型
|
||||
|
||||
| 消息类型 | 方向 | 说明 |
|
||||
|---------|------|------|
|
||||
| `identity:register` | → 网络 | 注册 Agent 身份 |
|
||||
| `identity:refresh` | → 网络 | 刷新注册信息 |
|
||||
| `identity:challenge` | 双向 | Endpoint 验证挑战 |
|
||||
| `identity:challenge_response` | 双向 | 挑战响应 |
|
||||
| `identity:revoke` | → 网络 | 注销身份 |
|
||||
| `identity:lookup` | → 网络 | 查询 Agent 信息 |
|
||||
| `identity:lookup_response` | → 网络 | 查询响应 |
|
||||
| `identity:announce` | → 网络 | 广播在线状态 |
|
||||
| `identity:heartbeat` | → 网络 | 心跳保活 |
|
||||
| 消息类型 | 方向 | 说明 |
|
||||
|-------------------------------|------|---------------|
|
||||
| `identity:register` | → 网络 | 注册 Agent 身份 |
|
||||
| `identity:refresh` | → 网络 | 刷新注册信息 |
|
||||
| `identity:challenge` | 双向 | Endpoint 验证挑战 |
|
||||
| `identity:challenge_response` | 双向 | 挑战响应 |
|
||||
| `identity:revoke` | → 网络 | 注销身份 |
|
||||
| `identity:lookup` | → 网络 | 查询 Agent 信息 |
|
||||
| `identity:lookup_response` | → 网络 | 查询响应 |
|
||||
| `identity:announce` | → 网络 | 广播在线状态 |
|
||||
| `identity:heartbeat` | → 网络 | 心跳保活 |
|
||||
|
||||
### 6.4 Register 载荷
|
||||
|
||||
```go
|
||||
type IdentityRegisterPayload struct {
|
||||
AgentID string // Agent 标识
|
||||
Alias string // 人类可读别名
|
||||
Endpoint string // 网络地址
|
||||
PublicKey []byte // 公钥
|
||||
TTL int64 // 注册有效期
|
||||
Version uint64 // 版本号
|
||||
Signature []byte // Agent 签名
|
||||
AgentID string // Agent 标识
|
||||
Alias string // 人类可读别名
|
||||
Endpoint string // 网络地址
|
||||
PublicKey []byte // 公钥
|
||||
TTL int64 // 注册有效期
|
||||
Version uint64 // 版本号
|
||||
Signature []byte // Agent 签名
|
||||
}
|
||||
```
|
||||
|
||||
@@ -719,10 +728,10 @@ type IdentityRegisterPayload struct {
|
||||
|
||||
```go
|
||||
type IdentityHeartbeatPayload struct {
|
||||
AgentID string // Agent 标识
|
||||
Endpoint string // 当前 Endpoint(可能变化)
|
||||
TTL int64 // 续期时间
|
||||
Signature []byte // Agent 签名
|
||||
AgentID string // Agent 标识
|
||||
Endpoint string // 当前 Endpoint(可能变化)
|
||||
TTL int64 // 续期时间
|
||||
Signature []byte // Agent 签名
|
||||
}
|
||||
```
|
||||
|
||||
@@ -732,48 +741,48 @@ type IdentityHeartbeatPayload struct {
|
||||
|
||||
### 7.1 威胁模型
|
||||
|
||||
| 威胁 | 场景 | 防护措施 |
|
||||
|------|------|---------|
|
||||
| 身份伪造 | 攻击者声称自己是他人 | 公钥派生 ID + 签名验证 |
|
||||
| Endpoint 欺骗 | 攻击者声称他人 Endpoint | 挑战-响应协议 |
|
||||
| 重放攻击 | 攻击者重放旧消息 | 时间戳 + Nonce |
|
||||
| 中间人攻击 | 拦截并修改消息 | TLS + 签名验证 |
|
||||
| 女巫攻击 | 一个节点伪装多个身份 | 工作量证明或权益证明(可选) |
|
||||
| 日食攻击 | 隔离目标节点 | 多路径查询 |
|
||||
| 威胁 | 场景 | 防护措施 |
|
||||
|-------------|------------------|----------------|
|
||||
| 身份伪造 | 攻击者声称自己是他人 | 公钥派生 ID + 签名验证 |
|
||||
| Endpoint 欺骗 | 攻击者声称他人 Endpoint | 挑战-响应协议 |
|
||||
| 重放攻击 | 攻击者重放旧消息 | 时间戳 + Nonce |
|
||||
| 中间人攻击 | 拦截并修改消息 | TLS + 签名验证 |
|
||||
| 女巫攻击 | 一个节点伪装多个身份 | 工作量证明或权益证明(可选) |
|
||||
| 日食攻击 | 隔离目标节点 | 多路径查询 |
|
||||
|
||||
### 7.2 重放攻击防护
|
||||
|
||||
```go
|
||||
type AntiReplay struct {
|
||||
RecentNonces map[string]int64 // nonce -> timestamp
|
||||
Window time.Duration // 时间窗口(5分钟)
|
||||
RecentNonces map[string]int64 // nonce -> timestamp
|
||||
Window time.Duration // 时间窗口(5分钟)
|
||||
}
|
||||
|
||||
func (a *AntiReplay) CheckAndAdd(nonce string, timestamp int64) bool {
|
||||
// 1. 检查时间戳是否在窗口内
|
||||
now := time.Now().Unix()
|
||||
if now - timestamp > int64(a.Window.Seconds()) {
|
||||
return false // 时间戳太旧
|
||||
}
|
||||
|
||||
// 2. 检查 Nonce 是否已使用
|
||||
if _, exists := a.RecentNonces[nonce]; exists {
|
||||
return false // 重放
|
||||
}
|
||||
|
||||
// 3. 记录
|
||||
a.RecentNonces[nonce] = timestamp
|
||||
return true
|
||||
// 1. 检查时间戳是否在窗口内
|
||||
now := time.Now().Unix()
|
||||
if now - timestamp > int64(a.Window.Seconds()) {
|
||||
return false // 时间戳太旧
|
||||
}
|
||||
|
||||
// 2. 检查 Nonce 是否已使用
|
||||
if _, exists := a.RecentNonces[nonce]; exists {
|
||||
return false // 重放
|
||||
}
|
||||
|
||||
// 3. 记录
|
||||
a.RecentNonces[nonce] = timestamp
|
||||
return true
|
||||
}
|
||||
```
|
||||
|
||||
### 7.3 私钥保护
|
||||
|
||||
| 场景 | 建议 |
|
||||
|------|------|
|
||||
| 本地运行 | 使用密钥文件 + 操作系统密钥链 |
|
||||
| 云端运行 | 使用 HSM/KMS |
|
||||
| 嵌入式设备 | 使用 TPM |
|
||||
| 场景 | 建议 |
|
||||
|------------|---------------------------------|
|
||||
| 本地运行 | 使用密钥文件 + 操作系统密钥链 |
|
||||
| 云端运行 | 使用 HSM/KMS |
|
||||
| 嵌入式设备 | 使用 TPM |
|
||||
| 多 Agent 共享 | 密钥分片(如 Shamir's Secret Sharing) |
|
||||
|
||||
---
|
||||
@@ -786,33 +795,33 @@ func (a *AntiReplay) CheckAndAdd(nonce string, timestamp int64) bool {
|
||||
|
||||
```go
|
||||
type AgentEndpoint struct {
|
||||
AgentID string // 扩展:基于公钥派生
|
||||
AgentName string // 人类可读名称
|
||||
SystemID string // 所属系统
|
||||
Endpoint string // 回调端点
|
||||
Version string // Agent 版本
|
||||
|
||||
// 新增字段
|
||||
PublicKey []byte // 公钥(用于验证)
|
||||
Namespace string // 命名空间
|
||||
Alias string // 人类可读别名
|
||||
AgentID string // 扩展:基于公钥派生
|
||||
AgentName string // 人类可读名称
|
||||
SystemID string // 所属系统
|
||||
Endpoint string // 回调端点
|
||||
Version string // Agent 版本
|
||||
|
||||
// 新增字段
|
||||
PublicKey []byte // 公钥(用于验证)
|
||||
Namespace string // 命名空间
|
||||
Alias string // 人类可读别名
|
||||
}
|
||||
```
|
||||
|
||||
### 8.2 与灵脉(Meridian)的整合
|
||||
|
||||
| 模式 | 行为 |
|
||||
|------|------|
|
||||
| 中心化可用 | 使用灵脉作为主注册表,本草案作为备份 |
|
||||
| 去中心化 | 使用本草案的 DHT 机制,完全去中心化 |
|
||||
| 混合模式 | 核心 Agent 使用中心化,边缘 Agent 使用去中心化 |
|
||||
| 模式 | 行为 |
|
||||
|-------|--------------------------------|
|
||||
| 中心化可用 | 使用灵脉作为主注册表,本草案作为备份 |
|
||||
| 去中心化 | 使用本草案的 DHT 机制,完全去中心化 |
|
||||
| 混合模式 | 核心 Agent 使用中心化,边缘 Agent 使用去中心化 |
|
||||
|
||||
### 8.3 与灵玺(Sigil)的整合
|
||||
|
||||
| 组件 | 职责 |
|
||||
|------|------|
|
||||
| 灵玺(Sigil) | 密钥管理、签名验证 |
|
||||
| 本草案 | ID 生成、发现协议、生命周期 |
|
||||
| 组件 | 职责 |
|
||||
|-----------|-----------------|
|
||||
| 灵玺(Sigil) | 密钥管理、签名验证 |
|
||||
| 本草案 | ID 生成、发现协议、生命周期 |
|
||||
|
||||
---
|
||||
|
||||
@@ -820,36 +829,36 @@ type AgentEndpoint struct {
|
||||
|
||||
### 9.1 消息类型列表
|
||||
|
||||
| 类型 | 协议前缀 | 说明 |
|
||||
|------|---------|------|
|
||||
| `identity:register` | 前端 | 注册身份 |
|
||||
| `identity:refresh` | 前端 | 刷新注册 |
|
||||
| `identity:revoke` | 前端 | 注销身份 |
|
||||
| `identity:challenge` | 前端 | 挑战请求 |
|
||||
| `identity:challenge_response` | 前端 | 挑战响应 |
|
||||
| `identity:lookup` | 前端 | 查询身份 |
|
||||
| `identity:lookup_response` | 前端 | 查询响应 |
|
||||
| `identity:announce` | 前端 | 广播在线 |
|
||||
| `identity:heartbeat` | 前端 | 心跳保活 |
|
||||
| `dht:ping` | DHT | 节点探测 |
|
||||
| `dht:store` | DHT | 存储记录 |
|
||||
| `dht:find_node` | DHT | 查找节点 |
|
||||
| `dht:find_value` | DHT | 查找值 |
|
||||
| `dht:notify` | DHT | 通知更新 |
|
||||
| 类型 | 协议前缀 | 说明 |
|
||||
|-------------------------------|------|------|
|
||||
| `identity:register` | 前端 | 注册身份 |
|
||||
| `identity:refresh` | 前端 | 刷新注册 |
|
||||
| `identity:revoke` | 前端 | 注销身份 |
|
||||
| `identity:challenge` | 前端 | 挑战请求 |
|
||||
| `identity:challenge_response` | 前端 | 挑战响应 |
|
||||
| `identity:lookup` | 前端 | 查询身份 |
|
||||
| `identity:lookup_response` | 前端 | 查询响应 |
|
||||
| `identity:announce` | 前端 | 广播在线 |
|
||||
| `identity:heartbeat` | 前端 | 心跳保活 |
|
||||
| `dht:ping` | DHT | 节点探测 |
|
||||
| `dht:store` | DHT | 存储记录 |
|
||||
| `dht:find_node` | DHT | 查找节点 |
|
||||
| `dht:find_value` | DHT | 查找值 |
|
||||
| `dht:notify` | DHT | 通知更新 |
|
||||
|
||||
---
|
||||
|
||||
## 10. 待解决问题(Open Issues)
|
||||
|
||||
| 问题 | 说明 | 优先级 |
|
||||
|------|------|--------|
|
||||
| 隐私保护 | 公钥哈希是否暴露身份? | 高 |
|
||||
| 密钥轮换 | 私钥更换后如何保持 AgentID? | 高 |
|
||||
| 名称冲突 | 人类可读别名可能重复 | 中 |
|
||||
| 性能优化 | DHT 查找延迟 | 中 |
|
||||
| 移动 Agent | Endpoint 频繁变化 | 低 |
|
||||
| 链上 Gas 成本 | 区块链交易费用 | 中 |
|
||||
| DID 方法注册 | W3C 标准 DID 方法注册流程 | 低 |
|
||||
| 问题 | 说明 | 优先级 |
|
||||
|-----------|--------------------|-----|
|
||||
| 隐私保护 | 公钥哈希是否暴露身份? | 高 |
|
||||
| 密钥轮换 | 私钥更换后如何保持 AgentID? | 高 |
|
||||
| 名称冲突 | 人类可读别名可能重复 | 中 |
|
||||
| 性能优化 | DHT 查找延迟 | 中 |
|
||||
| 移动 Agent | Endpoint 频繁变化 | 低 |
|
||||
| 链上 Gas 成本 | 区块链交易费用 | 中 |
|
||||
| DID 方法注册 | W3C 标准 DID 方法注册流程 | 低 |
|
||||
|
||||
---
|
||||
|
||||
@@ -858,28 +867,31 @@ type AgentEndpoint struct {
|
||||
### 11.1 分阶段实现
|
||||
|
||||
**Phase 1(最小可行)**:
|
||||
|
||||
- 实现 AgentID 公钥派生
|
||||
- 实现消息签名验证
|
||||
- 使用广播进行发现
|
||||
|
||||
**Phase 2(基本功能)**:
|
||||
|
||||
- 实现分层 DHT
|
||||
- 实现生命周期管理
|
||||
- 实现挑战-响应协议
|
||||
|
||||
**Phase 3(完整功能)**:
|
||||
|
||||
- 实现完整 Kademlia
|
||||
- 实现隐私保护
|
||||
- 实现密钥轮换
|
||||
|
||||
### 11.2 推荐库
|
||||
|
||||
| 功能 | 推荐库 |
|
||||
|------|--------|
|
||||
| 加密签名 | golang.org/x/crypto/ed25519 |
|
||||
| Base58 | github.com/mr-tron/base58 |
|
||||
| DHT | github.com/anacrolix/go-libutp 或自实现 |
|
||||
| 分布式存储 | etcd/consul(混合模式) |
|
||||
| 功能 | 推荐库 |
|
||||
|--------|-------------------------------------|
|
||||
| 加密签名 | golang.org/x/crypto/ed25519 |
|
||||
| Base58 | github.com/mr-tron/base58 |
|
||||
| DHT | github.com/anacrolix/go-libutp 或自实现 |
|
||||
| 分布式存储 | etcd/consul(混合模式) |
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user