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

# 操作者

> 用操作者记录每个操作的执行者

<Info>
  要完整记录操作者，需使用 Workspace API Key，创建方式见[认证](/zh/api-guide/v1/authentication)。旧版 API Key 创建的 Task 操作者信息有限。
</Info>

## 概览

**操作者（Actor）** 标识在 Nonce 中执行操作的主体，用来回答「这个操作是**谁**做的」，是 Task 审计的基础。

通过操作者可以：

* 追踪哪个用户、API Key 或系统进程创建了 Task Batch
* 留下合规和运营所需的审计记录
* 区分手动操作（用户）和自动化操作（API Key 或系统）

***

## 操作者类型

| 类型       | 描述               | ID 前缀   |
| -------- | ---------------- | ------- |
| `user`   | 通过 Nonce 平台登录的用户 | `user_` |
| `apikey` | 用于程序化访问的 API Key | `ak_`   |
| `system` | 内部系统操作或自动化       | -       |

***

## 操作者 Schema

API 响应中的操作者对象包含以下字段：

| 字段         | 类型             | 描述                               |
| ---------- | -------------- | -------------------------------- |
| `type`     | string         | 操作者类型：`user`、`apikey` 或 `system` |
| `id`       | string         | 操作者的唯一标识符                        |
| `name`     | string \| null | 操作者的显示名称                         |
| `avatar`   | string \| null | 头像 URL（适用于 user 类型的操作者）          |
| `metadata` | object         | 操作者的附加元数据                        |

### 操作者响应示例

**用户操作者：**

```json theme={null}
{
  "type": "user",
  "id": "user_2xGz1234567890",
  "name": "John Doe",
  "avatar": "https://example.com/avatar.png",
  "metadata": {
    "email": "john@example.com"
  }
}
```

**API Key 操作者：**

```json theme={null}
{
  "type": "apikey",
  "id": "ak_abc123xyz",
  "name": "Production API Key",
  "avatar": null,
  "metadata": {
    "keyPrefix": "nonce_sk_..."
  }
}
```

**系统操作者：**

```json theme={null}
{
  "type": "system",
  "id": "automation-system",
  "name": "Automation",
  "avatar": null
}
```

***

## 在 API 响应中的使用

### Task Batch

查询 Task Batch 时，`created_by` 字段是创建该 Task Batch 的操作者：

```json theme={null}
{
  "batch_id": "xxxxx-xxxxx-xxxx-xxxxxx",
  "task_name": "miner.power_mode.update",
  "status": "succeed",
  "task_count": 10,
  "succeed_count": 10,
  "failed_count": 0,
  "created_by": {
    "type": "user",
    "id": "user_2xGz1234567890",
    "name": "John Doe",
    "avatar": "https://example.com/avatar.png"
  },
  "created_at": "2024-01-15T10:30:00Z"
}
```

<Note>
  操作者无法解析时（例如用户已被删除），`created_by` 可能为 `null` 或显示为「Unknown」。
</Note>

***

## 当前限制

* **旧版 API Key**：用旧版 API Key 创建的 Task 可能只有部分操作者信息
* **系统操作**：部分自动化操作归属于 `system` 操作者
* **历史数据**：较早的记录可能没有操作者信息