Smith API：Annotation Queue 审核调度与状态机

Annotation Queue 是把 trace/run/thread 送入人工评价的工作队列，不只是一个 ID 列表。它包含队列配置、item、reviewer、reservation、每位 reviewer 的 status、位置和归档状态。正确实现必须把“项目是否已完成全部审核”与“当前审核人是否已完成”分开。

两代路由与统一概念

API 文档同时存在连字符路径 annotation-queues 和下划线路径 annotation_queues：

连字符组主要是传统 run-centric CRUD、populate、resolve、统计和导出；
下划线组提供新的通用 item/reviewer/status/placement 接口；
新 item 类型覆盖 RUN 与 THREAD，一次最多 100 项；
旧的按 key 加 run 端点要求 self-hosted LangSmith >=0.16。

不要依据路径拼写推断可互换。SDK 封装层应显式映射两组端点，并用契约测试锁定部署版本。

队列配置

创建队列可设置：

名称、描述、队列类型（single 或 pairwise）；
每个 item 所需 reviewer 数，默认 1；
是否启用 reservation，默认启用；
reservation 分钟数，最小 1；
reviewer access mode 与 reviewer 列表；
default dataset、rubric、预置 session IDs、metadata。

所需 reviewer 数决定真正完成条件。配置从 1 改为 2 时，要评估已有 item 的状态如何迁移；不能只改 UI。reservation 是并发租约而不是永久所有权，消费者要能处理超时、续租失败和另一 reviewer 接管。

入队

传统接口支持按 run IDs 入队、按 key 入队、populate 和删除 run；新接口接受通用 items：

RUN：需要 run_id，或可使用 suggested example 相关信息；
THREAD：需要 thread/project 上下文；
一批最多 100；
reviewer 的 add/remove 是幂等操作。

入队服务应使用业务幂等键，防止网络重试重复产生 item。先验证所有资源属于同一 workspace；对部分失败响应逐项落账，不把 HTTP 2xx 简化成“全部成功”。

状态机

可以把每位 reviewer 的工作理解为：

可见/未领取 -> 已预约 -> 审核中 -> 已提交状态
                    \-> 租约过期 -> 可重新领取

item 的全局归档发生在所有审核要求满足后。archived 并不等于“当前 reviewer 已完成”，反过来也一样。identity status 端点和通用 item status 端点记录的是 reviewer 维度；给 status 传 null 会让该 item 对此 reviewer 重新出现，这是明确的重开语义，不应被当成无操作。

resolve/run update 是业务状态改变，调用方要携带当前版本/placement 信息并在 409 或排序变化时重新读取，避免陈旧页面覆盖他人结果。

读取、排序与游标

队列读取覆盖：

按 ID 获取队列、列出队列、查某 run 所在队列；
获取单个 run/item；
按状态、reviewer 等条件分页列 items；
placement 解析 item 所处 section/position；
active、archived、total size 与分桶 count；
archived runs 导出。

新 item 列表支持前向/后向 cursor，单页最大 100。返回的列表对象偏 metadata，详细 trace 内容可能需另行读取。位置在并发插入、删除、归档后会变化，不能当稳定主键；稳定引用必须用 item ID。

删除与部分成功

队列、runs 和 items 都有单/批量删除。批量队列删除最多 100 个，并明确支持 200 全成功或 207 部分成功。批量 run 删除请求可表达：

delete_all；
精确 run_ids；
exclude_run_ids。

delete_all + exclude 是高风险组合。服务端调用前应展示解析后的数量并要求高权限确认；审计中保存过滤条件、排除集合和逐项结果。删除 item 不等于删除原始 trace/run，也不自动撤销已经写出的 feedback。

Reviewer 生命周期

添加/移除 reviewer 是幂等的，但移除 reviewer 前要判断：

已完成审核是否保留；
其 reservation 是否释放；
每 item 所需人数是否仍可满足；
未完成 items 是否需要重新分配。

最小权限应让 reviewer 只能读其被授权队列和必要 trace 数据；队列管理员、审核人和数据集管理员不应默认合并为一个角色。

典型消费循环

以 reviewer identity 列出可处理 item。
领取或确认 reservation，并记录到期时间。
按 item 类型读取 RUN/THREAD 所需最小数据。
写 feedback/rubric 结果。
更新 reviewer status。
再读 item，确认是否达到全局 archived 条件。
游标前进；若页面变动则从服务返回 cursor 恢复。

状态写入和 feedback 写入可能不是同一事务。客户端需要可重复提交的幂等键与补偿扫描，避免“有反馈但状态未完成”或“状态完成但反馈缺失”。

运营指标

至少监控：待审核数、已预约数、超时租约、按 reviewer 吞吐、归档率、重开率、队列等待时长、207 部分失败数和孤儿 feedback。size、total size、archived total 含义不同，仪表盘要标出统计口径。

安全清单

人工页面把 trace 内容视为不可信输入，禁止渲染可执行 HTML/链接。
reviewer 不能因拿到 item ID 越权读取其他 workspace 的 run。
导出 archived runs 前做 PII/秘密扫描并限制下载寿命。
reservation 超时使用服务端时间；不要依赖浏览器本地时钟。
自动 populate 要有速率、成本与采样上限，防止一次查询灌满队列。

Evaluator 和实验自动评分见 04-Evaluator实验视图优化与Playground配置；人工结果回写的 feedback/traces 端点在 Smith API Traces 专题中展开。