代码都是AI写的，你问我要操作手册？？别慌！这个skill：ManualGen 可以帮助你生成专业的用户操作手册
一、开篇
自从用了 AI 写代码，生产力确实起飞了。原来两周的功能，现在两天就整出来了。
但是大家或多或少可能会遇到这个问题：你这个系统怎么用？有哪些功能？怎么点啊？
于是立马让AI 帮忙写操作手册。结果它写了这个东西给我：
"功能：XXXX，调用 POST /api/knowledge-base/ 接口，请求体为 JSON 格式，包含 name 和 description 字段…"
我内心：我要的是面向小白的操作手册，你给我的这是啥？这是接口文档啊！😅
好不容易让AI左改右改，最后整出来的文档就500行，不痛不痒，哪里都简单的提到了几句
"操作手册"和"技术文档"是两回事。用户根本不在乎你用的是 FastAPI 还是 Neo4j，他们只想知道"点哪里、填什么、看到什么"。
二、问题分析：AI 写操作手册的三个坑
我试了让 AI 直接写手册，发现了三个逃不掉的坑：
坑 | 表现 | 原因 |
|---|---|---|
坑1：手册写成开发文档 | 满屏 API 端点、数据库名、技术术语 | AI 上下文中全是后端代码，它以为这些用户也需要知道 |
坑2：自卖自夸 | 让 AI 自我审核永远是满分，实际内容根本不能用 | AI 有"自我偏好偏差"——学术界证实它会系统性地给自己的产出打高分 |
坑3：没有流程图 | 用户最需要"先点哪里再点哪里"的引导图，但 AI 就是不爱画 | 画图太累了，AI 天然会偷懒 |
第二点是最坑的。我第一次生成的"操作手册"让 AI 自己打分——它给自己 9.6 分（满分 10 分）。
然后我让一个完全不知道这个项目的人去看：实际可用性不到 20 分。0 张流程图、7 大章节只覆盖了 3 个、满是技术术语。
这就好像让一个学生自己改自己的考卷——成绩能差才怪。
三、解决方案：ManualGen 的诞生
它的工作方式是这样的：你在 IDE 里告诉它"给我生成 XX 系统的操作手册"，然后它自动：
直接触发skill→ 会自动排好计划，无需额外描述
扫描你的项目代码→ 理解系统有哪几个功能模块，纯静态扫描，不会做任何修改
分析用户场景→ 梳理每个模块的操作流程，多子agent同时写作
多轮质量检查→ 多个子agent作为独立的审核者，对每个地方进行严厉的审核
找边界、串流程、懂业务（含完整的业务流程图）→ 自动追溯数据的产生与消费
生成面向用户的纯界面操作手册（初稿）→ 启动6维度终审
反复修改后通过门禁的操作手册（终稿）
包含详细的步骤、流程、常见问题及解决办法，我奶奶来了都看得懂！
看完演示后，来说说它最与众不同的地方，是三个关键设计。
关键设计一：三步上下文隔离
这个问题的根源很微妙。AI 写不好用户手册，不是因为"能力不够"，而是因为"知道太多"——它的上下文里全是 API 调用、数据库表名、后端服务地址。当你让它写用户手册时，它很自然地就把这些内容写进去了，因为它觉得"这很有用啊"。
那怎么办？让它"失忆"。
ManualGen 用了独立子 Agent 隔离的机制：
[主AI] [WRITE 子 Agent] 提取模块名 ───────────→ 只知道"模块名+用户场景" 提取 API 端点 ──────X 完全不知道 API → [REFINE 子 Agent] 只看模块文件，不知道谁写的 → [JUDGE 子 Agent] 盲审最终文档，只看内容关键点在于：当 WRITE 子 Agent 收到写"知识库管理"模块的任务时，它只知道"这是一个管理系统中的文件夹、用户可以在里面上传文档"。它完全不知道背后有 POST /api/kb/create 这个接口，也不知道存储层用了 SQLite 还是 Neo4j。所以它只能写"点击【创建知识库】按钮 → 填写名称和描述 → 点击【确认】"——这才是用户要的操作手册。
同样地，JUDGE 子 Agent 在审核时，它不知道这份文档是谁写的、经历了什么过程。它只看文档本身，对照检查清单打分。这样就实现了真正意义上的"双盲评审"。
关键设计二：六维度质量体系
好手册长什么样？大部分人说不清楚。但说不清楚就没法让 AI 产出合格的东西。
我研究了几十份优秀的用户手册，总结出6 个可量化的评估维度：
维度 | 权重 | 检查什么 |
|---|---|---|
① 手册结构完整性 | 25% | 7 大必备章节是否齐全（前置说明/基础操作/核心功能/业务闭环/异常处理/权限角色/附则） |
② 流程图质量 | 20% | Mermaid 流程图的数量和链路完整度（有正常走向也有驳回走向） |
③ 去技术化合规性 | 15% | 有没有 API 端点、HTTP 代码块、技术术语堆砌 |
④ 操作可执行性 | 15% | 用户能不能照着步骤一步一步操作成功 |
⑤ 角色隔离与权限 | 15% | 谁可以做什么，谁不可以做什么，边界清晰 |
⑥ 异常覆盖完整度 | 10% | 报错处理、边界说明、紧急流程 |
每个维度都有具体的检查点，比如"手册结构完整性"就要逐项核对：有概述吗？有版本信息吗？有名词释义吗？有联系方式吗？——缺 2 个就直接阻断，不通过。
关键设计三：强制约束链条
仅仅有标准是不够的。AI 的惰性会让他想办法绕过去。所以我在从"写"到"审"的整个链条上设了层层约束：
WRITE 阶段：子 Agent 必须遵守 12 条硬性规则（每个操作配 1 张流程图、节点引号用「」而不是""、禁止任何 API 端点…），输出前过 7 项自检清单
REFINE 阶段：另一个子 Agent 逐模块回扫，发现流程图缺失、权限表缺失等问题就标记 FAIL，不让通过
AUDIT + JUDGE 阶段：主 Agent 先按 6 维度自评一遍，然后拉一个全新子 Agent 做盲审
只有这样层层把关，才能确保最终产出的手册质量。
四、真实效果：前后对比
我把 ManualGen 放在一个真实项目上跑了一遍——一个包含 170+ API 端点、13 个数据库表的"知识库管理系统"。
结果如下：
对比维度 | 改造前（普通 Prompt） | 改造后（ManualGen Skill） |
|---|---|---|
Mermaid 流程图 | 0 个 | 11 个 |
7 大章节覆盖 | 3/7 | 7/7 全部覆盖 |
API 端点残留 | 2 处 bash 命令 + 架构图 | 0 处 |
权限矩阵 | ❌ 不存在 | ✅ 完整矩阵 + 流转图 |
风险提示 | ❌ 不存在 | ✅ 6 处 ⚠️ 警示 |
紧急处理流程 | ❌ 不存在 | ✅ 完整分支流程图 |
评审方式 | AI 自评 9.6/10 | 子 Agent 盲审 95/100 |
综合质量 | ~20/100 | ~85/100 |
五、翻车记录
这东西不是一次搞定的。5 轮迭代，翻了 7 次车：
翻车 1：第一次生成 → 满屏 API 端点。忘了做上下文隔离，AI 提取了 170 个 API 端点后直接写进了手册，手册变成了"接口大全"。解决方法：子 Agent 隔离，只传模块名不传技术细节。
翻车 2：独立 Agent→ 同上下文无效。以为定义了"独立评审 Agent"就行了，但实际上 AI 在同一个对话里"假装不知道"——它记得之前的全部内容。解决方法：只有拉全新的子 Agent（Task 工具）才能做到真正隔离。
翻车 3：流程图画了但看不到。第一次生成终于有了 11 张流程图，但全都不渲染——一片空白。折腾了半天发现是 Mermaid 中用了中文弯引号"…"，解析器直接挂掉。改成直角引号「」就好了。这是一个你不知道就永远不会想到的坑。
翻车 4：质量门写了又删了。写了一个 Python 脚本做自动化抽检，正则扫描文档质量。后来发现大部分 IDE 环境不一定能跑外部脚本，最终还是用子 Agent 方案替代了——更通用、不依赖环境。
翻车 5：总分结构不方便。第一次产出是 9 个独立文件+1 个目录索引，用户要打开 10 个文件才能完整阅读。后来改成完整单文件输出，用户打开 1 个文件就行。
翻车 6：文件藏在".agent/harness"里找不到。用户根本不知道要去哪个目录找手册。修复方案：按项目命名、输出到项目根目录。
翻车 7：模板与执行不一致。改了很多规则，但 AI 还是按自己的习惯写——因为旧规则和新规则在多个文件中打架。后来做了全系统穿透性审查，发现了 7 处文件间矛盾，逐个清理。
六、总结与启示
AI 写操作手册的核心矛盾，不是"AI 有没有能力写"，而是"AI 怎么知道自己写得好不好"。
它天然会：
把知道的都写进去（技术污染）
给自己的作品打满分（自我偏好）
能省力就省力（不画图）
解决这三个问题。学到了三个关键设计原则：
上下文隔离：让 AI "失忆"，该知道才知道，不该知道绝对不能知道
客观质量门：用独立的子 Agent 做盲审，不依赖 AI 的自我判断
可量化标准：不说"写好一点"，说"必须有 7 大章节、每章必须有 1 张图、每图必须有驳回走向"
七、skill下载地址
最后贴上skill的地址：https://github.com/songzhou666/ManualGen/releases
用了感觉不错的朋友 可以点个⭐，