package capabilities import ( "context" "encoding/json" "net/http" "synapse/pkg/types" ) // ============================================================================= // Capabilities Provider Interface // ============================================================================= // CapabilitiesProvider 定义Agent暴露自身能力的接口 // 所有Agent都应该实现此接口以便其他Agent查询其能力 type CapabilitiesProvider interface { // GetCapabilities 返回Agent的完整能力描述 GetCapabilities(ctx context.Context) (*types.AgentCapabilities, error) // GetSupportedInterfaces 返回Agent实现的接口列表 GetSupportedInterfaces() []ImplementedInterface // GetTaskTypeCapabilities 返回特定任务类型的详细能力 GetTaskTypeCapabilities(taskType string) (*types.SupportedTaskType, error) } // ImplementedInterface 定义Agent实现的接口 type ImplementedInterface struct { // InterfaceName 接口名称 Name string `json:"name"` // Category 接口分类 Category InterfaceCategory `json:"category"` // Version 接口版本 Version string `json:"version"` // ComplianceLevel 合规级别 (basic, complete, advanced) ComplianceLevel string `json:"compliance_level"` // Description 接口描述 Description string `json:"description"` // Methods 接口支持的方法 Methods []InterfaceMethod `json:"methods,omitempty"` // Status 接口状态 (implemented, partial, planned) Status string `json:"status"` } // InterfaceCategory 接口分类 type InterfaceCategory string const ( CategoryCore InterfaceCategory = "core" // 核心接口 CategoryP2P InterfaceCategory = "p2p" // P2P接口 CategoryGroup InterfaceCategory = "group" // 群组接口 CategoryHiL InterfaceCategory = "hil" // 人工介入接口 CategoryTransport InterfaceCategory = "transport" // 传输接口 CategorySecurity InterfaceCategory = "security" // 安全接口 CategoryManagement InterfaceCategory = "management" // 管理接口 ) // InterfaceMethod 接口方法 type InterfaceMethod struct { Name string `json:"name"` Description string `json:"description"` InputType string `json:"input_type,omitempty"` OutputType string `json:"output_type,omitempty"` Required bool `json:"required"` } // ============================================================================= // Standard Interfaces Registry // ============================================================================= // StandardInterfaces 定义Synapse协议的标准接口 var StandardInterfaces = map[string]ImplementedInterface{ // === Core Interfaces === "agent_identity": { Name: "AgentIdentity", Category: CategoryCore, Version: "1.0.0", ComplianceLevel: "basic", Description: "提供Agent身份信息接口", Status: "implemented", Methods: []InterfaceMethod{ {Name: "GetAgentID", Description: "返回Agent唯一标识", OutputType: "string", Required: true}, {Name: "GetSystemID", Description: "返回Agent所属系统ID", OutputType: "string", Required: true}, {Name: "GetEndpoint", Description: "返回Agent回调端点", OutputType: "string", Required: true}, {Name: "GetName", Description: "返回Agent名称", OutputType: "string", Required: false}, {Name: "GetVersion", Description: "返回Agent版本", OutputType: "string", Required: false}, }, }, "message_handler": { Name: "MessageHandler", Category: CategoryCore, Version: "1.0.0", ComplianceLevel: "basic", Description: "处理接收到的Synapse消息", Status: "implemented", Methods: []InterfaceMethod{ {Name: "HandleMessage", Description: "处理消息并返回响应", InputType: "UnifiedSynapseMessage", OutputType: "UnifiedSynapseMessage", Required: true}, {Name: "GetProtocolVersion", Description: "返回支持的协议版本", OutputType: "string", Required: true}, }, }, "capabilities_provider": { Name: "CapabilitiesProvider", Category: CategoryCore, Version: "1.0.0", ComplianceLevel: "basic", Description: "暴露Agent能力信息", Status: "implemented", Methods: []InterfaceMethod{ {Name: "GetCapabilities", Description: "返回完整能力描述", OutputType: "AgentCapabilities", Required: true}, {Name: "GetSupportedInterfaces", Description: "返回实现的接口列表", OutputType: "[]ImplementedInterface", Required: true}, }, }, // === P2P Interfaces === "task_handler": { Name: "P2PTaskHandler", Category: CategoryP2P, Version: "1.0.0", ComplianceLevel: "basic", Description: "处理P2P任务请求", Status: "implemented", Methods: []InterfaceMethod{ {Name: "ExecuteTask", Description: "执行任务并返回结果", InputType: "taskType, payload", OutputType: "any", Required: true}, {Name: "ValidateTask", Description: "验证任务是否可执行", InputType: "taskType, payload", OutputType: "[]MissingField, bool", Required: true}, {Name: "GetSupportedTaskTypes", Description: "返回支持的任务类型列表", OutputType: "[]string", Required: true}, {Name: "GetEstimatedDuration", Description: "预估任务执行时间", InputType: "taskType, payload", OutputType: "int", Required: false}, }, }, "callback_sender": { Name: "CallbackSender", Category: CategoryP2P, Version: "1.0.0", ComplianceLevel: "complete", Description: "发送回调消息", Status: "implemented", Methods: []InterfaceMethod{ {Name: "SendCallback", Description: "发送回调消息", InputType: "endpoint, message", OutputType: "error", Required: true}, {Name: "SendCallbackWithRetry", Description: "带重试的回调发送", InputType: "endpoint, message, maxRetries", OutputType: "error", Required: false}, }, }, "callback_receiver": { Name: "CallbackReceiver", Category: CategoryP2P, Version: "1.0.0", ComplianceLevel: "basic", Description: "接收回调消息的HTTP端点", Status: "implemented", Methods: []InterfaceMethod{ {Name: "POST /synapse/callback", Description: "接收回调消息的HTTP端点", InputType: "UnifiedSynapseMessage", OutputType: "HTTP 200", Required: true}, }, }, // === Polling Interfaces === "task_status_provider": { Name: "TaskStatusProvider", Category: CategoryP2P, Version: "1.0.0", ComplianceLevel: "complete", Description: "提供任务状态查询接口", Status: "implemented", Methods: []InterfaceMethod{ {Name: "GET /synapse/task/{id}", Description: "查询单个任务状态", OutputType: "TaskStatusResponse", Required: true}, {Name: "GET /synapse/tasks", Description: "查询任务列表", OutputType: "TaskListResponse", Required: true}, {Name: "GET /synapse/task/{id}/events", Description: "查询任务事件流", OutputType: "TaskEventsResponse", Required: false}, }, }, "polling_client": { Name: "PollingClient", Category: CategoryTransport, Version: "1.0.0", ComplianceLevel: "complete", Description: "轮询客户端", Status: "implemented", Methods: []InterfaceMethod{ {Name: "GetTaskStatus", Description: "获取任务状态", InputType: "taskID", OutputType: "TaskInfo", Required: true}, {Name: "StartPolling", Description: "开始持续轮询", InputType: "taskID, callback", OutputType: "error", Required: true}, {Name: "StopPolling", Description: "停止轮询", InputType: "taskID", Required: true}, }, }, // === Group Interfaces === "group_handler": { Name: "GroupTaskHandler", Category: CategoryGroup, Version: "1.0.0", ComplianceLevel: "advanced", Description: "处理群组任务协作", Status: "implemented", Methods: []InterfaceMethod{ {Name: "ExecuteSubtask", Description: "执行子任务", InputType: "subtaskID, payload", OutputType: "any", Required: true}, {Name: "MergeResults", Description: "合并子任务结果", InputType: "results, strategy", OutputType: "any", Required: true}, {Name: "ValidateTaskSplit", Description: "验证任务分解方案", InputType: "taskType, requirements", OutputType: "[]Subtask, bool", Required: true}, }, }, "group_manager": { Name: "GroupManager", Category: CategoryGroup, Version: "1.0.0", ComplianceLevel: "advanced", Description: "管理群组", Status: "implemented", Methods: []InterfaceMethod{ {Name: "CreateGroup", Description: "创建群组", InputType: "GroupConfig", OutputType: "Group", Required: true}, {Name: "JoinGroup", Description: "加入群组", InputType: "groupID", OutputType: "error", Required: true}, {Name: "LeaveGroup", Description: "离开群组", InputType: "groupID", OutputType: "error", Required: true}, {Name: "DisbandGroup", Description: "解散群组", InputType: "groupID", OutputType: "error", Required: true}, }, }, "voting_handler": { Name: "VotingHandler", Category: CategoryGroup, Version: "1.0.0", ComplianceLevel: "advanced", Description: "处理投票共识", Status: "implemented", Methods: []InterfaceMethod{ {Name: "InitiateVote", Description: "发起投票", InputType: "VoteRequest", OutputType: "Vote", Required: true}, {Name: "SubmitVote", Description: "提交投票", InputType: "voteID, option", OutputType: "error", Required: true}, {Name: "GetVoteStatus", Description: "获取投票状态", InputType: "voteID", OutputType: "VoteStatus", Required: true}, }, }, // === HiL Interfaces === "hil_handler": { Name: "HILHandler", Category: CategoryHiL, Version: "1.0.0", ComplianceLevel: "complete", Description: "处理人工介入请求", Status: "implemented", Methods: []InterfaceMethod{ {Name: "RequestHumanDecision", Description: "请求人工决策", InputType: "HILRequest", OutputType: "HILResponse", Required: true}, {Name: "ProcessHumanDecision", Description: "处理人工决策响应", InputType: "HILResponse", OutputType: "error", Required: true}, {Name: "GetHILStatus", Description: "获取HiL请求状态", InputType: "hilID", OutputType: "HILStatus", Required: true}, }, }, "escalation_handler": { Name: "EscalationHandler", Category: CategoryHiL, Version: "1.0.0", ComplianceLevel: "advanced", Description: "处理升级请求", Status: "implemented", Methods: []InterfaceMethod{ {Name: "EscalateToHuman", Description: "升级到人工", InputType: "taskID, reason, level", OutputType: "HILRequest", Required: true}, {Name: "EscalateToGroup", Description: "升级到群组", InputType: "taskID, groupID", OutputType: "error", Required: true}, }, }, // === Transport Interfaces === "http_transport": { Name: "HTTPTransport", Category: CategoryTransport, Version: "1.0.0", ComplianceLevel: "basic", Description: "HTTP传输", Status: "implemented", Methods: []InterfaceMethod{ {Name: "Send", Description: "发送HTTP消息", InputType: "endpoint, message", OutputType: "error", Required: true}, {Name: "Start", Description: "启动服务", Required: true}, {Name: "Stop", Description: "停止服务", Required: true}, }, }, "multipart_transport": { Name: "MultipartTransport", Category: CategoryTransport, Version: "1.0.0", ComplianceLevel: "complete", Description: "Multipart文件传输", Status: "implemented", Methods: []InterfaceMethod{ {Name: "SendTaskWithFiles", Description: "发送带文件的任务", InputType: "endpoint, message, files", OutputType: "error", Required: true}, {Name: "ParseMultipartRequest", Description: "解析multipart请求", InputType: "HTTPRequest", OutputType: "Message, Files", Required: true}, }, }, "hybrid_transport": { Name: "HybridTransport", Category: CategoryTransport, Version: "1.0.0", ComplianceLevel: "complete", Description: "混合传输(回调+轮询)", Status: "implemented", Methods: []InterfaceMethod{ {Name: "SendTaskWithHybridFallback", Description: "发送任务并自动切换", InputType: "endpoint, message, callback", OutputType: "error", Required: true}, {Name: "NotifyCallbackReceived", Description: "通知回调已收到", InputType: "taskID", Required: true}, }, }, "streaming_transport": { Name: "StreamingTransport", Category: CategoryTransport, Version: "1.0.0", ComplianceLevel: "advanced", Description: "流式传输", Status: "implemented", Methods: []InterfaceMethod{ {Name: "WebSocket /synapse/stream", Description: "WebSocket流式端点", Required: true}, {Name: "GET /synapse/stream (SSE)", Description: "SSE流式端点", Required: false}, }, }, // === Security Interfaces === "authenticator": { Name: "Authenticator", Category: CategorySecurity, Version: "1.0.0", ComplianceLevel: "basic", Description: "认证和签名", Status: "implemented", Methods: []InterfaceMethod{ {Name: "Authenticate", Description: "验证消息签名", InputType: "message, signature", OutputType: "bool", Required: true}, {Name: "Sign", Description: "签名消息", InputType: "message", OutputType: "string", Required: true}, }, }, "idempotency_handler": { Name: "IdempotencyHandler", Category: CategorySecurity, Version: "1.0.0", ComplianceLevel: "basic", Description: "幂等性处理", Status: "implemented", Methods: []InterfaceMethod{ {Name: "CheckIdempotency", Description: "检查消息幂等性", InputType: "messageID", OutputType: "bool", Required: true}, {Name: "MarkProcessed", Description: "标记消息已处理", InputType: "messageID", Required: true}, }, }, } // ============================================================================= // Extended AgentCapabilities // ============================================================================= // ExtendedAgentCapabilities 扩展的Agent能力描述 type ExtendedAgentCapabilities struct { // 基础能力 types.AgentCapabilities // 实现的接口列表 ImplementedInterfaces []ImplementedInterface `json:"implemented_interfaces"` // 合规级别 summary ComplianceSummary ComplianceSummary `json:"compliance_summary"` // 自定义能力 CustomCapabilities map[string]any `json:"custom_capabilities,omitempty"` // 依赖的其他Agent Dependencies []AgentDependency `json:"dependencies,omitempty"` // 服务健康信息 HealthInfo HealthInfo `json:"health_info"` } // ComplianceSummary 合规级别摘要 type ComplianceSummary struct { BasicImplemented int `json:"basic_implemented"` BasicRequired int `json:"basic_required"` CompleteImplemented int `json:"complete_implemented"` CompleteRequired int `json:"complete_required"` AdvancedImplemented int `json:"advanced_implemented"` OverallLevel string `json:"overall_level"` // "basic", "complete", "advanced" } // AgentDependency Agent依赖 type AgentDependency struct { AgentID string `json:"agent_id"` SystemID string `json:"system_id"` Required bool `json:"required"` Description string `json:"description"` } // HealthInfo 健康信息 type HealthInfo struct { Status string `json:"status"` // "healthy", "degraded", "unhealthy" LastCheckAt string `json:"last_check_at"` Uptime int64 `json:"uptime_seconds"` Version string `json:"version"` ActiveTasks int `json:"active_tasks"` } // ============================================================================= // HTTP Handler for Capabilities Endpoint // ============================================================================= // CapabilitiesHandler 处理 GET /synapse/capabilities 请求 type CapabilitiesHandler struct { provider CapabilitiesProvider } // NewCapabilitiesHandler 创建能力查询处理器 func NewCapabilitiesHandler(provider CapabilitiesProvider) *CapabilitiesHandler { return &CapabilitiesHandler{provider: provider} } // ServeHTTP 处理HTTP请求 func (h *CapabilitiesHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) { if r.Method != http.MethodGet { http.Error(w, "Method not allowed", http.StatusMethodNotAllowed) return } ctx := r.Context() // 获取能力 caps, err := h.provider.GetCapabilities(ctx) if err != nil { http.Error(w, err.Error(), http.StatusInternalServerError) return } // 获取实现的接口 interfaces := h.provider.GetSupportedInterfaces() // 构建扩展能力响应 extended := &ExtendedAgentCapabilities{ AgentCapabilities: *caps, ImplementedInterfaces: interfaces, ComplianceSummary: CalculateComplianceSummary(interfaces), } // 返回响应 w.Header().Set("Content-Type", "application/json") w.Header().Set("X-Synapse-Version", "1.0.0") resp := types.NewCapabilitiesResponse(&extended.AgentCapabilities) respJSON, _ := json.Marshal(resp) w.Write(respJSON) } // ============================================================================= // Helper Functions // ============================================================================= // CalculateComplianceSummary 计算合规摘要 func CalculateComplianceSummary(interfaces []ImplementedInterface) ComplianceSummary { summary := ComplianceSummary{} for _, iface := range interfaces { switch iface.ComplianceLevel { case "basic": summary.BasicImplemented++ case "complete": summary.CompleteImplemented++ case "advanced": summary.AdvancedImplemented++ } } // 计算要求的数量 for _, std := range StandardInterfaces { switch std.ComplianceLevel { case "basic": summary.BasicRequired++ case "complete": summary.CompleteRequired++ } } // 确定整体级别 if summary.BasicImplemented >= summary.BasicRequired { if summary.CompleteImplemented >= summary.CompleteRequired { if summary.AdvancedImplemented > 0 { summary.OverallLevel = "advanced" } else { summary.OverallLevel = "complete" } } else { summary.OverallLevel = "basic" } } else { summary.OverallLevel = "none" } return summary } // GetStandardInterface 获取标准接口定义 func GetStandardInterface(name string) *ImplementedInterface { if iface, ok := StandardInterfaces[name]; ok { return &iface } return nil } // GetAllStandardInterfaces 获取所有标准接口 func GetAllStandardInterfaces() map[string]ImplementedInterface { return StandardInterfaces } // GetInterfacesByCategory 获取指定分类的接口 func GetInterfacesByCategory(category InterfaceCategory) []ImplementedInterface { var result []ImplementedInterface for _, iface := range StandardInterfaces { if iface.Category == category { result = append(result, iface) } } return result } // GetInterfacesByComplianceLevel 获取指定合规级别的接口 func GetInterfacesByComplianceLevel(level string) []ImplementedInterface { var result []ImplementedInterface for _, iface := range StandardInterfaces { if iface.ComplianceLevel == level { result = append(result, iface) } } return result } // CheckInterfaceCompliance 检查接口合规性 func CheckInterfaceCompliance(implemented []ImplementedInterface) map[string][]string { result := map[string][]string{ "missing_basic": []string{}, "missing_complete": []string{}, "implemented": []string{}, } implementedSet := make(map[string]bool) for _, iface := range implemented { implementedSet[iface.Name] = true } for name, std := range StandardInterfaces { if implementedSet[std.Name] { result["implemented"] = append(result["implemented"], name) } else { switch std.ComplianceLevel { case "basic": result["missing_basic"] = append(result["missing_basic"], name) case "complete": result["missing_complete"] = append(result["missing_complete"], name) } } } return result }