灵隙(synapse) v1.0.0 版本

This commit is contained in:
lychang
2026-06-27 14:09:10 +08:00
parent 5798b30078
commit e0025a2563
4 changed files with 1514 additions and 1 deletions

465
docs/02-a2a-protocol.md Normal file
View File

@@ -0,0 +1,465 @@
# A2A 协议(Agent-to-Agent Protocol)
> 版本:1.0.0
> 状态:草案
> 类型:实现规范
> 基于:[灵隙原始协议(Synapse Raw Protocol) v1.0.0](./01-synapse-raw-protocol.md)
---
## 1. 概述
A2A 协议定义了两个 Agent 之间进行点对点(P2P)任务协作的完整规范,包括消息类型、交互流程、状态机、接口定义与错误处理。
### 1.1 适用场景
- 单个任务请求与响应
- 任务状态实时同步
- 任务取消
- 信息补全交互
- 人类介入决策
### 1.2 非适用场景
- 多 Agent 群组协作(参见 A2N 组群协议)
- 非 Agent 调用方接入(参见 P2A 调用协议)
---
## 2. 消息类型
### 2.1 消息类型清单
所有消息类型前缀:`p2p:`
| 消息类型 | 方向 | 说明 |
|---------|------|------|
| `p2p:task_request` | 请求方 → 执行方 | 提交任务请求 |
| `p2p:task_confirm` | 执行方 → 请求方 | 确认接受任务 |
| `p2p:task_reject` | 执行方 → 请求方 | 拒绝任务 |
| `p2p:task_need_info` | 执行方 → 请求方 | 请求补充信息 |
| `p2p:task_info_provided` | 请求方 → 执行方 | 提供补充信息 |
| `p2p:task_status_update` | 执行方 → 请求方 | 任务进度更新 |
| `p2p:task_complete` | 执行方 → 请求方 | 任务完成 |
| `p2p:task_failed` | 执行方 → 请求方 | 任务失败 |
| `p2p:task_cancel` | 请求方 → 执行方 | 取消任务 |
| `p2p:task_ack` | 双向 | 任务级确认 |
| `p2p:ack` | 双向 | 通用确认 |
| `p2p:nack` | 双向 | 通用否定确认(错误) |
| `p2p:heartbeat` | 双向 | 心跳保活 |
| `p2p:capability_query` | 双向 | 查询对方能力 |
| `p2p:capability_response` | 双向 | 返回能力清单 |
| `p2p:task_need_human` | 执行方 → 请求方 | 请求人类介入 |
| `p2p:human_decision` | 请求方 → 执行方 | 人类决策结果 |
### 2.2 消息类型完整定义
参见代码:[types/types.go](../types/types.go)
---
## 3. 任务状态机
### 3.1 状态定义
| 状态 | 说明 |
|------|------|
| `idle` | 空闲(初始状态) |
| `pending` | 待确认(已发送请求,等待确认) |
| `confirmed` | 已确认(对方接受任务) |
| `executing` | 执行中 |
| `info_needed` | 需要信息 |
| `info_provided` | 信息已提供 |
| `need_human` | 需要人类介入 |
| `human_deciding` | 人类决策中 |
| `human_approved` | 人类已批准 |
| `human_rejected` | 人类已拒绝 |
| `completed` | 已完成(终态) |
| `failed` | 已失败(终态) |
| `cancelled` | 已取消(终态) |
| `rejected` | 已拒绝(终态) |
### 3.2 状态流转图
```
请求方视角:
idle → pending → confirmed → executing → completed
↓ ↓ → failed
rejected info_needed → cancelled
↑↓
info_provided
↓
need_human
↑↓
human_decision
```
---
## 4. 核心交互流程
### 4.1 正常任务提交流程
```
请求方 Agent 执行方 Agent
| |
|-------- task_request ------------->| 1. 提交任务
| |
|<------- task_confirm / task_reject -| 2. 确认/拒绝
| |
|<------- task_status_update --------| 3. 进度更新(多次)
| |
|<------- task_complete -------------| 4. 完成通知
| |
|-------- task_ack ----------------->| 5. 确认收到
| |
```
### 4.2 信息补全流程
```
请求方 Agent 执行方 Agent
| |
|-------- task_request ------------->|
| |
|<------- task_need_info ------------| 发现信息缺失
| |
|-------- task_info_provided ------->| 补充信息
| |
|<------- task_status_update --------| 继续执行
| |
```
### 4.3 人类介入流程
```
请求方 Agent 执行方 Agent
| |
|-------- task_request ------------->|
| |
|<------- task_need_human -----------| 需要人类决策
| |
| [人类做出决策] |
| |
|-------- human_decision ----------->| 决策结果
| |
|<------- task_status_update --------| 继续执行
| |
```
### 4.4 任务取消流程
```
请求方 Agent 执行方 Agent
| |
|-------- task_request ------------->|
| |
|-------- task_cancel -------------->| 取消任务
| |
|<------- task_ack ------------------| 确认取消
| |
```
---
## 5. 接口规范
### 5.1 P2P 协议处理器接口
**接口定义:**
```go
type P2PProtocol interface {
// 处理收到的消息
HandleMessage(ctx context.Context, msg *UnifiedSynapseMessage) (*UnifiedSynapseMessage, error)
// 设置任务处理器
SetTaskHandler(h TaskHandler)
// 设置回调发送器
SetCallbackSender(s CallbackSender)
// 获取 Agent 端点
AgentEndpoint() AgentEndpoint
// 查询任务状态
GetTaskStatus(taskID string) (P2PTaskStatus, bool)
// 列出所有任务
ListTasks() map[string]P2PTaskStatus
}
```
**参考实现:** [p2p/protocol.go](../p2p/protocol.go)
### 5.2 任务处理器接口
```go
type TaskHandler interface {
// 执行任务并返回结果
ExecuteTask(ctx context.Context, taskType string, payload map[string]interface{}) (any, error)
// 验证任务是否可执行,返回缺失字段列表和是否可处理
ValidateTask(taskType string, payload map[string]interface{}) ([]MissingField, bool)
// 获取能力列表
GetCapabilities() []string
}
```
**说明:**
- `ExecuteTask`:实际执行业务逻辑的入口
- `ValidateTask`:在任务确认前调用,用于判断是否接受任务或需要补充信息
- `GetCapabilities`:返回 Agent 支持的任务类型列表
### 5.3 回调发送器接口
```go
type CallbackSender interface {
// 向远程 Agent 发送消息
SendCallback(ctx context.Context, endpoint string, msg *UnifiedSynapseMessage) error
}
```
**说明:**
- 传输层实现此接口
- 支持多种传输方式(HTTP、gRPC、WebSocket 等)
### 5.4 配置项
```go
type P2PConfig struct {
MaxRetries int // 最大重试次数(默认 5)
RetryBaseDelay time.Duration // 重试基础延迟(默认 2s,指数退避)
TaskTimeout time.Duration // 任务执行超时(默认 5 分钟)
HeartbeatInterval time.Duration // 心跳间隔(默认 30 秒)
}
```
---
## 6. 载荷格式
### 6.1 TaskRequestPayload(任务请求)
```json
{
"task": {
"id": "task-xxx",
"type": "text_generation",
"priority": "normal",
"deadline": "2026-01-01T00:00:00Z",
"payload": {
"prompt": "写一首诗",
"style": "古典"
}
},
"context": {
"session_id": "sess-xxx",
"parent_task_id": "parent-xxx",
"correlation_id": "corr-xxx",
"metadata": {}
}
}
```
### 6.2 TaskConfirmPayload(任务确认)
```json
{
"task_id": "task-xxx",
"confirmed": true,
"estimated_duration": 120,
"expected_completion": "2026-01-01T00:02:00Z",
"capabilities_used": ["text_generation"],
"constraints": {
"max_retries": 3,
"fallback_enabled": true
}
}
```
### 6.3 TaskRejectPayload(任务拒绝)
```json
{
"task_id": "task-xxx",
"reason": {
"code": "capability_lacking",
"message": "不支持该任务类型",
"details": null
},
"alternatives": {
"suggested_agent_id": "other-agent",
"retry_after": 300,
"partial_support": false
}
}
```
### 6.4 TaskStatusUpdatePayload(状态更新)
```json
{
"task_id": "task-xxx",
"status": "executing",
"progress": 50,
"message": "正在生成内容",
"intermediate_result": null
}
```
### 6.5 TaskCompletePayload(任务完成)
```json
{
"task_id": "task-xxx",
"result": {
"output_type": "text",
"output": "生成的文本内容...",
"metadata": {
"tokens": 1024,
"model": "gpt-4"
}
},
"summary": "任务已完成"
}
```
### 6.6 TaskFailedPayload(任务失败)
```json
{
"task_id": "task-xxx",
"error": {
"code": "execution_error",
"message": "模型调用超时",
"recoverable": true,
"details": null
},
"partial_result": null
}
```
### 6.7 TaskNeedInfoPayload(需要信息)
```json
{
"task_id": "task-xxx",
"missing_fields": [
{
"field": "style",
"reason": "未指定生成风格",
"suggested_value": "古典",
"alternatives": ["现代", "浪漫"]
}
],
"question": "请选择生成风格",
"required_by": "2026-01-01T00:01:00Z"
}
```
### 6.8 TaskNeedHumanPayload(需要人类)
```json
{
"task_id": "task-xxx",
"reason": {
"code": "ethical_decision",
"message": "涉及伦理决策需要人工审核"
},
"context": {
"task_summary": "生成一张人物肖像",
"current_progress": 30,
"blocked_reason": "需要确认肖像使用授权"
},
"options": [
{
"field": "authorized",
"value": true,
"pros_cons": "继续生成,假设已授权",
"confidence": 70
}
],
"escalation_level": 1,
"deadline": "2026-01-01T00:05:00Z"
}
```
### 6.9 HumanDecisionPayload(人类决策)
```json
{
"task_id": "task-xxx",
"decision_id": "dec-xxx",
"reply_to": "msg-xxx",
"decided_by": {
"user_id": "user-123",
"user_name": "张三",
"role": "reviewer"
},
"decision": {
"action": "approve",
"approved_fields": {
"authorized": true
},
"rejection_reason": ""
},
"notes": "已确认授权",
"timestamp": "2026-01-01T00:03:00Z"
}
```
**完整载荷定义:** [types/types.go](../types/types.go)
---
## 7. 错误码
| 错误码 | 说明 | HTTP 状态码(如适用) |
|--------|------|---------------------|
| `message_format_invalid` | 消息格式无效 | 400 |
| `capability_lacking` | 能力不足 | 403 |
| `agent_not_ready` | Agent 未就绪 | 503 |
| `task_not_found` | 任务不存在 | 404 |
| `task_already_completed` | 任务已完成 | 409 |
| `execution_timeout` | 执行超时 | 504 |
| `execution_failed` | 执行失败 | 500 |
| `permission_denied` | 权限不足 | 403 |
| `invalid_params` | 参数无效 | 400 |
| `rate_limited` | 限流 | 429 |
**完整错误定义:** [types/errors.go](../types/errors.go)
---
## 8. 传输要求
### 8.1 HTTP 传输
- Content-Type: `application/json`
- 请求方法:`POST`
- 端点路径:由 Agent 自行定义,建议 `/synapse/callback`
- 超时:建议 30 秒
### 8.2 签名验证(可选)
- 使用 HMAC-SHA256 签名
- 签名放在 Header:`X-Synapse-Signature`
- 或放在消息体:`signature` 字段
---
## 9. 参考实现
本协议的参考实现位于 `p2p/` 目录:
| 文件 | 说明 |
|------|------|
| [p2p/protocol.go](../p2p/protocol.go) | P2P 协议核心实现 |
| [types/types.go](../types/types.go) | 数据类型定义 |
| [types/errors.go](../types/errors.go) | 错误定义 |
| [transport/transport.go](../transport/transport.go) | HTTP 传输实现 |
---
## 附录 A:能力声明格式
参见 [灵隙原始协议(Synapse Raw Protocol) - Capability](./01-synapse-raw-protocol.md#44-capability能力)