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。