> ## 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>
  **Beta 功能**：操作者概念目前处于测试阶段。完整支持需要新的 API Key 格式，该格式尚未普遍可用。如需提前体验，请联系 [hi@nonce.app](mailto:hi@nonce.app)。
</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>

***

## 当前限制

<Warning>
  操作者功能需要新的 API Key 格式才能完全运作。使用旧版 API Key 时，操作者信息可能受限或不可用。
</Warning>

* **旧版 API Key**：使用旧版 API Key 创建的 Task 可能显示有限的操作者信息
* **系统操作**：某些自动化操作被归属于 `system` 操作者
* **历史数据**：较早的记录可能没有填充操作者信息

***

## 未来增强

一旦新的 API Key 格式普遍可用：

* 所有 API 操作的完整操作者追踪
* 包含操作者信息的增强审计日志
* 列表端点中基于操作者的过滤