Microsoft Copilot写命令行工具说明总是帮助信息难懂，提示词怎么补充

用 Copilot 写命令行工具的帮助信息，最让人头疼的地方在于：它生成的说明文档看着很“完整”，真要上手用起来，却总觉得隔了一层。术语堆砌得严严实实，可关键参数怎么组合、什么场景该用哪个选项，通通语焉不详。这口锅不该让模型一个人背——问题很可能出在提示词上，没有把“人类可执行”的输出标准锚定清楚。

咱们先从最基础的问题说起。

锁定角色和输出边界，是第一道防线

很多人一上来就问“帮我写一下某个命令的帮助信息”，然后任由 Copilot 自由发挥。它生成的默认风格更像“教学手册”，解释起 --verbose 来恨不得把“用于调试网络请求失败场景”这种上下文都塞进去。但真实的 CLI 帮助文档里，对应的行文通常是：

——简洁、直接、没有任何多余的温情。

正确的做法是，在提问的第一句就明确身份和交付物。比如说：“你是一个资深 CLI 工具文档工程师，只生成符合 GNU 标准的帮助信息（--help 输出），不解释、不举例、不加空行，严格按‘Usage → Options → Examples’三级结构输出。”

这一句指令下去，Copilot 输出的语义空间就被牢牢收紧了。不做这一步，它很容易滑向“教学式说明”，把帮助文档写得像安全手册一样冗长。

强制约束帮助信息的字段粒度

锁定格式之后，还需要控制每个字段的“颗粒度”。这里有两个可操作的方向。

直接输入：“按以下结构生成 --help 内容：Usage: {tool} [OPTIONS] {SUBCOMMAND}；Options: {短选项}, {长选项} {单行说明}；Examples: {一行可复制粘贴的命令}。现在为 ‘git sync’ 子命令生成。”

追加一条指令：“删除所有‘注意’‘提示’‘建议’字样；删除任何带‘可以’‘可能’‘通常’的模糊表述；每个选项说明控制在12个汉字以内。”

这两步不做，Copilot 大概率会往帮助信息里塞进“该选项在 CI 环境中慎用”这类警告。帮助文档不是安全手册，多出来的那些“关怀”只会让用户在快速检索时多花三秒钟。

用真实操作路径校准语义

结构和格式都对了，但最后还有一个更隐蔽的坑：语义对不上。举个例子，你执行 curl -X POST --data-binary @payload.json https://api.example.com/v1/submit 时，不确定 --data-binary 是否支持管道输入。如果你只问“生成 curl 的 --data-binary 选项帮助行”，Copilot 大概率会写“读取文件内容作为请求体”，可问题是，这个表述根本对应不上 @- 这种实际符号。

要解决这个问题，需要把提示词从“生成什么”升级为“生成什么，并以什么为参照”。具体拆成三步走：

第一步，回忆你最近一次被卡住的具体命令场景。第二步，把这个问题转化成 Copilot 能解析的动词指令：“生成 curl 的 --data-binary 选项帮助行，重点说明它是否接受 stdin（即 cat payload.json | curl --data-binary @-）。”第三步，要求它对比 GNU coreutils 风格写法：“参考 dd 命令的 --if=FILE 帮助格式，用相同颗粒度写 --data-binary。”

不绑定真实操作路径，Copilot 输出的帮助信息再规范，也会停留在“知道怎么查”的阶段，而达不到“拿到就能跑”的效果。这才是“可执行”的真正含义：不是格式对，而是语义对。