灵隙(synapse) v1.0.0 版本

This commit is contained in:
lychang
2026-06-27 22:17:15 +08:00
parent 7b105ded96
commit 88b606b9ca
27 changed files with 12630 additions and 245 deletions

547
sdk/p2a/client.go Normal file
View File

@@ -0,0 +1,547 @@
package p2a
import (
"bytes"
"context"
"encoding/json"
"fmt"
"io"
"mime/multipart"
"net/http"
"time"
)
// =============================================================================
// Synapse Caller SDK (P2A Protocol)
// 非Agent调用方使用的客户端SDK
// 基于 P2A 协议:非 Agent 调用方通过 REST API 调用 Agent 能力
// =============================================================================
// Client 是 Synapse P2A 服务的外部调用客户端
type Client struct {
baseURL string
apiKey string
httpClient *http.Client
}
// ClientConfig 客户端配置
type ClientConfig struct {
BaseURL string
APIKey string
Timeout time.Duration
MaxRetries int
}
// NewClient 创建新的 Synapse Caller 客户端
func NewClient(config ClientConfig) *Client {
if config.Timeout == 0 {
config.Timeout = 30 * time.Second
}
return &Client{
baseURL: config.BaseURL,
apiKey: config.APIKey,
httpClient: &http.Client{Timeout: config.Timeout},
}
}
// =============================================================================
// 通用响应结构
// =============================================================================
// APIResponse 通用 API 响应
type APIResponse struct {
Success bool `json:"success"`
Message string `json:"message,omitempty"`
Error string `json:"error,omitempty"`
}
// TaskResponse 任务提交响应
type TaskResponse struct {
APIResponse
TaskID string `json:"task_id"`
Status string `json:"status"`
Message string `json:"message,omitempty"`
}
// TaskStatusResponse 任务状态响应(简化版)
type TaskStatusResponse struct {
APIResponse
TaskID string `json:"task_id"`
Status string `json:"status"`
Progress int `json:"progress"`
}
// TaskDetailResponse 任务详情响应
type TaskDetailResponse struct {
APIResponse
Task TaskInfo `json:"task"`
}
// TaskListResponse 任务列表响应
type TaskListResponse struct {
APIResponse
Tasks []TaskInfo `json:"tasks"`
Total int `json:"total"`
Limit int `json:"limit"`
Offset int `json:"offset"`
HasMore bool `json:"has_more"`
}
// TaskInfo 任务详情信息
type TaskInfo struct {
ID string `json:"id"`
Type string `json:"type"`
Status string `json:"status"`
Progress int `json:"progress"`
Message string `json:"message,omitempty"`
CreatedAt string `json:"created_at"`
UpdatedAt string `json:"updated_at"`
CompletedAt string `json:"completed_at,omitempty"`
ETA string `json:"eta,omitempty"`
Result map[string]any `json:"result,omitempty"`
Error *TaskError `json:"error,omitempty"`
ExternalTaskID string `json:"external_task_id,omitempty"`
}
// TaskError 任务错误
type TaskError struct {
Code string `json:"code"`
Message string `json:"message"`
}
// TaskRequest 任务请求
type TaskRequest struct {
TaskType string `json:"task_type"`
Payload map[string]any `json:"payload"`
ExternalTaskID string `json:"external_task_id,omitempty"`
Priority string `json:"priority,omitempty"`
CallbackURL string `json:"callback_url,omitempty"`
CallbackToken string `json:"callback_token,omitempty"`
}
// FileParam 上传文件参数
type FileParam struct {
FieldName string
Filename string
Data []byte
MimeType string
}
// =============================================================================
// 能力查询
// =============================================================================
// CapabilitiesResponse 能力查询响应
type CapabilitiesResponse struct {
APIResponse
Capabilities CapabilitiesInfo `json:"capabilities"`
}
// CapabilitiesInfo Agent 能力信息
type CapabilitiesInfo struct {
AgentID string `json:"agent_id"`
AgentName string `json:"agent_name"`
SystemID string `json:"system_id"`
ProtocolVersion string `json:"protocol_version"`
SupportedTaskTypes []SupportedTaskType `json:"supported_task_types"`
SupportedTransportModes []string `json:"supported_transport_modes"`
MaxFileSize int64 `json:"max_file_size"`
MaxConcurrentTasks int `json:"max_concurrent_tasks"`
SupportProgressUpdates bool `json:"support_progress_updates"`
SupportStreaming bool `json:"support_streaming"`
SupportHiL bool `json:"support_hil"`
SupportGroups bool `json:"support_groups"`
}
// SupportedTaskType 支持的任务类型
type SupportedTaskType struct {
Type string `json:"type"`
Name string `json:"name"`
Description string `json:"description"`
EstimatedTime string `json:"estimated_time"`
InputSchema string `json:"input_schema,omitempty"`
OutputSchema string `json:"output_schema,omitempty"`
}
// GetCapabilities 获取 Agent 能力清单
func (c *Client) GetCapabilities(ctx context.Context) (*CapabilitiesResponse, error) {
url := fmt.Sprintf("%s/api/v1/synapse/capabilities", c.baseURL)
httpReq, err := http.NewRequestWithContext(ctx, "GET", url, nil)
if err != nil {
return nil, fmt.Errorf("failed to create request: %w", err)
}
c.setAuthHeaders(httpReq)
resp, err := c.httpClient.Do(httpReq)
if err != nil {
return nil, fmt.Errorf("request failed: %w", err)
}
defer resp.Body.Close()
respBody, _ := io.ReadAll(resp.Body)
var result CapabilitiesResponse
if err := json.Unmarshal(respBody, &result); err != nil {
return nil, fmt.Errorf("failed to decode response: %w", err)
}
if resp.StatusCode >= 400 {
return &result, fmt.Errorf("API error: %s", result.Error)
}
return &result, nil
}
// =============================================================================
// 任务提交
// =============================================================================
// SubmitTask 提交任务(JSON 方式)
func (c *Client) SubmitTask(ctx context.Context, req *TaskRequest) (*TaskResponse, error) {
url := fmt.Sprintf("%s/api/v1/synapse/task", c.baseURL)
body, err := json.Marshal(req)
if err != nil {
return nil, fmt.Errorf("failed to marshal request: %w", err)
}
httpReq, err := http.NewRequestWithContext(ctx, "POST", url, bytes.NewReader(body))
if err != nil {
return nil, fmt.Errorf("failed to create request: %w", err)
}
httpReq.Header.Set("Content-Type", "application/json")
c.setAuthHeaders(httpReq)
resp, err := c.httpClient.Do(httpReq)
if err != nil {
return nil, fmt.Errorf("request failed: %w", err)
}
defer resp.Body.Close()
respBody, _ := io.ReadAll(resp.Body)
var result TaskResponse
if err := json.Unmarshal(respBody, &result); err != nil {
return nil, fmt.Errorf("failed to decode response: %w", err)
}
if resp.StatusCode >= 400 {
return &result, fmt.Errorf("API error: %s", result.Error)
}
return &result, nil
}
// SubmitTaskWithFiles 提交带文件的任务(multipart/form-data 方式)
func (c *Client) SubmitTaskWithFiles(ctx context.Context, req *TaskRequest, files []FileParam) (*TaskResponse, error) {
url := fmt.Sprintf("%s/api/v1/synapse/task/multipart", c.baseURL)
var buf bytes.Buffer
writer := multipart.NewWriter(&buf)
_ = writer.WriteField("task_type", req.TaskType)
payloadJSON, _ := json.Marshal(req.Payload)
_ = writer.WriteField("payload", string(payloadJSON))
if req.ExternalTaskID != "" {
_ = writer.WriteField("external_task_id", req.ExternalTaskID)
}
if req.Priority != "" {
_ = writer.WriteField("priority", req.Priority)
}
if req.CallbackURL != "" {
_ = writer.WriteField("callback_url", req.CallbackURL)
}
if req.CallbackToken != "" {
_ = writer.WriteField("callback_token", req.CallbackToken)
}
for _, f := range files {
var part io.Writer
var err error
if f.MimeType != "" {
part, err = writer.CreatePart(map[string][]string{
"Content-Disposition": {fmt.Sprintf(`form-data; name="%s"; filename="%s"`, f.FieldName, f.Filename)},
"Content-Type": {f.MimeType},
})
} else {
part, err = writer.CreateFormFile(f.FieldName, f.Filename)
}
if err != nil {
return nil, fmt.Errorf("failed to create form file: %w", err)
}
_, _ = part.Write(f.Data)
}
_ = writer.Close()
httpReq, err := http.NewRequestWithContext(ctx, "POST", url, &buf)
if err != nil {
return nil, fmt.Errorf("failed to create request: %w", err)
}
httpReq.Header.Set("Content-Type", writer.FormDataContentType())
c.setAuthHeaders(httpReq)
resp, err := c.httpClient.Do(httpReq)
if err != nil {
return nil, fmt.Errorf("request failed: %w", err)
}
defer resp.Body.Close()
respBody, _ := io.ReadAll(resp.Body)
var result TaskResponse
if err := json.Unmarshal(respBody, &result); err != nil {
return nil, fmt.Errorf("failed to decode response: %w", err)
}
if resp.StatusCode >= 400 {
return &result, fmt.Errorf("API error: %s", result.Error)
}
return &result, nil
}
// =============================================================================
// 任务查询
// =============================================================================
// GetTask 获取任务详情
func (c *Client) GetTask(ctx context.Context, taskID string) (*TaskDetailResponse, error) {
url := fmt.Sprintf("%s/api/v1/synapse/task/%s", c.baseURL, taskID)
httpReq, err := http.NewRequestWithContext(ctx, "GET", url, nil)
if err != nil {
return nil, fmt.Errorf("failed to create request: %w", err)
}
c.setAuthHeaders(httpReq)
resp, err := c.httpClient.Do(httpReq)
if err != nil {
return nil, fmt.Errorf("request failed: %w", err)
}
defer resp.Body.Close()
respBody, _ := io.ReadAll(resp.Body)
var result TaskDetailResponse
if err := json.Unmarshal(respBody, &result); err != nil {
return nil, fmt.Errorf("failed to decode response: %w", err)
}
if resp.StatusCode >= 400 {
return &result, fmt.Errorf("API error: %s", result.Error)
}
return &result, nil
}
// GetTaskStatus 获取任务状态(简化版)
func (c *Client) GetTaskStatus(ctx context.Context, taskID string) (*TaskStatusResponse, error) {
url := fmt.Sprintf("%s/api/v1/synapse/task/%s/status", c.baseURL, taskID)
httpReq, err := http.NewRequestWithContext(ctx, "GET", url, nil)
if err != nil {
return nil, fmt.Errorf("failed to create request: %w", err)
}
c.setAuthHeaders(httpReq)
resp, err := c.httpClient.Do(httpReq)
if err != nil {
return nil, fmt.Errorf("request failed: %w", err)
}
defer resp.Body.Close()
respBody, _ := io.ReadAll(resp.Body)
var result TaskStatusResponse
if err := json.Unmarshal(respBody, &result); err != nil {
return nil, fmt.Errorf("failed to decode response: %w", err)
}
if resp.StatusCode >= 400 {
return &result, fmt.Errorf("API error: %s", result.Error)
}
return &result, nil
}
// ListTasks 获取任务列表
func (c *Client) ListTasks(ctx context.Context, status string, limit, offset int) (*TaskListResponse, error) {
if limit <= 0 {
limit = 20
}
url := fmt.Sprintf("%s/api/v1/synapse/tasks?status=%s&limit=%d&offset=%d",
c.baseURL, status, limit, offset)
httpReq, err := http.NewRequestWithContext(ctx, "GET", url, nil)
if err != nil {
return nil, fmt.Errorf("failed to create request: %w", err)
}
c.setAuthHeaders(httpReq)
resp, err := c.httpClient.Do(httpReq)
if err != nil {
return nil, fmt.Errorf("request failed: %w", err)
}
defer resp.Body.Close()
respBody, _ := io.ReadAll(resp.Body)
var result TaskListResponse
if err := json.Unmarshal(respBody, &result); err != nil {
return nil, fmt.Errorf("failed to decode response: %w", err)
}
if resp.StatusCode >= 400 {
return &result, fmt.Errorf("API error: %s", result.Error)
}
return &result, nil
}
// =============================================================================
// 任务取消
// =============================================================================
// CancelTask 取消任务
func (c *Client) CancelTask(ctx context.Context, taskID string) (*TaskResponse, error) {
url := fmt.Sprintf("%s/api/v1/synapse/task/%s/cancel", c.baseURL, taskID)
httpReq, err := http.NewRequestWithContext(ctx, "POST", url, nil)
if err != nil {
return nil, fmt.Errorf("failed to create request: %w", err)
}
c.setAuthHeaders(httpReq)
resp, err := c.httpClient.Do(httpReq)
if err != nil {
return nil, fmt.Errorf("request failed: %w", err)
}
defer resp.Body.Close()
respBody, _ := io.ReadAll(resp.Body)
var result TaskResponse
if err := json.Unmarshal(respBody, &result); err != nil {
return nil, fmt.Errorf("failed to decode response: %w", err)
}
if resp.StatusCode >= 400 {
return &result, fmt.Errorf("API error: %s", result.Error)
}
return &result, nil
}
// =============================================================================
// 等待任务完成
// =============================================================================
// WaitForTask 等待任务完成(轮询方式)
func (c *Client) WaitForTask(ctx context.Context, taskID string, interval time.Duration) (*TaskInfo, error) {
if interval == 0 {
interval = 5 * time.Second
}
ticker := time.NewTicker(interval)
defer ticker.Stop()
for {
select {
case <-ctx.Done():
return nil, ctx.Err()
case <-ticker.C:
resp, err := c.GetTask(ctx, taskID)
if err != nil {
continue
}
switch resp.Task.Status {
case "completed", "failed", "cancelled", "rejected":
return &resp.Task, nil
}
}
}
}
// =============================================================================
// 回调验证
// =============================================================================
// CallbackRequest 回调请求结构
type CallbackRequest struct {
TaskID string `json:"task_id"`
Status string `json:"status"`
Progress int `json:"progress"`
Message string `json:"message,omitempty"`
Result map[string]any `json:"result,omitempty"`
Error *TaskError `json:"error,omitempty"`
Timestamp string `json:"timestamp"`
}
// VerifyCallback 验证回调请求签名
func (c *Client) VerifyCallback(r *http.Request, callbackToken string) bool {
if callbackToken == "" {
return true
}
token := r.Header.Get("X-Callback-Token")
return token == callbackToken
}
// =============================================================================
// 高阶 API: 快速创建任务并等待
// =============================================================================
// CreateAndWait 创建任务并等待完成
func (c *Client) CreateAndWait(ctx context.Context, taskType string, payload map[string]any, interval time.Duration) (*TaskInfo, error) {
req := &TaskRequest{
TaskType: taskType,
Payload: payload,
Priority: "normal",
}
resp, err := c.SubmitTask(ctx, req)
if err != nil {
return nil, err
}
if !resp.Success {
return nil, fmt.Errorf("task submission failed: %s", resp.Message)
}
return c.WaitForTask(ctx, resp.TaskID, interval)
}
// CreateWithCallback 创建任务并指定回调
func (c *Client) CreateWithCallback(ctx context.Context, taskType string, payload map[string]any, callbackURL, callbackToken string) (*TaskResponse, error) {
req := &TaskRequest{
TaskType: taskType,
Payload: payload,
Priority: "normal",
CallbackURL: callbackURL,
CallbackToken: callbackToken,
}
return c.SubmitTask(ctx, req)
}
// =============================================================================
// 辅助方法
// =============================================================================
func (c *Client) setAuthHeaders(req *http.Request) {
if c.apiKey != "" {
req.Header.Set("X-API-Key", c.apiKey)
}
req.Header.Set("Accept", "application/json")
}