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

# Task

> Nonce 的 Task、Task Batch 与参数说明

## 概览

Task 是在矿机上执行的操作。Nonce 以 Task Batch 为单位下发：多个 Task 编成一组一起执行。

### Task vs Task Batch

| 概念             | 描述                           |
| -------------- | ---------------------------- |
| **Task**       | 作用于一台矿机的单次操作                 |
| **Task Batch** | 同批创建的一组 Task，共享 Task 名称和基础参数 |

通过 API 创建的一定是 **Task Batch**，系统会为每台目标矿机自动生成对应的 Task。

***

## Task 名称

Task 按执行对象和用途分为以下几类。创建 Task Batch 的请求包含：

```json theme={null}
{
  "task_name": "miner.power_mode.update",
  "miner_ids": ["miner-id-1", "miner-id-2"],
  "params": {
    "mode": "low"
  }
}
```

| 字段          | 类型        | 必填   | 描述                               |
| ----------- | --------- | ---- | -------------------------------- |
| `task_name` | string    | 是    | 要执行的 Task 类型（见下表）                |
| `miner_ids` | string\[] | 条件必填 | 目标矿机 ID 数组（矿机级别的 Task 必填）        |
| `params`    | object    | 否    | Task 特定参数（见 [Task 参数](#task-参数)） |

### Agent 级别 Task

> Agent 级别的 Task 不需要 `miner_ids` 参数。

在 Agent 上执行的操作。

| Task 名称                     | 描述                 |
| --------------------------- | ------------------ |
| `agent.scan.create`         | 扫描网络发现矿机           |
| `agent.ip_diagnosis.create` | 运行 IP 诊断并上传 CSV 报告 |
| `agent.self.update`         | 更新 Agent           |

### 矿机级别 Task

由 Agent 对矿机执行的操作。

> 需要 `miner_ids` 指定目标矿机。

| Task 名称                   | 描述                |
| ------------------------- | ----------------- |
| `miner.system.reboot`     | 重启矿机设备            |
| `miner.log.get`           | 从矿机收集诊断日志         |
| `miner.light.update`      | 切换矿机的 LED 指示灯     |
| `miner.power_mode.update` | 更改[挖矿功耗模式](#挖矿模式) |
| `miner.pool.update`       | 更新矿池配置            |
| `miner.pool.lock`         | 锁定或解锁矿池配置         |
| `miner.firmware.update`   | 更新矿机固件            |

### 矿机事件 Task

更新矿机清单元数据的特殊 Task。

> 需要 `miner_ids` 指定目标矿机。

| Task 名称                      | 描述            |
| ---------------------------- | ------------- |
| `miner.tags.update`          | 添加或移除矿机的运维标签  |
| `miner.record.delete`        | 将矿机在清单中标记为已删除 |
| `miner.rack_location.update` | 更新矿机的机架位置元数据  |

***

## Task 参数

每种 Task 有各自的参数。

### miner.system.reboot

重启矿机设备。

| 参数      | 类型      | 必填 | 描述                      |
| ------- | ------- | -- | ----------------------- |
| `force` | boolean | 否  | 即使矿机正在挖矿也强制重启（默认：false） |

### miner.log.get

从矿机收集诊断日志。无需额外参数。

### miner.light.update

切换矿机的 LED 指示灯。

| 参数     | 类型     | 必填 | 描述                |
| ------ | ------ | -- | ----------------- |
| `mode` | string | 是  | 灯光模式：`on` 或 `off` |

### miner.power\_mode.update

更改挖矿功耗模式。

| 参数     | 类型     | 必填 | 描述                     |
| ------ | ------ | -- | ---------------------- |
| `mode` | string | 是  | 挖矿模式（见下方[挖矿模式](#挖矿模式)） |

### miner.pool.update

更新矿池配置。

| 参数             | 类型     | 必填 | 描述                                               |
| -------------- | ------ | -- | ------------------------------------------------ |
| `pools`        | array  | 是  | 矿池配置数组                                           |
| `pools[].url`  | string | 是  | 矿池 URL（例如 `stratum+tcp://pool.example.com:3333`） |
| `pools[].user` | string | 是  | 矿池用户名/矿工名                                        |

### miner.firmware.update

更新矿机固件。

| 参数             | 类型     | 必填 | 描述          |
| -------------- | ------ | -- | ----------- |
| `firmware_url` | string | 是  | 固件文件的下载 URL |

### agent.scan.create

扫描网络发现矿机。

| 参数         | 类型     | 必填 | 描述                              |
| ---------- | ------ | -- | ------------------------------- |
| `ip_range` | string | 否  | 要扫描的 IP 范围（例如 `192.168.1.0/24`） |

### agent.ip\_diagnosis.create

运行 Agent IP 诊断并上传 CSV 报告。

| 参数               | 类型      | 必填 | 描述                             |
| ---------------- | ------- | -- | ------------------------------ |
| `target_scope`   | string  | 否  | 诊断目标范围（默认 `known_with_custom`） |
| `custom_targets` | array   | 否  | 自定义诊断目标                        |
| `ping_only`      | boolean | 否  | 对无本地上下文的目标仅执行 ICMP ping 检查     |

### miner.pool.lock

通过 auth package 锁定或解锁矿池配置。锁定期间可防止未授权的矿池修改。

| 参数             | 类型     | 必填 | 描述                               |
| -------------- | ------ | -- | -------------------------------- |
| `firmware_url` | string | 是  | auth package 文件的 URL             |
| `action`       | string | 是  | `lock` 固定强制矿池配置；`unlock` 恢复可配置矿池 |

### miner.tags.update

添加或移除矿机的运维标签。仅影响元数据，不影响挖矿运行。

| 参数       | 类型        | 必填 | 描述                      |
| -------- | --------- | -- | ----------------------- |
| `add`    | string\[] | 否  | 为所选矿机添加的标签（每台矿机最多 50 个） |
| `remove` | string\[] | 否  | 从所选矿机移除的标签              |

### miner.record.delete

将矿机在清单中标记为已删除。矿机物理下架后使用。

| 参数        | 类型     | 必填 | 描述        |
| --------- | ------ | -- | --------- |
| `comment` | string | 否  | 删除操作的可选备注 |

### miner.rack\_location.update

更新矿机的机架位置元数据。使用顶层 `updates` 数组，不使用 `miner_ids` + `params`。

| 字段                   | 类型             | 必填 | 描述                         |
| -------------------- | -------------- | -- | -------------------------- |
| `updates[].miner_id` | string         | 是  | 目标矿机 ID                    |
| `updates[].rack`     | string \| null | 是  | 机架标识（最长 50 字符）；`null` 表示清除 |
| `updates[].position` | number \| null | 是  | 机架内的槽位序号；`null` 表示清除       |

***

## Task 状态

Task 有以下状态。

| 状态          | 描述                     |
| ----------- | ---------------------- |
| `created`   | Task 已创建，等待加入队列        |
| `queuing`   | Task 已加入队列，等待 Agent 处理 |
| `pending`   | Task 正在由 Agent 执行      |
| `succeed`   | Task 执行成功              |
| `failed`    | Task 执行失败              |
| `timed_out` | Task 执行超时              |
| `cancelled` | Task 在完成前被取消           |

### Task 生命周期

```mermaid theme={null}
flowchart LR
    created([created]):::default --> queuing([queuing]):::default --> pending([pending]):::default --> succeed([succeed]):::success
    pending --> failed([failed]):::error
    pending --> timed_out([timed_out]):::error
    pending --> cancelled([cancelled]):::warning

    classDef default fill:#f3f4f6,stroke:#6b7280,stroke-width:1px,color:#374151
    classDef success fill:#d1fae5,stroke:#10b981,stroke-width:2px,color:#065f46
    classDef error fill:#fee2e2,stroke:#ef4444,stroke-width:2px,color:#991b1b
    classDef warning fill:#fef3c7,stroke:#f59e0b,stroke-width:2px,color:#92400e
```

### Batch 状态

Task Batch 的状态由其中所有 Task 汇总得出。

| Batch 状态          | 描述              |
| ----------------- | --------------- |
| `pending`         | 部分 Task 仍在运行    |
| `succeed`         | 所有 Task 执行成功    |
| `failed`          | 所有 Task 执行失败    |
| `partial_succeed` | 部分 Task 成功，部分失败 |

***

## 挖矿模式

功耗模式因厂商而异，不是所有设备都支持全部模式。

### 各厂商支持的模式

| 厂商             | 支持的模式                  |
| -------------- | ---------------------- |
| **AntMiner**   | `sleep`、`low`、`normal` |
| **WhatsMiner** | `low`、`normal`、`high`  |

> 后续可能支持更多厂商和模式。

### 模式说明

| 模式       | 功耗     | 描述                      |
| -------- | ------ | ----------------------- |
| `sleep`  | \~5%   | 待机模式，最低功耗（仅限 AntMiner）  |
| `low`    | \~75%  | 降低算力，节能模式               |
| `normal` | \~100% | 标准运行，平衡性能               |
| `high`   | \~125% | 最大算力，高功耗（仅限 WhatsMiner） |

<Warning>
  给矿机设置厂商不支持的模式会返回验证错误。
</Warning>

***

## 示例：创建 Task Batch

```bash theme={null}
curl -X POST "https://api.nonce.app/private-api/v1/{workspace_id}/farms/{farm_id}/tasks/batches" \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "task_name": "miner.power_mode.update",
    "miner_ids": ["miner-id-1", "miner-id-2"],
    "params": {
      "mode": "low"
    }
  }'
```

上面的请求创建一个 Task Batch，把指定矿机的功耗模式改为 `low`。

### 响应格式

API 响应中的 `meta` 字段汇总 Task 的创建结果。

<Note>
  `meta` 字段说明创建过程的实际结果：哪些 Task 创建成功、哪些被跳过、跳过原因是什么，便于排查部分矿机没有收到 Task 的情况。
</Note>

```json theme={null}
{
  "success": true,
  "data": { ... },
  "error": null,
  "meta": {
    "summary": {
      "created_count": 1,
      "skipped_count": 1
    },
    "skipped": [
      {
        "reason": "no_change",
        "message": "Task skipped: miner already in requested mode",
        "miner_ids": ["miner-id-2"]
      }
    ]
  }
}
```

#### Meta 摘要

| 字段              | 类型     | 描述            |
| --------------- | ------ | ------------- |
| `created_count` | number | 成功创建的 Task 数量 |
| `skipped_count` | number | 被跳过的 Task 数量  |

#### 跳过原因

有矿机被跳过时，`skipped` 数组给出明细：

| 字段          | 类型        | 描述           |
| ----------- | --------- | ------------ |
| `reason`    | string    | 跳过原因代码（见下表）  |
| `message`   | string    | 可读的说明文字      |
| `miner_ids` | string\[] | 受影响的矿机 ID 数组 |

| 原因                 | 描述             |
| ------------------ | -------------- |
| `no_change`        | 矿机已处于请求的状态     |
| `unsupported_mode` | 该矿机的厂商不支持请求的模式 |
| `miner_not_found`  | 矿机 ID 不存在或无法访问 |