灵隙(synapse) v1.0.0 版本

This commit is contained in:
lychang
2026-06-27 14:08:30 +08:00
parent a73ff857bb
commit 713292489f
44 changed files with 21884 additions and 0 deletions

245
MIGRATION.md Normal file
View 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. 完善文档和示例