一、开篇自从用了 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 SkillMermaid 流程图0 个11 个7 大章节覆盖3/77/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 在同一个对话里假装不知道——它记得之前的全部内容。解决方法只有拉全新的子 AgentTask 工具才能做到真正隔离。翻车 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用了感觉不错的朋友 可以点个⭐