让 Agent 评测结果值得相信

Agent 评测框架最危险的失败不是“跑不起来”，而是顺利产出一个看似精确、实际不可比较的分数。可信框架至少要把以下对象分开：

冻结 Dataset / Fixture
→ 被测 Agent 与隔离 Environment
→ Trial 的 Outcome + Trajectory
→ 确定性 / 模型 / 人工 Grader
→ Experiment 聚合与比较

Anthropic 将 task、trial、grader、transcript、outcome 和 harness 分开定义，并强调 Agent 声称完成不等于环境中的目标状态真的成立。Demystifying evals for AI agents

单元测试、端到端测试与 Agent 评测的关系

结果判定可以共用代码断言。单元、集成和端到端描述被测边界；Agent 评测关注模型与执行系统在任务上的能力、质量和稳定性，两种分类可以重叠。代码评分器只是判卷方式，使用 LLM Judge 也不是评测成立的必要条件。LangSmith 评测类型与评分器

以“把确认按钮改成蓝色，其他按钮不变”为例：

前两类的结果检查可以成为第三类的 Grader。固定模拟模型输出适合验证解析、执行和回传契约，但不能据此估计真实模型完成任务的能力。反过来，Agent 也可以只评测一个小组件，不必每次都覆盖整条用户链路；关键是声明实际被测范围。

Jest、Vitest 或 pytest 都可以承载模型评测，不需要为了命名为 eval 就重写运行器。LangSmith 官方直接提供 Vitest/Jest 集成，允许在测试用例中调用模型、执行断言并记录实验结果。用 Vitest/Jest 运行评测

数据集、多次 Trial、实验对照和轨迹诊断用于回答跨任务的能力与稳定性问题；管理页面、数据库和归档属于运行便利性。可检查的结果仍应优先用代码断言，并明确断言覆盖的是结构、渲染、交互还是持久化；结构字段正确不能自动证明其余层次正确。多次运行的解释见下文“多次 Trial 的默认值属于评测标准”。

评测价值与研发、测试的分工

评测是否有价值、由谁维护、是否需要自建平台，是三个独立问题。能力评测用于发现 Agent 尚不能稳定完成的任务；回归评测用于检查已有能力是否退化。随着能力改善，同一批任务可以从能力探索转为持续回归。二者都属于测试活动，不存在“用了模型评分就只能由研发负责”的技术边界。Anthropic 对能力评测与回归评测的区分

以下是协作设计建议，不是固定的岗位规范：

• Agent 研发：提出模型、提示词、检索和工具编排的改进假设，保证被测执行与真实系统的相关行为一致，分析失败轨迹并验证修复。
• 测试/质量团队：可以牵头评测工程，组织场景覆盖、异常和边界用例、独立验收与持续回归；也可以承担运行器和自动化建设。
• 产品与领域专家：共同定义任务成功条件、核验参考事实，抽样校准模型评分与实际用户判断。

分工应保证研发能在修改过程中直接运行评测，同时保留独立质量判断。共享案例、执行记录和评分协议可以减少两套系统的重复维护；团队名称不决定技术能力。Anthropic 报告的实践是专门团队维护核心评测基础设施，领域专家与产品团队贡献任务并自行运行；这是可参考的组织方式，并非通用强制标准。评测长期维护与所有权

职责落地时，还应分别约定用例数据维护、评测运行、框架扩展与被测业务实现的修改权限。若已有配置能表达输入、参考事实和验收条件，维护这些数据不要求修改 Agent 实现；新增评分机制或执行适配才需要代码变更。本地源码运行方式需要取得源码和配齐依赖，但获取、运行代码不等于拥有向共享仓库推送或合并的权限。若希望使用者完全不接触源码，则需另行提供可运行交付物或托管入口；已有报告查看页不能自动承担用例管理和任务执行。这是配置与执行接口分离的架构建议，具体权限和交付能力必须以实际实现为准。

评价投入时，应追踪评测实际支持了什么决定，例如拒绝了一次有退化的模型替换、定位了可修复的失败模式，或缩短了重复验收时间。已经实现批量运行、报告页面和评分器，只能证明具备评测设施，不能单独证明题集代表真实需求、评分经过校准或业务效果改善。可先围绕一次具体改动，用相同任务和评分口径比较前后结果，复核成功、失败及争议样本；再根据实际收益决定是否扩大平台投入。这是基于评测反馈闭环的工程建议，不是已测得的收益承诺。评测价值、评分校准及人工检查

本节于 2026-10-20 对照上述一手资料核验；岗位分工和投入评估方法属于设计建议。

从线上记录构建评测集

线上日志提供真实需求和失败线索，不能直接充当标准答案。先识别值得覆盖的任务，再核验参考事实、初始状态和通过条件；历史模型回复只能作为待核验的证据。LangSmith 区分没有参考答案的生产轨迹与经过整理的离线数据集，并把生产反馈转为离线案例作为持续改进流程。Evaluation concepts

筛选时同时覆盖常见需求、真实失败和行为边界，例如“应该调用工具”与“不应该调用工具”。不能把低评分、转人工或执行完成直接等同于任务失败或正确；这些信号用于选样，质量结论仍需结合任务和结果核验。用户反馈具有稀疏、自选择的特点，单靠反馈样本不能代表全部流量。Anthropic 的任务收集、平衡题集与反馈局限

实际整理时，可先导出每个会话一行的候选索引，再按选定会话提取有序消息，保留澄清、短确认和纠错上下文。构造某一轮任务时，只把该轮之前必要的信息作为输入，当前轮历史答案及后续纠错用于标注，不提前交给被测 Agent。这是根据“参考输出仅供评分、不能传入应用”的边界得到的整理建议；对于修改环境的任务，还要单独核验初始状态，不能用事后的最终状态冒充历史起点。输入与参考输出的边界

本节于 2026-10-15 核对上述官方文档；数据导出顺序属于实施建议，不表示任何具体日志系统已经保存了完整环境快照。

给已有 Trace 评分，与重新运行 Agent 的区别

已有 Trace 可以作为评测输入。只要提供任务、评分标准和足够的执行证据，就可以对已发生的运行做代码检查、模型评分或人工评价，不必为了评分重新执行 Agent。Langfuse 支持对生产记录中的操作进行评价，也支持对实验结果评分；当前 observation 评价默认只读取匹配记录，不能假定会自动带上同一 Trace 中所有子记录。Langfuse LLM-as-a-Judge

关键是记录里保存了什么，而不只是它叫 Trace 还是 Evidence。只有“请求更新状态”的工具参数，不能证明更新成功；如果 Trace 同时保存了可信的执行回执和任务结束时的实际状态，也可以据此检查结果。结果状态与运行过程的区别参见下文“先验证 Outcome，再限制路径”。

已经发生的运行不会因为修改 Agent 代码而变化，重新给旧 Trace 打分不能验证新代码效果。反过来，如果只是修正评分标准，重新执行全部任务会引入新的随机输出；优先在已有充分证据上重新评分，更便于检查评分规则本身的变化。重新评分无法恢复原记录没有保存的事实。

设计上可以让“执行新任务”和“导入已有记录”共用一套评分接口：前者负责运行并采集，后者负责整理任务、结果和来源信息，评分层只读取统一的证据与标准。这里是架构建议，不能据此认定任意平台已有导入适配，也不能假定相同材料一定得到相同模型分数。

证据采集也可以成为真实执行链路的公共能力：由工具执行器或环境读取器记录实际输入、回执和结果状态，线上运行与离线实验消费同一份事实。Evidence 可以只是 Trace 的结构化投影，不必另建一套独立采集逻辑。评分标准和参考答案仍由评分侧提供；不能把 Agent 自述的成功当作环境事实，也不能为了记录证据把参考答案传入被测 Agent。这是职责划分建议，不要求把所有大对象重复写入每个 span。

以 Trace 为评分输入时，需要明确证据何时完整以及 Judge 实际读取什么。异步导出可能尚未完成，不能在第一条模型输出到达时就认定整次任务已经可评分；短进程退出前还需完成 flush。多阶段任务应按执行身份关联所需记录，再检查终态证据。Langfuse 当前 observation evaluator 只读取匹配 observation 的字段，即使匹配 root 也不会自动读到子记录；可以在 root 写入所需上下文，或由外部适配器汇集证据。这里的完成条件与汇集方案属于设计建议，异步导出和字段读取边界于 2026-10-22 对照官方文档核验。Trace 导出机制、Evaluator 数据范围

本节于 2026-10-21 对照官方文档核验；数据源与执行入口的拆分属于设计分析。

Langfuse 中同一用例的多次执行与 Trace 导出

完整记录业务证据、为运行建立用例身份，以及执行新任务是三件事。增加 Trace 字段能改善评分输入，但不会自动建立实验关系或恢复任务初始环境。Langfuse 可用 DatasetItem 表示稳定用例、用 Experiment 表示一次实验，并通过运行条目关联用例与 Trace；实验 SDK 也允许传入本地 task 函数执行应用。因此同一用例跨不同实验的结果可以关联，并非只能记录临时对话。实验数据模型、实验 SDK

需要区分跨实验复测和单次实验内重复尝试：截至 2026-10-21，官方数据模型明确假设一个 DatasetItem 在一次 Experiment 中只出现一次，读取最多呈现一条对应的实验条目。需要每题运行 K 次时，可拆分实验或另建 Trial 标识与聚合逻辑；自定义 Trace 能保存多次执行，不代表原生实验统计已经正确识别这些重复尝试。重复运行限制

导出也不要求重新执行 Agent。当前官方 API 支持读取实验条目的输入、输出、参考输出、元数据和评分，再根据 traceId 读取对应 observations，整理为外部评分所需的执行记录。v4 的 observations 查询返回行，需要分页并按 Trace、父子关系和执行身份组装，不能把列表摘要直接当成完整证据。读取接口、SDK 和部署版本必须匹配；不能因为最新文档有 v4 API，就认定内部旧部署已能调用。完整日志也不能代替稳定的环境快照或保证确定性重放。实验与观测查询

执行状态和质量结论必须正交

一次 Trial 至少要区分：

超时和取消不能共用“signal 已 aborted”这一条判断。应分别保留 timeout controller 与 outer cancellation，并用硬截止包装 Trial；AbortSignal 只提供协作式取消，被调代码忽略 signal 时不会自动停止 Promise。超过截止时间的迟到成功也不能继续评分。

聚合结果同时报告 attempted、valid、timeout、infra error 和 cancelled。否则一个全部超时、但 infra error 计数为零的实验可能被错误标记为“有效”。

先验证 Outcome，再限制路径

工具 Agent 可能通过不同合法路径完成同一目标。优先检查最终业务状态，只把权限、安全和不可绕过的流程约束写成 trajectory/tool policy。τ-bench 也通过对话结束后的数据库状态与目标状态比较来判断成功。τ-bench

参考轨迹是一个可接受解的示例，不自动代表唯一正确解。把工具序列的编辑距离、调用次数或完整顺序直接作为通过门槛，可能惩罚额外核验、不同检索顺序和其他合法实现。Anthropic 明确提醒，过度限定工具步骤会产生脆弱评测，应优先评估产出；过程约束则需要由任务契约证明其必要性。Agent 评分器设计

路径匹配的严格程度应随问题变化。LangSmith 提供以下模式，而不是要求所有任务匹配完整标准轨迹：Trajectory evaluations。

因此，借鉴其他项目的评测时，应分别审查运行与记录机制、任务成功条件、评分证据、路径约束和聚合权重。可以复用代码评分器与模型评分器的组合，但具体业务的确认要求、技能加载协议和权重需要重新论证。工具名称与调用数量无法单独证明参数正确或结果落地；效率指标也不能替代结果验收。这是基于上述官方资料的设计建议，本段于 2026-10-16 核验。

Graph 评测与浏览器端到端测试不是替代关系

浏览器脚本适合验证“用户能否在页面上完成一次真实操作”：登录、请求发出、SSE 是否被渲染、动作是否由前端执行、画布/DOM 是否更新、保存或发布是否成功。Graph 或协议级 Target 则直接构造生产 Graph 的输入，收集工具调用与终态，再在隔离环境中执行其动作协议。其执行环境也可以是真实浏览器，因此“从 Graph 入口评测”与“使用浏览器”并不互斥；下面对照特指纯协议执行环境与完整用户入口。

若业务语义能由纯协议环境可靠承载，常见的组合是：多数 Case 用协议级 Target 评估 Agent 本身；每个重要入口再保留少量浏览器 smoke/E2E，用来证明协议在真实 UI 中没有断裂。需要真实渲染或组件 Hook 时，Graph Target 也可以直接使用浏览器执行动作。两者用同一份关键 Case 意图即可，但不必复制整套评分资产。若完整入口 E2E 失败而 Target 通过，优先检查前端执行器、SSE 映射、会话/鉴权、保存链路和环境；Target 失败仍需结合其实际执行环境区分 Agent 问题与资源故障。

浏览器自动化仍需按真实可见性和业务完成状态断言，不能把“元素已在 DOM 中”误当作操作完成；相关等待语义见Playwright：DOM 存在不等于元素可见。Playwright 将其定位为浏览器自动化工具，并提供隔离 Browser Context 的能力；隔离会减少 Cookie 与页面状态互相污染，但不会替代业务数据清理或服务端状态隔离。Playwright BrowserContext

评测保真问题应优先在 Target、Environment 或评测专用 adapter 中解决，不能为了让测试通过而直接改变生产行为。若评测与生产确实需要共享 parser 或执行语义，应把它抽成双方复用、可独立测试的纯契约层，并把生产迁移作为单独评审，而不是隐藏在评测改造中。

Fixture 使用 YAML 还是 JSON 与环境保真是两个问题。人工拼出的“看起来像生产 Schema”的最小对象适合协议单测，但不能代表真实页面分布；生产回归 Fixture 应来自真实对象导出，经过脱敏、人工审核和版本冻结，并记录来源 Schema 与组件目录版本。深层机器快照通常更适合 JSON，Case/Suite 等人工规则则可以继续使用 YAML。Target 回写给生产 Graph 的 diff、resume state 等中间协议也必须做 conformance test；最终页面相似并不能证明中间协议兼容。

工具策略还要区分“尝试调用”和“成功完成”：

• 禁止工具：开始调用就应记录违规。
• 必需工具：只有匹配名称、参数要求且成功结束才算满足。
• 最终结果依赖工具返回值时，Grader 必须看到经过裁剪和脱敏的输出证据，不能只看到工具名。

能由代码确定的事实优先使用确定性 Grader。开放式质量再交给 LLM Judge，并为 Judge 提供 reference facts、Outcome、必要的工具结果和“不足以判断”出口。模型评分具有非确定性，需要定期与领域专家标注校准；Anthropic 同样建议组合代码、模型和人工评分，并校准 LLM-as-judge。

评分标准（rubric）和参考答案（reference answer / expected output）承担不同职责，可以同时提供：标准定义按什么维度、满足到什么程度给分；参考答案提供本题预期的正确内容。参考事实（reference facts）则可把预期内容拆成已核验的关键事实，不要求一段完整示范回答。例如“准确回答且说明前提”是标准，“默认保留 30 天”是本题参考事实。使用 rubric 不自动意味着无参考评分；是否存在参考依据，要看实际传入的答案、事实和任务条件。LangSmith 明确区分 reference-free 与 reference-based LLM-as-judge，且数据集中的 reference outputs 是可选字段、仅供 evaluator 使用。Evaluation concepts

设计建议：事实明确的问答应提供经核验的参考答案或事实，减少 Judge 仅凭自身知识判断；开放式回答可用要点与约束验收；操作型 Agent 还应检查执行后的状态。完整参考答案也不天然要求逐字匹配，应明确接受语义等价的正确回答。只有“准确、完整、有帮助”等泛化标准，而没有可核验的事实或运行证据时，不应把评分当成事实正确性的充分证明。本段的概念区分于 2026-10-16 对照上述官方文档核验，具体组合属于评测设计建议。

评分前要核对 Judge 实际收到的证据，而不仅是完整报告保存了什么。若按序列化后的字符数截断工具结果，包装字段、重复内容和转义也会消耗预算；Agent 已经看到的关键文档段落可能没有传给 Judge，继而被误判为“无依据”。应先提取工具的有效正文，再保留与待核验结论相关的证据；确因裁剪而无法核验时，补充证据或标记该维度无法判断，不能把证据缺失直接等同于模型捏造。2026-10-15 通过完整工具结果与实际评分投影的逐项对照验证这一失配，未改写原实验结果。

脱敏与截断应分别设计。凭据字段可能藏在工具返回的 JSON 字符串中，需先解析有效 JSON 容器再按字段脱敏；解析失败的普通文本应保留，不能被当成空结果。去掉相同消息包装副本可以减小输入体积，而不丢失唯一正文；独有的包装字段与附加产物仍需保留。旧记录已经截掉的内容无法通过增大后续输入预算恢复，需重新采集；保留完整证据后若超出模型上下文，应作为评分资源限制处理，不冒充被测任务失败。2026-10-15 以长文尾部依据、JSON 内凭据、超长容器、不同值包装字段及旧截断标记的聚焦测试验证。

Rubric 的通过条件应对应用户当前轮次的目标。有效澄清不必一次收齐所有潜在诊断字段；回答格式要求也不自动要求完整上传教程。工具参数或交接事件已保存上下文时，不应仅因最终文本没有再复述一次就判定信息丢失。把正确性、安全边界和核心任务设为必要条件，次要完整性或表达质量用于连续评分；父评分项与子维度的 required 组合规则也要核对，避免父项将全部子项都变成硬门槛。校准应保留空回答、答非所问和关键无据结论等负例，不能为了提高通过率统一降低要求。本段是依据评分协议和实际证据复核得到的设计建议，不能替代领域专家对具体答案的判断。

分层权重必须保持语义稳定。若 Criterion 权重为 w，多个 Dimension 的权重应先在 Criterion 内归一化；不能简单为每个 Dimension 都乘 w，否则增加维度数量会悄悄放大整个 Criterion 的总权重。

平均分也必须写清聚合层级。单次 Trial 常用 Σ(value × weight) / Σ(weight)；跨 Trial、跨 Case 时要明确是“每个 Trial 等权”“每个 Case 等权”还是使用业务 Case 权重。Case 的 repetitions 不一致时，直接平均所有 Trial 会让 Trial 更多的 Case 获得更大隐含权重。required 维度失败通常还应独立触发 Trial fail，不能被其他高分抵消；质量门禁也不应只看一个平均分。

同次组合代码与模型评分、自动判定样本通过，以及发布准出是三个层次。前两项已经完成，也不代表发布会被质量失败阻断：如果命令退出码仅反映执行完成和报告保存成功，那么业务样本失败时仍可能成功退出。发布门禁需要明确消费有效样本数、必要条件、通过率或其他质量策略，并把拒绝结论传递给流水线。运行错误和质量拒绝可以使用不同状态，但两者都不能被发布流程当成允许通过。2026-10-21 通过聚合函数的合成输入与退出码控制流核验这一边界；本段为通用设计结论，不代表任意评测平台已经提供发布门禁。

多次 Trial 的默认值属于评测标准

LLM 和 Agent 输出具有随机性。LangSmith 的 repetition 文档也明确把多次运行用于降低高变异系统的噪声，并展示均值和标准差。Evaluate with repetitions

常见指标回答不同问题：

• pass@1：第一次尝试的默认体验。
• pass@k：k 次中至少一次成功，表示“是否有能力做到”。
• pass^k：k 次全部成功，表示“是否稳定可靠”。
• per-case success rate：该任务的经验成功率。

Suite 声明的 repetitions 是考试标准的一部分。CLI 或 UI 若无意中固定发送 1，会把 reliability 回归静默降成 one-shot 测试。界面应继承 Suite 默认值，只在用户明确修改后发送覆盖值，并展示预计 Trial 数、模型调用量和成本。

第一次验证 Harness 时可以维护一个独立的 minimal/sanity Suite：1 个无副作用 Case、1 个 Trial、只使用确定性 Outcome 或 Tool Policy，不调用 Judge。它仍应运行真实 Target，但能用最低成本区分“生产 Graph/模型链路不通”和“Rubric/Judge 配置有问题”。通过后再运行含 Judge 的 smoke 与多 Trial regression。

YAML 和 JSON 是编写体验选择，不是可信边界

人工维护的 Case 常包含长 Prompt、多行 reference facts 和嵌套评分条件。YAML 标点少、支持多行块和注释，代码评审时通常更容易阅读；JSON 语法更严格、生态统一，更适合程序生成、CI 交换和最终报告。

两者不应形成两套领域协议。合理实现是：加载层同时接受需要的文本格式，解析后立即进入同一套 runtime schema 和语义校验；hash 也基于规范化后的领域对象生成。评测可信度来自严格 Schema、引用检查和可复现指纹，而不是文件扩展名。

YAML 作为输入时仍要注意缩进和隐式标量解析，避免依赖容易歧义的裸值。尤其是 plain scalar 中空格后的 # 会开始注释：input: 改成 #FFF 的值可能只剩“改成”。Prompt、颜色值和 reference fact 包含 # 时应加引号或使用 | block；加载器可以拒绝带行内注释的 plain scalar，防止内容被静默截断。JSON 作为人工输入时则要接受更多引号、逗号和多行字符串转义。机器生成的 Experiment 报告通常优先 JSON，减少下游工具的解析差异。

本地离线评测资产通常也不应进入生产部署包。生产构建 smoke 可以验证被测 Graph 的编译产物能加载，但 Dataset、Case 和 Fixture 仍由本地 CLI 从源码资产目录读取；把它们复制进 dist 只会增加包体、扩大信息暴露面，并制造线上运行依赖的错觉。

未发布且可以直接删除的本地调试报告不需要历史兼容层。字段、渲染方式或本地目录仍在快速迭代时，优先清理旧产物并保持单一路径；只有协议已经发布、持久化数据无法迁移，或存在明确外部消费者时，才为旧版本增加解析、推断或动态转换。否则“临时兼容”会持续增加分支、测试面和认知成本。

本地报告要区分机器身份和人类入口

随机 UUID 适合作为 Experiment 的稳定机器标识，却不适合作为唯一目录展示名。输出目录可以使用 时间_场景_Suite_模型_短ID 这类可排序且可检索的名称，同时在 Manifest 内保留完整 ID；不要强迫目录名同时承担所有身份语义。

报告文件也要按读者分层：Manifest 回答“测了什么”，Summary 回答“结果怎样”，逐 Trial 文件保存重证据。若再提供包含全部对象的单文件快照，应明确它服务于传输、compare/export 或归档，并接受与拆分文件的有意冗余。面向人阅读时，可以额外生成 report.md/HTML，避免让使用者从多个 JSON 中自行拼装结论。

静态 HTML 会展示模型输出和工具证据，因此必须把所有动态值当作不可信文本做 HTML 转义，最好配合拒绝脚本和网络资源的 CSP，不直接把原始输出拼成可执行标签。CLI 可以在本地交互式终端自动打开报告，但 CI/非交互环境应只生成文件，并允许显式关闭；浏览器打开失败也不应把已经成功的评测改判为失败。

比较门槛要覆盖所有会改变结果的条件

可比较性检查至少包含：

• Dataset、Case 选择和 Fixture 的内容 hash。
• Grader 实现/版本、Judge 模型、参数和 prompt hash。
• Target adapter、Graph contract、工具/能力快照和隔离环境版本。
• timeout、resume/step 上限、Trial 数及影响结果的并发策略。
• 可恢复的代码或构建产物标识；仅记录 gitDirty: true 不能重建未提交代码。

版本化资产的 Schema 也属于可信边界：顶层和嵌套对象应拒绝未知字段，避免拼错字段后被静默删除并回退默认值；同时在运行前校验 ID 唯一性、长度、引用完整性和持久化约束。Grader 输出同样要做 runtime validation，required score 必须显式给出通过结论，数值与权重必须为有限合法值。

Suite 可以用 Glob 降低持续添加 Case 的维护成本，但 Glob 会让成员集合随目录内容自动变化。可靠实现应限定搜索根目录和扩展名、拒绝路径逃逸、稳定排序、拒绝空匹配与重复命中，并把展开后的相对路径和内容写入 Dataset Hash。小型 smoke/sanity 集合适合显式文件列表；不断增长的 regression 集合更适合显式 Glob，并用 exclude 排除草稿或其他分组。

被测模型或被测实现可以不同，因为这正是比较对象；其余考试条件应固定或显式声明实验目的。只给 adapter 写一个手工版本号、只 hash {id, contract}，都依赖维护者永不忘记 bump，不能称为自动可复现。

比较少量随机 Trial 时，不要把任意非零 delta 直接宣称为稳定回归。至少展示样本数和逐 Trial 结果；更成熟的系统再加入配对设计、置信区间或 bootstrap。

先证明评测内核，再决定是否平台化

评测的最小闭环是 Dataset → Target → Trial → Grader → 本地不可变报告。它本身不要求 Web 页面、HTTP API、数据库、队列或事务。早期先用 CLI 和本地产物验证 Case 是否有效、评分是否可信、真实 Graph 是否能运行，可以显著缩小问题空间，也不会向共享存储写入试验数据。

只有出现多人共享历史、集中调度、超长任务恢复、权限审计或统一配额等明确需求时，才需要增加平台层。平台层应作为 Runner 外部适配器，消费和产出同一份 Experiment 协议，不能把队列与数据库字段反向塞进评测领域模型。

先评估现有平台，再划定自研适配层

LangSmith 不只是 Trace 查看器。Studio 支持连接本地 Agent Server、查看图与中间状态、迭代 Prompt 和运行数据集实验；本地开发服务器支持监测代码变化后重启。Studio、本地 Studio 启动

LangSmith Evaluation 还支持数据集、自定义评分器、并发实验和结果分析。因此，“需要批量运行并打分”本身不足以证明必须自建 Runner、数据管理和实验界面。SDK 评测入口、实验分析

选择已有记录评分或重新执行任务，取决于本次要验证的是评分还是 Agent 行为。不能把评测平台统一描述为“只能上传旧 Trial 打分”：LangSmith SDK 接受被测 target 函数并在评测中调用它，也提供本地 Vitest/Jest 集成。重新运行仍需控制初始状态、资源和评分口径，不能等同于逐步复现旧轨迹。SDK 的 target 与 evaluate、本地测试集成

逐用例自定义验收条件也不是某种自建框架独有的能力。Promptfoo 的每个测试项可以声明自己的断言类型、期望值和 llm-rubric；公共评分机制与逐题标准可以并存。建议统一维度定义、证据要求和判定规则，再让具体任务提供自己的期望结果，避免把“标准化”理解成所有题目共用一句评分提示，也避免在看到结果后随意调整标准。Promptfoo 用例配置

SDK 接受 target 函数和自定义 evaluator；业务系统仍需提供真实输入、状态变更的执行环境和验收逻辑。由此可推导：本地命令或专有评分调用可以封装在自定义 evaluator 内，而业务适配层的存在不意味着必须自建完整平台。具体集成是否可运行仍需做小范围验证，不能把接口可扩展性当成已经完成的集成。

接入成本应按交互协议差异判断，而不是按 Graph 数量判断。输入、输出与中断/恢复协议相同的 Agent，适合复用同一类执行适配器，只提供构造函数、输入映射和结果提取；只改模型、Prompt 或内部节点通常不必重写适配层。全新的业务类型仍要定义环境、执行方式和验收证据，通用运行器不能推断这些业务语义。如果每个同类 Graph 都复制一遍执行循环、错误处理和轨迹整理，应优先参数化这些公共步骤；新任务的用例与预期结果仍需独立设计。注册接口的存在只能证明允许扩展，不能证明扩展成本已经足够低。

选型时分别检查平台可用性、数据传输与访问边界、运行环境和账号成本，再判断通用调度、数据管理与结果展示是否值得维护。功能重叠和领域定制可以同时存在，不宜用“第三方只能看日志”作为自研理由。

评测与被测实现同仓，有利于同步演进和本地调试，但代码位置本身不能证明评测更精细或更客观。精度取决于可控制的输入与环境、可采集的执行证据以及有效的断言；可信度还取决于代表性题集、独立复核和评分校准。迁移通用运行器或报告平台时，这些业务适配通常仍要复用或重新实现，因此应讨论迁移成本和验证边界，而不是声称整套系统永久不可替代。该段是架构建议；本地执行与逐用例配置能力于 2026-10-20 对照上述官方文档核验。

本节依据官方文档核验于 2026-09-10；未执行实际平台接入或上传实验。

托管执行与本地能力的边界

平台是否托管资产、Runner 在哪里执行、由谁提供模型凭据，是三个可以独立选择的维度。用户自配模型解决的是连接与额度归属，其安全和协议约束见用户自带 API Key 的模型接入边界。

建议保留同一评测内核的本地与托管入口：日常回归可在隔离 Worker 上运行冻结的构建产物，本地入口用于当前未提交代码、仅本机可达的服务或交互式登录。若要完全取消本地执行，必须提供受控的代码快照上传或版本构建机制，以及相应的网络和身份访问路径；托管平台不会自动获得用户工作目录和浏览器会话。

DOM、截图和浏览器交互也可以在远端执行，并非天然属于个人电脑。Playwright 官方提供 Docker 与远端运行方式，但访问不可信内容需要考虑用户权限、Chromium sandbox 和系统隔离，不能把浏览器会话分开就当作完成服务器安全隔离。Playwright Docker

页面状态模拟不等于真实渲染。JSDOM 不执行布局或绘制，Node VM 也不是执行不可信脚本的安全沙箱。若评测需要运行组件或生成代码，应按代码信任程度把执行从持有共享凭据的门户进程移出，并限制文件系统、网络和资源；这一部署建议基于下述官方能力边界。JSDOM、Node VM

本节核验日期：2026-09-09；入口拆分与部署方式为架构建议，浏览器、JSDOM 和 VM 的能力边界来自官方文档。

选择长任务平台后才需要数据库级正确性

部署到服务器不会改变 Node.js 的异步并发机制；需要重新确认的是执行环境的生命周期，以及调度与状态的共享范围。

例如 AWS Lambda 可以在一次调用结束后冻结执行环境，未完成的后台进程或回调可能在环境复用时才恢复，因此不能将返回响应等同于后台任务仍受到持续调度。AWS Lambda 执行环境生命周期

多个实例下，A 实例创建的内存任务记录不会自动出现在 B 实例；负载均衡将后续查询分配到 B 时，可能出现“任务不存在”。共享存储应保存任务 ID、归属、状态、进度与取消请求；真正的 AbortController、Promise 和子进程句柄由执行进程持有。实例内部并发上限也不等于集群、用户或模型提供方的总限额。本段为生命周期与状态归属的架构分析，未宣称已完成线上部署验证；核验日期 2026-09-10。

工作台把评测变成长任务后，还要补齐普通 Runner 不负责的边界：

数据库本身可以同时承载运行状态和任务队列，不必为此额外引入消息中间件。任务应从创建时就记录排队、运行、完成、失败或取消状态；仅在成功后写结果记录时，“没有结果”无法区分尚未执行、正在执行和执行失败。状态读取直接查询共享数据库即可；决定谁执行时，还需原子领取与正确的互斥范围。取消请求也可写数据库，由实际执行者读到后实施取消。

• 幂等重放返回同一个 canonical experiment/job ID；随机 ID 不能进入幂等 request hash。
• 进度包含 attempt + 单调 sequence，并用 CAS/条件写避免并发完成导致百分比倒退。
• cancellation 后停止领取新 work item，而不是把剩余队列逐个变成 cancelled Trial。
• Trial 完成后分批、幂等持久化；不要等整个实验结束才一次保存所有结果。
• checkpoint、trajectory 和完整页面/工具证据设置大小上限、脱敏与生命周期。
• 详情列表只返回轻量摘要，单个 Trial 的重证据按需加载。

应用运行账号即使名称包含 rw，也可能只允许对既有表执行 DML，而没有 CREATE/ALTER 权限。部署前应先用只读方式确认目标 schema、目标表是否存在和 SHOW GRANTS，再由独立迁移身份或数据库变更平台执行 DDL。不要打开 ORM synchronize 来绕过权限；MySQL DDL 通常会隐式提交，分多条建表时还要在失败后检查是否留下部分状态。

共享 Job 表中的 tenant/job type 只能提供逻辑隔离，不能提供物理零污染。复用前必须确认完成记录的 retention/cleanup；如果框架只清理锁、不删除终态 Job，评测记录会永久积累。对短期开发可优先使用 CLI + 本地产物；必须有工作台时，再在“共享表 + 明确保留策略”和“专用 Job 表/Schema”之间做显式架构决定。

最小验收清单

发布前至少验证：

1. 从生产构建产物启动并真正解析/加载被测 Target，不能只在 ts-node/Jest alias 环境测试。
2. 超时、用户取消、基础设施错误和 Grader 错误分别落入正确状态。
3. 必需工具调用失败时不会被判为满足。
4. 更换 timeout、resume 上限或 Judge 后，比较会被拒绝。
5. Suite 默认 repetitions 能从资产贯穿 CLI 和 Runner。
6. 本地报告使用不可覆盖的实验目录，并能直接用于 compare/export。
7. 定期抽样阅读失败 trajectory，确认失败来自 Agent 而不是任务、环境或 Grader 缺陷。

如果已经选择平台化，再额外验证幂等键、进度单调性、旧 attempt fencing、增量持久化、证据分页和 retention；这些不是 CLI-only 第一版的发布前提。

LangSmith 将 Dataset、Experiment、Trace 和 Evaluator 分层，并把生产问题回流为离线 Dataset，适合作为持续维护的心智模型参考。Evaluation concepts