> ## Documentation Index
> Fetch the complete documentation index at: https://all.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`、`waiting_confirmation`、`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`、执行模式为异步，并要求“设备无故障、目标容器已定位、没有冲突任务”。安全限制可以包括“目标容器剩余容量不少于加液量”和“单次加液量不超过设备上限”。受理后任务可为 `queued`；设备设备状态以实际读取结果为准，不能仅因预留资源就改写为 `busy`，并提示任务解除占用前不得移动容器。

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

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

## 执行时要注意的状态问题

状态转换、幂等、取消、资源隔离和持久化恢复遵循[任务状态与异常恢复](/docs/specification/fsp/lifecycle)。部署是否就绪由[能力门控](/docs/specification/fsp/capability-gating)判断。

要分别说明设备实际是什么状态、任务排到了哪一步、操作所需配置是否完成。受理任务并占用资源，不代表电机已经运动；任务结束并释放资源，也不代表设备已经空闲。

资源锁要写清锁住了什么、属于哪个任务或计划、是独占还是共享、现在是否有效。计划提前占用的资源可以供自己的子任务使用，但其他计划不能使用。

需要同时占用多个资源时，应避免双方各占一部分、一直互相等待。出现冲突时，按已公布的规则释放尚未使用的资源，或返回具体原因。动作结果未知时，必须先确认安全，才能解除占用。

同一对象、系统或设备定义的版本号，不能让旧版本代表新状态；重启后也不能从头使用旧版本号。状态改变，或者原来已知的结果变成未知时，应更新版本。只是查询，不应随意改变版本。

调用方只能增加执行条件和安全限制，不能关闭服务端原有的检查。传入空列表也不表示跳过检查。

查询时要分清 `observed_at`（实际观察时间）和响应生成时间。旧结果不能因为刚刚被读出来，就变成新结果。过期、没有来源或无法确认的状态，不能用于通过执行前检查；汇总缓存时要保留原来的时间、来源和可信程度。