# 导出全部交付记录


> 执行前先查[操作开放范围与兼容性](/zh/api/compatibility)。

`hbd campaign records pull` 读取一个活动交付到某项订阅的记录。它固定从第一条开始读，订阅的增量读取位置保持原位。活动筛选只会在订阅已授权的范围内缩小结果：收费订阅的范围仍是此前已取得的那一段，读到的始终是已交付记录，而非活动的全部提交。先确认 `hbd --help --json` 列出了这条命令；你的版本没有它时，改用 [HTTP 数据接口](/zh/api/api-data)逐页读取。

## 凭证与第一页

这条命令需要一把对该订阅有数据读取权限的完整组织 API Key，`hbd auth login` 的登录会话会被拒绝。只有 Data 授权的 Key 也可以运行 `hbd capabilities`；它会显示 Campaign API 目录不可用，这对本命令没有影响。按[首次获取已授权数据](/zh/api/api-data)设置 `HB_API_KEY` 和 `HB_SUBSCRIPTION_ID`，再把 Key 只交给这一条命令：

```sh
printf 'Campaign ID: '
read -r HB_CAMPAIGN_ID
HB_API_KEY="$HB_API_KEY" hbd campaign records pull "$HB_CAMPAIGN_ID" \
  --subscription "$HB_SUBSCRIPTION_ID" \
  --limit 5 --json
```

不加 `--all` 时只读一页，并返回 `data.next_cursor`。`--limit` 是每页条数，默认 50，最多 200。命令只接受一个 Campaign ID。

这把 Key 只通过一个订阅读取该活动时，可以不写 `--subscription`：命令会找到这个订阅，在附注里写明用的是哪一个，并在 `data.subscription_id` 中返回。有多个订阅时，命令什么也不读，返回 `SUBSCRIPTION_AMBIGUOUS`；`hbd campaign subscription list <campaign-id>` 按创建时间从新到旧列出它们。带 `--cursor` 续读时，每次都要写明订阅。

## 导出所有页

`--all` 沿游标继续读取，直到服务端报告没有更多记录。把结果写进私有目录：

```sh
HB_EXPORT_DIR="$(mktemp -d)"
printf 'Export directory: %s\n' "$HB_EXPORT_DIR"
HB_API_KEY="$HB_API_KEY" hbd campaign records pull "$HB_CAMPAIGN_ID" \
  --subscription "$HB_SUBSCRIPTION_ID" \
  --limit 200 --all --json > "$HB_EXPORT_DIR/campaign-records.json"
printf 'Exit code: %s\n' "$?"
```

记录在 `data.items`。两项检查都通过，才把这个文件当作完整导出：退出码为 `0`，且 `data.complete` 为 `true`。

| `data` 字段 | 含义 |
| --- | --- |
| `items` | 本次命令读到的记录，顺序与服务端返回一致。 |
| `count` | `items` 中的记录数。 |
| `pages_read` | 本次命令请求的页数。 |
| `has_more` | 命令停止时，服务端是否仍报告还有记录。 |
| `next_cursor` | 之后可以续读的位置，或 `null`。 |
| `complete` | 只有未传 `--cursor`、从第一条读到最后一页时才是 `true`。 |
| `pagination_stop_reason` | `null`，或 `--all` 提前停止的原因。 |

## 每行导出一个 JSON 对象

如果 `hbd campaign records pull --help` 列出 `--jsonl`，可用它将每条交付记录写成标准输出中的一行。把上方导出命令中的 `--json` 换成 `--jsonl`，将输出保存为 `campaign-records.jsonl`。每行字段与 JSON 封套中 `data.items` 的一条记录相同。加 `--quiet` 可隐藏进度计数。

写完记录后，命令会在标准错误输出中写出以 `records-checkpoint ` 开头的一行。解析前缀后的 JSON 对象，可读取 `count`、`pages_read`、`complete`、`has_more`、`next_cursor`、`pagination_stop_reason`、`campaign_id` 和 `subscription_id`。只有退出码为 `0` 且 `complete: true` 时，文件才是完整导出。从 `--cursor` 开始的读取即使到了末页，也只是其中一段。

`--all` 因分页上限或无效游标提前停止时，退出码为 `1`，已读取的记录和部分导出的检查点仍会输出。如果检查点给出游标，用其中的 `next_cursor` 和 `subscription_id` 续读。读取途中发生请求错误时，标准输出为空。请随导出文件保留退出码和检查点。

## 完整结果与部分结果

以下示例使用 `HB_CLI_ENVELOPE_VERSION=v1` 选择旧版 v1 输出。新的默认版本 v2 还会返回顶层 `nextAction` 字段。示例省略了 `data.items`、`context` 和 `notices`，标识符仅供示意。

```json
{
  "apiVersion": "humanbased.cli/v1",
  "command": "campaign.records.pull",
  "requestId": "e9dc2862-d165-44ce-b54a-42111284bd40",
  "context": {
    "profile": null,
    "apiOrigin": "https://api.humanbased.ai",
    "organizationId": "10571000020000000001"
  },
  "data": {
    "subscription_id": "784210003001",
    "campaign_id": "784210001001",
    "count": 1342,
    "pages_read": 7,
    "has_more": false,
    "next_cursor": null,
    "complete": true,
    "pagination_stop_reason": null
  },
  "notices": [],
  "error": null
}
```

部分导出以 `1` 退出。文件里仍保留已读到的记录，并说明停在哪里：

```json
{
  "apiVersion": "humanbased.cli/v1",
  "command": "campaign.records.pull",
  "requestId": "e9dc2862-d165-44ce-b54a-42111284bd40",
  "context": {
    "profile": null,
    "apiOrigin": "https://api.humanbased.ai",
    "organizationId": "10571000020000000001"
  },
  "data": {
    "subscription_id": "784210003001",
    "campaign_id": "784210001001",
    "count": 100000,
    "pages_read": 500,
    "has_more": true,
    "next_cursor": "example-opaque-cursor",
    "complete": false,
    "pagination_stop_reason": "item_limit"
  },
  "notices": [],
  "error": {
    "code": "PAGINATION_INCOMPLETE",
    "httpStatus": null,
    "message": "The --all walk stopped while the server still reported more pages. The partial data and a continuation cursor, when available, are included.",
    "retryable": false,
    "nextAction": null,
    "details": null
  }
}
```

| `pagination_stop_reason` | 发生了什么 | 你现在做什么 |
| --- | --- | --- |
| `page_limit` | 命令已读 1,000 页。按默认每页 50 条，就是 50,000 条记录。 | 从 `next_cursor` 续读。加 `--limit 200` 可让单次命令读到更多记录。 |
| `item_limit` | 命令已读 100,000 条记录。 | 从 `next_cursor` 续读。 |
| `missing_cursor` | 服务端报告还有记录，却没有返回游标。 | `next_cursor` 为 `null`，这个文件没有安全的续读位置。保留它供排查，再从第一条重新导出。 |
| `repeated_cursor` | 服务端返回了本次命令已经用过的游标。 | `next_cursor` 为 `null`。重复的游标只会回到同一页，请从第一条或你此前保存的更早游标重新导出；再次出现时联系 [support@humanbased.ai](mailto:support@humanbased.ai)。 |

## 续读部分导出

只有 `data.next_cursor` 是字符串时才续读。复制它的值，去掉 JSON 引号：

```sh
printf 'Part number, 2 for the first continuation: '
read -r HB_PART
printf 'Next cursor: '
read -r HB_CURSOR
HB_API_KEY="$HB_API_KEY" hbd campaign records pull "$HB_CAMPAIGN_ID" \
  --subscription "$HB_SUBSCRIPTION_ID" \
  --cursor "$HB_CURSOR" \
  --limit 200 --all --json > "$HB_EXPORT_DIR/campaign-records-$HB_PART.json"
printf 'Exit code: %s\n' "$?"
```

一次运行最多读取 100,000 条记录，较大的导出需要续读多次。每次续读保存为单独的文件：第 2 部分、第 3 部分，依此类推。续读结果覆盖了之前的文件，那一部分记录就丢失了。

续读文件只包含游标之后的记录。即使它读到最后一页并以 `0` 退出，`data.complete` 仍是 `false`。完整导出等于第一个文件的 `data.items` 依次接上每个续读文件的 `data.items`，各次命令使用同一个活动和订阅。

## 保护输出

| 导出的哪一部分 | 对你意味着什么 |
| --- | --- |
| 记录内容 | `data.items[].data` 按交付时的原样写出，外形像凭证的值也照样保留。按源数据的要求保管这个文件。 |
| 数字 | 记录内容里的数字保留原有位数，包括超出 JavaScript 安全整数范围的整数和长小数。数值需要这种精度时，用能保留它的解析器读取。 |
| 临时文件 | 读取期间，CLI 把记录暂存在系统临时目录里仅当前用户可读的文件中，命令结束时删除。请在那里留出整份导出所需的空间。 |
| 输出中断 | 管道关闭或目标位置写满时，命令以非零退出码结束，并在标准错误输出报告原因。已经写出一部分的 JSON 文件是残缺的：丢弃它，重新导出。 |

## 错误

| 退出码与 `error.code` | 原因 | 你现在做什么 |
| --- | --- | --- |
| `1`，`PAGINATION_INCOMPLETE` | `--all` 在还有记录时停止。 | 查看 `data.pagination_stop_reason`，按上文续读。 |
| `2`，`INVALID_ARGUMENT` | Campaign ID 为空或是逗号分隔的列表，某个 ID、游标外形像凭证，或带了 `--cursor` 却没写 `--subscription`。请求没有发出。 | 只传一个 Campaign ID 和真实的标识符。Key 只通过 `HB_API_KEY` 或 `--token-stdin` 提供。 |
| `2`，`SUBSCRIPTION_AMBIGUOUS` | 没写 `--subscription`，而这把 Key 通过多个订阅读取该活动。没有读取任何记录。 | 用 `hbd campaign subscription list <campaign-id>` 选定一个，再用 `--subscription` 传入。 |
| `3` | 没有可用凭证：Key 缺失、格式有误、过期或已撤销，或者用了登录会话。 | 提供完整的组织 API Key。 |
| `4` | Key 没有数据读取权限，或订阅在它的范围或组织之外。 | 按[创建和使用 API Key](/zh/api/api-auth)检查 Key 的 Data 授权。 |
| `4`，`SUBSCRIPTION_NOT_BOUND` | 没写 `--subscription`，而这把 Key 不通过任何订阅读取该活动。没有读取任何记录。 | 核对 Campaign ID。本组织自己的活动，可在 **Campaign access**（活动访问权限）中选中它，创建一把 Key。 |
| `6` | 服务暂时不可用，或输出没有送达。 | 重新执行同一条命令；从头读取既不计费，也不移动读取位置。 |

接口操作和权限见 [Campaign API](/zh/api/campaign-api)。把一次限定范围的读取交给智能体，见[通过智能体使用 Humanbased](/zh/api/agent-access)。
