
生成了一份类型,先确认它对应哪份响应
你已经把 AIGoCode 的一次响应保存为 JSON,希望给前端或日志处理代码补上 TypeScript 类型。最容易漏掉的工作,是把“这份样本能生成类型”直接当作“所有返回都已覆盖”。
AIGoCode Tools 中的“JSON 转 TypeScript”按目录说明,可以根据 JSON 示例生成嵌套的 TypeScript 类型定义。下面关注生成之后如何人工核对和交付;这是建议的工程检查流程,不代表工具会自动找齐全部响应形态。
第一步:给样本写一张来源卡
把样本、生成结果和来源说明一起保存。来源卡建议记录协议、是否流式、取得样本的时间、用途和脱敏范围。只写模型名称不够:同一模型的两种接口或两种返回方式,可能需要分别整理。
用于分享的 JSON 应移除真实密钥、个人信息和业务正文。替换敏感值时,尽量保留原来的对象、数组层级与值的类型;如果某个字段被整体删除,在来源卡中注明,免得接手的人以为接口从来不返回它。工具目录也列出了敏感信息脱敏入口,处理后仍建议人工查看结果。
例如,来源卡可以写“Chat Completions,非流式,普通文本样本,业务文字已替换”。不要写“覆盖全部 Chat 返回”,除非你确实另有足够的协议依据和验收材料。
第二步:先列业务读取路径,再看生成结果
官方 Chat Completions 文档 说明,普通文本读取 choices[0].message.content,结束原因位于 finish_reason;工具调用按 tool_calls 处理,用量位于 usage。
建议先列出应用真正读取的路径,而不是直接接受整份生成结果:
| 应用要做的事 | 应检查的材料 | 验收问题 |
|---|---|---|
| 展示普通回复 | 普通文本响应与读取代码 | 类型中的对象、数组层级能否对应到实际读取路径? |
| 记录结束原因 | 响应中的结束字段 | 代码读取的是哪一层字段,是否保留原值? |
| 处理工具调用 | 另有工具调用资料时单独核对 | 是否误把普通文本样本当成完整的工具调用结构? |
| 记录用量 | 实际出现的 usage 样本 | 样本未出现的字段,是尚未观察到,还是有文档明确说明? |
只负责展示文字的组件,不必因为样本里出现许多字段就承诺处理全部内容。反过来,业务需要记录用量时,样本没有 usage 就应标记资料缺口,不能自己补一个看似合理的完整结构。
第三步:用人工对照表处理样本差异
先保存第一份生成结果,再收集已有的、合规可用的其他样本逐项对照。下面是一张建议的检查表,不是对该工具合并算法的说明,也不要求为了凑样本额外发起付费调用。
- 字段只在一份样本出现:记录出现条件,回查文档或调用场景,再决定类型与读取代码如何处理缺失。
- 字段出现空值:把空值和字段根本不存在分开记,不替接口推断两者永远等价。
- 数组在样本里为空:记录“尚无元素样本”,不要凭空补出业务上期待的元素字段。
- 多份样本的同名字段形态不同:先检查是不是混入另一协议、流式事件或错误响应,再考虑业务类型设计。
这里的目标是把未知项显露出来。如果暂时只有一份普通文本样本,就把交付范围限定为它,留下“工具调用结构待核对”等明确待办,优于给文件起一个暗示全量覆盖的名称。
第四步:把流式和非流式分开验收
官方文档给出的 Chat 流式处理方式,是从事件的 choices[].delta 读取新增内容,data: [DONE] 表示流结束。它还提醒,Responses 使用另一套事件结构。
因此,整理非流式 JSON 时,不要顺手把生成结果当成流式事件类型。建议为两者分别保留样本说明、类型文件和读取路径;如果当前只实现了非流式,就在交付记录中明示这一范围。响应取文字的基础问题可先参考本站三种响应结构解析指南,再回到本稿核对类型材料是否完整。
最后交付四样材料
建议交付脱敏样本、生成后经人工检查的类型、应用读取路径清单、尚未核实的差异表。让接手者能够沿着“样本—类型—读取代码”追溯,而不是只收到一份无法解释来源的文件。
项目若已有类型检查和响应处理测试,把这些材料放入现有验证流程;另行核对实际输入处理与错误分支,不能仅凭生成了一份类型就宣布接口验收完成。本文未进行新的 API 调用,也不把文档示例当成本次实测记录。