建立清晰的圖表
使用已安裝的 transmute CLI 作為確定性適配器。保留原始作者編寫的 .diagram.json 原始碼；將 .light.svg、.dark.svg、.light.png、.dark.png 與 .tldr 視為可取代的匯出內容。
嚴格遵循提示
將使用者的提示視為完整的內容規範。
- 保留所提供的標籤、數值、關係、相對大小與省略的內容。
- 僅新增繪製這些事實所需的中立機制。
- 不要自行發明標題、副標題、圖例、註解、範例、隱含意義、類別、度量、刻度、連接線或裝飾性宣稱。
- 不要將簡短的標籤擴充為句子。請優先使用使用者自己的一至三個字詞的標籤。
- 更新時，移除被拒絕的內容，但不要用新的闡述來取代它。
尋找原始檔
- 閱讀本機儲存庫的指示，並尋找
transmute.config.*。 - 在建立新的
.diagram.json之前，先搜尋現有、相同主題的.diagram.json。 - 更新該原始檔，而不是編輯產生的圖片或建立重複的檔案。
- 在具有
info/的知識庫中，使用info/diagrams/<slug>.diagram.json，並搭配info/notes/<slug>.md。在仍使用kb/的儲存庫中，請使用相同的相對路徑。根據主機的慣例嵌入或連結已渲染的淺色/深色圖片，並透過筆記（而非二元畫布）連結知識。 - 在知識庫之外，預設使用
diagrams/<slug>.diagram.json。
構圖
在建立或大幅重新設計圖表之前，請先閱讀 visual-communication.md。
深度套用這些預設值：
- 使用圓角矩形表示一般概念。相同角色的形狀應具有相同的大小、圓角半徑、筆畫粗細、圖示大小與標籤處理方式。
- 在相連的形狀之間至少保留 96px（最好 120–200px）的間距，讓箭頭看起來是關係而非接縫。
- 將圖示直接放在其語意形狀內部。不要將帶邊框的圖示磁磚放在另一個帶邊框的卡片內部。
- 當提示允許抽象化時，使用三到七個主要元素。
- 建立清晰的閱讀順序，並將同層級的元素對齊到共享的網格。
- 在邊框、顏色或文字之前使用空白來分隔群組。
- 最多僅為一個語意差異使用顏色。切勿進行任意的大小或樣式變更，從而暗示提示未提供的差異。
- 讓圖示扮演輔助角色：標籤仍須承載其意義。
- 每個物件偏好一個可見的邊界，每個軸或連接線偏好一個可見的筆畫。
不要為了滿足這些偏好而「改善」字面上的資料。提示的優先級最高。
讓確定性佈局掌管一般座標
對於一個水平或垂直序列，使用無座標的 stack 佈局：
{
"layout": {
"type": "stack",
"direction": "horizontal",
"gap": 160,
"align": "center"
}
}
- 陣列順序僅控制放置位置。僅在提示提供了該關係時才繪製邊緣。
- 將堆疊形狀保持為矩形或橢圓，並省略
x和y。 - 除非提示或發佈框架要求不同的間距，否則使用預設的 160px 間距。
- 對於有分支、非相鄰邊緣、圖表、自由文字、線條或故意不均等放置的情況，請切換到定位模式。不要將這些意義強塞進一維堆疊中。
- 如果堆疊無法容納，請明確增加畫布或減少原始尺寸。不要悄悄縮小形狀或間距。
撰寫與渲染
使用公開的綱要 URL 或執行 transmute diagram init 來取得起始檔案：
transmute diagram check diagrams/<slug>.diagram.json --strict
transmute diagram render diagrams/<slug>.diagram.json
渲染命令會覆蓋一致的相同主檔名匯出內容。當佈局或對比度不確定時，請檢查淺色和深色輸出。處理所有有用的 lint 發現；變更原始檔，然後重新渲染。
如果儲存庫使用自己的字型或圖示套件，請閱讀 customization.md。不要將 MonoLisa 或其他授權字型新增到儲存庫。預設渲染使用系統無襯線字型堆疊。
在託管圖片生成之前進行認證
當託管生成報告 AUTH_REQUIRED 時，使用 OAuth 瀏覽器流程：
transmute auth login
transmute auth status
回呼固定為 http://127.0.0.1:49671/oauth/callback。Token 僅應透過 Bun.secrets 存放在作業系統的憑證儲存區。切勿要求使用者貼上 token、將 token 複製到檔案、在工作輸出中列印 token，或繞過探索機制。在支援的 macOS 與 Linux 主機上，transmute auth logout 會在可能的情況下撤銷遠端憑證，並移除本機憑證。登入、重新整理與登出行為使用基於程序範圍綁定的協調機制；跨 Linux PID 命名空間共享其租賃目錄會以失敗告終，且不會刪除其他範圍的標記。在 Windows 上，憑證變更操作會以失敗告終，直到 Transmute 擁有等效的私有原生協調原始語。
嚴格產生一個託管 WebP
當使用者明確要求託管點陣圖生成時，保留其提示，而不是豐富它：
transmute image generate '<文字提示>' --output path/to/image.webp
預設模型是 recraft/recraft-v4.1-utility。僅在使用者要求 --model openai/gpt-image-1.5 或其行為對於請求結果至關重要時，才使用該模型。這些是唯一支援的 ID。
託管生成是一種經過認證、有上限的免費預覽。其 UTC 日帳戶限制為 10，全球每日安全限制為 100。目前尚未強制執行付費。向量化功能則分開管理，且保持本機、免費且免認證。
- 將必要的
.webp輸出路徑保留在使用者請求的工作區內。 - 讓 CLI 建立一個冪等性 UUID。僅當呼叫者已擁有穩定的 16–128 字元金鑰時，才提供
--idempotency-key。服務會在套件帳戶範圍內持久儲存該金鑰。 - 切勿重試失敗的生成呼叫：即使有持久的帳戶範圍冪等性，錯誤也可能具有歧義。
- 不要自己解碼、寫入或信任圖片。CLI 會限制規範的 base64、驗證 RIFF/WebP 媒體魔術數字，並以原子方式發佈它。
故意使用參考引導的 3D 與材質工作流程
當使用者要求將生成的或提供的圖片轉換為 Three.js 場景、低多邊形物件、透明 3D 循環或金屬 Logo 產品渲染時，請閱讀 reference-led-3d.md。
這些是完整的本機 Code Mode 主機功能，目前隨 Desktop 分發。公開的無頭 Bun 執行器可以生成圖片並執行其四個固定的可移植操作，但它不執行 HTML 覆蓋層、Three.js 或私有專案渲染器。Desktop Shell 提供原生擷取、權限和 UI，而不是另一個工作流程模型。切勿暗示其他情況。在本機 Code Mode 中：
- 將圖片到 Three.js 的工作階段安排為參考生成、原始檔編寫、審查、預覽，然後最終渲染。切勿將模型產生的 JavaScript 直接傳送給語意操作。
- 使用
createThreeReferenceScaffoldInput將確切的參考成品綁定到審查過的場景，即使它沒有被視覺合成。 - 使用
createMetallicLogoImageRequest進行參考引導的方形產品處理。保持模型選擇明確，並在接受結果之前檢查身份保真度。 - 首先以 1x 渲染全長預覽。僅在選擇了來源和處理方式後，才提高解析度或裝置縮放比例。
向量化點陣圖而不改變其意義
當使用者要求將呼叫者擁有的點陣圖藝術作品轉換為 SVG 時，將點陣圖保留為來源，並將 SVG 視為可取代的衍生作品：
transmute image vectorize path/to/input.png --output path/to/input.svg --json
- 向量化時不需要認證。轉換是本機進行的，不會聯絡探索、OAuth、生成或任何其他網路端點。
- 除了命令所測量的追蹤機制之外，不要重新繪製、重新標記、裁切、重新著色或簡化主體。
- 僅在使用者明確要求這種雙色調適時，才使用
--duotone '#主要,#次要'。 - 當可稽核性很重要時，將輸出的收據保留在工作輸出或相鄰的來源記錄中。
- 不要繞過輸入、解碼像素、持續時間、路徑、位元組或保真度閘門。
- 在其預期大小下檢查 SVG。成功的追蹤並不能證明不熟悉的符號能傳達預期的概念。
VTracer 在首次使用時從其校驗和固定的官方版本下載。TRANSMUTE_VTRACER_PATH 僅用於相容的本機 0.6.4 二進位檔案；Transmute 仍會記錄其雜湊值。切勿新增放大模型、內嵌點陣圖後備方案或商業字型來使追蹤通過。
有界向量化目前僅在 macOS 和 Linux 上支援。在 Windows 上，回報故意的 tool_platform 錯誤；不要使用無界的暫存輸出檔案來繞過它。
狹義使用已連接的工具伺服器
當 Transmute MCP 已連接時，保留專用的 check_diagram 和 render_diagram 工具用於簡單的相容性呼叫。使用 search_transmute 來探索固定的語意註冊表，並使用 execute_transmute 搭配一個確切的傳回碼和型別化的 JSON。繼續直接編輯已檢查的圖表原始檔；沒有工具會建立或重寫原始檔。
- 僅傳遞相對於根目錄的
.diagram.json路徑。 - 將
check_diagram視為唯讀。 - 將
render_diagram視為允許取代五個已記錄的生成成品，但絕不取代原始檔。 - 對於超過 64 個形狀或 128 條邊的原始檔，請使用 CLI 而非 MCP。MCP 最多傳回 40 個發現，並在該列表被截斷時報告。
- MCP 模式故意使用內建主題和圖示，且永遠不會執行工作區配置。當需要可信賴的本機配置時，請在 MCP 之外使用 CLI。
transmute.image.vectorize接受相對於根目錄的輸入/輸出路徑，無需登入，並將點陣圖位元組保留在本機。transmute.image.generate需要相對於根目錄的.webp輸出路徑，以原子方式寫入有界圖片，並僅傳回經過編輯的檔案/請求中繼資料。僅使用兩個註冊表模型 ID，且不要重試。- 切勿將原始碼、Shell 文字、動態匯入文字、遠端 URL 或未註冊的操作名稱傳遞給語意執行。
如果沒有 MCP，等效的機器可讀 CLI 介面是：
transmute code search '<詞彙>' --limit 4
transmute code execute <精確操作代碼> --input '<嚴格 JSON 物件>'
故意使用 tldraw
生成的 .tldr 檔案是可編輯的交換格式，不需要 tldraw SDK 或桌面應用程式即可建立。當有人想要直接編輯畫布時，在 tldraw Offline 中開啟它：
transmute canvas open diagrams/<slug>.tldr
如果可選的應用程式不存在，transmute canvas install 會解析目前的官方版本，驗證其已發佈的 SHA-256 摘要，並啟動平台安裝程式。該應用程式會將 .tldr 匯入為未儲存的文件；在那裡儲存它會建立其較新的原生 .tldraw 套件。切勿直接重寫原生的 .tldraw ZIP/SQLite 套件。
驗證
- 執行
transmute diagram check <原始檔> --strict。 - 執行
transmute diagram render <原始檔>。 - 確認所有五個成品都存在於原始檔旁邊或請求的輸出目錄中。
- 以實際大小檢查淺色和深色輸出。
- 確認同層級形狀不會暗示虛假的差異。
- 確認連接線夠長、已綁定到
.tldr中預期的形狀，且不會越過標籤。 - 如果需要伴隨的筆記，請確認其路徑和視覺參考。