将小说改编为 React 互动小说网页游戏：用 bl…

当用户要把小说/故事做成 H5 互动小说、文字冒险、分支剧情或视觉小说时，按此流程搭建 React SPA，并可选接入 AI 视频/图片/TTS 素材。

适用场景

解决思路

1. 使用 AskUserQuestion 一次性确认：素材来源（是否有 EPUB/TXT，先读取提取剧情结构）、游戏类型（互动小说/文字冒险+解谜/文字RPG）、UI 风格（默认 auto，根据题材推断，用户可覆盖，仅不满意时指定）、叙事视角（第一人称/第三人称上帝视角/双主角切换）、AI 素材生成（是否需要；视频模式/图片模式/混合模式推荐）、音频（无/BGM/BGM+音效/BGM+音效+TTS 旁白）、游戏时长（15-20分钟 8-10场景/30-45分钟 15-18场景/1小时+ 25+场景）。
2. UI 风格 auto 推断：科幻/未来/太空/人工智能/末日→赛博朋克（冷色调、霓虹高光、等宽字体、扫描线）；古风/武侠/仙侠/历史/宫廷→水墨中国风（墨色、留白、衬线字体、水墨晕染）；复古/8bit/轻松/治愈/搞笑→像素风（低饱和、像素字体、CRT 扫描线）；现代/都市/现实主义/悬疑/职场→简约现代（中性色、无衬线字体、扁平化）；多题材混合取主导题材，无法判定默认简约现代；在第二步产出物中说明判定理由。
3. 剧情设计：识别 1-3 条主线（可交织），每条线梳理关键场景。
4. 剧情设计：选出 3-5 个影响结局的重大选择。
5. 剧情设计：设计 3-5 个不同结局，每个由 flags 组合决定。
6. 剧情设计：列出需要立绘的主要角色（6-8个），含外观描述。
7. 剧情设计：列出需要生成素材的高潮过场场景（5-8个），含画面描述。
8. 剧情设计：设计通过选择解锁的背景知识条目，即收集物/档案。
9. 剧情设计：auto 模式时根据题材判定 UI 风格并说明理由。
10. 剧情设计：画文字版分支图，确保每个重大选择有 ≥2 条不同后续路径。
11. 分支设计原则：选择即分叉，重大选择的每个选项应导向不同的下一场景（不同 next），而非同场景+不同 flag；玩家选 A 走 A 路线，选 B 走 B 路线，文本/立绘/BGM 都不同。
12. 分支设计原则：分后必合或分后不归，分支后要么在下游中转节点汇合（合流点保留共同剧情推进，用 flag 微调文本），要么一路分到底导向不同结局。
13. 分支设计原则：禁止假分支，避免选 A 或 B 但下一场景相同且仅 flag 不同的伪选择；若 A/B 后续差异不大则合并为单线，不硬凑分支。
14. 分支设计原则：分支深度，每个重大分支至少影响 2-3 个后续场景的文本/立绘/BGM，让玩家感受到这次玩的不一样。
15. 分支设计原则：flag 不再是分支的全部，而是记录累计倾向，用于在合流点微调文本和最终决定结局；真正的分支由 next 指向不同场景实现。
16. 分支示例：红岸基地·发射抉择，选「按下发射」→ scene_send_signal（发送信号路线，2-3个独有场景）→ 合流点 scene_convergence（文本根据 sent_signal=true 微调）；选「犹豫放弃」→ scene_abort_signal（放弃路线，2-3个独有场景）→ 合流点 scene_convergence（文本根据 sent_signal=false 微调）。
17. 项目架构：使用 npx create-react-app 初始化，并按结构组织代码：src/App.jsx 主应用、游戏状态路由；src/index.js；components/TitleScreen.jsx 开始画面（主题动画+标题+继续游戏+存档管理）；GameScene.jsx 核心场景渲染（文本+选择+立绘+旁白）；TypeWriter.jsx 打字机；ChoicePanel.jsx 选择面板（hover动效+延迟入场）；CharacterPortrait.jsx 角色立绘（自动适配视频/图片）；CutScene.jsx 过场播放（视频/图片 Ken Burns）；EndingScreen.jsx 结局界面；ArchivePanel.jsx 档案/收集物面板；ArchiveNotification.jsx 档案解锁通知；SaveLoadPanel.jsx 存档/读档面板；ProgressBar.jsx 章节进度条；data/story.js 场景图核心数据；characters.js 角色定义；archives.js 档案数据；generated-assets.json AI 生成素材的本地路径+类型；hooks/useGameState.js useReducer 游戏状态管理+存档；useAudio.js Web Audio API 音频系统；styles/theme.css 主题样式；animations.css 动画定义；crt.css CRT 扫描线效果（像素风专用）；[特殊场景组件] 按需 Canvas 动态背景等；scripts/generate-assets.sh bl CLI 素材生成脚本；public/assets/ 下载到本地的素材文件，portraits/ 角色立绘 .mp4 或 .png、cutscenes/ 过场素材 .mp4 或 .png、backgrounds/ 场景背景图 .png、narrations/ TTS 旁白音频 .mp3。
18. 核心数据模型 story.js：每个 scene 包含 id、title、timeline（past|present|game 时间线标识，影响 UI 颜色）、year、character、bgm、cutscene 可选、narration 可选、isEnding、endingType、texts 数组、choices 数组；choice 包含 text、next（分叉路线不同场景）、setFlags、archive 可选。
19. 核心数据模型：实现 getSceneText(scene, flags)，读 flag 返回该玩家路线专属的文本/立绘。
20. 核心数据模型：实现 getEnding(flags)，根据 flags 组合返回对应结局 scene id。
21. 核心数据模型 generated-assets.json：portraits 下每个角色含 path、type；cutscenes 含 path、type；backgrounds 含 path、type；narrations 含 path；路径为本地路径，如 /assets/portraits/ye_wenjie.mp4。
22. 核心数据模型 useGameState 状态结构：phase 'title'|'playing'|'cutscene'|'ending'、currentScene、flags、history、archives、textIndex、typingDone、showCutscene、showArchive、newArchive、bgm。
23. 实现 TypeWriter：用 setInterval 逐字显示，speed 约 40-50ms；点击/触摸可跳过，立即显示全文；每个字符触发打字音效回调；显示完毕调用 onDone 回调。
24. 实现 ChoicePanel：在最后一段文字打字完成后淡入；每个选项延迟入场动画（nth-child animation-delay）；hover 时边框变色+微位移+阴影扩大；点击触发音效→设置 flags→自动存档→跳转下一场景。
25. 实现 Hash 路由：URL hash 同步当前场景 #scene_id；支持直接通过 URL 跳转到任意章节（开发调试+分享）；监听 hashchange 支持浏览器前进/后退；回到标题时清除 hash。
26. 实现存档系统 localStorage：自动存档在每次做出选择后 localStorage.setItem('novel_autosave', JSON.stringify(state))；手动存档支持 3 个槽位 novel_save_1/novel_save_2/novel_save_3，每个槽位保存完整 state+存档时间+当前场景标题；TitleScreen 提供新游戏（清空状态从头开始）、继续游戏（仅自动存档存在时显示，加载自动存档）、读取存档（打开 SaveLoadPanel 显示 3 个手动槽位）；SaveLoadPanel 游戏内可随时打开（菜单按钮/快捷键），支持存档和读档；存档数据结构 {state, savedAt, sceneTitle, playTime}。
27. 实现 CharacterPortrait：从 generated-assets.json 读取素材信息，根据 type 字段渲染；type: video→<video src={path} autoPlay loop muted playsInline />；type: image→<img src={path} />+可选呼吸动效 CSS animation: breathe 3s ease-in-out infinite；无素材时显示角色名首字母占位符。
28. 实现 CutScene：type: video→全屏 <video> 播放，结束后自动关闭；type: image→全屏 <img>+Ken Burns 动效 CSS animation: kenburns 5s ease-in-out，5 秒后自动关闭；Ken Burns 效果从 scale(1.1) translate(-2%, -2%) 过渡到 scale(1.0) translate(0, 0)，模拟镜头缓慢推拉。
29. 实现素材懒加载：所有视频元素默认 <video preload='none'>，不预加载；仅预加载当前场景和下一可能场景的素材；场景切换时 video.load() 加载当前→requestIdleCallback 预加载下一个；离开场景时 video.pause(); video.removeAttribute('src'); video.load() 释放内存；图片使用 loading='lazy' 属性。
30. 实现移动端适配：meta name=viewport content=width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no；竖屏优先布局，文字区占屏幕上方 60%，立绘在下方 40%（横屏时立绘在侧边）；选择按钮最小高度 44px（iOS 触控标准）；字体 16px 起步，防止 iOS Safari 自动缩放；打字机跳过同时监听 click 和 touchend（不能只依赖 click，移动端有 300ms 延迟）；CSS env(safe-area-inset-bottom) 处理 iPhone 底部安全区；禁止双指缩放 touch-action: manipulation；禁止长按菜单 -webkit-touch-callout: none; user-select: none（仅对游戏 UI 元素）。
31. AI 素材生成：使用 Shell 脚本 scripts/generate-assets.sh 调用 bl CLI 生成并下载素材；素材必须离线生成并下载到本地，游戏运行时零 API 调用；本地文件路径直接传入 --image，bl CLI 自动上传到临时存储（48小时有效），无需手动上传；已生成素材自动跳过（[ -f path ]）；generated-assets.json 只存本地路径如 /assets/portraits/ye_wenjie.mp4，绝不存远程 URL；视频用 --async 并行提交，3-5 个并发，避免串行等待。
32. 视频素材命令：角色立绘有参考图时用 image-to-video，bl video generate --image ./references/ye_wenjie.png --prompt '一位穿着军绿色工装的年轻女性，目光坚定地注视远方，微风吹动发丝，半身特写' --resolution 720P --duration 5 --watermark false --download public/assets/portraits/ye_wenjie.mp4。
33. 视频素材命令：角色立绘无参考图时用 text-to-video，bl video generate --prompt '一位穿着深色西装的中年物理学家，站在大学讲台前，表情严肃，半身特写' --resolution 720P --duration 5 --watermark false --download public/assets/portraits/physicist.mp4。
34. 视频素材命令：过场动画用 bl video generate --prompt '红岸基地，巨大的抛物面天线在暴风雨中矗立，闪电照亮天线轮廓，镜头从远景推近，电影级画质' --resolution 1080P --duration 5 --watermark false --download public/assets/cutscenes/red_coast_storm.mp4。
35. 视频素材命令：多角色一致性场景用 bl video ref --prompt 'Image1 和 Image2 在实验室中争论，Image1 愤怒地拍桌子，Image2 冷静地注视' --image ./references/character_a.png --image ./references/character_b.png --resolution 1080P --duration 5 --watermark false --download public/assets/cutscenes/lab_argument.mp4。
36. 图片素材命令：角色立绘静态图用 bl image generate --prompt '一位穿着军绿色工装的年轻中国女性，目光坚定，黑色短发，70年代风格，半身肖像画，电影光影' --size 768*1024 --watermark false --out-dir public/assets/portraits/ --out-prefix ye_wenjie。
37. 图片素材命令：场景背景图用 bl image generate --prompt '1960年代中国大学校园，苏式建筑，红色标语横幅，秋天的梧桐树，灰暗天空，写实油画风格' --size 1920*1080 --watermark false --out-dir public/assets/backgrounds/ --out-prefix campus_1967。
38. 图片素材命令：过场 CG 静态图+游戏内 Ken Burns 动效用 bl image generate --prompt '红岸基地全景，巨大的抛物面天线矗立在山顶，黄昏，金色光芒，电影级构图' --size 1920*1080 --watermark false --out-dir public/assets/cutscenes/ --out-prefix red_coast_base。
39. TTS 旁白命令：场景旁白用 bl speech synthesize --text '1967年，中国大地上，一场浩劫正在改变无数人的命运。' --voice longxiaochun --language zh --out public/assets/narrations/scene_opening.mp3。
40. TTS 旁白命令：角色独白用 bl speech synthesize --text '叶文洁按下了发射按钮，那一刻，她做出了一个改变人类文明命运的决定。' --voice longxiaochun --language zh --instruction '用沉重而悲伤的语气' --out public/assets/narrations/ye_decision.mp3。
41. 并行生成脚本模式：用 declare -A TASKS 保存 name→task_id；循环 PORTRAITS，跳过已存在 outfile；bl video generate --prompt 等参数 --async --output json | jq -r '.taskId' 获取 tid；然后循环 TASKS，bl video download --task-id '${TASKS[$name]}' --out 'public/assets/portraits/${name}.mp4'。
42. 实现 Web Audio API 程序化音乐：用 MIDI 音高数组定义旋律乐句并循环播放；多声部叠加（主旋律+去谐波 detune+pad 持续音）；卷积混响（用随机衰减 impulse buffer）；ADSR 包络（attack-decay-sustain-release）；低通滤波器随时间衰减；不同场景/氛围用不同配置（bpm、音阶、波形、滤波频率）。
43. 实现音效：打字音用白噪声脉冲+带通滤波（2000-4000Hz）+微弱正弦下降音，模拟机械击键；点击音用双音方波上行（660→880Hz）；场景切换用四音正弦琶音+混响；档案解锁用扫频+四音三角波和弦。
44. 开发流程：1 初始化 React 项目+目录结构；2 编写 story.js（所有场景文本、选择、分支）这是最大工作量；3 编写 characters.js 和 archives.js；4 实现主题样式（CSS 变量、字体、配色、动画、移动端适配）；5 实现核心组件 TypeWriter→GameScene→ChoicePanel→CharacterPortrait（支持视频/图片）；6 实现 CutScene（支持视频/图片 Ken Burns）；7 实现 TitleScreen+EndingScreen+ArchivePanel+SaveLoadPanel；8 实现 useGameState（reducer+hash 路由+localStorage 存档）；9 实现 useAudio（BGM 乐谱+音效+可选 TTS 旁白播放）；10 如需 AI 素材：编写 scripts/generate-assets.sh→执行生成并下载；11 实现特殊场景效果（Canvas 动态背景、点击交互等）；12 整合 App.jsx；13 启动 dev server，浏览器测试完整流程（至少走通两条路线到不同结局）；14 移动端测试（用 Chrome DevTools 模拟手机视口+触控）。
45. 避坑：bl video 分辨率支持 720P 和 1080P，测试阶段用 720P（更快更便宜），最终版用 1080P。
46. 避坑：bl video --download 自动轮询，--download 标志会自动等待任务完成并下载文件，无需手写轮询代码；批量生成时用 --async+bl video download 并行提速。
47. 避坑：bl image generate 尺寸用 --size 指定，格式为 宽*高（如 1920*1080），也支持比例格式（如 16:9）。
48. 避坑：本地路径自动上传，bl CLI 的 --image 接受本地文件路径，会自动上传到临时存储（48小时有效），无需手动上传。
49. 避坑：素材必须离线生成并下载到本地，视频生成耗时 2-5 分钟/个，绝不能在游戏运行时调用；下载到 public/assets/，generated-assets.json 中只存本地路径。
50. 避坑：Prompt 内容审核，避免暴力、吸烟等敏感描述，否则会被 API 拒绝；换温和表述重试。
51. 避坑：React Hooks 顺序，所有 useCallback/useEffect 必须在 early return 之前调用，否则报 rules-of-hooks 错误。
52. 避坑：BGM 编曲用固定 MIDI 乐谱数组循环播放，不要用随机音符漫游（听起来像噪声）。
53. 避坑：打字音质感用噪声脉冲+带通滤波模拟击键，比纯方波 beep 好很多。
54. 避坑：特殊场景视觉，Canvas 动态背景必须与叙事内容紧密关联（出现什么元素画什么），不能泛泛画星空了事。
55. 避坑：点击交互，Canvas 场景加粒子爆发+冲击波环+屏幕震动+主题相关额外效果，大幅提升沉浸感。
56. 避坑：CRA 清理，初始化后立即删除 App.css/logo.svg/setupTests.js 等样板文件，避免冲突。
57. 避坑：移动端字体，正文最小 16px，否则 iOS Safari 会自动缩放页面。
58. 避坑：视频内存泄漏，离开场景时必须 video.pause(); video.removeAttribute('src'); video.load() 释放内存。
59. 避坑：避免伪分支，若两个选项的 next 指向同一场景且仅 flag 不同，玩家会感觉「选了没用」；重大选择必须 next 到不同场景，或至少在同场景用 flag 触发明显不同的文本/立绘。
60. 避坑：合流点保留差异感，分叉汇合后至少在合流场景的文本/旁白中体现玩家之前的选择（读 flag 渲染条件文本），否则分叉毫无意义。
61. 避坑：分支深度要够，每个重大分支至少影响 2-3 个后续场景，仅分叉一个场景就立刻合流会让玩家觉得「选了也就多看一句话」。

适用边界 · 注意事项

• 未安装或不想使用阿里云百炼 CLI（bl）/无法访问百炼服务时，AI 视频、图片、TTS 素材生成部分不适用。
• 需要纯离线、零 API 调用且不准备本地预生成素材时，不应使用依赖 bl 的素材生成流程。
• 只需简单静态页面、无分支剧情/存档/音频需求时，不必套用整套互动小说架构。