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

# 系统

> 说明设备状态、安全限制、长任务和注意事项如何表达。

系统维度说明设备此刻是否允许执行操作，以及受理和完成操作后设备处于什么状态。它包含设备状态、修订号、安全围栏、执行模式、异步任务和注意事项，但不要求设备为系统维度单独建立接口。

## 调用时的系统字段

| 字段                         | 含义               | 可以填写的内容与示例                                                                                |
| -------------------------- | ---------------- | ----------------------------------------------------------------------------------------- |
| `expected_device_state`    | 调用方要求的设备执行前状态    | 常见值包括 `idle`、`ready`；设备应声明自己的状态集合，实际为 `busy`、`fault`、`maintenance` 或 `offline` 时通常不得启动新动作 |
| `expected_system_revision` | 调用方依据的系统状态版本     | 可填 `system-21`；设备当前版本不同表示状态已变化，应重新检查                                                      |
| `execution_mode`           | 同步等待还是异步受理       | 可填 `sync` 或 `async`；预计耗时长、可查询进度或需要取消的操作通常使用异步模式                                           |
| `preconditions`            | 设备层面的执行前置条件      | 可填“设备无故障”“门盖关闭”“目标容器已经定位”“当前不存在冲突任务”                                                      |
| `safety_fences`            | 动作前必须通过的安全限制     | 可填最大体积、温度上限、压力上限、运动范围、容器兼容性、互锁和人员防护条件                                                     |
| `resource_locks`           | 本次操作需要独占或共享的设备资源 | 可填机械臂、加热区、移液通道、夹具、传感器或工作区域；冲突锁不得同时授予                                                      |
| `timeout_s`                | 调用方允许等待的最长时间     | 可填 `30 s`、`600 s`；超时只表示等待结束，不应自动推断物理动作失败                                                  |
| `idempotency_key`          | 识别同一次操作请求        | 可使用调用方生成的唯一标识；相同标识不得重复执行同一物理动作                                                            |
| `requested_notifications`  | 调用方希望接收的系统事件     | 可填任务开始、进度变化、完成、失败、安全围栏触发或需要人工处理                                                           |

## 返回时的系统字段

| 字段                | 含义                | 可以填写的内容与示例                                                         |
| ----------------- | ----------------- | ------------------------------------------------------------------ |
| `device_state`    | 返回时设备的实际状态        | 可填 `idle`、`busy`、`paused`、`fault`、`maintenance`、`offline`；必须来自设备事实 |
| `system_revision` | 当前系统状态版本          | 设备状态、资源锁或安全状态发生变化时应生成新修订号                                          |
| `safety_checks`   | 各项安全围栏的检查结果       | 每项应说明规则、是否通过、实际值和限制值；例如“剩余容量足够：通过，剩余 45 mL，需要 0.5 mL”              |
| `resource_locks`  | 当前锁的实际状态          | 可说明已获得、等待、释放或冲突，并标识对应资源                                            |
| `task`            | 长任务的状态与结果索引       | 包含任务标识、状态、进度、是否可取消以及结果是否可读取                                        |
| `notices`         | 调用方继续操作前需要知道的注意事项 | 可填“任务完成前不得移动目标容器”“设备需要人工复位”“结果需要复测”；无事项时为空集合                       |
| `observed_at`     | 系统状态的实际观测时间       | 使用带时区时间；超过实现声明的新鲜度后应重新获取                                           |
| `expires_at`      | 当前状态可以安全复用到何时     | 适用于短期缓存；过期后不得继续依赖旧状态执行物理动作                                         |

## 异步任务字段

| 字段                                       | 含义            | 可以填写的内容与示例                                                         |
| ---------------------------------------- | ------------- | ------------------------------------------------------------------ |
| `task_id`                                | 一次异步执行实例的稳定标识 | 可填 `task-001`；后续进度、结果和取消操作使用同一标识                                   |
| `status`                                 | 当前任务状态        | 可填 `queued`、`running`、`succeeded`、`failed`、`cancelled` 或 `unknown` |
| `progress`                               | 任务完成程度        | 可填百分比、完成数量、当前阶段和预计剩余时间，例如 `60%` 或“等待温度稳定”                          |
| `cancellable`                            | 当前阶段是否允许安全取消  | 可填 `true` 或 `false`；已经进入不可中断的物理阶段时应为 `false`                       |
| `result_available`                       | 是否已有可读取的最终结果  | 任务完成且结果写入后为 `true`；受理或运行阶段通常为 `false`                              |
| `started_at`、`updated_at`、`completed_at` | 任务关键时间        | 未开始或未完成时相应字段可以为空                                                   |
| `diagnostics`                            | 与任务状态有关的诊断    | 可说明设备故障、通信中断、结果无法确认、取消失败或需要人工检查                                    |

实现可以通过 HTTP、CLI、MCP、RPC 或 SDK 提供任务查询、通知和取消能力，FSP 不规定其名称或路径。每次返回任务状态时仍应同时给出对象、操作和系统三个维度的当前事实。

## 填写示例

加液操作开始前，系统信息可以要求设备状态为 `idle`、系统修订号为 `system-21`、执行模式为异步，并要求“设备无故障、目标容器已定位、没有冲突任务”。安全围栏可以包括“目标容器剩余容量不少于加液量”和“单次加液量不超过设备上限”。设备受理后可返回状态 `busy`、任务状态 `queued`，并提示任务完成前不得移动容器。

温控操作可以要求设备状态为 `ready`，锁定加热区，并设置温度上限、升温速率和门盖互锁。执行中任务进度可以填写“升温阶段，当前 65.2 °C，目标 80 °C”；完成后设备状态恢复为 `idle`，安全检查返回实际最高温度和限制值。

如果通信中断导致无法确认动作是否完成，任务状态必须填写 `unknown`，系统注意事项应要求重新读取设备和对象状态。此时不得直接重试可能重复发生的物理动作，也不得提交预期成功状态。