> ## Documentation Index
> Fetch the complete documentation index at: https://automationlaboratoryprotocol.mimedal.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 异步任务

> 长时间设备操作的受理、查询、取消和结果语义

## 适用范围

不能在一次请求内可靠完成的 `write` 或 `invoke` 技能应当返回异步任务。异步只是执行方式，不改变请求分类、参数、状态约束和返回值定义。`read` 也可以异步产生任务，但仍不得改变设备状态。

## 创建任务

分类请求入口返回：

```json theme={null}
{
  "result_type": "task",
  "task": {
    "task_id": "opaque-task-id",
    "device_id": "2002186824385539",
    "command_id": "add_liquid_with_material",
    "request_class": "invoke",
    "status": "queued",
    "accepted_at": "2026-09-01T12:00:00Z",
    "cancellable": true
  },
  "diagnostics": []
}
```

| 字段              | 类型        | 说明                    |
| --------------- | --------- | --------------------- |
| `task_id`       | `string`  | 服务端生成的不透明任务标识         |
| `device_id`     | `string`  | 执行任务的设备标识             |
| `command_id`    | `string`  | 完整技能定义中的稳定技能标识        |
| `request_class` | `string`  | 创建任务的请求分类，必须与完整技能定义一致 |
| `status`        | `string`  | 当前任务状态                |
| `accepted_at`   | `string`  | 服务端受理时间               |
| `cancellable`   | `boolean` | 当前阶段是否接受取消请求          |

## 查询任务

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": "task-read-1",
  "method": "fsp/get_task",
  "params": {
    "device_id": "2002186824385539",
    "task_id": "opaque-task-id"
  }
}
```

任务状态只能是：

```text theme={null}
queued
running
succeeded
failed
cancelled
unknown
```

### 运行中输出

```json theme={null}
{
  "result_type": "complete",
  "value": {
    "task_id": "opaque-task-id",
    "device_id": "2002186824385539",
    "command_id": "add_liquid_with_material",
    "request_class": "invoke",
    "status": "running",
    "accepted_at": "2026-09-01T12:00:00Z",
    "started_at": "2026-09-01T12:00:01Z",
    "completed_at": null,
    "cancellable": true,
    "result": null
  },
  "diagnostics": []
}
```

### 成功输出

成功时 `result` 必须符合对应技能的 `control.output_schema`。以下返回字段使用本规范的加液技能定义：

```json theme={null}
{
  "result_type": "complete",
  "value": {
    "task_id": "opaque-task-id",
    "device_id": "2002186824385539",
    "command_id": "add_liquid_with_material",
    "request_class": "invoke",
    "status": "succeeded",
    "accepted_at": "2026-09-01T12:00:00Z",
    "started_at": "2026-09-01T12:00:01Z",
    "completed_at": "2026-09-01T12:00:12Z",
    "cancellable": false,
    "result": {
      "containers": [
        {
          "container_type": "离心瓶",
          "container_status": "无盖",
          "sample_status": "液体",
          "container_id": 1,
          "sample_volume": 0.5,
          "source_bottle_ids": [1]
        }
      ]
    },
    "revision": "8"
  },
  "diagnostics": []
}
```

时间、任务标识和修订号属于 FSP 运行时字段；`containers` 内的字段和值来自技能返回定义。该示例用于说明协议结构，不表示设备已经产生过该任务。

## 取消任务

`fsp/cancel_task` 表示请求取消，不代表设备已经停止。服务端必须返回实际任务状态。不可取消的操作应当返回结构化诊断。

## 状态提交

* `succeeded`：完成条件和技能的结果验证规则全部满足后，可以提交实际状态变化；
* `failed`：不得提交预期成功状态，应当返回设备可确认的实际状态；
* `cancelled`：返回取消后可确认的状态；
* `unknown`：不得假定成功，调用方必须重新读取相关对象和设备状态。

## 示例边界

本页任务对象是规范性数据结构，示例中的设备标识、时间和值为非规范性结构示例。符合性必须由真实 FSP 服务的任务状态变化、结果查询和状态提交行为验证。