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 状态
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 合并修改：

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

​

Work heartbeat 对象

发送 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 队列统计 返回该对象。

字段	类型	说明
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 数

​

相关

云端环境

选择 Agent 运行的容器、网络与依赖。