ai/synapse

Fork 0

Files

lychang 88b606b9ca 灵隙(synapse) v1.0.0 版本

2026-06-27 22:17:15 +08:00

17 KiB

Raw Blame History

SDK 实现说明

版本：1.0.0
更新日期：2026-06-27
协议版本：1.0.0
关联协议：

A2A 协议

A2N 协议

P2A 协议

1. 概述

SDK 按照灵隙协议族（Synapse Protocol Suite）的三个子协议进行了模块化设计，分为三个子包，命名与协议名保持一致：

┌─────────────────────────────────────────────────────────────┐
│                        SDK (sdk/)                            │
├──────────────┬───────────────────┬───────────────────────────┤
│  sdk/p2a    │   sdk/a2a        │    sdk/a2n               │
│  P2A 协议    │  A2A 协议         │   A2N 协议               │
│  (外部调用)  │  (Agent间通信)    │   (群组协作)              │
│  ✅ 完整实现  │  ✅ 完整实现      │   ✅ 完整实现             │
└──────────────┴───────────────────┴───────────────────────────┘

2. SDK 目录结构

sdk/
├── doc.go           # SDK 包文档（使用说明）
├── p2a/
│   └── client.go   # P2A 协议 - 外部调用客户端
├── a2a/
│   └── client.go   # A2A 协议 - Agent间通信客户端
└── a2n/
    └── client.go   # A2N 协议 - 群组协作客户端

3. 第一部分：sdk/p2a - P2A 协议

协议对应：P2A 协议
版本：1.0.0
用途：非 Agent 调用方（前端、后端服务、第三方应用）通过 REST API 调用 Agent 能力

3.1 实现对应关系

P2A 协议功能	SDK 方法	位置
认证方式	`setHeaders()`	sdk/p2a/client.go
提交任务（JSON）	`SubmitTask()`	sdk/p2a/client.go
提交任务（Multipart）	`SubmitTaskWithFiles()`	sdk/p2a/client.go
获取任务详情	`GetTask()`	sdk/p2a/client.go
获取任务状态（简化版）	`GetTaskStatus()`	sdk/p2a/client.go
获取任务列表	`ListTasks()`	sdk/p2a/client.go
取消任务	`CancelTask()`	sdk/p2a/client.go
能力查询	`GetCapabilities()`	sdk/p2a/client.go
回调验证	`VerifyCallback()`	sdk/p2a/client.go
轮询等待	`WaitForTask()`	sdk/p2a/client.go

3.2 核心数据结构

// Client 客户端
type Client struct {
    baseURL    string
    apiKey     string
    httpClient *http.Client
}

// 配置
type ClientConfig struct {
    BaseURL    string
    APIKey     string
    Timeout    time.Duration
    MaxRetries int
}

// 任务请求
type TaskRequest struct {
    TaskType       string
    Payload        map[string]any
    ExternalTaskID string
    Priority       string
    CallbackURL    string
    CallbackToken  string
}

// 任务信息
type TaskInfo struct {
    ID             string
    Type           string
    Status         string
    Progress       int
    Result         map[string]any
    Error          *TaskError
}

// 文件上传参数
type FileParam struct {
    FieldName string
    Filename  string
    Data     []byte
    MimeType string
}

3.3 使用示例

import "dp-headless/synapse/sdk/p2a"

client := p2a.NewClient(p2a.ClientConfig{
    BaseURL: "https://agent-api.example.com",
    APIKey:  "your-api-key",
})

// 提交任务并等待完成
taskInfo, err := client.CreateAndWait(ctx, "text_generation", map[string]any{
    "prompt": "写一首诗",
    "style":  "古典",
}, 5*time.Second)

// 使用回调模式
resp, err := client.CreateWithCallback(ctx, "image_generation", payload,
    "https://your-domain.com/callback",
    "callback-token",
)

4. 第二部分：sdk/a2a - A2A 协议

协议对应：A2A 协议
版本：1.0.0
用途：Agent 之间的点对点通信，包含消息发送、签名验证、回调处理

4.1 实现对应关系

A2A 协议功能	SDK 方法	位置
发送任务请求	`SendTaskRequest()`	sdk/a2a/client.go
发送任务取消	`SendTaskCancel()`	sdk/a2a/client.go
发送人类决策	`SendHumanDecision()`	sdk/a2a/client.go
查询能力	`SendCapabilityQuery()`	sdk/a2a/client.go
消息签名	`signMessage()`	sdk/a2a/client.go
签名验证	`verifySignature()`	sdk/a2a/client.go
任务状态管理	`GetTaskState()`, `ListTasks()`	sdk/a2a/client.go
等待任务完成	`WaitForTask()`	sdk/a2a/client.go
回调服务	`startCallbackServer()`	sdk/a2a/client.go

4.2 核心数据结构

// Client A2A客户端
type Client struct {
    agentEndpoint    types.AgentEndpoint
    authSecret      string
    callbackHandler MessageCallbackHandler
    tasks          map[string]*A2ATaskState
}

// 配置
type ClientConfig struct {
    AgentEndpoint types.AgentEndpoint
    AuthSecret    string
    CallbackPort  int
    Timeout      time.Duration
    MaxRetries   int
}

// 消息回调处理器接口
type MessageCallbackHandler interface {
    HandleTaskRequest(ctx context.Context, msg *types.UnifiedSynapseMessage) (*types.UnifiedSynapseMessage, error)
    HandleTaskStatusUpdate(ctx context.Context, msg *types.UnifiedSynapseMessage) error
    HandleTaskComplete(ctx context.Context, msg *types.UnifiedSynapseMessage) error
    HandleTaskFailed(ctx context.Context, msg *types.UnifiedSynapseMessage) error
    HandleNeedHuman(ctx context.Context, msg *types.UnifiedSynapseMessage) error
}

// 任务状态
type A2ATaskState struct {
    TaskID   string
    Status   types.P2PTaskStatus
    Progress int
    Message  string
    Result   any
    Error    *types.SynapseError
}

4.3 使用示例

import "dp-headless/synapse/sdk/a2a"

a2aClient, err := a2a.NewClient(&a2a.ClientConfig{
    AgentEndpoint: types.AgentEndpoint{
        AgentID:   "my-agent",
        AgentName: "我的Agent",
        SystemID:  "my-system",
        Endpoint:  "http://localhost:8080/synapse/callback",
    },
    AuthSecret:   "my-hmac-secret",
    CallbackPort: 8080,
})

// 设置消息处理器
a2aClient.SetMessageHandler(&myHandler{})

// 发送任务请求给其他Agent
taskID, err := a2aClient.SendTaskRequest(ctx, targetAgent, "video_generation", map[string]any{
    "prompt": "生成一段视频",
})

5. 第三部分：sdk/a2n - A2N 协议

协议对应：A2N 协议
版本：1.0.0
用途：多 Agent 群组协作，包含群组管理、任务拆分合并、投票、升级

5.1 实现对应关系

A2N 协议功能	SDK 方法	位置
创建群组	`CreateGroup()`	sdk/a2n/client.go
加入群组	`JoinGroup()`	sdk/a2n/client.go
离开群组	`LeaveGroup()`	sdk/a2n/client.go
解散群组	`DisbandGroup()`	sdk/a2n/client.go
提交群组任务	`SubmitGroupTask()`	sdk/a2n/client.go
发送子任务结果	`SendSubtaskResult()`	sdk/a2n/client.go
发起投票	`InitiateVote()`	sdk/a2n/client.go
提交投票	`SubmitVote()`	sdk/a2n/client.go
广播消息	`Broadcast()`	sdk/a2n/client.go
升级到人类	`EscalateToHuman()`	sdk/a2n/client.go

5.2 核心数据结构

// Client A2N客户端
type Client struct {
    a2aClient   *a2a.Client
    groups      map[string]*GroupState
    eventHandler GroupEventHandler
}

// 配置
type ClientConfig struct {
    A2AClient   *a2a.Client
    EventHandler GroupEventHandler
}

// 群组状态
type GroupState struct {
    GroupID  string
    Name     string
    Topology types.GroupTopology
    Status   types.GroupStatus
    Members  []types.GroupMember
    Role     string  // "coordinator" | "worker"
}

// 群组事件处理器接口
type GroupEventHandler interface {
    OnGroupCreated(ctx context.Context, groupID string) error
    OnGroupDisbanded(ctx context.Context, groupID string) error
    OnMemberJoined(ctx context.Context, groupID string, member types.GroupMember) error
    OnMemberLeft(ctx context.Context, groupID string, agentID string) error
    OnTaskSplit(ctx context.Context, groupID string, originalTaskID string, subtasks []types.Subtask) error
    OnSubtaskProgress(ctx context.Context, groupID string, subtaskID string, progress int) error
    OnTaskMerged(ctx context.Context, groupID string, originalTaskID string, result any) error
    OnVoteInitiated(ctx context.Context, groupID string, vote types.GroupVotePayload) error
    OnVoteResult(ctx context.Context, groupID string, voteID string, option string, passed bool) error
    OnEscalation(ctx context.Context, groupID string, escalationID string, level int) error
    OnBroadcast(ctx context.Context, groupID string, sender types.AgentEndpoint, message []byte) error
}

5.3 使用示例

import (
    "dp-headless/synapse/sdk/a2n"
    "dp-headless/synapse/sdk/a2a"
)

// 创建A2A客户端
a2aClient, _ := a2a.NewClient(&a2a.ClientConfig{
    AgentEndpoint: myEndpoint,
})

// 创建A2N客户端
a2nClient, err := a2n.NewClient(&a2n.ClientConfig{
    A2AClient:    a2aClient,
    EventHandler: &myGroupHandler{},
})

// 创建群组
group, err := a2nClient.CreateGroup(ctx, "视频制作组", types.GroupTopologyStar, nil, members)

// 作为Coordinator，提交任务
subtasks, err := a2nClient.SubmitGroupTask(ctx, group.GroupID, "video_generation",
    map[string]any{"script": "..."},
    types.MergeAllSuccess,
)

// 发起投票
voteID, err := a2nClient.InitiateVote(ctx, group.GroupID,
    "选择哪个方案？",
    []string{"方案A", "方案B"},
    voterIDs,
    0.5,
    5*time.Minute,
)

6. SDK 架构总览

┌─────────────────────────────────────────────────────────────┐
│                    SDK (dp-headless/synapse/sdk)                │
├─────────────────────────────────────────────────────────────┤
│  doc.go                                                    │
│  ├── 包文档和使用说明                                       │
│  └── 指向各子包的链接                                      │
├────────────────┬────────────────┬─────────────────────────┤
│    sdk/p2a     │    sdk/a2a     │      sdk/a2n           │
│                │                │                         │
│  P2A协议        │  灵隙协议        │   A2N协议             │
│                │                │                         │
│  ├── Client    │  ├── Client    │   ├── Client           │
│  ├── 配置      │  ├── 配置      │   ├── 配置             │
│  ├── 任务操作   │  ├── 消息发送   │   ├── 群组管理         │
│  ├── 能力查询   │  ├── 任务状态   │   ├── 任务协作         │
│  └── 回调验证   │  ├── 回调服务   │   ├── 投票             │
│                │  └── 签名       │   └── 升级             │
└────────────────┴────────────────┴─────────────────────────┘

7. 快速开始

7.1 P2A 调用（外部调用者）

package main

import (
    "context"
    "fmt"

    "dp-headless/synapse/sdk/p2a"
)

func main() {
    client := p2a.NewClient(p2a.ClientConfig{
        BaseURL: "https://agent.example.com",
        APIKey:  "your-api-key",
    })

    ctx := context.Background()

    // 方式1: 轮询等待
    result, err := client.CreateAndWait(ctx, "text_generation", map[string]any{
        "prompt": "写一首诗",
    }, 5*time.Second)
    if err != nil {
        fmt.Println("Error:", err)
    }
    fmt.Printf("Result: %v\n", result.Result)

    // 方式2: 回调模式
    resp, err := client.CreateWithCallback(ctx, "image_generation",
        map[string]any{"prompt": "一只猫"},
        "https://your-domain.com/callback",
        "token",
    )
    fmt.Printf("Task ID: %s\n", resp.TaskID)
}

7.2 灵隙通信（Agent 间）

package main

import (
    "context"
    "fmt"

    "dp-headless/synapse/sdk/a2a"
    "dp-headless/synapse/types"
)

func main() {
    client, _ := a2a.NewClient(&a2a.ClientConfig{
        AgentEndpoint: types.AgentEndpoint{
            AgentID:   "agent-001",
            AgentName: "Agent 001",
            SystemID:  "my-system",
            Endpoint:  "http://localhost:8080/synapse/callback",
        },
        AuthSecret:   "secret-key",
        CallbackPort: 8080,
    })

    ctx := context.Background()
    target := types.AgentEndpoint{
        AgentID:  "agent-002",
        Endpoint: "http://agent-002:8080/synapse/callback",
    }

    // 发送任务请求
    taskID, err := client.SendTaskRequest(ctx, target, "data_analysis", map[string]any{
        "dataset": "sales.csv",
    })
    fmt.Printf("Task ID: %s\n", taskID)

    // 等待完成
    state, err := client.WaitForTask(ctx, taskID, 5*time.Minute)
    fmt.Printf("Status: %s\n", state.Status)
}

7.3 A2N 群组协作

package main

import (
    "context"
    "fmt"

    "dp-headless/synapse/sdk/a2n"
    "dp-headless/synapse/sdk/a2a"
    "dp-headless/synapse/types"
)

func main() {
    a2aClient, _ := a2a.NewClient(&a2a.ClientConfig{
        AgentEndpoint: myEndpoint,
    })

    a2nClient, _ := a2n.NewClient(&a2n.ClientConfig{
        A2AClient: a2aClient,
    })

    ctx := context.Background()

    // 创建群组
    group, _ := a2nClient.CreateGroup(ctx, "协作组", types.GroupTopologyStar, nil, []types.AgentEndpoint{
        {AgentID: "member-1", Endpoint: "http://member-1:8080"},
        {AgentID: "member-2", Endpoint: "http://member-2:8080"},
    })

    fmt.Printf("Group ID: %s\n", group.GroupID)

    // 提交任务
    subtasks, _ := a2nClient.SubmitGroupTask(ctx, group.GroupID, "video_generation",
        map[string]any{"script": "..."},
        types.MergeAllSuccess,
    )

    fmt.Printf("Split into %d subtasks\n", len(subtasks))
}

8. 协议与包名对应关系

协议名称	协议文档	SDK 包名	包路径
灵隙原始协议（Synapse Raw Protocol）	01-synapse-raw-protocol.md	-	纲领性文档
A2A 协议	02-a2a-protocol.md	`a2a`	`sdk/a2a/`
A2N 协议	03-a2n-protocol.md	`a2n`	`sdk/a2n/`
P2A 协议	04-p2a-protocol.md	`p2a`	`sdk/p2a/`

所有协议版本：1.0.0

9. 扩展建议

优先级	扩展项	说明
高	gRPC 传输	添加 gRPC 协议支持
高	WebSocket	添加 WebSocket 流式传输
中	批量操作	批量任务提交、批量查询
中	指标监控	内置指标收集
低	多语言 SDK	Python、JavaScript 等

附录：相关文件索引

文件路径	说明
sdk/doc.go	SDK 包文档
sdk/p2a/client.go	P2A 客户端实现
sdk/a2a/client.go	A2A 客户端实现
sdk/a2n/client.go	A2N 客户端实现
externalapi/handler.go	P2A 协议服务端实现
p2p/protocol.go	A2A 协议核心实现
group/protocol.go	A2N 协议核心实现
types/types.go	公共类型定义
transport/transport.go	HTTP 传输层实现

17 KiB Raw Blame History Unescape Escape