> ## 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.

# 操作

> 说明设备能力名称、参数、执行结果应怎样写。

操作维度说明设备能够执行什么操作、调用时需要提供什么参数，以及设备如何报告执行结果。它描述的是同一设备接口中的操作信息，不要求设备为操作维度单独建立接口。

## 操作说明字段

每项设备操作都应提供以下说明：

| 字段                      | 含义                 | 可以填写的内容与示例                                                                          |
| ----------------------- | ------------------ | ----------------------------------------------------------------------------------- |
| `operation_id`          | 在当前设备定义中稳定标识一项操作   | 可填 `add_liquid`、`set_temperature`、`start_stirring`、`measure_absorbance`；版本升级时不应随意改名 |
| `name`                  | 面向使用者的简短名称         | 可填“加液”“设定温度”“开始搅拌”“测量吸光度”                                                           |
| `description`           | 说明操作对象、动作和预期结果     | 例如“向指定离心管加入给定体积的液体，并返回实际加液结果”                                                       |
| `parameters`            | 操作接受的参数定义集合        | 例如加液量、来源容器、目标温度、转速、持续时间、测量波长；无参数操作可为空集合                                             |
| `preconditions`         | 操作逻辑自身必须满足的前置条件    | 例如“加液量位于声明范围”“目标温度不得低于环境露点”“转速与容器类型兼容”                                              |
| `effects`               | 操作成功后预期发生的变化       | 例如“目标容器样品体积增加”“设备设定温度更新”“搅拌状态变为运行中”                                                 |
| `completion_conditions` | 判定操作完成的条件          | 例如“实际加液量完成并通过核验”“温度进入允许偏差范围并保持 30 秒”                                                |
| `result_fields`         | 成功、失败或未知结果时需要返回的字段 | 例如实际体积、实际温度、测量值、持续时间、完成时间和结果质量标记                                                    |
| `diagnostic_codes`      | 该操作可能产生的结构化诊断      | 例如参数越界、液量不足、目标未定位、执行超时、结果无法确认                                                       |

## 参数字段

`parameters` 中的每个参数应分别说明：

| 字段                                      | 含义            | 可以填写的内容与示例                                                           |
| --------------------------------------- | ------------- | -------------------------------------------------------------------- |
| `name`                                  | 参数的稳定名称       | `volume_mL`、`temperature_c`、`speed_rpm`、`duration_s`、`wavelength_nm` |
| `type`                                  | 参数的数据类型       | `string`、`number`、`integer`、`boolean`、`array`、`object`               |
| `description`                           | 参数的物理含义与使用方式  | 例如“单次加入目标容器的液体体积”                                                    |
| `unit`                                  | 参数使用的标准单位     | `mL`、`μL`、`°C`、`rpm`、`s`、`nm`；无量纲参数可不填                               |
| `minimum`、`maximum`                     | 单个参数允许的闭区间    | 加液量可填最小 `0.05 mL`、最大 `0.8 mL`；温度可填 `20–120 °C`                       |
| `exclusive_minimum`、`exclusive_maximum` | 不允许等于边界时使用的范围 | 例如压力必须大于 `0 MPa`，但不得等于零                                              |
| `enum`                                  | 参数允许选择的有限值    | 搅拌方向可填 `clockwise`、`counterclockwise`；工作模式可填设备声明的模式集合                |
| `pattern`                               | 字符串格式约束       | 孔位可使用类似 `A1`、`H12` 的格式规则；容器标识可限制字符集合和长度                              |
| `default`                               | 未提供参数时采用的值    | 例如默认持续时间 `60 s`；不宜设置会掩盖错误的默认值                                        |
| `precision`                             | 允许的小数位数或分辨率   | 体积可精确到 `0.001 mL`，温度可精确到 `0.1 °C`                                    |
| `items`                                 | 数组元素的类型和约束    | 批量孔位可规定每项为孔位字符串，且数量不得超过设备批处理上限                                       |

参数约束既用于编译和仿真，也必须在设备动作前再次校验。参数之间存在关系时，还应说明跨字段约束，例如“总加液量不得超过目标容器剩余容量”“转速越高时允许的最大持续时间越短”。

## 调用时的操作字段

| 字段                 | 含义                  | 可以填写的内容与示例                                   |
| ------------------ | ------------------- | -------------------------------------------- |
| `operation_id`     | 本次准备执行的操作           | 例如 `add_liquid`，必须与设备声明的操作标识一致               |
| `parameters`       | 本次操作的实际参数值          | 例如来源容器为 `source-01`、加液量为 `0.5 mL`；字段必须符合参数定义 |
| `preconditions`    | 调用方已知且要求设备再次确认的操作条件 | 例如“加液量符合范围”“目标容器必须处于无盖状态”                    |
| `requested_result` | 调用方希望返回的附加结果        | 例如要求返回实际体积、温度曲线或测量质量标记；不得据此省略基础结果字段          |

## 返回时的操作字段

| 字段                          | 含义             | 可以填写的内容与示例                                                         |
| --------------------------- | -------------- | ------------------------------------------------------------------ |
| `operation_id`              | 返回结果对应的操作      | 应与调用中的操作标识一致                                                       |
| `status`                    | 操作执行状态         | 可填 `accepted`、`running`、`succeeded`、`failed`、`cancelled`、`unknown` |
| `actual_parameters`         | 设备实际采用或实际达到的参数 | 例如实际加液量 `0.498 mL`、实际最高温度 `79.8 °C`、实际转速 `598 rpm`                 |
| `result`                    | 操作产生的业务无关结果    | 例如测量值、完成数量、实际持续时间或设备确认的动作结果                                        |
| `progress`                  | 当前完成程度         | 可填百分比、已完成步骤数或阶段名称，例如 `60%`、`3/5`、`stabilizing`                     |
| `started_at`、`completed_at` | 实际开始和结束时间      | 使用带时区的时间；未开始或未结束时相应字段可为空                                           |
| `diagnostics`               | 结构化执行诊断集合      | 成功时可为空；失败时填写错误码、说明、相关字段、是否可重试和已确认事实                                |

## 填写示例

以加液操作为例，操作说明可以声明：操作标识为 `add_liquid`；参数包括来源容器标识和加液体积；体积类型为数值、单位为毫升、允许范围为 `0.05–0.8 mL`；完成条件为设备确认液体已经加入且实际体积得到核验。调用时可以填写来源容器 `source-01` 和体积 `0.5 mL`。完成后的操作结果可以填写状态 `succeeded`、实际体积 `0.498 mL`、诊断为空。

以设定温度操作为例，可以声明目标温度、升温速率和稳定时间三个参数。目标温度可限制为 `20–120 °C`，升温速率可限制为 `0.1–10 °C/min`。完成后返回实际稳定温度、达到稳定状态的时间以及超调量；如果温度未在规定时间内进入允许偏差，则状态填写 `failed`，诊断说明超时和实际温度。

## 强制规则

* 操作参数必须声明类型、含义以及适用的范围、枚举或格式约束；
* 调用前必须同时校验对象状态、操作参数和系统条件；
* 返回结果必须反映设备实际执行情况，不得把计划参数直接当作实际结果；
* 失败、取消或结果未知时，不得报告预期成功状态；
* FSP 不规定操作在 HTTP、CLI、MCP、RPC 或 SDK 中的具体名称与路径。