侧边栏壁纸
博主头像
一笑痕

人生若只如初见,
是可喜亦或者是可悲?

  • 累计撰写 291 篇文章
  • 累计收到 7 条评论

工具参数先归一化,解析与类型检查才有共同入口

2026-11-20 / 0 评论 / 8 阅读

工具参数先归一化,解析与类型检查才有共同入口

工具参数到达分发器时,有时还是一段 JSON 文本,有时已经是 JavaScript 对象。只写 JSON.parse(args) 会让后一种输入直接抛错;把所有输入都当对象用,又会漏掉损坏文本和顶层数组。入口需要先认清输入形态,再做同一套结构检查。

本地脚本用固定样例跑了两种有效输入和几种边界值,没有调用模型或网络。输出显示,文本形式和已解析对象都被接受;损坏的 JSON、数组、null 与数字则被拒绝。完整证据来自 tools/verify-agent-tool-arguments.log:

ACCEPT raw JSON string: {"city":"Osaka","unit":"c"}
ACCEPT already parsed object: {"city":"Osaka","unit":"c"}
REJECT malformed string: arguments string is not valid JSON
REJECT top-level JSON array: arguments must resolve to a JSON object
REJECT top-level null: arguments must resolve to a JSON object
REJECT unsupported number input: arguments must resolve to a JSON object
ASSERTIONS: all passed

两种输入不能走同一条解析语句

如果协议边界明确规定 arguments 永远是字符串,直接解析并在失败时返回参数错误很合理。问题出现在适配层需要兼容不同来源时:一个调用方传序列化文本,另一个调用方已替你解码。对后一种值再调用 JSON.parse,得到的是类型错误,不是 JSON 语法错误。异常日志会把「输入已经解析」误报成「文本格式坏了」。

反过来,拿到值就直接读取 args.city 也不稳。字符串会被当成对象包装,属性通常读到 undefined;数组本身也是对象;null 的属性读取还会直接抛异常。入口分支若没有统一,校验逻辑就会被两套调用路径绕开。

脚本中的 normalizeArguments 只在输入类型是字符串时解析。其他类型先作为值进入形状检查。解析失败会转成明确的 TypeError,让错误说明它属于输入文本,而不是后续业务字段。字符串解析和对象校验因此各自有清楚的职责。

解析成功之后仍要确认顶层形状

合法 JSON 可以解析成数组、null 或数字。工具参数约定通常需要键值对象,因此要在读取字段前拒绝这些顶层类型。JavaScript 里 typeof null 与 typeof [] 都是 object,单独写 typeof value !== 'object' 不够。要把 null 和数组明确排除。

function normalizeArguments(input) {
  let value;
  if (typeof input === 'string') {
    value = JSON.parse(input);
  } else {
    value = input;
  }
  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
    throw new TypeError('arguments must resolve to a JSON object');
  }
  return value;
}

这个检查只回答顶层是不是非空对象,不会替代每个工具的字段校验。天气工具还要按自己的参数定义检查 city 和 unit。共同入口把类型边界说清楚,业务校验仍留在工具自身的契约里。

归一化也不必然代表复制。脚本对已经解析的对象直接返回原引用,这让入口更轻,但调用方后续若原地改写参数,其他持有者也会看到变化。要不要复制,应由工具参数的所有权约定决定;这与字符串是否需要解析是两个问题。接口只承诺把输入变成合格对象时,不应悄悄承诺对象隔离。

错误分类要留在分发之前

坏文本和错误形状最好在工具执行前被挡住。这样调用记录能区分解析失败与对象结构不符,也不会让工具函数收到半成品数据。固定样例中,原始文本和对象形式各自通过;截断字符串报出无效 JSON;数组、null 与数值输入都因无法归一成参数对象而拒绝。

需要留心的是,接受已解析对象意味着信任对象的来源边界。若值来自插件或进程内其他代码,除了顶层类型,还应核对字段是否在允许范围内,并确认必填键都已出现。若输入来自模型响应,先解析也不等于授权;工具权限和调用审批仍是另一道检查。这段小脚本没有模拟外部 SDK 的真实返回类型,只验证了归一化函数对两种输入形态的处理。

我会把兼容判断放在单一分发入口,并让后续工具只接收已验证的对象。若上游协议本来就固定一种格式,就不必为了兼容而接受更多类型;边界越宽,适配和测试责任也越多。先确认真实调用方交付什么,再决定是否需要这个归一层。

    🤞 分享