在基础设施失败时停止无效运行

NiceEval 会自动重试明确未被 Agent 受理的瞬时失败，例如限流或部分网络错误。如果某个故障注定让同一实验或评估的后续 Attempt 失败，你可以立即停止它们。

先区分执行故障与业务结论

errored 表示运行没有形成可评分的业务结果，例如目标服务未启动、协议不匹配、凭证无效、依赖缺失或 Adapter 抛错。修复执行链后重跑。 failed 表示 Attempt 已经执行完成，但一个或多个业务断言不满足。它可能正确暴露了被测系统的问题，也可能暴露了过紧或错误的判据。先读取同一 Attempt 的输入、输出、Assertion 和证据覆盖，再决定修改被测系统还是评估用例。不要把真实业务失败归类成基础设施故障，也不要为了全绿而自动重写判据。 Score Eval 的完成状态只表示评分过程结束。是否表现良好由分数和逐项 Assertion 决定；低分结果不应因为执行完成而被解释为满分。

先读懂自动重试

自动重试不需要配置。重试等待时，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 会记为 errored。还没开始的 Attempt 会记为 unstarted，运行状态会显示 incomplete。修好服务、凭据或 Fixture 后，重新运行原命令。NiceEval 会保留已通过的结果，并运行之前 errored 或 unstarted 的部分。

npx niceeval exp compare evals/coding

需要查看某个 Attempt 的原始错误和重试摘要时，使用终端给出的定位符：

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

自定义 Adapter 如果有专用的受理前拒绝信号，可以提供 classifySendFailure。该字段的类型和边界见 defineSandboxAgent 参考。

开始使用

连接 Agent

编写评估

运行、观察与发布

问题排查

在基础设施失败时停止无效运行

先区分执行故障与业务结论

先读懂自动重试

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

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

修复后继续运行

​先区分执行故障与业务结论

​先读懂自动重试

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

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

​修复后继续运行

先区分执行故障与业务结论

先读懂自动重试

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

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

修复后继续运行