Fullgrade
自動、溫和的影片色彩校正。一切都在本地以 ffmpeg + Python 執行，無需 GPU，無需雲端 API，幾乎不消耗 token（分析由腳本進行，而非逐幀檢查畫面）。
語言： 以使用者的語言回覆。如果使用者寫中文，則傳遞 --lang zh 讓報告和比對圖片以中文顯示；否則使用 --lang en。
1. 環境設定（首次執行或出現問題時）
python3 <skill_dir>/scripts/fullgrade.py --check
如果缺少任何項目，告訴使用者所需的一條指令：
| 缺少項目 | macOS | Windows | Linux |
|---|---|---|---|
| ffmpeg | brew install ffmpeg | winget install ffmpeg | sudo apt install ffmpeg |
| numpy / Pillow | python3 -m pip install numpy pillow （若 pip 拒絕，加上 --break-system-packages） | ||
| face-aware crop（選用） | python3 -m pip install opencv-python-headless |
在存放影片的機器上執行此腳本。如果檔案上傳到沙箱中，就在那裡執行並將輸出傳回。
在 Windows 上，如果找不到 python3，請改用 python。
選用：python3 <skill_dir>/scripts/fullgrade.py --selftest 會建立合成素材並檢查所有功能（約需 2-3 分鐘）。如果使用者問「在我的電腦上能用嗎？」，請執行此測試。
2. 將需求轉換為一條指令
python3 <skill_dir>/scripts/fullgrade.py <檔案或資料夾> [選項] --lang <en|zh>
| 使用者說… | 選項 |
|---|---|
| 未提及風格 / 「幫我調整就好」 / 自然 | --preset natural（預設） |
| 房產、室內、明亮通透 | --preset real-estate |
| 溫暖、溫馨、傍晚 | --preset warm |
| 鮮豔、食物、產品 | --preset vivid |
| 乾淨、清冷、現代、科技 | --preset cool-modern |
| 電影感、電影風格、vlog | --preset cinematic |
| 直式、TikTok、Reels、Shorts、抖音、小紅書 | --ratio 9:16 |
| YouTube、橫式 | --ratio 16:9 |
| 正方形 / Instagram 貼文 | --ratio 1:1 或 --ratio 4:5 |
| 填滿畫面，無黑邊 / 裁切 | --fit crop |
| 保留完整畫面 / 不要裁切，補邊 | --fit blur |
| 黑 / 白邊 | --fit color --pad-color black（或 white） |
| 空拍機 / DJI D-Log | --log dlog |
| Sony S-Log3 · Panasonic V-Log · iPhone Apple Log | --log slog3 · --log vlog · --log applelog |
| 讓所有片段對齊這個片段 / 圖片 | --match <檔案> （--match-method mkl 為預設；亦可選 reinhard、hist） |
| 讓所有片段彼此緊密對齊 | --match hero |
| 更輕柔的調整 / 不要過度 / 輕一點 | --strength 0.6 |
| 更快的輸出 | --fast（Apple / NVIDIA / Intel 硬體編碼器，自動降級） |
| 最佳品質 | --quality best |
| 包含子資料夾 | --recursive |
| 僅檢查，不輸出 | --analyze-only |
| 整個檔案使用同一組調色 | --no-split |
| 供 Premiere / DaVinci / Final Cut / CapCut 使用的 LUT 檔案 | 指向 <skill_dir>/luts/ （或使用 --export-luts <資料夾>） |
已針對多數使用者調整好的預設值：--fit auto（若保留 ≥60% 畫面則裁切，否則模糊背景 —— 因此 16:9 ↔ 9:16 預設使用模糊背景，除非使用者要求裁切）、--dynamic auto、--denoise auto。
除非使用者提及，否則不要詢問比例 —— 保留原始比例。僅在需求確實不明確時才提問（例如使用者說「LOG」但未指明是哪款相機）。
3. 處理流程（僅在有人問時簡短說明）
- iPhone HDR → SDR 自動轉換；當指定
--log時解碼 LOG（腳本會在片段看起來像 LOG 時發出警告）。 - 已完成剪輯會拆分為鏡頭（場景檢測）；每個鏡頭獨立調色。
- 每個鏡頭：白平衡 → 黑白階（保護亮部）→ 曝光調整至舒適範圍 → 對比度 → 飽和度 → 風格預設 → 選擇性對齊。所有調整整合為每個鏡頭一個 3D LUT，並設有安全限制，確保不會過度調整。
- 鏡頭內部的亮度漂移（例如從暗廳走到亮房）會被平滑處理（動態曝光）。大幅度調亮的鏡頭會套用輕度降噪。
- 重新構圖絕不拉伸畫面；智慧裁切會跟隨人臉（若已安裝 OpenCV）或細節最豐富的區域。
- 已經看起來正確的片段會直接複製，不重新編碼。
速度：處理時間約為 1080p 影片長度的 1-3 倍（4K 更久）。對於長片或多個檔案，告訴使用者正在執行並請其等待；不要取消。如果使用者趕時間，請使用 --fast。
結束代碼： 0 = 全部完成 · 2 = 部分檔案失敗（其他檔案正常 —— 輸出結尾會列出 Done: X OK, Y failed，報告會說明原因） · 1 = 無任何檔案可處理。務必告訴使用者哪些檔案失敗及其原因（常見原因：非影片檔案、檔案損壞、純音訊檔案）。
4. 輸出
- 影片：
<輸入資料夾>/_graded/<檔名>_<預設>[_9x16].mp4—— 絕不覆寫（若同名則加上_v2），原始檔案不受影響。 _graded/compare/*_compare.jpg—— 前後靜態比對圖。務必至少向使用者展示一張。_graded/fullgrade_report.html—— 每個鏡頭的前後滑動比對、數值與波形圖。提供給使用者。_graded/fullgrade_report.md—— 相同數值的文字版；閱讀此檔案以撰寫您的摘要。
5. 回覆
以使用者的語言提供簡短摘要：處理了多少部影片、使用哪個預設/比例、檔案位置、一兩句說明改變了什麼（根據報告，例如「鏡頭 2 原本非常黃，現在已校正為中性；窗戶的高光被保護」）、比對圖片、以及一個實用的下一步建議（另一個預設、9:16 版本、若希望調色更輕可調整 --strength）。
誠實的限制
- 完全過曝的白色窗戶/天空無法恢復；但其餘畫面仍會改善。
- 非常暗的素材在調亮後會出現噪點（輕度降噪有幫助，但非萬能）。
- 單一鏡頭中的混合光源（橘色燈光 + 藍色日光）會以折衷方式平衡。
- 兩個差異極大的鏡頭之間的交錯淡變可能在剪輯點出現微小變化。
- DJI D-Log M 及其他未列出的 LOG 曲線在 V1 中不支援 —— 請在不使用
--log的情況下調色，並搭配--strength。