圖表產生器 是做什麼的？
ACTION REQUIRED（讀完後立刻執行）
NOW：確認當前任務是否命中本 skill 的適用範圍NOW：讀取../tool-index.md，校驗工具可用性和實際路徑NEXT：缺工具時呼叫 bootstrap，不要猜路徑ACT：進入「工作流」第一步並執行，不要停在確認狀態
Purpose
從雜亂或結構化的輸入建立清晰、可編輯的圖表。優先使用文字式圖表原始碼，以便結果可審查、可版本控制、可優化。僅在使用者要求圖片/PDF，或產出可下載的成品有實質幫助時，才渲染成檔案。
Default workflow
- 識別使用者的意圖、受眾與來源素材。
- 使用下方的決策表選擇圖表家族與語言。
- 在撰寫圖表程式碼前，正規化實體、關係、標籤、狀態、分支與時間/順序資訊。
- 產生簡潔且可讀的圖表原始碼。
- 在腦中驗證語法，並於建立檔案時執行
scripts/render_diagram.py。 - 回傳圖表原始碼以及關於假設的簡短說明。若產生了檔案，請包含輸出檔案的連結。
不要過度要求澄清。若請求的規格不足，請做出合理的假設並簡短標記。
Diagram language decision table
除非其他語言明顯更適合，否則使用 Mermaid。
| 使用者想要 | 偏好使用 | 原因 |
|---|---|---|
| 流程圖、決策樹、簡單泳道 | Mermaid flowchart | 可讀性高，易於貼入 Markdown |
| 系統/使用者互動的序列 | Mermaid sequenceDiagram 或 PlantUML sequence | Mermaid 用於文件；PlantUML 用於 UML 正式規格 |
| 生命週期、狀態機、轉換 | Mermaid stateDiagram-v2 或 PlantUML state | 簡潔的轉換語法 |
| 資料庫綱要、實體、關係 | Mermaid erDiagram | 可攜式的 ER 表示法 |
| 類別/介面/物件模型 | Mermaid classDiagram 或 PlantUML class | Mermaid 用於文件；PlantUML 用於詳細 UML |
| 專案時程表 | Mermaid gantt | 簡潔的時間軸語法 |
| 階層、想法、筆記 | Mermaid mindmap | 適合想法地圖的預設 |
| 顧客/產品旅程 | Mermaid journey | 內建的旅程表示法 |
| Git 歷史 | Mermaid gitGraph | 內建的 Git 表示法 |
| 相依圖、套件圖、大型網路 | Graphviz DOT | 對密集圖表有更好的佈局引擎 |
| 包含層級、叢集、邊界的架構 | Mermaid flowchart 搭配子圖、Graphviz clusters 或 PlantUML C4 風格 | 根據要求的精確度選擇 |
| 加權流程/桑基圖關係 | Mermaid sankey-beta（若支援），否則 SVG 或 Graphviz | Mermaid 支援度因渲染器而異 |
| 原始語言難以表達的自訂視覺 | SVG | 對佈局與樣式有精確控制 |
Output policy
- 除非使用者明確只要求圖片，否則一律提供可編輯的原始碼。
- 預設輸出單一最佳圖表。僅在真正有用時才提供替代方案。
- 偏好穩定、簡單的語法，避免在較舊的 Mermaid/PlantUML 版本中可能無法渲染的花俏功能。
- 使用簡短的標籤。必要時將長文字拆分為圖表外的註解。
- 避免模糊的節點 ID。使用 ASCII ID 與可讀的標籤。
- 保留使用者的術語，但在一張圖表內標準化大小寫。
- 對於技術圖表，當隱含客戶端、服務、資料庫、佇列、外部 API 與操作者/使用者時，請包含這些邊界。
- 對於商業流程圖，當存在快樂路徑、決策點、失敗、重試與人工步驟時，請加以區分。
- 對於從不確定文字建立的圖表，請在程式碼之後加上
Assumptions章節。
Mermaid generation rules
請參閱 references/diagram-patterns.md 以取得簡潔的範本。
一般 Mermaid 規則：
- 以正確的圖表指令開始，例如
flowchart TD、sequenceDiagram、erDiagram、gantt、mindmap或journey。 - 對於流程圖，除非使用者要求由左至右，否則使用
flowchart TD；對於架構與管線，使用flowchart LR。 - 使用子圖表示泳道或架構層級。為子圖命名可讀的標籤。
- 保持節點 ID 穩定且僅含 ASCII，例如
ingest_service[Ingest Service]。 - 對包含可能混淆解析器的標點符號的標籤加上引號。
- 使用決策菱形表示分支：
decision{Condition?}。 - 使用一致的邊緣標籤：僅在有意義時使用
-- yes -->、-- no -->、-. async .->或== critical ==>。 - 在序列圖中，在訊息之前宣告參與者。使用
actor表示人類，participant表示系統。 - 使用
alt/else/end、opt/end、loop/end與par/and/end區塊表示條件、選擇、重複與並行流程。
Graphviz DOT generation rules
對於大型、密集或對佈局敏感的關係圖，使用 Graphviz。
- 偏好使用
digraph G表示有向關係，graph G表示無向網路。 - 在頂端設定對佈局友善的圖形屬性：
rankdir=LR、nodesep、ranksep，必要時設定splines=true。 - 使用
subgraph cluster_name表示邊界與子系統。 - 使用純文字標籤與節制的樣式。
- 僅在有意義時才使用邊緣標籤。
- 對於大量節點，使用叢集按領域分組，並避免過多重疊的全連接邊。
PlantUML generation rules
當使用者要求 UML 或需要正式的 UML 表示法時，使用 PlantUML。
- 使用
@startuml與@enduml包裹圖表。 - 在有用時使用
actor、participant、database、queue、collections或component原型。 - 使用
package、rectangle或node表示架構邊界。 - 對於類別圖，除非使用者要求詳盡細節，否則僅包含重要的欄位/方法。
- 對於活動圖，使用明確的開始/結束標記與明確的分支標籤。
SVG generation rules
僅在文字圖表語言無法可靠表達要求的視覺效果時，才使用 SVG。
- 保持 SVG 簡單、可存取且可編輯。
- 包含
<title>與有意義的文字標籤。 - 偏好矩形、線條、箭頭與群組，而非複雜路徑。
- 不要嵌入外部字型或遠端圖片。
Rendering files
當使用者要求 PNG/SVG/PDF 時，建立原始碼檔案並執行：
python "<SKILL_ROOT>/diagram-generator/scripts/render_diagram.py" input.mmd --format svg --out output.svg
python "<SKILL_ROOT>/diagram-generator/scripts/render_diagram.py" input.dot --format png --out output.png
python "<SKILL_ROOT>/diagram-generator/scripts/render_diagram.py" input.puml --format svg --out output.svg
<SKILL_ROOT>是本套件skills/目錄的實際路徑，AI 應自動偵測。
The renderer is intentionally dependency-tolerant. It tries common local tools and reports actionable installation hints if a renderer is unavailable. Do not claim an image was rendered unless the script completed successfully and the output file exists.
Validation checklist
在最終確定前：
- 圖表類型符合使用者的任務。
- 原始碼在所選語言中語法合理。
- 標籤足夠簡短以容納。
- 邊緣與訊息順序正確反映輸入。
- 當輸入不完整時，已標註假設。
- 對於產生的檔案，輸出存在且可開啟或大小不為零。
Common response template
對大多數圖表回答使用此結構：
以下是可編輯的 [語言] 版本：
```[language]
[source]
Assumptions:
- [僅在需要時]
Rendered file: [link] [僅在產生時]
對於英文使用者的請求，請用英文回覆。對於中文使用者的請求，請用中文回覆，除非他們另有要求。
---
## 按需自舉（On-Demand Bootstrap）
### 自動化能力邊界
| 工具 | 可自動安裝 | 安裝方式 | 說明 |
|------|-----------|---------|------|
| Mermaid CLI (mmdc) | ✓ | npm install -g @mermaid-js/mermaid-cli | 渲染 Mermaid 為 PNG/SVG |
| Graphviz (dot) | ✗ | 手動安裝 | https://graphviz.org/download/ |
| PlantUML | ✗ | 需要 Java + plantuml.jar | https://plantuml.com/download |
| Python (render script) | ✓ | 已在 bootstrap 中 | `scripts/render_diagram.py` 依賴 |
### 說明
本 skill 主要輸出文字格式的圖表原始碼（Mermaid/DOT/PlantUML），不一定需要本地渲染工具。只有當使用者明確要求產生 PNG/SVG/PDF 檔案時才需要對應的渲染器。
如果渲染器不可用，`scripts/render_diagram.py` 會輸出安裝提示而非報錯。
---
## 路由上下文
**上游入口**: `skills/SKILL.md`（總控）、`routing.md`
**觸發條件**: 使用者說「畫圖」、「流程圖」、「架構圖」、「攻擊路徑圖」、「時序圖」、「Mermaid」、「Graphviz」、「PlantUML」
**下游出口**:
- 產生的圖表可嵌入 `docs-generator/` 的報告中
- 攻擊路徑圖可配合 `pentest-tools/` 的滲透報告
**同級關聯模組**: `docs-generator/`（報告中嵌入圖表）
## 任務完成自檢（聲稱完成前 MUST 通過）
- [ ] 我是否執行了工作流中的每一步（而不是只閱讀）？
- [ ] 我是否基於 `tool-index` 使用了真實工具路徑？
- [ ] 我是否產出了可重現證據（命令/腳本/截圖/報告）？
- [ ] 我是否完成並回寫了 RULES 要求的 Checklist 項？