全学段理工科三维课程资源开发
目标
将一个具体课时或认知难点转化为学生可操作、可观察、可判断、可回看的课程资源。先建立教学与科学契约，再实现二维、三维或混合场景，最后完成科学、交互、移动端和可访问性验收。
核心原则
- 优先服务认知难点，不以“炫酷、沉浸式”替代教学目标。
- 优先保证公式、单位、方向、场所、物质变化和操作顺序正确，再处理视觉效果。
- 将教学规则实现为程序约束，不只写在说明文字中。
- 使用单一状态驱动场景、读数、公式、步骤和讲解，避免各自更新。
- 仅在空间关系、立体结构或操作过程确有价值时使用三维；符号推导优先采用 SVG 或二维混合表达。
- 区分定量仿真、教学示意动画和演示读数，不将简化模型包装为真实预测。
- 为三维热点提供 DOM 按钮等替代入口，为核心内容提供静态降级。
工作流
1. 限定课时与认知难点
读取 references/pedagogy.md，从教材、课标、教案和用户说明中提取：
- 学段、学科、课时、目标学生与先备知识。
- 一个核心难点及对应的空间位置、操作动作或可测量量。
- 学习目标、非目标、课堂使用方式和交付限制。
优先从已有材料补全信息。仅询问会显著改变科学内容或交付结果的缺失项；采用合理假设时，在课程契约中明示。
将范围控制在一个课时或一个关键难点。排除纯版式美化、纯文字推理和缺少后续因果作用的环节。
2. 建立科学约束清单
在编码前列出：
- 必须成立的事实、公式、单位、数值范围、反应条件、结构和方向。
- 学生典型误解及禁止出现的表述。
- 强制操作顺序、安全要求和真实实验边界。
- 理想化、比例简化、演示数值及非定量部分。
- 可用于核对结果的教材依据、教师审核意见或数值金标准。
不得编造公式、教材结论或实验安全规范。资料不足且无法可靠判断时，先请求教师确认。
3. 拆分学生动作并选择原型
将内容拆成“学生做什么、观察什么、判断什么”的步骤。每一步只承担一个主要动作或一个可观察变化；明确依赖、跳步反馈、完成条件和回看方式。
| 教学特征 | 选择原型 | 推荐表达 |
|---|---|---|
| 调参后公式、读数、方向或拓扑联动 | 参数探索型 parameter-exploration |
三维/二维混合 |
| 规范操作顺序和错误反馈重要 | 流程实验型 procedure-experiment |
三维状态机 |
| 结构观察与场所、物质、能量过程重要 | 结构过程型 structure-process |
三维结构 + 过程演员 |
| 符号、参考方向、公式推导重要 | 符号推导型 symbolic-derivation |
SVG/二维混合 |
说明三维是否必要。三维非必要时，不强行增加三维场景。
4. 先完成课程契约
参考 assets/course-contract.example.json 创建课例自己的 JSON 契约。至少包含学习目标、科学事实、误解、模型边界、步骤、依赖和验收用例。
在生成页面前运行：
python3 scripts/validate_course.py path/to/course-contract.json
从 Skill 所在目录运行，或将命令中的脚本路径替换为绝对路径。修正全部契约错误后再进入实现。不得把示例中的学科知识、步骤数、数值或坐标直接复制到新课例。
5. 实现数据驱动的交互资源
读取 references/technical-standards.md。需要起步骨架时复制并改造 assets/single-file-template.html。
默认采用单文件 HTML、原生 JavaScript 和固定版本 Three.js ES Module；按交付要求选择 CDN 或本地依赖。优先使用程序几何体，避免不必要的外部模型、贴图和构建链。
实现以下联动：
- 将步骤、参数、公式、读数和讲解组织为数据。
- 通过统一状态对象和统一更新入口刷新界面与场景。
- 在动作执行前检查依赖，不合法操作给出具体教学反馈。
- 让每个关键动作至少产生两类反馈，例如场景变化 + 数值变化，或步骤变化 + 讲解变化。
- 提供上一步、下一步、重置、视角复位及必要的暂停和速度控制。
- 使用会话编号或取消机制阻止重置前的延迟回调污染新状态。
- 保留公式、步骤、结构列表或静态图等无 WebGL 内容路径。
6. 按学段调整表达
依据 references/pedagogy.md 的学段适配表调整术语密度、公式深度、提示方式、任务长度和安全责任。不得将“全学段”理解为在同一页面同时堆叠所有层级内容。
7. 验收实际交付版本
读取 references/acceptance.md，至少完成：
- 科学核对：教材表述、公式、单位、视觉拓扑、物质来源去向和数值金标准。
- 交互核对：主流程、跳步、重复操作、终态、快速切换、暂停和动画中重置。
- 展示核对：桌面、窄屏、触摸、横屏、最长文本、最大读数和弹窗。
- 可访问性核对：键盘、可访问名称、焦点、非颜色提示和减弱动态效果。
- 工程核对：控制台、资源加载、后台暂停、WebGL/CDN 失败降级和场景资源释放。
不得将历史截图或旧日志当作当前版本的验收结果。发现问题后修复并重新运行受影响测试。
8. 交付课堂可用成果
按任务需要交付：
- 交互 HTML 及必要本地依赖。
- 课程契约与科学约束清单。
- 静态 SVG/截图等备用资产。
- 桌面、移动端和关键步骤验收证据。
- 测试结果、已知限制、教学简化与安全边界。
- 教师使用建议，包括投影讲解和学生自主操作方式。
需要向用户展示文件时，使用环境提供的成果展示机制。不得宣称三维模型可替代真实实验操作、工程训练或教师安全指导。
案例参考
需要理解本 Skill 的方法来源或选择交互模式时，读取 references/case-patterns.md。仅复用“电路常用元件介绍、氧气生成、光合作用”三个案例的方法，不硬编码其具体数值、步骤、品牌、配色、模型坐标或专用安全文本。
完成标准
仅在以下条件同时满足时完成：
- 核心难点与学习目标一致，表达原型选择有理由。
- 科学约束已进入内容、交互规则和验收用例。
- 课程契约校验通过。
- 场景、读数、公式和讲解由同一状态同步驱动。
- 关键流程具备错误反馈、回看、重置和替代操作。
- 当前版本验收完成，模型边界与安全说明清楚。
