三图构建引擎

它在解决什么问题

把一门课做成一张大图谱，结果通常是节点上百、跨章连线爆炸，渲染出来谁也看不懂。这个技能反过来设定了一个硬约束：构建单位是章或教学单元，一次只给一章产出知识图谱、能力图谱、问题图谱，外加一个三图融合页。

同时它还堵住了另两个常见坑：ID 在每个文件里手写、四处漂移；以及数据还没确认就直接生成 HTML，导致整批返工。

核心能力

• 单一数据源：所有内容先写进一份 data.json，字段与 HTML 数据层同构。Excel 和 HTML 都从这份数据生成，不存在四份 HTML 各自维护映射表的情况。
• 先 Excel 后 HTML：build_excel.py 产出六表 Excel（说明、知识图谱、知识关联、能力图谱、问题图谱、映射矩阵），ID 与内容经用户确认后才进入 HTML 阶段。
• 全课程编码规划：ID 格式为 K/C/P + 两位章号 + - + 两位序号。章号取自教材物理章号，不是主题自编号，所以主题跨章（比如“程序控制结构”横跨第 3/4/5 章）时编码依然不冲突。这是为逐章构建预留空间，不等于一次性构建整本书。
• 一体化生成器：gen_three_graphs.py 读 data.json 自动生成单文件四 Tab HTML，配色、坐标布局、递进边、toolbar 全部推断，meta.catName、ability_edges、problem_adv 等扩展字段缺省时优雅降级，不需要改生成器代码。
• 跨图联动：单文件方案用 Tab 按钮与 chip 的 jumpTo(gtype, id) 同页定位；四文件降级方案走 URL 参数自动高亮。
• 三层验收：vm.Script 语法校验与引用完整性检查、smoke_generic.js 的 jsdom 冒烟（断言节点数、模拟点击与跳转）、真实浏览器截图并断言 SVG 尺寸大于 0。

适用边界与注意点

• 不适用于思维导图、普通 PPT 或与课程图谱无关的通用图表；也不接“整本书一次出图”的需求。
• 数据标识只存在于数据对象，显示层名称带 ID（如 K04-04 if语句），但绝不文本替换代码样例里的 if、for、while 等 C 保留字，升级 ID 用 sync_ids.js。
• 边端点正则需要加 \b，并且 cat 字段必须恢复：它用于配色筛选，每章取值不同，数组章与程序控制结构章的分类不可混用。
• 变暗的节点不要设 pointer-events: none，否则点击失效；关闭交互要放在 fxLayer、crossLayer 效果层上做。
• 生成器坐标字典必须覆盖全部节点 ID，漏一个就会中断渲染；改 DOM 元素 ID 时必须同步改 CSS 选择器。
• 跨图 chip 的 jumpTo 必须传齐 tab 参数，漏传会生成 jumpTo('undefined', id) 把所有页面隐藏，比无反应更难排查。
• 动画要带 @media print 与 prefers-reduced-motion 降级。
• 交付前 jsdom 冒烟测不出 width=0 这类纯渲染 bug，真实浏览器截图这步不能省。
• 中文路径建议在 Git Bash 下操作，PowerShell 会乱码。