照片細節編輯 (Photo Detail Edit)
使用者提供原始圖片與編輯提示。此技能完成完整流程：追加保真約束 → 內建圖片編輯 → 縮圖結構匹配 → 學習局部 RGB 轉換 → 應用於原始尺寸圖片 → 輸出成片與局部比對。請勿僅完成生成或提供操作建議。
輸入與邊界
- 需要能夠讀取的原始圖片檔案。請先檢查檔案的像素、位元組數、EXIF 方向與透明度；視覺預覽可能被縮小，不能作為「原始大圖」。若只有對話預覽且無法取得原始檔案，請要求使用者提供原始檔案或包含原始圖片的 ZIP。請不要從已遺失的細節中聲稱恢復了真實資訊。
- 使用者只需提供圖片與提示；由 agent 判斷保留區域、製作分割提示並檢查遮罩，不要求使用者先手動繪製遮罩。
- 保留使用者明確要求的改動。背景替換、去背、換裝、刪除飾物等對應區域不得被後續恢復步驟改回；對於明確改變的物體或結構，需建立排除區域。
- 此流程面向攝影修圖。大幅改變姿勢、人物身份或整體重繪可能無法可靠對應，必須如實保留生成結果並說明恢復有限。
工作流程
1. 建立本次任務目錄
在目前工作區建立新的輸出目錄，保留原始圖片，不覆蓋原始檔案或既有成片。儲存使用者的原始提示、實際發送的完整提示與生成的底圖。附件 ZIP 解壓縮時需核驗路徑，不覆蓋已有檔案。
若依賴套件未安裝，在目前專案的虛擬環境中安裝 scripts/requirements.txt；優先複用既有相容環境，或使用 uv venv / uv pip install --python ... -r ...。無需系統級安裝。腳本執行時不聯網、不下載模型。
2. GPT Image 編輯
- 先透過
view_image檢視原始本地檔案。呼叫本次對話可用的內建image_gen編輯工具，以原始檔案為編輯輸入，不要以前一輪生成的圖片取代原始圖。 - 實際 prompt = 使用者原文 + 固定保真約束。固定部分作為追加約束，不替換、不稀釋使用者目標；全身構圖要求僅適用於原本就是全身構圖的照片。儲存這個準確的拼接結果。
- 去背景/去背/透明背景請求需設定
transparent_background: true；替換為新背景則為 false。其他參數遵循目前工具能力，不虛構品質、尺寸或模型版本參數，不承諾 prompt 能保證像素或解析度保真。 - 將生成檔案複製到本次任務目錄。記錄真實輸出尺寸與大小。預設僅生成一次；僅在工具失敗或明顯遺漏使用者主要要求時修正並重試一次，避免無止盡地重新生成。不要擅自切換到付費 API/CLI。
3. 為本次圖片建立保留區域
檢視原始圖片與生成圖片。按照 區域配置與執行說明 建立本次的 regions.json，分別指定原始圖片與生成圖片的主體遮罩或 GrabCut 種子；座標從目前圖片判斷，不複製上次的人物座標。腳本會將配置座標依據各自圖片的 EXIF 顯示方向來解釋。
遮罩應覆蓋需要保真的共同主體，排除背景與使用者有意改動的部位。透明前景可利用 alpha，但仍須排除使用者有意重繪的區域。fill_holes 預設為關閉，物體把手、姿態形成的空隙可能是真實背景，不能盲目填洞。
至少選擇兩個人物/物體細節位置作為局部對照；若照片中有臉部、印花、毛呢/織物，優先選擇這些位置。配置來自 agent 的視覺判斷，不是固定模板。
4. 分析、檢查，再融合
使用同一組參數，先 --stage analyze，再 --stage fuse：
<python> <skill>/scripts/restore_detail.py --source <original> --base <generated> --regions <regions.json> --out <job>/restored --stage analyze
預設 --method local-rgb --structure-channel auto。分析階段會將原始圖片縮放到共同尺寸，驗證幾何對應，降低顏色、對比度與細紋理對結構判斷的影響，在可靠區域擬合受約束、保持單調的局部 RGB 顏色曲線。一般多色照片使用亮度結構；強單色光則自動選擇對應通道，兩張圖片使用相同表示，不固定紅通道。
檢查 base-mask.png、source-mask.png、confidence-overlay.png 與 report.json，確認實際方法為 local-rgb，結構通道與匹配範圍合理。背景不得被選進恢復區域；若遮罩明顯錯誤，修正區域配置後重新分析。不要透過放寬匹配閾值來強行提高覆蓋率。
<python> <skill>/scripts/restore_detail.py --source <original> --base <generated> --regions <regions.json> --out <job>/restored --stage fuse
腳本會將局部曲線參數平滑上取樣，應用於對位後的原始尺寸圖片，讓真實細節經過目標色調與光影的轉換。映射不可靠的位置則沿用放大的生成圖；背景、透明度與明確排除的編輯區域保持一致。在缺乏足夠共享特徵時不傳入原始圖片內容。主體色調與光影是擬合結果，不能承諾逐像素一致，也不能將原始圖片尺寸稱為完整恢復原始圖片畫質。
不預設疊加 Lab 灰階高頻，也不預設使用自由度過高的任意矩陣或完整 3D LUT。--method lab-detail 僅保留用於使用者明確要求的舊方案比較；請勿靜默回退至舊方法。
5. 檢查並交付
- 檢查最終預覽與至少兩個原始像素尺度的局部對照，分別核對真實紋理、顏色與大範圍光影，留意重影、黑塊、暗部發灰、邊緣與接地陰影。請不要僅憑紋理相關度或匹配覆蓋率來宣告畫質改善。必要時收緊排除區域，再執行一次分析與融合。
- 確認
report.json中背景範圍像素變動為 0、alpha 保留、PNG 可讀取。精確背景一致性針對無損 PNG，JPEG 壓縮可能改變像素。 - 返回可見預覽、完整尺寸無損 PNG 與局部對照連結。無透明度時另交付 JPEG；透明圖請勿透過 JPEG 交付。
- 簡述輸出尺寸、實際恢復範圍與明顯限制；提供實際完整 prompt 的檔案連結。請不要把插值放大的像素數量當成新增的真實細節。
呼叫範例
使用
$photo-detail-edit處理這張原始圖片：淨化背景與光影，使其具有雜誌攝影棚的質感。
使用
$photo-detail-edit去掉背景，輸出透明 PNG，保留人物與衣物細節。