> ## 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 参数

## 概览

Task 是在矿机上执行的操作。Nonce 使用基于 Task Batch 的系统，多个 Task 可以分组并一起执行。

### Task vs Task Batch

| 概念             | 描述                              |
| -------------- | ------------------------------- |
| **Task**       | 在单个矿机上执行的单个操作                   |
| **Task Batch** | 一组一起创建的 Task，共享相同的 Task 名称和基础参数 |

当您通过 API 创建 Task 时，您始终创建的是 **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.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.firmware.update`   | 更新矿机固件            |

### 矿机事件 Task

更新矿机资产元数据的特殊 Task。

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

| Task 名称              | 描述                  |
| -------------------- | ------------------- |
| `miner.asset.update` | 更新矿机资产状态（例如，标记为维护中） |
| `miner.asset.delete` | 将矿机资产标记为已删除         |

***

## 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`） |

### miner.asset.update

更新矿机资产状态。

| 参数        | 类型     | 必填 | 描述                                                                                 |
| --------- | ------ | -- | ---------------------------------------------------------------------------------- |
| `status`  | string | 是  | 可用的资产状态：`online`、`on_rack`、`off_rack`、`transit`、`maintenance`、`retired`、`archived` |
| `comment` | string | 否  | 资产状态更新的可选备注                                                                        |

### miner.asset.delete

将矿机资产标记为已删除。无必填参数。

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

***

## 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 实际被创建，哪些被跳过，以及跳过的原因。这对于调试和了解为什么某些矿机没有收到 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 不存在或无法访问   |