frame-judge

frame-judge 是做什麼的？

你不能自行評斷自己的視覺作品。

你建構它、渲染它。然後一個獨立的評審者會根據實際呈現的畫面，對照使用者實際提出的要求來評判。評審者永遠看不到你的程式碼、你的推理過程，或你對結果的意見。直到作品通過評審，或達到回合上限，你都不能宣稱它完成、打磨完善、流暢或精美。

原因：撰寫程式碼的模型會將自己的意圖讀入輸出中。它「看到」的是它想寫的行走循環，而不是實際渲染出來的那個。一個只看見像素和使用者文字的評審者無法做到這點。它必須實際觀看。

<skill> 指的是此檔案所在的資料夾（在 Claude Code 中為 ${CLAUDE_SKILL_DIR}）。腳本為純 Node 18+，無需安裝步驟。它們在工作目錄下的 .frame-judge/ 中維護狀態。

循環流程

步驟	內容	執行者
0	鎖定使用者的請求，一字不漏	你
0b	詢問「unsloppy?」。如果是，偵察員會研究要避免的 AI 預設行為	你、使用者、偵察員
1	建構	你
2	渲染並捕捉：螢幕截圖、影格表、運動軌跡	腳本
3	機械式自我檢查：確保有渲染、沒有空白、沒有執行時期錯誤	你
4	打包一個不含程式碼的審查包	腳本
5	詢問評審者跑在哪個模型上（如果平台允許僅一次）	你，然後使用者
6	評審者審查打包內容	全新子代理
7	閘門驗證評審結果並做決定	腳本
8	回覆每一個必須修正的發現，然後回到步驟 2	你
9	報告評審者的裁決，而非你的意見	你

預設上限：3 個評審回合。

0. 鎖定簡報

node <skill>/scripts/judge.mjs init --brief-file request.txt --kind frontend,motion

使用 --brief "..." 輸入內嵌文字，或使用 --brief-file - 從標準輸入讀取。

• 一字不漏。 儲存使用者的訊息原文：錯字、大小寫、全部保留。切勿改寫、摘要或「釐清」它。評審者是根據他們的文字來評判，而不是你對它們的解讀。
• 使用者後續的釐清 透過 judge.mjs brief --add "<他們的確切文字>" 加入。你自己的假設永遠不該加入。
• 使用者提供的參考圖片： 加入 --ref mock.png（可重複），以便評審者與之比較。
• --kind 選擇評分標準：frontend 用於頁面和 UI，motion 用於任何動畫，video 用於短片和剪輯。如果省略，則從捕捉內容自動偵測。
• --critic-model 如果使用者已指定模型。

這會建立 .frame-judge/（它會將自己加入 gitignore），其中包含 brief.md 和 ledger.json。ledger 會維持狀態，不受上下文壓縮影響。如果你追蹤不到，請執行 judge.mjs status。

0b. 詢問 unslop 模式（建構前）

只問使用者一次，使用以下措辭：

你想要 unsloppy 嗎？（實驗性：可能會降低品質並消耗更多 token）

在 Claude Code 中，使用 AskUserQuestion 提問，並與步驟 5 的評審者模型問題放在同一個提示中。在其他地方，在聊天中提問。如果使用者已經回覆過，則跳過。

• 否： 繼續。未啟用 unslop。
• 是：
  1. 執行 judge.mjs set unslop on，然後執行 judge.mjs scout。它會列印一條訊息給 slop 偵察員：一個具有網路搜尋功能的全新子代理，負責找出 AI 通常會如何搞錯這類請求。
  2. 將該訊息只傳送給偵察員，不要夾帶其他東西。與評審者相同的規則適用於偵察員：全新代理、無 fork、不附加任何內容。如果已設定評審者模型，則使用其模型。
  3. 儲存其回覆，然後執行 judge.mjs avoid --file <回覆>。這會拒絕沒有真實來源的清單。
• 無可用網路搜尋： 告訴使用者 unslop 無法在此執行，並繼續進行，不啟用此模式。

避免清單會放在 .frame-judge/avoid.md 中，並會包含在每個審查包中，因此評審者也會據此檢查作品。

「實驗性」是因為偏離預設值可能會導致建構走向奇怪的選擇，而且偵察員會消耗額外的一次代理執行和網路搜尋。

1. 建構

如果 unslop 已啟用，請先閱讀 .frame-judge/avoid.md。

• 圍繞每個模式進行設計。不要只是反轉它：目標是製作出符合簡報的作品，而不是僅僅與眾不同的作品。
• 使用者明確要求的任何事項優先於清單。

在開始建構之前，閱讀 references/craft.md[references/craft.md] 中有關你使用媒介的章節，每個會話一次。它涵蓋了評審者最常標記的問題：間距、字體、AI 生成模板的痕跡、緩動函數、行走循環、影片節奏。

對於任何動畫內容，讓時間成為一個明確的輸入：一個可以搜尋的時間軸，或是一個 window.frameJudgeSeek(ms) 鉤子。這使得捕捉可以精確到影格，並且可以輕鬆地將 HTML 轉換為影片。

2. 渲染與捕捉

頁面和 UI（需要 Playwright；安裝方式請參閱 references/capture.md）：

node <skill>/scripts/capture-page.mjs http://localhost:5173 --out .frame-judge/cap/page

預設值為桌面 1440×900、平板 768×1024 和手機 390×844，逐畫面捕捉。選項：

• --actions states.json 用於滑鼠懸停、選單和錯誤狀態
• --color-scheme dark
• --reduced-motion
• 支援本地檔案和 URL

頁面上的動畫。 這是精確到影格的（使用虛擬時鐘加上 Web Animations 搜尋），並編碼為 MP4：

node <skill>/scripts/capture-page.mjs scene.html --out .frame-judge/cap/anim --animate 3000 --fps 30 --selector "#hero"

任何影片，包括上面的 MP4：

node <skill>/scripts/video-frames.mjs .frame-judge/cap/anim/animation.mp4 --out .frame-judge/cap/anim-views --as motion

你會得到：

• 視口切片，而不是單一巨大的全頁圖片（後者會因縮小而變成糊狀）。
• 從你的 actions 檔案產生的狀態快照。
• 附時間戳的聯絡表。
• 膠捲底片：預設以 12 fps 取樣影格，並圍繞腳本偵測到的任何突然跳動或停滯，提供全速率膠捲底片（--motion-fps source 會給出每一幀）。取樣意味著一幀的閃爍可能落在圖塊之間，這就是為什麼存在事件偵測。
• 運動軌跡：應該保持靜止的保持銳利，滑動的則留下模糊軌跡。
• 客觀數字：持續時間、fps、黑色或凍結片段、水平溢出、損壞的圖片。

捕捉使用者會體驗到的內容：他們會使用的每個視口、重要的狀態、完整的動畫。評審者無法標記你沒有顯示給它的東西。忽略難看的部分正是這個技能要阻止的作弊行為。

3. 機械式自我檢查

在花費一個評審回合之前，檢查並修復二進位層面的問題：

• 有渲染
• 沒有空白或黑色影格
• 每個 capture.json 中的 builder_only 欄位沒有內容（主控台錯誤、失敗的請求）
• 持續時間和大小正確
• horizontal_overflow_px 和 broken_images 為零

就是這些。你不能自行決定它看起來很好就跳過評審。

4. 打包

node <skill>/scripts/judge.mjs bundle .frame-judge/cap/page .frame-judge/cap/anim-views

這會寫入 .frame-judge/round-N/bundle/。它只包含視覺檔案（png、jpg、webp、gif，如果你傳遞 --include-video 則包含影片），以及以下文字檔案：

• brief.md，並移除了程式碼區塊
• 評分標準
• CRITIC.md，評審者的說明
• manifest.json，包含可引用的工件 ID
• prior.json，從第 2 輪開始：包含開放的發現，不包含 你的「已修復」宣稱，以便評審者自行驗證

如果必須修正的發現未回覆，或超過回合上限，腳本將不會開啟新回合。它會列印應傳送給評審者的確切訊息。

圖片預算： 每回合目標為 20 張圖片或更少。Claude 在單一請求中超過 20 張圖片時，會收緊每張圖片的限制。每張圖片大約花費 ⌈w/28⌉×⌈h/28⌉ 個 token；一張 1440×900 的快照約為 1.7k。聯絡表和膠捲底片可以將 12 到 16 幀壓縮到一張圖片中，因此請多加利用。--slices 3 可以裁切長頁面。

5. 選擇評審者的模型（僅限平台支援的情況）

僅在你的平台允許你選擇子代理模型時詢問，並且僅詢問一次，在第 1 回合之前。如果使用者已指定模型則跳過。使用 judge.mjs set critic-model <別名> 儲存答案，並在每個回合重複使用。

平台	詢問？	方式
Claude Code、Claude 應用程式	是	AskUserQuestion，與 unslop 問題放在同一個提示中：Sonnet（平衡，建議）、Opus（最銳利，最多配額）、Haiku（最便宜，會遺漏細微問題）、與我相同
Codex 應用程式、Codex CLI	是	在聊天中提問，然後在你啟動評審者時傳遞選擇
Antigravity	否	沒有每次啟動的模型選擇。評審者使用其代理檔案設定運行；告知使用者。
其他任何平台	否	除非它明確支援每個子代理的模型。使用預設值，並告知使用者哪個模型審查了作品。

當你詢問時，請直接說明取捨。較弱的評審者較便宜，但它會幻覺更多缺陷，並遺漏細微問題。閘門可以抓到偽造的證據；它無法抓到糟糕的品味。

每個平台的確切語法：references/platforms.md。

6. 執行評審者

每個回合使用一個全新的評審者，因此它對 prior.json 之外沒有記憶，並且與其先前的判斷無關。將 bundle 列印的訊息傳送給它，不要夾帶其他東西：

你是影格評審者。你的套件位於 <abs path>。請閱讀 <abs path>/CRITIC.md 並嚴格遵循。不要開啟該資料夾之外的任何東西。僅回覆評審 JSON。

• 不要新增任何東西。 不要總結你建構了什麼，不要說「專注在 header」，不要說「我修好了腿」。你的意見是評審者絕對不能得到的輸入。如果使用者希望檢查什麼東西，它已經在簡報中，以使用者的文字呈現。
• 不要使用 fork。 永遠不要以 fork 或任何會繼承上下文的方式執行評審者。它會看到你的整個對話記錄，包括程式碼。
• 優先使用已安裝的代理。 如果存在 frame-critic，請使用它，因為它被限制只能讀取檔案。當技能作為 Claude Code 外掛程式安裝時，它的名稱是 frame-judge:frame-critic，在 Codex 中是 frame_critic。否則，使用一個通用子代理並傳送相同的訊息。
• Claude Code：如果可以，請執行沙箱。 如果 claude CLI 在 PATH 中，請執行 node <skill>/scripts/critic-sandbox.mjs 而不是啟動子代理。它會將評審者作為一個獨立的無頭程序執行於套件的私有副本上。該程序只有 Read 工具，加上一個鉤子，會阻止任何在該副本之外的讀取，並且腳本會自行把關審查（跳過步驟 7）。這是唯一一條程式碼盲審是被強制執行而非僅是要求的途徑。
• 所有其他平台： 使用會話內的子代理，程式碼盲審依賴於評審者的說明。在 Claude Code 上，步驟 7 中的對話記錄審計仍然可以抓到偷看的評審者。在 Codex、Antigravity 和 Cursor 上，沒有任何東西檢查它，因此請在你的報告中說明。

將回覆原封不動地儲存到 .frame-judge/round-N/review.json。

7. 閘門

node <skill>/scripts/judge.mjs gate --review .frame-judge/round-N/review.json --reviewer subagent --transcript auto

在 Claude Code 上，--transcript auto 會找到評審者子代理的對話記錄，因此閘門可以計算它實際開啟的圖片（而非它聲稱的），並在它觸及套件外任何東西時使審查無效。在其他地方，省略該旗標；覆蓋範圍隨後為自我報告，並且報告會說明情況。（critic-sandbox.mjs 會自動傳遞其自己的對話記錄。）

是閘門做決定，而不是評審者的心情，也不是你。它：

• 拒絕 引用不存在或評審者從未開啟的工件 ID 的發現、沒有證據的發現、不在簡報中的簡報引用，以及不良的嚴重性或信心值。
• 檢查覆蓋範圍： 僅當評審者開啟了每張圖片（如果存在對話記錄，則從中驗證；否則從其自己的 opened 列表中驗證）時，通過才計數。
• 檢查隔離： 如果有對話記錄，任何在套件之外的讀取都會使審查無效（RERUN_CRITIC）。
• 分類 其餘的：
  • must-fix：阻塞性或重大問題，信心值 0.6 或更高
  • verify：阻塞性或重大問題，信心值低於 0.6。更近距離地重新捕捉；不要盲目修復。
  • polish：次要問題
  • ignored：瑣碎問題
• 檢查 CRITIC.md 和評分標準沒有被編輯，因此沒有人放寬評審標準。
• 更新 ledger 並列印一個決定：

決定	意義	你的行動
PASS	沒有剩餘的 must-fix，簡報中的內容都沒有遺漏	報告（步驟 9）
SELF_PASS	同上，但來自自我審查的備援方案	報告，並說明並非獨立審查
REVISE	存在 must-fix 項目	步驟 8，然後新回合
RETHINK	評審者表示方法從根本上就錯了	在重建前告知使用者
STOP_MAX_ROUNDS	達到回合上限，仍然未通過	報告哪些是開放的，詢問是否繼續
STOP_PLATEAU	此回合未解決任何問題	停止循環。報告，詢問
RERUN_CRITIC	審查無法使用（無 JSON、大多為虛假證據）、來自跳過圖片的評審者的通過，或讀取其套件外部內容的評審者	在相同的套件上執行全新的評審者
STOP_CRITIC_UNRELIABLE	第二次無法使用的審查	建議更強的評審者模型或備援方案

8. 修正

按 ID 處理 must-fix 項目，阻塞性的優先。在下一個回合前回覆每一個：

node <skill>/scripts/judge.mjs respond R1-F2 fixed "contact foot planted for 4 frames"
node <skill>/scripts/judge.mjs respond R1-F4 disputed "gutters are equal on both sides" --evidence crop.png
node <skill>/scripts/judge.mjs respond R1-F6 wont-fix "user asked for this gradient" --quote "purple to blue gradient"

• disputed 需要視覺證據，例如裁切或額外影格。它會進入下一個套件，並由下一位評審者裁決。「CSS 寫著 16px」不是證據；像素才是。
• wont-fix 需要來自簡報的確切引用，證明修復會違反簡報。
• 修正原因，而非捕捉內容。 切勿為了躲避發現而更改捕捉方式：不要裁切掉損壞的頁尾、捨棄手機視口或修剪片段。
• 驗證項目和評審者的 requests： 更近距離地捕捉該位置（一個帶有 clip 的 action，一個更密集的 --motion 視窗），以便下一位評審者可以確認或否定它們。
• 不要退步 評審者在 keep 下列出的東西。