> ## Documentation Index
> Fetch the complete documentation index at: https://automationlaboratoryprotocol.mimedal.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 接口定义

> 设备被动接收 FSP 下发请求的事实信息与执行要求

## 接口目标

将设备的操作与数据统一封装为标准接口，使上层系统(FSP 模块或其适配器)能够稳定、便捷地控制设备并获取结果、状态或诊断。

```text theme={null}
FSP 模块下发请求
  → 设备接收上层的指令
  → 执行或创建异步任务
  → 返回实际状态、结果或诊断
```

设备底层可以使用 HTTP、RPC、SDK 或设备协议实现；本页不规定内部 URL、驱动或通信帧格式。

## 技能接口的三个维度

| 维度 | 要说明什么                               | 主要作用                         |
| -- | ----------------------------------- | ---------------------------- |
| 对象 | 容器类型、形状、直径、材质、可观察状态和实例编号            | 说明请求作用于什么对象，以及对象当前处于什么状态     |
| 控制 | 操作名称、控制参数、类型、范围、枚举、前置条件、状态变化、返回值和诊断 | 说明设备收到请求后如何校验和执行             |
| 系统 | 可用状态、运行状态字段和安全围栏                    | 判断设备当前是否允许执行，并保护设备不在不安全条件下动作 |

对象描述“操作谁”，控制描述“做什么”，系统描述“现在能不能做”。三个维度共同说明同一项设备技能，设备可以在一个既有接口中同时提供这些事实。

## 被动调用要求

设备或其适配器必须能够接收 FSP 模块已经确定的目标对象、技能参数与任务控制请求。

```text theme={null}
read 类请求 → 返回当前对象、设备或任务事实
write 类请求 → 校验并修改已声明的状态或工艺参数 → 验证写入结果
invoke 类请求 → 强制校验前置条件和围栏 → 执行或创建异步任务 → 验证物理结果
任务查询/取消请求 → 返回进度、最终结果或确认取消
```

设备返回的状态、结果和诊断必须来自实际执行或可确认的当前状态；设备不能把预期状态、缓存猜测或自然语言推断当作事实结果。FSP 对外方法、设备发现、技能披露、统一标识和版本语义见[设备发现](/specification/fsp/capabilities)。

## 内容要求

### 对象信息

对象事实必须能说明容器类型、形状、长宽高或直径、材质、标称容积、允许工作容积以及适用时的孔数和孔径；同时返回设备能够读取或改变的状态及允许值。完整目录和字段定义见[对象](/specification/fsp/objects)。

例如，`container_status: ["有盖", "无盖"]` 表示设备能区分这两种容器状态，也为操作的前置条件提供可验证的依据。

### 控制信息

每个技能接口必须有明确名称、请求分类、执行方式、参数、前置状态、状态变化、返回值和诊断。参数必须给出名称、类型、是否必填、用途，以及适用时的范围、单位、枚举值或跨字段约束。

例如，`container_count` 的类型为 `int`、范围为 `1..10`，`container_ids` 受 `max(container_ids) <= container_count` 约束；设备或适配器必须据此拒绝不符合已声明范围或跨字段约束的控制请求。

### 系统信息

系统事实必须说明该技能所需的设备状态、安全围栏和结果验证规则。设备或适配器在执行前检查安全围栏，例如“设备必须处于空闲状态”“容器必须无盖”或“参数不得超过物理上限”。任何上层说明都不能覆盖安全围栏。

## 加液接口示例

以下非规范性示例以 HTTP 表示设备的被动加液接口。接口路径只是示例；设备可以使用 RPC、SDK 或其他底层协议实现相同语义。

```text theme={null}
POST /operations/dispense
```

```json theme={null}
{
  "request_id": "req-001",
  "operation": "dispense",
  "target": {
    "container_id": "vial-01",
    "container_type": "西林瓶",
    "expected_state": {
      "container_status": "无盖"
    }
  },
  "parameters": {
    "source_container_id": "source-01",
    "volume": {
      "value": 0.5,
      "unit": "mL"
    }
  },
  "execution": {
    "mode": "async"
  }
}
```

| 部分                       | 所属维度 | 设备处理方式                                         |
| ------------------------ | ---- | ---------------------------------------------- |
| `target`                 | 对象   | 确认目标容器存在、类型匹配且处于无盖状态                           |
| `operation`、`parameters` | 控制   | 确认技能可用，校验来源容器、体积单位、范围及跨参数约束；该接口属于 `invoke` 类请求 |
| `execution` 与设备当前状态      | 系统   | 确认设备空闲、可用并通过安全围栏；长任务创建异步任务                     |

设备接收成功后返回任务标识，不将计划状态当作执行结果：

```json theme={null}
{
  "result_type": "accepted",
  "task_id": "task-001",
  "state": "queued",
  "diagnostics": []
}
```

任务完成后，设备返回实际加液结果、对象状态和诊断；若校验或执行失败，则返回失败原因，并保持未确认的对象状态不变。

## 设备侧最低要求

设备侧服务或映射层必须：

1. 为每项设备技能提供或可映射对象、控制和系统三个维度的事实；
2. 被动响应 FSP 下发的读取、写入、调用与异步任务控制；
3. 按请求分类执行不同安全约束，尤其在物理动作前强制检查对象状态、参数约束和安全围栏；
4. 同步返回实际状态变化或异步任务标识；
5. 对写入和物理动作返回可验证结果，对任务查询、完成、失败和取消返回实际进度或结构化诊断。

设备不需要原生实现发现、能力获取、统一身份或版本接口；FSP 模块负责这些对外协议职责，并将设备纳入[设备能力](/specification/capability/overview)流程。