Skip to main content

定义

操作是设备通过 FSP 暴露的具体技能接口。FSP 关注接口语义,不强制设备采用特定 URL、HTTP 方法或驱动实现。 每个操作至少说明:稳定指令标识、请求分类、名称、用途、对象维度、控制维度、系统维度、返回值、诊断和同步或异步模式。 request_class 是请求风险分类,不是具体请求名称,只能是: 同一分类下可以有任意多条具体技能。例如,读取温度和读取任务进度都属于 read,设置温度目标值和修改速度参数都属于 write,加液和移动容器都属于 invoke。具体技能始终由 command_id 区分。

非规范性完整操作集

以下三个操作共同构成一个容器开盖、加液、关盖的设备技能示例。具体设备实现可以声明不同操作,但每条操作必须从对象、控制和系统三个维度提供同等完整的信息。

开盖 open_caps

强制约束:容器必须有盖;容器数量与编号必须匹配;开盖瓶号必须属于本次容器;keep_cap 只能为 01。成功返回 container_typecontainer_statussample_statusopened_bottles[]opened_bottles_count

关盖 close_caps

强制约束:容器必须无盖;容器数量与编号必须匹配;关盖瓶号必须属于本次容器;容器内液体体积不得超过 30 mL。成功返回 container_typecontainer_statussample_statusclosed_bottles[]closed_bottles_count

加液 add_liquid_with_material

以下非规范性示例展示一条完整设备操作:
上述示例重点展示控制维度中的参数层级、范围、约束和返回字段。对象兼容条件与系统安全条件必须同时存在于该技能的完整定义中。execution_mode 取值只能是 syncasync,必须由 FSP 适配器根据设备接口声明,不能由转换器猜测。

参数要求

参数定义应当包含下列适用字段:
嵌套参数必须展开到可验证层级。例如 dispensing_plan 应当说明 sample_bottle_idsource_bottle_idingredient_namesource_volume_mL,不能只写“对象数组”。

读取类请求

fsp/read 用于执行 request_class=read 的具体技能。读取通常不受工艺步骤顺序限制,但仍需满足设备在线、目标存在和数据源可用等基本条件。 读取类技能必须声明读取范围、输入 Schema、输出 Schema、observed_at 和数据新鲜度。读取不得修改设备、容器或工艺参数;无法取得新鲜数据时应返回诊断或明确标记数据过期,不得把旧缓存伪装为当前状态。

调用类请求

fsp/invoke 表示请求分类入口,add_liquid_with_material 才是本次实际技能。最终执行计划中的 operation 和参数由技能绑定模块解析为这里的 command_id 与函数参数,不能直接按字符串猜测。

写入类请求

只有完整技能定义将某个字段声明为可写时,调用方才能使用 fsp/write。请求参数与 fsp/invoke 使用相同外层:device_id、能力中取得的 command_idargumentsexpected_revision 写入类请求必须在接触设备前完成以下检查:
  1. command_idrequest_class 必须为 write
  2. 目标字段必须明确声明为可写;
  3. 新值必须通过类型、范围、枚举和跨字段约束;
  4. expected_revision 必须与当前状态修订号一致;
  5. 写入完成后必须回读目标值,或取得具有同等可信度的设备确认。
写入结果未经验证时不得返回成功,也不得提交新的状态修订号。 本页非规范性设备示例只声明调用类技能,因此不提供写入类技能示例。其他设备只有在完整技能定义中声明可写字段后才能发布相应写入技能。

强制约束

invoke 类操作开始前必须校验完整技能定义中的强制条件,包括:
  • 初始容器状态;
  • 样品状态;
  • 参数类型、范围和枚举;
  • 容器数量与编号关系;
  • 多参数耦合约束;
  • 系统安全围栏。
所有强制错误必须在 diagnostics 中返回。存在强制错误时不得接触物理设备,也不得提交研究对象新状态。动作完成后还必须验证设备结果、对象状态和声明的状态变化;验证失败时不得把预期结果写成实际结果。

返回

同步成功时,返回值必须符合技能控制维度中的 returns,并包含实际状态变化。异步技能返回任务句柄,见异步任务

同步输出示例