Skill 決策流程圖產生器
讀取一份 SKILL.md，提取結構化資料 nodes.json，腳本確定性生成流程圖 HTML。
分工
| 階段 | 誰幹 | 為什麼 |
|---|---|---|
| SKILL.md → nodes.json | AI | SKILL.md 是自然語言，語義不穩定，靠 AI 理解上下文 |
| nodes.json → HTML | 腳本 | 座標計算要確定性、可重現、對齊像素 |
AI 只輸出結構化資料，絕不輸出座標或 SVG；腳本只做幾何，絕不猜語義。
執行步驟
1. 讀取 SKILL.md
讀取使用者指定的 SKILL.md。若未找到，詢問使用者輸入路徑。
2. AI 提取 nodes.json
依以下 schema 輸出 JSON。每條出邊必須顯式標註 side 欄位——這是 AI 的語義判斷，腳本不會猜。
頂層結構
{
"title": "技能名稱",
"subtitle": "可選描述",
"nodes": [ ... ],
"edges": [ ... ],
"loops": [ ... ],
"legend": [ ... ]
}
nodes：必填，節點陣列edges：必填，有向邊陣列loops：可選，迴環虛線（見下文）legend：通常留空[]，使用預設圖例
節點 type
| type | 含義 | 形狀 |
|---|---|---|
entry | 流程起點 | 圓角矩形 |
decision | 決策點（是/否、有/無） | 菱形 |
process | 處理步驟 | 圓角矩形 |
output | 報告/檔案輸出 | 圓角矩形 |
terminal | 終止/報錯退出 | 圓角矩形 |
節點 role（配色）
| role | 含義 | fill / stroke |
|---|---|---|
ai | AI 推理 / LLM 呼叫 | #E6F1FB / #185FA5 |
output | 報告 / 檔案輸出 | #EEEDFE / #534AB7 |
decision | 決策點 | #FAEEDA / #854F0B |
script | 腳本執行 | #E1F5EE / #0F6E56 |
terminal | 終止 / 報錯 | #FCEBEB / #A32D2D |
一個節點只能有一個 role。 如果一個步驟涉及多種不同性質的工作（對應不同 role），必須拆成多個節點串聯。例如「腳本取基線 + AI 補充分析」不能合併為一個 role=ai 的節點，必須拆成 role=script 和 role=ai 兩個節點。
邊 side（關鍵！）
| side | 含義 | 佈局行為 |
|---|---|---|
bottom | 主流程向下 | target 在 from 下一層，cx 繼承 from |
left | 決策左分支 / 分叉左 | 決策→同層水平連；普通→下一層正交折線 |
right | 決策右分支 / 分叉右 | 同上，方向相反 |
side 的語義判斷由 AI 完成：
- 決策菱形（type=decision）的
left/right→ 與決策同層，水平連線 - 普通矩形（type=process/output）的
left/right→ 下一層，正交折線（垂直→水平→垂直，無斜線）
loops（迴環，可選，虛線）
當流程中存在「回到先前步驟」的邏輯時使用，例如：
- 修復後重新審查（
apply_fix → entry） - 重試（
retry → checkpoint） - 循環直到滿足條件（
recheck → validate）
{ "from": "apply_fix", "to": "entry", "label": "修復後重新審查", "path": "left_edge" }
欄位說明：
from：迴環起點節點 id（通常是最後一步）to：迴環終點節點 id（通常是流程起點或某個檢查點）label：迴環標籤，顯示在虛線旁path：固定為"left_edge"（沿圖左邊緣路由）
注意：
- 迴環起點到終點之間不要在 edges 裡重複畫邊，否則會重複渲染
- loops 裡的 from/to 節點不參與 depth 計算
legend
通常留空 []，腳本會使用預設 5 色圖例。如需自訂：
[
{ "label": "AI 執行", "fill": "#E6F1FB", "stroke": "#185FA5" },
{ "label": "輸出/報告", "fill": "#EEEDFE", "stroke": "#534AB7" },
{ "label": "決策點", "fill": "#FAEEDA", "stroke": "#854F0B" },
{ "label": "腳本", "fill": "#E1F5EE", "stroke": "#0F6E56" },
{ "label": "終止", "fill": "#FCEBEB", "stroke": "#A32D2D" }
]
3. 呼叫腳本生成 HTML
python3 <skill_dir>/scripts/flowchart.py <nodes.json> --out docs/decision-flowchart.html
腳本會：
- 校驗 id 唯一性、side/type/role 合法性、from/to 引用合法性
- 自動計算層級（決策側支同層 / 普通分叉下層 / 匯合點 = max(入邊)+1）
- 自動計算 x（side 決定）和 y（按層級 + 節點高度）
- 渲染連線（水平側支 / 正交折線 / 垂直主流程 / 匯合三段 / 迴環虛線）
- 自動 viewBox + 底部圖例
- 輸出自包含 HTML
nodes.json 範例
docs/halucatch-v2-nodes.json— 完整範例（含 loop 迴環、三叉分支、匯合點）docs/halucatch-nodes.json— 基礎範例docs/security-review-nodes.json— 多決策點範例docs/self-nodes.json— 最小範例（9 節點）
自檢清單
- 入口節點 type=entry 在最頂部
- 每條邊都有 side 欄位（bottom/left/right）
- 決策菱形的 side=left/right 是側支（同層水平連線）
- 普通矩形的 side=left/right 是分叉（下層正交折線）
- 一節點一 role，混合步驟已拆分
- 匯合點（多條入邊到同一節點）不需要特殊處理，腳本自動識別
- 迴環用 loops 欄位，不在 edges 裡重複
- 所有節點 id 在 edges 的 from/to 中都被引用（無孤立節點）
- 圖例留空
[]
常見問題
Q: 節點重疊了怎麼辦？
檢查是否缺少 side 欄位。決策分支必須有 side（left/right/bottom），否則兩個目標節點會繼承同一位置。
Q: 迴環虛線沒有畫出來？
迴環用 loops 陣列宣告（不是 edges），且 from/to 不要在 edges 裡重複。path 固定為 "left_edge"。
Q: 腳本報 JSON 格式錯誤？ JSON 不支援註解和單引號。常見問題：缺少逗號、多餘逗號（陣列末尾）、單引號。
更多問題參見 docs/FAQ.md。