Blender 漸層映射
工作流程修訂版 15。以使用者語言回覆。使用已連接的 Blender MCP 及受維護的 scripts/gm_core.py（版本 8 以上）；保留其映射演算法。
僅讀取此階段所需的內容
對於基礎映射，於每次可用上下文時讀取 references/base-api.md 和 references/reference-quality.md。請勿僅為了探索 API 而載入輔助原始碼或完整工作流程。若需檢查未記載的參數，請檢查目標函式的簽名或文件字串；僅在必要時讀取相關的原始碼函式。
references/workflow.md 是關於預設集、可選計劃鍵、QA 說明和歷史範例的延伸參考資料：請按需閱讀相關章節。SKILL_DIR 是此進入點的資料夾。請在基礎映射獲得批准後，才讀取 references/detail.md。除非上下文變更或壓縮後遺失，否則重複使用已在上下文中的文件。
範圍與安全機制
/tb-hoidz授權準備、規劃、區域、基礎映射、比較與 QA。在簡短的開場更新中結合一個簡潔的計劃與調色盤分配通知，然後繼續進行，無需中間確認；請遵守以下溝通規則。在完成基礎映射後停止，等待使用者批准細節映射後再繼續。 幾何體新增需要使用者選擇細節、切割方法和三角形成本；已存在的批准繼續有效。- 重複使用提供的概念與目標，若無歧義則使用選定的網格。僅對缺少的輸入提問。切勿發明概念、替換資產或預設情況下導入重複物件。
- 在運行開始時記錄
bpy.data.filepath作為工作儲存目標。編輯即時物件。變更檔案即開始新上下文；未儲存的檔案需要使用者指定首次儲存位置。 - 每個面都屬於一個區域；每個區域一條色帶，U 軸折疊至其中心，至少 2 像素的 U/V 邊距。預設情況下，結合頂光法線與高度，而非僅使用高度。使用適當的硬/平滑法線與材質響應。在基礎映射期間保留幾何形狀。
- 將計劃、私有成員資格/證據、基線三角形數、簽名、QA 與例外狀況儲存在場景本地。持久化 JSON、圖片匯出和基準報告為可選，非預設交付成果。
save_plan預設儲存至技能資料夾：請改用明確的可寫入儲存位置。
溝通與預覽
預設採用最少的聊天敘述：執行授權工作與內部檢查，然後報告完成結果。將計劃、預期的調色盤分配以及任何已知的後備方案結合成一個簡短的開場更新。工作期間，避免常規里程碑訊息、顏色表、QA 資料傾印和重複的預覽說明。僅根據更高優先級的執行時指示提供簡短的進度更新，或即時報告阻礙、需要使用者決策的事項或資料範圍的變更。
將完整的證據、候選方案與報告保留在場景本地；為決策返回精簡的工具摘要。當工具明確支援時，優先使用內部視覺檢查。如果工具自動在聊天中顯示圖片，請接受此限制，僅使用必要的截圖，並且不要將這些圖片再次嵌入到評論或最終回應中。切勿發明隱藏預覽模式或為了保持聊天安靜而跳過必要的視覺 QA。預設使用一個映射後的總覽；額外的截圖必須能解決不確定性或驗證有意義的修正。
以一份簡潔的報告作為結尾，內容包括已儲存檔案與髒狀態、QA 結果、材質限制以及待處理的細節。在既有的檢查點請求基礎映射批准。如果儲存或必要檢查失敗，請報告實際的不完整狀態。僅靠最少的敘述並不能節省速度或 token。
基礎映射
- 連線與準備。 呼叫
get_addon_status一次，並取得簡潔的場景事實：工作路徑、網格、世界邊界、面/三角形數與材質。批次處理獨立的讀取操作。在每個使用它們的 Blender 呼叫中，從此技能的絕對腳本目錄導入輔助工具。首次導入時，將該目錄置於sys.path最前面，從其他路徑移除 gm 模組，重新載入gm_core，並列印其驗證後的路徑/版本一次（參見 base-api.md）。後續呼叫導入時無需重新載入。執行ensure_palette；將後備方案、重新連結或材質建立包含在最終報告中，除非它需要使用者立即決定。在prepare_model(..., assign_material=True)之前更新團隊調色盤的技能副本需要先詢問。關於調色盤分配的開場更新應在呼叫之前完成，避免單獨的常規公告。 - 映射前識別材質。 在一個實務可行的初始發現批次中，為目標物件收集零件、邊界、原始 UV 群組和世界空間法線摘要。私下儲存成員資格與證據；僅總結與決策相關的部分。對於不明確或混合的零件以及具代表性的系列，專注於更深入的 PCA/深度/相鄰性檢查，然後重複使用已驗證的證據。對於未解決的邊界，允許進行額外的發現。結合幾何線索與概念圖位置；發現應在語義分配之前進行。在分配模糊的主要零件之前進行審計。一個薄邊界框可能描述一個寬板或一條對角繩索：檢查主體尺寸與表面範圍以及語義位置。形狀提示是證據，絕非材質標籤。在覆寫混合外殼的 UV 之前，執行
surface_groups(..., uv_seams=True)。驗證一個代表性零件及匹配的結構後，再為重複零件重用規則。在基礎映射期間解決面板/輪緣、空腔/表面以及包裹/桅杆的邊界。對每個零件或結構上已驗證的系列，完成 reference-quality.md 中的小型零件材質閘門；體積小不免除零件。不確定的分配需要在映射前進行有針對性的發現。 - 規劃與分配。 使用 reference-quality.md 進行測量或明確估計的概念圖顏色、材質與價值層級。使用
suggest_zone_colors批次執行全安全 V 搜尋；私下保留 2 到 3 個候選顏色與最終選定的顏色；僅輸出精簡的工具摘要以及需要決策的問題。根據驗證後的材質審計結果分配區域，並在映射前檢查未分配的面與不確定的邊界。切勿使用預設的通用材質來使覆蓋檢查通過；暫時的分配在檢查完成前應保持明確的不確定狀態。保留已驗證的成員資格。將缺失的徽章/木板列為未來的細節。 - 映射與比較。 套用計劃，然後執行
show_texture(light="FLAT")。在檢查顏色之前，驗證調色盤與預覽材質；避免一個初始的全粉紅色截圖。預映射圖片必須回答特定的幾何問題：使用已驗證的純色實體或臨時區域顏色。在映射後，檢查一個可比較的 512 到 640 像素總覽圖。對已審計的系列進行語義邊界審查，包括在總覽圖中隱藏或無法讀取的小型配件與介面。僅在必要時使用目標視圖。僅修正受影響的物件/區域，並檢查鄰近物件。可選的實際光照適配是為了解決具體的未解決不匹配問題，而非預設的整個資產檢查。另一個截圖必須能解決問題或驗證有意義的修正。 - 最終 QA 與儲存。 在最終 QA 之前，完成計劃中的顏色與邊界修正。在映射期間，使用精簡的覆蓋範圍、邊界與受影響區域檢查，而非整個資產的最終 QA。最後一次變更後，對每個目標執行一次
qa和qa_faces。由 QA 觸發的修復會使受影響的結果失效：對受影響的目標重新執行整個物件的輔助工具，並對共享相依性變更擴展到所有使用者；切勿使用過時的 QA 結果進行儲存。修復失敗；檢查並記錄有意的警告/例外。驗證覆蓋範圍、邊距、活動/渲染 UV、實際調色盤著色器連結、法線/光照以及未變更的基礎拓撲。分別記錄參考圖比較與材質閘門結果：資料 QA 並不能證明正確的材質分配或視覺相似性。當仍存在不確定的分配時，不要將基礎映射標記為完全驗證；明確記錄任何真實的參考/拓撲限制。最終確定臨時預覽，打包調色盤，保持紋理可見，並執行 base-api.md 中的防護儲存。報告儲存路徑/髒狀態、待處理的細節，並請求基礎映射批准。
快取與輸出紀律
- 在每個相依批次重用快取之前，執行一次
state_signature加上compare_state。缺失的簽名視為未驗證。幾何變更會使成員資格失效；UV 變更會使原始 UV 證據失效。共享的法線/調色盤/材質/變換/光照變更會擴大範圍。在接受編輯後刷新簽名。在一個未變更的批次中，不要在獨立的讀取操作之間重複執行簽名。 - 將完整的零件、面成員資格、調色盤資料、候選方案與 QA 保留在場景中。預設情況下，返回聚合計數加上最多 12 個與決策相關的零件列；僅為一個命名的未解決區域或使用者請求而展開。切勿列印完整的調色盤地圖/色帶目錄、候選清單、面/頂點目錄或場景快取。過濾掉
apply_plan中的空白區域；返回映射的面總數與已變更的色帶，而非原始輔助工具報告。最終 QA 輸出涵蓋每個目標，包含失敗/問題計數與可操作的警告；將詳細的通過報告私下保留。 - 輸出一個 MCP 結果表示：可用時使用
structuredContent，否則使用文字內容。分別傳送圖片區塊。不要將兩個重複的表示或圖片資料字串化。 - 批次處理獨立的讀取與相容的物件操作；將相依的檢查/編輯保持為順序執行。避免未變更的截圖、場景傾印和連線輪詢。無可比對量測數據的 token/時間節省主張。
執行效率
- 每個執行批次載入調色盤地圖一次。根據已驗證的面成員資格快取
part_evidence；不要為中心和大小分別重新計算 PCA。批次處理相容的讀取與修正，同時保持決策的可審查性。保留受維護的映射演算法。 - 在截圖之前，一併建立圖片/著色器有效性、著色、光照與構圖。從總覽圖中收集具體的不匹配，並在驗證前批次處理獨立的修正。對於局部編輯，保留並驗證範圍外的 UV/區域資料，並檢查相鄰邊界；對共享相依性擴展範圍。
- 在場景本地儲存輕量級的運行指標：目標/基線身份、階段秒數、實際工具呼叫/截圖次數與最終 QA 狀態。在現有的發現、映射/修正及 QA/儲存工作周圍使用
time.perf_counter()；在編排中計算實際的工具呼叫次數。不要為了量測而新增呼叫。標記不可用的指標，並區分 Blender 執行時間與端到端的耗用時間。僅在請求時，對相同的概念/模型/初始狀態進行基準測試，並同時比較品質與時間。不要將輸出位元組與 token 節省畫上等號。
儲存與復原
對於顏色/UV 編輯，使用工作階段的復原功能與 Blender 現有的備份策略；無需單獨的復原檔案。更新工作檔案是授權的，但檔案系統邊界仍然適用。解析允許的儲存路徑一次並重複使用。當允許時，優先使用已連接的 Blender 工具。如果需要提升權限，僅在 QA 之後針對具體的防護儲存提出請求。不要每次運行都重新探索伺服器原始碼或實作原始 TCP。經批准的後備方案必須使用已設定的 live host/port，絕不能使用猜測的 port 或繞過拒絕的路由。
在進行幾何編輯前，使用 copy=True 儲存一個復原副本到同級的 _backup/<working_stem>_gm_recovery.blend 中；僅重複使用這個技能擁有的槽位。僅針對該復原儲存，記錄 preferences.filepaths.save_version，暫時將其設為 0，並在 finally 中恢復。不要持久化偏好設定、更改工作儲存策略或移除使用者的備份。在切割前驗證授權與成功的復原儲存；如果失敗則停止幾何工作。
直接的 bpy 編輯可能導致 is_dirty=False：需要一個成功的明確儲存運算子，匹配最終的檔案路徑以及儲存後的髒狀態檢查。在失敗時保留回滾狀態。如果視覺截圖不可用，完成資料 QA，將視覺保真度標記為未驗證，並識別需要即時審查的區域。