CLI工具的说明书一直没人看——我让AI把它改写成会说话的助手
一个管理者视角的老问题
如果你带过小团队，一定见过这样的场景：新人入职第一周，最常问的问题不是业务逻辑，而是“这个命令怎么用”“上次那个报错在哪份文档里查”。你们团队的CLI工具——可能是内部脚本，也可能是开源工具的二次封装——往往只有一份当年随手写的README，或者干脆只有代码里的注释。
文档没人写、没人看、没人维护，这是三重困境。对管理者来说，它带来的不是某个具体损失，而是持续的协作摩擦：上手周期长、重复答疑占用老人时间、误操作引发线上问题。更要命的是风险控制——当工具的用法只存在于某几个人脑子里，人员一旦流动，知识就断档。
我最近的实践是：用AI把一份静态的CLI使用手册，改造成“按需生成、持续更新、可以对话”的辅助体系。整个过程不需要写一行传统文档。
用户痛点先摆清楚
在动手之前，我把团队（几个人规模）的问题归了三类：
第一，文档覆盖不全。 工具迭代快，参数增减、行为变更，README永远落后于实际版本。人工补文档的成本，小团队根本付不起。
第二，答疑是黑洞。 同一个问题被不同人问五遍，回答的人烦，问的人也不敢多问。没有一个统一、可信、随叫随到的入口。
第三，风险不可控。 有些命令是危险操作——删除数据、覆盖配置、触发部署。新人在不理解后果的情况下照抄网上的命令，出了问题才发现手册里根本没写警示。
这三条，本质上都不是“文档写得不好”，而是静态文档这个形式本身，匹配不上动态的工具和不断变化的用户。AI的价值恰恰在这里：它可以基于工具的实际信息（--help输出、源码、变更记录）实时生成答案，而不是依赖一份过时的手稿。
我搭的AI辅助流程
整套流程分四步，管理者只需要把控两端：输入质量和审核标准。
第一步：收集原料。 把CLI工具的--help全文、子命令列表、源码中的docstring、changelog统一丢进一个目录。这一步是人工的，但只做一次，且不需要任何写作能力。
第二步：建立知识库。 用支持文档问答的AI服务，把上述原料作为知识源接入。市面上不少API平台都提供这类能力（价格以官网价格页为准），小团队按量付费即可，成本可控。
第三步：定义问答规范。 这是风险控制的关键。我在系统提示词里明确约定：AI必须区分“安全命令”和“危险命令”，危险命令必须附带影响说明和确认步骤；AI不确定时要明确说不知道，禁止编造参数。
第四步：接入团队工作流。 最简单的形态是聊天机器人群；进一步可以做成CLI内部的--ask子命令，让求助发生在使用现场而不是切出去问人。
一个可直接复制的提示词模板
这是我给团队知识库用的系统提示词，你可以按需替换占位符：
你是「{{工具名}}」的使用助手，服务对象是团队内的开发者。
【知识来源】
你只能基于以下材料回答问题，禁止编造不存在的参数或命令：
1. 工具的 --help 输出（版本：{{版本号}}）
2. 子命令说明文档
3. changelog
【回答规则】
1. 每次回答先给出完整可复制的命令示例，再用一句话解释关键参数
2. 涉及危险操作（删除、覆盖、发布、改配置）时：
- 必须在回答开头用【风险提示】标注
- 必须说明该命令的影响范围和是否可逆
- 必须建议先在测试环境验证
3. 如果知识来源中没有相关信息，明确回答"当前文档未覆盖该问题，
建议联系工具维护者"，不要猜测
4. 用户问题描述模糊时，先反问确认使用场景，再给命令
5. 回答末尾注明信息依据的文档版本，便于排查过时答案
【风格】
简洁，命令优先，解释不超过三句话。这套提示词的核心思路是：把管理者的风险要求编码进AI的行为约束里，而不是依赖使用者自觉。
用AI前后对比
上手时间： 之前新人熟悉内部CLI平均要翻聊天记录、问同事、试错，往往两三天才能独立操作；接入AI助手后，常见问题当场解决，第一天就能执行基础命令。这是流程上的质变，不是速度上的微调。
答疑负载： 之前维护者每天被打断多次，碎片化答疑既低效又容易漏掉警示；之后重复问题由AI承接，维护者只需要处理AI回答不了的边界问题，且这些问题往往正是文档该补的地方。
风险控制： 之前危险命令靠口头提醒，谁忘了谁担责；之后风险提示内嵌在每次回答里，且AI被明确禁止编造参数，"幻觉命令"这类隐蔽风险被前置拦截。
文档维护： 之前改完代码没人更新文档；现在维护者的习惯变成"改完代码顺手更新--help和changelog"，因为那是AI的知识源——文档从"给人看的负担"变成了"喂AI的原料"，维护动力完全不同。
管理者需要注意的边界
几点提醒：其一，AI回答的准确性取决于原料质量，垃圾进垃圾出，--help写得含糊，AI也无能为力；其二，危险操作的最终防线仍应是工具本身的确认机制，AI提示是辅助不是替代；其三，定期抽检AI的实际回答，把它当作一个需要考核的新员工，而不是放养的黑盒。
对小团队来说，这套方案的成本几乎只有初始搭建的半天时间。如果你想动手试试，需要一个稳定的大模型API服务作为底座，可以看看这个平台：https://api.thistoken.ai/register，注册即可接入多种模型，把上面那套流程快速跑起来。
---
本文的示例只需一个 API Key 就能复现：在 https://api.thistoken.ai/register 注册即用。