工具调用校验：按交付的 schema 比较，而非你预期的 schema

IT加油站2026-09-07 16:42398分钟

原文：https://dev.to/kenielzep97/compare-against-the-schema-they-shipped-not-the-one-you-expected-3mb8（作者 @kenielzep97）

我的测试框架（harness）标记了模型，因为它发送了错误的参数。它将模型实际发送的内容与本次运行事先承诺的内容做了比对，两者不匹配。

不匹配是真实存在的。但我据此得出的结论是错的，而比对器（comparator）无法告诉我这一点。

下面要讲的是：那个不完整的检查、取代它的新检查、为什么修复方法不是"放宽比对"，以及其中将来会腐烂变质的部分。

背景设定

测试框架在模型运行前准备好一次 exec 调用，将其冻结，要求模型精确发送该对象，然后把模型实际发出的工具参数与冻结的对象进行比对。如果二者不同，运行就会 fail closed（判定失败）。这个比对就是控制手段。

预期对象是这样构建的——`5bf10ac`，scripts/judgment/candidate.mjs：

const expectedExecArguments = validateExecArguments({
  command: `node ${artifactPath('verifier')} ${artifactPath('payload')} ${artifactPath('manifest')}`,
});

只有一个键。来自运行收据 `RUN_004_RECEIPT.json`，以下是模型实际发送的内容，逐字引用：

{"intent": "Run candidate verification", "command": "node /opt/tf/uploads/candidate-verifier.cjs /opt/tf/uploads/candidate-payload.json /opt/tf/uploads/candidate-command-manifest.json"}

同一份收据中记录的结果：EXEC_ARGUMENTS_MISMATCH。

两份契约，彼此冲突

这是我第一遍读时弄错的部分，而且它比"模型偏离了预期"更有意思。

提供者的 exec schema（模式）——来自我所运行的编译产物 @truefoundry/trueforge-core@0.1.4 中的 dist/core/sandbox/Sandbox.mjs：

var sandboxExecSchema = z.object({
  intent: z.string().describe(
    "A brief, user-facing explanation of the purpose of this command. Avoid technical jargon and code details."
  ),
  command: z.string().describe("The shell command to execute in the sandbox."),
  cwd: z.string().optional().describe("Working directory for command execution."),
  env: z.record(z.string(), z.string()).optional().describe("Additional environment variables to set.")
});

四个字段。intent 和 command 必填，cwd 和 env 可选。这是接入沙箱 exec 工具的实现 schema；我引用的是运行时实际接受的内容，而不是从会话中捕获的工具描述符。

我的测试框架的指令，scripts/judgment/live.mjs，在修复前后都存在：

'Call truefoundry-system exec exactly once with this exact JSON argument object: ' + ...

当时被插值进字符串的那个对象只有一个键。

于是，模型面对两个互相矛盾的权威来源，它遵循了提供者的那个。它满足了必填字段的 schema，却没有遵从我的精确 JSON 指令，因为我的指令要求的正是 schema 所禁止的东西。 我的比对器看到一处差异，就把它报告为偏离。它没有办法表达"双方各自内部自洽，但其中一方是错的"。

这就是结论：不是说模型是对的——而是说一次不匹配只能确立差异，不能确立哪个操作数是权威的。

修复方案，以及真正要紧的部分

最诱人的修法是减少比对内容——只检查 command，忽略多余的键，然后继续。但这会让失败消失，也把控制手段一并带走。之后智能体（agent）就可以发送任何它想发的额外参数，依然通过检查。

最终落地的方案，见提交 `0220a27`：

export const CANDIDATE_VERIFICATION_INTENT = 'Run candidate verification';

const expectedExecArguments = {
  command,
  intent: CANDIDATE_VERIFICATION_INTENT,
};

intent 的值由测试框架撰写且恒定不变，不是从模型发送的内容中复制来的。复制它，比对就变成了拿模型自己来检查自己。

那次提交的标题是 "Implement adopted transport A and B controls"——这个修正是搭载在一个更大的传输层改动里一起发布的，而不是作为独立修复单独提交。这一点值得说明，因为我正请你打开那次提交看看。

预期对象的门禁检查也变得更严格了：

const argumentKeys = Object.keys(expectedArguments).sort();

if (argumentKeys.length !== 2 || argumentKeys[0] !== 'command' || argumentKeys[1] !== 'intent' ||
    expectedArguments.intent !== CANDIDATE_VERIFICATION_INTENT ||
    typeof command !== 'string' || command.length === 0) {
  failures.add('EXEC_ARGUMENTS_MISMATCH');
}

三件相互独立的事，其中只有一件变了：

预期对象被修正了——从一个键变成两个。
预期对象的门禁检查变严格了——上面那个代码块是新增的。
实际值与预期值的比对完全没变。 它原本就是这样：

const actual = parseStrictJson(call.function.arguments);
...
} else if (!canonicalJsonBytes(actual).equals(canonicalJsonBytes(prepared.expectedExecArguments))) {

这一行在修复前后完全一致。键在规范化（canonical）序列化过程中会被排序，所以这是规范化对象比对，而不是原始字节比对；JSON 键顺序不会造成虚假的不匹配。我并没有靠削弱比对器来修复一个假失败。 这正是全部重点。

我修复的范围比看起来窄

提供者的契约： intent 和 command 必填，cwd 和 env 允许出现。

我冻结的运行契约： 恰好只有 command 和 intent，没有其他键，且 intent 固定为一个常量。

我这条是有意收窄的。一个宽松的提供者并不要求 harness 接受所有符合 schema 的变体——如果运行预先承诺了这两个特定参数，拒绝第三个键是合理的 harness 约束。但这是我自己的策略，不是 TrueForge 的要求；把它写成提供者的要求，就是朝相反方向犯了同样的错误。

而下面这些没有修正。 argumentKeys.length !== 2 一次硬编码了两件事：提供者当前的必填字段集合，以及我的运行中禁止可选字段的决定。如果 TrueForge 明天新增第三个必填字段，我的 harness 会拒绝一个遵守新 schema 的模型——除非我同时修改 harness。更耐用的版本会从实际的工具 schema 推导出提供者要求的字段，然后再显式地叠加更窄的 harness 策略。我没有构建这个版本。如果你复制这个模式，就把问题一起复制走了。