Feedback 数据模型、公开 Token 与保留

Feedback 将人工、应用、模型或自动评估结果关联到 Run/Trace/Project/Thread。它不只是一个分数，还可含结构化 value、评论、correction、比较实验和来源证据。

CRUD 和查询

创建必填 key。页面描述明确 session_id 必填，但当前 JSON Schema 只把 key 标为 required、将 session_id 建模为 nullable；生产 client 应按更严格的文档语义要求 project/session ID，不依赖服务端宽松序列化。

其他字段：score 可为 number/integer/boolean，value 还可为 string/object；可带 comment、correction、run/trace/start time、feedback group/thread、comparative experiment、自定义 ID、source 与 config。source 类型包括 api|model|app|auto_eval，应从已认证调用上下文生成，不相信客户端伪造的 user/source metadata。

列表默认 limit=100, offset=0，可按 run、key、session、source、user、有无 comment/score、level(run|session)、创建时间、feedback thread 和比较实验筛选。include_user_names 会增加身份数据，只在有显式权限的人工审核界面开启。

公开 Feedback Ingest Token

POST /api/v1/feedback/tokens 可一次创建一个或数组 token，每项必填 run_id 和 feedback_key，可用 expires_in 或 expires_at 限时，返回 id/url/expires_at/feedback_key。

持 token 者可无额外认证提交：

• GET /api/v1/feedback/tokens/{token}：score/value/comment/correction 都在 query string；
• POST /api/v1/feedback/tokens/{token}：JSON body，还可带 metadata。

POST 应作为默认；GET 会把用户反馈和 token 暴露到浏览器历史、代理/CDN/服务器日志、Referer 和分析系统。对公开页设 Referrer-Policy: no-referrer，不加第三方脚本，访问日志脱敏 path，限流、限 body 和防自动滥用。

文档没有承诺 token 一次性；不能把“成功提交一次”当作已撤销。使用短 TTL，将 token 绑定单一 run + key，由业务端以稳定 feedback ID/去重规则防重放；管理端只显示元数据，不回显完整 token URL。

Trace 保留的隐性成本

创建和 token 提交的 extend_trace_retention 默认 true。收集大量用户反馈会延长 Trace 保留，同时改变存储成本、数据删除 SLA 和合规范围。产品必须在创建 token 时明确这一决策，不依赖默认值，并将保留政策与用户同意/删除请求联动。

更新、删除和迁移

PATCH 只能修改 score/value/comment/correction/config，不应用它变更 Feedback 归属。并发审核应保存最后读时间/版本并防止后写覆盖；OpenAPI 没有 ETag/条件更新，需由业务层协调。删除前保存不含评论正文的审计信息，并重算相关聚合/规则结果。

/feedback/eager 已 deprecated，它假设 Run 已在数据库可见；新集成统一使用 POST /feedback，老 client 迁移时要验证 ingest 最终一致延迟和重试去重。