# 灵隙协议实现规范：能力声明系统

> 版本：1.0.0 | 层级：实现层

---

## 目录

1. [核心接口 CapabilitiesProvider](#1-核心接口-capabilitiesprovider)
2. [能力描述结构 AgentCapabilities](#2-能力描述结构-agentcapabilities)
3. [SupportedTaskType 结构](#3-supportedtasktype-结构)
4. [接口分类](#4-接口分类)
5. [合规级别](#5-合规级别)
6. [标准接口注册表](#6-标准接口注册表)

---

## 1. 核心接口 CapabilitiesProvider

每个 Agent 必须实现 `CapabilitiesProvider` 接口，以便其他 Agent 查询其能力。该接口是所有能力声明系统的入口点，定义了三个核心方法：

### 1.1 接口定义

```go
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 结构

```go
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 完整结构定义

```go
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 枚举

```go
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 默认值工厂函数

```go
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 序列化示例

```json
{
    "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 结构定义

```go
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 示例

```go
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 分类枚举

```go
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 级别枚举

```go
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 进行合规性评估：

```go
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. 按协商接口通信         │                              │
    │ ──────────────────────────────────────────────────────────→ │
```

**流程说明**：

1. Agent 启动时向注册中心注册，并上报 `AgentCapabilities`。
2. 注册中心将能力信息存入全局目录，验证 basic 接口合规性。
3. 请求方通过 `FindByCapability` 查询具备特定能力的 Agent。
4. 注册中心返回匹配的 Agent 端点列表。
5. 请求方与目标 Agent 直接建立 P2P 连接，进行握手。
6. 目标 Agent 返回 `GetSupportedInterfaces()` 结果，协商接口兼容性。
7. 双方按协商结果使用对应接口进行通信。

### 6.5 接口版本兼容规则

- Agent 必须实现当前协议版本所要求的所有 basic 接口。
- 接口版本遵循语义化版本规范：
  - **MAJOR** 版本不匹配时，接口不兼容，无法通信。
  - **MINOR** 版本不同时，以较低版本为兼容基准。
  - **PATCH** 版本不同时，完全兼容。
- 新增接口字段必须使用 `omitempty` 标记，确保向后兼容。

---

> 本文档基于 v0 实现细节文档第 3 章扩展编写，是灵隙协议能力声明系统的完整实现规范。
> 配套文档：（接口实现指南）