meticulous-review

若要審查 Meticulous 測試執行，請依照下列工作流程逐步操作，並使用所述 CLI 指令。

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

此工作流程中的每個 meticulous agent … 指令，在託管的 Meticulous MCP 伺服器 上都有對應的工具，名為 get_…（例如 agent test-run-diffs → get_test_run_diffs）。每個工具回傳的資料與 CLI 指令的 --json 輸出相同。以下步驟使用 CLI 指令，並標註對應的 MCP 工具。

評估前端視覺變更

先取得差異概覽，再逐一檢查每個差異。預設摘要會回傳預先選取的代表性集合 — 每個獨特的結構性 DOM 變更對應一張截圖 — 因此每個回傳列都值得檢查。列會按優先順序回傳（最具代表性/最重要的優先），請從上到下逐一處理。 對於每個差異，務必先查看截圖影像（步驟 2）— 差異影像是最能了解實際變更的資訊。使用 DOM 差異（步驟 3）取得額外結構細節，而時間軸（步驟 4）僅在差異出乎意料且無法由 DOM 或影像解釋時使用。

若要判定 PR 沒問題，每個回傳的差異都必須檢查並確認 — 每個差異都應歸類為預期或可解釋（請參閱決策指南）。只有在沒有未解釋或非預期的變更時，PR 才算安全可核准。最終報告應涵蓋所有顯著的視覺變更：每個變更都應有各自的說明。

步驟 1 — 取得重播差異摘要

從本地檢出執行，以從當前提交的 git HEAD 解析測試執行 — 這是在審查或監控已在本機檢出分支的合併請求時的常見情況。首先確保 HEAD 與 CI 執行的遠端 HEAD 一致（例如 git pull），否則可能審查到過時或遺失的執行：

meticulous agent test-run-diffs

MCP 工具：get_test_run_diffs。

所有非結果輸出會送到 stderr（stdout 僅攜帶差異表格）；傳入 --verbose 可查看解析的提交和 testRunId。若要明確指定執行，請傳入以下其中之一：

• --testRunId <id> — 20 個字元以上的英數字串（例如 aB3xK9LmN7QrStUvWxYz12）。
• --commitSha <sha> — 使用該提交的最新測試執行。對於合併請求，請解析其 HEAD 提交 SHA（例如透過託管平台的 CLI 或 API），然後在此傳入。

如果解析的執行仍在進行中，指令會阻塞直到完成並顯示差異（等待是預設行為）；傳入 --dontWaitForTestRunToComplete 則會回報進行中的執行並立即結束。如果找不到該提交的執行，表示執行尚未觸發 — 請等待並重新執行，或詢問使用者。

輸出格式： stdout 為 TSV，stderr 為中繼資料。

輸出僅涵蓋視覺差異 — 相符的截圖、已知的 flake，以及分歧點下游的截圖不會包含在內。預設進一步限制為選取的截圖 — 每個獨特結構性 DOM 變更對應一張截圖的代表性子集。列會按優先順序回傳（最具代表性/最重要的優先）— 請依此順序檢查。

stdout 欄位：

replayDiffId	screenshotName	index	outcome	mismatchFraction

index 是列的全局排名（上述優先順序）；使用 --orderByReplayDiffs 時，則改為按重播差異分組排名。

輸出範例：

CqctwLpPC7	after-event-0	1	diff	0.00234
RRMGQft7PD	after-event-174	2	diff	0.01050
CLkCJ8WLrJ	after-event-8	4	diff	0.00100

每列代表一個在基準（之前）和 HEAD（之後）重播之間比較的截圖，且是已確認的視覺差異 — 每列都有 outcome=diff。列按優先順序排列。

• outcome 永遠是 diff — 基準和 HEAD 之間的視覺像素差異。非差異的截圖（相符、新增/移除的截圖、分歧點下游的截圖）不屬於此摘要；若要查看，請將 screenshotName 傳給 agent image-files / agent dom-diff（步驟 2-3），並透過 agent timeline-diff 發現可用的名稱。
• mismatchFraction（0-1，5 位小數）是像素不匹配比例 — 基準和 HEAD 截圖之間差異像素的比例（0 = 完全相同，越高表示影像變更越多）。較大的 mismatchFraction 是變更幅度大的快速提示，但無論如何都應檢查差異影像，因為即使很小的比例也可能是有意義的變更。

stderr 顯示：總數、唯一差異數和時間細項。每個回傳列都必須在審查中說明 — 檢查每個列（步驟 2-3），並在結論 PR 沒問題之前，確認它是預期或可解釋的。

可選旗標（用於擴展輸出，超出預設選取子集）：

• --includeDomDiffIds — 新增 domDiffIds 欄位：一個分號分隔的有序差異 ID 列表，每個 ID 對應截圖中的一個獨立 DOM 變更。相同 ID 表示跨截圖的結構相同 DOM 變更。範例：1;3 表示兩個獨立 DOM 變更，ID 分別為 1 和 3。特殊值：none 表示未找到 DOM 變更（視覺差異純屬像素層級，例如反鋸齒 — 請檢查截圖影像以了解）；error 表示嘗試 DOM 差異但失敗（例如中繼資料不可用）。可與 --includeAllDiffs 搭配使用，查看選取子集如何涵蓋所有唯一差異 ID。
• --includeAllDiffs — 回傳所有差異，而不僅是選取的代表性子集。新增 isSelected 欄位（true/false），標記哪些列屬於選取子集。
• --orderByReplayDiffs — 按重播差異分組排序列（每個 session 的截圖視為流程），而非按全局優先順序；此時 index 在該分組內排名。輸出仍為平面列列表（每列一個截圖），無論是 TSV 還是 --json — 這僅改變排序和 index 值。

步驟 2 — 取得截圖影像

對於每個代表性截圖：

meticulous agent image-files --replayDiffId <replayDiffId> --screenshotName <screenshotName>

這會將截圖影像下載到 ~/.meticulous/agent-images/，並列印本地檔案路徑。

MCP 工具：get_image_urls 回傳相同的結果和簽名影像 URL，請取得 URL 以檢視影像。

輸出格式：

outcome:	<outcome>
before:	<path>              # 基準影像；當 outcome 為 missing-base 時省略
after:	<path>               # HEAD 影像；當 outcome 為 missing-head 時省略
diffImage:	<path>           # 僅在 diff 結果時出現

開啟 before、after 和 diffImage 檔案以視覺檢查變更。diffImage 通常資訊最豐富 — 它會精確標示哪些像素變更了。即使 DOM 差異很清楚，也務必檢查影像以了解變更的實際視覺影響。

替代方案：使用 image-urls 而非 image-files，以取得影像 URL 而非下載到本地。

步驟 3 — 檢查 DOM 差異（結構細節）

meticulous agent dom-diff --replayDiffId <replayDiffId> --screenshotName <screenshotName>

MCP 工具：get_dom_diff。

可選：傳入 --context <N|full> 控制每個區塊周圍的上下文行數（預設 3）。使用 --context 0 表示無上下文，或 --context full 表示包含完整檔案上下文的單一統一差異。

輸出格式： 統一差異（+/- 格式），移除前導縮排。所有差異區塊以 [diff 0]、[diff 1] 等標題分隔。範例：

[diff 0]
 <span class="text-zinc-400">#7687</span>
-<span class="min-w-0 flex-1 truncate transition-colors">Use divergence-aware comparison</span>
+<span class="min-w-0 flex-1 truncate transition-colors" data-tooltip-id=":r1h:">Use divergence-aware comparison</span>
[diff 1]
 <span class="inline-flex items-center rounded-lg bg-zinc-800">Temporal Workflow</span></a>
+<a href="/projects/Foo/Bar/test-runs/abc123"><span class="inline-flex items-center rounded-lg bg-zinc-800">Original: abc123</span></a>

步驟 4 — 取得重播時間軸（可選，用於診斷非預期差異）

如果差異出乎意料，且影像/DOM 無法清楚說明原因：

meticulous agent timeline-diff --replayDiffId <replayDiffId>

MCP 工具：get_timeline_diff。

輸出格式： stdout 為 TSV。

stdout 欄位：

diff	timeMs	event	description

• diff 欄位： （相同）、-（移除）、+（新增）、!（變更）
• event 類型：user、screenshot、network、console、debug、urlChange、error、fatalError 等
• description：事件的簡潔一行摘要

尋找異常情況，例如失敗的網路請求、非預期的重新導向，或可能解釋視覺變更的時序相關差異。

決策指南

對於每個代表性截圖，根據差異影像和 DOM 差異將視覺變更分類為預期或非預期：

• 預期：視覺變更是您正在處理任務的期望結果。確認後繼續。
• 非預期：變更並非任務目標。這包括與您的程式碼明顯無關的變更，以及 — 通常更重要 — 您的程式碼變更產生的非預期副作用。變更可以被您的程式碼解釋並不代表它是預期的；如果任務不需要該視覺變更，它就是非預期的。

對於非預期變更：

1. 如果變更是程式碼的副作用，請嘗試修正，使程式碼在不產生非預期視覺變更的情況下達到預期結果，然後重新執行測試。
2. 使用時間軸（步驟 4）檢查失敗的網路請求、重新導向或其他可能解釋與程式碼無關差異的異常情況。
3. 如果您能自信地解釋原因（例如不穩定的時間戳、非確定性元素），請記錄說明。
4. 如果您無法解釋或修正，請向使用者標記。

最終報告

在調查所有差異並嘗試修正任何可修正問題後，產出涵蓋所有顯著視覺變更的摘要。說明點的數量應至少與您檢查的代表性差異數量相同 — 每個視覺變更都應有各自的說明。

1. 預期變更：對於每個屬於任務期望結果的獨特視覺變更，描述視覺上變更了什麼（根據差異影像）以及為何是預期的。
2. 非預期變更（如有）：對於每個變更，包含：
   • 代表性的 replayDiffId / screenshotName
   • 視覺變更的樣貌（例如「新增徽章元素」、「標題佈局偏移」）
   • 是程式碼的副作用還是無關，以及您對原因的最佳評估

只有當每個回傳的差異都已檢查並說明 — 每個都確認是預期或可解釋 — 時，PR 才算沒問題。如果仍有任何差異是非預期或未解釋的，PR 還不算好：請修正，或清楚地向使用者提出。

向 Meticulous 回報意見回饋

作為最後一步，在提供最終報告後，向 Meticulous 團隊提交一則簡短的意見回饋：Meticulous 是否捕捉到真正的問題？是否有任何令人困惑或誤導的地方？哪些資訊會讓審查更容易？

meticulous agent submit-feedback --message="<一兩句話>" --outcome=<helped|neutral|hindered> --testRunId=<id> --skill=meticulous-review

MCP 工具：submit_feedback。