从实际代码生成命令说明草稿：给模型什么证据

命令行说明最容易出现一种小错：选项名写对了，行为却写成了开发者希望它做到的样子。例如 –dry-run 在实现中只跳过写文件，说明却声称“不会产生任何副作用”。如果命令仍会访问网络或执行准备脚本，这句承诺就不成立。

AI 适合整理参数和组织示例，前提是交给它的材料足以解释命令的实际路径。只给帮助文本，模型能改写帮助文本；要说明真实行为，还得读参数的使用处。

先锁定入口和版本

同一个仓库可能有开发入口、打包入口与兼容命令。先确认用户会执行哪个程序、哪个版本、哪个子命令，再读取对应参数定义。否则模型可能把开发脚本里的选项写进正式安装包说明。

证据包应保留目标提交、入口路径、参数解析片段和相关处理函数。包管理配置能帮助定位入口，但不能直接证明安装后的环境可用。若没有打包验证记录，就只说明源码中的入口映射，不写“安装后即可直接运行”。

代码示意：

if args.dry_run:
return plan_changes()
apply_changes(plan_changes())

它只能确认此分支没有调用 apply_changes。plan_changes() 是否读网络、创建临时文件或调用其他程序，仍需继续看实现。示例不是某个真实命令的代码，也不能作为任何项目的安全保证。

参数表要来自定义，也要经过使用处

参数名称、类型、默认值、是否可重复，通常能从解析器定义里提取。是否必填、互斥和依赖条件，可能还在后续校验里。例如解析器允许省略 –output，但某个子命令会在运行前检查它是否存在。

默认值也可能来自环境变量或配置文件。说明应区分“解析器默认值”和“最终生效值”。如果两者不同，把读取优先级写清楚，比在参数表里填一个看似确定的值更准确。

不要把所有布尔参数写成同一种形式。有的参数是开关，有的接收明确的真假值，有的还有反向选项。以实际定义为准，必要时同时核对命令的帮助输出与源码，发现不一致时标为待维护事项。

示例命令应该解释它会做什么

一个好示例不必覆盖全部参数。选一个最小任务，说明输入来源、输出位置和可能发生的修改。涉及覆盖、删除或外部服务调用的选项，应在示例旁交代前提条件，别把它们藏在长参数表里。

如果只是从代码生成草稿，示例标为“用法示意”，不要附上伪造的成功日志。真实运行记录则应包含版本、工作目录、环境与退出状态。某次在特定环境里运行成功，也不能自动推广为所有平台都支持。

路径示例使用中性目录，令牌用占位说明，不嵌入真实秘密。占位文本必须显眼，不能写成一个看起来可直接使用的有效凭据。若参数会把秘密留在命令历史里，也应根据工具支持的输入方式说明更合适的传递渠道。

错误与退出状态也属于接口

用户执行失败时需要知道下一步。说明草稿应从错误分支中提取可确认的信息：输入不存在会怎样，权限不足在哪里暴露，网络失败是否重试，输出已存在时是拒绝还是覆盖。

若代码没有明确的退出码约定，不要替它设计一套表再写成现有行为。可以把约定缺失列为维护建议。类似地，异常消息里有“timeout”不代表所有超时都会走同一处理路径，需要看捕获范围。

生成草稿时，内部可以先用“说明句—源码位置—验证状态”三列核对。面向读者的文档不必展示全部内部记录，但维护者应能回到依据。这样后续参数变化时，也知道哪些说明受影响。

最后删掉没有依据的方便话

“适用于所有环境”“不会修改任何内容”“自动恢复”“兼容旧版”都很省字，却需要较强证据。逐句问：是实现分支直接证明了它，还是有运行记录支持，抑或只是常见工具的习惯？后一种就不能写进这个项目的现状说明。

我更愿意交付一份范围清楚的命令草稿：哪些参数已确认、示例做什么、哪些环境未验证。等真实执行和打包核验补齐，再把相应结论写进去。这样的文档能随着代码维护，也更少让用户在终端里碰运气。