定义
操作是设备通过 FSP 暴露的具体技能接口。FSP 关注接口语义,不强制设备采用特定 URL、HTTP 方法或驱动实现。 每个操作至少说明:稳定指令标识、请求分类、名称、用途、对象维度、控制维度、系统维度、返回值、诊断和同步或异步模式。request_class 是请求风险分类,不是具体请求名称,只能是:
同一分类下可以有任意多条具体技能。例如,读取温度和读取任务进度都属于
read,设置温度目标值和修改速度参数都属于 write,加液和移动容器都属于 invoke。具体技能始终由 command_id 区分。
非规范性完整操作集
以下三个操作共同构成一个容器开盖、加液、关盖的设备技能示例。具体设备实现可以声明不同操作,但每条操作必须从对象、控制和系统三个维度提供同等完整的信息。开盖 open_caps
强制约束:容器必须有盖;容器数量与编号必须匹配;开盖瓶号必须属于本次容器;
keep_cap 只能为 0 或 1。成功返回 container_type、container_status、sample_status、opened_bottles[] 和 opened_bottles_count。
关盖 close_caps
强制约束:容器必须无盖;容器数量与编号必须匹配;关盖瓶号必须属于本次容器;容器内液体体积不得超过 30 mL。成功返回
container_type、container_status、sample_status、closed_bottles[] 和 closed_bottles_count。
加液 add_liquid_with_material
以下非规范性示例展示一条完整设备操作:
execution_mode 取值只能是 sync 或 async,必须由 FSP 适配器根据设备接口声明,不能由转换器猜测。
参数要求
参数定义应当包含下列适用字段:dispensing_plan 应当说明 sample_bottle_id、source_bottle_id、ingredient_name 和 source_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_id、arguments 和 expected_revision。
写入类请求必须在接触设备前完成以下检查:
command_id的request_class必须为write;- 目标字段必须明确声明为可写;
- 新值必须通过类型、范围、枚举和跨字段约束;
expected_revision必须与当前状态修订号一致;- 写入完成后必须回读目标值,或取得具有同等可信度的设备确认。
强制约束
invoke 类操作开始前必须校验完整技能定义中的强制条件,包括:
- 初始容器状态;
- 样品状态;
- 参数类型、范围和枚举;
- 容器数量与编号关系;
- 多参数耦合约束;
- 系统安全围栏。
diagnostics 中返回。存在强制错误时不得接触物理设备,也不得提交研究对象新状态。动作完成后还必须验证设备结果、对象状态和声明的状态变化;验证失败时不得把预期结果写成实际结果。
返回
同步成功时,返回值必须符合技能控制维度中的returns,并包含实际状态变化。异步技能返回任务句柄,见异步任务。