panfu/arch-diagram

arch-diagram 是做什麼的？

兩個方法，可單獨用，也可串聯（自然語言 → Mermaid → HTML）。

• nl2mmd：自然語言 → Mermaid 方言
• mmd2html：Mermaid 方言 → 互動式 HTML（模板：本 skill 目錄 assets/template.html）

共同約定：Mermaid 方言

結構（三層，與 HTML 的 伺服器→服務→子服務 對應）：

• 頂層 subgraph = 伺服器，內寫 direction TB
• 二層 subgraph = 服務（僅當有子服務時才建子圖；無子服務的服務直接寫成節點）
• 服務子圖內的節點 = 子服務
• 所有標題用帶引號文字：subgraph X["標題"]、N["標題"]

備註（meta）：標題內用 | 分隔名稱與備註，生成 HTML 後顯示在名稱旁的淺色小字（伺服器規格、埠號、任務量、參數等）。無備註就不寫 |：

• subgraph WEB["Web 邊緣 | 雙活 · LAN"] → 伺服器名 "Web 邊緣"，備註 "雙活 · LAN"
• WEB_GW["API 閘道 | QPS 3k"] → 服務名 + 備註
• 解析規則：取最後一個 |，左側為名稱、右側為備註

邊類型由線型表達，固定不變：

類型	線型	語義
sync 同步	==>	資料同步 / 寫回
call 呼叫	-->	API / RPC / WS
job 定時	-.->	cron / 計劃任務 / 推送
data 讀取	-.-	唯讀查庫

• 邊標籤：==>|"type · 時刻或頻率"|，如 ==>|"sync · 07:10 4×/日"|；-->|call| 可省略說明
• 節點 id 用大寫蛇形：<伺服器>_<服務>_<子服務>，如 NAS_SCHED_FLAT
• 邊可以錨在子圖上（服務級/伺服器級），代表該邊在該粒度
• flowchart LR 開頭；同宿主的內部邊照常寫（生成 HTML 時會畫成右出右入的環線）

方法一：nl2mmd（自然語言 → Mermaid）

1. 抽實體：機器/主機/環境 → 伺服器；其上安裝或執行的軟體 → 服務；軟體內的元件/功能/任務/函式庫 → 子服務。
2. 抽關係：動詞映射類型——同步/寫回/鏡像 → sync；呼叫/請求/收發 → call；每日/定時/cron/xx:xx/推送 → job；讀取/查詢/白盒 → data。時間與頻率寫進邊標籤。
3. 層級拿不準就放服務級，不要虛構子服務。
4. 數字與規格資訊（埠號、規格、任務量、IP 段等）進節點備註：["名稱 | 備註"]；時間與頻率進邊標籤。不要丟。
5. 輸出一個完整 flowchart LR 程式碼區塊，無需解釋。

方法二：mmd2html（Mermaid → 互動 HTML）

步驟

1. 讀 assets/template.html 全文（約 38KB，單檔案自包含，預設資料即 examples/sample.mmd 的內容）。
2. 解析 Mermaid（按上方方言），建立 mermaid id → 層級路徑 映射：路徑為點連接的 伺服器.服務.子服務（按巢狀深度截斷）。邊錨在子圖時，路徑停在對應層級。
3. 把模板中 /*==DATA==*/ 到 /*==DATA-END==*/ 之間的整塊替換為新資料區塊，其餘程式碼一字不改：

/*==DATA==*/
var ARCH_TITLE='圖標題（終端標題列與 standalone <title>）';
var ARCH_LSKEY='arch-<slug>';   // localStorage 鍵，每張圖唯一
var TYPE={sync:{c:'#3ecf8e',dash:'10 4',dur:'1.5s',label:'同步'},
 call:{c:'#58a6ff',dash:'6 5',dur:'1.1s',label:'呼叫'},
 job :{c:'#f0a942',dash:'2 4',dur:'0.85s',label:'定時'},
 data:{c:'#b18cff',dash:'14 5',dur:'1.9s',label:'讀取'}};
var COLS=[['srvA','srvB'],['srvC']];   // 預設列佈局：陣列每列 = 一組伺服器 id
var SERVERS=[
 {id:'srvA',short:'A',name:'A · 顯示名',meta:'備註',ac:'#b18cff',svc:[
   {id:'svc1',short:'svc1',name:'服務1',meta:'',subs:[
     {id:'sub1',short:'sub1',name:'子服務1',meta:''}]},
   {id:'svc2',short:'svc2',name:'服務2'}]},
];
var EDGES=[
 {from:'srvA.svc1.sub1',to:'srvC.svc2',type:'sync',sched:'07:10 4×/日'},
];
/*==DATA-END==*/

欄位規則：

• id 用 ASCII（點路徑由此拼出）；name 可中文；short 是連線/日誌裡的短名
• meta 來自節點/子圖標題裡最後一個 | 之後的部分，沒有則省略
• ac 從色板輪換：#b18cff #3ecf8e #39d0c4 #58a6ff #f0a942
• type ∈ sync|call|job|data（對應 Mermaid 線型）；sched 來自邊標籤裡 type 之後的部分，沒有就寫 即時
• COLS：按邊的流向粗排（源在左、匯在右）；單伺服器的列生成器會自動垂直居中

4. 產物寫到目標路徑（fragment 版）。需要雙擊可用時，包一層：

<!doctype html><html lang="zh-TW"><head><meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>{ARCH_TITLE}</title>
<style>html,body{margin:0;padding:0;background:#080b12}#svcarch{min-height:100vh}</style></head><body>
{fragment}</body></html>

QA

1. 必做：抽出 <script> 跑 node --check；核對資料——伺服器/服務/子服務數與 Mermaid 一致，邊數 = Mermaid 邊數，預設視圖連線數 = 去重後 (from,to,type) 組數。
2. 有瀏覽器時：起本地服務必須帶 charset 頭（python3 -m http.server 不帶 charset 會中文亂碼，需自訂 handler 給 .html 加 Content-Type: text/html; charset=utf-8），開啟檢查標題、計數、▾ servers 粒度切換、點擊收合。
3. 模板只改 DATA 區塊；其餘程式碼（拖曳/收合上浮/持久化）不要重複實作。

範例

• examples/sample.mmd — 方言完整範例（4 伺服器、9 條邊、覆蓋全部 4 種線型與同宿主邊）
• examples/sample.html — 由模板生成的成品（雙擊可用）

生成後的 HTML 自帶能力（不要在模板外重複實作）

拖曳移動（框頂把手，按住 Alt 全顯示）、右緣調寬、收合上浮、三種粒度預設（servers/services/leaves）、edge log / inspector、佈局與收合狀態存 localStorage（鍵 = ARCH_LSKEY）。介面文案為英文。

• 畫布縮放與平移：ctrl+滾輪以游標為中心縮放（0.4–2.5×），按住 ctrl 滑鼠變手形、拖曳平移畫布；右下角百分比 chip 點擊重設。縮放/平移隨 localStorage 持久化。
• 內建編輯：按住 Alt 點擊任意節點頭部（三層均可）改名稱/備註/伺服器框色、新增下屬、刪除（兩段確認，級聯子樹與邊）；Alt 點擊連線可改類型/時刻或刪邊；Alt 按住時右上出現 ⇱ export，彈窗顯示最新狀態的 Mermaid（語法高亮 + 複製），內含 ⟲ relayout 與 ↺ 恢復預設資料。編輯結果隨 localStorage 持久化。