archify

Archify Skill

建立專業技術圖表，輸出為包含內嵌 SVG、主題切換器以及內建圖片／SVG 匯出選單的自包含 HTML 檔案。

每個由繪製器驅動的圖表均配備客觀的「圖表指南（Diagram Guide）」以探索當前操作與快捷鍵、確定性語意節點 Hook、具備精選內嵌圖例入口的計數雙類型「語意鏡頭（Semantic Lens）」、在確定焦點前使用的精確指標／鍵盤「意圖軌跡（Intent Trace）」、針對作者定義之有向關聯進行分析的雙端點「路徑探針（Route Probe）」、可搜尋的「節點尋找器（Node Finder）」、具備繪製器專屬「語意護照（Semantic Passport）」與可複製深層連結的鍵盤可達單跳焦點、即時「語意雷達（Semantic Radar）」總覽、可選的具名「章節軌（Named Chapter Rail）」及其靜態「章節增量預覽（Chapter Delta Preview）」、原生「故事拍點導航器（Story Beat Navigator）」配有「故事跟隨鏡頭（Story Follow Camera）」、「故事導演列（Story Director Strip）」與「故事地平線（Story Horizon）」、穩定的「可分享故事瞬間（Shareable Story Moment）」連結、供讀者控制軌跡產物的「動態／靜態運動控制器（Live/Still Motion Governor）」、僅供檢視者單次嵌入使用的「分享章節提示（Share Chapter Cue）」、「簡報舞台（Presentation Stage）」、無第三方套件依賴的平移／縮放、深色／淺色主題切換（持久化儲存於 localStorage，並遵循 prefers-color-scheme）、匯出選單（複製 PNG 至剪貼簿；以最高 4 倍解析度原生點陣化下載 PNG/JPEG/WebP；下載雙主題 SVG；將支援軌跡錄製的圖表錄製為 WebM），以及保持雙主題視覺一致的 CSS 變數色彩系統。暫時性的 Diagram Guide、Semantic Lens、圖例預覽、Intent Trace、Route Probe、尋找器、焦點、雷達、Chapter Delta Preview、Story Trail 覆蓋層、Story Director Strip、Story Horizon、拍點狀態、引導檢視、播放、簡報、運動擁有者與視口狀態，絕不會改變標準全圖表的匯出結果。

「閱讀深度（Reading Depth）」會在讀者放大時，漸進式揭示繪製器專屬的上下文與精細細節，而語意互動則能在任何縮放比例下，精確呈現讀者所需的區域資訊。

「直接關聯釘選（Direct Relationship Pin）」讓每個編譯出的獨特關聯皆可直接操作，無須修改原先繪製的線條。您可以使用標準識別碼模式，為重要的 connections、edges、messages、flows 與 transitions 提供可選的作者控管 id；ID 在其關聯集合中必須保持唯一。繪製器會保留其數值 data-edge-key 用於執行期去重，並將作者識別碼另行輸出為 data-edge-id。執行期時，系統會拒絕衝突的 source/target/label/ID 元資料，並僅將 path/line/polyline 幾何形狀複製到節點下方的檢視者專屬覆蓋層中。使用 24px 透明非縮放外框進行點擊命中測試，並輔以獨立的虛線焦點軌；精確保留一個 tabindex="0" 的關聯按鈕，並可透過所有方向鍵、Home 與 End 移動焦點。精確指標懸停與鍵盤焦點會暫時重用精確的關聯預覽（Relationship Preview）。點擊、觸控、Enter 或 Space 會開啟來源端的語意護照，並釘選現有的精確 Lens 資料列。當關聯包含作者定義的 ID 時，釘選操作會寫入 #relation=<id>，將操作變更為 Copy relation，並在重新排序後還原相同的 source、target、label、path 與受限鏡頭；過期的 ID 則採失敗封閉機制（fail closed）。無 ID 的舊版關聯仍保持頁面內釘選、保留 Copy node，且絕不暴露其數值 Key。再次點擊相同關聯、真正的背景觸發、Clear 或 Escape 皆可清除釘選。aria-pressed 用於傳達釘選狀態，而 source/target/label 名稱保持穩定。觸控操作無需等待懸停，節點在端點附近享有優先權，平移絕不會觸發關聯，且較強的 Focus、Story、Route、Semantic Lens、Chapter 與嵌入狀態具備優先執行權。請勿新增額外的面板、工具列動作、第三方元件、儲存區或繪製幾何。在嵌入、列印與標準匯出中，請移除所有命中、釘選、預覽與脈衝狀態；並保留作者定義的 data-edge-id 作為語意 SVG 識別碼。

設定

無須安裝任何第三方套件。發行套件中已包含從五個 JSON Schema 編譯而成的獨立驗證器，因此安裝後即可立即進行 Schema 與排版驗證。產生的 HTML 與繪製器執行期皆無第三方依賴。

執行 node bin/archify.mjs doctor 可驗證安裝狀態。在建立第一個自訂圖表前，執行 node bin/archify.mjs demo [output-directory] 可生成可直接開啟的範例。

若您完全無法使用 Shell 權限（例如 Skill 是作為專案知識庫新增），請在處理任何需求時退回使用架構模式：遵循下方的設計系統，手動將 SVG 放置到 assets/template.html 中，並在交付前完成自我審查清單。

選擇圖表類型

當需求描述較模糊時，請在選擇繪製器前執行 node bin/archify.mjs guide "<the user's scenario>"。內建的無依賴指南會從 11 個限定情境食譜中選出最合適的方案，並傳回已解答的問題、何時使用或避免、所需佐證、簡報設定以及可直接複製的提示詞。--json 為自動化流程提供相同的契約，而 --lang en|zh 則可覆寫語言偵測。請將建議作為起點，並對照使用者的實際問題與儲存庫佐證進行確認。

每個內建的情境食譜皆由 examples/ 中已簽入且通過驗證的範例，以及產生的 Proof Lab 卡片提供支援。請將這些範例作為結構參考，而非直接複製其領域內容。當修改儲存庫中的食譜或證明範例時，請重新生成 docs/guide.html 與 docs/gallery.html；測試會強制驗證所有 11 個食譜證明 ID 皆可解析，且每個證明皆保留三個具名的讀者檢視。

類型	適用於	操作方式
architecture	系統組件、雲端資源、服務、資安邊界、基礎設施	renderers/architecture/render-architecture.mjs + JSON（或當繪製器無法執行時手動放置 SVG）
workflow	技術流程、審核關卡、工具呼叫、Runbook、CI/CD、應變處置	renderers/workflow/render-workflow.mjs + JSON
sequence	API 呼叫鏈、請求生命週期、快取快退（fallback）、非同步追蹤、傳回路徑	renderers/sequence/render-sequence.mjs + JSON
dataflow	資料管道、ETL/ELT、PII 隔離、資料血緣、資料倉庫同步、消費者	renderers/dataflow/render-dataflow.mjs + JSON
lifecycle	狀態機、狀態轉移、等待狀態、重試機制、終端狀態	renderers/lifecycle/render-lifecycle.mjs + JSON

觸發詞彙："architecture/system/cloud diagram" → architecture（除非有明確的程序導向）。"workflow/flow/process/runbook/approval/CI-CD/incident" → workflow。"sequence/interaction/call chain/who calls whom" → sequence。"data flow/pipeline/ETL/lineage/PII/governance" → dataflow。"state/status/lifecycle/state machine/retry/terminal" → lifecycle。

將 Mermaid 作為輸入語法

當使用者貼上 Mermaid 程式碼時，請勿嘗試直接進行機械式的繪製或剖析 — 請閱讀其結構，並在對應的 archify 模式中從頭開始排版：

Mermaid	Archify 模式	映射方式
flowchart / graph	workflow（若為組件圖則使用 architecture）	subgraph → 泳道或區域邊界；節點形狀 {} (菱形) → 判斷／資安節點；--> 標籤 → 邊緣標籤（謹慎使用）；classDef/style → 最接近的語意類型
sequenceDiagram	sequence	participant → 參與者（從名稱選擇語意 type）；->> → 訊息，-->> → return 變體；Note → 訊息 note；rect 區塊 → 區段（segments）
stateDiagram	lifecycle	states → 狀態（從名稱選擇 start/active/waiting/success/failure）；[*] 開始／結束 → start 類型／terminal 泳道；轉移標籤 → 事件類標籤

捨棄 Mermaid 的樣式；僅保留拓撲結構與語意。由您來決定分組、泳道順序以及值得強調的重點 — 這項專業判斷正是產品的價值所在。

排版原則（擺放前必讀）

Archify 的易讀性來自於空間敘事，而非將每個依賴關係都畫成箭頭。在撰寫座標或邊緣清單前，請先規劃一個清晰的故事：

1. 一條主要路徑 — 自左至右（architecture）或自泳道至欄位（workflow）。讀者應能順暢追蹤正常流程（happy path）而不必跨越線條。
2. 精簡標記邊緣 — 僅在主要路徑上標記跨越邊界或非直覺的轉移。相鄰的步驟保持無標籤狀態。
3. 簡短的分支 — 權限、儲存、Bot、CI：從主要路徑上最近的節點向上或向下連接。絕不要將次要邊緣斜向跨越無關的組件。
4. 使用卡片呈現細節 — 政策、技術棧說明以及「同時連接至 X」等資訊，應歸類於摘要卡片中，而非繪製額外的箭頭。
5. 契合模式 — 程序／審核／工具呼叫故事 → workflow 或 sequence。節點數 ≤12 的組件圖 → architecture。若圖表需要 20+ 個邊緣，請刪減邊緣直到主要路徑變得清晰。

符合此模式的實作範例：examples/archify-repo.architecture.json（本儲存庫）與 examples/maka-architecture.architecture.json（第三方桌面應用程式）。

當驗證因標籤重疊而失敗時，請閱讀**建議修復（Suggested fix）**列（座標 / labelAt / labelDy）並直接應用 — 切勿盲目猜測偏移量。

繪製器模式（architecture / workflow / sequence / dataflow / lifecycle）

所有五種模式皆遵循相同的迴圈：

1. 先閱讀：Schema（schemas/<type>.schema.json）以及完整的實作範例（examples/*.{architecture,workflow,sequence,dataflow,lifecycle}.json） — 請參考其模式，而非盲目猜測欄位結構。
2. 撰寫 <name>.<type>.json。
3. 繪製：node bin/archify.mjs render <type> <input>.json <output>.html（路徑相對於此 Skill 資料夾）。
4. 驗證產生的產物：node bin/archify.mjs validate <type> <input>.json --json，密集工程圖請明確加上 --quality standard，精緻交付圖請加上 --quality showcase，或使用 node bin/archify.mjs check <output>.html 檢查現有的 HTML 檔案。這能捕捉格式錯誤的 SVG 輸出、非有限 SVG 值、兩點斜向箭頭、跨越圖例的箭頭，以及感知 Profile 的關聯交叉。
5. 若任一步驟失敗，錯誤訊息會指出 JSON 路徑或修復方式（臨界值、有效範圍、需調整的參數）。修復 JSON 並重新執行；切勿