# 机器人能力模型 V1.0

| 项目 | 内容 |
|------|------|
| 文档编号 | DES-03 |
| 文档名称 | 机器人能力模型 |
| 版本 | V1.0 |
| 状态 | 已评审（Reviewed） |
| 适用系统 | 机器人智慧服务系统 |
| 编写日期 | 2026-08-10 |
| 关联文档 | DOC-08 设备数据字典（§5 能力编码）、DOC-09 控制命令字典 |

---

## 1. 概述

能力模型解决"平台如何知道一台设备能干什么"的问题。设备在注册时声明 `capabilities` 能力列表（见 DOC-08 §5），平台据此：
- 动态渲染控制台可下发命令（能力 → 命令映射）；
- 拒绝向不具备能力的设备下发命令（`E2002 命令不支持`）；
- 支持能力化扩展：新增设备类型只需声明新能力，无需改平台代码。

## 2. 能力分层架构

```
┌─────────────────────────────────────────────────┐
│  能力层（Capability Layer）                      │
│  移动 / 转向 / 拍照 / 视频 / 巡检 / 充电 / 急停  │
├─────────────────────────────────────────────────┤
│  命令层（Command Layer）· 命令服务 Alpha         │
│  能力 → 命令类型映射（cap.move → move 等）        │
├─────────────────────────────────────────────────┤
│  设备层（Device Layer）· 设备接入服务 Alpha      │
│  注册时声明 capabilities，运行时心跳保活          │
└─────────────────────────────────────────────────┘
```

## 3. 能力定义表（CAPABILITY）

| 能力编码 | 能力名 | 能力类型 | 对应命令（DOC-09） | 适用设备 |
|----------|--------|----------|--------------------|----------|
| `cap.move` | 移动 | 执行 | `move` / `stop` | 巡检机器人 |
| `cap.rotate` | 原地转向 | 执行 | `rotate` | 巡检机器人 |
| `cap.photo` | 拍照 | 感知 | `photo` | 巡检机器人/无人机 |
| `cap.video` | 视频回传 | 感知 | （WebRTC 通道） | 巡检机器人/无人机 |
| `cap.patrol` | 自主巡检 | 任务 | `task_start` / `task_cancel` | 巡检机器人/无人机 |
| `cap.charging` | 自动充电 | 执行 | `charge` | 巡检机器人 |
| `cap.emergency_stop` | 急停 | 安全 | `emergency_stop` | 巡检机器人/无人机 |
| `cap.thermal` | 热成像 | 感知 | `photo {camera:'thermal'}` | 巡检机器人/无人机 |

## 4. 能力属性元模型

每个能力包含如下元数据（扩展时按此注册）：

| 属性 | 类型 | 说明 |
|------|------|------|
| `code` | string | 能力编码，全局唯一 |
| `name` | string | 能力显示名 |
| `category` | enum | `execution`(执行) / `perception`(感知) / `task`(任务) / `safety`(安全) |
| `commands` | string[] | 该能力暴露的命令类型 |
| `paramsSchema` | object | 命令参数 JSON Schema（用于前端表单动态生成） |
| `required` | boolean | 设备类型是否强制具备 |

## 5. 能力-设备类型矩阵（CAP-MATRIX）

| 能力 | 巡检机器人 | 无人机 | 充电桩 | 网关 | 传感器 |
|------|:---:|:---:|:---:|:---:|:---:|
| `cap.move` | ✅ | ❌ | ❌ | ❌ | ❌ |
| `cap.rotate` | ✅ | ❌ | ❌ | ❌ | ❌ |
| `cap.photo` | ✅ | ✅ | ❌ | ❌ | ❌ |
| `cap.video` | ✅ | ✅ | ❌ | ❌ | ❌ |
| `cap.patrol` | ✅ | ✅ | ❌ | ❌ | ❌ |
| `cap.charging` | ✅ | ❌ | ❌ | ❌ | ❌ |
| `cap.emergency_stop` | ✅ | ✅ | ❌ | ❌ | ❌ |
| `cap.thermal` | ✅ | ✅ | ❌ | ❌ | ❌ |

> 充电桩/网关/传感器默认能力为空或仅含数据类能力（数据上报由状态服务承载，不属于控制命令）。

## 6. 能力校验规则（CAP-RULE）

| 规则编号 | 规则 | 说明 |
|----------|------|------|
| CAP-R1 | 设备注册时必须声明能力列表 | 缺省视为无控制能力 |
| CAP-R2 | 命令下发前校验能力 | 设备 capabilities 不含命令对应能力 → 拒绝 `E2002` |
| CAP-R3 | 能力声明可变更 | 设备重启/固件升级后可重新上报能力（更新注册信息） |
| CAP-R4 | 能力与命令 1:N | 一个能力可映射多条命令（如 `cap.move` → `move`+`stop`） |

## 7. 能力注册与发现流程

```
设备上电 → 注册（声明 capabilities）→ 设备接入服务建档
   → 控制台拉取设备详情 → 按能力渲染命令面板
   → 操作员下发命令 → 命令服务校验能力 → 通过则下发 / 拒绝 E2002
```

---

**变更记录**

| 版本 | 日期 | 变更内容 | 作者 |
|------|------|----------|------|
| V1.0 | 2026-08-10 | 初稿：能力分层/定义表/矩阵/校验规则 | 系统组 |