wreck-it

wreck-it：在使用者之前，破壞你的應用程式

WRECK 在下方代表 npx @miyanishar/wreck-it。這個 CLI 執行確定性的工作（設定、探索、掃描、模糊測試、頁面速度、負載、發現、分數、報告、測試）。你透過 Playwright MCP 驅動瀏覽器，扮演使用者角色，判斷什麼是錯誤並追溯到程式碼。

只產出報告。 在運行期間不要修復錯誤，除非使用者要求在報告之後。

規則（永遠遵守）

• 僅限本地。 CLI 拒絕非本地目標。只有當使用者聲明擁有遠端目標時，才傳入 --i-own-this。
• 僅限假資料。 使用測試帳號、假名字，絕對不使用真實的個人或付款資料。將你建立的項目命名為 wreck-it …，並記錄它：WRECK run created "<項目>" --by <角色>（報告會列出這些項目供清理）。
• 寫入前先詢問。 預檢的 safety.ask 會列出問題：是否使用託管的（通常是正式環境）資料庫、真實的 Stripe 金鑰、沒有可讀收件匣的電子郵件、付費的 AI/SMS 呼叫。在一條訊息中一次問完所有問題，然後在一般使用者傳遞之前，將每個「是」記錄在 .wreck-it/config.json 中（allowRemoteDb、testEmail、allowSideEffects）。如果資料庫是正式環境，提議停止，以便他們將應用程式指向開發專案。
• 金錢和訊息。 僅使用 Stripe 測試金鑰（卡號 4242 4242 4242 4242）付款；使用真實金鑰時，在付款步驟停止。除非允許，否則每個流程觸發 AI/SMS/電子郵件操作最多 2-3 次。fuzz 和 load 會跳過那些端點。
• 電子郵件。 使用來自 WRECK email new 的地址註冊，絕不使用 example.com。對於本地收件匣，你自己讀取連結（WRECK email read --to <地址>）；否則要求使用者提供，或將檢查標記為「已跳過：沒有可讀收件匣」。
• 保持共享登入有效。 絕不要登出、刪除或更改其他階段使用的共用帳號密碼：在 Supabase 和許多應用程式中，登出會終止該使用者的所有階段。最後使用一次性帳號測試登出和刪除。

聚焦運行（單一功能）

當使用者指定一個功能或流程（「測試結帳」、「/wreck focus signup」）時，僅在幾分鐘內測試該項目：

1. 執行 WRECK run init --focus "<功能>"、WRECK discover、WRECK setup --dry-run 和 WRECK preflight --wait 5，如同階段 1 處理。僅在功能需要時才登入（階段 2）。僅在功能會寫入資料時才詢問 safety.ask 問題。
2. 界定範圍。 從 discovery.json 和程式碼中，列出該功能的頁面和 API 路由（例如 /cart、/checkout、/api/cart、/api/orders）。用一句話告訴使用者範圍。
3. 測試它（跳過不適用的角色和階段；將它們標記為 skipped）：
   • 先以一般使用者身份操作該功能，然後以倉促的初學者身份在手機上操作（雙擊、錯誤格式、流程中返回）。檢查探索技能適用的核對清單項目（總計、持久性、刪除、錯誤訊息）。
   • 執行 WRECK sweep --record --only <頁面…> 和 WRECK fuzz --record --only <API 路由…>。
   • 混沌技能中的惡意輸入、雙重提交、導航和網路故障，僅針對此功能的表單。
   • 如果該功能有自己的頁面，則執行 WRECK perf --record <頁面…>。
4. 重現並追蹤每個發現（階段 9），然後執行 WRECK report && WRECK gen-tests。報告標記為聚焦運行：說「功能分數」，而不是「就緒度」。

執行管線

用 WRECK run stage <階段名稱> running|done|skipped|failed 標記階段。發現會隨著進行而儲存。

1. 設定與預檢

WRECK run init               # --fresh 會丟棄之前運行的發現
WRECK discover
WRECK setup --dry-run        # 檢查已安裝和缺少的項目
WRECK preflight --wait 5

• 如果 setup --dry-run 列出任何需要安裝的項目，顯示它並詢問一次；如果確認，執行 WRECK setup。如果它新增了 MCP 伺服器，瀏覽器工具只會在使用者重新啟動代理後出現：告知使用者，並同時提供僅 CLI 的運行。
• 瀏覽器工具顯示「Browser … is not installed」：執行 WRECK setup --skip playwright-mcp devtools-mcp，然後重試。
• 預檢退出碼 4（應用程式無法連線）：提供在背景啟動 devScript 的選項，然後執行 WRECK preflight --wait 60。退出碼 3（目標拒絕）：停止並解釋。
• 沒有 .wreck-it/config.json：建立 {"baseUrl": "http://localhost:3000"}（使用真實埠號）。
• 僅 CLI 運行（沒有瀏覽器工具）：執行 sweep --record、fuzz --record、perf --record、階段 7 和報告；將 personas、normal、explore、chaos 標記為 skipped 並說明原因。絕不要假裝你點擊了應用程式。

2. 登入

• Google、GitHub、SSO、託管登入、魔法連結、2FA（discovery.json 中 auth.sso 已設定，或沒有密碼欄位）：告訴使用者「瀏覽器視窗將會開啟。請以你的測試使用者身份登入；一旦你登入，它會自動關閉。」執行 WRECK login（它會等待最多 10 分鐘；請使用長時間逾時）。其輸出應顯示 check: valid。對於雙使用者檢查，要求執行 WRECK login --label second；對於新帳號檢查，使用 --label fresh，或將它們標記為 skipped。
• 電子郵件和密碼： 註冊一個測試帳號（或使用使用者的），並將 "accounts": [{"label": "main", "email": "…", "password": "…"}] 新增到設定檔。
• 之後：sweep、fuzz 和 perf 會自行登入。在瀏覽器中，在訪問需要登入的頁面之前，使用 {"filename": ".wreck-it/auth/<標籤>.json"} 呼叫 browser_set_storage_state。記錄為已登入的發現會取得 "auth": "<標籤>"，且步驟從登入後開始。
• 如果預檢或 WRECK login --check 顯示 expired，要求使用者再次執行 login。

3. 使用者角色

使用 wreck-personas 技能。

4–5. 一般使用者，接著是使用者角色

使用 wreck-explore 技能。在 Claude Code 搭配外掛程式時，最多可以同時以 wreck-persona 子代理執行 3 個角色，每個瀏覽器一個（wreck-browser-1..3）；同時不要自己使用瀏覽器，並在階段 6 之前等待所有角色完成。其他代理：一個接一個地執行角色。

6. 混沌

使用 wreck-chaos 技能（掃描、API 模糊測試、惡意輸入、雙重提交、導航、網路故障、會話篡改、鍵盤）。

7. 頁面速度與負載

使用 wreck-load 技能。

8. 安全性

不在 v1 中：WRECK run stage security skipped。

9. 重現，然後追蹤

執行 WRECK finding list：在新環境中重播每個帶有 ? 的發現，如果再次出現則設定 reproduced: true（未重現的發現不計分）。然後對每個沒有 source 的重現發現使用 wreck-trace 技能。

10. 報告

在產生報告之前，檢查每個重現的瀏覽器發現是否有一張顯示實際失敗的螢幕截圖。也要重新檢視來自 CLI 掃描的發現；遵循 references/recording-findings.md 中的螢幕截圖指南。驗證已儲存的圖片檔案存在，並解決任何缺少截圖的警告。僅 API 或負載的發現可能改用請求/指標作為證據；當螢幕截圖不適用或無法擷取時要說明。

在最後一次發現更新之後產生報告和測試。如果你之後更改了發現，在呈現結果之前重新產生兩者。閱讀 references/regression-tests.md：檢查保留的規格警告，並將那些測試與更新的發現進行協調；重新產生會刻意保留代理的編輯和 fixture。針對有錯誤的應用程式執行支援的規格，並檢查失敗是否達到預期的斷言。在報告中揭露跳過的項目、設定失敗、超時或未經驗證的測試；如果存在修正後的副本，也要針對它檢查相同的規格。

WRECK report && WRECK gen-tests && WRECK run stage report done

探索期間（階段 4–6）

• 嚴格按照 references/recording-findings.md 記錄錯誤：使用 WRECK finding add、結構化步驟、角色/標籤目標、描述正確行為的斷言，然後在新環境中重播並設定 reproduced: true。
• 每次導航後，透過 browser_evaluate 執行異常腳本（WRECK oddity-script，一次），並檢查 browser_console_messages 和 browser_network_requests（4xx/5xx）。也要尋找腳本無法判斷的問題：破損的版面、沒有引導的空白狀態、無止境的載入動畫、失效的按鈕、不一致的日期或價格。將真實的問題記錄為 oddity。
• 記錄覆蓋率：WRECK run visit <路由> --persona <名稱>。

最終訊息

簡短說明：分數和等級、「優先修復此問題」的發現及其 file:line、按嚴重性計數、未完成的階段、路徑 .wreck-it/report.html、.wreck-it/report.md、tests/wreck-it/ 和 npx playwright test tests/wreck-it。提議修復最重要的發現；等待使用者同意。

在呈現錯誤時，在其發現 ID 和說明旁邊附上相關的螢幕截圖。使用聊天的圖片附件功能或 Markdown 圖片，並使用實際的已儲存檔案路徑；僅提供報告路徑無法顯示證據。在聊天中呈現最重要的發現及其截圖，並在報告中保留完整的集合。如果圖片不可用或不適用，說明原因並連結請求、追蹤或指標。將儲存的 shots/... 路徑解析為相對於 .wreck-it/ 的路徑。

對於你在聊天中包含的每個瀏覽器發現，使用以下格式（將範例替換為實際發現和驗證過的絕對圖片路徑）：

**WR-007 — 購物車小計忽略數量** (`lib/cart.ts:19`)
三件 $79.99 的商品總計應為 $239.97；頁面顯示 $79.99。
![WR-007: 數量 3 但小計不正確](/absolute/project/.wreck-it/shots/WR-007-cart.png)

在發送之前，開啟你計劃呈現的每張圖片，並描述它實際顯示的狀態和數值。驗證你呈現的每個瀏覽器發現都附有圖片附件或圖片嵌入。一份圖片檔名列表或一句「截圖已儲存」的陳述不是附件。透過呈現較少的發現及其證據，並連結完整報告，來保持回應簡潔；將剩餘的瀏覽器發現留在該報告中，而不是在聊天中新增一個沒有圖片的列表。