# 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. 完善文档和示例