当工具名“长得一样”却校验失败: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一个用于检查和追踪AI代理运行的JavaScript库,提供MCP客户端包装和TraceContract检查功能。 的维护者。这个例子在 6.31.35 上测过,该版本的诊断能对某些可疑名称暴露码点。这里的设计选择不是什么聪明的 Unicode 技巧,而是:把解释做得更好,但绝不悄悄改掉正在被评估的那个标识符。
核心结论
Agent 工具名在屏幕上看起来一样,但可能是不同的 Unicode 字符(如拉丁字母 o 为 U+006F,西里尔字母 о 为 U+043E),严格比较会直接判为不匹配,这是工具契约评估失败的隐蔽原因之一。
在 agent-inspect
6.31.35版本上可复现该问题:用西里尔字母构造的retrieve_p\u043Elicy调用能成功执行,但 TraceContractAgentInspect中的一种契约定义,用于对追踪数据(如运行完成状态、观察结果)进行断言和验证。 评估会失败,findings 中会包含 U+043E 的码点诊断在错误报告中显示字符的 Unicode 码点信息,帮助解释视觉上难以区分的字符串差异。,而精确 ASCII 名称的对照则通过。解决思路是保留标识符的原始身份、让不匹配变得可读,而不是通过 normalize 或大小写折叠把观察值改成期望值——后者会让 fixture 变绿,却把真实的集成缺陷藏起来。
工具名不匹配应依次排查注册表、序列化后的调用、适配器映射和契约定义四个边界,复制粘贴错误、命名规范不一致、适配器缺陷都能产生相同症状,不能仅凭此断定是攻击。
减少漂移的实践是让注册、调用和测试期望共享同一份常量(如 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 会给出码点诊断,帮助定位注册表、调用或适配器边界。
版权与免责声明:本文仅用于信息分享与交流,不构成任何形式的法律、投资、医疗或其他专业建议,也不构成对任何结果的承诺或保证。
文中提及的商标、品牌、Logo、产品名称及相关图片/素材,其权利归各自合法权利人所有。本站内容可能基于公开资料整理,亦可能使用 AI 辅助生成或润色;我们尽力确保准确与合规,但不保证完整性、时效性与适用性,请读者自行甄别并以官方信息为准。
若本文内容或素材涉嫌侵权、隐私不当或存在错误,请相关权利人/当事人联系本站,我们将及时核实并采取删除、修正或下架等处理措施。也请勿在评论或联系信息中提交身份证号、手机号、住址等个人敏感信息。




