智能命令工具原型怎样变成可用功能
原型只会输出一句建议;可用功能还要有输入校验、预览和失败出口。我给命令加了 --dry-run,默认不改文件。
tool rename demo.md --dry-run
输出为 JSON 时先用 schema 校验,解析失败就停止。模型只读取当前文件,不能递归扫描目录。人工确认差异后才执行写入,这条流程比“自动完成”更可靠。
先把命令的责任范围说清楚
命令行工具最容易被低估的地方,是它把“看一眼结果”和“改掉一批文件”放在同一个入口里。rename 这种名字看起来很普通,实际会碰到目标文件是否存在、同名冲突、软链接、只读目录,以及一次操作中途失败后怎样恢复。原型阶段通常只演示了路径替换;到了交付阶段,先要决定哪些情况工具根本不碰。比如输入不是普通文件、目标落在工作目录外、扩展名与约束不符,就在参数解析阶段报错,不要等写入发生后再解释。
我会把一次执行拆成计划和应用两个对象。计划里只保存源路径、目标路径、冲突原因和预计动作;它可以打印,也可以序列化给测试读取。真正写文件的函数只接受已经确认过的计划,不再自己猜路径。这样 --dry-run 不是额外复制的一套分支,而是自然停在计划阶段。测试也能直接断言计划:同名时是跳过还是报错,大小写变化在当前文件系统上是否安全,多个重命名之间有没有形成环。
差异要让人能读懂
预览不能只显示“将修改 12 个文件”。我更愿意按操作逐行列出 旧路径 -> 新路径,并把跳过项和原因放在后面。用户看见目标已存在,才能决定改参数、先清理目录,还是明确选择覆盖。若工具支持覆盖,覆盖必须是单独的开关,不能被 --yes 顺带打开。脚本环境里可以使用 --yes 省去确认,但默认交互命令应把计划完整打出来。
原子性也要按能力如实表达。同一文件系统内的单文件改名通常可依赖系统调用完成;跨目录、批量交换名称或跨设备移动则未必如此。遇到后一类操作,我会先在计划里检测环和跨设备情况,把临时名称、执行顺序写清楚。执行过程中每完成一步记录一条结果;失败时报告已完成的动作和未执行的动作,不假装已经自动回滚。是否提供回滚命令取决于工具能否可靠记录旧状态,不能为了界面好看而承诺做不到的恢复。
用边界用例验收,而不是只跑一次成功样例
这类工具的测试不需要连接真实目录。每个用例在临时目录创建几个文件,再断言最后的目录树和命令输出。最基本的一组包括:单文件改名、目标冲突、空匹配、只读文件、两个名称互换、执行到一半模拟失败,以及 dry-run 后目录完全不变。对于 Windows 与 macOS 的大小写差异,测试名称要说明预期,不要把某台开发机的行为当成通用规则。
日志同样应克制。记录操作数量、是否 dry-run 和错误分类已经足够;不要把整个文件内容或用户目录直接写入日志。工具一旦有了明确计划、可读预览和可测试的失败出口,模型生成的建议就只是实现草稿,不能越过这些边界直接取得写权限。
把执行记录留在用户看得见的地方
一次批处理结束后,终端应给出一份简短结果:成功了哪些动作、跳过了哪些动作、失败在哪一步。它不必伪装成审计平台,但至少让用户能把本次执行和刚才的预览对上。若提供结果文件,写入前先显示路径,并避免默认存进源目录;否则工具本身又会制造新的待处理文件。
对模型参与的命令尤其要区分“建议”和“执行”。建议可以根据当前参数生成,执行只能来自已确认的计划。这样即便模型误读了文件名,错误也会停在预览阶段。把这条界线写进帮助信息和测试用例,比在出错后补一段道歉文字更有用。
563



被折叠的 条评论
为什么被折叠?



