246 lines
8.2 KiB
Markdown
246 lines
8.2 KiB
Markdown
# A2A 协议迁移说明
|
||
|
||
## 概述
|
||
|
||
本文档记录了从 `ai-video-factory` 项目中抽离 A2A（Agent-to-Agent）协议和 Group（群组）相关代码到独立模块的过程。
|
||
|
||
## 源项目信息
|
||
|
||
- **源项目**: `ai-video-factory`
|
||
- **源路径**: `ai-video-factory/a2aprotocol/`
|
||
- **目标项目**: `dp-headless`
|
||
- **目标路径**: `dp-headless/a2a/`
|
||
|
||
## 模块路径变更
|
||
|
||
| 项目 | 模块路径 |
|
||
|------|----------|
|
||
| 源 | `ai-video-factory/a2aprotocol/` |
|
||
| 目标 | `dp-headless/a2a/` |
|
||
|
||
所有 Go 文件中的 import 路径已从 `ai-video-factory/a2aprotocol/xxx` 更新为 `dp-headless/a2a/xxx`。
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
a2a/
|
||
├── go.mod # Go 模块定义
|
||
├── proto/
|
||
│ └── a2a.proto # gRPC 协议定义
|
||
├── types/ # 核心类型定义
|
||
│ ├── types.go # 基础类型、消息类型、任务状态
|
||
│ ├── content.go # 内容类型（文本、图片、视频、音频等）
|
||
│ └── errors.go # 错误定义
|
||
├── p2p/ # P2P 协议
|
||
│ └── protocol.go # 点对点任务处理协议
|
||
├── group/ # 群组协议
|
||
│ └── protocol.go # 群组协作协议（创建、解散、任务拆分合并）
|
||
├── routing/ # 消息路由
|
||
│ └── router.go # 消息路由器（P2P/群组分发）
|
||
├── transport/ # 传输层
|
||
│ ├── transport.go # HTTP 传输实现
|
||
│ └── multipart_polling.go # 多部分文件传输和轮询客户端
|
||
├── capabilities/ # 能力发现
|
||
│ └── provider.go # Agent 能力提供者
|
||
├── externalapi/ # 外部 REST API
|
||
│ └── handler.go # 简化的 RESTful API 处理器
|
||
├── sdk/ # SDK
|
||
│ └── client.go # 外部调用者 SDK 客户端
|
||
├── grpcapi/ # gRPC API
|
||
│ ├── a2a.pb.go # gRPC 消息生成代码
|
||
│ ├── a2a_grpc.pb.go # gRPC 服务生成代码
|
||
│ ├── client.go # gRPC 客户端实现
|
||
│ └── server.go # gRPC 服务端实现
|
||
├── hil/ # 人机协同（HiL）
|
||
│ └── protocol.go # 人工介入任务处理协议
|
||
└── examples/ # 示例代码
|
||
└── main.go # 完整使用示例
|
||
```
|
||
|
||
## 迁移的文件清单
|
||
|
||
### types 包（3 个文件）
|
||
- `types/types.go` - 核心数据类型：AgentEndpoint、A2AMessage、TaskPayload、TaskStatus 等
|
||
- `types/content.go` - 内容类型：TextContent、ImageContent、VideoContent、AudioContent、FileContent
|
||
- `types/errors.go` - 错误定义：TaskError、错误码常量
|
||
|
||
### p2p 包（1 个文件）
|
||
- `p2p/protocol.go` - P2P 协议实现：任务提交、状态更新、结果回调、取消任务
|
||
|
||
### group 包（1 个文件）
|
||
- `group/protocol.go` - 群组协议实现：群组创建/解散、成员管理、任务拆分/合并、投票机制
|
||
|
||
### routing 包（1 个文件）
|
||
- `routing/router.go` - 消息路由器：根据消息类型分发到 P2P 或群组处理器
|
||
|
||
### transport 包（2 个文件）
|
||
- `transport/transport.go` - HTTP 传输：发送消息、处理回调、签名验证
|
||
- `transport/multipart_polling.go` - 多部分文件传输和轮询客户端
|
||
|
||
### capabilities 包（1 个文件）
|
||
- `capabilities/provider.go` - Agent 能力提供者：能力声明、能力查询
|
||
|
||
### externalapi 包（1 个文件）
|
||
- `externalapi/handler.go` - 外部 REST API：任务提交/查询/取消、能力查询
|
||
|
||
### sdk 包（1 个文件）
|
||
- `sdk/client.go` - SDK 客户端：封装 A2A 协议调用，简化外部集成
|
||
|
||
### grpcapi 包（4 个文件）
|
||
- `grpcapi/a2a.pb.go` - Protobuf 生成的消息类型
|
||
- `grpcapi/a2a_grpc.pb.go` - Protobuf 生成的 gRPC 服务接口
|
||
- `grpcapi/client.go` - gRPC 客户端实现
|
||
- `grpcapi/server.go` - gRPC 服务端实现
|
||
|
||
### hil 包（1 个文件）
|
||
- `hil/protocol.go` - 人机协同协议：人工决策请求/响应、任务挂起/恢复
|
||
|
||
### proto（1 个文件）
|
||
- `proto/a2a.proto` - gRPC 协议定义文件
|
||
|
||
### examples（1 个文件）
|
||
- `examples/main.go` - 完整使用示例
|
||
|
||
**总计：17 个 Go 源文件 + 1 个 proto 文件 + 1 个 go.mod**
|
||
|
||
## 核心功能
|
||
|
||
### 1. P2P 任务协议
|
||
- 任务提交与响应
|
||
- 任务状态查询与更新
|
||
- 任务取消
|
||
- 进度回调
|
||
- 信息缺失通知
|
||
|
||
### 2. 群组协作协议
|
||
- 群组创建与解散
|
||
- 成员加入与离开
|
||
- 任务拆分与分发
|
||
- 子任务结果收集
|
||
- 结果合并
|
||
- 投票机制（发起投票、提交投票、公布结果）
|
||
|
||
### 3. 传输层
|
||
- HTTP 回调模式
|
||
- 轮询模式
|
||
- 同步模式
|
||
- 混合模式
|
||
- HMAC 签名验证
|
||
- 多部分文件上传
|
||
|
||
### 4. 能力发现
|
||
- Agent 能力声明
|
||
- 能力查询接口
|
||
- 支持的任务类型
|
||
- 支持的传输模式
|
||
- 并发能力限制
|
||
|
||
### 5. 人机协同（HiL）
|
||
- 人工决策请求
|
||
- 决策响应
|
||
- 任务挂起与恢复
|
||
- 超时处理
|
||
|
||
### 6. gRPC 支持
|
||
- TaskService - 任务服务
|
||
- A2AMessageService - 消息服务
|
||
- CapabilitiesService - 能力服务
|
||
- GroupService - 群组服务
|
||
- HealthService - 健康检查
|
||
|
||
## 使用示例
|
||
|
||
### 快速开始
|
||
|
||
```go
|
||
package main
|
||
|
||
import (
|
||
"dp-headless/a2a/capabilities"
|
||
"dp-headless/a2a/externalapi"
|
||
"dp-headless/a2a/group"
|
||
"dp-headless/a2a/p2p"
|
||
"dp-headless/a2a/routing"
|
||
"dp-headless/a2a/transport"
|
||
"dp-headless/a2a/types"
|
||
)
|
||
|
||
func main() {
|
||
// 1. 定义 Agent 端点
|
||
agentEndpoint := types.AgentEndpoint{
|
||
AgentID: "my-agent",
|
||
AgentName: "我的Agent",
|
||
SystemID: "my-system",
|
||
Endpoint: "http://localhost:8080/api/v1/a2a/callback",
|
||
Version: "1.0.0",
|
||
}
|
||
|
||
// 2. 配置能力提供者
|
||
caps := &capabilities.AgentCapabilityProvider{
|
||
AgentID: agentEndpoint.AgentID,
|
||
AgentName: agentEndpoint.AgentName,
|
||
SystemID: agentEndpoint.SystemID,
|
||
SupportedTaskTypes: []capabilities.SupportedTaskType{
|
||
{Type: "text_generation", Name: "文本生成"},
|
||
},
|
||
SupportGroups: true,
|
||
SupportHiL: true,
|
||
}
|
||
|
||
// 3. 创建 P2P 协议处理器
|
||
p2pProtocol := p2p.NewP2PProtocol(agentEndpoint, caps,
|
||
func(taskID string, taskType string, payload map[string]interface{}) (map[string]interface{}, error) {
|
||
// 处理任务逻辑
|
||
return map[string]interface{}{"result": "success"}, nil
|
||
})
|
||
|
||
// 4. 创建群组协议处理器
|
||
groupConfig := &group.GroupConfig{MaxGroupSize: 10}
|
||
groupProtocol := group.NewGroupProtocol(agentEndpoint, nil, groupConfig)
|
||
|
||
// 5. 配置消息路由
|
||
router := routing.NewMessageRouter(agentEndpoint)
|
||
router.RegisterP2PHandler(p2pProtocol)
|
||
router.RegisterGroupHandler(groupProtocol)
|
||
|
||
// 6. 启动 HTTP 服务
|
||
httpTransport := transport.NewHTTPTransport(agentEndpoint, nil, router)
|
||
extHandler := externalapi.NewExternalAPIHandler(p2pProtocol, caps, httpTransport)
|
||
|
||
mux := http.NewServeMux()
|
||
extHandler.RegisterRoutes(mux, "/api/v1/a2a")
|
||
http.ListenAndServe(":8080", mux)
|
||
}
|
||
```
|
||
|
||
完整示例请参考 `examples/main.go`。
|
||
|
||
## 依赖项
|
||
|
||
```
|
||
- github.com/golang/protobuf v1.5.4
|
||
- github.com/gorilla/websocket v1.5.3
|
||
- golang.org/x/image v0.42.0
|
||
- google.golang.org/grpc v1.68.0
|
||
- google.golang.org/protobuf v1.35.2
|
||
- modernc.org/sqlite v1.52.0
|
||
```
|
||
|
||
## 未迁移的内容
|
||
|
||
以下内容因与 ai-video-factory 业务逻辑强耦合，未包含在本次迁移中：
|
||
|
||
1. **旧版 A2A 实现**（`a2a.go` 和 `a2a_api.go`）- 基于 SQLite 的简单实现，与视频生成工作流深度绑定
|
||
2. **数据库集成** - 旧版的 SQLite 数据库层
|
||
3. **视频工作流集成** - 与 VideoCreationWorkflow 的集成代码
|
||
|
||
如需数据库持久化，建议基于现有的协议层自行实现存储适配层。
|
||
|
||
## 后续可扩展方向
|
||
|
||
1. 添加持久化存储接口（Memory/Redis/PostgreSQL 等）
|
||
2. 实现完整的 gRPC 网关
|
||
3. 添加更多传输协议支持（WebSocket、MQTT 等）
|
||
4. 增加单元测试和集成测试
|
||
5. 完善文档和示例
|