Skip to main content
FSP 要求厂商提供的设备接口必须包含 操作、对象、系统 三个维度的内容。操作说明调用什么能力以及实际结果,对象说明涉及哪些容器或样品及其状态变化,系统说明设备、安全、任务和资源状态。三者是同一套厂商接口必须覆盖的三方面内容,不是三套独立服务。 厂商可以继续使用原有的 HTTP API、CLI、MCP 工具、SDK、RPC 或驱动,也可以把三方面信息分布在操作调用、状态查询、结果回调或事件中。FSP 服务中的适配器按预先写好的规则完成字段、单位和结果映射;如果厂商接口没有提供某项实际信息,适配器只能把它标为未知,不能临时猜测或用请求值代替。 流程伪代码见适配器:用同一个加液例子说明动作怎么定义、执行前怎么检查、设备命令怎么转换。完整实现见 GitCode 示例源码

各部分负责什么

这些职责可以放在同一个程序里,也可以分成多个服务,不要求使用特定语言或类名。但要能查清每项检查由谁完成、结果从哪里取得。 每项操作必须对应到指定设备的实现代码。找不到时就报错,不能拿另一台设备的同名动作替代。初始化时必须检查必填参数、返回格式和配置;这些检查通过,不代表设备已经在线或真实动作已经验收。 接入设备前,必须整理协议来源和版本、命令与返回值的对应关系、单位、限制、超时、完成条件,以及哪些功能还不支持。这些材料必须经过人工或既定流程审核。不能把模板或模型生成的配置直接用于控制真实设备。 简单的一请求一响应命令可以采用声明式映射;涉及会话、校验和、二进制帧、分段读写、轮询、取消或多阶段动作时,必须明确实现相应行为。配置中写了命令不等于协议已经被实现。

规范请求示例

以下加液场景假设设备定义版本为 12,操作契约版本为 1,体积单位为 mL。来源和目标都参与资源及版本号检查。字符串条件仅为阅读说明;实现必须把它们关联到稳定规则和可执行检查,不能靠语言模型临场判断。
before_state 是调用方预期,不是服务端可无条件采信的现场证据。目标容器由唯一 target 角色确定;来源参数必须与 source 角色一致。各操作必须明确角色数量、可重复性以及参数引用规则。

受理响应示例

这里设备尚未运动,因此物理状态仍为 idle;资源已预留,因此系统版本号发生变化。其他冲突任务仍不可进入。changes: [] 仅表示受理时没有新增对象变化;actual_parameters: {} 表示尚无实际参数证据,不能把请求量抄入该字段。 任务开始后,必须通过查询或订阅取得实际结果。最终状态仍要覆盖操作、对象、系统三个维度;成功证据见怎样判断操作成功,未知及取消处理见任务生命周期。已确认的部分对象变化必须返回,不必等待任务成功。

不同接口怎么使用同一份数据

每种接口都必须说明怎样选择设备、调用操作、查询结果、取消任务、提交观察记录,以及怎样返回错误。FSP 不指定 URL、工具名、命令名或函数名。没有实现的可选功能要明确说明,不能返回成功。 接口请求 ID 用于识别一次通信,system.idempotency_key 用于关联一次会改变设备或样品状态的操作。HTTP 实现若使用 Idempotency-Key 头,必须定义到该规范字段的对应关系;头与请求体同时出现且不一致时拒绝。路径、工具参数、连接上下文等多处设备标识也必须一致。 旧实现的顶层 operation_id 或扁平对象参数只有经过明确版本化映射,才是本规范输入。不能仅因能返回 JSON 就声称已经覆盖操作、对象、系统三个维度。

接入验证与交付

交付设备实现时,应附上操作版本、设备定义、已支持的功能、必填配置、经过审核的命令对应表、失败情况、结果证据样例和测试记录。测试要分开记录:
  1. 静态定义与绑定检查;
  2. 桩驱动的参数、状态、锁与故障注入测试;
  3. 真实通信及回执解析验证;
  4. 真实设备动作、停止和恢复验证;
  5. 目标样品效果验证(仅当契约承诺该范围时)。
每层记录版本、设备或桩身份、环境、时间、案例和结果。代码和配置检查、模拟结果、过去的测试报告,不能代替后面的实际测试;未执行项必须标为未验证。验收场景见符合性