app-docs

应用文档生成器

浏览正在运行的 Web 应用，为每个界面截图，并生成足以发布的文档。这不是单纯的截图合集，而是一份结构化指南，能教会读者如何使用应用。

浏览器工具检测

与 ux-audit 相同：Chrome MCP、Playwright MCP 或 playwright-cli。

URL 解析

与 ux-audit 相同：优先使用已部署的线上 URL，而非 localhost。

深度级别

深度	截图数量	生成内容	耗时
quick	~10	单页快速入门指南。涵盖关键界面和顺利完成任务的流程。	10-15 分钟
standard	~30	完整用户指南。涵盖所有页面、主要工作流和参考表格。	30-60 分钟
thorough	~80+	综合指南。涵盖所有状态、移动端界面、每种 CRUD 流程和故障排除。	1-3 小时
exhaustive	~150+	可发布的文档套件。涵盖 thorough 的所有内容，此外还包括：入门教程、按功能逐一深入介绍、管理指南、键盘快捷键参考、常见问题解答和 HTML 版本。	3-6 小时

默认值：standard

工作流

1. 获取应用详情

询问用户：

• 应用 URL（必填；也可从 wrangler.jsonc 或正在运行的开发服务器自动检测）
• 应用名称（用作指南标题）
• 身份验证 — Chrome MCP 使用用户当前会话；Playwright 需要凭据
• 深度 — quick、standard、thorough 或 exhaustive
• 受众 — 谁会阅读这份文档？（最终用户、管理员、新团队成员、客户）

2. 发现所有路由

浏览应用并建立完整的页面清单：

• 查看侧边栏／导航菜单
• 逐一点击所有顶级项目和子项目
• 记录子页面、页面内的标签页和嵌套导航
• 检查设置、个人资料、管理区域和帮助页面
• 记录每个页面的 URL 和用途
• 标记包含交互元素（表单、按钮、筛选器）的页面

创建任务清单以跟踪文档进度。

3. 记录每个页面

对清单中的每个页面：

a. 导航并准备

• 导航到该页面
• 等待数据加载完成（截图中不应有骨架屏／加载指示器）
• 将浏览器调整为 1280x720，以确保截图一致
• 确保页面中有真实数据，而不是“Test Client”或空表格

b. 截取默认状态

• 截取清晰的页面截图，展示已填充的数据
• 使用描述性名称保存到 docs/screenshots/

c. 撰写页面章节

针对每个页面，撰写：

## [Page Name]

[One sentence: what this page is for and when you'd use it]

![Page name](screenshots/NN-page-name.png)

### What You'll See
[Describe the key elements: sidebar shows X, main area shows Y, toolbar has Z]

### What You Can Do
[List the actions available, each as a brief description]

### How To: [Primary Action]
1. [Step with screenshot reference]
2. [Step]
3. [Step — screenshot the result]

> **Tip:** [Helpful shortcut or non-obvious feature]

d. 记录关键工作流

对于交互式页面，按步骤记录操作流程，并在每个重要步骤截图：

### How To: Add a New Client

1. Click the **"Add Client"** button in the top right
   ![Add button location](screenshots/12-clients-add-button.png)

2. Fill in the required fields — Name and Email are required, everything else is optional
   ![New client form](screenshots/13-clients-new-form.png)

3. Click **"Save"** — you'll be taken to the new client's detail page
   ![Client saved confirmation](screenshots/14-clients-saved.png)

> **Tip:** You can also press **Cmd+N** from anywhere to create a new client.

e. 特定深度级别的补充内容

补充内容	quick	standard	thorough	exhaustive
空状态	跳过	备注	截图并记录	截图并提出改进建议
错误状态	跳过	备注	触发错误并截图	记录每种验证错误
深色模式	跳过	跳过	截取关键页面	截取每个页面
移动端（375px）	跳过	跳过	截取关键页面	截取每个页面
所有 CRUD 操作	跳过	仅主要操作	每种操作	每种操作及边缘情况
设置／配置	跳过	列出选项	逐项记录	逐项记录并附示例
键盘快捷键	跳过	列出可见项	完整参考表格	单独设立章节
搜索／筛选器	跳过	提及	逐项记录筛选器	记录所有筛选条件组合
权限／角色	跳过	跳过	备注差异	按角色分别设立章节
API／集成	跳过	跳过	若存在则提及	记录端点及示例

4. 撰写辅助章节

除了各页面的文档外，还需撰写：

入门指南（所有深度级别）：

## Getting Started

### Accessing [App Name]
- URL: [production URL]
- Supported browsers: Chrome, Firefox, Safari, Edge
- Mobile: [responsive / PWA / not supported]

### Logging In
[Screenshot of login page + steps]

### Your First 5 Minutes
1. [First thing to do after logging in]
2. [Second thing — the quick win]
3. [Third thing — explore the main feature]

导航指南（standard 及以上）：

## Navigation

### Sidebar
[Screenshot with annotations describing each section]

### Quick Actions
- **Cmd+K**: Quick switcher — jump to any page or record
- **Cmd+N**: Create new [item]
[Other shortcuts]

### Breadcrumbs / Back Navigation
[How to navigate back, where breadcrumbs appear]

键盘快捷键参考（thorough 及以上）：

## Keyboard Shortcuts

| Shortcut | Action |
|----------|--------|
| Cmd+K | Quick switcher |
| Cmd+N | New [item] |
| Cmd+S | Save |
| Escape | Close dialog / cancel |

故障排除（thorough 及以上）：

## Troubleshooting

### [Error message or symptom]
**What it means**: [explanation]
**How to fix**: [steps]

### Common Questions
[FAQ generated from what would confuse a new user — based on the documentation process itself]

管理指南（exhaustive）：

## Admin Guide

### User Management
[How to invite users, set roles, remove access]

### Settings Reference
| Setting | What it does | Default | Recommendation |
[Every setting documented]

### Data Management
[Export, import, backup, delete account]

5. 输出格式

Markdown（默认）：docs/USER_GUIDE.md

• 相对图片路径：![alt](screenshots/NN-description.png)
• GitHub 风格的 Markdown——可在 GitHub、VS Code 和 Obsidian 中渲染

HTML（详尽模式，或按需提供）：docs/user-guide.html

• 使用 Tailwind CDN 的独立 HTML 文件
• 截图使用相对路径（而非 base64，以控制文件大小）
• 带平滑滚动的目录侧边栏
• 适合打印的 CSS（@media print）
• 支持深色模式

截图命名：docs/screenshots/NN-section-description.png

• 使用数字排序：01-、02-、03-
• 章节前缀：01-dashboard-、05-clients-、12-settings-
• 描述性后缀：-overview.png、-add-form.png、-saved-confirmation.png

6. 模型图和示意图

在有助于理解的地方，结合使用截图和示意图：

工作流示意图（基于文本，不使用外部工具）：

### How a Client Moves Through the System

New Enquiry → Create Client → Add Policy → Send Renewal → Archive ↓ ↓ ↓ ↓ ↓ [Email] [Client Page] [Policy Page] [Email Outbox] [Archive]

带注释的截图：截图需要标注时，请在文本中进行说明：

![Dashboard](screenshots/01-dashboard.png)

The dashboard shows:
- **A** (top left): Your client count and active policies
- **B** (centre): Items needing attention today
- **C** (right): Recent activity feed

UI 元素参考：对于复杂页面，带标签的示意图会很有帮助：

### Editor Layout

| Area | What it does |
|------|-------------|
| Left panel | Folder tree — organise your notes |
| Centre panel | Note list — shows notes in the selected folder |
| Right panel | Editor — write and preview your note |
| Top bar | Navigation, search (Cmd+K), and view toggles |

截图质量

• 分辨率：1280x720（桌面端），375x812（移动端）
• 数据：使用真实的数据。不要使用“Test”或“Lorem ipsum”。应按照实际使用应用的方式填入数据。
• 时机：等待数据加载完成。最终截图中不要出现加载指示器或骨架屏。
• 状态：展示有用的页面状态——已填入数据、展开了相关章节、显示了关键功能
• 一致性：始终使用相同的视口大小、缩放级别和浏览器
• 深色模式：如果要记录深色模式，请在截图前切换——不要在同一章节中混用不同模式

自主执行规则

• 直接执行：浏览页面、截图、阅读页面内容、编写文档
• 简短确认：编写大型文档文件前先确认
• 先询问：提交含有真实数据的表单前、点击删除前
• 详尽模式：编写文件和填写测试数据时跳过确认

质量标准

文档应达到以下标准：

1. 新用户无需求助，就能按照指南完成任何任务
2. 每张截图都有上下文——我看到的是什么？我应该做什么？
3. 步骤是原子化的——编号步骤每步只执行一个操作，绝不写成“点击 X，然后填写 Y 和 Z”
4. 提示能揭示隐藏价值——快捷方式、高级功能，以及用户不容易自行发现的内容
5. 排障内容切合实际——基于编写文档时实际遇到的困惑，而非假设的常见问题
6. 便于浏览——使用标题、截图、表格和提示。没人会从头到尾通读文档，读者会查找自己需要的内容。