asset-size-matrix 是做什麼的？
一個主檔案，每個版位，不切掉重要元素，每份檔案都有收據。
這個技能是做什麼的
一次發佈通常不只需要一張圖。它需要一個連結預覽、一個影片縮圖、一張正方形貼文、一張直式貼文、一張 3:4 封面、一個直式限時動態、一個個人頁面橫幅、一個應用程式圖示、一個儲存庫預覽，可能還需要一個直式影片。每一個都有各自的像素尺寸、各自的檔案規則，以及各自的介面疊加：直式動態右側的按讚欄、縮圖角落的時長徽章、橫幅上方的大頭貼、圖示的圓角遮罩。
人們通常的做法是把裁切框拖來拖去十幾次。結果很常見：9:16 版本上標題被切掉一半、標誌被大頭貼遮住、在 4K 主檔上清晰可讀的文字在動態裡只有三個像素高、縮圖因為 2.3 MB 而被拒絕、短影片的音量比周圍內容安靜了 8 dB。
這個技能把這項工作變成一個表格。每個目標版位都變成一張版位卡，上面有數字和日期。主檔被標記一次：哪些區塊必須保留下來。一個小型規劃器會為每個版位計算，在保留這些區塊在版位安全區域內的前提下，最寬的裁切方式，並在無法裁切時清楚告知。然後每個匯出的檔案都會根據其版位卡進行檢查。
它解決的問題
- 裁切憑肉眼決定，一次一個，導致不一致，而且沒有人能說出為什麼選擇某個裁切方式。
- 安全區域總是被遺忘，直到貼文上線後，行動呼籲按鈕被埋在另一個按鈕下方才發現。
- 「直接裁切」被套用在裁切無法奏效的版位（例如寬版佈局被擠壓進 9:16），結果不是被切掉就是縮小到無法辨識。
- 文字大小是在主檔上判斷，而不是在版位實際顯示的尺寸下判斷。
- 檔案規則（格式、大小、編碼、幀率、音量）是透過上傳錯誤才發現的。
- 平台數據是從沒有日期和來源的舊部落格文章複製過來的。
何時使用
在以下情況使用它：
- 一個設計需要以多種尺寸或提供給多個平台；
- 有人要求「發佈組」、「社交媒體包」、「所有尺寸」、「橫幅套件」；
- 封面或縮圖在上傳後持續被切掉或變得模糊；
- 一個短影片也必須有直式、正方形和寬版版本；
- 你即將匯出一批檔案，並希望證明每個檔案都符合規格。
請勿用它來從無到有地創造設計（請先製作主檔）、編輯影片內容（剪輯、字幕、調色），或發佈內容。它可以告訴你某個版位需要新的佈局；新的佈局是設計任務。
你需要什麼
- 主檔：理想情況下是可編輯的原始檔（Figma/PSD/HTML/SVG/專案檔案）加上最大可用尺寸的平面匯出。僅使用像素對於僅需裁切的版位來說就足夠了。
- 目標版位清單，或目標（例如「在 X、Instagram 和我們的部落格上發佈」）。
- 對於影片版位：影片檔案，如果你想要自動檢查，則需要安裝
ffmpeg/ffprobe。 - Python 3.8+ 用於輔助腳本
scripts/matrix.py（僅使用標準函式庫）。
逐步指南
1. 評估主檔
在 master.json 中記錄（參見 examples/master.json）：
- 像素寬度與高度，以及它是靜態圖片還是影片；
- 是否存在可編輯的原始檔（這決定了重新排版的成本）；
- 可用的最大版本。切勿根據有人在聊天中貼出的縮小版本來規劃。
如果主檔比最大的版位還小，請立即說明；這將在後續顯示為 UPSCALE（放大）。
2. 撰寫版位清單，包含日期
建立 slots.json（從 examples/slots.json 開始）。每個版位一張卡：
| 欄位 | 意義 |
|---|---|
id | 匯出檔案的檔名主體，例如 video-thumb -> video-thumb.jpg |
w, h | 交付的像素大小；exact: false 表示「至少這麼大，相同比例」 |
safe | 平台 UI 覆蓋的頂、右、底、左內邊距（以版位像素為單位） |
drop | 不應在此版位出現的命名區塊（例如圖示上的標題） |
fit | wide（預設，保留盡可能多的上下文）或 tight（填滿安全區域） |
display_w | 版位實際顯示的寬度，以 CSS px 為單位，例如網格中的縮圖 |
min_text_px | 在 display_w 下仍可讀的最小大寫字母高度 |
formats, max_kb | 允許的檔案類型和大小上限 |
| 影片欄位 | video_codec, audio_codec, pix_fmt, fps 範圍, min_s/max_s, sample_rate, lufs (+lufs_tol), true_peak_max |
source | 數字來源 |
清單規則：
- 在頂部放置
as_of（今天的日期）。尺寸和疊加層會改變；沒有日期的版位卡就像謠言。 - 根據平台自己的當前幫助頁面或可下載模板檢查每張卡。
如果你無法驗證某個數字，請保留它，但寫下
"source": "unverified"並在交接時說明。 - 僅在目標不明確時詢問版位。一次問完的問題勝過五次：「我會製作連結卡、縮圖、正方形、9:16 限時動態和橫幅。要增減什麼嗎？」
3. 標記主檔
仍在 master.json 中，以主檔像素為單位列出區塊為 [x, y, w, h]：
keep：必須在每個未捨棄它的版位中都可見的內容（產品、臉部、主視覺）；text：每個文字區塊及其cap_px（主檔上大寫字母的高度）；logo：標誌；focus：當沒有其他標記時要對齊的點。
透過在設計工具中測量、從原始檔案讀取圖層邊界，或開啟圖片仔細估算來取得區塊。為每個區塊增加幾個百分點的內距；緊貼臉部的區塊實際上會切掉下巴。
4. 規劃每個版位
python3 scripts/matrix.py plan --master master.json --slots slots.json
你會得到每個版位的裁決結果：
- CROP：一個裁切 + 縮放可以將所有必要內容保留在安全區域內。該行包含裁切矩形和一個現成的
ffmpeg濾鏡（crop=w:h:x:y,scale=W:H）。 - UPSCALE：裁切可行但需要放大主檔。該行會說明所需的主檔尺寸。請索取更大的匯出版本或向量標誌，而不是交付模糊的圖片。
- REFLOW：沒有裁切方式可行，或者文字在顯示尺寸下變得無法閱讀。如果該行包含
art_only，則表示藝術作品仍然可以乾淨裁切，只有列出的文字/標誌需要為此形狀重新設定。否則，構圖本身必須改變。
在匯出任何東西之前，先向使用者顯示該表格。這是最容易改變主意的時機。
5. 解決每個 REFLOW
選擇最簡單的可行修復方式，按此順序：
- 重新設定文字：使用
art_only矩形裁切藝術作品，然後在版位安全區域內重新放置標題和標誌，文字大小需符合min_text_px。 - 重新堆疊：將寬版佈局（文字在左，藝術作品在右）變為直式佈局（藝術作品在上，文字在下），從可編輯原始檔開始，保持相同的字型、顏色和間距比例。
- 延伸畫布：在原始檔中加寬背景（或使用純品牌顏色），使藝術作品適合安全區域，而不是縮小藝術作品。
- 為小版位縮短內容：圖示和大頭貼只包含標記；兩欄網格中的 3:4 封面可能需要較短的標題。切勿自行重寫文案；提出較短的標題並讓擁有者批准。
每次更改後重新執行 plan，直到每個版位都是 CROP 或是一個故意且經說明的例外。
6. 匯出
- 僅裁切版位：套用規劃的濾鏡，對於靜態圖片或影片都一樣：
ffmpeg -i master.png -vf "crop=...,scale=..." link-card.png。 - REFLOW 版位：從可編輯原始檔以確切版位尺寸匯出。
- 將所有檔案命名為
<slot id>.<ext>並放在同一個資料夾中，以便檢查工具能找到它們。 - 靜態圖片：sRGB，如果平台會將透明度疊在未知顏色上則不要有透明度，逐步降低品質直到達到
max_kb。 - 影片：寬高皆為偶數、
yuv420p、來源的幀率（除非版位卡另有指定）、音量標準化至版位卡的目標值。對於大小限制，計算位元率：python3 scripts/matrix.py budget --seconds 58 --max-mb 50。 - 更多說明在
references/export-recipes.md。
7. 檢查每個檔案
python3 scripts/matrix.py check --slots slots.json --dir out/ --loudness
每個版位會回傳 PASS、FAIL、CHECK（某些項目無法測量）或 MISSING。 請自由修正機械性失敗（錯誤的尺寸、格式、大小、像素格式、取樣率）。 會改變內容的失敗（較短的時長、更緊的裁切、會提升背景噪音的較大音量）需要擁有者做決定：說明選項及其成本。
8. 以實際尺寸檢視
檢查工具無法看到。建立一份聯絡表，以 display_w 顯示每個版位，並標出安全區域，然後打開它：
python3 scripts/matrix.py sheet --slots slots.json --dir out/ # 寫出 out/contact-sheet.html
檢查項目： 文字是否越過安全線、臉部是否在關節處被切掉（下巴、頭頂、手）、標誌是否放在複雜背景上、兩個版位看起來是否像不同品牌。
9. 交接
交付該資料夾以及一份簡短說明：
Kit: Tidepool 發佈，版位 as_of 2026-10-24（2 個版位卡未驗證：note-cover、article-cover）
link-card.png 1200x630 184 KB PASS crop
video-thumb.jpg 1280x720 402 KB PASS reflow：標題重新設定為 96 px 大寫高度
story-vertical.png 1080x1920 1.1 MB PASS reflow：重新堆疊，畫布延伸
app-icon.png 1024x1024 61 KB PASS 來自向量標誌（點陣圖小了 1.6 倍）
vertical-video.mp4 1080x1920 21 MB PASS -14.2 LUFS, -1.3 dBTP, 30 fps, 41.0 s
檢視：contact-sheet.html（所有版位以顯示尺寸呈現）
範例
「讓這張發佈橫幅隨處可用。」
主檔 4000x2250，標題在左，手機模型在右。規劃：連結卡和儲存庫預覽為 CROP；
縮圖為 REFLOW（標題在網格尺寸下僅 13.5 px 高，需要 14 px）；正方形、直式和 3:4 為 REFLOW，帶 art_only 裁切（在手機下方重新設定標題）；9:16 為 REFLOW，不帶 art-only（模型對於安全欄位太寬，因此延伸畫布並重新堆疊）；應用程式圖示為 UPSCALE（使用向量標誌）。參見 examples/plan.output.md。
「YouTube 一直拒絕我的縮圖。」 一個版位。檢查顯示 2.4 MB 超出 2 MB 上限，且尺寸為 1280x721。重新匯出為 1280x720，JPEG 品質從 95 降至 88：1.3 MB，PASS。
「同一個短影片要給 Reels、Shorts 和 YouTube 寬版使用。」
三個影片版位。直式版位從 16:9 主檔 CROP 成功，僅因為講者置中；寬版就是主檔。檢查發現音訊為 44.1 kHz（WARN）和 -21.9 LUFS（FAIL，目標為 -14）；標準化、重新匯出、重新檢查。參見 examples/check.output.txt。
提示
- 只標記主檔一次，並將
master.json與設計檔一起保存；下次活動可以重複使用。 - 當兩個平台共用相同形狀時，如果它們的疊加層不同，仍然給它們獨立的版位卡。
- 如果一個匯出版本必須服務多個動態，為直式影片偏好使用一個保守的安全區塊。
- 一個在數字上通過但切到人物關節的裁切仍然是失敗的；請相信實際檢視步驟。
fit: tight適用於標記和圖示；其他所有內容應保留上下文（wide）。- 在說明中標明未經驗證的數字，而不是默默信任它們。
- 每次重新匯出後都要重新檢查，而不僅僅是你更改過的檔案：批次工具會覆蓋相鄰的檔案。