papermorph

Papermorph

Papermorph 可在一台机器上制作四种图书：

• 课程，根据教材 PDF 制作：每章都是一部简短的动画课程影片，画面负责解释，旁白讲出内容，快速测验和练习则融入画面中。
• 绘本，根据故事、笑话或童话制作：纸偶在布景前演出的短片，布景可用代码绘制，也可由图像模型绘制，并配上配音、音效和音乐。
• 纪录片，根据书籍或想法制作：以公有领域图片为素材的旁白影片，文字和地图随旁白同步移动，并配上音乐。
• 短视频，根据用户列出的论点制作：适合手机信息流的竖屏影片，在三分钟内阐明一个观点。

所有成品都由一个 SVG 舞台（1600×900，短视频则为 900×1600）和一个播放器组成；节拍将旁白片段与定时动作配对。好的成品应该生动（事物的动作和变化有分量感，也讲究时机）、构图得当（每个瞬间都能作为一幅完整的画面来理解，文字放在其所指对象旁边）、准确（动作、标签和数字在每个瞬间都相符），并且流畅（播放时不会卡顿，也包括 Firefox）。

画面应该呈现什么，取决于图书和用户，因此制作从一场对话开始，并以 style.json 收尾：其中记录用户的原话、他们选择的视觉风格、配音、各步骤使用的模型，以及之后获批的章节。每一章都依据它制作；每个节拍如何布局和编排，由你根据它和获批章节来判断。用户的要求优先于默认设置。重新创作解释、示例和绘图；将源 PDF、页面图片和提取的文本放在静态输出文件夹之外，并排除在版本控制之外（.gitignore：*.pdf、books/*/pages/）。交付一个自包含的图书文件夹，并附上本地预览说明。

选择路径

用户提供的内容	路径	阅读
教材 PDF	课程	intake.md，然后阅读 diagrams.md（第 1 级）或 scenes.md（第 2 级）、authoring.md、assets.md、review.md
故事、笑话、童话或故事书的 PDF	绘本	stories.md、puppets.md、sound.md；如需绘画风格，再阅读 painting.md
要制作成旁白影片来讲解的书籍、想法或一段历史	纪录片	documentary.md；如需音乐，再阅读 sound.md
要在三分钟内阐明的一个观点，竖屏，适合手机信息流（YouTube Shorts、TikTok、Reels）	短视频	shorts.md，以及 documentary.md 中有关配音、图片和审核的内容
课程用书（引用作品、经审核的问题、LMS）	课程及可选项	仅在用书有此需求时阅读 courses.md

所有路径都会用到 site.md（图书文件夹、封面或系列页面、预览、视频导出）、engine.md（播放器和绘图 API）、team.md（使用子 Agent 制作章节），以及 intake.md 中的模型步骤。只阅读当前步骤需要的参考资料。

项目布局

books/<book>/
  book.pdf, sections.json      source and page map (private)
  pages/chNN/text.md, *.png    extracted reference material (private)
  style.json                  the agreed style every chapter anchors to (assets/templates/style.json)
  chapters.md                 chapter map and status
  chapters/chNN.md            storyboard, errata, feedback
  images/                     inbox, SOURCES.md (where each image came from), image-requests.md, processing scripts
  review/chNN/                storyboard sheets, strips, check output
content/<book>/chNN/           narration.<lang>.json and TTS cache
tools/<book>/                 tests and evidence scripts
site/<book>/                   the static book (only this is delivered)
  index.html, unit-art.js      cover + contents, unit sketches
  lib/engine.*, math.js,       the engine (player, maths helpers, cover/contents, unit headers), copied into
      volume.*, contents.*,      the book by scripts/engine.py
      units.*
  lib/book.css                 this book's engine settings and style overrides
  lib/*.js, img/               the book's element library and images
  chNN/index.html, audio/<lang>/   a lesson, its beat MP3s + timings.js

绘本会添加 books/<book>/story.md（用户的讲述，原文照录）、storyboard.md 和 art/（包含场景草图的 sets.js、生成的图片、painted.json、costs.tsv）；其 site/<book>/lib/ 存放纸偶套件（来自 assets/templates/picture-book/ 的 paper.js、cast.js、shared.js，需要 engine-v2.2 或更高版本：sfx() 和 music() 已在引擎中），img/ 存放烘焙后的场景、道具和纸偶部件；每集 chNN/ 有每个场景的一个脚本，以及 audio/<lang>/、audio/sfx/、audio/bgm/。

纪录片会添加 books/<book>/storyboard.md、art/（包含下载图片的 found/、prep.py 清单、生成的片段、costs.tsv）和 music/，其中 commons.py 会将 SOURCES.tsv 与下载文件放在一起；其 site/<book>/lib/ 存放来自 assets/templates/documentary/ 的 film.js、fonts.css 和 fonts/（以及影片配色对应的 book.css），并在影片使用时包含 lines.js（trace.py）；img/ 存放处理后的图片及其 art.js（prep.py），还有片段的帧表及其 frames.js（frames.py）；index.html 是包含鸣谢信息的系列页面；每部影片的 chNN/ 都有 audio/<lang>/ 和 audio/bgm/。

短片系列会添加 books/<book>/chNN-script.md（大纲，包含画面内容的节拍、来源）、art/（生成和收集的图片、costs.tsv）和 music/；其 site/<book>/lib/ 存放来自 assets/templates/shorts/ 的 shorts.js、book.css 和 icons.js，以及纪录片套件的字体，还会有一个系列自有部件的文件，在 shorts.js 之后加载；每集 chNN/ 都有 audio/<lang>/、audio/sfx/ 和 audio/bgm/。

SKILL 表示此技能所在文件夹的绝对路径；<book> 是书籍 slug，<lang> 是其主要语言代码。依赖项：uv、ffmpeg/ffprobe、Edge TTS 网络访问（或本地 Kokoro：uv run --python 3.12 --with kokoro）；当仓库中没有 engine/ 文件夹时，需要访问 github.com 以获取 engine.py；仅在用户选择付费步骤时需要 OpenRouter 密钥（paint.py、eleven.py、video.py；paint_openai.py 需要 OpenAI 密钥）；还需要 Playwright 浏览器（uv run --with playwright playwright install chromium firefox；如果 Playwright 的 Chromium 无法运行，请将 CHROME 设置为已安装的 Chrome、Chromium、Brave 或 Edge）。预览：python3 SKILL/scripts/serve.py 8765 site（不缓存浏览器内容）。

经验总结

流程

如果 books/<book>/style.json 尚不存在，请先进行信息收集；复用已给出的回答和批准意见。

1. 信息收集（intake.md），进行一段简短对话：与用户一起找到 PDF（故事请转到 stories.md），拆分 PDF，说明这本书的内容，协商选定一个试做章节和一个层级，建立图书文件夹，按照该层级的要求确定外观，协商哪个模型负责哪个步骤，并编写 style.json。
   • 拆分：uv run --with pymupdf SKILL/scripts/outline.py books/<book>/book.pdf；在章节层级使用 --level N -o books/<book>/sections.json。若某个章节书签指向其相邻章节范围之外，则将其移至标题所在页，或发出警告后舍弃：检查这些章节的页面。对于没有可用章节书签的 PDF，请检查 split_pages.py … --pages 1-12 --out books/<book>/pages，然后根据其内容编写映射（架构：outline.py --help）。使用 split_pages.py … --sections books/<book>/sections.json --out books/<book>/pages --text-only 提取章节文本。
   • 在向用户展示任何画面之前，先按照 site.md 建立图书文件夹；将协商好的共享组件一次性构建到图书库中（assets.md），并在 style.json 中列出。
2. 试点。 通过章节循环制作选定章节，并交付给用户评审。将用户反馈整合到 style.json 中，并将该章节记录在 approved 下。
3. 其余章节和收尾：当用户希望完成整本书时，编写 chapters.md，按顺序制作各章节（见 上下文），使用 site.md 完成封面文字、目录和单元草图。交付静态图书文件夹、用于本地预览的入口 URL，以及任何尚未解决的问题。

课程教材可能还需要经过验证的引用链接、经过审阅的题库，或用于 LMS 的 SCORM 包；仅在教材有此需要时才提供（courses.md）。

章节循环

1. 阅读本章的 pages/chNN/text.md；如果图表或缺失文本需要图片，请使用 split_pages.py … --only chNN 渲染页面。选择要讲解的观点、示例和章节。
2. 节拍与旁白：在 chapters/chNN.md 中列出各个节拍，说明每个节拍的内容，以及哪个词会触发哪个动作（authoring.md）。编写 content/<book>/chNN/narration.<lang>.json，然后运行 uv run --with edge-tts SKILL/scripts/tts.py content/<book>/chNN/narration.<lang>.json site/<book>/chNN/audio/<lang>（对于 "engine": "kokoro"：uv run --python 3.12 --with kokoro …）。
3. 故事板，先布局：在实际页面中，为每个节拍的一到三个关键时刻放置所有内容，使用实际尺寸的真实元素，暂不添加动画。使用 strip.py 将其截取到一张图上，并为每一帧写一句话，说明其中的内容以及视觉焦点所在。该图就是故事板。记录本章还需要哪些图书库之外的内容：绘制这些内容，或将其添加到图片请求中。
4. 动画：添加动画、镜头和问题；API 和回放不变量见 engine.md。
5. 交付检查：观看输出动画，并像观众一样对照故事板进行评估；然后运行 review.md 中的检查。修正发现的问题，重新检查后再交付；报告尚未解决的问题。
6. 登记：将本章添加到目录（index.html 中 Contents.book 的 units），设置上一章的 CHAPTER.next，更新 chapters.md 和 chapters/chNN.md。将新的共享决策和反复出现的元素纳入 style.json 和图书库。使用子 Agent 时，这一步由协调者负责。

绘本

如果 books/<book>/style.json 尚不存在，请先按 stories.md 中的故事采集流程开始；商定模型（intake.md）并编写 style.json。然后按照工作顺序进行：先向用户展示剧本和分镜，再构建任何内容；接着创建图书文件夹（site.md）、制作声音、布景和场景，进行审阅轮次，最后让用户观看初剪。每集为一章（chNN）；系列共用角色阵容、布景和系列页面。

纪录片

如果 books/<book>/style.json 尚不存在，请先按 documentary.md 中的采集流程开始。然后按照工作顺序进行：研究，向用户展示剧本和分镜，使用 assets/templates/documentary/ 中的文件夹（site.md），寻找并处理图片，制作配音和音乐，制作节拍，进行审阅轮次，最后让用户观看。书架上的 《疯狂与文明》 是获批参考作品；《射象》（site/shooting-an-elephant/）是互动作品，读者可以开枪（互动环节）。

短视频

如果 books/<book>/style.json 尚不存在，请先回答 shorts.md 中的问题；用户的大纲应先于任何剧本（将长片重新剪辑为短视频时，大纲就是长片本身：从长片改编）。然后按照工作顺序进行：与用户逐个节拍编写剧本，制作分镜和图片，在竖屏舞台上使用 assets/templates/shorts/ 中的文件夹，调整配音和音乐音量，制作节拍，进行导演审看并让用户观看，最后使用 export.py 导出 1080 × 1920 视频。*《疯狂与文明》*第 1 集 《船》（site/madness-shorts/）是完整示例。

脚本

所有脚本都位于 SKILL/scripts/；每个脚本都可通过 --help 显示用法（使用其文档字符串中指定的 uv run --with … 运行）。

用途	脚本
所有图书	serve.py 不缓存预览 · engine.py 将引擎同步到图书目录 · tts.py 旁白和词语时间 · lint.py 静态检查 · shot.py 节拍截图 · strip.py 分镜表和运动条 · still.py 拉伸静止画面 · perf.py Firefox 帧耗时 · export.py MP4 和 .srt · level.py 均衡响度
课程	outline.py 和 split_pages.py 页面映射和章节文本 · check_blank.py 空白开场 · overlap.py 穿过文本的箭头 · sprites.py 图片处理步骤
绘本	mouths.py 嘴形 · join.py 每个场景合并为一个片段 · sfx.py 合成音效 · playlog.py 对照画面的声音和字幕 · bake_sets.py 布景图层 · bake_puppets.py 木偶位图 · paint.py / paint_openai.py 图像模型图片 · painted.py 将图片放入图书
纪录片	commons.py 公共领域图片和录音及其许可 · prep.py 印刷和线条处理 · trace.py 自行绘制的图画 · video.py 根据静止画面制作片段 · frames.py 将片段处理为帧 · eleven.py ElevenLabs 旁白和词语时间 · music.py 为影片剪辑的音乐曲目，以及配音空隙中的背景音乐 · safe.py 竖屏影片安全区域之外的文字
课程选项	refs.py 已验证的引用 · items.py 题库 · scorm.py LMS 包

silence.py、ledger.py 和 browsers.py 是其他脚本导入的辅助脚本。

背景

• 在主对话中与用户交流：接收需求，以及试播的每张表单和每项选择。有子 Agent 可用时，按团队方式制作章节：章节循环的每一步都使用一个新的工作者，并使用用户为该步骤选择的模型（style.json 中的 models），逐章推进；绘本则按场景拆分，纪录片则按影片部分拆分。主对话负责协调试播，因为用户能看到其中的表单；之后的章节最好在新会话中协调（team.md）。没有子 Agent 时，在当前 Agent 中使用基于文件的状态运行相同的循环。
• 工作者只需少量资料，除了此 Skill 和 style.json，还需要用户的话语、外观设定、供查看和阅读的已批准章节，以及元素库。简报应补充章节、页面、该步骤的输入和输出，以及用户当前的任何请求。工作者用几行文字回复；协调者登记章节。
• 使用引擎 API，并在需要时检查单个函数；复制素材，而不要把素材的完整源码当作指令来阅读。
• 保持 style.json 内容简短且为最新状态。章节状态、勘误和历史反馈保存在 chapters.md 和 chapters/chNN.md 中。