需要为 Web 应用生成带截图和分步说明的用户文档时…

适用于已运行的 Web 应用，通过浏览器自动化截图并生成结构化用户指南、工作流说明和参考表。

适用场景

解决思路

1. 检测浏览器工具：与 ux-audit 相同，使用 Chrome MCP、Playwright MCP 或 playwright-cli。
2. 解析 URL：与 ux-audit 相同，优先使用已部署/线上 URL，而不是 localhost。
3. 选择深度级别 quick：约 10 张截图，生成单页快速开始指南；只覆盖关键页面和 happy path；约 10-15 分钟。
4. 选择深度级别 standard：约 30 张截图，生成完整用户指南；覆盖所有页面、主要工作流、参考表；约 30-60 分钟。
5. 选择深度级别 thorough：约 80+ 张截图，生成综合指南；覆盖所有状态、移动端视图、每个 CRUD 流程、故障排除；约 1-3 小时。
6. 选择深度级别 exhaustive：约 150+ 张截图，生成可发布文档套件；包含 thorough 的全部内容，加上入门教程、逐功能深入、管理员指南、键盘快捷键参考、FAQ 和 HTML 版本；约 3-6 小时。
7. 默认使用 standard 深度。
8. 获取应用详情：询问用户 App URL（必需；或从 wrangler.jsonc / 正在运行的开发服务器自动检测）。
9. 获取应用详情：询问 App name（用于指南标题）。
10. 获取认证方式：Chrome MCP 使用用户会话；Playwright 需要凭据。
11. 获取深度：quick、standard、thorough 或 exhaustive。
12. 获取受众：谁阅读这份文档（最终用户、管理员、新团队成员、客户）。
13. 发现所有路由：导航应用并建立完整页面清单。
14. 读取侧边栏/导航菜单。
15. 点击所有顶级项和子项。
16. 记录子页面、页面内标签页和嵌套导航。
17. 检查设置、个人资料、管理员区域、帮助页面。
18. 记录每个页面的 URL 和用途。
19. 记录哪些页面有交互元素（表单、按钮、筛选器）。
20. 创建任务列表以跟踪文档进度。
21. 对清单中的每个页面：导航到页面。
22. 等待数据加载（最终截图里不能有 skeleton/spinner）。
23. 将浏览器调整为 1280x720，以保持截图一致。
24. 确保页面有真实数据——不要 “Test Client” 或空表格。
25. 截取默认状态：截取干净截图，显示页面已填充数据。
26. 保存到 docs/screenshots/，使用描述性文件名。
27. 编写页面章节：对每个页面按模板写 `## [Page Name]`。
28. 写一句说明：这个页面用于什么、何时使用。
29. 插入图片：``。
30. 写 `### What You'll See`：描述关键元素，如 sidebar 显示 X、main area 显示 Y、toolbar 有 Z。
31. 写 `### What You Can Do`：列出可用操作，每项简短描述。
32. 写 `### How To: [Primary Action]`：按步骤写 1. [Step with screenshot reference]、2. [Step]、3. [Step — screenshot the result]。
33. 添加 `> **Tip:**`：有帮助的快捷方式或非显而易见的特性。
34. 记录关键工作流：对交互页面，按步骤记录并在每个重要步骤截图。
35. 示例工作流：`### How To: Add a New Client`。
36. 示例步骤 1：点击右上角 **“Add Client”** 按钮；``。
37. 示例步骤 2：填写必填字段——Name 和 Email 必填，其他可选；``。
38. 示例步骤 3：点击 **“Save”**——会进入新客户详情页；``。
39. 示例 Tip：在任何地方可按 **Cmd+N** 创建新客户。
40. 深度特定额外内容——空状态：quick 跳过；standard 备注；thorough 截图 + 文档；exhaustive 截图 + 建议改进。
41. 错误状态：quick 跳过；standard 备注；thorough 触发 + 截图；exhaustive 记录每个验证错误。
42. 深色模式：quick 跳过；standard 跳过；thorough 截取关键页面；exhaustive 截取每个页面。
43. 移动端（375px）：quick 跳过；standard 跳过；thorough 截取关键页面；exhaustive 截取每个页面。
44. 所有 CRUD：quick 跳过；standard 只记录主要操作；thorough 记录每个操作；exhaustive 记录每个操作 + 边界情况。
45. 设置/配置：quick 跳过；standard 列出选项；thorough 记录每一项；exhaustive 记录每一项并附示例。
46. 键盘快捷键：quick 跳过；standard 如果可见则列出；thorough 完整参考表；exhaustive 专门章节。
47. 搜索/筛选：quick 跳过；standard 提及；thorough 记录每个筛选器；exhaustive 记录每种组合。
48. 权限/角色：quick 跳过；standard 跳过；thorough 备注差异；exhaustive 按角色分章节。
49. API/集成：quick 跳过；standard 跳过；thorough 如存在则提及；exhaustive 记录 endpoints + 示例。
50. 编写支持章节：Getting Started（所有深度）。
51. Getting Started 中 `### Accessing [App Name]`：写 URL: [production URL]；支持浏览器: Chrome、Firefox、Safari、Edge；移动端: [responsive / PWA / not supported]。
52. Getting Started 中 `### Logging In`：登录页截图 + 步骤。
53. Getting Started 中 `### Your First 5 Minutes`：写 1. 登录后第一件事；2. 第二件事——快速胜利；3. 第三件事——探索主要功能。
54. 编写 Navigation Guide（standard+）。
55. Navigation 中 `### Sidebar`：带注释的截图，描述每个区域。
56. Navigation 中 `### Quick Actions`：列出 **Cmd+K** Quick switcher——跳转到任何页面或记录；**Cmd+N** 创建新 [item]；其他快捷键。
57. Navigation 中 `### Breadcrumbs / Back Navigation`：说明如何返回、breadcrumbs 出现在哪里。
58. 编写 Keyboard Shortcuts Reference（thorough+）。
59. 快捷键表：| Shortcut | Action |；| Cmd+K | Quick switcher |；| Cmd+N | New [item] |；| Cmd+S | Save |；| Escape | Close dialog / cancel |。
60. 编写 Troubleshooting（thorough+）。
61. Troubleshooting 中 `### [Error message or symptom]`：写 **What it means**: [explanation]；**How to fix**: [steps]。
62. Troubleshooting 中 `### Common Questions`：根据文档过程中实际让人困惑的点生成 FAQ，而不是假设 FAQ。
63. 编写 Admin Guide（exhaustive）。
64. Admin Guide 中 `### User Management`：说明如何邀请用户、设置角色、移除访问权限。
65. Admin Guide 中 `### Settings Reference`：表格 | Setting | What it does | Default | Recommendation |，记录每个设置。
66. Admin Guide 中 `### Data Management`：说明导出、导入、备份、删除账户。
67. 输出格式 Markdown（默认）：`docs/USER_GUIDE.md`。
68. Markdown 中使用相对图片路径：``。
69. Markdown 使用 GitHub-flavoured markdown——可在 GitHub、VS Code、Obsidian 渲染。
70. 输出格式 HTML（exhaustive 深度或按请求）：`docs/user-guide.html`。
71. HTML 使用单个自包含 HTML 文件，带 Tailwind CDN。
72. HTML 中截图使用相对路径（不要 base64——保持文件大小合理）。
73. HTML 添加带平滑滚动的目录侧边栏。
74. HTML 添加打印友好 CSS（`@media print`）。
75. HTML 支持深色模式。
76. 截图命名：`docs/screenshots/NN-section-description.png`。
77. 命名中用数字表示排序：`01-`、`02-`、`03-`。
78. 命名中用章节前缀：`01-dashboard-`、`05-clients-`、`12-settings-`。
79. 命名中用描述性后缀：`-overview.png`、`-add-form.png`、`-saved-confirmation.png`。
80. 混合使用截图与图表以帮助理解。
81. 工作流图（基于文本，不用外部工具）：例如 `### How a Client Moves Through the System`，代码块 `New Enquiry → Create Client → Add Policy → Send Renewal → Archive`，下方箭头到 `[Email] [Client Page] [Policy Page] [Email Outbox] [Archive]`。
82. 带注释截图：当截图需要标注时，在文本中描述标注；例如 `` 后说明 A/B/C。
83. UI 元素参考：对复杂页面，添加带标签的说明；例如 `### Editor Layout` 表格 Area | What it does，Left panel、Centre panel、Right panel、Top bar。
84. 截图质量：分辨率 1280x720（桌面），375x812（移动端）。
85. 数据：使用真实数据，不要 “Test” 或 “Lorem ipsum”；像实际使用应用一样使用它。
86. 时机：等待数据加载；最终截图无 spinner、无 skeleton screen。
87. 状态：以有用状态展示页面——数据已填充、相关区域已展开、关键功能可见。
88. 一致性：全程使用相同 viewport 大小、相同缩放级别、相同浏览器。
89. 深色模式：如果记录深色模式，截图前先切换——不要在同一章节混合模式。
90. 自主规则：直接做：导航页面、截图、读取页面内容、编写文档。
91. 简要确认：写大型文档文件前。
92. 先询问：提交含真实数据的表单前，点击删除前。
93. thorough/exhaustive 模式：写文件和填测试数据表单时跳过确认。
94. 质量线：新用户能按指南完成任何任务而不求助。
95. 每张截图有上下文——我在看什么？我应该做什么？
96. 步骤原子化——每个编号步骤一个动作，绝不要 “click X and then fill in Y and Z”。
97. Tips 揭示隐藏价值——快捷方式、高级功能、用户自己不会发现的东西。
98. 故障排除要真实——基于文档过程中实际遇到的困惑时刻，不是假设 FAQ。
99. 可扫读——标题、截图、表格、提示；没人从头读到尾，他们搜索需要的内容。

适用边界 · 注意事项

• 不适用于非 Web 应用、没有运行中/可访问 URL 的应用，或不需要用户界面文档的场景。
• 没有可用的浏览器自动化工具（Chrome MCP、Playwright MCP 或 playwright-cli）或不在 Claude Code 环境时。
• 当不允许自动化访问、无法提供登录凭据/会话，或禁止提交表单/删除操作且无法用测试数据时。