discovery

type AgentCapabilityProvider interface {
	// ID 返回代理的唯一标识符 。
	ID() string

	// 名称返回代理名.
	Name() string

	// Get Capabilitys 返回代理的能力.
	GetCapabilities() []a2a.Capability

	// Get AgentCard返回代理的A2A卡.
	GetAgentCard() *a2a.AgentCard
}

type AgentDiscoveryIntegration struct {
	// contains filtered or unexported fields
}

type AgentExecutor interface {
	ExecuteCapability(ctx context.Context, agentID string, capability string, input any) (any, error)
}

type AgentInfo struct {
	// 卡为A2A代理卡.
	Card *a2a.AgentCard `json:"card"`

	// 状态是代理人的现状.
	Status AgentStatus `json:"status"`

	// 能力是这种代理人提供的能力清单。
	Capabilities []CapabilityInfo `json:"capabilities"`

	// 负载是代理的当前负载 (0-1).
	Load float64 `json:"load"`

	// 优先权是代理人对任务分配的优先权.
	Priority int `json:"priority"`

	// 端点是代理商的端点URL(用于远程代理).
	Endpoint string `json:"endpoint,omitempty"`

	// Is Local 表示是否为本地( 正在处理) 代理 。
	IsLocal bool `json:"is_local"`

	// 注册的At是该代理注册时.
	RegisteredAt time.Time `json:"registered_at"`

	// 最后的心跳是收到最后的心跳的时候.
	LastHeartbeat time.Time `json:"last_heartbeat"`

	// 元数据包含额外的元数据.
	Metadata map[string]string `json:"metadata,omitempty"`
}

type AgentStatus string

type CapabilityComposer struct {
	// contains filtered or unexported fields
}

type CapabilityInfo struct {
	// 能力是A2A协议中的基础能力定义.
	Capability a2a.Capability `json:"capability"`

	// AgentID是提供这种能力的代理的身份.
	AgentID string `json:"agent_id"`

	// 代理名称是提供这种能力的代理的名称 。
	AgentName string `json:"agent_name"`

	// 地位是这一能力的现状。
	Status CapabilityStatus `json:"status"`

	// 得分是依据历史表现(0-100)而得的能力分.
	Score float64 `json:"score"`

	// 负载是代理的当前负载 (0-1).
	Load float64 `json:"load"`

	// 标记是能力分类的附加标记.
	Tags []string `json:"tags,omitempty"`

	// 元数据包含额外的元数据.
	Metadata map[string]string `json:"metadata,omitempty"`

	// 注册是登记这种能力的时候。
	RegisteredAt time.Time `json:"registered_at"`

	// 上次更新是上次更新时。
	LastUpdatedAt time.Time `json:"last_updated_at"`

	// 最后一次健康检查是最后一次健康检查的时间。
	LastHealthCheck time.Time `json:"last_health_check"`

	// 成功处决是成功处决的数量。
	SuccessCount int64 `json:"success_count"`

	// 失败是被处决的次数。
	FailureCount int64 `json:"failure_count"`

	// AvgLatency是平均行刑时间.
	AvgLatency time.Duration `json:"avg_latency"`
}

type CapabilityMatcher struct {
	// contains filtered or unexported fields
}

type CapabilityRegistry struct {
	// contains filtered or unexported fields
}

type CapabilityStatus string

type Composer interface {
	// 作曲从多个代理中产生能力组成.
	Compose(ctx context.Context, req *CompositionRequest) (*CompositionResult, error)

	// 解决依赖解决了能力之间的依赖.
	ResolveDependencies(ctx context.Context, capabilities []string) (map[string][]string, error)

	// 侦测冲突能发现能力之间的冲突。
	DetectConflicts(ctx context.Context, capabilities []string) ([]Conflict, error)
}

type ComposerConfig struct {
	// MaxComposition深度是依赖分辨率的最大深度.
	MaxCompositionDepth int `json:"max_composition_depth"`

	// 默认超时是组件操作的默认超时.
	DefaultTimeout time.Duration `json:"default_timeout"`

	// 如果并非所有能力都具备,允许部分组成。
	AllowPartialComposition bool `json:"allow_partial_composition"`

	// 启用冲突探测可以检测冲突。
	EnableConflictDetection bool `json:"enable_conflict_detection"`

	// 启用依赖性决议允许自动依赖性解析 。
	EnableDependencyResolution bool `json:"enable_dependency_resolution"`
}

type CompositionExecutor struct {
	// contains filtered or unexported fields
}

type CompositionRequest struct {
	// TaskDescription是任务的自然语言描述.
	TaskDescription string `json:"task_description"`

	// 所需能力是所需能力名称的清单。
	RequiredCapabilities []string `json:"required_capabilities"`

	// 如果并非所有能力都具备,允许参与则允许部分组成。
	AllowPartial bool `json:"allow_partial"`

	// MaxAgents是包含在成分中的最大剂数.
	MaxAgents int `json:"max_agents,omitempty"`

	// 超时是组成操作的超时.
	Timeout time.Duration `json:"timeout,omitempty"`
}

type CompositionResult struct {
	// 代理是构成中的代理名单.
	Agents []*AgentInfo `json:"agents"`

	// 能力映射能力名称到代理ID.
	CapabilityMap map[string]string `json:"capability_map"`

	// 依赖是能力之间的依赖图.
	Dependencies map[string][]string `json:"dependencies,omitempty"`

	// 执行命令是推荐的执行命令.
	ExecutionOrder []string `json:"execution_order,omitempty"`

	// 冲突是已发现的冲突清单。
	Conflicts []Conflict `json:"conflicts,omitempty"`

	// 完整表示是否满足所有要求的能力。
	Complete bool `json:"complete"`

	// 缺失能力是缺失能力列表.
	MissingCapabilities []string `json:"missing_capabilities,omitempty"`
}

type Conflict struct {
	// 类型是冲突的类型。
	Type ConflictType `json:"type"`

	// 能力是相互冲突的能力清单。
	Capabilities []string `json:"capabilities"`

	// 特工是卷入冲突的特工名单.
	Agents []string `json:"agents"`

	// 描述是对冲突的描述.
	Description string `json:"description"`

	// 决议就是所建议的决议。
	Resolution string `json:"resolution,omitempty"`
}

type ConflictType string

type DiscoveryEvent struct {
	// 类型是事件类型 。
	Type DiscoveryEventType `json:"type"`

	// AgentID是涉案特工的身份证明.
	AgentID string `json:"agent_id"`

	// 能力是所涉及的能力(如果适用的话)。
	Capability string `json:"capability,omitempty"`

	// 数据包含额外事件数据.
	Data json.RawMessage `json:"data,omitempty"`

	// 时间戳是事件发生的时间 。
	Timestamp time.Time `json:"timestamp"`
}

type DiscoveryEventHandler func(event *DiscoveryEvent)

type DiscoveryEventType string

type DiscoveryFilter struct {
	// 能力过滤 通过能力名称。
	Capabilities []string `json:"capabilities,omitempty"`

	// 通过标签过滤标记 。
	Tags []string `json:"tags,omitempty"`

	// 按代理状态进行状态过滤.
	Status []AgentStatus `json:"status,omitempty"`

	// 仅针对本地代理的本地过滤器 。
	Local *bool `json:"local,omitempty"`

	// 仅用于远程代理的远程过滤器 。
	Remote *bool `json:"remote,omitempty"`
}

type DiscoveryProtocol struct {
	// contains filtered or unexported fields
}

type DiscoveryService struct {
	// contains filtered or unexported fields
}

type ExecutionResult struct {
	// Results maps capability name to its output.
	Results map[string]any
	// Errors maps capability name to its error (if any).
	Errors map[string]error
	// Duration is the total wall-clock time of the execution.
	Duration time.Duration
	// AgentsUsed lists the agent IDs that were actually invoked.
	AgentsUsed []string
	// Completed is true when all capabilities finished without error.
	Completed bool
}

type HealthCheckResult struct {
	// 代理ID是代理的身份证明.
	AgentID string `json:"agent_id"`

	// 健康指示剂是否健康.
	Healthy bool `json:"healthy"`

	// 状态是代理状态.
	Status AgentStatus `json:"status"`

	// 短暂性是健康检查的短暂性。
	Latency time.Duration `json:"latency"`

	// 信件是可选信件 。
	Message string `json:"message,omitempty"`

	// 时间戳是进行健康检查的时候。
	Timestamp time.Time `json:"timestamp"`
}

type HealthChecker struct {
	// contains filtered or unexported fields
}

type HealthCheckerConfig struct {
	// 间距是指健康检查之间的间隔.
	Interval time.Duration

	// 暂停是健康检查的暂停。
	Timeout time.Duration

	// 体质不健康 阈值是标记不健康前连续失败的次数.
	UnhealthyThreshold int
}

type InMemoryRegistryStore struct {
	// contains filtered or unexported fields
}

type IntegrationConfig struct {
	// 自动登记使代理自动登记成为可能。
	AutoRegister bool `json:"auto_register"`

	// 自动注销记录器允许在代理停止时自动注销登记 。
	AutoUnregister bool `json:"auto_unregister"`

	// 加载报告Interval是报告代理加载的间隔.
	LoadReportInterval time.Duration `json:"load_report_interval"`

	// 默认端点是本地代理的默认端点 。
	DefaultEndpoint string `json:"default_endpoint"`

	// 默认版本是代理的默认版本.
	DefaultVersion string `json:"default_version"`
}

type MatchRequest struct {
	// TaskDescription是任务的自然语言描述.
	TaskDescription string `json:"task_description"`

	// 所需能力是所需能力名称的清单。
	RequiredCapabilities []string `json:"required_capabilities,omitempty"`

	// 首选能力是首选能力名列表.
	PreferredCapabilities []string `json:"preferred_capabilities,omitempty"`

	// 需求 标记是需要标记的列表.
	RequiredTags []string `json:"required_tags,omitempty"`

	// 被排除的代理人是被排除的代理人身份列表.
	ExcludedAgents []string `json:"excluded_agents,omitempty"`

	// MinScore是所需的最低能力分数.
	MinScore float64 `json:"min_score,omitempty"`

	// MaxLoad是最大可接受负载.
	MaxLoad float64 `json:"max_load,omitempty"`

	// 限制是返回的最大结果数。
	Limit int `json:"limit,omitempty"`

	// 战略是使用的匹配战略。
	Strategy MatchStrategy `json:"strategy,omitempty"`

	// 超时是匹配操作的超时.
	Timeout time.Duration `json:"timeout,omitempty"`
}

type MatchResult struct {
	// 代理是匹配的代理信息。
	Agent *AgentInfo `json:"agent"`

	// 匹配能力是匹配能力列表.
	MatchedCapabilities []CapabilityInfo `json:"matched_capabilities"`

	// 得分为总比分(0-100).
	Score float64 `json:"score"`

	// 信心是比赛的信心水平 (0-1).
	Confidence float64 `json:"confidence"`

	// 理由就是比赛的原因
	Reason string `json:"reason,omitempty"`
}

type MatchStrategy string

type Matcher interface {
	// Match 找到匹配给定请求的代理 。
	Match(ctx context.Context, req *MatchRequest) ([]*MatchResult, error)

	// MatchOne 找到指定请求的最佳匹配代理 。
	MatchOne(ctx context.Context, req *MatchRequest) (*MatchResult, error)

	// 分数根据请求计算代理商的比分。
	Score(ctx context.Context, agent *AgentInfo, req *MatchRequest) (float64, error)
}

type MatcherConfig struct {
	// 默认策略是默认匹配策略.
	DefaultStrategy MatchStrategy `json:"default_strategy"`

	// 默认限制是匹配结果的默认限制 。
	DefaultLimit int `json:"default_limit"`

	// 默认超时是匹配操作的默认超时.
	DefaultTimeout time.Duration `json:"default_timeout"`

	// MinScore Threershold是比赛的最低得分门槛.
	MinScoreThreshold float64 `json:"min_score_threshold"`

	// 载重是积分(0-1)中载重.
	LoadWeight float64 `json:"load_weight"`

	// 分数(ScoreWight)是分数(0-1)中能力分数的权重.
	ScoreWeight float64 `json:"score_weight"`

	// latencyWight是积分(0-1)中耐久的重量.
	LatencyWeight float64 `json:"latency_weight"`

	// 启用语义匹配可实现语义匹配任务描述.
	EnableSemanticMatching bool `json:"enable_semantic_matching"`

	// 语义相似 阈值是语义相似性的阈值.
	SemanticSimilarityThreshold float64 `json:"semantic_similarity_threshold"`
}

type Protocol interface {
	// 启动发现协议 。
	Start(ctx context.Context) error

	// 停止停止发现协议。
	Stop(ctx context.Context) error

	// 公告向网络宣布本地代理.
	Announce(ctx context.Context, info *AgentInfo) error

	// 发现在网络上发现了特工.
	Discover(ctx context.Context, filter *DiscoveryFilter) ([]*AgentInfo, error)

	// 订阅代理通知 。
	Subscribe(handler func(*AgentInfo)) string

	// 从代理通知中取消订阅。
	Unsubscribe(subscriptionID string)
}

type ProtocolConfig struct {
	// 启用本地启用本地( 正在处理中) 发现 。
	EnableLocal bool `json:"enable_local"`

	// 启用 HTTP 启用基于 HTTP 的远程发现 。
	EnableHTTP bool `json:"enable_http"`

	// HTTPPort是HTTP发现服务器的端口.
	HTTPPort int `json:"http_port"`

	// HTTPHost是HTTP发现服务器的主机.
	HTTPHost string `json:"http_host"`

	// 启用多播可以基于多播的发现.
	EnableMulticast bool `json:"enable_multicast"`

	// 多播Address是多播组地址.
	MulticastAddress string `json:"multicast_address"`

	// 多播口是多播口.
	MulticastPort int `json:"multicast_port"`

	// 公告Interval是定期公告的间隔.
	AnnounceInterval time.Duration `json:"announce_interval"`

	// 发现 超时是发现操作的超时.
	DiscoveryTimeout time.Duration `json:"discovery_timeout"`

	// MaxPeers是跟踪的最大对等者数量.
	MaxPeers int `json:"max_peers"`
}

type Registry interface {
	// 代理人对具有其能力的代理人进行登记。
	RegisterAgent(ctx context.Context, info *AgentInfo) error

	// 未注册代理 未经注册代理。
	UnregisterAgent(ctx context.Context, agentID string) error

	// 更新代理更新一个代理的信息 。
	UpdateAgent(ctx context.Context, info *AgentInfo) error

	// Get Agent通过身份识别找到一个特工.
	GetAgent(ctx context.Context, agentID string) (*AgentInfo, error)

	// ListAgents列出所有注册代理.
	ListAgents(ctx context.Context) ([]*AgentInfo, error)

	// 注册能力登记一种代理的能力。
	RegisterCapability(ctx context.Context, agentID string, cap *CapabilityInfo) error

	// 未注册能力不注册 一种能力。
	UnregisterCapability(ctx context.Context, agentID string, capabilityName string) error

	// 更新能力更新一个能力.
	UpdateCapability(ctx context.Context, agentID string, cap *CapabilityInfo) error

	// Get Capability通过代理身份和姓名检索能力.
	GetCapability(ctx context.Context, agentID string, capabilityName string) (*CapabilityInfo, error)

	// List Capabilitys 列出一个代理的所有能力.
	ListCapabilities(ctx context.Context, agentID string) ([]CapabilityInfo, error)

	// Find Capabilitys 在所有特工中按名称找到能力.
	FindCapabilities(ctx context.Context, capabilityName string) ([]CapabilityInfo, error)

	// 更新代理状态更新代理状态 。
	UpdateAgentStatus(ctx context.Context, agentID string, status AgentStatus) error

	// 更新 AgentLoad 更新一个代理的负载 。
	UpdateAgentLoad(ctx context.Context, agentID string, load float64) error

	// 记录 Execution 记录一个执行结果 一个能力。
	RecordExecution(ctx context.Context, agentID string, capabilityName string, success bool, latency time.Duration) error

	// 订阅了发现事件。
	Subscribe(handler DiscoveryEventHandler) string

	// 不订阅来自发现事件的用户 。
	Unsubscribe(subscriptionID string)

	// 关闭注册 。
	Close() error
}

type RegistryConfig struct {
	// 健康检查Interval是健康检查的间隔.
	HealthCheckInterval time.Duration `json:"health_check_interval"`

	// 健康检查 暂停是健康检查的暂停。
	HealthCheckTimeout time.Duration `json:"health_check_timeout"`

	// 体质不健康 阈值是指在标记不健康之前,健康检查失败的次数.
	UnhealthyThreshold int `json:"unhealthy_threshold"`

	// 移除Unhealty 之后是清除不健康剂的期限。
	RemoveUnhealthyAfter time.Duration `json:"remove_unhealthy_after"`

	// 启用健康检查可以定期进行健康检查。
	EnableHealthCheck bool `json:"enable_health_check"`

	// 默认能力分数是新能力的默认分数.
	DefaultCapabilityScore float64 `json:"default_capability_score"`
}

type RegistryOption func(*CapabilityRegistry)

type RegistryStore interface {
	Save(ctx context.Context, agent *AgentInfo) error
	Load(ctx context.Context, id string) (*AgentInfo, error)
	LoadAll(ctx context.Context) ([]*AgentInfo, error)
	Delete(ctx context.Context, id string) error
}

type ResourceRequirement struct {
	// 能力 名称是能力的名称.
	CapabilityName string `json:"capability_name"`

	// CPUCores是所需的CPU核心.
	CPUCores float64 `json:"cpu_cores"`

	// 内存MB是MB中所需的内存.
	MemoryMB int `json:"memory_mb"`

	// GPUrered表示是否需要GPU.
	GPURequired bool `json:"gpu_required"`

	// 专属资源是一份必须专属的资源清单。
	ExclusiveResources []string `json:"exclusive_resources"`
}

type ServiceConfig struct {
	// 书记官处配置
	Registry *RegistryConfig `json:"registry"`

	// 匹配器配置
	Matcher *MatcherConfig `json:"matcher"`

	// 作曲家配置
	Composer *ComposerConfig `json:"composer"`

	// 协议配置
	Protocol *ProtocolConfig `json:"protocol"`

	// 启用自动注册可自动注册本地代理。
	EnableAutoRegistration bool `json:"enable_auto_registration"`

	// Heartbeat Interval是发送心跳的间隔.
	HeartbeatInterval time.Duration `json:"heartbeat_interval"`

	// 启用度量衡启用了度量衡收集 。
	EnableMetrics bool `json:"enable_metrics"`
}