dogfood 是做什麼的？
系統化探索 Web 應用程式，找出問題，並為每個發現產出具完整重現證據的報告。
設定
只需要提供目標 URL。其他參數都有合理的預設值，除非使用者明確提供覆寫值，否則請使用預設值。
| 參數 | 預設值 | 覆寫範例 |
|---|---|---|
| 目標 URL | (必要) | vercel.com、http://localhost:3000 |
| 工作階段名稱 | 網域 slug（例如 vercel.com -> vercel-com） | --session my-session |
| 輸出目錄 | ./dogfood-output/ | Output directory: /tmp/qa |
| 範圍 | 整個應用程式 | 專注於帳單頁面 |
| 驗證 | 無 | 以 [email protected] 帳號登入 |
如果使用者說「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 domcontentloaded
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
# 將以下內容替換為目標應用程式登入後的 URL、文字或 JS 條件：
agent-browser --session {SESSION} wait --url "{POST_LOGIN_URL_PATTERN}"
# 或者：
# agent-browser --session {SESSION} wait --text "{POST_LOGIN_TEXT}"
# agent-browser --session {SESSION} wait --fn "{POST_LOGIN_CONDITION}"
對於 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、操作時的主控台錯誤）
這類問題需要使用者互動才能重現 — 使用包含影片和逐步截圖的完整重現：
- 在重現前先啟動重現影片：
agent-browser --session {SESSION} record start {OUTPUT_DIR}/videos/issue-{NNN}-repro.webm
- 以人類操作的速度逐步重現。 在每個動作之間暫停 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
# ...繼續直到問題出現
- 捕捉問題發生的狀態。 暫停讓觀看者能看清楚，然後拍攝註解截圖：
sleep 2
agent-browser --session {SESSION} screenshot --annotate {OUTPUT_DIR}/screenshots/issue-{NNN}-result.png
- 停止影片：
agent-browser --session {SESSION} record stop
- 在報告中撰寫編號的重現步驟，每個步驟都要引用其對應的截圖。
靜態 / 載入即可見的問題（錯字、佔位文字、文字被截斷、排版錯誤、載入時的主控台錯誤）
這類問題不需要互動即可看到 — 一張註解截圖就足夠了。不需要影片，也不需要多步驟的重現：
agent-browser --session {SESSION} screenshot --annotate {OUTPUT_DIR}/screenshots/issue-{NNN}.png
在報告中撰寫簡短描述並引用該截圖。將重現影片設為 N/A。
對於所有問題：
-
立即附加到報告中。 不要將問題批次留到最後。每發現一個問題就立即寫入，這樣即使工作階段中斷，也不會遺失任何內容。
-
遞增問題計數器（ISSUE-001, ISSUE-002, ...）。
6. 結尾
目標是找出 5-10 個記錄完善的問題，然後結尾。證據的深度比總數更重要 — 5 個有完整重現的問題勝過 20 個描述模糊的問題。
探索完畢後：
- 重新閱讀報告，更新摘要中的嚴重性計數，使其與實際問題相符。每個
### ISSUE-區塊都必須反映在總數中。 - 關閉工作階段：
agent-browser --session {SESSION} close
- 告知使用者報告已準備就緒，並總結發現：問題總數、按嚴重性分類，以及最重要的項目。
指導原則
- 重現即是一切。 每個問題都需要證據 — 但要將證據與問題匹配。互動式錯誤需要影片和逐步截圖。靜態錯誤（錯字、佔位文字、載入時可見的視覺問題）只需要一張註解截圖。
- 在收集證據前先驗證可重現性。 在錄製影片或拍攝截圖前，至少重試一次以確認問題是可重現的。如果無法一致地重現，就不是有效的問題。
- 靜態問題不要錄製影片。 錯字或被截斷的文字並不會因為影片而變得更有價值。僅在問題涉及使用者互動、時間差或狀態變更時才使用影片。
- 對於互動式問題，每個步驟都要截圖。 捕捉「之前」、「動作」和「之後」的狀態，讓別人可以看到完整的序列。
- 撰寫與截圖對應的重現步驟。 報告中每個編號步驟都應引用其對應的截圖。讀者應該能夠在不碰觸瀏覽器的情況下，透過視覺方式跟隨步驟。
- 使用正確的快照指令。
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 | 複製到輸出目錄作為報告檔案 |