工具脚本复盘模板：输入输出契约法

脚本类商品最常见的纠纷不是“功能没实现”，而是“换了个环境就不对”。根源往往在于输入输出的约定没有被写清楚。复盘模板以契约为中心，把脚本当成一个有明确边界的小系统来检查。

输入契约：把假设写出来
先列出脚本接受的全部输入：参数、配置文件、环境变量、标准输入、以及它读取的文件路径。每个输入记录四项：是否必需、允许的取值形态、缺省行为、非法值时的表现。很多脚本的问题出在“缺省行为”这一栏——省略某个参数时它到底用默认值、还是去猜、还是静默跳过，必须写明。同时记录输入的来源优先级，避免同一项被多处覆盖时行为不可预期。

输出契约与失败处理
输出包括标准输出、生成的文件、退出状态、以及日志。模板要求分别写明：成功时输出什么形态、部分成功时如何标识、失败时是否留下半成品。退出状态要区分“参数错误”“环境不满足”“执行中断”“结果不符合预期”等类别，便于调用方判断。失败处理部分重点检查三件事：是否在动手前完成前置校验；中断时是否清理临时产物；错误信息是否指出下一步该看什么。错误信息里只写可操作提示，不写内部实现细节。

可重复运行与边界场景
脚本能否重复执行是可靠性的关键。模板要求逐项确认：重复运行时是否覆盖、追加还是报错；是否存在依赖上一次残留状态的行为；并发执行时是否互相干扰。边界场景记录空输入、超长输入、路径含特殊字符、目标不存在、权限不足这几类，每类写明当前表现与期望表现。期望与现状不一致的，直接转为改进项。

使用步骤与注意点
执行复盘时按“输入—输出—重复运行—边界”的顺序填，最后汇总改进项并按风险排序。注意四点：契约描述只写行为，不写实现方式，方便后续重构；每条缺省行为都要有明确结论，不允许“视情况而定”；错误信息检查以“使用者能否据此自助排查”为标准；改进项要写成可验证的句子，例如“缺少必需参数时以特定状态退出并给出提示”。脚本类商品的信任来自可预期，契约写得越清楚，使用方的试错成本越低，复购与推荐也就越稳。