新人三天能上手CLI工具？我把使用手册这件事也交给了AI
一个管理者的老问题：文档永远追不上工具
带过小团队的人对这一幕都不陌生：新同事入职，丢给他一份 CLI 工具文档，三天后他还在群里问“这个命令的参数是什么意思”。老文档是两年前写的，工具已经迭代了十几个版本；命令帮助输出越来越长，--help 刷满两屏没人看完；Wiki 上的笔记五花八门，有的过时了，有的是某个人的个人习惯写法。
我负责的团队里有几套自研和开源混用的 CLI 工具。过去我们处理这个问题的方式是：指定一个人“负责文档”。结果是这个人永远在忙别的，文档更新永远排不进迭代计划。直到有一次线上事故——新人用了一个废弃参数，把测试环境的数据清了——我才下决心把“使用手册”这件事流程化，而 AI 在其中扮演的角色，远不止“帮我写几段文字”这么简单。
先说清楚：AI 在这件事里到底能做什么
管理者视角下，AI 辅助写手册不是让 AI 一次性生成一份文档完事，而是让它承担四个环节里的具体工作：
1. 信息采集环节：把散落的入口收拢
把 --help 输出、README、变更日志、群聊里的 FAQ 记录、甚至历史工单描述，全部喂给 AI，让它归类整理：哪些是核心命令，哪些是冷门参数，哪些是历史遗留已经废弃。这一步过去要人肉做一两天，AI 几分钟给出结构化的初稿。
2. 结构设计环节：按用户角色分层
好的手册不是命令大全，而是分层的。AI 可以根据团队的角色（新人 / 日常使用者 / 管理员）生成三套不同深度的路径：新人只需要“五个命令走通主流程”，管理员才需要看配置和权限相关内容。
3. 内容生成环节：例子比参数表重要
参数表工具自己会输出，人真正缺的是“我想做 X,该怎么组合命令”。让 AI 基于命令定义生成场景化示例，并标注每个示例的适用前提和风险点。
4. 审校环节：风险控制的关键防线
这是管理者最该关注的一步。让 AI 专门做一轮“危险命令审查”：标出所有有删除、覆盖、写操作、影响环境状态的命令，强制在文档中加上警示标签和回滚说明。前面提到的那次事故，本质上就是缺了这一层。
我们的流程长什么样
落地后的流程分五步，每步都有明确的产出物和责任人，避免“AI 写的东西没人背书”的常见坑：
- 收集：责任人把工具的
--help、README、changelog、FAQ 汇总到一个目录。 - AI 整理：用提示词模板（见下文）生成手册初稿，按角色分层。
- 人工审校：工具的维护者逐条核对命令和参数是否仍然有效，重点核对 AI 生成的示例是否能真实跑通。
- 风险标注：AI 做危险操作审查，人工确认警示标签，补充回滚方案。
- 版本绑定：手册版本与工具版本绑定，每次工具升级 changelog 变更时，把 diff 喂给 AI 做增量更新，再走一遍快速审校。
这套流程的关键在于：AI 负责体力活和覆盖率，人负责准确性和签字。管理者要控的风险就两个——文档错误误导新人，以及危险命令没有警示。流程第 3、4 步就是专门堵这两个口的。
可复制的提示词模板
下面是我们在第 2 步使用的核心提示词模板，直接替换方括号内容即可：
你是一名资深技术文档工程师。请基于我提供的材料，为 CLI 工具「[工具名] v[版本号]」编写一份分层使用手册。
【材料】
1. --help 完整输出：[粘贴]
2. README / changangelog：[粘贴或粘贴链接内容]
3. 团队常见问题记录：[粘贴]
【输出要求】
一、按三类读者分层组织：
- 新人上手：5 个以内命令走通主流程，每步附完整示例和预期输出
- 日常使用：按任务场景组织（如"批量处理""查询""导出"），而非按字母序
- 管理员：配置、权限、环境变量说明
二、每个示例命令前标注：适用前提、是否有写操作、出错时如何回滚
三、单独列出一节「危险命令清单」：凡涉及删除、覆盖、批量修改的命令，
用 ⚠️ 标注并说明典型误用场景
四、列出你在整理过程中发现的：材料之间互相矛盾的地方、疑似已废弃
但未声明的参数。不要自行猜测，标记为"待人工确认"
五、语言风格：短句、命令可复制执行、避免营销化描述第 4 条特别值得强调——让 AI 主动暴露“不确定”，而不是让它把矛盾糊弄过去，这是控制文档质量风险最实用的一招。
用 AI 前后的对比
| 维度 | 之前（人肉维护） | 之后（AI 辅助流程） |
|---|---|---|
| 手册初稿产出 | 3-5 天，且常被延期 | 半天内出初稿，人工审校半天 |
| 版本更新 | 大版本才想起来改 | changangelog 驱动增量更新，当天完成 |
| 新人上手 | 一周左右，靠群里问人 | 3 天内独立完成主流程操作 |
| 危险命令警示 | 无系统性覆盖 | 100% 过一遍审查，带回滚说明 |
| 维护责任 | 集中在一个人身上，离职即断档 | 流程化，责任人只做审校，可交接 |
最直观的变化是群里“这个命令怎么用”的提问量明显下降——不是因为大家突然爱看文档了，而是文档终于按“人想做什么事”来组织，而不是按“工具有什么参数”来组织。
几点管理上的提醒
- AI 生成 ≠ 可发布。示例命令必须在真实环境跑一遍再进手册，这一步不能省，否则手册本身就成了风险源。
- 不要追求一次写成完美手册。AI 的优势是低成本重写，让文档保持“够用且新鲜”，比追求大而全重要得多。
- 把提示词模板也纳入团队资产。模板存在仓库里，谁维护谁使用，避免流程又退化成个人技能。
这件事给我最大的启发是：AI 在文档场景的价值不在于“写得快”，而在于让“维护文档”从一项没人愿意做的负担，变成一条成本足够低、可以嵌入日常迭代的流程。成本足够低，事情才会持续发生。
如果你的团队也在用多家模型的 API 做这类自动化流程，可以看看 Thistoken 提供的统一接入服务，一个接口对接多家模型，管理起来更省心，注册入口在这里：https://api.thistoken.ai/register
---
本文的示例只需一个 API Key 就能复现：在 https://api.thistoken.ai/register 注册即用。