structured-outputs-integration-gate 技能——Schema 单元测试漏掉的测试
当把 LLM 响应处理迁移到 API 侧的结构化输出校验时,仅靠 schema 单元测试是不够的。该技能解释了会静默失效的契约边界,以及能堵住这一漏洞的那一个 wrapper 路径测试。
在隔离环境中,为 LLM 流水线添加 schema 绑定的响应解析是直截了当的。新的校验器能编译,schema 单元测试通过,实现看起来也很干净。失败模式出现在之后,位于新校验器与既有的后处理代码之间的边界处——这些后处理代码在校验器存在之前一直在悄悄清理响应。
structured-outputs-integration-gate 技能的存在,就是为了在进入代码审查之前捕获这一类特定的回归。它的触发条件很窄:任务从提示词工程式的 JSON 提取迁移到 API 的结构化输出或类型化解析端点,或者在现有响应清理辅助函数旁边新增一个解析后校验层。
为什么 schema 单元测试不够
schema 单元测试在隔离环境中检验校验器。它模拟提供方调用,发送一个有效载荷、一个形状无效的载荷,以及一些边界字段。这正确地锁定了 schema 契约。然而,它看不到当遗留响应清理器和新校验器按顺序对同一载荷运行时会发生什么。
问题在于顺序。新校验器通常会在旧过滤器有机会运行之前,对解析后的模型对象运行。如果遗留契约是「从响应中静默移除这些 token」,新校验器就会把它翻转为「一旦这些 token 中出现任何一个,就硬失败整个响应」。schema 测试之所以是绿的,是因为它们从未引入那个确切的载荷。生产行为之所以被破坏,是因为遗留响应载荷恰好包含那些 token。
wrapper 路径测试
该门禁要求除 schema 单元测试之外再增加一个测试。wrapper 路径测试从入口点开始,经过每一个现有的后处理过滤器和新校验器,完整地检验整个处理器。关键步骤是注入一个遗留过滤器本就设计用来剥离的载荷,然后断言历史行为得以保留——静默移除并成功——而不是 schema 单元测试所体现的行为,即硬拒绝。
这个测试就是门禁。该技能明确指出,单独任何一种测试都不够。没有 wrapper 路径测试的 schema 单元测试会让契约边界不可观测。没有注入遗留剥离载荷的 wrapper 路径测试则会完全错过失败模式。
门禁触发时该做什么
如果所涉处理器的计划没有列出这两种测试,该技能要求返回计划生成阶段,并在任何实现开始之前将它们加入。如果实现已经进行中,该技能要求暂缓合并,直到 wrapper 路径测试既为绿色,又已刻意尝试过遗留剥离场景。
该门禁拒绝的反模式是具体的:即使穷尽也只是 schema 单元测试;不注入遗留过滤器载荷的 wrapper 路径测试;以及在校验器在遗留过滤器运行之前就触发的校验器。第三种情况有一个结构性修复:将校验器拆分为仅 schema 检查和过滤器后安全网辅助函数,使遗留过滤器先运行,无残留检查后运行。
规则的来源
该技能记录了自己的起源。一次这种确切形态的静默契约回归被发布到功能分支,通过了 schema 单元审查,仅在人工合并请求审查时被一位将遗留过滤器契约记在脑中的维护者捕获。schema 测试是绿的;生产行为却被破坏了。一个 wrapper 路径测试本可以在审查到达人类之前就堵住这个缺口。
阅读什么是 Datarim了解技能如何将经验教训嵌入工作流的背景,或查看自验证技能了解这类缺口如何在验证层被捕获。