工具脚本可用性自检表

工具脚本类商品常被当作小件，验收也随意：跑一次没报错就算通过。但脚本真正的风险在边界输入和重复执行上，这两类问题在演示时几乎不会出现，却会在真实使用中反复咬人。下面这份自检表按四项组织，适合发布前自审，也适合接收他人脚本时核对。

一、输入边界
先把脚本接受的输入分成必填、可选、环境推断三类，逐类写出合法范围。然后构造极端输入：空值、超长文本、含特殊字符、格式正确但语义无效、数量为零、数量极大。观察脚本是明确拒绝、给出可读提示，还是带着异常值继续执行。合格的表现是：非法输入在入口处被拦下，提示说明哪里不对以及期望什么格式；合法但异常的输入有明确处理策略，例如分批、截断或跳过并记录。还要检查路径类输入是否处理了相对路径、含空格路径、不存在路径三种情况，这三类在实际使用中占比很高。

二、失败处理与可观测性
人为制造失败：目标文件被占用、网络中断、权限不足、中途被强制终止。观察脚本留下什么状态：是干净退出、留下半成品，还是留下锁或临时文件导致下次无法运行。自检要点是每个可能失败的步骤都有对应的处理分支，失败时输出足够定位的信息但不泄露敏感内容，且退出状态能反映成功与否。对于耗时较长的脚本，应有阶段性进度输出，让人能判断它是在工作还是卡住了。静默运行很久没有任何输出的脚本，排查成本极高。

三、幂等与重复执行
同一个脚本连续执行两次会发生什么？这是最值得测的一项。检查写入类操作是否有覆盖判断，追加类操作是否会重复累加，创建类操作是否会因已存在而报错。理想状态是重复执行结果一致，或者第二次执行明确提示“已存在，跳过”。对于无法做到幂等的操作，应在执行前做存在性检查，或提供显式的强制参数。把这一条写进说明文档，能避免大量重复执行导致的脏数据。

四、参数与可读性
参数设计遵循少而明确的原则：必填参数不设默认值，可选参数有合理默认并在帮助信息中写明，互斥参数在执行前校验而不是执行到一半才报错。帮助信息应包含一个可直接复制的最小示例，示例要真实可跑。代码层面看三点：命名是否表达意图、关键分支是否有注释说明原因而非重复代码、是否存在复制粘贴形成的大段重复逻辑。可读性不是为了好看，而是为了让下一个人敢改。

五、交付清单
交付时附带一份简短说明：用途一句话、依赖与版本、最小示例、参数表、已知限制、失败时的排查顺序。已知限制这一项最容易被省略，却最能减少误解。把上述五项过完，再让一个没写过这个脚本的人按说明跑一次，记录他卡住的地方并补进说明，脚本才算真正可用。