Smith API：Dataset 版本、实验、共享与导入导出

Dataset 不是一张可随意覆盖的样本表，而是评估资产的版本边界。它同时承载输入/输出 schema、数据类型、transformations、splits、版本标签、实验关联和分享状态；生产系统应保存 dataset_id + as_of/version tag，不能只保存可变名称。

资源模型

POST /api/v1/datasets 创建数据集，核心字段包括：

读取有三种形态：单个读取、带多条件/分页的列表，以及 JSON Patch 流。流式读取面向大列表和 UI 增量同步，消费者必须按顺序应用 patch，并在断线时从完整快照重新建立状态，不能把 patch 当独立对象缓存。

PATCH /datasets/{dataset_id} 对可选字段区分“未提供”与显式 null。SDK/网关若在序列化时自动补 null，可能无意清空 schema、描述或设置；更新 DTO 应启用 missing-field 语义。

每次样本变化会形成可按时间点观察的数据集状态：

版本 tag 是对历史时间点的命名引用，不是复制一份数据。CI 评估建议固定 tag 或精确时间；若永远使用 latest，基准集漂移会让同一代码版本的结果不可复现。split 更新同样应记录变更审计，避免训练集/测试集串漏。

克隆支持指定源/目标数据集、as_of，并按 example、split 或 tag 选取子集。这适合从只读基准派生实验分支；目标名称与幂等键应由调用方控制，重试前先查询，避免重复克隆。

generate 从既有数据生成合成样本。合成数据必须保留 provenance、生成模型/提示版本与人工抽检结果，不能与人工 gold set 混为一谈。

导入路径包括：

大文件上传要设置大小上限、内容类型校验、超时和失败重试策略；先校验再落正式数据集，避免半成功批次污染版本。

官方接口覆盖 CSV、普通 JSONL、OpenAI Evals JSONL 与 OpenAI fine-tuning JSONL，均可按 as_of 固定版本。注意 JSONL 下载页的描述文字仍写成 CSV，这是文档文本错误；应以端点名、响应 Content-Type 和实际集成测试为准。

导出可能包含输入、参考输出、metadata 与附件引用，属于潜在敏感数据。生产下载要做最小权限、短期存储、访问审计和脱敏，不能把分享 token 或导出链接写进公开日志。

Dataset 是 experiment 的参照轴：

create-comparative-experiment 把多个 experiment 放进同一对比对象；
删除 comparative experiment 只删除对比视图，不应被理解为删除原始 runs；
read-examples-with-runs 把 examples 与实验 runs 对齐；
V2 experiment-runs 接口返回 {items, next_cursor}，默认 20、最大 100，example IDs 上限 1000，experiments 必填；
shared 版本用 share token 读取对应实验数据。

对比必须固定同一 dataset version，并检查每个 example 是否都有候选 run。否则均值可能来自不同样本集合，形成无效排名。

share-dataset 生成公开访问状态，可选 share_projects；read-dataset-share-state 查询当前状态；unshare-dataset 撤销。分享 token 应按 bearer secret 管理：

单删和批量删都是破坏性动作；批量删除最多 100 个 ID。调用方应先解析精确目标、保存审计清单，并把“部分成功”作为可能结果处理。不要用名称模糊匹配后直接删除。