Drawio 視覺技能

建立、重建和編輯原生、使用者可編輯的 Draw.io 檔案，無需伺服器、MCP、固定模板、Scene IR 或自訂渲染器。

預設使用物件，而非文字模組

對於一個新的說明流程——流程、管道、泳道、請求生命週期或架構流程——預設使用可辨識的可編輯物件和可見的變更。諸如「繪製工作流程」這類簡單請求即會啟動此規則；使用者無需特別要求「圖形化」、「具體」或「插圖式」圖形。請將圖表類型與此視覺處理方式分開選擇。

在放置節點之前，請識別哪些會移動、哪些會改變，以及誰會採取行動。然後為每個主要業務物件和處理階段選擇一個輪廓、有意義的內容或一個小型物件場景：佇列有獨立的任務卡片和輸入/輸出端；解析器顯示文件變成提取的部分；退款區分待處理與已退還資金。首先繪製這些原生部分，然後加上簡短的名稱/動作。即使標籤簡短且版面整潔，一串包含步驟名稱的矩形也無法滿足此預設要求。重複的伺服器機架、表情符號或散文卡片上不相關的圖示，都不能替代可見的意義。在創作這些流程之前，請先閱讀 visual-storytelling.md。

從捆綁的圖形開始： 查閱 component index，閱讀 assets/components/ 下相關的 .drawio XML，並選擇是重複使用其原生後代、改編/組合其零件，還是將其構造作為生成新原生物件的參考。根據任務需求組合瀏覽器、文件、訊息、佇列、工作者、儲存、區塊、表格、向量、審查、決策和通知物件。例如，組合瀏覽器 + 文件 → 儲存，然後單獨的訊息 → 佇列 → 工作者；不要僅將這些名稱寫入矩形內。這 12 個起點是一個可擴展的種子庫，而不是完整的模板或能力限制；在生成附加物件時，借用相關的構造理念，例如輪廓、有意義的內容、狀態標記、嵌套和連接埠，然後將其適應到領域中。不要強加起點的樣本調色板或強制進行完全複製。

內建元件語言： 在 assets/components/ 下新增、生成或維護可重複使用的資產時，請保持所有標題、欄位名稱、說明性文字值、狀態、頁面名稱和工具提示為英文。數字、公式和符號可以保持原樣。這是一條庫創作規則：為使用者生成的圖表仍遵循其請求/來源語言，起始文字會相應調整。

例外情況遵循任務，而非便利性： 保留忠實的重建、局部編輯的範圍、明確的純文字/最小方塊請求，以及所需的正式符號。類別/實體分隔區、序列生命線、決策/分支/合併符號和狀態邊界具有實際語義；請保留它們。對於「流程圖」的通用請求、「簡單」圖表、缺少起點，或 Mermaid 的可用性，這些並不構成例外。在相容的情況下，使用可見的物件變化來解釋狀態；不要用圖片取代正式的關係。這些預設值適用於每個頁面，並且在方向/類型變更後仍然有效。

核心規則

將當前的 .drawio 檔案視為內部的可編輯事實來源。預設僅提供每頁的 PNG 圖像和一個 HTML 預覽；將原生檔案保存在內部的臨時工作目錄中，交付目錄之外，並且不要在交接中連結它們。僅在明確要求時才交付原生檔案、SVG、PDF 或其他格式。
絕不覆蓋輸入。每次機械寫入都必須使用新的輸出路徑，包括內部工作檔案。
不要強加主題、形狀列表、圖表類型、座標網格或佈局配方。
遵循使用者指定的圖表類型、符號和方向。當這些未指定時，選擇最能回答任務實際問題的呈現方式，包括 UML 和非 UML 形式；不要將每個請求都預設為流程圖或泳道。在選擇或大幅變更呈現方式時，請使用 diagram-selection.md。
將上述的物件優先預設應用於新的說明流程；標準的控制符號和可重複使用的元件起點支援此功能，而不會強加固定的圖標目錄。
對於垂直流程圖，將主要路徑從上到下運行，將平行分支並排放置，標記決策菱形的出口，並將支援性檢查分組在淺灰色虛線框中，帶有通俗易懂的目的說明。
當中央引擎協調外部模組時，將核心放在中心，將輸入和工作人員分組在兩側，並使用帶有動作標籤的編號箭頭來引導讀者完成一個任務。在相關情況下，將回饋路由到核心上方，將人類決策和通知通道置於其下方，並在底部顯示一個範例工作流程。選擇適合主題的顏色。
保持任意的原生 Draw.io 形狀、模板、樣式、幾何、路徑點、圖層、群組和包裝中繼資料。
偏好較大的畫布或容器，而不是壓縮的節點、標籤或路由通道。無衝突的檔案不一定寬敞、易於閱讀或佈局良好。
在放置相鄰節點之前，先預留連接器標籤的空間。長標籤必須能夠在連接的形狀之間放置，並有可見的間隙，或使用明確的換行/其他清晰的標籤位置。在將圖表標記為準備就緒之前，解決端點標籤的風險並檢查實際渲染的文字邊界；請參閱 connector-label clearance。
對於新創作或大幅重新設計的內容，預設在定向的語義流程邊上設定原生 flowAnimation=1，包括正常、次要、資料、異常和重試流程。保持參考、註釋、包含、分組和純結構性關係靜態。讓明確的使用者意圖覆蓋此策略。
在局部編輯期間保留不相關的動畫樣式，除非要求動畫標準化。如果動畫模糊了層次結構，請在渲染的品質保證期間將優先級較低的語義流程設為靜態，而不是改變其拓撲。
將連接器動畫視為視覺效果，絕非路由或衝突避免。
僅將捆綁的 CLI 用於檢查、查詢、修補、驗證、佈局/拓撲檢查、Desktop/Web 匯出編排、配套 HTML、頁面 CRUD、版本列出、發布和還原。它不負責創作、佈局或實現渲染器；render 委派給 Draw.io Desktop，web-svg-bridge 將一個選定的頁面委派給官方的 Draw.io Web，而預覽 HTML 則委派給官方的遠端檢視器。
將 <base>-vNNN 視為由圖像和 HTML 共享的邏輯交付版本，而不是每次內部寫入。除非要求來源交付，否則原生版本控制保持內部。預設情況下，一個使用者批准的更改最多消耗一個新的同級版本。
保持每個公開 CLI 的 --page-index 從零開始，與 inspect 返回的 index 匹配。對於多頁工作，偏好穩定的頁面 ID。
將每個文件限制為 15 頁。CLI 會拒絕超過此限制的現有文件和新增內容，並返回 PAGE_COUNT_LIMIT；切勿截斷頁面以滿足此限制。
不要將此技能與官方的 drawio@drawio 技能一同啟用；此技能已包含相同的原生 Mermaid/XML 創作路徑。

選擇呈現方式

將圖表類型與創作工具分開。根據讀者需要理解的內容來選擇：進展、職責、互動、狀態、結構、部署、資料移動或比較。提供的圖表、明確格式或要求的局部編輯會限制該選擇。當使用者未指定時，自主做出選擇，在有用時簡要說明，然後繼續進行；不要讓使用者從目錄中選擇。閱讀 diagram-selection.md 以了解問題到形式的指南和權衡取捨。

在所有頁面和修訂版本中套用預設的視覺處理方式或任務的明確例外。不要添加純文字的配套頁面作為基於物件說明的替代。

然後選擇適合該呈現方式的物件和符號。具體的插圖可以解釋有效負載和轉換，而正式的 UML、ER 和其他既定符號則應保留其語義慣例。不要將每個標記的類別、狀態或架構框都視為文字密集型流程的缺陷。

選擇工作流程

請求	工作流程
解釋流程、管道、泳道、生命週期或架構流程	證據/所有權 → 視覺敘事 → 物件/狀態構造 → 直接原生 XML → 官方渲染器 QA
建立正式的結構圖或明確的最小方塊圖	保留符號/內容 → 如果它能保留預期的表示且 Desktop 可用，則使用 Mermaid；否則使用原生 XML
使用自訂形狀/樣式/位置建立	直接原生 XML → `.drawio`
從 PDF 或文字建立	讀取來源 → 提取支援的結構 → 使用相同預設選擇表示 → 原生 XML 或合適的 Mermaid
從圖像重建	以原始解析度檢查 → 可編輯的原生細胞 → 可選的預覽比較
檢查視覺衝突	`check-layout` → Desktop `render` → 檢查圖像 → 小修補 → 重新渲染；備用為 Viewer HTML
檢查業務流程	`check-topology`，使用已知的起點、終點和必需的邊
在沒有 Desktop 的情況下檢視	`preview` → 配套的 `.html`，使用官方的遠端檢視器顯示可見的頁面計數/名稱
在沒有 Desktop 的情況下匯出 SVG	偏好一個 `web_svg_session.py` 回送會話；保留 `web-svg-bridge → commit-web-svg` 以進行手動恢復
匯出或套用請求的佈局	先建立 `.drawio` → Draw.io Desktop CLI
編輯，目標未知	`inspect → query → patch`
編輯，頁面和細胞 ID 已知	`query → patch`
編輯，新的可信 CLI 結果已包含修訂版和目標	`patch`
新增、重新命名或刪除頁面	`inspect → page add/rename/delete`
列出或還原檔案版本	`versions` 或 `versions → inspect old → restore`
發布完成的運作中檔案	`inspect working → publish`
檢視一個或多個已知細胞	`query`
獨立檢查檔案	`validate`

創建、預覽、Desktop 偵測、佈局和匯出，請閱讀 references/authoring.md。僅當 Desktop 不可用且明確要求的 SVG 必須透過官方 Draw.io Web 匯出時，才閱讀 references/web-svg-export.md。在創作擁擠的圖表、維護跨頁面視覺一致性、解讀 check-layout，或執行渲染視覺 QA 時，請閱讀 references/layout-authoring.md。當流程、生命週期或請求路徑必須連接時，請閱讀 references/topology.md。當來源是 PDF、文字或圖像時，請閱讀 references/source-to-diagram.md。僅在直接 XML 創作時閱讀 references/drawio-xml.md。在構建修補程式之前，請閱讀 references/patch-contract.md。有關頁面命令和不可變歷史記錄，請閱讀 references/versioning.md。

規劃邏輯交付

在寫入之前，將每個請求的變更映射到其頁面/細胞、所需的決策出口、關鍵的起點/終點/邊約束、副作用或錯誤路徑、術語，以及所有受影響的頁面。
對於新的多頁文件，在創作之前定義文件內部的視覺角色，並在頁面之間重複使用頁面基礎、排版、重複的元件樣式和關係樣式。在新增或編輯內容時，在請求的範圍內繼承現有文件的慣例。有關角色選擇、有意的例外和跨頁面驗收，請遵循 document visual consistency。
對於一個不需要後續拓撲、佈局或視覺修正的原子編輯，直接寫入一個新的內部原生版本。
對於多頁編輯或任何可能需要 QA 修正的任務，建立一個 Agent 擁有的臨時目錄，並依序寫入 working-01.drawio、working-02.drawio 等。在其中完成所有請求的編輯和檢查；publish 對於內部的最終快照或明確要求的原生交付是可選的。
從相同最終檢查過的原生快照生成交付 HTML 和每頁 PNG；不需要發布的 .drawio 交付物。對於使用者面對的 HTML，使用 preview --fallback-png（按頁面順序重複）嵌入每個頁面的經過驗證的渲染。在遠端檢視器被阻止的情況下檢查交付的 HTML，包括在窄寬度下。僅成功的線上渲染並不能驗證接收者的預覽。如果沒有官方渲染可用，請將 HTML 標記為僅限線上的，並揭露此限制。臨時預覽是 QA 工件，而非交付物。
在驗證了自包含的圖像和 HTML 之後，僅刪除由這個任務建立的、可丟棄的 QA 檔案；保留最終的原生快照在內部以供後續編輯。未經明確的使用者授權，絕不清理現有的正式版本。

建立

閱讀 references/authoring.md，並在選擇語法之前選擇表示方式。對於新的說明流程，使用物件優先預設和直接原生 XML；Desktop 的可用性會改變匯出，而不是視覺要求。僅在 Mermaid 能夠保留所選的語義/表示時（例如正式的結構圖或明確的最小方塊圖）才使用它。偵測 Desktop 以進行轉換/匯出。
選擇一個描述性的小寫連字號基礎名稱，為初始的圖像/HTML 交付保留 <base>-v001，並將其 .drawio 快照保留在內部。

drawio-visuals-skill