Communitygithub.com

step-animation

把任何学习材料(一段讲义或文章的文字、一个概念或公式、一个流程、一段代码或算法、一份文件如 .md/.pdf/.docx/.pptx/.txt/.csv)做成一个独立的「分步动画」HTML 网页:用小的数字格子演示数据,数字从输入格子飞到结果格子,橙框标正在读、蓝框标正在写,每一步显示对应的原文句子/公式/代码行和一句大白话,自动播放、可暂停/上一步/下一步/调速。当用户说「用动画讲给我听」「做成分步演示」「这个我看不懂,一步一步演示」「把这个讲义/这份文件做成动画网页」或者要把学习内容可视化成逐步动画时使用。

step-animation 是什么?

step-animation is a Claude Code agent skill that 把任何学习材料(一段讲义或文章的文字、一个概念或公式、一个流程、一段代码或算法、一份文件如 .md/.pdf/.docx/.pptx/.txt/.csv)做成一个独立的「分步动画」HTML 网页:用小的数字格子演示数据,数字从输入格子飞到结果格子,橙框标正在读、蓝框标正在写,每一步显示对应的原文句子/公式/代码行和一句大白话,自动播放、可暂停/上一步/下一步/调速。当用户说「用动画讲给我听」「做成分步演示」「这个我看不懂,一步一步演示」「把这个讲义/这份文件做成动画网页」或者要把学习内容可视化成逐步动画时使用。.

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Rinta13795/step-animation-skill/tree/HEAD

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

分步动画学习网页

给一段学习材料,生成一个独立的 HTML 文件(双击就能打开,不联网),让学习者一步一步看懂。 材料不限于代码:讲义或文章里的一段话、一个概念(复利、梯度下降、TCP 握手)、一个公式、一个流程、一份文件都可以——只要里面有「一步一步发生的变化」,就能拆成动画。 效果:小格子里的数字 → 飞到结果格子;橙框 = 正在读,蓝框 = 正在写;底下是当前代码行 + 一句大白话;自动播放,停留时间按说明文字长短算;← → 翻步,空格暂停。

本目录:

  • engine/engine.js、engine/engine.css:引擎(格子、框、飞行数字、指针、变量面板、表格、折线图、播放器、自检)。不要改引擎来适配某一节课,课程里的东西都写在课程文件里。
  • build.mjs:把「课程文件 + 引擎」拼成一个独立 HTML。
  • check.mjs:无界面打开网页的 ?check 模式,每一步都跑一遍,打印问题。
  • tools/snap.mjs:给指定的步骤截图,用来自己看一眼效果。
  • template/lesson.js:课程文件骨架,从这里开始写。
  • reference/api.md:引擎全部函数的说明(写课程前读一遍)。
  • examples/:compound-interest.lesson.js(复利,输入只有一段文字、没有代码)、binary-search.lesson.js(二分查找,含图表)、bubble-sort.lesson.js(冒泡排序,含交换动画)、sliding-window.lesson.js(滑动窗口)。写新课程前至少看一个和材料类型接近的。

流程

0. 拿到材料

  • 用户直接贴的文字、代码:直接用。
  • 给的是文件:先完整读一遍。.md/.txt/.csv/代码文件直接读;.pdf/.docx/.pptx 用能读这些格式的工具或 skill 读出文字(扫描版 PDF 先 OCR)。材料很长时,先列出里面的知识点让用户挑要做哪几个,或者按章节一节一节做。
  • 材料里有数据(表格、CSV、实验结果):把要用的数据直接写成 JS 数组常量放进课程文件。
  • 先判断材料里什么在一步一步变化:代码是变量和数组;概念讲解里通常是数量(钱、温度、概率)、状态(排队的人、网络包)、或者一张表格。演示的就是这个东西怎么变。

1. 读材料,拆成「节 → 步」

  • 节(上方标签)= 一个独立的小知识点:一个函数、一个循环、一张图怎么读。第 0 节通常讲「数据长什么样」(比如「图片就是一张数字表格」「列表就是一排格子」)。
  • 步 = 一个动作:一次读取、一次计算、一次比较、一次写入。一步只讲一件事。
  • 循环:一轮里有几行有新东西的代码,就拆成几步(比如「更新 s」「更新 best」是两步)。轮数多时,前 1~2 轮细拆,后面每轮合成一步;再多就「……一直重复……」直接跳到关键的一轮。
  • 一节 315 步比较合适。整个网页 310 节。
  • 最后一节可以是「读图 / 看结果」:嵌入真实数据画折线图,回答材料里的问题。

2. 先用 JS 把材料里的计算真的跑一遍

网页上出现的每一个数字都要是算出来的,不要手填。做法:在课程文件里用 JS 实现同样的算法,记下 trace(每一步的中间值),再按 trace 生成步骤(见 examples/binary-search.lesson.js 的 trace() 和 searchScene())。要嵌入真实数据(CSV、实验结果)时,把数据直接写成 JS 数组常量放进课程文件。

3. 选演示用的小数据

  • 用很小的数据:图片用 3×4、4×4 的表格,数组 5~12 个数。真实规模写在说明里(「真实是 8 行 9 列,这里用 2 行 4 列演示,道理一样」)。
  • 数字要挑得好算、能看出规律:比如 10、20、200 而不是 137、59。
  • 舞台宽度大约 900px:一排格子 × 格子边长不要超过 ~850px(12 格 × 54px 正好)。

4. 写每一步的 c(代码)和 p(说明)

  • c:这一步对应的原文。材料是代码时,就是正在执行的那一行(或几行)代码,原样照抄;可以在后面用 → 或 # 写出这一步的结果,比如 'img[0, 2] → 200'。 材料是文字、概念或文件时,写这一步对应的原文那句话(用「」括起来)、公式或规则,比如 '「每年的利息会加进本金,下一年连利息一起生利息」'、'本金 × (1 + 10%)'(见 examples/compound-interest.lesson.js)。
    • 代码是一个完整函数/循环时,给这一节写 code: '整段代码',然后每步的 c 写行号(从 1 数),比如 c: [5, 7],网页会显示整段代码并高亮这几行。
  • p:一两句大白话,说清「这一步在干什么、得到了什么」。规则:
    • 不堆术语;必须出现的术语,后面马上用大白话解释一次。
    • 学习者懂 Java / C:能类比就类比(「相当于 C 的 unsigned char img[3][4]」「append = Java 的 list.add」「// 是整除,和 Java 两个 int 相除一样」)。
    • 写出具体的数和算式:「(10 + 10 + 10 + 10) ÷ 4 = 10」,比「求平均」好懂得多。
    • 用 <b>…</b> 标出这一步最关键的几个字(显示成橙色),<code>…</code> 标代码。
    • 说明里的数字用模板字符串从 trace 里取,不手写。
  • 停留时间自动按 p 的长度算(4 秒 + 每字 70ms)。动画本身很长(比如画一条 2.5 秒的折线)时加 wait: 2500。

5. 写每一步的 run(S)

  • build() 只搭舞台:创建格子、结果框、图表,stage.appendChild(...),返回一个对象 S。
  • run(S) 只写这一步的变化(增量)。引擎翻到第 k 步时,会先重新 build(),再瞬间重放第 0 ~ k−1 步,再带动画播放第 k 步——所以每一步不需要也不应该重画前面的结果。
  • 动画写法:
    • 读哪些格子 → frame('a', CO, 格子们)(橙框);写哪个格子 → frame('b', BL, 格子)(蓝框)。同名框会平滑移动过去。
    • 数字移动 → fly(从, 到, '文字', () => 到达后要 set 的值)。结果一定在 then 回调里 set,不要只在 setTimeout 里 set。
    • 多个数先后飞 → 给 fly 传 delay,或用 T(fn, 毫秒);不要直接用 setTimeout(瞬间重放时 T 会立即执行,setTimeout 不会)。
    • 指针(lo / hi / i / j)→ mark('lo', 格子, 'lo', BL);同一格子上多个指针会自动错开,grid 要加 below: 行数 留位置。
    • 图表:chart({...}) 创建,C.line(xs, ys, 颜色) 画线(会逐渐画出来),C.text(x, y, '标注') 写字:会自动上下挪,躲开其他文字、圆点和已经画好的曲线,并拉回边界内。所以先画线、再写标注;标注写在线的后面一步也行。
  • 详细函数表见 reference/api.md。

6. 生成网页

node <本目录>/build.mjs  你的课程.lesson.js   [输出.html]

课程文件放在用户的工作目录里(不要放进本 skill 目录),输出的 HTML 和它放在一起。

7. 自检(必须做,不能跳过)

自检会把每一节的每一步都跑两遍:瞬间模式查布局,带动画(8 倍速)查回调报错和「动画播完的画面和瞬间重放是否一致」。会报告:

  • 报错:JS 异常(包括动画回调里的);
  • 标注重叠:文字标签、格子、指针、图表文字互相压住;
  • 标注压住圆点 / 标注压线:图表文字压在圆点、圆圈或曲线上;
  • 超出画布 / 超出图表:东西伸出舞台或 SVG,被裁掉看不见;
  • 框没对准:框或指针没有对准它要指的格子;
  • 文字撑出格子:数字太长,格子装不下;
  • 重放不一致:只在动画里 set、瞬间重放时没 set 的值(会导致按「上一步」时画面不对);
  • 缺内容:某一步没有 c 或 p、某一节 steps 是空的,或者课程文件有语法错误(这时一节都读不到)。

怎么跑(任选一种):

  • 有 Node 和 Chrome/Edge:node <本目录>/check.mjs 输出.html(退出码 0 = 通过),再加 --width 760 跑一次窄屏。 如果它报「缺少 puppeteer-core」,在本 skill 目录运行一次 npm install(这是唯一需要在 skill 目录里做的改动)。
  • 有浏览器工具(如 Claude 的内置浏览器):打开 file:///…/输出.html?check,等页面顶部出现「✅ 自检通过」或「❌ 自检发现 N 个问题」;也可以执行 JS 读 window.__CHECK__({ok, steps, problems})。
  • 都没有:告诉用户用浏览器打开 输出.html?check 看顶部报告。

有问题就改课程文件 → 重新 build → 重新 check,直到通过。然后再截几张图自己看一眼:

node <本目录>/tools/snap.mjs 输出.html 截图目录 0:1 1:5 3:2 [--width 760]

节:步 里,节 = 上方标签从左数第几个(最左边是 0,不管标签上写的是「0」还是「①」);步 = 网页右下角「第 k / n 步」的 k。比如「① 找 77」是第 2 个标签,它的第 5 步写 1:5。 自检查不出「数字算错」「说明和画面对不上」「看起来挤」这类问题,要靠截图看。

8. 交付

告诉用户 HTML 的路径、一共几节几步、自检结果。不要在网页里放真实的个人信息、公司名、内网地址或真实监控画面;演示数据用编出来的小数字。

常见坑

  • build() 里不要调用 fly/frame/mark:那时元素还没布局好。
  • 改格子、结果框、变量、表格的内容,一律用 G.set / valBox.set / vars.set / table.add,不要直接改 textContent:引擎靠这些函数知道布局变了,好让框和指针跟着挪。
  • 课程代码会被包在自己的作用域里运行,起什么变量名、函数名都不会和引擎冲突;LESSON 会被自动交给引擎。
  • 每步的 run 里的 if (!INST) 分支只能放纯装饰(比如额外的飞行效果),不能 set 任何最终状态。
  • 一个格子里的文字很长(比如 16 位哈希)→ 用 valBox 并设置 {w: 宽度, fs: 字号},或者截短显示。
  • 横轴最右边的刻度文字和轴名字会挤:引擎已经把轴名放在刻度下面居中。自己加的标注先交给 C.text 自动避让;如果自检还报重叠/压线(比如曲线很密、没空地方),再手动换一个空白处的坐标。
  • 二维数据:grid([[...],[...]]);一维:grid([...]) 也可以,取格子用 G.c(列) 或 G.c(行, 列)。

相关技能