Dogfood：应用探索与问题发现

系统地探索一个 Web 应用程序，发现问题，并为每个发现生成一份包含完整复现证据的报告。

设置

只有目标 URL 是必需的。其他所有参数都有合理的默认值——除非用户明确提供了覆盖值，否则请使用默认值。

如果用户说“dogfood vercel.com”之类的话，请立即使用默认值开始。除非提到了身份验证但缺少凭据，否则不要询问澄清性问题。

始终直接使用 agent-browser——不要使用 npx agent-browser。直接使用二进制文件会调用快速的 Rust 客户端。npx 通过 Node.js 路由，速度会慢很多。

工作流程

1. 初始化     设置会话、输出目录、报告文件
2. 身份验证   如果需要则登录，保存状态
3. 定位       导航到起始点，拍摄初始快照
4. 探索       系统地访问页面并测试功能
5. 记录       发现问题时立即截图并记录
6. 收尾       更新摘要计数，关闭会话

1. 初始化

mkdir -p {OUTPUT_DIR}/screenshots {OUTPUT_DIR}/videos

将报告模板复制到输出目录并填写头部字段：

cp {SKILL_DIR}/templates/dogfood-report-template.md {OUTPUT_DIR}/report.md

启动一个命名的会话：

agent-browser --session {SESSION} open {TARGET_URL}
agent-browser --session {SESSION} wait --load networkidle

2. 身份验证

如果应用需要登录：

agent-browser --session {SESSION} snapshot -i
# 识别登录表单引用，填写凭据
agent-browser --session {SESSION} fill @e1 "{EMAIL}"
agent-browser --session {SESSION} fill @e2 "{PASSWORD}"
agent-browser --session {SESSION} click @e3
agent-browser --session {SESSION} wait --load networkidle

对于 OTP/邮件验证码：询问用户，等待其响应，然后输入验证码。

成功登录后，保存状态以备潜在重用：

agent-browser --session {SESSION} state save {OUTPUT_DIR}/auth-state.json

3. 定位

拍摄初始带注释的屏幕截图和快照，以了解应用结构：

agent-browser --session {SESSION} screenshot --annotate {OUTPUT_DIR}/screenshots/initial.png
agent-browser --session {SESSION} snapshot -i

识别主要的导航元素，并规划要访问的部分。

4. 探索

阅读 references/issue-taxonomy.md 获取需要查找的内容的完整列表和探索清单。

策略——系统地遍历应用：

• 从主导航开始。访问每个顶级部分。
• 在每个部分中，测试交互元素：点击按钮、填写表单、打开下拉菜单/模态框。
• 检查边缘情况：空状态、错误处理、边界输入。
• 尝试真实的端到端工作流（创建、编辑、删除流程）。
• 定期检查浏览器控制台是否有错误。

在每个页面上：

agent-browser --session {SESSION} snapshot -i
agent-browser --session {SESSION} screenshot --annotate {OUTPUT_DIR}/screenshots/{page-name}.png
agent-browser --session {SESSION} errors
agent-browser --session {SESSION} console

根据您的判断决定探索的深度。在核心功能上花更多时间，在次要页面上花较少时间。如果您在一个区域发现了一系列问题，请进行更深入的调查。

5. 记录问题（复现优先）

步骤 4 和 5 是同时进行的——在一次遍历中探索和记录。当您发现问题时，立即停止探索并记录，然后再继续。不要先探索整个应用，之后再记录。

每个问题必须是可复现的。当您发现错误时，不要仅仅记下来——要用证据证明它。目标是阅读报告的人能够准确地看到发生了什么，并且可以重放它。

为问题选择适当级别的证据：

交互/行为问题（功能问题、用户体验问题、操作时控制台报错）

这些问题需要用户交互才能复现——请使用带有视频和分步屏幕截图的完整复现：

1. 在复现之前开始录制复现视频：

agent-browser --session {SESSION} record start {OUTPUT_DIR}/videos/issue-{NNN}-repro.webm

2. 以人类可读的速度逐步执行步骤。 在操作之间暂停 1-2 秒，以便视频易于观看。在每个步骤拍摄屏幕截图：

agent-browser --session {SESSION} screenshot {OUTPUT_DIR}/screenshots/issue-{NNN}-step-1.png
sleep 1
# 执行操作（点击、填写等）
sleep 1
agent-browser --session {SESSION} screenshot {OUTPUT_DIR}/screenshots/issue-{NNN}-step-2.png
sleep 1
# ...继续直到问题显现

3. 捕获错误状态。 暂停以便查看者能看到，然后拍摄带注释的屏幕截图：

sleep 2
agent-browser --session {SESSION} screenshot --annotate {OUTPUT_DIR}/screenshots/issue-{NNN}-result.png

4. 停止视频：

agent-browser --session {SESSION} record stop

5. 在报告中编写编号的复现步骤，每个步骤引用其对应的屏幕截图。

静态/加载时可见的问题（错别字、占位符文本、文本截断、错位、加载时控制台报错）

这些问题无需交互即可见——一张带注释的屏幕截图就足够了。无需视频，也无需多步骤复现：

agent-browser --session {SESSION} screenshot --annotate {OUTPUT_DIR}/screenshots/issue-{NNN}.png

编写简要描述并在报告中引用屏幕截图。将复现视频设置为 N/A。

对于所有问题：

1. 立即追加到报告。 不要将问题留到以后批量处理。一旦发现就立即记录每个问题，这样即使会话中断，信息也不会丢失。
2. 递增问题计数器（ISSUE-001, ISSUE-002, …）。

6. 收尾

目标是找到 5-10 个记录良好的问题，然后收尾。证据的深度比总数更重要——5 个有完整复现步骤的问题胜过 20 个描述模糊的问题。

探索结束后：

1. 重新阅读报告并更新摘要严重性计数，使其与实际发现的问题相匹配。每个 ### ISSUE- 块都必须反映在总数中。
2. 关闭会话：

agent-browser --session {SESSION} close

3. 告知用户报告已就绪，并总结发现：问题总数、按严重性分类的细分以及最关键的项目。

指南

• 复现是一切。 每个问题都需要证据——但要让证据与问题相匹配。交互式错误需要视频和分步屏幕截图。静态错误（错别字、占位符文本、加载时可见的视觉缺陷）只需要一张带注释的屏幕截图。
• 在收集证据前验证可复现性。 在录制视频或拍摄屏幕截图之前，至少重试一次以验证问题是否可复现。如果无法稳定复现，则不是一个有效问题。
• 不要为静态问题录制视频。 错别字或文本截断不需要视频。将视频留作记录涉及用户交互、计时或状态变化的问题。
• 对于交互式问题，为每一步截图。 捕获前、操作中和操作后——以便人们可以看到完整的序列。
• 编写映射到屏幕截图的复现步骤。 报告中的每个编号步骤都应引用其对应的屏幕截图。读者应该能够在不接触浏览器的情况下，直观地跟随步骤。
• 使用正确的快照命令。
  • snapshot -i — 用于查找可点击/可填充的元素（按钮、输入框、链接）
  • snapshot（无标志） — 用于读取页面内容（文本、标题、数据列表）
• 要彻底，但也要运用判断力。 您不是在遵循测试脚本——您是在像真实用户一样探索。如果感觉不对劲，就深入调查。
• 增量式地记录发现。 发现一个问题就立即将其追加到报告中。如果会话中断，发现的结果得以保留。切勿将所有问题留到最后批量处理。
• 切勿删除输出文件。 不要在会话中途 rm 屏幕截图、视频或报告。不要关闭会话并重新启动。应向前推进，而不是倒退。
• 切勿读取目标应用的源代码。 您是以用户身份进行测试，而不是审核代码。不要读取被测应用的 HTML、JS 或配置文件。所有发现必须来自您在浏览器中观察到的内容。
• 检查控制台。 许多问题在 UI 中不可见，但会以 JS 错误或失败的请求形式出现。
• 像用户一样测试，而不是像机器人。 尝试端到端的常见工作流。点击真实用户会点击的东西。输入真实的数据。
• 像人类一样输入。 在视频录制期间填写表单字段时，使用 type 而不是 fill——它会逐个字符地输入。仅在视频录制之外、速度重要时使用 fill。
• 为人类观众调整复现视频的节奏。 在操作之间添加 sleep 1，在最终结果截图之前添加 sleep 2。视频应该能以 1 倍速观看——审查报告的人需要看到发生了什么，而不是一连串瞬间的状态变化模糊影像。
• 高效使用命令。 当多个 agent-browser 命令彼此独立时，可以将它们合并到单个 shell 调用中（例如，agent-browser ... screenshot ... && agent-browser ... console）。使用 agent-browser --session {SESSION} scroll down 300 进行滚动——不要使用 key 或 evaluate 来滚动。

参考

模板