screenshotting-apps

标注截图文档

为任意 Web 应用或在线网站生成包含标注截图的 Markdown 文档。

前置条件

• 全局安装 agent-browser CLI（npm i -g agent-browser && agent-browser install）

阶段 1：确定目标

A) 在线网站

1. 规范化 URL（缺少时补上 https://）：

   agent-browser open https://example.com && agent-browser wait --load networkidle
   

2. 使用语义定位器关闭 cookie/同意横幅（最可靠）：

   agent-browser find text "Accept" click
   

   或者做一次快照，找到接受按钮的 ref，然后直接点击该 ref：

   agent-browser snapshot -i -s "[role=dialog], [class*=cookie], [class*=consent]" -c
   agent-browser click @e1  # Use the ref from snapshot
   

   验证它已消失：agent-browser is visible "[role=dialog]" 或 agent-browser wait "[role=dialog]" --state hidden
3. 对于登录墙或反爬问题，请参阅 references/live-sites.md。

B) 本地开发服务器

1. 找到或启动开发服务器（检查端口 3000/5173/4321/8080，或通过 package.json 启动）
2. 对于自签名证书：agent-browser --ignore-https-errors open https://localhost:<port>

阶段 2：梳理站点

1. 打开首页：agent-browser open <url> && agent-browser wait --load networkidle
2. 截取一张快速自动标注的截图来勘察页面——它会为所有交互元素标注带编号的 ref：

   agent-browser screenshot --annotate docs/screenshots/_survey.png
   

   阅读输出图例，了解页面上有什么（按钮、链接、输入框都映射到 @e ref）。
3. 对导航做快照以发现页面：

   agent-browser snapshot -i -s "header, nav, [role=navigation]" -c
   

   如需深层 DOM：agent-browser snapshot -i -c -d 3
4. 对于采用客户端路由的 SPA：还要检查源码中的路由定义（grep -r "path:" src/router 或类似命令），因为并非所有路由都会在导航中链接出来。
5. 询问用户以确认页面列表。对于在线网站，建议最多 5-10 个页面。

阶段 3：为每个页面截图

每个页面的工作流：验证选择器 → 标注 → 检查是否有 FAILED → 验证截图 → 修复或继续。

设置（在所有截图之前运行一次）：

agent-browser set viewport 1440 900
export AGENT_BROWSER_SCREENSHOT_DIR=docs/screenshots

拦截会产生浮层或拖慢页面加载的广告和跟踪脚本（在线网站）：

agent-browser network route "**/*.doubleclick.net/**" --abort
agent-browser network route "**/googlesyndication.com/**" --abort
agent-browser network route "**/analytics.js" --abort
agent-browser network route "**/gtm.js" --abort

解析标注脚本的路径（检查常见的安装位置）：

ANNOT_JS="$(find . .claude .agents ~/skills -path '*/app-screenshots/references/annotate.js' 2>/dev/null | head -1)"
[ -z "$ANNOT_JS" ] && echo "ERROR: annotate.js not found — check skill installation"

对于每个页面：

第 1 步：导航

agent-browser open <url> && agent-browser wait --load networkidle

对于在线网站，为懒加载内容加上 agent-browser wait 2000。当你不需要中间输出时可以链式调用：agent-browser open <url> && agent-browser wait --load networkidle && agent-browser wait 2000

第 2 步：关闭 cookie/同意横幅（在线网站）

agent-browser find text "Accept" click
agent-browser wait "[class*=overlay]" --state hidden

对于复杂或位于 iframe 中的横幅，请参阅 references/live-sites.md。

第 3 步：在标注之前验证选择器

始终先测试选择器。 失败的选择器会产生不可见的标注。

对于复杂的 JS，使用带 heredoc 的 eval --stdin（可避免 shell 引号问题）：

agent-browser eval --stdin <<'EVALEOF'
const sels = ['selector1', 'selector2'];
sels.map(s => {
  const el = document.querySelector(s);
  if (!el) return 'MISSING: ' + s;
  const r = el.getBoundingClientRect();
  return 'OK: ' + s + ' (' + Math.round(r.width) + 'x' + Math.round(r.height) + ')';
}).join('\n')
EVALEOF

快速检查匹配数量：agent-browser get count "<selector>"

如果为 MISSING，使用 agent-browser snapshot -i -c 来发现正确的选择器和 ref。不要用已失效的选择器进行标注。 提示请参阅 references/selectors.md。

对于首屏以下的元素，先将它们滚动到视图中：agent-browser scrollintoview "<selector>"

步骤 4：注入标注

使用 eval --stdin 安全注入标注脚本：

agent-browser eval --stdin <<EVALEOF
$(cat "$ANNOT_JS")
annotateMulti([
  {sel: 'selector', label: 'Label', type: 'box'},
  {sel: 'selector', label: 'Label', type: 'click'}
])
EVALEOF

关键： 如果输出以 FAILED: 开头，请先修复选择器再截图。清除并重试：

agent-browser eval "clearAnnotations()"

标注类型：

• click — 实心圆点 + 箭头 + 编号标签。用于按钮、链接、输入框。
• box — 虚线边框 + 编号标签。用于区块、卡片、容器。
• circle（默认）— 限制半径的虚线圆 + 箭头 + 编号标签。用于一般性标注。

颜色自动轮换：红色、蓝色、绿色、琥珀色、紫色。每个标注自动编号（1、2、3……），便于在 markdown 中交叉引用。

每张截图最多 3 个标注。 如有需要，请拆分为多张截图（例如 03a-top.png、03b-actions.png）。

类型选择规则：

• 小型元素（按钮、链接、图标）使用 click — 限制圆不会过度膨胀
• 中型区域（卡片、表单分组、侧边栏）使用 box — 贴合元素形状
• 切勿 在全宽元素（导航栏、页眉）上使用 circle 或 box — 而应标注其中的具体条目

各页面类型应标注的内容：

• 首页：主视觉 CTA、搜索输入框、一个导航示例
• 商品列表：一个商品卡片、筛选开关、排序下拉菜单
• 商品详情：价格、加入购物车、尺码/款式选择器
• 搜索结果：搜索输入框、一个结果卡片、筛选侧边栏
• 仪表盘：一个指标卡片、一个图表、主要操作
• 表格/数据视图：列标题、筛选控件、数据区域
• 设置/表单：关键表单字段、提交按钮

步骤 5：截图

agent-browser screenshot <NN>-<page-name>.png

补零编号：01-homepage.png、02-category.png 等。当内容超出首屏时，使用 --full 进行全页截图。

步骤 6：验证截图质量

读取你刚刚捕获的截图文件 并检查：

• 标注可见且互不重叠
• 标签未被视口边缘截断
• 页面内容正确加载（无加载动画、无损坏图片）
• Cookie 横幅或浮层未遮挡视图

如有任何问题：agent-browser eval "clearAnnotations()"，修复问题，重新标注，然后重新截图。不要带着有问题的截图继续。

交互式截图

对于搜索、菜单、模态框、悬停状态 — 使用快照 → refs → 交互模式：

# 1. Snapshot to get refs
agent-browser snapshot -i
# 2. Interact using refs (more reliable than CSS selectors)
agent-browser click @e5          # Click search input by ref
agent-browser type @e5 "shoes"
agent-browser wait 2000
# 3. Annotate the result
agent-browser eval --stdin <<EVALEOF
$(cat "$ANNOT_JS")
annotateMulti([{sel: '[class*=suggest]', label: 'Suggestions', type: 'box'}])
EVALEOF
# 4. Screenshot
agent-browser screenshot 05-search-results.png
# 5. Verify — read the screenshot and check quality

注意：iframe 内的 refs 可直接使用 — 交互时无需切换 frame。

录制交互流程（可选）

对于复杂交互（结账流程、多步骤向导），可随截图一起录制视频：

agent-browser record start docs/screenshots/checkout-flow.webm
# ... perform the interaction steps, taking screenshots along the way ...
agent-browser record stop

在 markdown 中链接视频：[Watch checkout flow](screenshots/checkout-flow.webm)

移动端 / 响应式截图

要记录移动端布局：

# Use device emulation (sets viewport + user agent together)
agent-browser set device "iPhone 14"

然后遵循相同的标注 → 截图 → 验证工作流。文件名添加 -mobile 后缀：01-homepage-mobile.png。

要返回桌面端：agent-browser set viewport 1440 900

注意：在窄视口下，每张截图最好最多 2 个标注，以避免拥挤。

阶段 4：生成 Markdown

文件名：docs/<domain>-screenshots.md（线上站点）或 docs/app-screenshots.md（本地）。

在描述中使用编号引用 (1)、(2)、(3)，以交叉引用每张截图中可见的标注徽标。

# <Site/App Name> - Visual Guide

Brief description of the site/app.

**URL:** <base-url>
**Date:** <today's date>

**Annotation key:** Red = primary actions, Blue = secondary elements, Green = content areas

---

## <Page Name>

1-3 sentences describing the page. Reference annotations by number:
"The **Search bar** (1) supports autocomplete. Use the **Category nav** (2) to browse departments.
The **Hero banner** (3) rotates seasonal promotions."

![<Page Name>](screenshots/<filename>.png)

---

阶段 5：比较环境（可选）

在记录预发布环境与生产环境之间的差异时，或在重新设计之前/之后：

# Visual pixel diff between two URLs
agent-browser diff url https://staging.example.com https://prod.example.com

# Diff against a baseline screenshot
agent-browser diff screenshot --baseline docs/screenshots/01-homepage-before.png

# Accessibility tree diff (detect structural changes)
agent-browser diff snapshot

在 markdown 中包含差异截图，以突出显示变更内容。

阶段 6：清理

# Remove network intercepts
agent-browser network unroute
agent-browser close

参考

• 选择器技巧与故障排除：参见 references/selectors.md
• 线上站点技巧（cookies、懒加载、速率限制、地区）：参见 references/live-sites.md