通过交互式提问，把系统构成图、环境构成图、处理流程图、开发计划（含功能说明与里程碑）、业务流程、组织体制等整理成单文件交互式图解 HTML——点击方块在右侧看说明、拖拽平移与缩放、阶段范围开关、图下附一览表与说明卡片；需要时还能开启编辑模式，在浏览器里拖动方块、调整宽度、画连线并保存回数据文件。用户提到构成图、架构图、流程图、开发计划、路线图、泳道图、WBS、system / architecture diagram、構成図、フロー図、開発計画、ロードマップ，或想把设计、计划"做成能点开看说明的 HTML / 图"、"在页面上拖动调整布局"时都应使用，即使没有明说"交互式"。
Scanned 9/19/2026
Install to Claude Code
Skills Directorynpx -y skills add XuGuanghaiGoogle/interactive-diagram-html --skill interactive-diagram-html --agent claude-codeInstalls into .claude/skills of the current project.
Are you the author of Interactive Diagram Html?
Add the live security badge to your README — it updates automatically with every re-scan.
[](https://www.skillsdirectory.com/skills/xuguanghaigoogle-interactive-diagram-html)More formats (shields.io, HTML) on the badges page.
---
name: interactive-diagram-html
description: 通过交互式提问，把系统构成图、环境构成图、处理流程图、开发计划（含功能说明与里程碑）、业务流程、组织体制等整理成单文件交互式图解 HTML——点击方块在右侧看说明、拖拽平移与缩放、阶段范围开关、图下附一览表与说明卡片；需要时还能开启编辑模式，在浏览器里拖动方块、调整宽度、画连线并保存回数据文件。用户提到构成图、架构图、流程图、开发计划、路线图、泳道图、WBS、system / architecture diagram、構成図、フロー図、開発計画、ロードマップ，或想把设计、计划"做成能点开看说明的 HTML / 图"、"在页面上拖动调整布局"时都应使用，即使没有明说"交互式"。
---
# 交互式图解 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](references/scenarios.md) 里对应的那一节。那里给出了该场景推荐的布局类型、分组、节点类别、面板字段、表格和卡片，还有第二轮要问的问题。
### 2. 收集内容（第二轮提问）
按场景给出的问题清单提问，每轮最多 4 个问题，只问那些会实质改变图的内容。信息不足、但有合理默认值的地方，直接采用默认值，并在大纲里标出来。
### 3. 先给大纲，用户确认后再画
用简短的列表给出以下内容，请用户确认或修改：
- 分组（容器或泳道）
- 节点清单：按分组列出，每个节点一行，写名称、一句话作用和阶段
- 主要连线，以及它们表示什么（数据流、依赖或调用）
- 表格和说明卡片的标题
这样做是因为改大纲只需几秒，而改一张已经排好坐标的图，往往要把整张图重排一遍。
### 4. 写数据 JSON
- 文件放在输出 HTML 的同一目录，命名为 `<名称>.data.json`，保留下来，方便以后修改。
- 字段说明见 [references/data-schema.md](references/data-schema.md)，坐标和走线的写法见 [references/layout-guide.md](references/layout-guide.md)。
- 从 `assets/examples/` 里最接近的示例改起：`dev-plan.json` 是时间轴型，`system-architecture.json` 是容器型。
- 用户选了"需要编辑"：顶层加 `"editable": true`。
- 开发计划且"每一列就是一期"时：`phase.byColumn: true`（方块所在列决定所属期，拖到别的列会自动改期）；需要每期一个强调按钮时加 `phase.focusButtons: true`；需要每期工作量时加 `stats`（顶部柱形图）和 `type: "phaseSummary"` 的表，明细表的分组写 `{ "level": "第2期" }` 让它按期自动归组。
右侧面板是评审时真正会被逐条阅读的部分，内容要写到能直接用于评审的程度：
- **role**：1～2 句，说清这个节点负责什么、为什么需要它。
- **fn**：4～7 条，写到具体的配置值、判断标准或数量级。不要写"提高效率""增强安全性"这类空话。
- **职责单一**：同一件事（例如权限判定、待处理队列、主数据）只由一个节点负责，其他节点引用它。设计评审最常指出的问题就是两个组件做同一件事。
- **成本和工数**：只写量级，并注明需要复核，不要写成确定的数值。
- **页面文字**：只用一种语言，不要中英日混杂；不要写"根据××补全""本次新增"之类的元说明。
### 5. 构建与校验
```bash
node "$SKILL/scripts/build.mjs" <名称>.data.json <名称>.html --strict
```
- 脚本默认拒绝覆盖已经存在的文件。新文档请换一个文件名；只有在用户明确要更新本次生成的文件时，才加 `--force`。
- 错误和警告都要修到 0 再交付。常见警告的修法，见 layout-guide.md 里的「校验警告对照」。
### 6. 在浏览器里确认（有浏览器工具时）
打开生成的 HTML，做三件事：点一个节点，确认右侧面板能打开；拖拽一次，确认拖拽后不会误开面板；看一眼整张图有没有文字挤在一起。如果没有浏览器工具，在报告里说明这一步没有做目视确认。
开启了编辑模式时，按下一节启动本地服务，用 `http://localhost:<端口>/<名称>.html` 打开，再加做一件事：点「编辑布局」，拖动一个方块后按 Ctrl+Z 撤销，确认能动能撤。**不要点保存**，以免把测试改动写进用户的数据文件。
### 7. 报告
报告只写这几项：HTML 和 data.json 的路径、节点数和连线数、校验结果。需要用户补充的数值或未定事项，单独列出来。开启了编辑模式时，再附上启动服务的命令和打开地址。
## 编辑模式
`"editable": true` 的图在工具栏第二行多一个「编辑布局」按钮。进入编辑后：
| 操作 | 做法 |
| --- | --- |
| 移动方块 | 直接拖动，按 10px 对齐网格 |
| 调整宽度 | 鼠标移到方块上，拖右下角的蓝色小方块 |
| 画连线 | 鼠标移到方块上，从四边中点的蓝点拖到另一个方块 |
| 改连线 | 点击选中后可删除（Delete）、切换虚线 / 粗线；双击编辑标签 |
| 撤销 | Ctrl+Z |
| 保存 | 写回 `<名称>.data.json` 并重新生成 HTML，旧数据留一份 `.data.json.bak`；有校验警告时显示条数 |
保存需要通过本地服务打开页面（只监听 127.0.0.1）：
```bash
node "$SKILL/scripts/serve.mjs" <HTML 所在目录> [端口，默认 8765]
```
- 服务没开、或直接双击 HTML 打开时，点保存会改为下载 JSON，需要用户手动覆盖 data.json。
- 拖动方块后，连在它上面的线会丢掉手写的 `via` / `mx` / `my` 和标签坐标，改用自动走线。
- 用户保存后，data.json 已经变了：**之后任何修改都先重新读取 data.json，在它的基础上改**，不要用自己记忆里的旧内容覆盖。
- 发布成 Artifact 等沙箱环境时，保存与下载都会被拦截；需要编辑时请在本机打开。
## 修改已有的图
先读取当前的 data.json（用户可能在编辑模式里保存过），再改，然后用 `--force` 重新生成同一个 HTML。只改用户指出的部分，不要借机把整张图重新排版，因为用户往往已经记住了原来的位置。
## 不要改引擎
不要手写或改写 `engine.html` 的交互代码。像平移时不能用 `setPointerCapture`（否则会吞掉节点的点击事件）这样的细节，都是踩过坑之后才定下来的，统一放在引擎里维护。如果需要引擎不支持的效果，先告诉用户，由用户决定是否扩展引擎。
走线算法只在 `scripts/route-block.js` 里维护。改完运行下面两条，把它注入 engine.html 与 build.mjs，并跑完全部端口组合的回归测试：
```bash
node "$SKILL/scripts/sync-route.mjs"
node "$SKILL/scripts/test-route.mjs"
```
Is this your skill, or is something wrong with this listing? Request removal or report an issue. Author removals are honored within 72 hours.
No comments yet. Be the first to comment!
