截图式业务操作手册生成器

一句话定位：读前端代码搞清楚「界面长什么样、操作入口在哪」，读后端代码搞清楚「提交后系统做了什么、状态怎么变」，然后把两者缝合成一份给不懂代码的人看的、带图的操作手册。

和 code-to-doc-generator 的区别：那个 skill 出的是给开发者/产品看的分析型文档（PRD/HLD/影响矩阵、带 〔INFER〕 标注）。本 skill 出的是给一线业务人员看的图文操作手册——像人工截图 + 批注那种：每一节讲一个操作，配界面示意图和流程图，告诉读者点哪个按钮、填哪些字段、提交后会发生什么。两者不冲突，按受众选。

关键设计决策（为什么这么做）：

• 图用 Mermaid + SVG 线框图文件，不用真实截图。一个只读代码的 skill 截不了真图（真图要启动项目 + 浏览器自动化 + 登录账号，对绝大多数项目都跑不通）。Mermaid 流程图/状态图在 Typora、VSCode、GitHub、Obsidian 里都能直接渲染成图；界面示意图用 SVG 文件（![](images/xxx.svg)），依据前端组件代码忠实还原真实页面结构（真实的列名、按钮名、字段名），不凭空编造。SVG 是真实的图片文件、矢量清晰、所有主流 markdown 查看器都能显示，且 Claude 直接写文本即可——无需运行任何脚本，最通用、最稳定。（若用户坚持要 PNG，可用附带的 scripts/svg_to_png.py 一次性批量转换，但那需要能执行 Python；SVG 默认就够。不要用内联 HTML+CSS 画线框图，它在 Typora 等渲染器里经常塌成一堆文字。）
• 面向业务人员，全程去技术化。手册里不出现 API/JSON/Token/HTTP/SQL 这类词；状态码（如 status=2）要翻译成业务名（「待发货」）。技术细节（接口、字段类型、错误码）收进附录，不污染正文。

第零步：先确认「为哪个端、给谁看」

一份好手册必须先框定范围，否则会写成大而全、谁都用不上的东西。在动任何代码之前，明确两件事：

1. 覆盖哪个端？ 一个仓库常常多端并存（C 端 H5 / B 端后台 / 小程序 / 后端服务）。每多覆盖一个端，手册就多一倍篇幅、面向的读者也变了。先识别仓库里有哪些端（见下方「识别项目端」），再跟用户确认要为哪个端出手册。如果用户没说，主动问，不要默认全做。
2. 给谁看？ 默认是「一线业务/运营/客服人员」（非技术）。如果用户说是给实施/接手的技术人员看，正文的去技术化程度可以放宽、附录可以更厚——确认后再动笔。

为什么硬要确认：给顾客看的 C 端手册和给仓管看的 B 端手册，连「同一个功能」的写法都完全不同；混在一起写，两边都看不懂。

识别项目有哪些端

读根目录（不递归）+ 顶层目录，按特征判断：

多端并存时，逐端说明它是什么端、面向谁、技术栈，然后请用户选。不要默认覆盖全部，除非用户明确要。

工作流：四步出手册

每一步都遵循「先骨架后填充」：先把全部操作/章节列出来，再逐个补内容，避免写到一半漏掉大块功能。 references/ 下的文件是按需展开材料，需要完整模板/示例时再打开，不必先读。

第一步：盘点操作清单（= 手册目录）

目标是产出一份「这个端有哪些操作/业务场景」的完整清单，作为手册目录。先读现成文档再读代码，省大量时间：

1. 先读现成文档：README.md、API.md、CLAUDE.md、docs/。很多项目已有接口文档或架构说明，是最快的操作清单来源。（例：仓库项目 h5/API.md 把全部接口按业务域分好了类，直接给出目录骨架。）
2. 前端导航/路由：这是「用户能看到哪些功能」的真相源。
   • uni-app → pages.json（navigationBarTitleText 是页面名）+ tabBar.list.text 是底部菜单
   • Vue/React → 路由表 + 侧边栏菜单配置（菜单的 title/name 就是功能名）
   • 详细提取方法见 references/frontend-extraction.md
3. 后端接口分组：Controller/路由按资源分组，用来校验和补全前端清单（有些功能前端没菜单入口、靠按钮触发，后端接口能暴露出来）。
4. 输出：按业务域分组的操作清单 → 手册目录。把清单写进 todo 工具，跟用户确认「这些是要写的吗？有遗漏或不要的吗？」再进下一步。

经验：操作清单要按业务流程顺序排，不要按代码目录排。比如电商手册应是「注册登录 → 浏览选购 → 加购 → 下单 → 支付 → 发货 → 收货 → 售后」，而不是「AccountController → ProductController → OrderController」。

第二步：逐操作深度分析

对目录里每个操作，把界面侧和后端侧的信息对齐收集。交叉对照「前端页面调了哪些后端接口」是理解一个操作全貌的关键——前端只告诉你点哪里，后端才告诉你点了之后系统真正做了什么。

**界面侧（前端代码）**要提取：

• 操作入口：在哪个菜单/页面，需要什么角色/权限（needLogin、路由 meta.roles、按钮的 v-if/权限指令）
• 页面要素：搜索/筛选条件、表格列、操作按钮（新增/编辑/删除/启用/禁用/导入/导出/审核/下推…）、状态 Tab、弹窗表单字段
• 真实文案：按钮文字、字段 label、空状态/提示语（i18n 文件或模板里的中文）

**后端侧（后端代码）**要提取：

• 该操作调用的接口（路径、方法）+ 对应的 Service 逻辑
• 状态流转：操作前后状态怎么变（找状态枚举 + Service 里的状态判断分支）——这是写「提交后系统会怎样」的核心
• 联动副作用：是否扣库存/生成单据/发通知/写日志/触发定时任务
• 校验规则：必填、格式（@Pattern/正则）、业务约束（如「一人一仓」「每个商品只能认领一次」）
• 错误码与边界：不能做什么、什么情况会报错

详细的「业务信息 → 在哪段代码里找」对照表见 references/frontend-extraction.md 和 references/backend-extraction.md。

遇到看不懂的逻辑：搜它的调用方推断语义；枚举值找定义处 + 使用处对照看；实在推断不出的业务背景（代码里没有的「为什么」），不要硬编，记到附录的「待业务确认」清单里。

第三步：写手册 + 配图

按 references/manual-template.md 的整体骨架和每节模板填充。每个操作一节，标配四件套：

1. 文字说明：在哪里做、这个操作干嘛用的、分步操作、提交后系统会怎样、注意点。业务语言。
2. 界面示意图：依据该页前端代码还原的 SVG 线框图文件（写到 images/xxx.svg，手册里用 ![](images/xxx.svg) 引用；模板与规则见 references/ui-wireframe.md）。当前操作涉及的按钮/字段用红色描边高亮。
3. 流程图/状态图：Mermaid。多步带分支的用 flowchart；有状态生命周期的用 stateDiagram；关键交互（用户→前端→后端→副作用）用 sequence。谱例见 references/mermaid-patterns.md。
4. 字段表：表单字段含义 / 状态值对照表。

生成策略：

• 先写全文骨架（所有章节标题 + 每节四件套的小标题），再逐节填内容，避免漏节。
• 界面示意图和流程图先想清楚逻辑再写语法——线框图先在脑子里摆好页面结构，流程图先理清节点和分支。
• 手册正文保持干净，不要到处插 〔INFER〕/〔FACT〕 标注（那是给开发者的分析文档的规矩，会干扰业务读者）。把所有「代码里没写明、靠推断」的内容集中收进文末附录的「生成说明 / 待业务确认」。

第四步：保存、自检、汇报

1. 保存：docs/[项目名]/[端名]操作手册.md（如 docs/兑换商城/B端后台操作手册.md、docs/兑换商城/C端H5操作手册.md）。文件名用与用户对话相同的语言，不夹英文缩写。

2. 自检（逐项过）：

   检查项	标准
   受众匹配	通篇业务语言，无 API/JSON/Token/HTTP/SQL 等技术词；状态码已翻译成业务名
   图文配套	每个有界面的操作都有界面示意图；每个多步/带状态的操作都有 Mermaid 图
   界面保真	线框图里的列名/按钮名/字段名是从代码读到的真实值，没有编造；不确定的进了附录
   步骤可跟	操作步骤能让一个新手照着点完，没有跳步
   「提交后会怎样」清晰	每个写操作都写清了状态变化/联动/时机
   覆盖完整	目录里的操作都写了，没有半截章节

3. 汇报：覆盖了几个业务域 / 几个操作；哪些信息是从代码直接读到的、哪些是推断的（指向附录）；哪些地方建议业务方确认；界面上有哪些容易踩坑的操作。

语言去技术化对照（正文必须遵守）

技术词不是禁词，而是第一次出现时用一句话解释，后续用业务说法。完整原则：读者是来学怎么干活的，不是来学架构的。