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

# Work 数据结构

> 自托管 work item、heartbeat 和队列统计的数据结构。

Work API 用于连接 `self_hosted` Environment 的外部 worker。worker 通过 poll 获取 Session work，ack 确认执行，heartbeat 维持租约，并在完成或需要中止时 stop。

## Work item 对象

list、poll、get、update metadata、ack 和 stop 接口都会返回该对象。

| 字段                    | 类型           | 说明                                                 |
| --------------------- | ------------ | -------------------------------------------------- |
| `id`                  | string       | Work item ID，前缀为 `work_`                           |
| `type`                | string       | 固定为 `"work"`                                       |
| `environment_id`      | string       | Environment ID，前缀为 `env_`                          |
| `data`                | object       | Work payload 描述                                    |
| `data.type`           | string       | 当前固定为 `"session"`                                  |
| `data.id`             | string       | Session ID，前缀为 `sess_`                             |
| `state`               | string       | Work item 状态，见 [Work 状态](#work-状态)                 |
| `created_at`          | string       | 创建时间，UTC                                           |
| `acknowledged_at`     | string\|null | worker ack 的时间；未 ack 时为 `null`                     |
| `started_at`          | string\|null | 第一次 heartbeat 将 item 推进到 `active` 的时间；未开始时为 `null` |
| `latest_heartbeat_at` | string\|null | 最近一次 heartbeat 时间；首次 heartbeat 前为 `null`           |
| `stop_requested_at`   | string\|null | graceful stop 请求时间；未请求时为 `null`                    |
| `stopped_at`          | string\|null | 到达 `stopped` 的时间；仍 live 时为 `null`                  |
| `metadata`            | object       | 与 work item 关联的仅字符串 metadata                       |

## Work 状态

| 状态         | 说明                                        |
| ---------- | ----------------------------------------- |
| `queued`   | work item 可被 poll；或已投递但尚未 ack             |
| `starting` | worker 已 ack，应开始执行                        |
| `active`   | worker 已发送 heartbeat，并持有当前 lease          |
| `stopping` | 已请求 graceful stop；worker 应 drain 并确认 stop |
| `stopped`  | item 已不再 live，不能再 heartbeat               |

## Work metadata

Work metadata 是仅字符串 map。Session 创建 work item 时，Session metadata 会被投影到该字符串 map。使用 [更新 work item metadata](/zh/cloud-agents/api/environments/work/update-metadata) 合并修改：

* 字符串值表示 upsert key。
* `null` 表示删除 key。
* 省略 `metadata` 会保留当前 metadata 不变。

## Work heartbeat 对象

[发送 work heartbeat](/zh/cloud-agents/api/environments/work/heartbeat) 返回该对象。

| 字段               | 类型      | 说明                          |
| ---------------- | ------- | --------------------------- |
| `type`           | string  | 固定为 `"work_heartbeat"`      |
| `last_heartbeat` | string  | 服务端接受 heartbeat 的时间戳        |
| `lease_extended` | boolean | 成功 heartbeat 时固定为 `true`    |
| `state`          | string  | heartbeat 后的当前 work item 状态 |
| `ttl_seconds`    | integer | 当前 lease TTL，单位秒            |

## Work queue stats 对象

[获取 work 队列统计](/zh/cloud-agents/api/environments/work/stats) 返回该对象。

| 字段                 | 类型           | 说明                                                   |
| ------------------ | ------------ | ---------------------------------------------------- |
| `type`             | string       | 固定为 `"work_queue_stats"`                             |
| `depth`            | integer      | 当前可被 worker claim 的 queued item 数                    |
| `pending`          | integer      | 最近已投递但尚未 ack 的 queued item 数                         |
| `oldest_queued_at` | string\|null | 最早 queued item 的创建时间；队列为空时为 `null`                   |
| `workers_polling`  | integer      | 最近 30 秒内携带 `Worker-ID` 轮询过该 Environment 的不同 worker 数 |

## 相关

<CardGroup cols={2}>
  <Card title="云端环境" icon="server" href="/zh/cloud-agents/environments">
    选择 Agent 运行的容器、网络与依赖。
  </Card>
</CardGroup>