meticulous-simulate-and-diff

模擬工作階段並分析差異

本技能涵蓋執行單次模擬並解讀結果。關於 simulate 指令的完整選項參考，請參閱 meticulous-cli 技能的 simulate 參考。

開始前，請先執行 meticulous-cli-update 技能以確保 Meticulous CLI 為最新版本——除非本次對話中已執行過，則可跳過。

前置需求

• 一個要重播的 sessionId
• 一個 appUrl（本機開發伺服器，或留空以使用原始錄製的 URL）
• 可選：一個 baseReplayId——用於比對螢幕截圖差異的先前重播 ID。若無此 ID，螢幕截圖仍會儲存但不會進行比對。

若沒有 baseReplayId，可從下載的測試執行中取得：

meticulous download test-run
# 然後檢查 ~/.meticulous/test-runs/<testRunId>/coverage.json
# 或查看 testCases[].replayId 欄位

步驟 1 — 執行模擬

搭配基準重播（差異模式）

meticulous simulate \
  --sessionId=<sessionId> \
  --appUrl=<url> \
  --baseReplayId=<baseReplayId> \
  --headless

擷取完整的標準輸出。需注意的關鍵資訊：

# 每張螢幕截圖的差異結果（每行一個）：
0.412% pixel mismatch for screenshot screenshot-1234.png (threshold is 0.100%) => FAIL!
0.000% pixel mismatch for screenshot screenshot-5678.png (threshold is 0.100%) => PASS

# 最終摘要區塊：
=======
View simulation at: https://app.meticulous.ai/projects/<org>/<project>/simulations/<headReplayId>
View comparison with base: https://app.meticulous.ai/projects/<org>/<project>/simulations/<baseReplayId>/compare-to/<headReplayId>
=======

若無任何 FAIL! 行： 表示工作階段與基準視覺上相同——回報無回歸，然後直接進行步驟 6。

若發現差異，請繼續步驟 2–6 以定位並分析差異，然後提交回饋。

無基準重播（快速檢查模式）

若無 baseReplayId，則省略該參數。螢幕截圖仍會儲存在本機，可直接進行視覺檢查：

meticulous simulate \
  --sessionId=<sessionId> \
  --appUrl=<url> \
  --headless

然後找到重播目錄（步驟 2），並在 <replayDir>/screenshots/ 中開啟螢幕截圖以確認 UI 是否正確。此模式下無差異圖片——檢查純屬視覺比對。步驟 3–5 不適用；檢查後仍須完成步驟 6。

步驟 2 — 提取 head 重播 ID 並找到重播目錄

從 View simulation at: 的 URL 中提取 <headReplayId>（最後一個路徑片段）。

若要找到本次執行所建立的本地重播目錄：

ls -lt ~/.meticulous/replays/ | head -5

最新建立的項目即為 head 重播的目錄（以時間戳命名，例如 2024-01-15T12-30-45.123Z-abc123/）。記下此路徑——以下稱為 <replayDir>。

步驟 3 — 找出哪些螢幕截圖有差異

ls ~/.meticulous/replays/<replayDir>/diffs/<baseReplayId>/

此處的每個 .png 檔案對應於偵測到視覺差異的螢幕截圖。像素差異圖片會以彩色標示變更的像素。此外還有 thumb_ 前綴的縮圖版本。

請注意檔案名稱——它們與螢幕截圖識別碼相符（例如 screenshot-after-event-42.png）。

步驟 4 — 分析每張差異螢幕截圖的 HTML 差異

每張螢幕截圖都有一個對應的中繼資料檔案，其中包含在截圖前一刻的完整 HTML 快照。這些檔案已存在於磁碟上：

• Head 中繼資料： ~/.meticulous/replays/<replayDir>/screenshots/<screenshotFilename>.metadata.json
• 基準中繼資料： ~/.meticulous/replays/<baseReplayId>/screenshots/<screenshotFilename>.metadata.json

基準中繼資料在模擬下載基準重播時會永久快取，因此無需額外下載。

讀取兩個 .metadata.json 檔案。相關欄位為：

• before.dom — 截圖時的完整頁面 HTML；比對這兩個字串以了解變更內容
• before.routeData.url — 截圖所在的頁面/路由

比對 HTML 時，請專注於標籤的新增/移除、class 屬性的變更以及文字內容的變更。

標準輸出中每張螢幕截圖的結果行也會報告 mismatchFraction（變更像素的比例）。若像素有差異但 before.dom 字串完全相同，則變更純屬視覺（例如顏色變化）而非結構性。

步驟 5 — 總結發現

本技能的主要輸出是一份高階、人類可讀的描述，說明視覺上變更了什麼以及原因。利用上述收集的像素差異計數、路由 URL、變更的類別名稱和 HTML 差異來回答：使用者體驗發生了什麼變化，以及 UI 的哪個部分造成此變化？

以適合當前脈絡的格式呈現（對話式回答、結構化報告、輸入至呼叫工作流程等）。可參考的有用訊號：

• 哪些路由受到影響
• 哪些 CSS 類別出現在變更的 DOM 區域中（這些通常直接對應到元件）
• 變更是結構性（DOM 新增/移除）還是純視覺（像素位移但 HTML 無差異）
• 同一變更是否出現在多張螢幕截圖中（暗示共用元件變更）還是僅限於單張截圖

標準輸出中記錄的比較 URL 總是值得提供，因為它讓人類可以快速以視覺方式驗證差異：
https://app.meticulous.ai/.../simulations/<baseReplayId>/compare-to/<headReplayId>

步驟 6 — 向 Meticulous 回報回饋

作為最後一步，在回報結果（無回歸或總結發現）後，向 Meticulous 團隊提交一則簡短的回饋：模擬和差異是否有助於驗證變更？是否有任何令人困惑之處？哪些資訊能讓任務更輕鬆？

meticulous agent submit-feedback --message="<一兩句話>" --outcome=<helped|neutral|hindered> --skill=meticulous-simulate-and-diff

MCP 工具：submit_feedback。

備註

• 位於 ~/.meticulous/replays/<replayDir>/diffs/<baseReplayId>/ 的像素差異圖片可直接開啟進行視覺檢查。
• 若省略 --baseReplayId，則無法進行差異分析。螢幕截圖仍會儲存在本機，之後可透過將 --baseReplayId 設為第一次執行的 head 重播 ID 來重新執行以進行比較。
• 關於完整的迭代開發工作流程（工作階段發現、逐步提交和最終雲端執行），請參閱 meticulous-iterative-dev 技能。