一份CLI使用手册,我把两周的文档活儿压进了两个晚上
·ThisToken.AI·
AI Best PracticesAI最新实践ThisToken.AI
一个常见的场景
你写了一个 CLI 工具,功能不少,命令二十多个,参数五花八门。用户的第一个问题永远是:「这个工具怎么用?」
于是你要写使用手册。对独立开发者和小团队来说,这几乎是世界上最不划算的活儿:
- 写代码花了两周,写文档还得再花两周。 而且写文档没有写代码爽。
- 手册写完那一刻就开始过时。下个版本改了参数,文档没人更新,用户照着旧手册敲命令,报错,然后在 issue 区开喷。
- 团队里最懂工具的人恰恰最没时间写文档。最后文档往往是“能看懂的人本来就不需要看”的水平。
我自己的体验:一份覆盖 20 个命令的手册,第一版大概要 10~15 个小时的专注时间,还不算后续维护。这还是在我对工具了如指掌的前提下。
这篇文章讲的是:AI 能在这件事里承担多少,以及怎么把它变成可复用的流程。
先明确:AI 能做什么,不能做什么
AI 能做的:
- 从代码里提取命令清单。 你把 CLI 的入口文件、参数解析代码丢给它,它能整理出完整的命令、参数、默认值表格。这一步原本是最枯燥的“体力活”,占整个写作时间的 40% 以上。
- 生成每个命令的标准结构文档。 用法、参数说明、示例、常见报错——AI 按统一模板批量生成初稿,你只做校对。
- 把报错信息翻译成人话。 用户看不懂
ERR_PIPE_BREAK是什么意思,AI 可以基于你的错误处理代码生成对应的排查指引。 - 持续维护。 版本更新后,把 diff 丢给 AI,让它标出手册里需要同步修改的段落。这一步能把文档维护从“想起来才做”变成“顺手就做”。
AI 不能做的:
- 它没用过你的工具,不知道哪些参数组合在实际中容易踩坑。这部分“实战经验”必须由你补充。
- 它会自信地编造不存在的参数。所有 AI 生成的命令示例必须实际跑一遍,这是底线,没有例外。
具体流程:两个晚上怎么分配
第一晚(约 2~3 小时):搭骨架
- 整理素材:CLI 入口代码、
--help输出、参数定义文件。如果你用 argparse / click / cobra,直接把定义文件给 AI,结构最清晰。 - 用提示词模板(见下文)让 AI 生成全量命令的文档初稿。
- 逐条跑示例命令,删掉跑不通的、修正输出不一致的。
第二晚(约 2 小时):填血肉
- 把你在用户群、issue 区里反复回答过的问题,手动补进 FAQ。这部分 AI 生成不了,但价值最高。
- 让 AI 从用户视角通读手册,列出“解释跳跃”的地方——它扮演一个第一次接触工具的读者,效果出奇地好。
- 定稿,发布。
提示词模板
直接可复制,把方括号内容替换成你自己的:
你是一位技术文档工程师。请为我的 CLI 工具生成使用手册初稿。
## 工具信息
- 工具名称:[名称]
- 工具用途:[一句话说明]
- 目标用户:[如:独立开发者 / 运维人员]
## 命令定义
[粘贴 argparse/click/cobra 的参数定义代码,或 --help 的完整输出]
## 要求
1. 手册结构:
- 快速开始(5 分钟内能跑通第一个命令)
- 命令参考(每个命令包含:用途、语法、参数表格、1-2 个可运行示例、常见报错及排查)
- FAQ(基于参数的常见误用)
2. 每个示例命令必须只使用上文定义过的参数,禁止推测不存在的参数。
3. 参数说明中标注默认值和取值范围。
4. 语言风格:直接、简短,不用营销语气。
5. 不确定的地方用 [待确认] 标记,不要编造。
先输出手册目录结构给我确认,再逐节输出内容。最后那句“先输出目录”很关键——目录不对就重来,比全文写完再改省太多时间。
前后对比
| 环节 | 纯手写 | AI 辅助 |
|---|---|---|
| 命令清单整理 | 2~3 小时 | 20 分钟(AI 生成 + 人工核对) |
| 每个命令的初稿 | 平均 20 分钟/个 × 20 个 ≈ 7 小时 | 约 1 小时(批量生成 + 校对) |
| 示例验证 | 1 小时 | 1 小时(这步不能省) |
| FAQ 撰写 | 2 小时 | 2 小时(人工为主) |
| 版本更新时的同步维护 | 每次 1~2 小时,经常被跳过 | 每次 20 分钟,diff 交给 AI 定位 |
| 首次成稿总计 | 约 13~15 小时 | 约 4~5 小时 |
时间账之外还有一笔隐性账:手写手册的结构往往不统一(写到第十个命令就累了),AI 生成的结构天然一致,后续新增命令照模板补就行。
几个容易翻车的点
- 别让 AI 直接“读”你的整个仓库。 与其让它猜,不如你先把参数定义代码剪出来。喂得越准,产出越准。
- 示例必须实跑。 AI 生成的示例命令里大约有一到两成存在细节错误(参数拼写、路径假设),全量验证是唯一可靠的办法。
- FAQ 别外包给 AI。 真实用户问过的问题,比 AI 想象出来的“常见问题”有价值得多。
- 保留“[待确认]”机制。 强迫 AI 承认不确定性,能显著降低编造率。
写在最后
CLI 工具的文档长期处于“重要但不紧急、所以永远没空写”的状态。AI 辅助流程的意义不是让文档变得更华丽,而是把成本压到“顺手就能做”的水平——首稿时间砍掉三分之二,维护成本降到可以随版本发布同步更新的程度。
如果你在自己的工作流里大量使用 AI,模型调用成本也值得认真算一笔账。接入多模型平台、按任务选合适的模型,是控制成本的常见做法,可以看看 https://api.thistoken.ai/register,注册后即可按需调用多种模型,具体以官网价格页为准。
---
想直接跑通示例?访问 https://api.thistoken.ai/register 注册 ThisToken.AI,获取 API Key 后即可开始。