三大图谱构建技能

适用范围（先读）

• 构建单位 = 章 / 单元：本技能一次为一个章或一个教学单元产出知识+能力+问题三图及融合页。一个"单元"可横跨多个教材章（如"程序控制结构"横跨第 3/4/5 章），仍作为一个单元统一构建。
• 不做整本书：不要试图把整本书所有章节塞进一张图——节点过多、跨章关系爆炸、可读性极差，且各章能力/问题维度差异大，无法套同一模板。
• "全课程统一"仅指 ID 编码层面：章号取自整门课程大纲，是为了逐章构建时编号不冲突、未来可扩展——这是编码规划，不是"一次性做完整本书"。二者务必分清。

何时使用

• 用户是高校教师/课程设计者，要为某门课程的某一章（或某一教学单元）建设"知识图谱、能力图谱、问题图谱"及三图融合页面。
• 触发语示例："为《C语言程序设计》'程序控制结构'这一章做知识图谱/能力图谱/问题图谱""把三大图谱导出到Excel""三图融合联动""设计图谱的ID编码，避免全课程扩展冲突"。
• 不触发：单纯的思维导图、普通PPT、与课程图谱无关的通用图表；也不触发"一次性把整本书做成一张图"的需求（应拆成逐章/逐单元）。

核心原则（务必遵守）

1. 先 Excel、后 HTML：先产出图谱的 Excel（结构+ID+关系），交用户确认编号与内容；确认后再据此生成 HTML。禁止在 ID/内容未确认时直接做 HTML，否则必返工。
2. ID 全课程统一规划（仅编码层面）：编码前必须与用户敲定整门课程的"章号↔章节"映射表。章号 = 所用教材的物理章号，不是知识主题的自编号（一个主题可横跨多章，如"程序控制结构"跨第 3/4/5 章）。编号空间全局预留，绝不按样例临时编号。注意：这是为逐章构建预留编号空间，不代表一次性构建整本书——构建单位始终是章/单元。
3. 数据层与显示层分离：知识点名称在显示层统一带 ID（"K04-04 if语句"），但数据标识只存在于数据对象；绝不文本替换代码样例中的 if/for/while 等 C 保留字。
4. 单一数据源：先写一份 data.json（字段与 HTML 数据层同构，见 references/excel-spec.md），Excel 由 build_excel.py 读取、HTML 数据层由同一份数据生成。避免 kgLabel/aLabel/pInfo 等"ID→名称/信息"映射在四个 HTML 里重复手写、彼此漂移。
5. 遵循设计要求规范：单文件 Tab 切换、节点"名称+ID"、三图结构互不相同、各图筛选维度独立、问题描述情境化、融合页三角布局、图区撑满宽度、数据一致性校验——这些是用户实测确认的硬性偏好，详见 references/design-spec.md，构建前先读。

工作流概览（详见 references/workflow.md）

> 下列 9 步对应 workflow.md 的「阶段零～阶段八」（编号从 0 起）；workflow.md 另有「阶段九·重编码」属未来扩展，不计入主流程。二者只是编号起点的差异，内容一致。

1. 概念对齐：讲清三图定义、作用、价值、关系（知识是基础、能力是目标、问题是载体，形成闭环）。
2. 章号映射（仅编码规划）：列出所用教材的章节大纲，按教材物理章号分配 ch01..chNN（知识主题可跨多章，如"程序控制结构"跨第 3/4/5 章），预留编号空间，与用户确认映射表。构建仍按章/单元进行，不一次性做全书。
3. ID 编码方案：前缀 K/C/P + 2位章号 + "-" + 2位序号（如 K03-01）。详见 references/id-coding.md。
4. 编数据：知识/能力/问题三类 + 知识点间关系（结构+语义）。
5. 生成 Excel（scripts/build_excel.py）→ 交用户确认，未确认不进 HTML。
6. 确认后生成 HTML：优先写脚本从 data.json 生成（单一数据源，避免四文件手改漂移）；仅在无生成器时才复制 assets/templates/ 四份作参考实现并替换数据数组（见 workflow.md 阶段五）。名称带 ID，知识图加"关联问题"、能力图问题点带文字描述、四图加切换导航。
7. 动效增强：glow / pulseStroke / flow（流光连线）/ breathe，加打印安全与 reduced-motion。
8. 跨图跳转：单文件方案用 Tab 按钮 + chip 的 jumpTo(gtype,id) 同页切换并定位（chip 的 tab 参数必传，见 lessons-learned #29）；四文件降级方案用 URL 参数 ?node= / ?ability= / ?problem= 自动高亮。
9. 验收（三层，缺一不可）：① vm.Script 语法校验 + 遗留旧 ID 扫描 + getElementById 引用完整性；② jsdom 无头冒烟（脚本见 assets/examples/array-chapter/smoke_test.js）：断言四图 .node 数 == 数据节点总数、模拟节点点击 + 跨图 chip 跳转、断言跳转后激活页正确且面板非空、零运行时错误；③ 真实浏览器（agent-browser / playwright）截图 + 断言关键 SVG getBoundingClientRect().width/height > 0 —— jsdom 只查 DOM 存在性，查不出 width=0 这种纯渲染 bug（详见 lessons-learned #25）。

ID 编码方案（要点，详见 references/id-coding.md）

• 命名空间：K=知识 / C=能力 / P=问题。
• 格式：前缀 + 2位章号 + "-" + 2位序号，例 K03-01 C03-01 P03-11。
• 章号 00 = 跨章/通用项；章号来自全课程大纲，非样例临时号。

经验教训要点（详见 references/lessons-learned.md）

• ID 同步禁止文本替换 if/for/while 等 C 保留字 → 只改数据层标识（用 sync_ids.js）。
• 边端点正则须加 \b 且恢复 cat 字段（root/seq/sel/loop 是"程序控制结构"样例分类，每章自定，如"数组"章用 root/oned/twod/charstr/parr/sortfind/adv；cat 用于配色筛选，不可改）。
• 点击无响应：变暗节点勿设 pointer-events:none，改在效果层 fxLayer/crossLayer 关闭。
• 动画需 @media print 与 prefers-reduced-motion 降级。
• 中文路径用 Git Bash，PowerShell 会乱码。
• 从 HTML 提取数据用 acorn 时，从 nodes 数组取，勿取动态构建的 N。
• Excel 必须有«知识关联»层；能力图问题点带文字描述；知识图加"关联问题"。
• 融合页用三角布局（知识顶/能力左下/问题右下 + 分色贝塞尔跨组边 + 组内边可隐藏），勿用三栏并列（详见 design-spec.md 与 lessons-learned #26）。
• 生成器坐标字典必须覆盖全部节点 ID，遗漏即渲染中断（#24）；改 DOM 元素 ID 必须同步改 CSS 选择器（#25）。
• 跨图 chip 的 jumpTo tab 参数必须齐全，漏传会生成 jumpTo('undefined',id) 导致所有页面被隐藏（比"无反应"更糟，见 #26 之后）。
• f-string 内嵌 JS：大段花括号 JS 抽成 r'''...''' 常量 + {VAR} 占位；src.index(marker) 定位替换须限定搜索起点，否则误删模板主体（#28）。
• jsdom 冒烟测不出 width=0 的渲染 bug，交付前必须真实浏览器截图断言 SVG 尺寸 > 0（#25）。

Excel 规范（要点，详见 references/excel-spec.md）

六表：说明 / 知识图谱 / 知识关联 / 能力图谱 / 问题图谱 / 映射矩阵。«知识关联»单列（结构关系蓝 + 语义关系橙）。

资源

• scripts/gen_three_graphs.py：通用一体化生成器（正式工具）——读一份 data.json 自动生成单文件四 Tab HTML（知识/能力/问题/融合三角布局）。零硬编码：cat/bloom/level 配色、坐标布局、能力递进边、问题进阶边、toolbar 按钮全部自动推断；缺失字段（sample/rubric/hint/errs/level）优雅降级。用法 python gen_three_graphs.py [data.json] [输出.html]。
• scripts/build_excel.py：从结构化 JSON 生成六表 Excel（依赖 openpyxl）。
• scripts/check_data.py：反向字段一致性校验（kids↔abilities / needs↔problems / trains↔pids），交付前必跑。
• scripts/smoke_generic.js：通用 jsdom 冒烟测试（用法 node smoke_generic.js <html> <K数> <C数> <P数>）。
• scripts/sync_ids.js：HTML 数据层 ID 升级（幂等、避开 C 保留字、恢复 cat；仅用于"复制模板"老路径）。
• assets/templates/：四份参考实现 HTML（knowledge/competency/problem/fusion），内含"程序控制结构"样例数据，复用须按 workflow.md 阶段五替换数据层。
• assets/examples/array-chapter/：数组章完整样例（data.json 含 catName/ability_edges/problem_adv 扩展字段 + generate_html.py 旧版数组章专用生成器 + smoke_test.js）。新章节不必照抄此样例，直接用 gen_three_graphs.py 即可；本目录仅作 data.json 完整字段的 schema 参考。
• references/：workflow.md、id-coding.md、lessons-learned.md、excel-spec.md、design-spec.md（设计要求与用户偏好）。

> data.json 扩展字段（均可选，不提供也能跑，gen_three_graphs.py 自动降级）：meta.catName（cat 值→中文名，缺省用 cat 值本身）、ability_edges（能力递进边，缺省按 bloom 层级自动递进）、problem_adv（问题进阶边，缺省按难度层级自动递进）。详见 excel-spec.md 的 schema 说明。

快速开始

1. 与用户确认"章号↔教材章节"映射表（全课程统一，章号=教材物理章号；此为编码规划，构建单位为章/单元）。
2. 按 references/excel-spec.md 的 JSON schema 编写数据文件 data.json（单一数据源；可加 meta.catName/ability_edges/problem_adv 扩展字段）。
3. 运行 check_data.py data.json 校验反向字段一致性（= 0 方可继续），再运行 build_excel.py data.json 生成 Excel，交用户确认 ID 与内容。
4. 确认后：运行 gen_three_graphs.py data.json 生成单文件四 Tab HTML（零硬编码，无需改生成器）；仅当需要特殊定制布局时才参考 assets/examples/array-chapter/generate_html.py 或 assets/templates/ 手工改。
5. 三层验收（见工作流概览第 9 步 / workflow.md 阶段八）：静态校验 + jsdom 冒烟（smoke_generic.js）+ 真实浏览器截图断言 SVG 尺寸 > 0。

过拟合替换点（仅"复制模板/样例手工改"老路径需要，缺一不可）

gen_three_graphs.py 已零硬编码，无需任何替换。仅当退回老路径（复制 assets/templates/ 或改 generate_html.py）时，才需替换：title/文件名与跳转链接、数据层数组与派生映射、cat 配色图例、sync_ids.js 的 IDMAP·FILES。唯一出处是 references/workflow.md「阶段五·过拟合替换点」，此处不重复罗列，避免两处漂移。核心提醒：派生映射（kgLabel/aLabel/pInfo/pByAbility）能由 data.json 生成就不要手写。