ai/synapse

Fork 0

Files

lychang 713292489f 灵隙(synapse) v1.0.0 版本

2026-06-27 14:08:30 +08:00

8.2 KiB

Raw Blame History

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 - 健康检查

使用示例

快速开始

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 业务逻辑强耦合，未包含在本次迁移中：

旧版 A2A 实现（a2a.go 和 a2a_api.go）- 基于 SQLite 的简单实现，与视频生成工作流深度绑定
数据库集成 - 旧版的 SQLite 数据库层
视频工作流集成 - 与 VideoCreationWorkflow 的集成代码

如需数据库持久化，建议基于现有的协议层自行实现存储适配层。

后续可扩展方向

添加持久化存储接口（Memory/Redis/PostgreSQL 等）
实现完整的 gRPC 网关
添加更多传输协议支持（WebSocket、MQTT 等）
增加单元测试和集成测试
完善文档和示例

8.2 KiB Raw Blame History Unescape Escape