灵隙(synapse) v1.0.0 版本

This commit is contained in:
lychang
2026-06-29 02:12:44 +08:00
parent 2c59efe0ca
commit 65710a4536
27 changed files with 1819 additions and 760 deletions

View File

@@ -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:* 类型消息 |
| 任务处理器 | 执行具体任务逻辑 |
| 回调发送器 | 发送进度、完成、失败等回调 |
| 状态查询 | 支持任务状态查询 |
| 任务处理器 | 执行具体任务逻辑 |
| 回调发送器 | 发送进度、完成、失败等回调 |
| 状态查询 | 支持任务状态查询 |
---