25 KiB
25 KiB
灵隙协议实现规范：能力声明系统
版本：1.0.0 | 层级：实现层
目录
1. 核心接口 CapabilitiesProvider
每个 Agent 必须实现 CapabilitiesProvider 接口，以便其他 Agent 查询其能力。该接口是所有能力声明系统的入口点，定义了三个核心方法：
1.1 接口定义
type CapabilitiesProvider interface {
GetCapabilities(ctx context.Context) (*AgentCapabilities, error)
GetSupportedInterfaces() []ImplementedInterface
GetTaskTypeCapabilities(taskType string) (*SupportedTaskType, error)
}
1.2 方法说明
| 方法 | 返回值 | 说明 |
|---|---|---|
GetCapabilities(ctx) |
*AgentCapabilities |
返回 Agent 的完整能力描述，包括身份信息、支持的任务类型、内容类型、传输模式、资源限制以及各项特性支持标志。这是能力查询的核心方法。 |
GetSupportedInterfaces() |
[]ImplementedInterface |
返回 Agent 实现的标准接口列表。每个条目包含接口名称、分类、合规级别和版本号，用于快速判断 Agent 是否支持某项协议功能。 |
GetTaskTypeCapabilities(taskType) |
*SupportedTaskType |
返回指定任务类型的详细能力描述，包括输入输出 Schema、预估耗时、关联能力标签等。若 Agent 不支持该任务类型，应返回 nil。 |
1.3 ImplementedInterface 结构
type ImplementedInterface struct {
Name string `json:"name"`
Category InterfaceCategory `json:"category"`
ComplianceLevel Compliance `json:"compliance_level"`
Version string `json:"version"`
Description string `json:"description,omitempty"`
Metadata map[string]interface{} `json:"metadata,omitempty"`
}
1.4 调用约定
GetCapabilities应当在 Agent 启动时被注册中心调用，用于填充全局能力目录。GetSupportedInterfaces应当在 P2P 握手阶段被对端 Agent 调用，用于协商交互协议。GetTaskTypeCapabilities应当在任务提交前被调用，用于验证任务类型是否受支持以及获取输入输出约束。- 所有方法必须保持幂等性，多次调用应返回一致的结果。
2. 能力描述结构 AgentCapabilities
AgentCapabilities 是 Agent 能力声明的核心数据结构，包含了 Agent 的身份信息、支持的任务类型、内容类型、传输模式以及资源限制和特性支持标志。
2.1 完整结构定义
type AgentCapabilities 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"`
SupportedContentTypes []string `json:"supported_content_types"`
SupportedTransportModes []TransportMode `json:"supported_transport_modes"`
// ── 资源限制 ──
MaxFileSize int64 `json:"max_file_size"`
MaxConcurrentTasks int `json:"max_concurrent_tasks"`
MaxTaskDuration int `json:"max_task_duration_seconds"`
// ── 特性支持 ──
SupportProgressUpdates bool `json:"support_progress_updates"`
SupportStreaming bool `json:"support_streaming"`
SupportHiL bool `json:"support_hil"`
SupportGroups bool `json:"support_groups"`
}
2.2 字段详解
身份信息
| 字段 | 类型 | 说明 |
|---|---|---|
AgentID |
string |
Agent 唯一标识符。在整个生态系统中必须全局唯一，通常由系统 ID 和 Agent 名称组合生成。格式示例：sys_alpha_agent_01。 |
AgentName |
string |
Agent 的人类可读名称。用于日志和界面展示，如"文本生成助手"。 |
SystemID |
string |
所属系统 ID。标识该 Agent 归属于哪个系统或组织，用于跨系统路由和权限控制。 |
ProtocolVersion |
string |
协议版本号。遵循语义化版本规范，格式为 major.minor.patch，如 "1.0.0"。用于协议兼容性协商。 |
能力清单
| 字段 | 类型 | 说明 |
|---|---|---|
SupportedTaskTypes |
[]SupportedTaskType |
支持的任务类型列表。每个条目描述一种任务类型的详细能力（见第 3 章）。 |
SupportedContentTypes |
[]string |
支持的内容类型列表。使用 MIME 类型标识，如 ["text/plain", "image/png", "application/json"]。 |
SupportedTransportModes |
[]TransportMode |
支持的传输模式列表。详见 TransportMode 枚举定义。 |
TransportMode 枚举
type TransportMode string
const (
TransportModeCallback TransportMode = "callback" // 异步回调（Webhook）
TransportModePolling TransportMode = "polling" // 异步轮询
TransportModeSync TransportMode = "sync" // 同步等待
TransportModeHybrid TransportMode = "hybrid" // 回调 + 轮询兜底
)
资源限制
| 字段 | 类型 | 说明 | 默认值 |
|---|---|---|---|
MaxFileSize |
int64 |
单文件最大字节数。超过此大小的文件应当使用 URL 或流式传输。 | 10MB（10485760） |
MaxConcurrentTasks |
int |
最大并发任务数。用于流量控制和负载均衡，超过此数的任务请求将被拒绝（错误码 4004）。 | 10 |
MaxTaskDuration |
int |
单个任务最大持续时间（秒）。超过此时间的任务将被自动终止（错误码 2004）。 | 3600（1 小时） |
特性支持标志
| 字段 | 类型 | 说明 |
|---|---|---|
SupportProgressUpdates |
bool |
是否支持进度更新推送。若为 true，Agent 将在任务执行过程中发送 TaskEvent 类型为 progress 的更新。 |
SupportStreaming |
bool |
是否支持流式传输。若为 true，Agent 可以接收和发送 StreamChunk 格式的流数据。 |
SupportHiL |
bool |
是否支持人工介入（Human-in-the-Loop）。若为 true，Agent 可以在必要时发起 HiL 升级请求（见第 5 章）。 |
SupportGroups |
bool |
是否支持群组协作。若为 true，Agent 可以参与群组任务、投票和消息广播。 |
2.3 默认值工厂函数
func DefaultAgentCapabilities() *AgentCapabilities {
return &AgentCapabilities{
ProtocolVersion: "1.0.0",
MaxFileSize: 10 * 1024 * 1024, // 10MB
MaxConcurrentTasks: 10,
MaxTaskDuration: 3600,
SupportProgressUpdates: true,
SupportStreaming: false,
SupportHiL: false,
SupportGroups: false,
}
}
2.4 序列化示例
{
"agent_id": "agent_text_gen_01",
"agent_name": "文本生成助手",
"system_id": "system_alpha",
"protocol_version": "1.0.0",
"supported_task_types": [
{
"type": "text_generation",
"name": "文本生成",
"description": "根据输入提示生成自然语言文本",
"estimated_time": "5s-30s",
"input_schema": "...",
"output_schema": "...",
"capabilities": ["creative_writing", "summarization"]
}
],
"supported_content_types": [
"text/plain",
"text/markdown",
"application/json"
],
"supported_transport_modes": [
"callback",
"polling",
"sync"
],
"max_file_size": 10485760,
"max_concurrent_tasks": 10,
"max_task_duration_seconds": 3600,
"support_progress_updates": true,
"support_streaming": false,
"support_hil": true,
"support_groups": false
}
3. SupportedTaskType 结构
SupportedTaskType 描述 Agent 支持的单一任务类型的详细信息，包括类型标识、名称、描述、预估耗时、输入输出 Schema 以及关联能力标签。
3.1 结构定义
type SupportedTaskType struct {
Type string `json:"type"`
Name string `json:"name"`
Description string `json:"description"`
EstimatedTime string `json:"estimated_time"` // 如 "30s-2min"
InputSchema string `json:"input_schema,omitempty"`
OutputSchema string `json:"output_schema,omitempty"`
Capabilities []string `json:"capabilities,omitempty"`
}
3.2 字段说明
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
Type |
string |
是 | 任务类型标识符。采用蛇形命名法（snake_case），如 text_generation、image_analysis、code_review。该标识在协议消息的 TaskType 字段中使用。 |
Name |
string |
是 | 任务类型的人类可读名称，如"文本生成"、"图片分析"、"代码审查"。用于界面展示。 |
Description |
string |
是 | 任务类型的详细描述，说明该任务的输入、输出和适用场景。 |
EstimatedTime |
string |
是 | 预估完成时间范围。格式为字符串，如 "5s-30s"、"30s-2min"、"1min-5min"。用于任务调度和超时设置参考。 |
InputSchema |
string |
否 | 输入数据的 JSON Schema。用于验证任务提交时的 payload 格式。格式为 JSON Schema Draft-07 字符串。 |
OutputSchema |
string |
否 | 输出数据的 JSON Schema。用于解析任务结果时的格式校验。 |
Capabilities |
[]string |
否 | 该任务类型所依赖的细粒度能力标签列表。用于按能力搜索 Agent。 |
3.3 预定义任务类型
| 类型标识 | 名称 | 说明 |
|---|---|---|
text_generation |
文本生成 | 根据提示生成自然语言文本 |
text_analysis |
文本分析 | 对文本进行分类、情感分析、实体识别等 |
summarization |
摘要生成 | 将长文本总结为简短摘要 |
translation |
翻译 | 在不同语言之间进行翻译 |
code_generation |
代码生成 | 根据需求生成源代码 |
code_review |
代码审查 | 对代码进行审查、发现潜在问题 |
image_generation |
图片生成 | 根据文本描述生成图片 |
image_analysis |
图片分析 | 对图片进行内容识别和分析 |
audio_transcription |
语音转文字 | 将音频转换为文本 |
audio_generation |
语音合成 | 将文本合成为语音 |
video_generation |
视频生成 | 根据描述生成视频内容 |
data_analysis |
数据分析 | 对结构化数据进行分析和可视化 |
search_retrieval |
搜索检索 | 从知识库或互联网检索信息 |
planning |
任务规划 | 将复杂任务分解为可执行的子任务 |
reasoning |
逻辑推理 | 执行多步逻辑推理和决策 |
3.4 示例
textGenTaskType := &SupportedTaskType{
Type: "text_generation",
Name: "文本生成",
Description: "根据输入提示生成自然语言文本，支持创意写作、商业文案、技术文档等",
EstimatedTime: "5s-30s",
InputSchema: `{
"type": "object",
"properties": {
"prompt": {"type": "string", "description": "输入提示"},
"max_tokens": {"type": "integer", "minimum": 1, "maximum": 4096},
"temperature": {"type": "number", "minimum": 0, "maximum": 2}
},
"required": ["prompt"]
}`,
OutputSchema: `{
"type": "object",
"properties": {
"text": {"type": "string", "description": "生成的文本"},
"tokens_used": {"type": "integer", "description": "使用的 token 数量"}
},
"required": ["text"]
}`,
Capabilities: []string{"creative_writing", "summarization", "paraphrasing"},
}
4. 接口分类
系统中的标准接口按照功能领域划分为七大分类。每个分类代表协议栈中的一个特定功能维度。
4.1 分类枚举
type InterfaceCategory string
const (
CategoryCore InterfaceCategory = "core" // 核心接口
CategoryP2P InterfaceCategory = "p2p" // P2P 接口
CategoryGroup InterfaceCategory = "group" // 群组接口
CategoryHiL InterfaceCategory = "hil" // HiL 接口
CategoryTransport InterfaceCategory = "transport" // 传输接口
CategorySecurity InterfaceCategory = "security" // 安全接口
CategoryManagement InterfaceCategory = "management" // 管理接口
)
4.2 分类详解
| 分类 | 枚举值 | 定位 | 职责范围 | 典型接口 |
|---|---|---|---|---|
| 核心接口 | core |
协议基石 | Agent 身份标识、消息收发、能力声明等所有 Agent 最基本的生存能力 | AgentIdentity、MessageHandler、CapabilitiesProvider |
| P2P 接口 | p2p |
点对点协作 | Agent 之间的任务提交、处理、回调与状态查询 | P2PTaskHandler、CallbackSender、CallbackReceiver、TaskStatusProvider |
| 群组接口 | group |
群组协同 | 多 Agent 组成群组后的任务分发、投票决策与管理 | GroupTaskHandler、GroupManager、VotingHandler |
| HiL 接口 | hil |
人工介入 | 将决策升级到人类用户，处理人工审批、驳回与修改 | HILHandler、EscalationHandler |
| 传输接口 | transport |
数据传输 | 定义 Agent 间数据传输的网络协议和模式 | HTTPTransport、MultipartTransport、HybridTransport、StreamingTransport |
| 安全接口 | security |
安全保障 | 身份认证、消息签名、幂等性保障 | Authenticator、IdempotencyHandler |
| 管理接口 | management |
运维管理 | Agent 配置、健康监控、日志查询 | ConfigProvider、HealthReporter、MetricCollector |
4.3 分类依赖关系
core ──→ 所有分类的前置依赖，任何 Agent 必须实现
│
├──→ security ──→ transport ──→ p2p ──→ group
│ │
│ └──→ hil
│
└──→ management（可选，与所有分类正交）
core是基础层，所有其他分类都依赖core接口。security在transport之上提供安全层。p2p依赖transport和security。group和hil在p2p基础上构建更高级的交互模式。management与所有分类正交，提供运维支持。
5. 合规级别
每个标准接口定义了一个合规级别，用于标识该接口在协议实现中的重要性等级。
5.1 级别枚举
const (
ComplianceBasic Compliance = "basic" // 基本级 - 必须实现
ComplianceComplete Compliance = "complete" // 完整级 - 推荐实现
ComplianceAdvanced Compliance = "advanced" // 进阶级 - 可选实现
)
5.2 级别说明
| 级别 | 约束 | 说明 |
|---|---|---|
| basic（基本级） | 必须实现 | 所有 Agent 都必须实现此接口，否则无法完成基本的协议握手与通信。这是协议兼容性的最低门槛。未实现 basic 级别接口的 Agent 将被注册中心拒绝注册。 |
| complete（完整级） | 推荐实现 | 建议 Agent 实现此接口以获得完整的协议功能体验。未实现时，Agent 仍然可以正常工作，但部分高级交互模式（如异步回调、进度更新）将不可用。 |
| advanced（进阶级） | 可选实现 | Agent 可根据自身场景和能力选择实现。这些接口通常对应特定场景的高级功能（如流式传输、群组协作）。未实现不影响基本通信能力。 |
5.3 合规矩阵
| 场景 | Basic 接口 | Complete 接口 | Advanced 接口 |
|---|---|---|---|
| 最小可行 Agent | 全部实现 | 可不实现 | 可不实现 |
| 标准 P2P Agent | 全部实现 | 推荐全部实现 | 按需实现 |
| 群组协作 Agent | 全部实现 | 全部实现 | 推荐全部实现 |
| 全功能 Agent | 全部实现 | 全部实现 | 全部实现 |
5.4 合规级别声明
Agent 通过 GetSupportedInterfaces() 方法声明其实现的接口及对应的合规级别。注册中心可以根据这些信息对 Agent 进行合规性评估：
type ComplianceEvaluation struct {
AgentID string `json:"agent_id"`
BasicImplemented int `json:"basic_implemented"` // 已实现的 basic 接口数
BasicRequired int `json:"basic_required"` // 需要实现的 basic 接口数
CompleteImplemented int `json:"complete_implemented"` // 已实现的 complete 接口数
CompleteTotal int `json:"complete_total"` // complete 接口总数
AdvancedImplemented int `json:"advanced_implemented"` // 已实现的 advanced 接口数
AdvancedTotal int `json:"advanced_total"` // advanced 接口总数
Compliant bool `json:"compliant"` // 是否合规（所有 basic 接口均已实现）
MissingBasics []string `json:"missing_basics,omitempty"` // 缺失的 basic 接口列表
}
6. 标准接口注册表
系统预定义了 18 个标准接口，涵盖协议栈的所有功能维度。以下表格详细列出每个接口的名称、分类、合规级别和说明。
6.1 接口注册表
| 序号 | 接口名 | 分类 | 合规级别 | 说明 |
|---|---|---|---|---|
| 1 | AgentIdentity |
core |
basic | Agent 身份信息。提供 Agent 的 ID、名称、公钥等基础身份数据。是所有交互的起点，注册中心以此识别 Agent。 |
| 2 | MessageHandler |
core |
basic | 消息处理。接收并处理来自其他 Agent 或外部调用方的 UnifiedSynapseMessage 消息。Agent 之间通信的核心入口。 |
| 3 | CapabilitiesProvider |
core |
basic | 能力声明。提供 Agent 的能力描述（AgentCapabilities），供注册中心和其他 Agent 查询。 |
| 4 | P2PTaskHandler |
p2p |
basic | P2P 任务处理。接收并处理来自其他 Agent 的点对点任务请求，执行任务并返回结果。 |
| 5 | CallbackReceiver |
p2p |
basic | 回调接收端点。对外暴露回调 URL，用于接收其他 Agent 异步执行完成后的任务结果回调。 |
| 6 | CallbackSender |
p2p |
complete | 回调发送。在异步任务完成后，主动向请求方注册的回调端点发送结果。 |
| 7 | TaskStatusProvider |
p2p |
complete | 任务状态查询。提供任务执行状态的查询接口，支持按任务 ID 查询当前进度和状态。用于轮询模式。 |
| 8 | GroupTaskHandler |
group |
advanced | 群组任务处理。接收群组内分发的子任务，执行并将结果报告给群组协调者。 |
| 9 | GroupManager |
group |
advanced | 群组管理。创建、解散群组，管理成员加入/离开，维护群组角色和权限。 |
| 10 | VotingHandler |
group |
advanced | 投票处理。发起投票、提交投票、统计结果，支持多种共识类型（多数、绝对多数、一致同意、加权、排序）。 |
| 11 | HILHandler |
hil |
complete | HiL 决策处理。接收人工介入请求，将决策上下文呈现给人类用户，处理用户的批准/驳回/修改响应。 |
| 12 | EscalationHandler |
hil |
advanced | 升级处理。在 HiL 超时或 Level 1 无法解决时，自动将决策升级到更高级别（Level 2/3）。 |
| 13 | HTTPTransport |
transport |
basic | HTTP 传输。支持通过 HTTP/HTTPS 协议进行同步请求-响应通信。所有 Agent 必须支持 HTTP 作为基础传输方式。 |
| 14 | MultipartTransport |
transport |
complete | Multipart 文件传输。支持通过 multipart/form-data 进行文件上传，适用于大文件传输场景。 |
| 15 | HybridTransport |
transport |
complete | 混合传输。同时支持回调（Webhook）和轮询两种异步传输模式，以回调为主、轮询为兜底。 |
| 16 | StreamingTransport |
transport |
advanced | 流式传输。支持 Server-Sent Events（SSE）或 WebSocket 流式数据传输，适用于实时性要求高的场景。 |
| 17 | Authenticator |
security |
basic | 认证签名。提供消息签名、验签、令牌颁发与验证功能。所有消息必须经过签名认证。 |
| 18 | IdempotencyHandler |
security |
basic | 幂等性处理。通过幂等键（Idempotency-Key）确保任务提交和消息发送的幂等性，防止重复处理。 |
6.2 按合规级别汇总
| 合规级别 | 接口数量 | 接口列表 |
|---|---|---|
| basic（必须实现） | 7 | AgentIdentity、MessageHandler、CapabilitiesProvider、P2PTaskHandler、CallbackReceiver、HTTPTransport、Authenticator、IdempotencyHandler |
| complete（推荐实现） | 4 | CallbackSender、TaskStatusProvider、HILHandler、MultipartTransport、HybridTransport |
| advanced（可选实现） | 5 | GroupTaskHandler、GroupManager、VotingHandler、EscalationHandler、StreamingTransport |
注：basic 接口共 8 个，complete 共 5 个，advanced 共 5 个，总计 18 个标准接口。
6.3 按分类汇总
| 分类 | 接口数量 | 接口列表 |
|---|---|---|
| core | 3 | AgentIdentity、MessageHandler、CapabilitiesProvider |
| p2p | 4 | P2PTaskHandler、CallbackReceiver、CallbackSender、TaskStatusProvider |
| group | 3 | GroupTaskHandler、GroupManager、VotingHandler |
| hil | 2 | HILHandler、EscalationHandler |
| transport | 4 | HTTPTransport、MultipartTransport、HybridTransport、StreamingTransport |
| security | 2 | Authenticator、IdempotencyHandler |
| management | 0 | （由具体实现自行定义，协议层面不强制） |
6.4 接口注册与发现流程
请求方 Agent 注册中心 目标 Agent
│ │ │
│ 1. 注册并上报能力 │ │
│ ────────────────────────────→ │ │
│ │ 2. 存储能力信息到目录 │
│ │ ──────────────── │
│ │ │
│ 3. 按能力查询 Agent │ │
│ ────────────────────────────→ │ │
│ │ 4. 返回匹配的 Agent 列表 │
│ ←──────────────────────────── │ │
│ │ │
│ 5. P2P 握手 │ │
│ ──────────────────────────────────────────────────────────→ │
│ │ 6. 返回支持接口列表 │
│ ←────────────────────────────────────────────────────────── │
│ │ │
│ 7. 按协商接口通信 │ │
│ ──────────────────────────────────────────────────────────→ │
流程说明：
- Agent 启动时向注册中心注册，并上报
AgentCapabilities。 - 注册中心将能力信息存入全局目录，验证 basic 接口合规性。
- 请求方通过
FindByCapability查询具备特定能力的 Agent。 - 注册中心返回匹配的 Agent 端点列表。
- 请求方与目标 Agent 直接建立 P2P 连接，进行握手。
- 目标 Agent 返回
GetSupportedInterfaces()结果，协商接口兼容性。 - 双方按协商结果使用对应接口进行通信。
6.5 接口版本兼容规则
- Agent 必须实现当前协议版本所要求的所有 basic 接口。
- 接口版本遵循语义化版本规范：
- MAJOR 版本不匹配时，接口不兼容，无法通信。
- MINOR 版本不同时，以较低版本为兼容基准。
- PATCH 版本不同时，完全兼容。
- 新增接口字段必须使用
omitempty标记，确保向后兼容。
本文档基于 v0 实现细节文档第 3 章扩展编写，是灵隙协议能力声明系统的完整实现规范。 配套文档：（接口实现指南）