Smith API：Evaluator、实验视图、Prompt 优化与 Playground 配置

这组 API 覆盖四个层面：定义自动 evaluator、触发实验评估、配置实验 UI、管理 prompt 优化作业与模型连接设置。它们共享同一评估链路，但生命周期和权限边界不同，不能合成一个“评估配置”对象。

Evaluator 资源

平台 evaluator 支持 LLM 和 code 两类。创建请求包含统一的 name/type，再携带对应的 llm_evaluator 或 code_evaluator 配置。响应会包含 feedback keys、creator、run rules、子配置、租户与时间戳；is_managed 标识 LangChain 管理的 evaluator，目前文档举例为 Perceived Error judge。

列表可按 type、名称/creator 子串、tag value、feedback key 和 resource ID 过滤，offset/limit 最大 100，并支持排序。读取单个 evaluator 会内嵌 run rules，因此删除前应先判断依赖。

删除有两种策略：

默认删除若仍被 run rule 引用，可能返回 409；
delete_run_rules=true 先删除同租户的全部引用规则，再删 evaluator。

后者是级联破坏性操作，应先列出关联规则并要求明确确认。批量删除返回 succeeded/failed 每项结果，不可只判断顶层 200。

更新可以修改 name 以及 LLM/code 配置。类型切换是否允许、嵌套配置是 patch 还是 replacement，文档未给足语义；客户端应保留 read-modify-write 契约测试，禁止发送与 type 不匹配的两个子对象。

成本查询

spend 接口返回指定 7 天窗口内按天的 LLM evaluator 成本。period_start 必填，而且以下四者必须恰好一个：

group_by；
evaluator_id；
session_id；
dataset_id。

group_by 可选 evaluator、resource 或 run_rule；只有 group 模式才允许 resource ID、type、feedback key 等进一步过滤。成本告警应基于服务端日期边界，避免把本地时区自然周误当 API 的固定 7 天窗口。

触发一次性实验评估

POST /runs/experiments/{experiment_id}/evaluate 用 rule_id 对既有 experiment 立即执行评估，并按批处理 runs。它是异步成本/吞吐风险入口：

先固定 experiment 和 evaluator/rule 版本；
对大 experiment 设置并发与预算；
防止用户重复点击造成重复评分；
以 run/evaluation 状态追踪完成，不以 HTTP 200 当全部评估完成。

实验视图覆盖

每个 Dataset 可配置 experiment view 的列显示。列名必须以前缀之一开头：inputs、outputs、reference_outputs、feedback、metrics、attachments、metadata。每项可设置：

数值颜色梯度；
1 到 6 位小数精度；
hide 可见性。

一次配置 1–50 个 column overrides；同 Dataset 已存在时 create 返回 409。PATCH 是完整替换全部列配置，不是逐列合并。因此 UI 保存时必须带上完整期望状态；多个管理员并发编辑需要 ETag/版本或客户端冲突检查。DELETE 永久移除配置并恢复默认显示，但不删除实验数据。

视图颜色只是展示，不改变 metric 数值。颜色梯度要考虑色盲、空值、异常值和反向指标，不能让红绿视觉成为唯一质量判断。

Prompt 优化作业

Optimization Job 挂在 prompt repo 下，包含 algorithm、Promptim/Demo config、status、results 和 timestamps。API 覆盖创建、列表、读取、更新、删除，以及 job log 的创建/列表/读取/删除。

更新只接受 status 和一个 result，文档称“replace existing job”，调用方不能假设是 append；多 worker 写结果时需要唯一 job owner 或乐观并发。日志包含 type、message 和任意 data，可能泄露 prompt、example 或模型响应，必须在写入前做 secrets/PII 过滤。

路径模板带 {owner}/{repo}，但部分自动生成页面的 parameter 表没有列出 owner，或只列 repo/job ID。这是 OpenAPI 文档映射不一致，不代表 owner 可省略；应以实际路径参数和当前 SDK 为准。

删除 job/log 是不可逆控制面操作。状态机至少应限制 terminal job 被重新标为 running，并让取消、失败、成功都可审计。

Playground Settings

Settings 可以是 complex 或 simple，scope 是 workspace 或 organization；响应还控制配置是否出现在 playground、evaluators、agent builder、Polly 与 insights 等产品入口。

配置可含 OAuth：token URL、client ID、client secret、token endpoint auth method、params 和 headers。这里的 oauth_client_secret 是高敏感字段：

不应写入 Obsidian、普通日志、前端状态或错误报告；
API 响应即使包含字段，也不能默认会遮罩；
organization scope 会扩大爆炸半径，需单独审批；
token URL 必须做 SSRF allowlist、TLS 与 DNS 重绑定防护；
更新时避免空字符串覆盖已有 secret。

settings 本身是自由对象，创建前用 provider-specific schema 校验。可用范围的 flags 应从默认拒绝开始，再按功能开启；删除前检查是否仍被 evaluator/agent builder 使用。

资源	版本/审计重点	主要风险
Evaluator	配置、feedback key、run rules	级联删除、模型成本、代码执行
Experiment evaluation	experiment + rule 快照	重复运行、批量成本
View override	Dataset 级完整 replacement	并发覆盖、误导性可视化
Optimization job	状态、结果、日志	多 worker 竞态、敏感日志
Playground settings	scope、provider/OAuth 配置	secret 泄露、SSRF、过宽可用范围

上线检查

evaluator 先在小 Dataset 做 golden test，再挂 run rule。
为 LLM evaluator 设置每日成本阈值和失败降级；code evaluator 必须沙箱化。
一次性 experiment 评估带幂等键和明确预算。
视图 PATCH 先 GET 合并并检测并发版本。
optimization job 只允许受控 worker 更新状态/日志。
Playground OAuth secret 进入专用 secret store，任何 GET 响应都做脱敏测试。

Dataset 固定版本的原因见 01-Dataset版本实验共享与导入导出；Prompt repo、commit 和 webhook 见 05-Prompt-Hub版本Webhook与公开分享边界。