适用范围
本规范定义厂商设备接口必须包含的数据结构与行为。每个厂商接口都要覆盖操作、对象和系统三个维度的内容,但不要求拆成三套独立接口,也不规定 HTTP 路径、CLI 命令、MCP 工具名、RPC 名称或消息封装格式。实现可以自行选择连接和传输方式。通用操作输入
通用操作输出
版本号与单位
- 对象状态和系统状态必须带有版本号;
- 改变状态的操作必须带入预期版本号;冲突时不得继续执行;
- 数值和单位必须明确表达。
出错时怎样返回
输入不能解析、缺少必填字段或字段类型错误时,厂商接口可以使用自身错误格式返回格式固定的错误说明。设备已经受理操作后的失败必须提供三个维度的输出,返回实际对象状态、操作错误说明及设备和任务状态。字段放在哪里
以上为结构示意,空容器数组不能替代加液操作所需的真实对象。完整受理示例见设备接口。 操作名称统一放在operation.operation_id。device_id 指定执行设备,可以写在请求外层,也可以由经过身份校验的连接提供。
实际接口如果用工具名、URL 路径或旧的顶层字段表示操作,必须说明怎样转成规范字段。如果请求的不同位置写了不同的设备或操作,必须拒绝,不能擅自选一个。
实现必须提供程序能读取的输入、输出和设备能力定义,例如 JSON Schema,并说明各字段怎样对应到实际接口。
本页的表格和示例不是完整 JSON Schema。验收时既要检查数据格式,也要检查本规范要求的处理行为。
缺失字段表示未提供;
null 只用于契约允许的未知或尚不存在值,并说明原因;空数组表示已明确没有条目。不得将未知物理量填为默认零值,也不能将 null 或空字符串解释为测量结果。数字应为有限数值,带单位的文本不能替代数值字段;字段名含单位时定义中仍须声明单位、换算和舍入规则。
请求编号区分每次通信,任务编号区分每次执行;设备编号、操作名称和对象版本也各有用途,不能混用。查询结果应说明属于哪台设备、哪个任务。请求尚未受理就被拒绝时,不能返回一个假装已经创建的任务编号。