> ## 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.

# 接口契约

> 说明设备接口如何表达输入、结果、状态版本和错误。

## 适用范围

本规范只定义设备接口必须表达的数据结构与行为，不定义 HTTP 路径、CLI 命令、MCP 工具名、RPC 名称或消息封装格式。实现可以自行选择连接和传输方式。

## 通用操作输入

```json theme={null}
{
  "device_id": "device-01",
  "operation_id": "add_liquid",
  "object": {
    "containers": []
  },
  "operation": {
    "parameters": {},
    "preconditions": []
  },
  "system": {
    "expected_device_state": "idle",
    "expected_system_revision": "system-21",
    "execution_mode": "async",
    "preconditions": [],
    "safety_fences": []
  }
}
```

## 通用操作输出

```json theme={null}
{
  "object": {
    "changes": []
  },
  "operation": {
    "operation_id": "add_liquid",
    "status": "accepted",
    "actual_parameters": {},
    "diagnostics": []
  },
  "system": {
    "device_state": "busy",
    "system_revision": "system-22",
    "safety_checks": [],
    "task": null,
    "notices": [],
    "observed_at": "2026-09-02T06:00:00Z"
  }
}
```

| 部分          | 最低要求                          |
| ----------- | ----------------------------- |
| `object`    | 返回容器当前可确认状态、变化与修订号；无变化也必须明确表达 |
| `operation` | 返回操作标识、受理或完成状态、实际参数和诊断        |
| `system`    | 返回设备状态、安全检查、任务、注意事项和观测时间      |

## 修订号与单位

* 对象状态和系统状态必须带有修订号；
* 改变状态的操作必须带入预期修订号；冲突时不得继续执行；
* 数值和单位必须明确表达。

## 错误语义

输入不能解析、缺少必填字段或字段类型错误时，承载协议可以使用自身错误格式返回结构化诊断。设备已经受理操作后的失败必须使用三段操作输出，返回实际对象状态、操作诊断和系统事实。