
**适用于 Ooder 智能体系统** | **版本号**：v0.6 | **更新日期**：2026-01-18

## 1. 概述
Skill 是 Ooder 智能体系统中提供特定功能的**原子化服务单元**，通过 **AI Bridge 协议** 与智能体、路由服务、注册中心等组件实现标准化通信。本分册定义 Skill 的需求规格、接口协议、数据模型及安全交互规范，是 Skill 开发、部署、集成的核心依据。

### 1.1 设计目标
- **功能模块化**：将单一或关联功能封装为独立 Skill，降低耦合度
- **能力可组合**：支持 1 个 Skill 承载多个 Capability，灵活适配复杂业务场景
- **接口标准化**：统一注册、调用、监控接口，实现跨语言/跨平台兼容
- **部署灵活性**：支持容器化、裸机、Serverless 等多部署形态，适配云边端环境

## 2. Skill-Capability 关系
### 2.1 关系模型（Mermaid 格式）
Skill 与 Capability 为**一对多**关联关系，一个 Skill 可包含多个独立的 Capability，Capability 不可脱离 Skill 独立存在。
![9823dbb6-30bd-47f9-8398-f142fba975e3.png](https://developer.qcloudimg.com/http-save/yehe-10352285/b46f58f4cd2ada5c7c01286c9eb77dc6.png)

### 2.2 关系特性
- **独立性**：Capability 的参数定义、版本管理独立于其他 Capability
- **组合性**：相同/不同 Skill 的 Capability 可通过智能体编排，实现复杂任务
- **可扩展性**：支持运行时动态添加/移除 Capability，无需重启 Skill 服务
- **版本控制**：Skill 和 Capability 均遵循 **语义化版本规范（SemVer）**，支持灰度发布

## 3. Skill 需求规格
### 3.1 功能需求
| 需求编号 | 需求描述 | 优先级 | 验收标准 |
|----------|----------|--------|----------|
| SKILL-REQ-001 | Skill 应支持注册到 Ooder 系统注册中心 | 高 | 注册后 10s 内可被路由服务发现，注册信息持久化存储 |
| SKILL-REQ-002 | Skill 应支持从 Ooder 系统注销 | 高 | 注销后 5s 内停止接收新请求，注册信息从缓存/数据库中移除 |
| SKILL-REQ-003 | Skill 应支持一个 Skill 对应多个 Capability | 高 | 单个 Skill 可注册 ≥10 个 Capability，且各自独立响应调用 |
| SKILL-REQ-004 | Skill 应支持状态查询 | 高 | 可返回运行状态、负载率、Capability 可用列表等信息 |
| SKILL-REQ-005 | Skill 应支持版本管理 | 高 | 支持多版本共存，可通过版本号精准调用指定版本 Skill |

### 3.2 非功能需求
| 需求编号 | 需求描述 | 优先级 | 验收标准 |
|----------|----------|--------|----------|
| SKILL-NREQ-001 | Skill 应支持高并发请求 | 高 | 单实例稳定处理 1000 QPS 以上请求，错误率 ≤ 0.1% |
| SKILL-NREQ-002 | Skill 响应时间应小于 500ms | 高 | 95% 分位请求响应时间 < 500ms，99% 分位 < 1000ms |
| SKILL-NREQ-003 | Skill 可用性应达到 99.9% | 高 | 年度计划外停机时间 ≤ 8.76 小时，支持故障自动恢复 |
| SKILL-NREQ-004 | Skill 应向后兼容 | 高 | 新版本 Skill 可兼容旧版本的请求参数格式，无感知升级 |

## 4. Skill 接口定义
所有接口均采用 **RESTful 风格**，请求/响应数据格式为 JSON，字符编码为 UTF-8。

### 4.1 注册接口
| 接口名称 | Skill 注册 |
|----------|------------|
| URL | `/api/v1/skills/register` |
| 方法 | POST |
| 认证 | 是（基于 JWT Token） |
| 权限 | 需具备 `skill:register` 权限 |

**请求参数**（必填字段加粗）：
```json
{
  "skill_id": "string", // UUID，Skill 唯一标识
  "name": "string", // Skill 名称
  "description": "string", // 功能描述
  "version": "string", // 语义化版本号，如 v1.0.0
  "endpoints": [
    {
      "url": "string", // Skill 服务地址
      "protocol": "http|https|ws|wss", // 通信协议
      "weight": "number" // 负载均衡权重，默认 1
    }
  ],
  "capabilities": [
    {
      "capability_id": "string", // UUID，Capability 唯一标识
      "name": "string", // Capability 名称
      "description": "string", // 能力描述
      "category": "string", // 能力分类，如 NLP、CV、Tool
      "version": "string", // Capability 版本号
      "parameters": {
        "param1": {
          "type": "string|number|boolean|object|array", // 参数类型
          "required": "boolean", // 是否必填
          "description": "string" // 参数说明
        }
      }
    }
  ]
}
```

**响应参数**：
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "skill_id": "string",
    "register_time": "timestamp",
    "expire_time": "timestamp" // 注册有效期，永久有效则为 null
  }
}
```

### 4.2 命令执行接口
| 接口名称 | 命令执行 |
|----------|------------|
| URL | `/api/v1/commands/execute` |
| 方法 | POST |
| 认证 | 是 |
| 权限 | 需具备 `command:execute` 权限 |

**请求参数**：
```json
{
  "command_id": "string", // 命令唯一标识
  "skill_id": "string", // 目标 Skill ID
  "capability_id": "string", // 目标 Capability ID
  "parameters": {
    "param1": "value1",
    "param2": "value2"
  },
  "callback_url": "string", // 异步回调地址（可选）
  "timeout": "number" // 超时时间，单位 ms，默认 5000
}
```

### 4.3 健康检查接口
| 接口名称 | 健康检查 |
|----------|------------|
| URL | `/health` |
| 方法 | GET |
| 认证 | 否 |
| 权限 | 无 |

**返回参数**：
```json
{
  "status": "healthy|unhealthy|warning", // 健康状态
  "version": "string", // Skill 版本
  "uptime": "number", // 运行时长，单位 s
  "timestamp": "timestamp", // 检查时间戳
  "details": { // 扩展字段，可选
    "cpu_usage": "number", // CPU 使用率
    "memory_usage": "number", // 内存使用率
    "capability_status": { // 各 Capability 状态
      "cap-id-1": "enabled",
      "cap-id-2": "disabled"
    }
  }
}
```

## 5. Skill 数据模型
### 5.1 核心数据模型关系（Mermaid 格式）
![image.png](https://developer.qcloudimg.com/http-save/yehe-10352285/c3acfbe97e442beb1a37c2ceedfdd509.png)
### 5.2 字段约束说明
- 所有 `id` 字段均采用 **UUID v4** 生成，确保全局唯一性
- `version` 字段需遵循 `主版本号.次版本号.修订号` 格式（如 `1.2.3`）
- `created_at`/`updated_at` 字段为 **ISO 8601** 格式时间戳（如 `2026-01-18T12:00:00Z`）

## 6. Skill 协议交互流程
### 6.1 Skill 注册流程（Mermaid 格式）
![image.png](https://developer.qcloudimg.com/http-save/yehe-10352285/096a5de407bb640621045affd2629110.png)

### 6.2 Skill 调用流程（Mermaid 格式）
![image.png](https://developer.qcloudimg.com/http-save/yehe-10352285/7cd640e0c73bdde32ffe683edcb07a8f.png)

### 6.3 MCP Agent 内部 UDP 广播与服务发现流程
> **重要约束**：UDP 广播**仅限 MCP Agent 内部局域网**使用，禁止跨子网、跨公网传输；所有广播消息必须携带安全签名，防止伪造和重放攻击。

#### 6.3.1 UDP 通信技术规范
| 配置项 | 取值 | 强制约束 |
|--------|------|----------|
| UDP 端口 | 5000 | 不可修改，需在防火墙中放行 |
| 广播地址 | 255.255.255.255 | 仅限本地子网广播 |
| 缓冲区大小 | 1024 字节 | 消息长度超过则分片传输 |
| 超时时间 | 5 秒 | 超过超时未收到响应则重试 1 次 |
| 广播频率 | 30 秒 | 心跳广播间隔，可配置 |

#### 6.3.2 安全广播消息格式
- **发现请求消息**（带 HMAC-SHA256 签名）
  ```
  DISCOVER:SKILL:{agentId};{agentName};{agentType};{agentEndpoint};{timestamp};{signature}
  ```
  - `signature` 计算规则：`HMAC-SHA256(预共享密钥, 拼接字符串{agentId}{agentType}{timestamp})`

- **加入响应消息**（带 HMAC-SHA256 签名）
  ```
  JOIN_RESPONSE:SKILL:{agentId};{agentType};{sceneId};{status};{timestamp};{signature}
  ```

#### 6.3.3 安全认证流程（Mermaid 格式）
![image.png](https://developer.qcloudimg.com/http-save/yehe-10352285/a43d0f53a72b29c0d306a8c781f2ebd4.png)

#### 6.3.4 协议实现安全要求
1. **网络隔离**：MCP Agent 内部网络需与公网隔离，禁止 UDP 端口暴露在外网
2. **签名强制**：无签名或签名验证失败的消息，**必须立即丢弃**，并记录安全审计日志
3. **密钥轮换**：预共享密钥需每 90 天轮换一次，支持动态更新
4. **日志审计**：所有 UDP 通信需记录发送方 IP、消息内容、签名验证结果，日志留存 ≥ 90 天

## 7. 错误处理
### 7.1 Skill 错误码规范
| 错误码 | 描述 | HTTP 状态码 | 适用场景 |
|--------|------|------------|----------|
| 2001 | Skill 不存在 | 404 | 请求的 skill_id 未注册或已注销 |
| 2002 | Capability 不存在 | 404 | 请求的 capability_id 在 Skill 中未定义 |
| 2003 | Skill 不可用 | 503 | Skill 处于维护中或所有节点下线 |
| 2004 | Capability 不可用 | 503 | Capability 被禁用或运行异常 |
| 2005 | 参数错误 | 400 | 缺少必填参数/参数类型不匹配/参数值非法 |
| 2006 | 执行超时 | 504 | Skill 执行时间超过请求 timeout 限制 |

### 7.2 错误响应格式（全局统一）
```json
{
  "code": "2001", // 错误码
  "message": "Skill not found", // 错误描述（支持多语言）
  "details": { // 错误详情（可选）
    "skill_id": "skill-123",
    "trace_id": "string" // 链路追踪 ID，用于问题排查
  },
  "timestamp": "2026-01-18T00:00:00Z" // 错误发生时间
}
```

## 8. 部署与运行
### 8.1 部署方式对比
| 部署方式 | 核心特点 | 适用场景 | 部署建议 |
|----------|----------|----------|----------|
| 容器化部署（Docker/K8s） | 环境隔离、弹性伸缩、一键部署 | 云平台、微服务集群、规模化部署 | 推荐生产环境使用，通过 K8s 实现自动扩缩容 |
| 裸机部署 | 性能损耗低、资源利用率高 | 专用服务器、边缘计算节点、低延迟场景 | 适合对性能要求极高的 Skill 服务 |
| Serverless 部署（函数计算） | 按需计费、免运维、自动扩缩容 | 流量波动大、调用频率低的长尾 Skill | 适合非核心、低优先级的 Skill 功能 |

### 8.2 运行环境最低要求
| 运行环境 | 版本要求 | 备注 |
|----------|----------|------|
| Python | 3.9+ | 适用于 Python 开发的 Skill |
| Go | 1.18+ | 适用于 Go 开发的 Skill，推荐高并发场景 |
| Node.js | 16+ | 适用于前端一体化 Skill 开发 |
| Java | 11+ | 适用于企业级复杂业务 Skill |
| 内存 | 1GB+ | 建议根据并发量调整，高并发场景 ≥ 4GB |
| CPU | 1核+ | 建议 2 核及以上，支持多线程处理 |

## 9. 监控与维护
### 9.1 核心监控指标（需接入 Ooder 监控平台）
| 指标分类 | 具体指标 | 监控阈值 | 告警策略 |
|----------|----------|----------|----------|
| 业务指标 | QPS、请求成功率、响应时间 | 响应时间 > 500ms 持续 1min | 触发一级告警 |
| 资源指标 | CPU 使用率、内存使用率、磁盘使用率 | CPU 使用率 > 80% 持续 5min | 触发二级告警 |
| 可用性指标 | 服务在线率、健康检查通过率 | 健康检查失败率 > 10% | 触发三级告警 |

### 9.2 日志管理规范
| 日志类型 | 记录内容 | 存储周期 | 存储介质 |
|----------|----------|----------|----------|
| 访问日志 | 请求 URL、请求参数、响应状态、耗时 | 7 天 | 日志文件/ELK |
| 错误日志 | 错误码、错误堆栈、请求上下文、trace_id | 30 天 | 日志文件/ELK |
| 审计日志 | 注册/注销、权限变更、配置修改等关键操作 | 90 天 | 数据库（不可篡改） |
| 性能日志 | 接口耗时、资源使用率、并发数 | 14 天 | 时序数据库（如 Prometheus） |

## 10. 兼容性
### 10.1 向后兼容（强制要求）
- 新版本 Skill 必须兼容旧版本的 **API 接口**和**数据格式**
- 新增参数必须为**可选参数**，不得影响旧请求的正常执行
- 错误码定义不得修改，新增错误码需在 2000 以后扩展

### 10.2 向前兼容（推荐实践）
- 支持**渐进式功能灰度**，通过配置开关控制新功能是否启用
- 客户端可通过 `Accept-Version` 请求头指定 Skill 版本，实现多版本共存
- 数据模型新增字段时，需提供默认值，确保旧客户端能正常解析

---

## 文档使用说明
1. 本协议分册为 OoderAI Skill 开发的**强制标准**，所有 Skill 需遵循本规范
2. 协议变更需通过 Ooder 技术委员会评审，变更后会同步更新版本号
3. 配套资源：Skill 开发 SDK、Demo 工程、接口测试工具可从 Ooder 开发者平台获取

---


适用于 Ooder 智能体系统 | 版本号：v0.6 | 更新日期：2026-01-18

ooderAI A2A协议 Skill 协议分册V.06（精读）

Skill 是 Ooder 智能体系统中提供特定功能的**原子化服务单元**，通过 **AI Bridge 协议** 与智能体、路由服务、注册中心等组件实现标准化通信。本分册定义 Skill 的需求规格、接口协议、数据模型及安全交互规范，是 Skill 开发、部署、集成的核心依据。

架构师

人工智能

Ooder智能体系统Skill规范v0.6版本详解，定义原子化服务单元的功能规格、接口协议及安全交互标准。支持多Capability组合、高并发处理、99.9%可用性，提供RESTful标准化接口，兼容容器化/裸机/Serverless部署。规范涵盖注册发现、命令执行、健康检查等核心流程，确保跨平台兼容与安全通信。

弹性伸缩

安全审计

日志文件

负载均衡

防火墙

服务器

智能体

数据库

路由

容器

Python

JSON

2026采购季 | AI焕新·智启新局

tencentdb-catalog

serverless-catalog

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

ooderAI A2A协议 Skill 协议分册V.06（精读）-腾讯云开发者社区-腾讯云

ooderAI A2A协议 Skill 协议分册V.06（精读）

ooderAI A2A协议 Skill 协议分册V.06（精读）

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐