AI 编程与开发

用 Codex 改善导入报错：位置、原因和下一步

导入失败后，程序只留下一个错误代码。知道失败了，却不知道要检查哪条记录，也不知道能不能直接重试。

接着预览过期检查的自建 JSON 库存教学项目，这次给失败结果加一个只读说明器。它读取失败输出，保留原始代码，并对约定内的错误补充位置、原因和下一步；它本身不执行导入、不修改输入，也不自动重试。

从错误代码到下一步

教学导入程序可能返回：

1
{"ok": false, "action": "preview", "error": "batch[2].stock:invalid_range"}

说明器保留 error_code，并将已知格式整理为：导入批次的第 2 条记录、stock 字段，原因是库存值小于零；先核对该记录，修改后重新校验并生成新预览。这里的数字是 JSON 数组中的记录序号，从 1 开始，不是文件物理行号。

如果原文件或批次在预览后发生变化，说明器提示核对当前输入，再用新计划名重新预览，不执行旧计划。对于不认识的代码，它保留原文、将 recognized 标为 false，不猜位置或编造修复办法。

这些错误代码和解释规则是本项目自定的教学格式，不是 Codex 或 API 的通用错误规范。re.fullmatch 在这里用来匹配整个约定格式；匹配失败时不能直接读取分组。Python 文档：re.fullmatch

交给 Codex 的任务

1
2
3
4
5
给自建 JSON 导入教学项目增加只读错误说明器。
保留原始错误代码；对已知格式补充来源、记录序号、字段、原因和下一步。
记录序号不是文件行号。未知格式保留原文，不猜位置或自动修复。
说明器不执行导入、不修改输入、不自动重试；不要据此断言业务文件状态。
测试已知错误、未知及部分匹配的格式，并核对输入文件是否被说明器改动。

这是一份可按项目调整的任务，不是功能保证。官方的 Codex 提示词指南也建议交代期望行为、相关上下文、约束和验证方式。

下载后自己检查

下载说明器、四份输入样例及验收测试

解压到新目录，在 PowerShell 中运行：

1
2
3
4
5
6
python -B test_report_errors.py
python -B report_errors.py examples/invalid-stock.json
$LASTEXITCODE
python -B report_errors.py examples/changed-store.json
python -B report_errors.py examples/changed-batch.json
python -B report_errors.py examples/unknown-synthetic.json

第一份应定位到 batch 的第 2 条记录和 stock 字段；未知错误应保留原始代码且没有位置。前三份输入来自教学导入程序的实际失败输出，第四份未知错误是人工构造的验收夹具。下载包还保留教学导入程序和样例；要运行其提交命令时，只能使用明确可替换的测试副本。

说明器退出 0 只代表说明生成成功，不代表原导入成功；输入不是有效失败对象、缺少错误代码或无法读取时，说明器退出 2。它没有检查业务文件，文件是否变化仍须独立核验。JSON 解析和测试断言分别参考 Python json 与 unittest。

本次验证与边界

2026 年 10 月 29 日，在 Windows / Python 3.13.5 完成 8 项验收，并整理 3 份教学程序实际失败输出和 1 份人工构造的未知错误；四次整理前后，输入结果和场景文件未被说明器修改。2026 年 11 月 1 日重新运行说明器的 8 项验收，全部通过；官方资料亦于当日复核。

本例只覆盖约定格式，没有验证真实库存、任意报错、自动修复、性能、费用或并发安全，脚本没有调用 API。教学代码与文章含 AI 辅助。

本文发表日期：