智能场景API

# 百度小度语音场景协议

## 1. 概述

本文定义百度小度与摩根系统之间的语音场景协议，覆盖场景的新建、编辑、删除、列表查询和详情查询。场景执行沿用现有 `DuerOS.ConnectedHome.Scene` 场景控制消息，不在本文范围内。

| 项目 | 约定 |
| --- | --- |
| 通信方式 | 与现有设备控制复用同一 HTTP 接口：POST，`application/json; charset=utf-8`，UTF-8 |
| 消息区分 | `header.namespace` 固定为 `DuerOS.ConnectedHome.Scene`，通过 `header.name` 区分消息类型 |
| 鉴权 | 复用现有设备控制接口的鉴权方式，并在 `payload.accessToken` 中传入访问令牌 |

### 1.1 消息总览

| 能力 | 请求名称 | 成功响应名称 |
| --- | --- | --- |
| 场景新建 | `CreateSceneRequest` | `CreateSceneResponse` |
| 场景编辑 | `UpdateSceneRequest` | `UpdateSceneResponse` |
| 场景删除 | `DeleteSceneRequest` | `DeleteSceneResponse` |
| 场景列表查询 | `ListScenesRequest` | `ListScenesResponse` |
| 场景详情查询 | `GetSceneRequest` | `GetSceneResponse` |
| 失败响应（各消息通用） | — | `ErrorResponse` |

## 2. 通用报文结构

协议沿用现有小度设备控制的 `header` / `payload` 结构，本文各消息仅描述差异部分。

### 2.1 Header（所有消息相同）

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `header.namespace` | string | 是 | 固定为 `DuerOS.ConnectedHome.Scene` |
| `header.name` | string | 是 | 消息名称，见 1.1 |
| `header.messageId` | string | 是 | 本次消息的唯一标识，响应原样回显 |
| `header.payloadVersion` | string | 是 | 协议版本，当前固定为 `1` |

### 2.2 Payload 公共字段

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `payload.accessToken` | string | 是 | 小度访问令牌，格式参考 `{{access_token}}` |
| `payload.requestId` | string | 是 | 请求唯一标识；创建时兼作幂等标识，同一次请求重试时保持不变 |

### 2.3 设备动作结构

`actions[]` 中每个元素代表一条设备控制动作，直接复用现有小度设备控制协议的命令名称、`appliance` 对象和控制参数。每条动作只对应一个设备，必须独立携带完整 `appliance`。

示例——等待 500 毫秒后将空调风速增加 1 档：

```json
{
  "delay": 5,
  "name": "IncrementFanSpeedRequest",
  "appliance": {
    "additionalApplianceDetails": {
      "bdType": "AIR_CONDITION",
      "type": 87,
      "version": 107,
      "roomId": "3"
    },
    "applianceId": "0121363ffffffff1-e403ffffffff00ff"
  },
  "deltaValue": { "value": 1 }
}
```

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `actions[].delay` | integer | 是 | 执行当前动作前的等待量，单位固定 100 毫秒；首条动作相对场景启动计时，后续动作相对上一动作 |
| `actions[].name` | string | 是 | 现有设备控制命令名称，如 `TurnOnRequest`、`TurnOffRequest`、`IncrementFanSpeedRequest` |
| `actions[].appliance.additionalApplianceDetails` | object | 是 | 设备附加信息，直接使用设备发现或设备控制返回的数据，不得自行推测 |
| `actions[].appliance.applianceId` | string | 是 | 目标设备 ID（单个，不使用数组） |
| `actions[].<控制参数>` | object | 按命令 | 控制参数，与现有设备控制 `payload` 同名、同结构，如示例中的 `deltaValue` |

### 2.4 响应结构

**成功响应**：`header.name` 为对应消息的 `XxxResponse`（见 1.1），`messageId`、`payloadVersion` 原样回显；`payload` 统一为：

```json
{
  "code": 0,
  "message": "success",
  "requestId": "回显请求 requestId",
  "data": { }
}
```

`data` 结构见各消息章节。

**失败响应**：`header.name` 为 `ErrorResponse`，各消息格式相同：

```json
{
  "header": {
    "namespace": "DuerOS.ConnectedHome.Scene",
    "name": "ErrorResponse",
    "messageId": "6d6d6e14-8aee-473e-8c24-0d31ff9c17a2",
    "payloadVersion": "1"
  },
  "payload": {
    "code": 40012,
    "errorCode": "INVALID_DEVICE_ACTION",
    "message": "unsupported device action",
    "requestId": "scene-create-20260828-0001"
  }
}
```

错误码见第 8 节。

## 3. 场景新建 CreateSceneRequest

在指定区域创建场景。完整请求示例——在“客厅”创建“回家模式”：场景启动 200 毫秒后打开空调，再等 500 毫秒风速加 1 档（两个动作指向同一设备，每条仍需独立携带完整 `appliance`）：

```json
{
  "header": {
    "namespace": "DuerOS.ConnectedHome.Scene",
    "name": "CreateSceneRequest",
    "messageId": "6d6d6e14-8aee-473e-8c24-0d31ff9c17a2",
    "payloadVersion": "1"
  },
  "payload": {
    "accessToken": "{{access_token}}",
    "requestId": "scene-create-20260828-0001",
    "sceneName": "回家模式",
    "areaName": "客厅",
    "actions": [
      {
        "delay": 2,
        "name": "TurnOnRequest",
        "appliance": {
          "additionalApplianceDetails": {
            "bdType": "AIR_CONDITION",
            "type": 87,
            "version": 107,
            "roomId": "3"
          },
          "applianceId": "0121363ffffffff1-e403ffffffff00ff"
        }
      },
      {
        "delay": 5,
        "name": "IncrementFanSpeedRequest",
        "appliance": {
          "additionalApplianceDetails": {
            "bdType": "AIR_CONDITION",
            "type": 87,
            "version": 107,
            "roomId": "3"
          },
          "applianceId": "0121363ffffffff1-e403ffffffff00ff"
        },
        "deltaValue": { "value": 1 }
      }
    ]
  }
}
```

### 3.1 请求 payload 差异字段

除 2.2 公共字段外：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `payload.sceneName` | string | 是 | 场景名称，去除首尾空格后不能为空 |
| `payload.areaName` | string | 是 | 场景所属区域名称，是场景自身的属性 |
| `payload.actions` | array | 是 | 有序设备动作列表，至少一个动作，结构见 2.3 |

### 3.2 成功响应 data（场景信息）

```json
{
  "sceneId": "SCENE_20260828_0001",
  "sceneName": "回家模式",
  "areaName": "客厅",
  "actionCount": 2,
  "status": "CREATED"
}
```

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `sceneId` | string | 场景 ID，后续编辑、删除、详情查询的标识 |
| `sceneName` | string | 场景名称 |
| `areaName` | string | 所属区域名称 |
| `actionCount` | integer | 场景包含的设备动作数量 |
| `status` | string | 新建成功固定为 `CREATED` |

## 4. 场景编辑 UpdateSceneRequest

部分更新：`sceneName`、`areaName`、`actions` 至少传一项，未传字段保持不变；`actions` 传入时全量替换原有动作列表。header 同 2.1，请求 payload 示例：

```json
{
  "accessToken": "{{access_token}}",
  "requestId": "scene-update-20260829-0001",
  "sceneId": "SCENE_20260828_0001",
  "sceneName": "回家模式",
  "actions": [
    {
      "delay": 2,
      "name": "TurnOnRequest",
      "appliance": {
        "additionalApplianceDetails": { "bdType": "AIR_CONDITION", "type": 87, "version": 107, "roomId": "3" },
        "applianceId": "0121363ffffffff1-e403ffffffff00ff"
      }
    }
  ]
}
```

### 4.1 请求 payload 差异字段

除 2.2 公共字段外：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `payload.sceneId` | string | 是 | 待编辑场景 ID |
| `payload.sceneName` | string | 否 | 新场景名称；传入时校验规则同新建 |
| `payload.areaName` | string | 否 | 新区域名称；传入时校验规则同新建 |
| `payload.actions` | array | 否 | 新动作列表；传入时全量替换，校验规则同新建 |

### 4.2 成功响应 data

同 3.2 场景信息，`status` 固定为 `UPDATED`。

## 5. 场景删除 DeleteSceneRequest

删除后 `sceneId` 立即失效，重复删除返回 `SCENE_NOT_FOUND`。header 同 2.1，请求 payload 示例：

```json
{
  "accessToken": "{{access_token}}",
  "requestId": "scene-delete-20260829-0001",
  "sceneId": "SCENE_20260828_0001"
}
```

### 5.1 请求 payload 差异字段

除 2.2 公共字段外：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `payload.sceneId` | string | 是 | 待删除场景 ID |

### 5.2 成功响应 data

```json
{
  "sceneId": "SCENE_20260828_0001",
  "status": "DELETED"
}
```

## 6. 场景列表查询 ListScenesRequest

查询当前 accessToken 作用域（主机）下的全部语音场景。header 同 2.1，请求 payload 示例：

```json
{
  "accessToken": "{{access_token}}",
  "requestId": "scene-list-20260829-0001",
  "areaName": "客厅"
}
```

### 6.1 请求 payload 差异字段

除 2.2 公共字段外：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `payload.areaName` | string | 否 | 区域过滤条件，传入时只返回该区域下的场景 |

### 6.2 成功响应 data

```json
{
  "total": 2,
  "scenes": [
    {
      "sceneId": "SCENE_20260828_0001",
      "sceneName": "回家模式",
      "areaName": "客厅",
      "actionCount": 2,
      "status": "CREATED",
      "createTime": "2026-08-28 10:00:00"
    },
    {
      "sceneId": "SCENE_20260829_0002",
      "sceneName": "睡眠模式",
      "areaName": "卧室",
      "actionCount": 3,
      "status": "CREATED",
      "createTime": "2026-08-29 22:30:00"
    }
  ]
}
```

`scenes[]` 条目为 3.2 场景信息加 `createTime`（`yyyy-MM-dd HH:mm:ss`），`status` 固定为 `CREATED`。按创建时间升序返回；无场景时 `total` 为 `0`、`scenes` 为空数组，仍返回成功。

## 7. 场景详情查询 GetSceneRequest

查询单个场景的定义，含完整有序动作列表。请求 payload 同第 5 节删除（`sceneId` 定位场景）。

### 7.1 成功响应 data

```json
{
  "sceneId": "SCENE_20260828_0001",
  "sceneName": "回家模式",
  "areaName": "客厅",
  "actionCount": 2,
  "status": "CREATED",
  "createTime": "2026-08-28 10:00:00",
  "updateTime": "2026-08-29 09:00:00",
  "actions": [
    {
      "delay": 2,
      "name": "TurnOnRequest",
      "appliance": {
        "additionalApplianceDetails": { "bdType": "AIR_CONDITION", "type": 87, "version": 107, "roomId": "3" },
        "applianceId": "0121363ffffffff1-e403ffffffff00ff"
      }
    },
    {
      "delay": 5,
      "name": "IncrementFanSpeedRequest",
      "appliance": {
        "additionalApplianceDetails": { "bdType": "AIR_CONDITION", "type": 87, "version": 107, "roomId": "3" },
        "applianceId": "0121363ffffffff1-e403ffffffff00ff"
      },
      "deltaValue": { "value": 1 }
    }
  ]
}
```

为 3.2 场景信息加 `createTime`、`updateTime`（格式 `yyyy-MM-dd HH:mm:ss`）和 `actions[]`。`actions[]` 结构与 2.3 完全一致，按保存顺序（`actionOrder` 与数组顺序一致）原样回显创建/编辑时保存的 `delay`、`name`、`appliance` 与控制参数。

## 8. 错误码

| code | errorCode | 含义 |
| --- | --- | --- |
| `40001` | `REQUIRED_FIELD_MISSING` | 必填字段缺失（如 `sceneName`、`areaName`、`actions`、`sceneId`） |
| `40011` | `INVALID_SCENE_NAME` | 场景名称为空或格式不合法 |
| `40012` | `INVALID_DEVICE_ACTION` | 设备命令、目标设备或控制参数无效 |
| `40013` | `DEVICE_NOT_FOUND_OR_DENIED` | 设备不存在或当前用户无控制权限 |
| `40014` | `INVALID_ACTION_DELAY` | 动作延时不是非负整数或超出系统限制 |
| `40015` | `INVALID_SCENE_AREA` | 场景区域不存在或调用方无区域权限 |
| `40401` | `SCENE_NOT_FOUND` | 场景不存在或当前用户无权限 |
| `40901` | `SCENE_NAME_CONFLICT` | 相同作用域内已存在同名场景 |
| `40902` | `IDEMPOTENCY_CONFLICT` | 相同 `requestId` 对应的请求内容不同 |
| `50000` | `INTERNAL_ERROR` | 服务内部异常 |

## 9. 处理规则

### 9.1 通用

1. `accessToken` 确定操作作用域（主机）。访问非当前作用域的场景（编辑、删除、详情）统一返回 `SCENE_NOT_FOUND`，不得泄露场景存在性。
2. 服务端必须校验目标设备是否存在、调用方是否具有设备控制权限，以及区域名称是否有效、调用方是否有区域权限。
3. 写操作（新建、编辑）必须具备原子性：全部动作校验并保存成功后才返回成功，任一动作失败不得保留部分场景数据。

### 9.2 新建

1. `actions` 按数组顺序保存，后续执行场景时必须保持相同顺序。
2. `delay` 实际等待时间为 `delay × 100` 毫秒，所有动作（包括首条）均可设置延时。首条 `delay=2` 表示场景启动 200 毫秒后执行；后续 `delay=5` 表示上一动作执行后再等 500 毫秒。
3. 每条动作只允许对应一个设备，必须独立携带完整 `appliance`，且 `applianceId` 必须为字符串。
4. 同一区域内的同名场景不得静默覆盖，应返回 `SCENE_NAME_CONFLICT`。
5. 幂等：相同 `requestId` 且请求内容相同重复提交时，返回第一次创建的结果，不得重复创建；内容不同返回 `IDEMPOTENCY_CONFLICT`。
6. 创建成功只保存场景定义，不立即执行其中的设备动作。

### 9.3 编辑

1. `actions` 传入时必须整体替换，不支持增量修改。
2. 重名校验不含自身：修改后的名称/区域不得与同区域内其他场景重名。
3. 编辑只更新场景定义，不影响已保存场景的执行。

### 9.4 删除与查询

1. 删除同时移除场景定义与动作明细，删除后 `sceneId` 立即失效。
2. 列表按创建时间升序返回；空结果仍返回成功。

## 10. 版本记录

| 版本 | 日期 | 说明 |
| --- | --- | --- |
| V1.0 | 2026-08-28 | 首次定义小度场景新建协议 |
| V1.1 | 2026-10-09 | 新增场景编辑、删除、列表查询、详情查询协议 |