Smith API：Example 写入、附件、验证与删除语义

Example 是 Dataset 的版本化记录，通常由 inputs、可选 outputs、metadata、split、来源 run/trace 和附件组成。它既是评估输入，也是 gold/reference output 的载体；写入管道必须把数据契约、来源和删除级别明确分开。

创建与来源复用

单条与 bulk 创建都接受 dataset_id，并可提供：

• inputs、outputs、metadata；
• split，默认 base，也可为多个 split；
• 客户端指定 id 与 created_at；
• source_run_id、session/start time、trace 等来源；
• use_source_run_io 与 use_source_run_attachments；
• use_legacy_message_format。

从 run 复用 I/O 或附件时，来源 run 是数据血缘，不是永久授权。复制前仍要检查目标 Dataset 的敏感级别和保留策略。客户端生成 UUID 可用于幂等，但服务重试必须复用同一个 ID；每次重试生成新 ID 会制造重复样本。

查询与历史快照

单读和列表都支持 as_of，默认 latest。列表最大 100 条，可按 ID、dataset、metadata、全文、split 和服务端 filter 筛选，还支持列选择、顺序和随机种子；count 使用相同过滤维度但不返回对象。

随机抽样若要复现，固定 random_seed，并固定 dataset version。select 应最小化：列表页只读 ID/时间/名称时不要拉完整 inputs、outputs 和附件 URL，既降低成本也减少数据暴露。

两套更新路径

普通 PATCH /examples/{id} 更新 inputs、outputs、metadata、split 和附件操作；overwrite=false 表示调用方必须理解合并语义，不能假设是整对象替换。

旧 bulk PATCH 被官方标为 legacy。涉及附件时，应使用 dataset-scoped 的 multipart 端点：

PATCH /api/v1/platform/datasets/{dataset_id}/examples

multipart 的 part 名以 example ID 为前缀：主 JSON、.inputs、.outputs、.attachments_operations 以及 .attachment.{name}。附件操作支持保留、重命名和新增。动态 part 名很容易在通用 HTTP 客户端里被错误转义，集成测试应覆盖 Unicode 文件名、重复名称、空附件和大文件边界。

上传

平台上传端点用 multipart 一次写入多条 example 和二进制附件，成功返回 as_of、数量与 IDs。CSV 专用旧入口要求 file、input keys，并可提供 output/metadata keys；官方建议非 CSV 使用更高效的平台端点。

上传流程建议：

1. 客户端先做 schema、大小、MIME 与病毒扫描；
2. 调用 validate 或在隔离 Dataset 预导入；
3. 记录请求批次与生成的 as_of；
4. 逐 ID 核对数量和附件；
5. 失败批次不要盲目整批重放，先确认哪些 ID 已落库。

validate 并不等于持久化

单条和 bulk validate 返回规范化的 ExampleValidationResult，但不创建数据。它们适合在正式写入前检查 dataset、I/O、split、来源与 overwrite 参数。API 页面没有展示 request body schema时，客户端生成代码可能产生空 body；应以当前 OpenAPI/SDK 和真实 422 响应验证契约，不能因为文档页只有 response 就假设无需输入。

软删除与硬删除

删除有完全不同的语义：

硬删除最多 1000 个 IDs，且请求中的 hard_delete 当前只接受 true。正文、输出和 metadata 立即清空，但附件文件最多可能需要 7 天才物理删除。因此：

• 合规删除回执应区分“逻辑内容已清空”和“附件物理清理完成”；
• 不应承诺即时彻底删除；
• 删除任务要保存不含原文的 ID 审计、请求时间和复核时间；
• CDN、导出物和下游缓存需要单独处置。

一致性与安全边界

• Dataset 和 Example ID 都要在服务端租户范围内校验，不能相信客户端组合。
• inputs/outputs 可能包含 prompt injection、PII 或密钥；进入人工审核、导出、公开分享前做分类和脱敏。
• 附件 URL 可能是时效签名 URL，不应持久化为永久资源地址。
• 409 要按冲突处理，不能统一当临时网络错误无限重试。
• 更新和删除后以返回的 as_of 或重新读取确认结果；UI 本地状态不能替代服务端事实。

选择接口

Dataset 的版本、导出与分享边界见 01-Dataset版本实验共享与导入导出。