给 AI 输出加上可校验的结构契约

dev.to · AI#输出校验#Python#开源

Editor brief · 编辑速览

Output Contracts 是无第三方运行时依赖的 Python 校验工具，可检查 JSON 结构及 Markdown 必需标题、顺序和禁用措辞。它只报告契约违规，不调用模型、不自动修复，也不判断内容是否真实完整。

文章思维导图

Knowledge map

拖拽缩放

AI deep read

AI 深度解读

JSON 能解析，不代表下游程序能用；交接文档读着顺畅，也可能漏掉接手的人最需要的信息。作者介绍的 Output Contracts，把这些接口要求写成明确规则，再指出究竟哪个字段、哪个章节违约。

它的价值是把「格式不对」变成可定位、可处理的错误。但边界也很清楚：结构符合约定，不代表内容真实，更不能证明任务已经完成。

能解析的 JSON，为什么还会交付失败

输出契约（Output Contract）就是消费方事先声明的接收条件。例如，交接文档必须包含哪些标题、按什么顺序排列；JSON 必须提供哪些字段，字段接受什么类型和值。

Output Contracts 是一个小型 Python 校验器，不调用模型，不评价文笔，也不会悄悄修复输出。

原文的 JSON 反例包含 "id": "case-18"、"status": "accepted"、"count": true 和 "items": []。它可以正常解析，却违反了两条声明：count 必须是整数，items 必须是非空数组。

这里有个容易踩的坑：Python 中布尔值与整数存在类型关系，但按这个契约，true 不能通过整数检查。字段位置通过 JSON pointers 表示，null 也与字段缺失分开处理。

语法校验只回答能不能读取，契约校验还要回答读到的结构是否符合约定。

Markdown 也一样。缺少未决问题章节，或者把证据放到后续步骤之后，即使全文通顺，也破坏了约定的交接顺序。

怎样让错误真正进入处理流程

工具要求 Python 3.11 或更新版本，没有第三方运行时依赖。下面的命令用自带反例检查 Markdown 交接文档，并把报告保存下来：

git clone https://github.com/asadani/output-contracts.git
cd output-contracts
out_dir="$(mktemp -d)"

python -m output_contracts validate \
  fixtures/handoff-contract.json fixtures/handoff-bad.md \
  --format markdown --out "$out_dir/handoff-review.md"

python -m output_contracts inspect fixtures/handoff-contract.json

注意 inspect 那一行：它检查的是契约本身，并输出规范化摘要。前面的 validate 则会指出缺失章节、顺序错误和禁用短语。

退出码让调用脚本能够区分三种结果：0 表示通过，1 表示输出违反契约，2 表示契约无效、输入不可读或命令出错。内容被拒收，与校验过程根本没跑成功，需要走不同的处理路径。

JSON 示例也提供了正反两组输入：

python -m output_contracts validate \
  fixtures/result-contract.json fixtures/result-bad.json \
  --format json --out "$out_dir/bad-result-review.json"

python -m output_contracts validate \
  fixtures/result-contract.json fixtures/result-good.json \
  --format markdown --out "$out_dir/good-result-review.md"

注意两条命令的 --format：同样检查 JSON 输入，报告分别输出为 JSON 和 Markdown；坏样例返回 1，好样例返回 0。

作者建议把校验放在下一位工程师或程序消费输出之前，保存报告，再将违规项交回修正。这比只在提示词里写一句「严格遵守格式」多了一道可执行的验收。

我的判断

我赞同把反复发生的交接失误写成规则，但规则必须和工具能力匹配。

当前 Markdown 检查只识别围栏代码块之外的 ATX 标题，也就是以 # 开头的标题，不把加粗文字或 HTML 当作标题。禁用模式却会扫描全文，包括代码块。因此，教程只是引用 Everything is complete.，也可能被拒收。

禁止这句话只能约束措辞，无法判断工作是否完成。要求存在 Evidence 章节，也不能保证里面的证据是真的。

结构检查可以自动化，事实审查仍要单独进行。

另一个前提是契约作者可信。复杂正则没有沙箱，也不保证线性运行时间，不适合把任意外部规则直接交给它执行。

如果团队需要通用 JSON Schema 校验，成熟校验器可能更合适。这个 MIT 许可项目的定位，是同时需要 Markdown 报告检查和少量 JSON 字段约束的有限工作流。原文给出了样例行为，没有提供团队效率、误报率或替代方案的对照数据；收益判断仍属于经验建议。作者也披露文章由 AI 辅助起草，依据是项目代码和样例。

能拿来做什么

为 AI 生成的交接文档先约束必需章节和顺序，从最常漏掉的一项开始，并同时准备通过与失败样例。
在 Node 或其他调用脚本消费结果前运行校验，分别处理退出码 0、1、2，保存报告供修正时定位问题。
对 JSON 中会直接影响后续处理的字段检查类型、允许值和数组长度，同时保留业务层面的真实性检查。
给教程和工作交接分别制定禁用模式，观察代码示例等位置是否出现误报，再决定是否增加规则。