Animation Html

---
name: animation-html
description: 把一个技术流程、实验、架构或对比做成分步讲解的单文件动画网页（分组步骤条 + SVG 舞台 + 播放条 + 逐段旁白 + 细节与出处 + 参考表，支持像幻灯片一样全屏放映、空格暂停、方向键 / 翻页笔，还能在网页上像 PPT 一样直接编辑）。用户输入 /animation-html <主题> 时使用，也用于「做个动画解释一下」「可视化讲解」这类请求。
---

# animation-html：分步讲解动画网页

做一个**单文件 HTML** 动画：一步一个画面，按时间轴逐步出现，旁白随时间切换，读者可以暂停、拖动、跳步、全屏。目标读者是不熟悉细节的人，所以每一步只讲一件事。

起点模板：`assets/template.html`（本 skill 目录下）。它已经包含全部样式、明暗主题、播放器和键盘逻辑，**只需要填标题、数据和 STEPS**，不要重写播放器。

> 模板固定的是**播放器**，不是**画面**。最常见的失败是每一步都画成“色块分区 + 方框 + 箭头”，或者把模板里 `chip()` `plate()` `beam()` 这些来自光学芯片主题的图元套到不相干的主题上。这样的动画换个主题照样成立，读者看不到这个主题本身长什么样。每一步的 `draw(t)` 要画**这个主题自己的东西**（见“画面规范”第一条）。

## 用法

`/animation-html <主题>`，例如 `/animation-html 解释一下这个训练流程是怎么跑的`。主题不清楚时先问一句「给谁看、讲到多细」；其余按下面流程直接做。

## 流程

0. **定创意方向。** 跑 `python3 <本 skill 目录>/scripts/brief.py "<主题>"`，从视觉隐喻、美术风格、动效语法、叙事结构、旁白语气、配色调整各抽一项，想清楚怎么落到这个主题上（冲突的项可重抽或改，写明理由）。目标是每个动画在画面、动效、叙事和语气上都是新的，不是上一个动画换了文字。
1. **弄清要讲什么。** 读相关代码、日志、CSV、论文，列出 6~12 步的大纲，每步一句话。按「问题 → 原理 / 结构 → 怎么做 → 结果 → 例子」组织，用 `g` 分组。
2. **准备数据。** 画面里的数字、图像、曲线**尽量用真实中间量**（模型输出、训练日志、CSV），写一个构建脚本（Python）生成 `D` 的 JSON，替换模板里的 `/*__DATA__*/{}`。图片转成 base64 PNG data URI 嵌入。没有来源的数字写「UNKNOWN」或「训练中」，**绝不编数字**。
3. **写 STEPS。** 复制模板，在「本动画专用」区写每一步（字段见下）。需要的辅助函数直接在 STEPS 前定义。
4. **生成并自检。** 用 Playwright（Python 或 Node 均可）逐步截图：`go(i); t=STEPS[cur].dur; playing=false; render();` 后截 `.stage`。检查：无 JS 报错、文字不出 viewBox、元素不重叠、明暗模式颜色都可读、画面是不是这个主题自己的对象（不是一屏屏方框箭头）。截图拼成网格自己看一遍再交付。**放映模式也要测**（见「放映模式」一节的自检办法）。
5. **交付。** 说明里写上本次的创意方向（视觉隐喻、风格、动效语法、叙事结构）。把 HTML 文件交给用户（能直接发送文件就发送，否则告诉对方文件路径）。如果数据还在跑，结果步骤要写「训练中」，跑完后重建再发。

文件放在项目里合适的目录：成品 `<主题>_animation.html`，模板另存为 `<主题>_animation.template.html`，构建脚本 `build_<主题>_anim.py`；不在项目里时放临时工作目录。

## 每一步的字段

```js
{g:"章节名", nm:"步骤条短名(≤6字)", title:"大标题：一句话说清这一步", key:"一句话要点（数字结论）", dur:12,
 cap:[[0,"旁白 1"],[4,"旁白 2"],[8,"旁白 3"]],   // 秒数递增；<b>强调</b> <em>警示</em>
 note:"细节与限制：出处（脚本 / CSV / 论文行号）、假设、没算的东西",
 draw(t){ /* 按时间 t 画整帧，每帧都会先清空 */ }}
```

- `dur` 8~22 秒。旁白每段 2~4 秒的画面变化配一句，先说结论再给数字。
- 动态结论（取决于结果的标题、旁白）在 STEPS 之后用一个 IIFE 根据 `D` 改写，结果没出来时显示「训练中」。不利的结果和有利的一起写。

## 画面规范

- **画主题本身**：先列出这个主题里真实存在的对象和数据形态（TCP 讲解里的报文头字段、序号、时间线；训练流程里的张量形状、loss 曲线、真实样本图；分子机理里的原子和键），每一步的画面由它们构成，并让它们动起来（报文沿连线移动、张量被切分、曲线逐点画出）。方框加箭头只用于总览类步骤，全片不超过三分之一。
- 模板里的 `chip()` `plate()` `beam()` `photo()` `boxOn()` 和 `band()` 的 opt/det/ele 四色来自一个光学芯片 / 目标检测的例子：主题相关时才用，不相关就自己写图元（直接用 `el()` 画 SVG），`band()` 的四种颜色按本主题重新定义含义。
- 自检时加一条换皮测试：把标题和旁白换成另一个主题，如果画面照样成立，就回去换成主题自己的对象。
- 画布 `viewBox="0 0 960 500"`，所有元素留在框内（底部文字 y ≤ 470）。
- 颜色**只用 CSS token**（token 名不变，但可以按 brief 在 `:root` 和暗色块里改 token 的取值，形成这一份自己的配色）：`--opt`（蓝）`--det`（紫）`--ele`（橙）`--new`（青，新方案 / 强调）`--bad`（红，错误 / 选中）`--good`（绿，真值 / 正确）`--muted` `--off` `--grid` `--soft`；分区底色 `band(x,y,w,h,"opt"|"det"|"ele"|"new",label)`（四种颜色对应流程里的不同模块，按需要自定含义）。不要写死颜色，否则暗色模式会坏。
- 常用图元（模板已有）：`el(tag, attrs)` 任意 SVG；`tx(x,y,text,attrs)`；`label()` 粗体居中；`chipNote()` 小号注释；`arrow(x1,y1,x2,y2)`；`chip(x,y,w,h,text,color)` 芯片；`plate()` 斜放薄板；`beam()` 光束；`photo(x,y,w)` / `boxOn(box,x,y,w,color)` 画 `D.img` 与框（需 `D.img_w/img_h`）。
- 动画节奏：`seg(t,a,b)` 线性 0→1，`E(t,a,b)` 缓动；元素按旁白顺序进场，不要一开始全部出现。进场方式按 brief 的动效语法选（描线、生长、流动、拆解、推拉 viewBox……），不要每一步都只是淡入加平移。
- **带框的照片一律按原图比例显示**；如果网络输入做过拉伸，展示前把图和框换回原图坐标。
- 数字用 `class:"mono"`；柱状图标数值；有阈值线（如验收线）要画出来并标注。
- 每步只讲一件事；一屏文字不超过三四行。

## 播放器约定（模板已实现，不要改坏）

- 空格：播放 / 暂停（即使焦点在按钮上）。
- →：当前步没放完时先跳到本步结尾并停住，再按一次才进下一步；最后一步结尾不再动作。←：上一步。
- F 或「放映」按钮：进入放映模式（见下节）；Esc 退出。
- 换步后自动开始播放；「播完自动进下一步」默认关，可勾选；速度是滑杆 0.5~4×、默认 2×；URL `#s=3&t=5` 直接定位。
- 按钮是线条图标（上一步 / 播放暂停 / 下一步 / 放映），速度滑杆并在播放条里；换步时标题、字幕、画面淡入。
- 步骤条按 `g` 分组显示进度；下方「这一步的细节与限制」折叠显示 `note`；页底参考表 `#reftab` 放关键数字与出处（不需要可删）。

## 放映模式（模板已实现，不要改坏）

全屏时像幻灯片放映：只留分组名、页码、标题、要点、画面和底部大字幕，顶部一条分段进度。由模板末尾第二个 `<script>`（「UI 精修与放映模式」）实现，`.stage.is-fs` 下的 CSS 控制版面。

- 控制栏在鼠标移动时浮出，静止 2 秒隐去；浮出时字幕上移 76 px 让位，隐去时落回。
- 点击画面 = 下一步（没放完先跳到本步结尾）；PageDown / ↓ / Enter 下一步，PageUp / ↑ 上一步，Home / End 首尾，翻页笔可用。
- 进入时中间提示一次操作方法，2.6 秒后消失。

**三条踩过的坑（改样式时守住）：**

1. **字幕框高度必须按本步最长那句定死。** 每步的字幕会随时间换句，行数一变，字幕框所在的 `auto` 行就变高变矮，`1fr` 的画面行被挤得上下抽搐；字幕框若随文字收缩宽度，换句时文字也会跳。现做法：放映时 `.narr{width:100%}`；每次 `go()` 用一个隐藏的同类元素量出本步所有 `cap` 的高度，取最大值写进 `narr.style.height`。一步之内画面尺寸不变，只在翻页时调整一次。
2. **短句要在定高框里上下居中。** 量高时顺便记下每句的高度，每次 `render()` 按 `(最大高 − 本句高) / 2` 设 `padding-top`。不要用 flex / grid 居中——会把 `<b>` `<em>` 拆成独立块，打乱行内排版。
3. **控制栏常驻只认键盘焦点。** 用 `:has(:focus-visible)`，不要用 `:focus-within`：鼠标点暂停后焦点留在按钮上，`:focus-within` 会让控制栏一直挂着，而字幕已按「鼠标静止」落回原位，两者叠在一起。字幕上移的条件要与控制栏显示的条件一致（`.ui-on` 或 `:has(.player :focus-visible)`）。

**自检办法**（真全屏要用户手势，playwright 里用模拟）：

```js
const st=document.querySelector('.stage'); st.style.cssText='position:fixed;inset:0;z-index:99';
st.classList.add('is-fs'); document.dispatchEvent(new Event('fullscreenchange')); st.classList.add('is-fs');
```

然后对每一步取 40~60 个时刻 `t=s.dur*k/K; render();`，检查：`svg#svg` 与 `#caption` 的尺寸在一步之内不变；`#caption` 不溢出（`scrollHeight ≤ clientHeight`）；文字上下留白相差 ≤ 2 px。再模拟「鼠标移动 → 点 `#play` → 鼠标静止 2.6 秒」，控制栏 opacity 应为 0、字幕 transform 为 none；按 Tab 后两者应同时浮起。至少测 1280×720、1440×900、2000×1250 三种尺寸。

## 网页编辑器（模板自带，不要删）

读者可以像改 PPT 一样直接在网页上改动画：点播放条上的「编辑」或按 **E** 进入，右侧出现编辑面板。

- **改原有元素**：点画面里任意元素选中（Alt+点击 选下面一层），拖动或方向键移动（Shift ×10）；文字可改内容、字号、粗体、颜色，图形可改填充、描边、线宽；Delete 隐藏。改动对这一步的每一帧生效，原来的动画照常播放。
- **加新元素**：文字、方框、椭圆、箭头、图片（图片转成 data URI 存进文件）；可设出现 / 消失秒数、复制（Ctrl+D）、调层级、拖角点改大小。
- **改步骤文字**：分组、短名、标题、要点、时长、旁白（秒数 + 文字）、细节；插入空白步、隐藏 / 恢复步骤。整页大标题和导语也能改。
- **撤销 / 保存**：Ctrl+Z / Ctrl+Shift+Z；Ctrl+S 或「保存」把改动写回 HTML（Chrome / Edge 直接覆盖原文件，其他浏览器下载新文件）。没保存的改动自动暂存在浏览器里，下次打开会提示恢复。

**实现约定（改模板或写构建脚本时要守住）：**

- 改动存在 `<script id="edits" type="application/json">…</script>` 里（单行 JSON，位于主脚本之前）。结构：`{v, page:{h1,lead}, steps:{"分组/短名":{f:{字段覆盖}, hidden, ov:{元素键:{dx,dy,text,fs,fw,fill,stroke,sw,hide}}, add:[新增元素]}}, ins:[{id,after,g}]}`。
- **构建脚本重建 HTML 时必须保留旧文件里的这一段**，否则用户在网页上的修改会被覆盖：

```python
import os, re
if os.path.exists(OUT):
    m = re.search(r'<script id="edits" type="application/json">.*?</script>', open(OUT, encoding="utf-8").read(), re.S)
    if m:
        html = html.replace('<script id="edits" type="application/json">{}</script>', m.group(0), 1)
```

- 原有元素的「元素键」= 画它的那几行代码的位置（相对主脚本第一行的行:列）+ 同一位置第几次调用。所以**改了 STEPS 或辅助函数的代码后，旧的元素改动可能对不上**（新增元素、步骤文字不受影响）。用户在网页上改过之后再要改代码时，先读 `#edits`，把改动并进 STEPS 代码，再清掉对应的 `ov` 条目。
- 步骤键是 `分组/短名`；改了某步的 `g` 或 `nm` 原文，该步的网页改动会失联。
- 保存时以页面加载那一刻的 HTML（`PRISTINE`）为底稿，只替换 `#edits` 这一行。`el()` 只在编辑模式或该步有元素改动时才记录元素键，平时没有额外开销。
- 主脚本末尾的编辑器代码用 `var` 声明状态、在 `edInit()` 里赋初值（`edInit()` 在播放器建立前就被调用），不要改成带初值的声明。
- 改了放映模式或字幕相关的样式后，按「放映模式」一节的办法重测。
- 自检时也测一遍编辑：按 E、点选拖动一个元素、加一个方框、保存，重新打开确认改动还在、控制台无报错。

## 多章节对比（可选）

要对比多个方案（顶部有方案切换标签、数字键 1~6 跳章节）时，在模板基础上加一排 `.tabs` 按钮，每个标签跳到该章节第一步，并在 keydown 里加 `/^[1-9]$/`。

## 写作要求

- 中文、通俗，先结论后数字；关键概念先用大白话说一遍。
- 每个数字可追溯（`note` 写出处）；没有依据写 UNKNOWN，不记成 0。
- 不说「完美」「显著」之类空话；冲突或不利的结果要一起讲。