草圖轉擬真渲染

將建築繪圖——手繪草圖、立面圖、SketchUp 或 Revit 匯出檔案、彩色基地計畫、PDF 圖紙——轉換成看起來像是用全片幅 DSLR 拍攝的照片，且設計完全按照繪圖內容保留。Gemini 負責生成像素（gemini-3-pro-image，傳統的 generateContent）。你的工作是圍繞那個 API 呼叫的一切：讀取繪圖、撰寫提示、控管花費，並在交付任何內容之前，對每個結果與其來源進行核對。

scripts/render.py 負責執行細節，每次模型呼叫為一個回合：它會將來源影像邊緣延伸至模型提供的十種長寬比中最接近的一種（這樣就不會要求模型重新構圖），以該比例渲染，然後將來源本身的矩形區域裁切回來，標記任何重新構圖的情況，並寫入一個處理前/處理後的比對圖表。以下提到的路徑都是相對於此技能資料夾的路徑；請使用絕對路徑並使用 render.py check 所通過的 Python 來呼叫此腳本。

在何處執行

即時渲染需要在使用者自己的機器上執行 Claude Code，並在該機器中設定 GOOGLE_API_KEY。如果你沒有本機 Shell 或檔案系統——例如在 claude.ai 聊天、Claude API 技能容器中——請直接說明：你可以讀取繪圖、撰寫提示，並且如果 Python 和 Pillow 可用，可以顯示 --prompt-only 提示，但你無法進行渲染。絕對不要提議代為保管金鑰。

固定政策——直接引用，切勿改寫

使用者於 2026 年 8 月 28 日給定的渲染政策：

任務：先以 1K 品質渲染輸入影像以降低成本。

維持 100% 準確的幾何形狀、比例和長寬比。

無幻覺，除非明確指示，否則不添加/移除任何元素。

用真實的飾面替換材質（例如，陶土屋頂、逼真的樹木、泳池、景觀）。

輸出必須看起來像是高階 DSLR 建築攝影。

所有編輯和修改都應保持在 1K 品質，直到獲得確認。

一旦獲得批准，將同一張影像升級至 4K 品質：

提供清晰、細緻的準確度，無模糊或髒污。

放大檢視時，每個元素都必須看起來真實且擬真。

精確保留參考影像的幾何形狀和細節。

最終規則：始終先以 1K 渲染編輯內容，然後僅在獲得明確確認後才增強至 4K。

使用者於 2026 年 8 月 31 日給定的比對圖表需求：

在未來所有的渲染中，每次渲染後，我都需要比對圖表來進行交叉驗證。請更新到所有地方。

如果你要複述上述任一項，請直接引用。成本數字和背景資訊：請參閱 references/policy.md。

嚴格閘門

花費前先詢問。 在任何付費呼叫之前，告知使用者影像數量、級別和費用，並等待明確的「是」。之後才能加上 --spend-ok。腳本會強制執行此要求：如果沒有 --spend-ok，它只會印出預估費用並以退出碼 3 結束，而不會讀取金鑰。一個「是」只涵蓋你剛剛報價的內容；之後的每一次修改、修補或重新執行失敗的回合都是一次新的花費，因此請重新報價（一張影像，1K，最高 USD 0.268）並再次取得同意。你可以將計劃和價格放在同一則訊息中（例如：「下一步：修改視圖 02 以修正屋頂顏色——1 張影像，1K 品質，最高 USD 0.268。可以繼續嗎？」）。報價是基於影像費率；Google 還會對每次嘗試的輸入影像（約 USD 0.0011）、提示文字和模型的思考 token 收費，因此請說明實際費用會略高於報價。
4K 是針對單張影像，且需在批准後進行。 僅對使用者已在比對圖表上看到並指名批准的單張影像執行 upscale --confirmed。對一組影像說「看起來不錯」並不代表批准將整組影像升級至 4K，而「讓它更清晰」也不代表批准以 4K 重新渲染——請詢問是哪一張特定的影像。像其他花費一樣報價：檔案名稱、1 張影像、4K、最多 2 次嘗試、最高 USD 0.48（每次嘗試 USD 0.24）。
永遠不要在 4K 下疊代。 先在 1K 下修正所有問題；4K 的處理會如實重現所有缺陷。4K 檔案是最終版本，永不修改。
每次渲染都必須產出圖表，且你先進行審查。 每次渲染完成後，使用讀取工具打開圖表影像，並依照 references/review-checklist.md 進行審查。決定一個判決（相符 / 小幅差異 / 重大差異）並說明你看到的問題，然後將渲染結果、圖表以及圖表顯示的內容交給使用者。沒有圖表的渲染不算完成。
永不覆寫，也永不寫入此技能資料夾。 腳本絕不重複使用檔案名稱，並拒絕在技能資料夾內設定輸出資料夾；你自己也不要移動、重新命名或取代已交付的檔案或來源。
永遠不要在聊天中處理 API 金鑰。 不要要求、接受、列印或將其寫入檔案。如果使用者貼出了一個金鑰，請告知該金鑰現在已暴露在聊天記錄中，他們應該在 AI Studio 中刪除並重新建立一個，並說明如何將新金鑰設定為環境變數。偏好讓使用者使用環境變數，而非 .env 檔案，並且絕對不要將 .env 檔案放在會被複製、壓縮或上傳的技能資料夾中。
在每個專案中，於首次即時呼叫前，告知使用者繪圖內容將被發送到 Google 的 Gemini API（generativelanguage.googleapis.com）進行渲染。客戶的繪圖是機密的；需要獲得使用者的許可。
每次重試都會被收費，包括那些未回傳影像的嘗試。修正提示；永遠不要為了挽救一個糟糕的提示而提高 --attempts（腳本將其上限設為 3）。

此技能無法做到的事

此流程會保留繪圖本身的視角。它無法展示建築物的另一側、新的角度、變焦、裁切或不同的長寬比，也無法將平面圖轉換為透視圖或人眼高度視圖：在之前的案例中，將平面圖作為圖片發送，結果回傳了另一棟房子；而僅透過提示文字進行鏡頭移動，每次都會得到不同的別墅（請參閱 references/art-direction.md 第 13 節）。當使用者提出任何此類要求時，不要花費：解釋原因，並要求從 3D 模型匯出該視圖的新檔案，然後將該匯出檔案作為一個新任務進行渲染。絕對不要將鏡頭或構圖變更寫入 revise 或 patch 的備註中；如果你這麼做，腳本會列印 !! CAMERA / FRAMING WORDS。

此外，它也無法擦除標籤、對齊圖板、拼接陡峭的航拍圖或合成背景底圖，這些在之前的案例中都是圍繞渲染進行的周邊工作（請參閱 references/failure-modes.md）。在這些情況確實有效的地方，請在花費前警告使用者，僅靠提示文字可能不足以解決問題。

設定檢查（每台機器一次）

執行 python scripts/render.py check。它會印出 Python、Pillow 和 PyMuPDF 的版本、圖表字型、模型 ID，以及金鑰的找到位置（僅顯示來源，絕不顯示數值）；如果沒有找到金鑰，它會印出設定金鑰的步驟。如果某個匯入失敗，請使用該 Python 環境執行 python -m pip install -r scripts/requirements.txt。金鑰設定好後，check --online 會進行免費的 models.get 元資料呼叫，以證明金鑰和模型可以正常工作；這不會產生任何費用。

單一視圖的工作流程

1. 接收

從使用者處取得：磁碟上的檔案路徑（貼上的圖片沒有路徑——詢問檔案在哪裡）、一個視圖名稱，以及四個欄位的備註——材質、照明、環境、其他（皆為選填）。對於繪圖中未明確說明且會改變圖片樣貌的部分（例如，這塊平坦區域是草地還是鋪面？光線從哪個方向來？），主動提問，而不是自行猜測。對輸入進行分類：

一個包含多個圖板（樓層、立面）的圖紙，或是一個視圖不在第一頁的 PDF：請使用者匯出其中一個圖板或頁面，或者你自己在一個 ... Input 資料夾中將其裁切為一個新檔案，每個工作一個視圖。告知使用者，比對圖表會將該圖板與其渲染結果配對。密集的傢俱配置在之前案例的生成中失敗了；在花錢之前先說明這一點。
一個流程無法滿足的要求（見上文）：在花費之前先停止並解釋。
帶有標題欄、面積表、標籤或法定界線的圖紙：這些必須完全按照繪圖保留，並且模型無法保留文字（提示中禁止了這一點）。在渲染之前將它們裁切掉，並在最終圖紙上將其原封不動地放回渲染區域之外；在警告中指明任何法定界線，以免其被變成牆壁或被擦除。
一個與繪圖內容矛盾的請求（例如，圖上畫的是斜屋頂，但要求平屋頂）：指出矛盾並詢問。政策要求保持圖紙上的幾何形狀，除非使用者明確表示其他。

2. 讀取繪圖並撰寫提示

首先執行一個免費的 --prompt-only 回合，總是加上 --out（輸出到此技能資料夾之外；對於 assets/test_sketch.png，使用一個暫存資料夾）：它會將 PDF 的第一頁柵格化，並將填充後的輸入寫入 <out>/_work/prompt-only/<view>_<tier>_padded.jpg（最大 2400 像素），這是最容易檢視的檔案。使用讀取工具打開它並仔細研究。然後，依照 references/art-direction.md 編寫提示 JSON：

{"elements": ["兩層樓體塊，斜屋頂，位於畫面左半部", "..."],
 "finishes": ["暖色米白色石灰粉刷牆", "..."],
 "cautions": ["構圖：別墅寬度佔畫面 20-78%，屋簷位於高度 37%；如果它變大、重新置中或增加了天空，則表示結果失敗", "..."]}

elements：每個建築元素、開口、屋頂形式、樓層、欄杆、泳池、鋪面區域、植栽團塊和傢俱項目，包含其位置和數量（最多 30 項，每項 160 字元）。
finishes：真實的材質（最多 15 項，每項 120 字元）。
cautions：首先放入可測量的構圖錨點，並附上「結果失敗如果」的測試；然後是樓層數、非物體的製圖痕跡，以及針對此畫面的負面提示（最多 10 項，每項 160 字元）。

保持提示簡短——在之前案例中，過長的提示會導致構圖錯誤。將提示 JSON 儲存在工作旁邊，例如 <out>/_briefs/<view>.json。較長的材質或設定文字應放在 --materials / --environment 中（備註總字元數可達 4000）。

3. 選擇旗標

屋頂不是陶土材質（例如，平板、防水膜、石板、金屬、綠屋頂）？加上 --no-terracotta-example，在提示中放入一條關於屋頂的警告（例如，「所有屋頂都是平屋頂——無瓦片、無坡度、無陶土」，或「側翼屋頂是平板——無瓦片、無坡度」），並指明真實的屋頂飾面。共享的保真度提示使用陶土作為其範例飾面，並曾將紅瓦屋頂加到平屋頂的別墅上；這個旗標會移除那個正面範例。警告中仍可將陶土作為負面範例提及。
預設級別是 1K。僅在關鍵元素在 1K 解析度下可能小於約 20 像素時（例如在寬廣的莊園航拍圖中），才建議使用 --size 2K（相同牌價），並且僅在使用者同意後使用；4K 絕不是草稿級別。
輸入是經過處理的副本（已清除軸線、擦除標籤、預填白色空白區域）？將未經處理的原始匯出檔案作為 --original FILE 傳入，以便比對圖表能夠配對到真正的原始檔案。
當輸入位於一個 ... Input 資料夾中時，--out 預設為其同級的 03 Output 資料夾，否則為 <input folder>/03 Output；它絕對不能位於此技能資料夾內部。

4. 稽核提示（免費）

使用提示和備註重新執行 --prompt-only，閱讀列印出的提示，並檢查其中沒有任何要求繪圖中不存在的元素。

5. 估算、詢問、渲染

在不加任何閘門旗標的情況下執行命令以獲取估算值（退出碼 3），將報價提供給使用者，然後等待一個「是」。然後，加上 --spend-ok 再次執行。一次即時呼叫通常需要 20-60 秒，但一次嘗試可能等待長達 15 分鐘，比前台 Bash 呼叫更長：在背景執行即時任務（run_in_background）並等待它們。如果一個即時命令被中斷，請執行 render.py status，將被中斷的任務報告為可能已產生費用，並在重新執行之前進行詢問。多個視圖：報價批次總價（視圖數量 x 1K x 最多 2 次嘗試）並為整個批次取得一個「是」，然後一個接一個地執行這些視圖。

6. 審查圖表

使用讀取工具打開 <out>/_Before After - <view>_1K.jpg。遵循 references/review-checklist.md：構圖與比例、數量、開口、屋頂形式、樓層數、新增或遺失的物體、文字、材質、逼真度。一個橙色的「寬高比 a -> b（構圖已更改）」備註，或來自腳本的 WARNING 行，表示模型重新構圖了：該渲染結果無法被修改或批准，因此需要使用更強的構圖錨點重新從來源渲染，並在警告中指明失敗的回合具體做了什麼（例如，「PREVIOUS ATTEMPT FAILED: ...」）。如果一個視圖的兩個 1K 渲染都重新構圖了，請停止並報告，而不是繼續重試。當圖表太小而無法判斷某個細節時，請直接打開渲染結果本身來檢視。

7. 報告

提供給使用者：渲染結果路徑、圖表路徑、你的判決以及發現的問題、費用（render.py status 會顯示），以及可供選擇的後續動作——批准此影像升級至 4K、修改一件事、修補一個區域、或從來源重新渲染。

修改循環（保持在 1K）

revise "<current render>" --notes "<one change>"。規則：

每次修改只做一個變更。一次進行多個變更往往會導致整個畫面被重新生成。
描述物體的目標狀態，而不是修正動作（例如，「大門是實心暖青銅色木材，帶有兩個垂直拉手」，而不是「修復門」）。在撰寫備註前，先放大檢視渲染結果：改變顏色不是添加。
「before」是被修改的影像；圖表會將其與新檔案進行配對（BEFORE · <view>_1K / AFTER · <view>_1K_rev02）。
只有當前檔案（該工作中最新且非 4K 的回合）可以被修改；如果你選了其他檔案，腳本會顯示正確的檔案名稱。對 2K 渲染的修改將以 1K 進行，並命名為 _1K_revNN。
當構圖本身是錯誤的時候（鏡頭移動、主體變大、出現重新構圖警告），不要修改：使用更好的提示從來源再次執行 render。

修補（局部修正，保持在 1K）

patch "<current render>" --box x0,y0,x1,y1 --notes "<the change>"，其中方框座標以畫面比例表示（0,0 為左上角）。方框區域會被裁切出來，以全 1K 解析度編輯，然後縮放回去並貼回，在畫面內的邊緣帶有 36 像素的羽化效果；方框外的每個像素都保持位元組一致。用於修正一個物體或一個區域（例如，一個被憑空創造的牆壁、錯誤的植物、一扇門）。說明必須改變什麼，並且它必須清晰可見；不要告訴它要保留你正想要改變的東西。方框的每一邊至少要有 72 像素。

4K（一張已批准的影像）

當使用者…

[原文截斷，翻譯至此]

sketch-to-photoreal-render