适用于 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 独立存在。
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） |
10. 兼容性
10.1 向后兼容（强制要求）
- 新版本 Skill 必须兼容旧版本的 API 接口和数据格式
- 新增参数必须为可选参数，不得影响旧请求的正常执行
- 错误码定义不得修改，新增错误码需在 2000 以后扩展
10.2 向前兼容（推荐实践）
- 支持渐进式功能灰度，通过配置开关控制新功能是否启用
- 客户端可通过
Accept-Version请求头指定 Skill 版本，实现多版本共存 - 数据模型新增字段时，需提供默认值，确保旧客户端能正常解析
文档使用说明
- 本协议分册为 OoderAI Skill 开发的强制标准，所有 Skill 需遵循本规范
- 协议变更需通过 Ooder 技术委员会评审，变更后会同步更新版本号
- 配套资源：Skill 开发 SDK、Demo 工程、接口测试工具可从 Ooder 开发者平台获取
