一、开篇

自从用了 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 系统的操作手册"，然后它自动：

1. 直接触发skill→ 会自动排好计划，无需额外描述

2. 扫描你的项目代码 → 理解系统有哪几个功能模块，纯静态扫描，不会做任何修改

3. 分析用户场景 → 梳理每个模块的操作流程，多子agent同时写作

4. 多轮质量检查→ 多个子agent作为独立的审核者，对每个地方进行严厉的审核

5. 找边界、串流程、懂业务（含完整的业务流程图）→ 自动追溯数据的产生与消费

6. 生成面向用户的纯界面操作手册（初稿）→ 启动6维度终审

7. 反复修改后通过门禁的操作手册（终稿）

包含详细的步骤、流程、常见问题及解决办法，我奶奶来了都看得懂！

看完演示后，来说说它最与众不同的地方，是三个关键设计。

关键设计一：三步上下文隔离

这个问题的根源很微妙。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 的惰性会让他想办法绕过去。所以我在从"写"到"审"的整个链条上设了层层约束：

1. WRITE 阶段：子 Agent 必须遵守 12 条硬性规则（每个操作配 1 张流程图、节点引号用「」而不是""、禁止任何 API 端点…），输出前过 7 项自检清单

2. REFINE 阶段：另一个子 Agent 逐模块回扫，发现流程图缺失、权限表缺失等问题就标记 FAIL，不让通过

3. AUDIT + JUDGE 阶段：主 Agent 先按 6 维度自评一遍，然后拉一个全新子 Agent 做盲审

只有这样层层把关，才能确保最终产出的手册质量。

状态机总览

阶段	职责	核心产物	自动推进
0 EXPLORE	理解项目业务全貌	_exploration.md	✅ 自动
1 EXTRACT	提取功能/API/路由/页面	_extraction.md	✅ 自动
2 ANALYZE	流程+状态机+边界+数据上下游	_analysis.md + _function_survey.md	✅ 自动
2.5 GAP	完整性评估+项目形状报告	_gap_analysis.md	✅ 自动
3 CONFIRM	展示摘要等待用户确认	用户反馈记录	⛔ 等待用户
4 RESOLVE	冲突检测与解决	_resolution.md	✅ 自动
5 WRITE	子Agent写模块（隔离技术上下文）	_modules/	✅ 自动
5.5 REFINE	子Agent逐模块回扫	_refine_log.md	✅ 自动
5.7 REFERENCE_CHECK	交叉引用+术语一致性检查	_reference_check.md	✅ 自动
6 INTEGRATE	完整合并→项目命名→根目录输出	{项目名} 用户操作手册.md	✅ 自动
7 AUDIT	自评（6维度预审）	_audit.md	✅ 自动
8 TODO_RESOLVE	统一解决待办项	_todo_resolution.md	✅ 自动
9 JUDGE	子Agent盲审（真正质量门）	_judgment.md	✅ 自动（DONE结束）

        注意：使用过程中会有一次用户确认的环节，基于一轮基本分析后，需要用户确认是否执行此方案，如果有要补充的，可以和AI反馈，如果没有可以直接输入确认即可，后续skill将持续引导AI自主完成操作手册的生成

---

四、真实效果：前后对比

我把 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 怎么知道自己写得好不好"。

它天然会：

• 把知道的都写进去（技术污染）

• 给自己的作品打满分（自我偏好）

• 能省力就省力（不画图）

解决这三个问题。学到了三个关键设计原则：

1. 上下文隔离：让 AI "失忆"，该知道才知道，不该知道绝对不能知道

2. 客观质量门：用独立的子 Agent 做盲审，不依赖 AI 的自我判断

3. 可量化标准：不说"写好一点"，说"必须有 7 大章节、每章必须有 1 张图、每图必须有驳回走向"

七、skill下载地址

最后贴上skill的地址：https://github.com/songzhou666/ManualGen/releases

用了感觉不错的朋友  可以点个⭐，