edu-3d-studio — 互动 3D 教学课件工坊
用途
把一个教学主题（如"心脏的结构""单摆运动""人体骨骼""柴油机工作原理"）做成一个双击即开的单文件 HTML 互动课件：Three.js 场景 + 教学交互层（标注 / 爆炸拆解 / 分步讲解 / 知识卡 / 参数实验 / 课堂问答）。
两条建模路线，按需选择：
| 模式A · 看图重建 | 模式B · 概念建模 | |
|---|---|---|
| 输入 | 实物/器官/仪器参考图 | 只有教学主题（无图） |
| 引擎 | vendor 的 img2threejs 管线（精简流程） | 直接程序化编写 model.js |
| 适用 | 显微镜、青蛙解剖、骨骼、机械结构 | 摆、波、电场、分子、天体等抽象概念 |
| 精度观 | 忠实于参考图，但要向用户声明"近似" | 清晰 > 逼真，教学正确性优先 |
总工作流
- 判断模式：用户给了参考图 → 模式A；只给了主题 → 模式B。拿不准就问。
- 教学设计先行（不要跳过）：读
references/teaching-design.md，确定：本课知识点清单、部件划分（parts）、讲解步骤（steps）、问答题（quiz）、可调参数（params）。部件划分遵循"教学粒度"而非"物理粒度"——考试考什么就拆什么。 - 写 lesson.json：schema 见
references/lesson-spec.md。 - 建模：
- 模式B：手写model.js（契约见references/lesson-spec.md；学科套路见references/subject-playbooks.md）。
- 模式A：按references/mode-a-pipeline.md驱动vendor/img2threejs/forge/管线生成模型代码，再把生成的工厂函数改写成 model.js 契约（通常是把 TS 类型去掉、函数名改为buildModel、给每个教学部件补userData.partId）。 - 组装：
bash python scripts/assemble_lesson.py --lesson lesson.json --model model.js --out "<输出路径>.html"
先用--check只校验。脚本仅依赖 Python 3.10+ 标准库。Windows 上传参用D:\...风格绝对路径（脚本已兼容 Git Bash 的/d/...，但 Windows 风格最稳）。 - 验证（必须做）：
- 语法：提取<script type="module">内容存为 .mjs，node --check。
- 运行时：用 Chrome/Edge 无头截图自查（模板支持 URL 深链直接复现状态）：
chrome --headless=new --disable-gpu --window-size=1400,900 --virtual-time-budget=9000 \ --screenshot="< out>.png" "file:///<课件绝对路径>#labels=1&explode=0.8"
至少验证三张图：默认视角、#labels=1&explode=0.8（标注+拆解）、#step=2（分步+高亮+镜头）。截图后用视觉能力亲自看：模型是否可辨认、标注是否对齐、部件是否飞出画面。 - 交付：
present_files把 HTML 呈现给用户，并附上"教师核对清单"（见下）。
硬性规则
- 准确性命门：医学/生物内容必须在交付时明确提醒"AI 生成、近似表达，关键结构请教师核对"。课件底部已内置免责声明，不要删。涉及考点级事实（如"左心室壁最厚"）宁可保守，写进 narration 前再自查一遍。
- 性能预算：教室设备弱。总三角形 ≤ 60k（球体分段 24~36 足够），不开阴影，
devicePixelRatio已限 2。单文件 HTML，Three.js 走 CDN（模板内置 jsdelivr/unpack/npmmirror 三源回退），首次打开需联网。 - partId 一致性：lesson.json 的 parts / steps.highlight / quiz.answer 引用的 id，必须能在 model.js 里通过
userData.partId找到——assemble_lesson.py 会校验，0 告警才交付。 - 不要重造交互层：所有交互都在
assets/edu-template/lesson-template.html里实现好了。课件个性化的正当方式是改 lesson.json 和 model.js；确需改模板时保持占位符__LESSON_TITLE__/__LESSON_DATA__/__MODEL_CODE__完整。 - 多 CDN 与离线：若用户明确要完全离线（教室无网），把 three.module.js 下载到本地并在模板里改成相对路径引用，课件变成"HTML + three.module.js 同目录分发"，向用户说明。
资源地图
| 路径 | 作用 |
|---|---|
assets/edu-template/lesson-template.html |
课件模板（交互层全部在此） |
scripts/assemble_lesson.py |
校验 + 组装单文件 HTML |
references/lesson-spec.md |
lesson.json schema + model.js 契约（写代码前必读） |
references/teaching-design.md |
教学设计原则：知识点拆解、步骤编排、问答设计、教师核对清单 |
references/subject-playbooks.md |
物理/生物/医学/化学建模套路与禁区 |
references/mode-a-pipeline.md |
模式A 精简管线操作手册（img2threejs 的教学版用法） |
assets/examples/heart/ |
完整示例：心脏课件（lesson.json + model.js），可直接模仿 |
vendor/img2threejs/ |
img2threejs v1.4.4 管线与知识库（Apache-2.0，见 NOTICE.md），其原生用法见 vendor/img2threejs/README.md 与 grimoire/ |
模式选择的诚实边界
- 模式A 重建的是"图里那个东西"，单图看不到的面靠推断，要在交付时说明哪些面是推断的。
- 模式B 做的是"教学示意模型"，不是科学仿真。参数动画（如心率、重力）只需定性正确；用户要求定量精确时，把公式写进 model.js 的 onTick 并在 narration 里写明公式来源。
- "这个主题不适合做 3D" 是合法结论（如纯符号推导内容），此时建议改用 2D 图示或文字讲解，不要硬做。
