把一张字段定义表格变成 OpenAPI 规范：在一把 key 上让第二个后端帮你校验结果

在多模型聚合的 API 里，一个 key 就能切换不同后端，这带来一个很实用的工作方式：起草和审查分开做。草案由一个模型产出，审查交给另一个模型，避免同一个模型给自己挑错时“顺拐”。下面以「把一张字段定义表格变成 OpenAPI 规范」为例，走一遍完整流程。

为什么分两个后端

同一个模型既写又审，通常会沿着自己刚才的假设往下走，对结构性问题不敏感。让第二个后端在不知道起草过程、只看到 CSV 和产出的规范时做审查，更容易发现字段类型冲突、必填项漏标、枚举取值不一致这类问题。聚合站的价值就在这里：换后端只改请求里的模型名，账号、计费、鉴权都是同一套。

第一步：把 CSV 准备干净

模型的输出质量很大程度取决于输入表格的规整程度。开始前先确认：

• 每一行对应一个字段，字段名、类型、是否必填、取值范围/枚举、说明各占一列。
• 类型列用一致的写法（如 string / integer / boolean），不要一半写「文本」一半写「string」。
• 嵌套结构用点号或路径表示父子关系（如 address.city），不要靠缩进。
• 空值含义要区分：「不适用」和「未填写」在规范里对应不同的处理。

如果表里本身有矛盾，先人工清理，不要让模型去猜。模型会替你做出一个看似合理的决定，而那个决定往往不是你想要的。

第二步：用第一个后端起草

把 CSV 原文贴进提示词，并给出明确的产出约束：

• 指定 OpenAPI 版本（如 3.0.x 或 3.1.x），不同版本对 nullable、examples 的写法不同。
• 要求只输出 YAML，不要夹带解释文字，便于后续解析。
• 要求类型映射遵循固定规则，例如 CSV 里的「必填=是」映射为 required 数组中的成员，而不是字段上的布尔值。
• 要求对无法从表格推断的信息（如路径、请求方法、响应状态码）显式标注 TODO，而不是编造。

明确禁止编造这一点很重要。字段表格通常只描述数据结构，不描述接口形态；模型很容易顺手补出一个看起来很像真的 POST /users。让它标 TODO，后面的审查才有意义。

第三步：换第二个后端做审查

拿到草案后，把 CSV 原文和生成的规范一起交给另一个后端，让它扮演审查者。提示词里给出检查清单，而不是笼统地说「帮我看看有没有问题」：

• 字段覆盖：CSV 中的每个字段是否都出现在 properties 里？有没有多出来的字段？
• 必填一致性：required 列表与 CSV 的必填列是否逐项对应？
• 类型匹配：integer 与 number、string 与 format: date-time 的选择是否与说明列一致？
• 枚举完整性：枚举字段的 enum 取值是否与 CSV 中列出的完全一致，有无增删或大小写变化？
• 命名规范：字段名是否保持原样，有没有被模型「顺手美化」成驼峰或下划线？
• 结构层级：嵌套字段的父子关系是否与点号路径一致，有没有被拍平成同级字段？
• 悬空引用：$ref 指向的组件是否都存在，有没有循环引用？
• 占位符残留：所有 TODO 是否被清楚列出，而不是被悄悄填上了猜测值。

要求审查者按「问题—依据—建议」的格式逐条输出，并明确指出它引用了 CSV 的哪一行。这样你能快速判断它是真的发现了矛盾，还是在一本正经地发挥。

第四步：让起草方按审查意见修订

把审查结论回传给第一个后端，让它只做定点修改，不要重写整份文件。限定「只输出被修改的部分及其上下文」，可以显著降低它顺手改动无关字段的概率。修订完成后可以再跑一轮审查，但通常两轮就足够收敛；第三轮开始模型容易为了「找到问题」而制造问题。

常见坑

• 两个后端用同一个模型：审查会退化成自我确认，失去分工的意义。
• 只给规范不给 CSV：审查者没有比对基准，只能评风格，查不出矛盾。
• 让模型补全接口形态：字段表不包含的信息应由人补，模型补出来的路径和状态码往往是幻觉。
• 忽略版本差异：3.0 与 3.1 在可空写法和 examples 结构上不同，混用会让规范在校验工具里报错。
• 不做机器校验：模型审查之后再跑一次规范校验工具（如 Swagger 系列的 validator），语法层面的错误交给工具更可靠。

一点成本视角

这种「起草 + 审查」的双后端流程意味着同一份任务会产生两次调用。按本站的计费方式，用户按官方价 ×1.3 扣费，多一次调用就多一份消耗，所以值得把审查范围限定在真正容易出错的地方（必填、枚举、类型、引用），而不是让第二个后端做全文润色。如果你自己也向平台贡献 key，按官方价 ×1.1（优质 ×1.2）返 USDC，这部分抵扣可以用来覆盖审查环节的额外开销。