
工具参数里少了 unit,和写着 "unit": null,看上去都像没有单位。到了校验器这里,两种输入却可能走不同分支:前者是键不存在,后者是键存在、值为空。把它们提前合并,后面就再也无法判断调用方原本表达了什么。
在本地 Node 脚本中,JSON.parse 解析了缺少 unit 的对象和显式写出 null 的对象。随后用 Object.hasOwn 检查键,再让 JSON.stringify 输出一个值为 undefined 的属性和一个值为 null 的属性。输出保存在 tools/verify-agent-null-vs-missing-fields.log,只覆盖 JSON 与 JavaScript 对象行为,没有接模型接口。
parsed missing unit: {"city":"Oslo"}; hasOwn=false
parsed null unit: {"city":"Oslo","unit":null}; hasOwn=true
stringify undefined field: {"city":"Oslo"}
stringify null field: {"city":"Oslo","unit":null}
validator missing/null/value: missing/explicit-null/valid
rebuilt tool call: {"id":"call_7","type":"function","function":{"name":"weather","arguments":"{\"city\":\"Oslo\",\"unit\":null}"}}
ASSERTIONS: all passed
字段存在与值为空是两回事
JSON 对象可以不包含某个键,也可以把这个键的值设为 null。解析后,缺省版本的 Object.hasOwn(args, 'unit') 是 false;显式 null 版本则是 true,并且读取 args.unit 得到 null。如果只写 if (!args.unit),这两种情况都会被当成假值,连空字符串、数字 0 也会一起混进去。判断字段是否提供,应看键是否存在;再检查值的类型和允许范围,确认参数能不能使用。
校验规则由工具契约决定,不能从 JSON 语法本身推断。比如可选的 unit 可以在未提供时采用默认值;若契约规定它必填且允许显式清空,则缺键应报错,而 null 可以是有效输入。必填且非空的字段则需要拒绝两者。这些策略名称相近,结果却不相同,最好在 schema 或验证函数里写清楚,而不是塞进统一的真假值判断。
这也是参数校验需要先划分缺失与无效的原因。缺失通常代表调用没有给这个字段,可能触发默认值;显式 null 是调用给出的一个值,可能代表清除,也可能表示值未知。含义必须由工具定义。把 null 一概当成缺省值,会让保持现状与清空内容之类的操作失去区分;把缺省一律改成 null,也会让必填字段看起来像是传过了参数。
序列化时 undefined 会消失
JSON.stringify 不会把对象中的 undefined 属性编码成 null,而是直接略过这个属性。脚本里 { city: 'Oslo', unit: undefined } 最终成为 {"city":"Oslo"};换成 unit: null,输出才是 {"city":"Oslo","unit":null}。因此,某段业务代码即使在内存里保留了一个 unit 属性,序列化后仍可能变成字段缺失。如果对话历史或工具协议使用 JSON 文本传递参数,检查对象本身还不够,序列化后的内容才是传输边界上的实际形状。
相反方向也要留神。把对象解析后,再按白名单字段逐个造一个新对象,容易无意中删掉尚未识别的可选字段。字段过滤当然有它的用途,例如把不可信输入限制在工具 schema 内;但过滤规则应明确,而不是因为重建对象时忘了复制某个键,就静默改变参数语义。对于必填键,缺失应由校验器报出来,不能靠序列化后看起来差不多来补救。
重建调用时保留关联信息
工具请求通常还带有调用标识,函数部分也会携带名称与类型信息。不同接口定义并不完全相同,不能把一个 SDK 的字段表当成通用协议。不过只要消息需要和前一条工具调用配对,标识就属于数据契约;在转换参数时把它丢了,回填层便可能无法确认结果对应哪次调用。
验证脚本构造了一个本地调用对象,包含 id、type、函数名和 JSON 参数字符串。重建时使用对象展开保留外层调用字段,也展开原函数对象,只更新参数文本。断言检查重建前后结构相等,且 unit: null 仍在参数中。浅展开并不适用于所有场景:嵌套结构仍需逐层处理,协议新增字段也应原样通过或由明确的 schema 管控。关键是修改一个已知字段时,别让无关字段陪着丢失。
我会把两步分开:先按工具定义校验参数,再在构造返回消息时保留调用所需的原始关联字段。若字段允许省略,就让省略保持省略;若允许 null,就保留这个明确值。要不要给缺省字段补默认值,是工具业务规则,不是 JSON 序列化器替调用方作出的决定。