dogfood

Dogfood

系统性地探索 Web 应用，发现问题，并为每项发现提供完整的复现证据，生成报告。

设置

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

参数	默认值	示例覆盖值
目标 URL	(必填)	vercel.com、http://localhost:3000
会话名称	转换为 slug 格式的域名（例如，vercel.com -> vercel-com）	--session my-session
输出目录	./dogfood-output/	输出目录：/tmp/qa
范围	整个应用	重点检查账单页面
身份验证	无	登录 [email protected]

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

始终直接使用 agent-browser，不要使用 npx agent-browser。直接调用二进制文件会使用快速的 Rust 客户端。npx 会通过 Node.js 运行，速度明显更慢。

工作流

1. Initialize    Set up session, output dirs, report file
2. Authenticate  Sign in if needed, save state
3. Orient        Navigate to starting point, take initial snapshot
4. Explore       Systematically visit pages and test features
5. Document      Screenshot + record each issue as found
6. Wrap up       Update summary counts, close session

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
# Identify login form refs, fill credentials
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 步要同时进行——边探索边记录。发现问题时，先停下探索并立即记录，然后再继续。不要先探索整个应用，再事后记录。

每个问题都必须可复现。发现问题时，不要只做记录——要用证据证明问题。目标是让阅读报告的人能够清楚地看到发生了什么，并重新复现整个过程。

根据问题选择合适级别的证据：

交互／行为问题（功能问题、UX 问题、操作时出现的控制台错误）

这些问题需要通过用户交互来复现——使用完整的复现视频和逐步截图：

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
# Perform action (click, fill, etc.)
sleep 1
agent-browser --session {SESSION} screenshot {OUTPUT_DIR}/screenshots/issue-{NNN}-step-2.png
sleep 1
# ...continue until the issue manifests

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

简要描述问题，并在报告中引用截图。将 Repro Video 设为 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 命令彼此独立（例如 agent-browser ... screenshot ... && agent-browser ... console），请在同一个 shell 调用中批量执行。滚动时请使用 agent-browser --session {SESSION} scroll down 300，不要用 key 或 evaluate 滚动。

参考资料

参考资料	阅读时机
references/issue-taxonomy.md	会话开始时 — 校准检查重点、严重程度和探索清单

模板

模板	用途
templates/dogfood-report-template.md	复制到输出目录，作为报告文件