Mirofy

Mirofy 是做什麼的？

從一個小型、型別化的 JSON 規範建立一個自我包含、互動式的 HTML 圖表。靜態輸出是預設值；只有當使用者要求示範或簡報時，才啟用動畫。

掃描優先：從真實的儲存庫推導圖表

當圖表必須描述現有的程式碼時，不要憑記憶撰寫。請推導它：

npm run scan      # 儲存庫 -> 證據圖譜（事實與缺口）
npm run model     # 證據 + 文件 -> 一個系統模型
npm run compile   # 模型 -> 一個具有意圖的有限視圖

每個步驟都會報告它無法確定的內容。scan 會記錄每個無法分析的檔案的缺口，compile 會記錄它省略的每個物件及其原因。將這些資訊傳遞給使用者；一個默默地省略半個系統的圖表，比一個說明遺漏了什麼的圖表更糟糕。

當使用者正在描述尚不存在的內容，或沒有可用的儲存庫時，請使用下面的快速路徑。

快速創作路徑

使用這個有限的路徑進行一般生成。除非使用者詢問這些功能，否則請不要閱讀選用的檢視器執行時期參考文件。

1. 從問題中選擇 architecture、workflow、sequence、dataflow 或 lifecycle。

2. 讀取 schemas/ 中一個相符的 schema、schemas/common.schema.json，以及 examples/ 中一個相符的 JSON 範例。僅讀取這些檔案。全新的創作意味著新的穩定 ID、領域用語和版面配置；使用範例來了解欄位形狀，而不是事實。當真實的產品身分很重要時，請執行 node bin/mirofy.mjs brands "<name>" --json；只有在品牌未知且使用者提供了 URL 時，才讀取 references/brand-marks.md。

3. 先產出成品：下一個工具動作必須撰寫候選檔案。在檢查轉譯器內部之前，先撰寫候選檔案。不要用散文規劃確切的座標。從一條清晰的主要路徑、簡短的側分支、稀疏的標籤以及最多 12 個主要節點開始。將 meta.quality_profile 設定為 "showcase"，除非使用者明確要求密集的 standard 地圖。從自動路由和標籤開始。在診斷要求之前，不要添加 via、channelX、channelY 或 labelAt；每次修復最多應用一個經診斷的幾何控制。

4. 在每次編輯候選檔案後以及交件前立即進行驗證：

   node bin/mirofy.mjs validate <type> <candidate.json> --quality showcase --json
   

   只有 4 項成品檢查的收據是基本驗證，絕非 showcase 驗收。showcase 通過必須報告所有 9 項成品檢查，且無組成錯誤和警告。如果候選檔案省略或拼錯確切的 meta.quality_profile 欄位，請在處理幾何之前修正。通過最終驗證即凍結候選檔案：之後絕不可編輯。

5. 對於已交付的 HTML，deliver 是最終的驗收命令：

   node bin/mirofy.mjs deliver <type> <candidate.json> <output.html> --quality showcase --json
   

   非零的退出碼絕不能描述為成功。如果驗證失敗，僅更改被診斷的 subject，驗證 evidence，從 supportedFixes 中選擇，然後重新執行。在客觀錯誤計數達到新的最小值之前，持續進行針對性修正。如果連續兩輪未改善該最佳計數，請停止並如實報告未解決的診斷資訊。

在第一個候選檔案之前，不要讀取 renderers/shared/geometry.mjs、轉譯器原始碼、驗證器原始碼、測試或基準測試。僅在遇到不支援的內部診斷或在兩次針對性修復失敗後，才檢查實作。

類型路由

類型	用途
architecture	元件、服務、雲端/安全邊界、基礎設施
workflow	流程、核准關卡、工具呼叫、執行手冊、CI/CD
sequence	API 呼叫鏈、請求生命週期、非同步追蹤、回傳值
dataflow	管線、ETL/ELT、譜系、治理、消費者
lifecycle	狀態/狀態轉換、重試、等待和終止狀態

當有歧義時，執行 node bin/mirofy.mjs guide "<scenario>" --json。情境證明範例是結構性參考，不是要複製的事實。

Mermaid 輸入

node bin/mirofy.mjs import mermaid <input.mmd> [output.json] [--json]

flowchart/graph → architecture，sequenceDiagram → sequence，stateDiagram(-v2) → lifecycle。

匯入器從不猜測：任何它無法讀取的行都會變成一個帶有行號的缺口，因此請報告哪些內容未被攜帶過來，而不是稱結果為完整。它也從不指派位置 — 轉換後的架構使用 layout.mode: "grid"，而扇出可能導致邊線穿過節點，這會使始終啟用的 clean-flow 閘門失敗。匯入後始終進行驗證。 也要閱讀原始碼以了解其意義：匯入器攜帶拓撲，而不是領域判斷，因此標籤和類型通常值得重寫。

修復幾何

當驗證報告元件重疊時，不要手動逐一編輯座標：

node bin/mirofy.mjs repair <type> <input.json> [output.json] --safe

--safe 是必需的，因為這會重寫已創作的座標。修復僅移動涉及重疊的元件，每個元件移動最小的修正量以清除驗證器的 8px 間距，列印每個微調的收據，並且只觸碰幾何，絕不觸碰標籤、類型、連接或 ID。它會重新驗證，並命名那些位移無法修復的問題（路由、標籤放置），而不是留給下一次執行重新發現。

創作不變性

• 一條明顯的主要路徑；側分支離開最近的主要路徑節點。在添加路由控制之前，移除低價值的邊線。
• 預設省略 meta.visual_preset，以便每個圖表都以 classic 開啟，無論其解析的顏色模式是淺色還是深色。顏色模式和視覺預設是獨立的：切換淺色/深色必須保留目前的預設。僅在使用者明確要求該視覺樣式時，才設定 signal-flow、blueprint 或 editorial。
• 預設省略 meta.subtitle。切勿發明一個重複標題、節點或卡片內容的子標題；僅在使用者明確要求時，才包含一個簡短的輔助行。
• 預設將獨立的桌面檢視器視為第一畫面成品，而不是淺窄的條帶。為筆記型電腦和外接顯示器生成一個響應式成品 — 永遠不要生成特定於裝置的 HTML 或替代拓撲。檢視器只能從即時視窗高度調整外部閱讀寬度；它必須保留已創作的 SVG/viewBox、比例、語意幾何和正常的文件流。在寬或高的桌面上，使用足夠的已創作垂直節奏，使圖表面板和必要的結論卡片作為一個平衡的整體佔據螢幕；執行時期縮放無法修復過度壓縮的 Y 版面或尺寸過小的顯式 meta.viewBox。在交件前，在 1440×900、1600×1000 和 1920×1080 解析度下開啟實際的 HTML；另外，當構圖預期用於大型桌面顯示器時，檢查 2048×1320。要求在每個檢查的大小下，document.documentElement.scrollWidth <= window.innerWidth 且 scrollHeight <= window.innerHeight，同時視覺上檢查圖表在最大檢查的視口中是否保持舒適可讀且垂直平衡。透過移除真正多餘的內容或壓縮間距（在縮小節點、標籤或主要面板之前）來修復溢出。如果最大的視口在檢視器的寬度上限處仍然有一個顯著的空底部帶，請重新分配已創作的 Y 位置並按比例增加 viewBox 高度；不要添加填充複製文字或裝飾性卡片。切勿使用 overflow: hidden、裁剪內容、內部圖表滾動器、拉伸的 SVG 高度或較小的字體來偽造通過。狹窄/行動版面在需要時可以垂直滾動。
• 對於真實的 auto 預設值，省略 meta.legend。需要時，僅使用 mode: auto|all|hidden 和轉譯器支援的 entries.<kind>.label|visible；標籤永遠不會改變語意。
• 根據使用者的明確選擇選擇一個主要的創作語言；否則請遵循請求或對話的主流語言。meta.locale 僅控制轉譯器擁有的檢視器 UI：使用 "en" 或 "zh-CN" 對應到支援的主要語言。對於所有其他語言，省略 meta.locale 並明確揭露固定的檢視器 UI 和 <html lang> 會回退到英文。轉譯器從不翻譯已創作的內容。詳見 references/authoring-contract.md。
• 保留確切的產品名稱、程式碼識別碼、命令、協定、API 路徑和環境名稱。它們可以在本地化的複製文字中保留英文，但絕不能因此將周圍的說明性散文留在另一種語言。
• 品牌身分是選用且明確的。當節點命名了該真實產品時，在 brand 中放入一個規範的內建 ID。如果沒有匹配的預設值且使用者提供了官方的 HTTP(S) URL，請先執行 node bin/mirofy.mjs brands capture "<url>" --json，然後創作回傳的摘要鎖定 brand 物件。轉譯和驗證永遠不會執行未鎖定的捕獲。否則省略 brand。切勿從模糊的角色（例如 "database"）推斷品牌，也切勿讓徽章取代語義 type、標籤或關係事實。
• 對於序列圖，對於穩定的 fixed 版面，省略 meta.column_fit。當寬 viewBox 會留下未使用的水平空間，或是有意義的參與者標籤無法容納在固定框中時，將其設定為 "spread"；在嘗試 spread 之前，不要縮短語義標籤。
• 元件類型為 frontend、backend、database、cloud、security、messagebus 和 external；變體為 default、emphasis、security 和 dashed。
• 關係標籤是語義資料。當發生碰撞時，移動標籤、調整路由或間距，然後在保留意義的同時縮短措辭。僅在兩個端點完全暗示了關係，且它不包含協定、動作、方向、同步/非同步行為或跨邊界機制時，才刪除標籤；解釋為何被刪除的標籤是多餘的。切勿僅僅為了通過 showcase 而刪除有意義的標籤。
• 預設省略 meta.engineering_profile。區域、叢集和安全邊界措辭本身不會啟用它。僅在使用者明確要求生產部署拓撲、擁有權交接或故障關閉部署審查，且來源事實已知時，才啟用 deployment-ownership。一旦啟用，不得僅僅為了通過驗證而移除工程設定檔；修復事實或如實報告診斷。
• 間距意味著清晰的間隙，而不是中心距離。對於關係標籤，清晰的間隙必須超過其測量的遮罩寬度；在考慮刪除之前，使用保留標籤的修復順序。
• 自動路由擁有其端點側。側邊是一個方向合約：第一個和最後一個區段必須垂直於該側進出。
• 自動連接埠擴展是 architecture、workflow、data-flow 和 lifecycle 的預設轉譯器行為。它跳過單個關係和顯式的 via、channelX、channelY、labelAt 或非 auto 路由。接近的平行連接埠使用外部橋接，以便自動路由不會建立小於 8px 的區段或小於 16px 的內部轉彎。Architecture 另外會在偏移小於 16px 且兩個連接埠都保留角落間隙時，將暢通無阻的面對面自動連接埠（left/right 或 top/bottom）保持在一個共享軸上。如果恰好一個端點被擴展，則只有未共享的端點可以移動到該軸上；如果兩個端點都被擴展，則保留外部橋接，以便競爭的連接埠保持區別。
• 永遠不接受邊線穿過不相關的不透明節點、模糊的共享通道，或關係標籤遮擋另一條路由。

僅在需要欄位列舉、間距計算、自動連接埠放置、幾何修復規則、儲存庫證據或特定模式的放置時，才讀取 references/authoring-contract.md。

交付

在修復期間使用 validate，並僅使用一次 deliver 進行最終驗收。交付將確切的規範位元組凍結到一個私有的同目錄快照中，轉譯並檢查該快照，原子性地提交 HTML，並報告規範和成品兩者的 SHA-256 和位元組計數。

交付後，在不修改或重新轉譯受信任的 HTML 的情況下，收集有限的桌面證據：

node bin/mirofy.mjs visual-check <output.html> --json

visual-check 在 1440×900、1600×1000、1920×1080 和 2048×1320 解析度下測量包含性；在最小和最大的尺寸下捕獲淺色/深色截圖；並在成品旁邊寫入一個相對路徑的聯絡表和 JSON sidecar 檔案。其自動化收據始終報告 visualReview: "pending"：截圖是供檢查的證據，絕非自動的潤飾聲明。退出碼 0 表示包含性和捕獲通過，1 表示溢出或捕獲失敗，2 表示 Chrome/Chromium 不可用且收據為 skipped。該命令永遠不會更改已交付的 HTML。僅在使用者想要立即的本地預覽時，才添加 --open。對於活躍的桌面創作迴圈，選用命令是：

node bin/mirofy.mjs preview <type> <input>.json <output>.html --quality showcase

預設永遠不要啟動預覽。在使用預覽、儲存庫證據、匯出收據、視覺審查或提交後開啟時，請閱讀 references/delivery-contract.md。

選用的檢視器功能

生成的 HTML 已經包含主題切換、平移/縮放、搜尋、聚焦、關係追蹤、語意檢視、簡報和真實的匯出功能。這些是讀者能力，不是額外的創作工作。meta.animation: "trace" 是選擇加入的；meta.views 是選用的，應包含最多五個策劃的章節。僅在使用者明確要求分享卡片、路由/到達卡片、動畫、引導故事、深層連結、簡報、搜尋/聚焦或其他檢視器執行時期功能時，才讀取 references/viewer-runtime.md。

設定和回退

安裝該技能是非必需的。

…

[為進行翻譯而截斷]