凭据失效或服务挂掉时，及时止损

一批 200 条的评估跑到第 30 条，API Key 过期了。剩下 170 条注定全部失败，却还会一条条地创建 Sandbox、调用模型、消耗预算。 NiceEval 分两种情况处理：

限流、网络抖动这类瞬时失败，只要能确认 Agent 还没收到请求，NiceEval 会自动重试，你不用管。
凭据失效、共享服务断开这类故障，重试也没用。你可以在代码里声明它影响哪些范围，NiceEval 会停止派发剩下的相关 Attempt。修好之后，只补跑没完成的部分，已经得出的结果照常保留。

先分清是运行出错还是答错了

动手修之前，先看失败的 Attempt 是哪一种：

errored：运行本身没跑成，没有得出可以评分的结果。例如目标服务没启动、协议不匹配、凭据无效、依赖缺失或 Adapter 抛错。修好运行环境后重跑。
failed：Attempt 跑完了，但有业务断言没满足。它可能确实暴露了被测系统的问题，也可能说明判据过紧或写错了。先查看同一个 Attempt 的输入、输出、断言和证据，再决定改被测系统还是改评估用例。

不要把真实的业务失败归成基础设施故障，也不要为了全绿去改判据。计分制评估跑完只说明打分结束了。表现好不好要看分数和每条断言，低分结果不会因为跑完了就算满分。查看某个 Attempt 的错误正文时，复制终端给出的 locator：

pnpm exec niceeval show @<attempt-locator>

读懂自动重试

自动重试不需要配置。重试等待时，Attempt 的进度行会显示类似这条信息：

turn retry 2/4 (rate_limit) — waiting 8s

重试成功后，评分和对话记录只保留成功的那次 Turn。重试次数用完后，Attempt 会变成 errored，错误里会出现摘要：

retries exhausted (4 attempts, rate_limit)

没有这条摘要，说明 NiceEval 没有重试这个错误。Agent 已经收到的请求，或者无法确定是否收到的请求，不会自动重试，以免重复执行有副作用的操作。

在发现故障时声明影响范围

你自己检查共享服务或 Fixture 时，可以直接抛出带有影响范围的错误：

ExperimentFatalError 停止同一实验尚未开始的 Attempt。它适合共享服务、共享凭据和实验级配置故障。
EvalFatalError 只停止当前评估尚未开始的 Attempt。它适合确定性缺失的 Fixture 或该评估专用的前置资源。

下面的评估在 Fixture 缺少时停止自己的剩余 Attempt：

// evals/coding/fix-button.eval.ts
import { defineEval, EvalFatalError } from "niceeval";

export default defineEval({
  async test(t) {
    const fixture = await t.sandbox.runCommand("test", ["-f", "src/Button.tsx"]);
    if (fixture.exitCode !== 0) {
      throw new EvalFatalError(
        "Fixture 缺少 src/Button.tsx。请先运行 pnpm fixtures:sync，然后重跑评估。",
      );
    }

    await t.send("修复 Button 的键盘焦点问题。");
  },
});

共享服务无法访问时，把检查写进真实评估用例的 test(t) callback。先把 serviceHealthUrl 换成服务的健康检查地址，再用 ExperimentFatalError 停止同一实验的剩余 Attempt：

// evals/coding/shared-service-health.eval.ts
import { defineEval, ExperimentFatalError } from "niceeval";

const serviceHealthUrl = "https://service.example.test/health";

export default defineEval({
  async test(t) {
    const health = await t.sandbox.runCommand("curl", ["-fsS", serviceHealthUrl]);
    if (health.exitCode !== 0) {
      throw new ExperimentFatalError(
        "共享服务无法访问。请检查服务和隧道，然后重跑实验。",
        { cause: health.stderr },
      );
    }
  },
});

错误消息会出现在终端和运行记录中。请写明发生了什么，以及下一步怎么修复。

识别运行中断开的共享服务

有些共享服务在实验开始时正常，却在运行中断开。这种失败通常由 SDK、CLI 或网络库抛出。你可以用实验的 classifyFailure 识别自己的服务地址：

// experiments/compare.ts
import { defineExperiment } from "niceeval";

const serviceHost = "memory.internal.example";

export default defineExperiment({
  // agent 和 sandbox 配置省略
  classifyFailure({ text }) {
    const isOurService = text.includes(serviceHost);
    const isConnectionFailure = /ECONNREFUSED|ENOTFOUND|connection refused/i.test(text);

    if (isOurService && isConnectionFailure) {
      return {
        retryable: false,
        scope: "experiment",
        reason: "shared_service_unavailable",
      };
    }
    return undefined;
  },
});

只识别你能确定影响范围的服务。不要把所有 ECONNREFUSED 都当成实验级故障，因为 Agent 访问其他站点时也可能出现同样的错误。

修好后补跑没完成的部分

止损生效后，同一范围里还没开始的 Attempt 不再派发，记为 unstarted，运行状态显示 incomplete。已经在跑的 Attempt 会跑完并如实记录结果，触发故障的那些记为 errored。先看这次运行的结果，确认停下来的范围和你预期的一致。Run ID 在终端的 NEXT 面板里：

pnpm exec niceeval show --run <run-id>

也可以用 pnpm exec niceeval view --run <run-id> 在浏览器里看。需要查看某个 Attempt 的原始错误和重试摘要时，复制它的 locator：

pnpm exec niceeval show @<attempt-locator> --execution

修好服务、凭据或 Fixture 后，重新运行原命令：

pnpm exec niceeval exp compare evals/coding

errored 和 unstarted 的 Attempt 会重新跑，已经通过的结果照常沿用。运行前可以加 --dry 确认哪些会重跑，规则见修改后只重跑受影响的评估。自定义 Adapter 如果能明确识别“请求被拒绝、还没被受理”的协议信号，可以提供 classifySendFailure，把这类失败标为可以重试。字段类型和边界见 defineSandboxAgent 参考。

开始使用

接入你的应用

评估 Coding Agent

写好评估用例

实验与对比

看结果与迭代

提速：并发与复用

基础设施与 CI

问题排查

凭据失效或服务挂掉时，及时止损

先分清是运行出错还是答错了

读懂自动重试

在发现故障时声明影响范围

识别运行中断开的共享服务

修好后补跑没完成的部分

​先分清是运行出错还是答错了

​读懂自动重试

​在发现故障时声明影响范围

​识别运行中断开的共享服务

​修好后补跑没完成的部分

先分清是运行出错还是答错了

读懂自动重试

在发现故障时声明影响范围

识别运行中断开的共享服务

修好后补跑没完成的部分