当工具名“长得一样”却校验失败:Unicode 同形字符如何骗过你的 Agent 契约

2026/11/20
当工具名“长得一样”却校验失败:Unicode 同形字符如何骗过你的 Agent 契约

AI Summary (BLUF)

当 agent 工具名因 Unicode 同形字符(如西里尔字母 o 与拉丁字母 o)导致契约校验失败时,不要通过归一化来“修复”证据。本文以 AgentInspect 6.31.35 为例,演示如何复现不匹配、读取码点诊断、追溯命名边界,并用共享常量与类型约束减少漂移。

核心洞察

这个坑比想象中隐蔽。两个字符串在屏幕上长得一模一样,但一个是拉丁字母 o,一个是西里尔字母 о,Unicode 码点不同,严格比较直接判假。我见过有人第一反应是加个 normalize 让它“匹配上”,这等于把证据改了让测试变绿。文章给的思路是对的:保留原始身份,把不匹配解释清楚。


Agent 的契约要求有 retrieve_policy。trace 里看着也有 retrieve_policy。评估器却说工具不存在。

先别急着改契约,看看字符本身。

const expected = "retrieve_policy";
const observed = "retrieve_p\u043Elicy";

console.log(expected === observed); // false

observed 里那个 o 是西里尔小写字母 o,U+043E。expected 里是拉丁字母 o,U+006F。很多字体下这俩长得一样。但它们是不同的字符串。

我是 AgentInspect 的维护者。这个例子在 6.31.35 上测过,该版本的诊断能对某些可疑名称暴露码点。这里的设计选择不是什么聪明的 Unicode 技巧,而是:把解释做得更好,但绝不悄悄改掉正在被评估的那个标识符。

核心结论

  1. Agent 工具名在屏幕上看起来一样,但可能是不同的 Unicode 字符(如拉丁字母 o 为 U+006F,西里尔字母 о 为 U+043E),严格比较会直接判为不匹配,这是工具契约评估失败的隐蔽原因之一。

  2. 在 agent-inspect 6.31.35 版本上可复现该问题:用西里尔字母构造的 retrieve_p\u043Elicy 调用能成功执行,但 TraceContract 评估会失败,findings 中会包含 U+043E 的码点诊断,而精确 ASCII 名称的对照则通过。

  3. 解决思路是保留标识符的原始身份、让不匹配变得可读,而不是通过 normalize 或大小写折叠把观察值改成期望值——后者会让 fixture 变绿,却把真实的集成缺陷藏起来。

  4. 工具名不匹配应依次排查注册表、序列化后的调用、适配器映射和契约定义四个边界,复制粘贴错误、命名规范不一致、适配器缺陷都能产生相同症状,不能仅凭此断定是攻击。

  5. 减少漂移的实践是让注册、调用和测试期望共享同一份常量(如 TypeScript 的 as const 工具名映射),并将标识符与可读描述分离,改标识符应触发契约和历史比较的有意迁移。

相等性和可读性解决的是两件事

一个工具名参与的是工具注册表、调用、trace 适配器和评估器之间的契约。这几方一旦对不上,过于宽容的显示逻辑会把真实的集成缺陷藏起来。

操作 合适的用途 用于策略匹配的风险
精确比较 比较记录下来的标识符 对人来说可能需要更好的诊断
转义/码点显示 解释视觉上容易混淆的值 不能替代原始身份
友好的显示标签 让 UI 好读 多个标识符可能共用一个标签
大小写折叠或规范化 明确定义过的命名方案 可能在不同方案下悄悄合并名称

白名单不是拼写检查器。应用授权的是某一个标识符,适配器不该替它授权一个长得像的。

这不意味着非拉丁工具名就无效。契约可以明确允许任何受支持命名方案下的名字。问题出在身份之间的不一致,跟用什么语言写无关。

保留身份,让不匹配变得可读。

不用 LLM 就能复现这个不匹配

装固定版本的包,抓一个合成调用:

npm install --save-exact agent-inspect@6.31.35
import { inspectRun, step } from "agent-inspect";

await inspectRun("unicode-name-fixture", async () => {
  return step.tool("retrieve_p\u043Elicy", async () => ({
    found: true,
  }));
}, { traceDir: ".agent-inspect", silent: true });

回调成功了。但这不代表名字匹配了契约。用 openTraceFile 打开生成的 trace 之后,评估一下:

import {
  defineTraceContract,
  evaluateTraceContractRead,
} from "agent-inspect/checks";

const contract = defineTraceContract({
  tools: {
    required: ["retrieve_policy"],
    allowed: ["retrieve_policy"],
  },
});

const result = evaluateTraceContractRead(trace, contract);
console.log(result.status, result.findings);

这个 fixture 会失败。findings 里包含 U+043E 的诊断。用精确 ASCII 名字做的正向对照则通过。

两个约束是互补的。required 问的是期望的工具有没有出现。allowed 问的是有没有出现意料之外的。具体到你的应用,有意义的报告可能同时包含“缺少期望操作”和“出现了无法识别的操作”。

TraceContract 还是 beta API。回归 fixture 记得钉在你发布门禁用的那个版本上。

把不匹配追回到边界

名字对不上时,依次查注册表、序列化后的调用、适配器映射和契约定义。一段复制过来的描述可能变成了标识符。一个显示标签可能替换了注册名。某个规范化层可能改写了字符。

别光凭这个 fixture 就断定是攻击。复制粘贴错误、命名规范不一致、适配器缺陷,都能产生同样的症状。诊断应该报告观察到的不匹配,而不是对意图做没有依据的断言。

同样的纪律适用于前导空格、大小写变化、隐藏控制字符和别名。先确定应用的命名契约,再判断是哪个边界违反了它。

如果别名是有意为之,写进经过评审的映射里并做版本管理。一个没记录的“差不多就行”转换,会让之后的证据更难解读。

减少漂移的机会

对于你自己控制的名字,让注册、调用和测试期望共享同一份常量:

export const Tool = {
  retrievePolicy: "retrieve_policy",
  summarizePolicy: "summarize_policy",
} as const;

type ToolName = typeof Tool[keyof typeof Tool];

function acceptsRegisteredName(name: ToolName) {
  return name;
}

类型能挡住你自己 TypeScript 代码里某些手滑的字面量。它验证不了不可信的运行时字符串。外部值要在边界处用注册表的真实标识符来校验。

另外把标识符和描述分开。一个可读标签在本地化时可以改,不用重命名操作。反过来,改操作的标识符应该触发契约和历史比较的一次有意迁移。

诊断输出要有边界

一份有用的错误报告会显示期望的名字、观察到的名字,以及足够解释差异的转义或码点信息。它不该把无界的输入倒进终端或报告里。

当前实现只对选定的混合文字或高风险控制字符情况附加码点细节,它不是通用的欺骗检测器。没拿到额外诊断的名字不代表就可信。同样,拿到诊断的名字也不自动等于恶意。

原始捕获的证据、比较结果、给人看的解释,这三者在概念上要分开。各干各的活。

别为了让测试变绿去修证据

最诱人的修法是把观察到的名字规范化成期望的那个。fixture 可能因此通过,真实的不匹配却被藏了起来。

更好的修法是纠正命名边界,或者明确更新契约。然后把精确匹配的正向对照和相似名称的负向对照都重跑一遍。

当一个 agent 工具穿过注册表、SDK、适配器和评估器时,一个微小的标识符变化就能变成一场漫长的调试绕路。解法是精确的策略和能看懂的诊断,不是更宽容的猜测。

实现参考

  • 工具匹配与有界诊断格式化(GitHub 链接)
  • 契约文档(GitHub 链接)
  • 配套文件:examples/probes.test.mjs,测试 D04。

常见问题(FAQ)

agent 工具名看起来一样却校验失败,是什么原因?

很可能是 Unicode 同形字符导致:例如西里尔字母 о(U+043E)与拉丁字母 o(U+006F)外观相同但码点不同,严格比较会判为不相等,因此契约校验失败。

为什么不能通过归一化让工具名匹配通过测试?

归一化等于改掉正在被评估的标识符,会把真实的不匹配证据藏起来,让测试变绿却掩盖集成缺陷。应保留原始身份,纠正命名边界或明确更新契约。

如何复现并诊断工具名 Unicode 不匹配问题?

安装固定版本 agent-inspect@6.31.35,用合成调用生成 trace,再通过 evaluateTraceContractRead 评估契约;findings 会给出码点诊断,帮助定位注册表、调用或适配器边界。

Roger深圳
本文由 Roger 审核,最后更新于 2026年11月20日
联系编辑 →
← 返回文章列表
分享到:微博

版权与免责声明:本文仅用于信息分享与交流,不构成任何形式的法律、投资、医疗或其他专业建议,也不构成对任何结果的承诺或保证。

文中提及的商标、品牌、Logo、产品名称及相关图片/素材,其权利归各自合法权利人所有。本站内容可能基于公开资料整理,亦可能使用 AI 辅助生成或润色;我们尽力确保准确与合规,但不保证完整性、时效性与适用性,请读者自行甄别并以官方信息为准。

若本文内容或素材涉嫌侵权、隐私不当或存在错误,请相关权利人/当事人联系本站,我们将及时核实并采取删除、修正或下架等处理措施。也请勿在评论或联系信息中提交身份证号、手机号、住址等个人敏感信息。