panfu/arch-diagram

arch-diagram は何をしますか？

2つのメソッドを単独で、または直列に（自然言語 → Mermaid → HTML）使用できます。

• nl2mmd：自然言語 → Mermaid 方言
• mmd2html：Mermaid 方言 → インタラクティブ HTML（テンプレート：本スキルディレクトリ assets/template.html）

共通の取り決め：Mermaid 方言

構造（3層。HTMLの サーバー→サービス→サブサービス に対応）：

• 最上位 subgraph = サーバー。内部に direction TB を記述
• 2層目 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 読み取り	-.-	読み取り専用のDB参照

• エッジラベル：==>|"type · 時刻または頻度"|、例：==>|"sync · 07:10 4×/日"|；-->|call| は説明を省略可能
• ノードIDは大文字スネークケース：<サーバー>_<サービス>_<サブサービス>、例：NAS_SCHED_FLAT
• エッジはサブグラフ（サービスの階層/サーバーの階層）にアンカー可能で、その粒度のエッジを表します
• flowchart LR で開始；同じホスト内のエッジは通常通り記述します（HTML生成時に右出右入のループ線として描画されます）

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

1. エンティティ抽出：マシン/ホスト/環境 → サーバー；その上にインストールまたは実行されているソフトウェア → サービス；ソフトウェア内のコンポーネント/機能/タスク/ライブラリ → サブサービス。
2. 関係抽出：動詞をタイプにマッピング——同期/書き戻し/ミラーリング → sync；呼び出し/リクエスト/送受信 → call；毎日/定期/cron/xx:xx/プッシュ → job；読み取り/クエリ/ホワイトボックス → data。時刻と頻度はエッジラベルに。
3. 階層が曖昧な場合はサービスの階層に配置し、サブサービスを架空に作成しないでください。
4. 数字と仕様情報（ポート、仕様、タスク量、IPセグメントなど）はノードの備考に：["名前 | 備考"]；時刻と頻度はエッジラベルに。情報を失わないでください。
5. 完全な flowchart LR コードブロックを出力し、説明は不要です。

方法2：mmd2html（Mermaid → インタラクティブHTML）

手順

1. assets/template.html 全文を読み込みます（約38KB、単一ファイルで自己完結、デフォルトデータは examples/sample.mmd の内容）。
2. Mermaidを（上記方言に従って）解析し、mermaid id → 階層パス のマッピングを構築します：パスはドット区切りの サーバー.サービス.サブサービス（ネストの深さに応じて切り捨て）。エッジがサブグラフにアンカーされている場合は、パスは対応する階層で停止します。
3. テンプレート内の /*==DATA==*/ から /*==DATA-END==*/ までのブロック全体を新しいデータブロックに置き換え、他のコードは一字も変更しません：

/*==DATA==*/
var ARCH_TITLE='図のタイトル（ターミナルタイトルバーとスタンドアロン <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. 生成物を目的のパスに書き出します（フラグメント版）。ダブルクリックで使用可能にする場合は、以下のようにラップします：

<!doctype html><html lang="ja"><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を含まないため、カスタムハンドラーで .html に Content-Type: text/html; charset=utf-8 を追加）、開いてタイトル、カウント、▾ servers 粒度切り替え、クリックによる折りたたみを確認します。
3. テンプレートはDATAブロックのみ変更；他のコード（ドラッグ/折りたたみ浮上/永続化）は再実装しないでください。

サンプル

• examples/sample.mmd — 方言の完全な例（4サーバー、9エッジ、4種類の線種すべてと同一ホストエッジを網羅）
• examples/sample.html — テンプレートから生成された完成品（ダブルクリックで使用可能）

生成後のHTMLが持つ機能（テンプレート外で再実装しないこと）

ドラッグ移動（ボックストップのハンドル。Altキーを押すとすべて表示）、右端幅調整、折りたたみ浮上、3つの粒度プリセット（servers/services/leaves）、エッジログ/インスペクター、レイアウトと折りたたみ状態のlocalStorage保存（キー = ARCH_LSKEY）。インターフェースのテキストは英語。

• キャンバスのズームとパン：Ctrl+ホイールでカーソルを中心にズーム（0.4–2.5倍）、Ctrlを押しながらマウスで手の形に変わり、ドラッグでキャンバスをパン；右下のパーセンテージチップをクリックでリセット。ズーム/パンはlocalStorageで永続化。
• 内蔵編集：Altを押しながら任意のノードヘッダー（3層すべて可能）をクリックして名前/備考/サーバーボックス色の変更、子の追加、削除（2段階確認、サブツリーとエッジをカスケード削除）；Altを押しながら線をクリックしてタイプ/時刻の変更または線の削除；Altを押しているときに右上に ⇱ export が表示され、モーダルで最新状態のMermaidを表示（シンタックスハイライト + コピー）、⟲ relayout と ↺ デフォルトデータ復元を含む。編集結果はlocalStorageで永続化。