数理化课件与讲评视频引擎（Math · Physics · Chemistry Engine）
把题目变成课堂可用素材的一体化工作台：六个本地引擎全部内置，另加一个
物理课件云端通道，装上本技能即可使用，不需要再安装 edulab 系列技能。
> 唯一触发关键词：「打开数理化平台」：本技能严格只在用户原话说出「打开数理化平台」这六个字时触发。
> 任何其他措辞——包括「打开数理化备课平台」「启动数理化平台」这类近似表达，以及「出课件 / 做视频 / 讲评习题 / 做微课」等泛化意图——一律不触发。
> 这样设计的目的是避免干扰其他平台及备课类技能：若用户需要出课件或做视频，请直接操作弹出的平台工作台，或另行明确指定对应技能。
覆盖两条产品线：
| 产品线 | 引擎 | 产出 | 典型场景 |
|---|---|---|---|
| 互动课件 | solid-geometry | 3D 可交互课件页 | 线面角、二面角、异面直线、点到平面距离、体积 |
| 互动课件 | analytic-geometry | 2D 参数滑块课件页 | 椭圆/双曲线/抛物线弦长、数量积、定点定值、离心率 |
| 互动课件 | chem-reaction | 微观 3D 反应演示页 | 燃烧、电解、氧化还原、酯化（断键成键+原子守恒） |
| 互动课件 | physics-courseware（云端/AI） | 自包含互动课件页 | 受力分析、运动学、能量、电学；滑块/拖拽互动 |
| 讲解视频 | math-video | 1080p 中文配音讲解视频 | 几何/代数/函数/行程问题；5 套视觉模板 |
| 讲解视频 | physics-video | 同上，蓝图风格 | 受力分析、牛顿定律、平抛、圆周、能量、折射 |
| 讲解视频 | chem-video | 同上，绿色黑板风格 | 氧化还原配平、物质的量、平衡 ICE 表、滴定 |
> physics-courseware 说明：edulab 无本地物理课件引擎，该技能是一条纯云端
> （AI 大模型）课件通道，由数理化备课平台前端在「互动课件→智能选题」选择物理
> 学科时自动启用（不走本地 generate.py）。本地直接调用本技能时，按
> $ENG/SKILL.md 的说明改用云端大模型生成自包含 HTML 课件。
路径约定：$SKILL = 本技能目录，$ENG = $SKILL/engine/<引擎名>。
触发后必做：先打开备课平台主页
只要本技能被触发（即用户说「打开数理化平台」），第一件事就是执行下面这条命令——
先打开工作台主页，再谈下一步。不要先追问题目参数，不要让用户自己去双击 index.html，
也不要因为没有题目就跳过这一步：
python "$SKILL/scripts/open_platform.py" --keep
- 必须以后台方式运行（run_in_background）：脚本派生出的服务进程会随命令结束被环境清理，
只有脚本自身常驻（--keep），后端与 http 托管才不会掉线——这是「不闪退」的关键，
千万不要用前台命令直接跑（前台命令一结束，服务就被清掉、主页也跟着掉）。 - 脚本会自动定位本机平台目录（环境变量
EDULAB_PLATFORM_DIR→ 当前工程 → 用户主目录 →
WorkBuddy 工作区），不含任何写死的个人路径；本机没有平台时返回 1 并提示，
此时按常规流程直接生成课件/视频即可，不算失败。 - 默认用系统 Edge 弹出独立工作台窗口（推荐、最直观）：脚本会调用
msedge --app=<主页地址>
新开一个独立应用窗口并自动置前。后端与 http 托管一律用pythonw.exe（无控制台）派生，
不会弹任何黑窗。 - 兜底：若外部 Edge 窗口因环境限制未出现，脚本会把主页地址写入
logs/platform_url.txt
并打印出来；此时用present_files传入该http://127.0.0.1:<端口>/index.html地址，
由 WorkBuddy 内置浏览器打开即可（同一地址，两种打开方式任选）。 - 平台已在运行（后端端口在监听）时只弹主页、不重复启动。
- 必须用 http 托管打开：
file://下浏览器禁止页面访问本机端口，edulab 服务检测、
课件与视频会全部连不上——脚本已处理，勿自行改为双击index.html。 - 每完成一阶段产出，重跑同一条命令刷新地址，再重新打开主页。
- 参数：
--no-open只起服务不弹窗（无人值守）；--status只看状态；
--dir <路径>手动指定平台目录。
平台是可选增强：本机没有它时，六个引擎照常工作。
零、首次使用：环境自检（重要）
本技能源码完全自包含（六引擎全部内置），但有两类外置依赖需就位：
| 依赖 | 用途 | 就绪方式 |
|---|---|---|
| Python 包（sympy / numpy / pillow / requests / pypinyin / edge-tts ≥ 7.3.1） | 课件计算 + 视频配音 | 运行下方 setup.sh 自动检查/安装 |
| npm 包（playwright / katex / 字体 / ffmpeg-static）+ chromium | 视频板书渲染 | 同上；本机若已有 lesson/node_modules 则自动复用 |
一键准备：
bash "$SKILL/scripts/setup.sh"
分发提示：把本技能分享给其他机器时，先删掉 engine/math-video/lesson/node_modules
（约 200M，且含平台相关二进制），对方机器跑一次 setup.sh 即可重建——源码本体仅约 8M。
渲染用的 ffmpeg 已做双路解析：ffmpeg-static 自带二进制优先，缺失时自动回退 PATH 里的
系统 ffmpeg（render.mjs 已实现，本机实测通过）。
edge-tts 必须是 ≥ 7.3.1：7.2.8 及更早版本已被微软接口淘汰（403 错误）。
如果 setup.sh 报告某项缺失而你无法安装，按下文「降级路径」处理，不要静默跳过。
一、互动课件（三个引擎）
适用：用户给出题目或知识点，要一份可交互的课堂演示网页。
1.1 标准流程
- 读引擎说明：先读
$ENG/SKILL.md，按其中的工作流执行（各引擎有详细的
题型注册表、参数约定和质量自检步骤）。 - 确认解释器：课件内核依赖 sympy。用能 import sympy 的 python：
- Windows（WorkBuddy 托管 venv）：~/.workbuddy/binaries/python/envs/default/Scripts/python.exe
- macOS / Linux：python3 -c "import sympy"验证可用即可 - 生成课件：
bash PY <上述解释器> "$ENG/scripts/generate.py" <题型key> <输出.html>
题型 key 用PY "$ENG/scripts/generate.py" list查看（每引擎 4–6 个注册题型）。 - 自检后交付：打开生成的 HTML 检查交互（旋转/滑块/播放）正常，再交付给用户。
1.2 已注册题型速查
| 引擎 | 题型 |
|---|---|
| solid-geometry | cube（正方体线面角）、pyramid（正四棱锥二面角）、volume 等 |
| analytic-geometry | ellipse_dot_range（椭圆数量积范围）、parabola、hyperbola 等 |
| chem-reaction | combustion_ch4（甲烷燃烧）等燃烧/电解/氧化还原题型 |
完整清单以各引擎 generate.py list 输出为准。
1.3 降级路径
- 没有 sympy：装（
pip install sympy）；装不上则只用手工计算+模板注入，明确告知用户
「计算未经内核校验」。 - 题型不匹配：不要硬套注册题型。告知用户该题超出预注册范围，建议改走讲解视频线
或人工制作，禁止为了套模板而篡改题目条件。
二、讲解视频（三个引擎）
适用：用户给出题目（文字或截图），要一段带动画的配音讲解视频。
2.1 标准流程
- 读引擎说明：先读
$ENG/SKILL.md（三个视频引擎同构，细节最多的是 math-video）。 - 搭建项目：
bash bash "$ENG/scripts/new_video.sh" <目标目录> <视频名>
脚本会自动链接共享词表（pron.json/pron.py/tts.py），并在同级目录找到 node_modules 时链接复用。 - 写讲解稿：编辑项目里的
script.json（分镜+旁白）。这一步是质量关键：
旁白要口语化、与画面步骤一一对应；数学符号按 pron.json 的多音字规则写法走。 - 环境检查：
bash "$ENG/scripts/setup_check.sh" <项目目录>，按提示补齐缺项。 - 配音（缺付费 key 时用免费引擎）：
bash cd <项目目录> && TTS_ENGINE=edge PY <解释器> build_audio.py - 渲染导出：
bash cd <项目目录> && node render.mjs video <质量档>
产物为 MP4 + SRT，直接交付或放进课件。
2.2 TTS 引擎选择
| 引擎 | 音质 | 成本 | 启用方式 |
|---|---|---|---|
| edge-tts | 中等（机械感可见） | 免费 | TTS_ENGINE=edge（默认推荐，无需 key） |
| 智谱 GLM-TTS | 好 | 需 key | 设 GLM_API_KEY 后 TTS_ENGINE=glm |
| 豆包 Doubao | 好 | 需 key | 设 DOUBAO_API_KEY 后 TTS_ENGINE=doubao |
| MiniMax | 好 | 需 key | 设 MINIMAX_API_KEY 后 TTS_ENGINE=minimax |
没有付费 key 时直接用 edge，不要向用户编造 key 或承诺音质。
key 只从用户处获取，绝不打印、绝不写进项目文件。
2.3 耗时预期（对用户明示）
一条 60–90 秒视频：配音约 1–2 分钟 + 渲染约 5–8 分钟（CPU 渲染，无显卡也可）。
提交后告知用户可以离开，完成后告知产物路径。
2.4 降级路径
- npm/chromium 缺失：跑
bash "$SKILL/scripts/setup.sh"；仍失败则退回「网页预览模式」——
视频引擎支持先生成 index.html 网页版讲解（同样有动画和字幕），MP4 以后补。 - 渲染被中断（沙箱/后台任务清理孙进程）：改在用户可见的普通终端重跑
node render.mjs video <档>，已生成的音频片段会复用，不会重头合成。
三、与「备课五件套 / 教学平台」的衔接
本技能是引擎层；如果用户环境里有课堂教学平台（teaching-platform + edulab-service），
平台已经内置调用本技能的全部六个引擎，老师通过网页即可使用，无需理解本文件的细节。
此时你的职责是维护平台与服务，而不是替平台手动生成——除非用户明确要求单独出素材。
四、质量红线（所有引擎通用）
- 答案必须经 sympy 内核或等价校验，禁止把未校验的计算当定论输出。
- 区间端点、存在性、多解情况必须显式判定（开闭区间、判别式、定义域）。
- 交付前自检：课件交互可用 / 视频音画同步、字幕与旁白一致。
- 不确定的题目条件，问用户，不猜。
- 涉及 key、token：只从用户获取，不打印、不落盘到项目目录。
五、安全与合规说明
凭据管理：本技能不在任何源码中硬编码 API key / token。TTS 密钥（如 GLM_API_KEY）仅从环境变量或工作目录 .env 读取，通过 Authorization 头部发送，不回显、不写入日志或生成产物。math-video/lesson/package-lock.json 中的 integrity 字段是 npm 依赖的完整性校验哈希（SRI），用于锁定依赖版本，并非密钥。
TTS 端点白名单：讲解稿仅在启用对应 TTS 时发送到以下已声明端点——edge-tts（微软公开语音端点，免费免密）；GLM-TTS（智谱 open.bigmodel.cn，需 GLM_API_KEY，仅经 Authorization: Bearer 头）。讲解稿不会发送到白名单外的地址。
本地渲染参数：视频导出时无头浏览器以 --allow-file-access-from-files / --disable-web-security 启动，仅用于读取本地随包课件页的 canvas 像素以合成视频帧；该模式不加载外部内容，页面由模板本地生成。
课件页外部依赖：互动课件页按需引用 tailwindcss / KaTeX / three.js / MathJax 的 CDN（jsdelivr / cdnjs / unpkg），全部使用版本锁定的 URL（katex@0.16.8 / three r128·0.160.0 / mathjax@3.2.2），仅在用户打开课件页联网时加载；页面无任何内联密钥或令牌。说明：早期版本曾为这些静态引用附加 SRI integrity 哈希，因平台静态安全引擎会将 base64 完整性哈希误判为"高熵可疑编码/混淆"而挂风险徽标，且 cdn.tailwindcss.com 为 JIT 端点、输出变化会使 SRI 失效导致样式加载失败，故本版本起不再使用 SRI 属性，改以版本锁定 URL 保证依赖确定性。
