An AI skill that turns books into animated, narrated, interactive web experiences
JavaScript ai-agentsai-educationanimationclaudeclaude-codeclaude-skillsedtecheducationinteractive-textbookscormtext-to-video
Add animebook-chapter skill for building chapters
yzra4107cb28075
diff --git a/.claude/skills/animebook-chapter/SKILL.md b/.claude/skills/animebook-chapter/SKILL.mdnew file mode 100644index 0000000..93af75f--- /dev/null+++ b/.claude/skills/animebook-chapter/SKILL.md@@ -0,0 +1,54 @@+---+name: animebook-chapter+description: 为 AnimeBook 制作或修改一章数学动画课:读参考书页、写分镜与英文讲稿、用 Edge TTS 生成逐词对齐的语音、用 SVG 编写动画步骤、设计画面内小测和全屏整章练习、截图审阅并跑浏览器端到端检查。只要在这个仓库里做新章节(ch02…ch68)、改第一章的动画/讲稿/小测/练习、调语音同步、加题型或调播放器,都先用这个技能,即使用户只说“做下一章”“改一下这段动画”“这里加个题”。+---++# AnimeBook 章节制作++第一章 `site/ch01/index.html` 是用户认可的样板(“非常接近我们想要的”)。新章节要达到同样的质量,并沿用同样的交互约定。先读 `plan.md` 和 `CLAUDE.md`;本技能讲的是**怎么做**,以及第一章踩过的坑。++## 用户已拍板的约定(不要回退)++- **一块画面**:整页只有一块 16:9 画面(1600×900 舞台 + 60 高控制条),不在画面外另放练习区。+- **全部在屏幕上完成**:不设纸笔任务。需要示范计算时写成讲解例题。+- **小测插在讲解中途**,只考已经讲过的内容;尽量让学生直接操作画面里的数学对象(点数轴、拖进集合图),而不是只点文字选项。+- **两个练习不能接连出现**(小测后面至少隔一段讲解);例外是结尾的整章练习组。+- **结尾的整章练习**每组全屏,标“Chapter practice N of M”,最后是成绩页。+- **答题有画面动画**:答对让相关数学对象动起来(点跳动、圈层依次亮、画出跳步弧线),答错抖动并给出针对这个错误的解释,可“Show answer”。+- **角色**是 SVG 画的无穷符号 ∞(`mascotEl`),只出现在小测卡片和结束页。不用狗狗素材,不用 π(有知名 YouTuber 在用)。+- **字幕**:CC 按钮或 C 键,默认关,逐句显示旁白;讲解主要靠画面内文字。+- **键盘**:拖拽之外的所有操作都要有快捷键,按钮上标出按键,`?` 列出全部。新题型必须同时给出键盘操作。+- **语言与语气**:先做英文,中文最后补;面向初一左右,语气不幼稚。+- **数学约定**:natural numbers 从 1 开始,whole numbers 含 0;同一个数可属于多个集合。+- **原书只作参考**:不截图、不照搬题干和讲解;读书页时留意原书错误(第一章就有三处),改写时修正并告诉用户。++## 制作流程++1. **读书页**:`book_pages/chNN/`(用 `sections.json` 找页码范围)。列出知识点、原书例题、原书错误和容易超纲的地方。+2. **分镜**:把内容拆成若干“步”(beat),每步一段旁白(通常 5–30 秒)加一组画面动作。确定小测插在哪里、考什么、怎么操作画面对象、答对答错时画面怎么动。大改前把分镜要点给用户过目。+3. **讲稿**:写进 `content/chNN/narration.en.json`。在需要画面同步的词前面放 `[[mark]]`,例如 `"you say [[c1]]one, [[c2]]two"`。旁白要把数学读成口语(“negative seven halves”),画面上再写成符号。+4. **生成语音**(需联网,只重做改动过的步):+ ```sh+ uv run --with edge-tts tools/tts.py content/chNN/narration.en.json site/chNN/audio/en+ ```+ 输出每步 MP3 与 `timings.js`(时长、mark 时间、逐句字幕)。+5. **写步骤代码**:见 `references/engine.md`。动作时间一律用 `m('mark', 偏移)` 或基于时长 `D`,不要手写秒数去猜语音。+6. **截图审阅**:启动 `python3 -m http.server 8765 -d site`,用 `?beat=N&t=秒` 定格任意时刻;逐步看首尾画面,检查遮挡、标签重叠、数学位置是否准确。截图时一次一个浏览器进程(并行会拖慢加载,画面停在半截),`t` 设在淡入完成之后。+7. **端到端检查**:复制并改写 `tools/e2e_ch01.py`(鼠标一遍、纯键盘一遍),每道题都走对、错、看答案三种情况,控制台零报错。+8. **更新文档**:`plan.md` 记录新决定,`CLAUDE.md` 更新目录地图。提交前先问用户。++## 第一章踩过的坑++- **重播靠快进**:跳到第 N 步时,页面重建场景,再把前面每一步的 `run` 以 `evalTo(Infinity)` 瞬间执行一遍。因此 `run` 里只能用补间函数(`tw/prog/show/draw…`)排动作,不能用 `setTimeout`、随机数或读取当前时间,否则跳步后画面和正常播放不一致。交互元素只能在 `ask` 里创建。+- **画面时钟跟随音频**:播放时 `P.t = audio.currentTime`。用 Python `http.server` 测试时,它不支持 Range 请求,给 audio 设 `currentTime` 会跳回开头;测试请让音频自然播完。+- **小测提前继续**:学生答完直接继续时,本步还没播完的补间要先收尾(`evalTo(Infinity)`),否则淡出做一半的东西会残留到下一步。+- **拖拽**:先 `append` 把元素移到最上层,再 `setPointerCapture`;移动 DOM 节点会丢失指针捕获。+- **BEATS 里的对象字面量在定义时求值**:被引用的常量(卡片位置、`$m` 等)必须定义在 `BEATS` 之前。+- **布局分区**(避免挡住数学):数轴 `Y0 = 610`,下方 `BAND` 卡片 y 686–886;数轴场景右上 `TOPR` 卡片不超过 470 高;集合图场景右栏 x ≥ 1258;字幕在 y ≈ 884 之上,小测时自动隐藏。+- **行内数学**用 `mathEl`,基线已和正文对齐;分数、根号、循环节都由 `M()` 绘制,不引入公式库。+- **Playwright 选择器**:`text=Check` 不区分大小写且按子串匹配,会命中“Quick check”;按钮名里带有按键提示(“1Rational”)。请用 CSS 类或序号定位。+- **判题只看数学意义**:分类题按集合判断,顺序无关;不能凭有限位小数断言无理数;分母不能为 0;先化简再归类(√9、12/4)。++## 引擎现状与第二章的前置工作++播放器、绘图、题型、角色目前都写在 `site/ch01/index.html` 里(约 1400 行)。**开始第二章之前,先向用户提议把通用部分抽到 `site/lib/`**:各章只保留自己的 `BEATS`、题目数据和讲稿,不要复制整份文件再改。抽离后第一章必须保持原样:两遍端到端检查都通过,关键步骤的截图一致。用户同意后再动手。diff --git a/.claude/skills/animebook-chapter/references/engine.md b/.claude/skills/animebook-chapter/references/engine.mdnew file mode 100644index 0000000..db4dc26--- /dev/null+++ b/.claude/skills/animebook-chapter/references/engine.md@@ -0,0 +1,58 @@+# 课程引擎速查(以 site/ch01/index.html 为准)++写步骤代码或新题型前先读本文件。函数名如与代码不一致,以代码为准,并顺手更新本文件。++## 舞台与状态++- 舞台为 SVG,`viewBox 0 0 1600 900`,所有动画元素画在 `#scene` 中。HTML 卡片放在 `#ui`,坐标系与舞台相同。+- 每个动画元素带一个状态对象,由 `render()` 写回 DOM:`x y`(平移)、`s`(缩放)、`r`(旋转,度)、`o`(不透明度)、`d`(描边绘制进度 0–1)、`a_<属性>`(数值属性,如 `'a_stroke-width'`)、`c_<属性>`(十六进制颜色)。补间用到的键要先在创建时赋初值。+- 缩放、旋转都绕元素自身原点。所以把内容画在 (0,0) 周围,再用 `x/y` 摆放位置。+- `S` 保存本章跨步骤共用的对象(`S.line`、`S.dots`、`S.ring`、`S.panel`……)。`reset()` 会清空它,需要跨步使用的对象都要登记在 `S` 上。++## 绘图++| 函数 | 用途 |+| --- | --- |+| `G(parent, {x,y,s,r,o})` | 分组 |+| `path(parent, d, attrs, {d:0})` | 路径;传 `d:0` 表示之后用 `draw()` 逐步画出 |+| `T(parent, str, {x,y,size,fill,font,weight,anchor,o})` | 文字(默认 UI 字体) |+| `M(parent, parts, {x,y,size,fill,anchor,o,s})` | 数学式,基线在 y;`parts` 由字符串、`F(n,d)` 分数、`R(x)` 根号组成;返回的元素带 `_w` 宽度 |+| `chip(parent, parts, color, {x,y,size})` | 胶囊形数字卡片,中心在 (x,y) |+| `mathEl(parts, size)` | HTML 行内数学(小 SVG),基线与正文对齐 |+| `rich([...])` | HTML 富文本:字符串、DOM 节点、`$m(...parts)` 行内数学 |++第一章专用:数轴(`X(v)`、`Y0`、`tick`、`dot`)、家族列表 `row`、右侧面板 `panel/header`、集合图(`RINGS`、`CHAIN`、`buildVenn`、`regionAt`)。新章节需要的新场景(坐标系、方程两边等)按同样方式写一组小函数。++## 步骤(BEATS)++```js+['sqrt2', '标题', (m, D) => {+ const p = panel(0); // 面板:先淡出上一个,再新建+ draw(path(S.line, '…', {…}, { d: 0 }), m('sq'), 1.1);+ show(T(p, '…', { o: 0 }), m('dec', 3.6)); // 该 mark 的词开始后 3.6 秒出现+}, { ask: done => quiz(BAND, [问题…], done) }], // 可选:本步是小测+```++- `m(name, 偏移)` 返回讲稿里 `[[name]]` 后第一个词开始的秒数;拼错名字会直接报错。`D` 是本段语音时长。+- 补间函数:`tw(e, to, t0, dur, ease)`、`prog(q => …, t0, dur)`(自定义进度,例如滚动圆、弧线运动)、`show/hide/draw/pop/pulse`、`glow/glowRun`(集合圈描边闪亮)、`stream`(数字逐位出现)。缓动有 `io`、`out`、`back`、`lin`。+- 普通步骤播完自动进入下一步;带 `ask` 的步骤播完旁白后等待学生答完再继续。++## 小测与练习++```js+quiz(位置, [{ id: 'c-xxx', prompt: [...rich], build: 题型(...) }, …], done, 'Quick check')+```++- 位置:`BAND`(数轴下方横条)、`TOPR`(数轴场景右上)、`RIGHT`(集合图右栏)、`SCREEN`(全屏)、`SORT_SCREEN`(全屏集合图分类)。+- `id` 前缀:`c-` 表示讲解中途的小测,`p-` 表示整章练习;结束页按前缀汇总首次作答成绩。+- 题型:+ - `choice(选项, 正确序号, 答对说明, 各选项错因[], 答对动画?)`:单选,数字键作答。+ - `tap(数值[], 正确值, 答对说明, v => 错因, 答对动画?)`:点数轴上的点,←/→ 移动,Enter 选定。+ - `grid(行[{parts, ans:[键], why, fx?}], 列[[键, 名称, 颜色?, 快捷键?]], {multi, text})`:表格勾选,↑/↓ 换行,数字键或字母键选择。+ - `sorter(卡片[[parts, 最小圈, 错因]], i => [x, y])`:拖进集合图,←/→ 挑卡片,1–6 放入圈。+- 新题型的 `build(body, api)` 需返回 `{ reveal, check?, lock?, key?(e), hint? }`,判完调用 `api.grade(是否正确, 说明, {right, total})`。`key` 处理本题快捷键,返回 true 表示已处理;`hint` 显示在题干下方。+- 答题动画使用独立时钟,函数有 `fx`、`fxp`、`pulseFx`、`shakeFx`、`glowFx`、`popDotFx`、`floatText`、`hopsFx`。离开本步时会自动收尾,不必自己清理。++## 播放器++`seek(i, play)` 重建并快进到第 i 步;`start(i, play)` 从当前画面开始第 i 步。`P.keys` 是当前题目的按键处理器,由 `quiz` 设置,由 `clearCards` 清除。字幕数据来自 `TIMINGS[id].cues`。diff --git a/CLAUDE.md b/CLAUDE.mdindex 8cf7771..8f60a3f 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -61,6 +61,7 @@ AnimeBook/├── content/ch01/│ ├── narration.en.json # 第一章英文讲稿(语音源),[[mark]] 标记动画触发词│ └── narration.en.timings.json # tts.py 的缓存,不部署+├── .claude/skills/animebook-chapter/ # 做章节的流程、已定约定、踩过的坑、引擎速查(新章节先读)├── tools/│ ├── tts.py # Edge TTS 生成 MP3 与词级时间点│ └── e2e_ch01.py # 浏览器端到端检查第一章全部流程(Playwright)