古诗沉浸式网页生成

何时使用

用户给了一首古诗（至少：一个朗读 mp3 + 诗题 + 作者），希望得到一个"电影感沉浸式"播放网页：固定图舞台 + 滚动切场景 + 毛玻璃诗文卡 + 自动/可控背景乐 + 真人朗读。典型场景：小学/初中古诗课件、教资备考复习页、古诗赏析分享。

最小输入

1. 朗读音频（真实播音腔，必需）：放到 小学古诗文 音频-古诗文网/<年级>/<诗名>.mp3（按年级分目录，文件名即诗名）。跑 python sync_real_recitation.py 把它按 (年级,诗名) 自动复制到 static/poem-audio/<slug>-recitation.mp3（网页内嵌的朗读源）。禁止用 edge-tts 合成冒充真人朗读——gen_recitation.py 仅在该诗无真实音频时兜底。
2. 诗的身份：诗题 + 作者（朝代）。诗句可从知识库补全；用户贴全诗更稳。

引擎与文件（来自本技能 scripts/）

把 scripts/ 下 .py 复制到你的项目根目录（与 poems/、music/、voice/ 同级），ROOT 即脚本所在目录：
- gen_immersive.py —— 主入口（推荐）：读 poems/primary_school.json → 批量或单首生成沉浸式 HTML，并自动把 6 张 webp（hero/scene-1~4/closing）复制一份到每首诗 <题目>/images/（便于单独查看/替换）；重生成时优先采用 images/ 里已存在的本地副本（替换后重跑即生效）。
- build_poem.py —— 底层主控：读 JSON → 生成 <题目>-<作者>.html（内嵌）+ <题目>-<作者>.md；被 gen_immersive 调用，也可单独 --grade --title --inline 使用。
- prep_images.py —— 把文生图原始长文件名整理成 hero.png / scene-N.png / closing.png、裁底部 70px 水印，并用边缘密度显著性校验"主体在右"（偏左则镜像）。
- process_img.py —— PNG→webp 处理（裁水印 + 主体在右显著性镜像 + 缩 1200px + 降质 <200KB）；也向 prep_images.py 暴露 ensure_subject_right() 复用。
- fix_subject_right.py —— 批量主体右移翻转：对 static/poem-img/*.webp 用区域密度法（左40% vs 右60%边缘比 >1.15 判定偏左）水平镜像到右侧，避免文字压住人物。--dry 预览、--apply 执行；单图出错跳过不中断。
- sync_images_to_dirs.py —— 一次性补齐：把 static/poem-img 每首诗 6 张 webp 复制到各诗 <题目>/images/（用于历史目录 images/ 为空的场景）。
- sync_real_recitation.py —— 真实朗读同步：把 小学古诗文 音频-古诗文网/ 的真实朗读按 (年级,诗名) 匹配并覆盖到 static/poem-audio/<slug>-recitation.mp3 + 各诗 recitation.mp3；edge-tts 仅作无源兜底。--dry 预览、--all-grades 含 4-6 年级。
- inline_assets.py —— 资源内嵌（被 build_poem --inline 调用）。
- gen_recitation.py —— edge-tts 合成（仅兜底：当且仅当该诗在 小学古诗文 音频-古诗文网 无真实朗读时使用；默认一律用真实朗读）。
- assets/music/ —— 4 首免版税国风 BGM（直接复制到项目的 music/ 即可用）。
- poems/primary_school.json —— 真实诗库（本技能随附，使用时放到项目根 poems/）。
- references/spec.md —— 完整设计规范（强制，优先读它）。
- references/primary_school.template.json —— JSON 结构模板（含一首完整示例：咏鹅）。

完整流程（新增一首）

1. 建数据：在 poems/primary_school.json 对应 grade 下追加 poem 条目，补全全部字段（见下方 schema；可复制 template 改）。
2. 放真实朗读：把播音腔 mp3 放进 小学古诗文 音频-古诗文网/<年级>/<诗名>.mp3；然后 python sync_real_recitation.py 同步进 static/poem-audio/（网页朗读源）。无真实源的诗才由 edge-tts 兜底。
3. 生图（ImageGen，文生图）：
   - 共需 2 + n_chunks 张：hero(题图) + scene-1..n_chunks(分句/分联) + closing(尾评)。n_chunks = ceil(len(lines)/group)，绝句 group=1→4 张场景，律诗 group=2→4 张场景。
   - 文件名约定：static/poem-img/<slug>-hero.webp / <slug>-scene-N.webp / <slug>-closing.webp（slug 见 JSON 该诗条目）。
   - 提示词标准见下；核心：主体在右 60% / 留白在左 40%、年代考据、anamorphic 宽幅、意境互增、无文字水印。
4. 整理图：运行 python prep_images.py 后，对单首执行
   python -c "import prep_images; prep_images.prep('<年级>','<诗名>')"
   得到标准命名 + 裁水印 + 主体在右校验（偏左则镜像）。若已有批量 webp 在 static/poem-img/，可跑 python fix_subject_right.py --apply 统一校正主体右移。
5. 配乐：在 poem 加 "music":"<file>.mp3"（从 music/ 4 首选最贴意境的，或新增 Pixabay 曲放入 music/）。
6. 生成网页：python gen_immersive.py --grade <年级>（批量该年级全部）；或 python gen_immersive.py --grade <年级> --only <slug>（单首重生成）。脚本自动内嵌并输出 images/ 副本。旧流程 python build_poem.py --grade <年级> --title <诗名> --inline 仍可用。
7. 补全 images/ 副本（仅历史目录为空时需要）：python sync_images_to_dirs.py 一次性把 static/poem-img 复制到各诗 images/。
8. 校验：首页含「情感主旨」、结尾页无「表达的情感」且含「可借鉴的写作方法」「小练笔」、场景页含生字/注释/翻译、BGM 已内嵌、右下角「⛶ 全屏」按钮存在、每诗 images/ 含 6 张 webp。

配图提示词标准（强制，详见 spec.md）

• 写实历史电影感、anamorphic 宽幅、克制水墨油画质感。
• 主体在右约 60%，左侧约 40% 为干净天空/大漠/水面留白；网页文字永远在左。
• 意境互增 + 大气沉浸：每张图须与该句/该联诗意互相强化，宏大辽阔。相邻图景别/焦点须明显不同。
• 年代一致：人物服饰/发型/器物/建筑须严格符合朝代（唐圆领袍+幞头、汉深衣曲裾、宋襕衫），禁后世/现代元素。
• 无水印、无文字、无书法、无印章；避卡通/低多边形/塑料感/过饱和/奇幻。
• chunk_prompt(world, lines, idx, n) 会自动把"原句文字 + 意境 + 景别词"编入提示词；world 字段传朝代/地理提示（如"唐代边塞""汉代江南"）。

JSON 字段 schema（一首应含）

{
  "title", "author", "dynasty",
  "group": 1,                 // 1=一句一图(绝句) 2=两句一图(律诗)
  "world": "唐代",             // 生图年代提示
  "kicker": "唐·五言绝句",     // 可省，自动推导
  "highlight": "末句名句",     // 可省，首页钩子
  "lines": ["句1","句2",...],        // 单句数组
  "words": ["句1生字拼音",...],      // 与 lines 对齐
  "notes": ["句1注释",...],
  "translations": ["句1大白话",...],
  "author_intro":"...", "background":"...", "emotion":"...",
  "writing_methods":"...", "practice":"...",
  "music":"mountain_spring_full.mp3",
  "summary":"..."             // 已不渲染但可保留
}

注意：lines/words/notes/translations 必须按"单句"对齐（律诗也拆成单句，group=2 只控制几句拼一图）。

红线（勿破）

• 已认可基准视觉（咏鹅/江南/使至塞上那版）：文字区 48vw、毛笔楷体、局部暗底、情感主旨在首页、结尾只留写法+练笔、默认 BGM——嗣后只做微小调整，禁止整体重写结构/风格。
• 改文件名 ≠ 改风格：只改名字/文案时绝不顺手动视觉。
• 图片人物须符合朝代；一句一图(律诗两联一图)；主体右、留白左、无文字水印。

BGM 选曲映射（内置 4 首，来源 Pixabay 免版税可商用无需署名）

• mountain_spring_full.mp3（笛筝轻快）→ 童趣/咏物
• mist_over_jiangnan.mp3（烟雨江南）→ 水乡/思乡
• ha_long_bay_serenity.mp3（古筝清雅）→ 山水/月夜
• chinese_emotional_erhu.mp3（二胡苍凉）→ 边塞/悲壮
  不足时从 Pixabay 再下新曲放入 music/，并在 poem 的 music 字段指定。

输出

• <题目>-<作者>.html（内嵌图/朗读/BGM，单文件可分享、可投屏）
• <题目>-<作者>.md（逐页文案，便于校对）

备注

• 生字/注释/翻译由模型依据知识撰写，名篇把握大；正式进课堂前建议语文老师扫一眼校对，冷僻诗或指定教材版本请用户贴教材注释后直接套用。
• 浏览器禁止"零交互自动出声"：网页已用 load 自动播放 + 首次滚动兜底 + fullscreenchange 触发（进全屏必响）+ 右下角「⛶ 全屏」按钮一键全屏并播放，投课场景默认有声。