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(),保证两边的走线算法一致。
