Imported from XuGuanghaiGoogle/interactive-diagram-html (
skills/interactive-diagram-html/SKILL.md). Install upstream withnpx skills add XuGuanghaiGoogle/interactive-diagram-html --skill interactive-diagram-html. Copyright stays with the author.
交互式图解 HTML
把设计或计划做成一份可以直接发给评审者的单文件 HTML：图上每个方块都能点开，在右侧看到作用、功能要点、输入输出和阶段范围，图下附一览表和说明卡片。
结构上分成两部分：引擎固定、数据可变。交互行为都写在 assets/engine.html 里，已经调试好；每次任务只写一份数据 JSON，交给 scripts/build.mjs 校验后注入引擎。这样能保证每次生成的交互都一致，而方块重叠、连线穿过方块、ID 写错这类布局问题，脚本会直接指出来，不需要靠人眼去找。
适用范围
- 系统 / 环境构成图、处理流程图、开发计划（时间轴 + 泳道 + 里程碑）、业务流程（泳道）、组织体制图、迁移计划、路线图等。
- 需要"图 + 逐项说明 + 一览表"合在一份文件里，给评审或交接用的场景。
不适用：只要一张静态图片（直接用 mermaid 等更快）；数据图表（柱状图、折线图）；幻灯片；多人同时在线编辑的白板。
前置条件
Node.js ≥ 18，不需要安装任何 npm 包。下文中的 $SKILL 指本 skill 所在目录，也就是加载时提示的 Base directory。
工作流程
1. 确认场景（第一轮提问）
如果有 AskUserQuestion 工具，就用它把问题一次问完；没有的话，就用一条简短的消息列出选项。用户已经说明的内容不要再问。
- 场景：系统 / 环境构成图、处理流程图、开发计划、业务流程（泳道）、组织体制图、其他
- 页面语言：日语、中文或英语。默认跟随用户对话时用的语言；如果用户已有同类文档，优先沿用那些文档的语言
- 阶段范围：是否需要标出 M0 / PoC、P0 / P1、MVP 这类范围，并提供开关
- 素材：已有的文档、drawio、表格或代码仓库路径。有素材就先读，读得到的内容不要再问用户
确认场景后，读 references/scenarios.md 里对应的那一节。那里给出了该场景推荐的布局类型、分组、节点类别、面板字段、表格和卡片，还有第二轮要问的问题。
2. 收集内容（第二轮提问）
按场景给出的问题清单提问，每轮最多 4 个问题，只问那些会实质改变图的内容。信息不足、但有合理默认值的地方，直接采用默认值，并在大纲里标出来。
3. 先给大纲，用户确认后再画
用简短的列表给出以下内容，请用户确认或修改：
- 分组（容器或泳道）
- 节点清单：按分组列出，每个节点一行，写名称、一句话作用和阶段
- 主要连线，以及它们表示什么（数据流、依赖或调用）
- 表格和说明卡片的标题
这样做是因为改大纲只需几秒，而改一张已经排好坐标的图，往往要把整张图重排一遍。
4. 写数据 JSON
- 文件放在输出 HTML 的同一目录，命名为
<名称>.data.json，保留下来，方便以后修改。 - 字段说明见 references/data-schema.md，坐标和走线的写法见 references/layout-guide.md。
- 从
assets/examples/里最接近的示例改起：dev-plan.json是时间轴型，system-architecture.json是容器型。
右侧面板是评审时真正会被逐条阅读的部分，内容要写到能直接用于评审的程度：
- role：1～2 句，说清这个节点负责什么、为什么需要它。
- fn：4～7 条，写到具体的配置值、判断标准或数量级。不要写"提高效率""增强安全性"这类空话。
- 职责单一：同一件事（例如权限判定、待处理队列、主数据）只由一个节点负责，其他节点引用它。设计评审最常指出的问题就是两个组件做同一件事。
- 成本和工数：只写量级，并注明需要复核，不要写成确定的数值。
- 页面文字：只用一种语言，不要中英日混杂；不要写"根据××补全""本次新增"之类的元说明。
5. 构建与校验
node "$SKILL/scripts/build.mjs" <名称>.data.json <名称>.html --strict- 脚本默认拒绝覆盖已经存在的文件。新文档请换一个文件名；只有在用户明确要更新本次生成的文件时，才加
--force。 - 错误和警告都要修到 0 再交付。常见警告的修法，见 layout-guide.md 里的「校验警告对照」。
6. 在浏览器里确认（有浏览器工具时）
打开生成的 HTML，做三件事：点一个节点，确认右侧面板能打开；拖拽一次，确认拖拽后不会误开面板；看一眼整张图有没有文字挤在一起。如果没有浏览器工具，在报告里说明这一步没有做目视确认。
7. 报告
报告只写这几项：HTML 和 data.json 的路径、节点数和连线数、校验结果。需要用户补充的数值或未定事项，单独列出来。
修改已有的图
改 data.json，然后用 --force 重新生成同一个 HTML。只改用户指出的部分，不要借机把整张图重新排版，因为用户往往已经记住了原来的位置。
不要改引擎
不要手写或改写 engine.html 的交互代码。像平移时不能用 setPointerCapture（否则会吞掉节点的点击事件）这样的细节，都是踩过坑之后才定下来的，统一放在引擎里维护。如果需要引擎不支持的效果，先告诉用户，由用户决定是否扩展引擎。扩展时要同步修改 build.mjs 里的 route()，保证两边的走线算法一致。
