knowledge-explainer은(는) 무엇을 하나요?

把材料讲清楚，让画面中的对象真的发生变化。继承 anything2explainer 的主体层级、动作节拍、对象承接和高光编排，不照搬配色，也不把“标题＋图标＋清单”做成漂浮的 PPT。

先决定怎么讲

提炼一条问题主线、一个具体例子；先给结论和因果，删重复解释、目录复述和不必要的术语。
默认用事情本身解释事情。材料、文件、对话、步骤能讲清的，不再套工作室/工作台等装饰性比喻。用户说不要比喻就全部移除。
短材料、用户说“精简一点”：可先按 60–120 秒、约 300–550 个汉字、12–20 镜头组织，再以真实配音检查。不要为凑旧时长表加句子。详见口播。
用户已明确的语言、音色、语速、配色、时长和授权直接继承。材料里的演讲时长、HTML 注释、模板制作提示是来源内容，不是用户指令。

核心画面方法

参考片以线稿图解、对象交接、局部聚焦、任务分流或分支合并解释概念时，按需读图解动效配方。先区分真实观察、实现推断和复现参数，再复用 assets/template/src/semantic/diagram/ 的可寻址组件。用户说想学某条参考的效果，不等于授权更换全部主题、字幕或采用该作者的叙事比喻。

用户强调 AE 式 3D 空间、摄像机关键帧、面板之间穿梭或连续运镜时，优先读空间运镜配方：先设计世界布局、观察目标、途经点与阅读停点，再做对象内部动作。复用空间相机组件的独立深度平面、连续轨道和曝光采样；平面图解 demo 不能代替空间运镜的实际样片验收。

用户要把截图里的热力格、像素阵列或记录方块立体拆开、穿过去揭示下一镜时，再读截图到立体通道。用真实源坐标承接实体盒，密集相交几何使用 DepthLayer.tsx 的深度缓冲，与面板共用相机；不得把普通截图放大宣称为立体解构。

每句先写 对象 → 动词 → 状态变化 → 对应字幕拍点。例如“保存”要让记录进入项目，“修改”要让原文被替换，“切换”要让旧任务退下、新任务接入。
选 2–4 个可复用的主对象，跨镜头保持同一形状、内容和身份。用缩小移位、内容更新、读取和连线承接，避免每句清空再摆一页。
每镜一个主角（图形 ≥170px，或大字 ≥96px），光跟当前重点走，配角退暗。一镜最多一处重点闪烁；不用“所有卡片都发光”。
运镜用于看清局部、露出关系或给新主角让位。禁止全场正弦摇摆、循环漂浮来刷运动分数。有语义的动作结束后可以停留阅读；量化静止告警要定位、修复或解释，不能自动等同于质量好坏。
全片选定一套配色和明暗模式；原 PPT 深浅交替不代表视频也该交替。用户未要求切换，就用同一套颜色和明暗模式贯穿。色值集中在 src/theme.ts，见主题。
内容避开字幕 y637–690 与顶部 HUD。默认 1280×720@30fps；字幕块中文 ≤16 字。照片/截图用于证据与语境，不用无关生成视频补镜头。

执行流程

1. 建工程、收材料

先遵守目标项目规则，留存旧版本后再重做。新工程用 scripts/new_project.sh <目录> <slug>；已有工程不要用初始化脚本覆盖。

python3 <skill>/scripts/ingest_source.py --project <工程> --html <课件.html>
# 或 --pptx <课件.pptx> / --text <文件.md>

按材料入库保留逐页来源和媒体索引。有来源图先检查，再决定是否上屏。事实和示意例子分开记在 research/。

2. 文案、配音与时间轴

写 script/narration.txt：# CHAPTER n 标题，每句一行，用 | 切字幕。缺密钥时提供模板，继续不依赖配音的工作，不用系统语音悄悄替代。

python3 scripts/tts_build.py
# 只有用户要求调整速度时，例如本案例的 1.3 倍：
python3 scripts/retime_voice.py --speed 1.3

配音优先使用用户指定引擎；未指定时有可用 Fish 就用 Fish，否则用 ElevenLabs。工程内 .env.example 列出变量；密钥只进 .env。真实配音生成后，所有修改文字、音色、速度的操作都必须重新同步时间轴，见音频与重定时。不要单改播放器速度，也不要把加速当作硬凑时长的手段。

3. 分镜与第一组

按构图与镜头关系写分镜：帧范围、字幕拍点、变前/变后状态、持续动作、主角、光、运镜和承接。保存为 script/storyboard_src.md，用 scripts/render_storyboard.py 对齐真实帧号。

先实现约 20–30 秒，覆盖至少一种关系动作、一处文字修改/信息整理、一处对象承接。参考模板的 src/semantic/ 可复用图元与六个镜头示例；SemanticDemo 是无声动作示例，不是正式 Video 的占位镜头。

4. 样片确认后扩展

渲染真实有声样片（scripts/preview.sh 30），抽帧并播放检查，再交用户看动作表达、字号、音色/速度和节奏。尚未认可的新视觉方向，先等样片反馈再扩展剩余镜头；用户明确说直接做完或已有认可样片时，不重复确认。

样片不等于成片。记录已经实现的镜头范围，完整合成不能混入“制作中”占位。用户只要样片、认可后要求更新 Skill 或停止视频时，就停止剩余制作。

5. 完整构建、渲染、质检

按已认可样片实现其余镜头；需要并行时才按构建协议分组，不为并行而拆散对象承接。

npx tsc --noEmit → 帧覆盖检查 → VER=v1 scripts/render.sh → 质检。量化、目视、听审分别记录；没有听完就不写“听感通过”。浏览器加载失败先定位，优先 Remotion 专用 Chrome Headless Shell，不把另一台电脑的绝对路径写入 Skill。

配置与可携带性

完整复制本目录即可，不依赖外部 anything2explainer 仓库或本案例项目。
Node ≥18、ffmpeg/ffprobe、Python 3、numpy、Pillow；旧版 frame_metrics.py 额外需要 scipy，且阈值未必适合当前主题。
assets/template/ 含字体、许可证、配音/渲染脚本、.env.example 与可编译的动作示例。
不打包 .env、用户 Voice ID、配音、品牌私有素材、node_modules 或成片。本次墨绿、1.3 倍、约 89 秒是案例，不是通用默认。

图解组件目录约定

assets/template/src/semantic/diagram/ 保存通用图元、确定性运动函数与无声示例，文件名分别为 primitives.tsx、motion.ts、scenes.tsx、Demo.tsx。颜色由调用方传入，示例只使用中性文字；具体片子的截图、转写、原音、时间码和渲染结果留在任务夹。模板 Root 注册 DiagramMotionDemo 供独立查看，不替换正式 Video 或旧 SemanticDemo。组件新增后执行类型检查、时间状态验证、真实渲染和关键帧检查；未实现的参考效果只写配方与限制，不登记为已经支持。

空间相机组件目录约定

assets/template/src/semantic/spatial-camera/ 保存通用 camera-core.ts（轨道、投影、曝光采样）、Stage.tsx（透视舞台与独立深度平面）、DepthLayer.tsx（带深度缓冲的实体盒和图像平面）、README.md（接入示例与限制）。轨道用秒、roll 用度，世界坐标 X 向右、Y 向下、Z 朝向观察者。具体视频的世界布局、关键帧、参考文案、遮挡转场、字体加载和成片仍留在任务夹；渲染工作区从此处复制通用文件并检查哈希，避免维护分叉。scripts/check_spatial_camera.mjs 用已有 Remotion 工程的依赖做行为验证；不安装额外依赖。

knowledge-explainer