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

Skill 是 Ooder 智能体系统中提供特定功能的原子化服务单元，通过AI Bridge 协议与智能体、路由服务、注册中心等组件实现标准化通信。本分册定义 Skill 的需求规格、接口协议、数据模型及安全交互规范，是 Skill 开发、部署、集成的核心依据。所有接口均采用RESTful 风格，请求/响应数据格式为 JSON，字符编码为 UTF-8。

wenzhangli7

610人浏览 · 2026-01-19 10:23:07

wenzhangli7 · 2026-01-19 10:23:07 发布

Skill 协议分册

适用于 Ooder 智能体系统 | 版本号：v1.0 | 更新日期：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 独立存在。

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` 权限

请求参数（必填字段加粗）：

{
  "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" // 参数说明
        }
      }
    }
  ]
}

响应参数：

{
  "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` 权限

请求参数：

{
  "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
认证	否
权限	无

返回参数：

{
  "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 格式）

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 格式）

6.2 Skill 调用流程（Mermaid 格式）

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 格式）

6.3.4 协议实现安全要求

网络隔离：MCP Agent 内部网络需与公网隔离，禁止 UDP 端口暴露在外网
签名强制：无签名或签名验证失败的消息，必须立即丢弃，并记录安全审计日志
密钥轮换：预共享密钥需每 90 天轮换一次，支持动态更新
日志审计：所有 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 错误响应格式（全局统一）

{
  "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）