SkillFlowChart 流程图生成器

这个流程图为什么要拆成两段来做

给一个技能（SKILL.md）画决策流程图，卡点通常不在画图，而在语义：文档里的步骤是用自然语言写的，「如果校验失败就重试」这句话该变成菱形还是矩形、分支朝左还是朝右，只有懂上下文的模型能判断。但坐标计算必须确定、可复现，否则同一份输入今天画出来是布局，明天就成了一团错位的方块。

SkillFlowChart 用分工解决这个矛盾：

• AI 只输出结构化数据：理解 SKILL.md，输出符合 schema 的 nodes.json，包含 nodes、edges，可选 loops 和 legend。它绝不输出坐标或 SVG。
• 脚本只做几何：读取 nodes.json 做合法性校验、层级推算、坐标计算，渲染连线并输出自包含 HTML。它绝不猜语义。

它具体怎么做

1. 读取用户指定的 SKILL.md；文件未找到时先询问路径。
2. AI 按 schema 产出 nodes.json，这是全流程里唯一需要语义判断的环节。
3. 脚本校验 id 唯一性、side/type/role 合法性、from/to 引用合法性，然后自动计算层级、x 与 y 坐标，渲染连线并输出 HTML。

几个关键字段决定了最终图的形状：

• 每条边都必须显式标注 side（bottom / left / right）。缺少这个字段时，两个目标节点会继承同一坐标，出现节点重叠；这是最常见的排版错误。
• side 在两类节点上的布局行为不同：决策菱形（type=decision）的 left/right 是与决策同层的水平连线；普通矩形（type=process/output）的 left/right 是下一层的正交折线（垂直→水平→垂直，不画斜线）。
• 一个节点只能有一个 role，对应五种配色：ai、script、decision、output、terminal。混合了不同性质工作的步骤必须拆开，例如「脚本取基线 + AI 补充分析」要拆成 role=script 和 role=ai 两个串联节点。
• 节点 type 决定形状：entry 与 process/output/terminal 用圆角矩形，decision 用菱形。
• 回环用可选的 loops 数组声明，path 固定为 left_edge（沿图左边缘路由），虚线旁可加 label。loops 里的 from/to 不参与 depth 计算。

脚本还会自动处理汇合点：多条入边指向同一节点时取 max(入边)+1 作为层级，不需要特殊标注。legend 通常留空 []，脚本会补上默认的五色图例。

仓库 docs/ 下提供了四份可直接对照的示例：halucatch-v2-nodes.json（含 loop 回环、三叉分支、汇合点）、halucatch-nodes.json（基础示例）、security-review-nodes.json（多决策点）、self-nodes.json（9 节点最小示例）。

适用边界与注意点

• 它服务于 SKILL.md 的决策流程，不是通用流程图工具。分支方向、节点性质这些语义判断必须由模型完成，脚本不会替你补全。
• 生成前建议按文档末尾的自检清单过一遍：入口节点 type=entry 在最顶部、每条边都有 side、混合 role 已拆分、loops 里的边没有在 edges 里重复声明、没有孤立节点、图例留空。
• 回环虚线没画出来通常是两个原因：用了 edges 而不是 loops，或者 from/to 之间在 edges 里重复了同一条边。
• 节点重叠先检查是否缺少 side 字段——决策分支必须有显式的 left/right/bottom。
• nodes.json 是标准 JSON，不支持注释和单引号。报格式错误时优先排查多余逗号（尤其是数组末尾）、缺失逗号、单引号。
• 需要扩展 schema 或查看更细的边界场景时，见仓库内的 docs/FAQ.md。