灵隙(synapse) v1.0.0 版本
This commit is contained in:
245
MIGRATION.md
Normal file
245
MIGRATION.md
Normal file
@@ -0,0 +1,245 @@
|
||||
# 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. 完善文档和示例
|
||||
Reference in New Issue
Block a user