绘本生成技能

从一段创意出发,生成一本可交付的儿童绘本电子书:完整分页故事、角色参考图、逐页插画、神经网络朗读音频、真实背景纯音乐、单文件自动播放翻页 HTML 电子书。

本技能不依赖任何平台后端,纯靠当前 AI 工具的内置模型 + 图像 API + 神经网络 TTS(edge-tts)完成,可整体复制到 Claude Code / WorkBuddy / Trae 等任意工具中使用。

> 脚本位置（上架/分发必读）：本技能所有 Python 脚本位于技能目录的 scripts/ 子目录（已用 SCRIPT_DIR 相对路径自定位，无任何本机绝对路径硬编码）。下文命令中的 <技能目录> 即指本 SKILL.md 所在目录——技能被安装后由运行环境提供其绝对路径，请勿把绝对路径写死进脚本。音频依赖 edge-tts：首次使用按下方 Step 4 安装；上架后市场会自动执行 metadata.openclaw.install 中的安装命令，买家安装技能即自动装好依赖。

最终交付物特性(开箱即得)

生成出的 book.html 单文件已内置:
- 自动播放:从封面/当前页开始朗读,读毕停顿约 0.9 秒自动翻页,末页自动停止;手动翻页仍可用。
- 神经网络朗读(非机器人腔):每页文字预合成并内嵌,自然类人声。
- 女声 / 青年男声 / 中年磁性男声可选:generate_audio.py --voice female|male|mature(默认女声 XiaoxiaoNeural;male=青年男声 YunxiNeural;mature=中年磁性男声 YunyangNeural 播音腔沉稳,最适合讲故事)。
- 真实背景纯音乐:reading / guofeng / warm_home 三首钢琴曲循环衬底,以 base64 文本内嵌于 assets/bgm/bgm_embed.py(技能包不含任何二进制文件,上传 SkillHub 不会被剥离);缺失时优雅跳过,♪ 可独立开关。
- 语速调节:「慢速 / 标准 / 快速」实时切换(0.85 / 1.0 / 1.15 倍速),默认按舒缓档(-20%)预生成。

工作原理

核心质量(分页结构、角色物种前缀、画面禁止文字、跨页一致性)由提示词与流程规则保证。

多本输出约定(避免覆盖)

每本绘本使用独立目录 <BOOK_DIR>,所有产物(story.json / characters/ pages/ audio/ bgm/ book.html)都在其中,多次生成互不覆盖。

1. 用 scripts/new_book.py 在指定 root 下创建碰撞安全目录:
   bash python3 new_book.py --root ~/books --title "登鹳雀楼的故事" --slug dengguanquelou # 打印并返回 <BOOK_DIR> 绝对路径;若同名已存在自动加 -2 -3 后缀,绝不覆盖
   - --slug:ASCII 目录名(推荐,跨系统/URL 友好);省略时若标题为 ASCII 用标题,否则回退 book-<时间戳>。也可用 --name 直接指定(允许中文,本地可用)。
   - 同时把内置 3 首英文 bgm 复制到 <BOOK_DIR>/bgm/,使每本自包含、可独立分发。
2. 后续步骤的脚本均加 --book-dir <BOOK_DIR>(默认即当前目录)。
3. 图像工具(角色参考图 / 逐页插画)的 output_dir 分别设为 <BOOK_DIR>/characters 与 <BOOK_DIR>/pages。

> 不传 --book-dir 时,脚本以当前工作目录为 <BOOK_DIR>,行为与旧版 output/ 一致,向后兼容。

使用模式(用户可任意选择)

本技能支持两种使用方式:

• 模式 A · 一键生成（推荐）:用户只给一段创意,智能体按本技能全流程自动执行——用客户端已配置的模型生成故事、用客户端图像工具（ImageGen 等）出插画、最后用 make_book.py 一键合成朗读并组装成书。
• 零配置:故事与插画依赖的是客户端自带能力,技能脚本内不写任何 API Key / 端点 / LLM 调用;音频用 edge-tts（免费、无需密钥）。装技能即用,可直接分发给 WorkBuddy / TraeWork / Claude Code 等任意客户端。
• 插画完成后的收尾命令（自动完成 Step 4 音频 + Step 5 组装）:
  bash python3 make_book.py --book-dir <BOOK_DIR> --voice mature --external # 可选参数: --voice female|male|mature --no-audio --check(仅校验素材) # --root/--title/--slug(免建目录,直接建一个) # --index-root <库根> / --no-index(控制书架索引 index.html 更新)
• 用 --root 建书后,make_book.py 会自动更新该库根的 index.html 书架总览页(见下方「绘本书架索引页」章节),用户可在一个页面总览并跳转到任意绘本。
• 模式 B · 分步 / 调试:手动依次执行下方 Step 0–6,适合精细化调整、部分重跑、排查问题（Step 4/5 直接用 generate_audio.py 与 build_book.py）。

> 无论哪种模式,故事与插画都不在脚本内调用 LLM / 图像 API——它们由运行本技能的智能体使用其客户端已配置好的模型与图像工具完成。这是「零配置、可跨客户端分发」的关键。

绘本书架索引页（多本总览）

多次生成绘本后,用 make_index.py 在 library root 生成 index.html 总览页:书架卡片(封面 + 标题 + 日期 + 页数)+「翻开阅读」按钮,点击跳转到对应绘本阅读页,形成「书架 → 单本」的总览体验。

python3 make_index.py --root ~/books            # 扫描 ~/books 下所有绘本子目录
python3 make_index.py --root ~/books --title "小神的绘本书架"

• 一本书的判定:<root> 自身若含 story.json 也算一本(兼容老的单本直接放在 root 的情况);<root> 下任一含 story.json 的子目录算一本。
• 阅读链接:自动优先 book_external.html(外链版,内置预览有声),否则 book.html(单文件版)。
• 封面:取每本 pages/page_01.png(首页即封面);卡片与封面对外均用相对路径,file:// 与 http:// 均可打开。
• 自动更新:make_book.py 在用 --root 建书后会自动调用本脚本更新该 root 的 index.html,无需手动;也可用 --no-index 跳过,或用 --index-root 显式指定库根。
• 返回总览(反向导航):make_book.py 在 --root / --index-root 且该库根为已存在目录时,会在组装阶段给阅读页注入「← 总览」返回键(build_book.py --index <root>/index.html);点击后从本书目录相对跳回 index.html(根直放本 → index.html,子目录本 → ../index.html,相对路径由脚本自动算)。由此形成「书架总览 → 单本阅读 → 返回书架」的闭环。不传 --index 时阅读页不带返回键(适合单文件 book.html 离线分发)。
• 本地预览:在 root 起 HTTP 服务后访问 index.html(外链版需 HTTP,内置预览才出声):
  bash cd ~/books && python3 -m http.server 8765 # 浏览器 / 内置预览打开 http://127.0.0.1:8765/index.html

工作流

Step 0 · 需求收集

向用户收集(缺省用默认值,不用逐项追问):

> 若创意为空,先引导用户描述:主角是谁、发生在哪、发生了什么事、希望什么样的结局。
> 声音性别与背景乐若用户未指定,直接用默认值生成最终版,无需追问。

size 表(图像 API 用):

Step 1 · 生成故事(一次调用)

1. 读取 references/story-prompt.md,代入 Step 0 参数生成故事 JSON。
2. 读取 references/character-name-normalization.md,执行角色名规范化自检与纠正。
3. 保存为 <BOOK_DIR>/story.json。
4. 向用户展示易读摘要:书名、角色(含物种)、总页数、前几页梗概。
5. 必须等用户确认后才进入图像阶段(图像按张计费/消耗,未经确认不得生成)。

Step 2 · 生成角色参考图(强烈推荐,保证跨页一致)

读取 references/character-reference-prompt.md,对每个角色构建提示词,调用图像 API(或工具绘图)生成 1行3列 正/侧/背 立绘,保存为 <BOOK_DIR>/characters/<角色名>.png。

> 参考图是跨页一致性的核心锚点。若某角色参考图生成失败,继续下一步,但后续该角色的插画提示词里必须写全其视觉描述。

Step 3 · 逐页生成插画

读取 references/illustration-prompt.md 与 references/image-generation.md,对每页组装提示词(注入该页出场角色的参考图),保存为 <BOOK_DIR>/pages/page_NN.png。

• 逐页报告进度(第 N/总页数 完成)
• 已存在的页面文件跳过(支持断点续跑)
• 每页调用间隔 ≥ 1 秒(Agnes 限速)

Step 4 · 生成朗读音频(默认必做)

> 一键模式（模式 A）可跳过本步与 Step 5,插画完成后直接运行 make_book.py --book-dir <BOOK_DIR> --voice mature --external 自动完成音频合成 + 电子书组装,无需手动跑两个脚本或复制文件。

用微软神经网络语音(edge-tts,免费、无需密钥)把每页 story_text 合成为 mp3。一次性准备隔离环境后运行:

python3 -m venv venv && venv/bin/pip install edge-tts
cp <技能目录>/scripts/generate_audio.py <BOOK_DIR>/
cd <BOOK_DIR>
python3 generate_audio.py --book-dir <BOOK_DIR> --voice mature   # 中年磁性男声(推荐)
# 可选: --voice female(默认) / --voice male(青年) / --rate "-25%"

生成 <BOOK_DIR>/audio/page_NN.mp3。

> 若环境无法安装 edge-tts,退化为浏览器 Web Speech 朗读(build_book 模板改用 SpeechSynthesisUtterance 朗读 story_text),无预合成音频与背景乐,需向用户说明。

Step 5 · 组装导出电子书(最终版)

运行 scripts/build_book.py(<BOOK_DIR> 即运行目录或传 --book-dir):

cp <技能目录>/scripts/build_book.py <BOOK_DIR>/
cd <BOOK_DIR>
python3 build_book.py --book-dir <BOOK_DIR>              # 单文件 book.html(内嵌图片+音频+背景乐)
python3 build_book.py --book-dir <BOOK_DIR> --external   # 外链版 book_external.html(配合本地HTTP,内置预览用)
python3 build_book.py --book-dir <BOOK_DIR> --external --index ~/books/index.html   # 外链版 + 注入「返回总览」按钮

> --index <index.html路径>(可选):阅读页左上角注入「← 总览」返回键,相对路径由脚本自动计算(根直放本 → index.html,子目录本 → ../index.html)。make_book.py 在 --root / --index-root 且该库根为已存在目录时会自动传此参数,因此一键生成的绘本自带返回键,无需手动传。

背景乐自动发现顺序:--bgm 显式 > <BOOK_DIR>/bgm.mp3 > <BOOK_DIR>/bgm/ 首曲 > 技能内置 assets/bgm > --bgm-dir。默认优先 reading.mp3。找不到时优雅跳过(♪ 按钮不生效)。

> ⚠️ 背景乐文件名必须 ASCII 英文:中文文件名会因 URL 编码在预览/浏览器加载失败。内置三首已统一为 reading.mp3 / guofeng.mp3 / warm_home.mp3。--external 模式会把选中的 bgm 自动复制到 <BOOK_DIR>/bgm/ 并用实际文件名生成相对引用。

Step 6 · 自动播放与交互(已内置,无需额外开发)

build_book.py 生成的模板已内置:自动播放自动翻页、语速选择器、背景乐循环衬底与独立开关、← → / 空格 / 圆点导航、封面「开始阅读(带朗读)」。

> ⚠️ 实现要点（避坑）:自动翻页依赖「朗读音频播完 → 自动翻下一页」。build_book.py 模板里必须保留 audioEl.addEventListener('ended', onNarrEnded) 这一行绑定（onNarrEnded 在末页停止、否则停顿 0.9 秒后 go(1))。重构/改模板时切勿删除这行——只保留 onNarrEnded 函数定义而不绑定 ended 事件,表现就是「读完了不翻页」,且单文件旧版可能掩盖此问题。交付前务必实测一次「封面开始阅读 → 逐页自动朗读翻页 → 末页停止」。

内置预览无声

外部浏览器打开 book.html 正常出声;WorkBuddy 内置预览面板对 data: 内联媒体有安全限制会无声。解决办法见 references/preview-audio.md:用 --external 生成外链版 + 本地 HTTP 服务,经 http://127.0.0.1:8765/book_external.html 打开。

质量检查清单(交付前逐项核对)

• [ ] 每页 story_text 与 scene_description 画面一致
• [ ] 插画中无任何文字/字幕/气泡/水印/签名
• [ ] 角色名全篇统一(非人类带物种前缀),无别名变体
• [ ] 同一角色跨页外观一致(有参考图或描述完整)
• [ ] 页数符合预期(自动时偶数、8-32)
• [ ] book.html 可打开、可翻页、文字与图一一对应
• [ ] 每页 audio/page_NN.mp3 已生成且被内嵌(声音性别/语速符合 Step 0)
• [ ] 背景乐已按优先级发现并内嵌(或明确告知用户本次无背景乐)
• [ ] 「开始阅读(带朗读)」可从封面发声并自动翻页,末页自动停止
• [ ] 语速选择器可实时切换
• [ ] 多本输出:各 <BOOK_DIR> 独立、互不覆盖
• [ ] 多本时 index.html 已生成,各卡片封面/链接相对路径正确、可点击跳转
• [ ] 从 index.html 进入单本后,阅读页左上角「← 总览」可跳回 index.html(闭环导航)

成本与安全

• 确认检查点:Step 1 生成故事后必须经用户确认才生成图像;页数多时中途可让用户确认续跑
• 参考图最多 5 张/页,单角色 1 张
• 儿童内容红线:避免黑暗、恐怖、暴力、不适内容
• 图像失败时:换提示词措辞(保留构图/角色/场景信息)重试,或提示用户检查 key/网络,不要无限重试