Draw.io 圖表工程師
透過一個小巧、確定性的中間表示 (IR) 來建構圖表。將 IR 視為唯一事實來源，而 .drawio 則是編譯後的成品。
工作流程
-
首次使用或在環境故障後，請執行
doctor。閱讀 user-workflows.md 以了解能力狀態、起始範本選擇、套件內容及安全覆寫行為。在組合較不常用的指令或解譯退出碼時，請閱讀 cli.md。 對於舊版或版本化的圖表 IR，請閱讀 compatibility.md 並在編輯前執行migrate --check。 -
檢查請求及相關的原始素材。當使用者未指定時，推斷出合理的圖表類型、範圍、方向及主題。 對於協調式的架構圖套件，請閱讀 blueprint.md，依據 blueprint.schema.json 撰寫內容，並使用
blueprint。 對於 ERD，請閱讀 erd.md，依據 erd.schema.json 撰寫內容，並使用erd。如果 SQL DDL 是唯一事實來源，則直接接受它。 對於高可用性，請閱讀 ha.md，依據 ha.schema.json 撰寫內容，並使用ha。 -
編寫或調整最小的結構化來源。當沒有來源存在時，使用
init architecture、init blueprint、init erd或init ha。閱讀 ir-format.md 了解圖表 IR，以及 authoring.md 了解特定圖表類型的選擇。 當從 Python/TypeScript 樹、OpenAPI、SQL、Compose、Terraform、Kubernetes、GitHub Actions 或 GitLab CI 開始時，請閱讀 importers.md 並使用import產生 IR。 當自動連接器在視覺上仍然模糊不清，或存在固定的介面需求時，請在指定明確端口前閱讀 routing.md。 當需要組織樣式或更深入的視覺品質檢查時，請閱讀 style-system.md 並使用經過驗證的主題套件。 當匯入不受信任的內容或準備發佈套件時，請閱讀 security.md。切勿將憑證放在標籤、描述、連結、中繼資料或實體預設值中。 -
偏好單一指令的套件工作流程：
python3 <skill-dir>/scripts/drawio_tool.py build source.json \ -o build/diagram --name diagram --strict這會建立正規化的 IR、可編輯的
.drawio、所有 SVG 預覽、audit.json、security.json以及bundle.json。僅在使用者需要個別成品或增量工作流程時，才使用較低階的compile、validate、preview、security和audit指令。 -
如果 draw.io Desktop 可用且要求 Desktop 匯出，請閱讀 desktop-export.md，從套件的
.drawio檔案進行渲染，並保留其驗證報告：python3 <skill-dir>/scripts/drawio_tool.py render build/diagram/diagram.drawio \ -o diagram.png --report diagram.export.json -
視覺檢查每個捆綁的預覽項目。修正階層、文字被裁剪、重疊、不明確的邊線、對比度不足以及過多的細節。在呈現最佳結果前，最多重建兩次。
-
交付套件中的可編輯
.drawio、IR 來源、審計報告、預覽以及要求的匯出檔。當 Desktop 匯出被跳過時，請清楚說明。
在比較已核准的架構與新產生的模型時，請閱讀 drift.md，執行 diff，並交付機器可讀的報告以及可編輯的漂移檢視。
編輯現有圖表
保留使用者的成品。首先檢查並驗證它：
python3 <skill-dir>/scripts/drawio_tool.py inspect existing.drawio
python3 <skill-dir>/scripts/drawio_tool.py validate existing.drawio
在進行語義編輯前，還原可審查的圖表 IR：
python3 <skill-dir>/scripts/drawio_tool.py extract existing.drawio \
-o existing.diagram.json --report existing.extraction.json --strict
在依賴還原的模型之前，請閱讀 round-trip.md。lossless: true 表示所有語義單元都使用了支援的編譯器中繼資料。當 --strict 以退出碼 3 結束時，仍然可能寫入一個有效的盡力而為模型；在取代原始檔案之前，請審查每個推斷出的單元。
對於由 IR 支援的圖表，編寫語義操作並原子性地套用它們：
python3 <skill-dir>/scripts/drawio_tool.py patch diagram.json changes.json -o diagram.updated.json
在進行破壞性或多頁編輯之前，請閱讀 patching.md。如果提取報告指出存在不受支援的僅 XML 內容，則僅修改相符的 mxCell 值、樣式或幾何形狀，並保留原始內容，直到視覺審查通過為止。切勿為了整潔而重新編號穩定的 ID。
品質合約
要求在交付前滿足所有以下條件：
- 沒有懸空的邊線端點、重複的 ID、無效的父參照或節點重疊。
- 標籤適合其節點，並在正常縮放下保持可讀。
- 方向和分組傳達了預期的階層。
- 邊線標籤描述關係，而非實作細節。
- 顏色具有一致的含義，並且不是唯一的區分方式。
- 裝飾性細節不會壓倒主要的閱讀路徑。
使用 --strict 作為發佈的閘道。當檢查失敗或圖表需要手動視覺審查時，請閱讀 quality-gates.md。
編寫規則
- 使用穩定、語義化的 ID，例如
api-gateway，而不是序數 ID，例如node-7。 - 保持標籤簡短。將較長的上下文放在
description中。 - 使用明確的
group值來表示層級、信任區域、有限上下文或所有權。 - 對於請求/資料管線，偏好從左到右的配置；對於流程或階層，則偏好從上到下。
- 每個圖表保持一個主要概念。將大型系統拆分為多個頁面或層級，而不是縮小所有內容。
- 僅在使用者需要刻意放置時才使用
position；否則讓編譯器確定性地佈局節點。 - 不要猜測特定於供應商的 draw.io 模板名稱。在存在經過驗證的形狀映射之前，使用中性的語義種類。
工具行為
scripts/drawio_tool.py 對於 JSON 輸入僅使用標準函式庫。當安裝了 PyYAML 時，也支援 YAML 輸入。它提供：
doctor：驗證核心檔案和 Python/XML 支援，然後報告可選的 YAML 和 Desktop 能力。init：複製一個安全的起始範本，用於架構、藍圖、ERD、HA、路由、基礎設施或 CI。build：自動檢測模型或來源，並建立一個完整的、經過審計的drawio-diagram-bundle/v1。migrate：確定性地升級舊版/未版本化的圖表 IR，並輸出機器可讀的變更報告。compile：驗證 IR、計算確定性佈局，並輸出未壓縮的可編輯 draw.io XML。extract：從壓縮或未壓縮的 draw.io 檔案還原圖表 IR，保留編譯器支援的語義，並報告每個推斷出的舊版單元。blueprint：將一個架構模型投影到上下文、邏輯、資料、部署、安全和決策頁面。erd：驗證實體、欄位、鍵、類型和基數，然後從模型或 SQL DDL 產生可編輯的 Crow's Foot ERD。ha：驗證故障域、副本、複寫、健康檢查和容錯移轉，然後產生拓撲和容錯移轉頁面。import：將 Python/TypeScript 模組樹、OpenAPI、SQL DDL、Docker Compose、Terraform、Kubernetes、GitHub Actions 或 GitLab CI 轉換為圖表 IR。diff：語義性地比較圖表 IR，輸出結構化的漂移報告，並可選擇性地產生可編輯的、顏色和形狀編碼的漂移檢視。patch：原子性地套用語義節點、邊線、群組、位置和圖表變更。preview：無需 draw.io Desktop 即可建立可審查的 SVG。audit：檢查結構化來源和產生的幾何形狀，然後將發現結果分組，並附上修復建議和預覽路徑。security：掃描模型、.drawio或完整套件中是否存在憑證、不安全的連結、禁止的 XML 結構和解壓縮風險。validate：對 IR 或.drawio進行 lint 檢查，列印 0–100 的品質分數，並在--strict下失敗。inspect：總結頁面、節點、邊線、群組和畫布邊界。render：在 macOS、Windows 和 Linux 上發現 draw.io Desktop CLI，遵循DRAWIO_DESKTOP_BINARY或--binary，並匯出 PNG、SVG、PDF 或 JPG。verify-export：驗證原生匯出的格式簽章、結構終止符、尺寸和安全的 SVG 內容，無需啟動 Desktop。
在首次使用前，驗證 python3 -c "import xml.etree.ElementTree"。如果 macOS Homebrew Python 報告 pyexpat/libexpat 符號錯誤，請使用 /usr/bin/python3 或修復該 Python 安裝；不要將 ABI 故障歸因於圖表輸入。
使用 example.architecture.json、example.blueprint.json、example.erd.json、example.ha.json、example.routing.json、example.terraform.tf 或 example.kubernetes.json 作為簡潔的起點，而非固定的範本。當需要可重複使用的自訂主題範例時，請套用 corporate.json。