tech-talk-deck：单文件 HTML 技术讲解 deck

基于 skJack/kelip-slide（MIT）改造，原名 kelip-slide；来源和改动见 UPSTREAM.md。

一个 deck.html + 一个 media/ 目录，Chrome 双击打开，方向键翻页，断网可用。 为直接发出去看设计：读者没有讲解、没有画外音，一页要自己说清楚。机制图想画就画、视频能嵌、改一行字不用重新导出。

这个 skill 固定两样东西：版式框架（CSS 变量、舞台缩放、导航、键位、图卡自适应、渲染自查）和 写页规则（下面标了「硬规则」的几节，是反复被读者纠正后沉淀下来的）。标了「建议」的段落可以按项目推翻； 项目自己的 AGENTS.md / CLAUDE.md / 风格约定优先于这里的默认值。 为什么定这些规则、好坏例子对照，见 references/style.md；换配色、字号、比例看 references/customize.md。

快速开始

mkdir -p <项目>/deck/media && cd <项目>/deck
cp ~/.claude/skills/tech-talk-deck/assets/deck-template.html deck.html
cp ~/.claude/skills/tech-talk-deck/assets/{render_pages.sh,render_preview.py,check_arrows.py} .

模板里每种页型都有一个填好的示例页（按注释编号找，长什么样见 assets/page-types.png； 示例页用的猫图在 assets/media/，换成自己的素材）。删掉用不上的，逐页填。 每页的 data-sec（段名）和 data-title（列表里显示的标题）都要填，左上角的导航面板靠它分组。

动手前先列施工图：说明.md 里一张「页 | 段 | 这页要解决什么 | 结论 | 主体是什么图」的表。 「这页要解决什么」那一列填不出来的页，说明它没有存在的理由。

键位（模板内置，一般不用改）：→ 空格 ↓ 下一页，← ↑ 上一页，Home/End 首尾， 数字键跳页，F 全屏，C 页码，G 或左上角 ☰ 展开页面列表，分步高亮页 J/K 走步。点击页面不翻页（防误触），只用键盘或左上 ‹ ›。 地址栏 deck.html#10 直接开第 10 页，?nav=1 打开时展开列表。

版式系统（框架固定的部分）

• 舞台：#stage 是固定的 1920×1080，JS 按窗口 Math.min(w/1920,h/1080) 等比缩放。 所以所有尺寸都按 1920×1080 写死，不用写响应式。
• 默认视觉（全部是 :root 变量，组件只引用变量）：
  • 暖纸底 --bg:#F3EFE6，舞台铺 120px 浅网格；墨字 --ink:#1C1B19，次要 --muted:#6E685E；卡片 --card:#FBF8F2。
  • 一个强调色赭橙 --accent:#C2410C，一页只点一处；第二强调 --accent2 和 --good / --bad 少用。
  • kicker 用等宽字、强调色。
  • 图示五色语义 --c-io / --c-linear / --c-core / --c-ffn / --c-norm / --c-cond，一种颜色只代表一类模块，全篇一致（表见 references/svg.md）。
  • 备选主题：<html data-theme="keynote"> 切回上游的苹果浅灰风（浅灰底、蓝强调、无网格）。
• 字号下限：标题 68px、sub 30px、讲稿 26px、图内标注 ≥ 22px，任何文字 ≥ 22px（代码 18px 例外）。 装不下就拆页，不缩字号。
• 一页的构造，顺序固定：

kicker    <b>02</b>段名 · 这页的出处 / 口径 / 限定     24px 等宽，强调色
h1        标题：先目的，再做法或结论                     68px
sub       一行，图页必填（这张图看哪里）                 30px 灰
主体      图 / 自绘 SVG / 表 / 长度条 / 大字，占满剩下的空间
talk      讲稿块，每个内容页必填，2–4 句                 26px 灰，左侧强调色竖线

• 图卡自己贴合图片比例：.fig.card 的尺寸由 JS（fitFigs）按图片真实宽高算， 宽图不会上下留大片空白。所以别给 .fig 写死宽高，也别把图卡再包一层 div—— 只有 .slide > .fig 和 .slide > .fig2 > .fig 这两层会被处理。

页型速查

还有 .grid2 / .grid4（图或视频的网格，.ph 单元裁切填满 + 左下角标签）、 .cards（并排大卡）、.steps（四步条）、.code2（代码卡）、.eq（HTML 排公式）、.src（右下角出处小字）也在模板 CSS 里，直接用。

每页怎么写（硬规则）

做第一版就照做，不要等读者来纠正。每条的理由和正反例见 references/style.md。

1. 标题先说目的，再说做法；不直接甩操作名或效果。 一页按 目的 → 限制 → 做法 → 效果 排： 这一步要达到什么 → 卡在哪 → 所以怎么做 → 换来什么。 「要把图送进语言模型：先减数量，再换空间」好过「2×2 合并 + MLP 投影到 4096 维」； 读者看到操作名会问「为啥要做这个」。限制和效果写在 sub / talk 或图上，标题装不下就只留目的 + 做法。
2. 结论先行。 标题、sub、talk 的第一句都写结论，不写栏目名（「实验结果」「方法概述」）也不写过程。
3. 图先全出，再逐项高亮。 一张图一出现就是完整的；分步页按 J 只移动高亮，不让元素一批批冒出来。 说明文字不能先于它描述的图——「两根条一样长」必须在条画出来之后出现。
4. 页上不写自我批判、修正史、免责声明。 不信的数字就别写，而不是写上去再附一句「此数可能偏低」。 口径说明（分母是什么、按什么算、示意还是实测）照常写进 kicker——那是方法交代，不是免责。
5. 数字画成图，不做数字卡页。 不做「几个方块各放一个数字」的汇总页：比例画成长度（.bars）， 数量画成格子，过程画成中间状态。精确对照才用表。
6. 当页定义。 页上出现的每个符号、缩写、指标、组件名，在当页给一句话定义或公式， 不假设读者记得前文，也不用对话里的内部代号。公式每个符号用大白话说一遍；抽象概念先给直觉（示意图 / 几何图 / 伪代码），再给公式。
7. 多用真实素材。 论文原图、真实输入输出、真实例子优先于方块箭头；不批量套「一页三张横卡」。 讲一个方法不能只放一张架构图：输入怎么进、怎么训、怎么推、数据怎么造各配示意，再附效果。 流程图从真实原始输入画起，每个中间量标出处，张量形状就近标各维含义。
8. 颜色有语义且全篇一致。 五色语义按 references/svg.md 的表用，同一颜色在全篇只表达一种含义， 图上或 sub 里写图例（「橙框 = 本页主角」）。
9. 每页只留独有信息。 和前后页重复的页直接删；只讲和主线对象一致的实验；不做「小结」「谢谢」页。
10. 读者追问某页 = 这页没讲清。 回答完直接改那页（补 sub、改标题、加一句 talk），重新截图自查， 再一两句说明改了哪页；不要以「要不要我改？」收尾。点出一种改法并说「同类页都改」时，所有同类页一起改。

图页 sub 必填、每页带讲稿（硬规则）

这个 deck 是发出去让人自己看的，不录屏、没有人在旁边讲。所以：

• 凡是主体是图 / 视频的页（一图页、两图并排、图片网格、视频页、自绘 SVG），.sub 必填， 一行写「这张图看哪里」：横轴纵轴是什么、哪条线是本文、在哪个位置能看出标题说的结论。 标题说结论，sub 指路，缺一个读者就得猜。
• 每个内容页末尾放一块 .talk（封面、过渡页、满屏播片除外），2–4 句、≤ 120 字， 写的是本来要口头讲的话：这页为什么重要、和上一页的关系、容易看错的地方。 <b> 加粗关键词，<span class="acc"> 点一个数。不重复标题和 sub 已经说过的。
• .talk 放在主体块之后、</section> 之前，flex:none，图卡会自动让出高度。 讲稿超过 4 句说明这页塞了两个点，拆页。
• 验收：把 kicker + 标题 + sub + talk 单独读一遍，不看图也知道这页在说什么，才算过。

代码解读页（硬规则）

只要一页在讲代码——读源码、解释某个函数、对照实现——就用 .cx 这一种排法，不用裸 .code2， 不用截图，不把解释塞进代码注释里。长什么样见 assets/page-types.png 第 15 格。

• 左边 .code：代码卡，.tt 写「类名.方法名」，<pre> 里逐行放代码。要解读的行整行包进 <span class="hb|ho|hg|hp">（蓝 / 橙 / 绿 / 紫），一段逻辑一种颜色，连续几行同色； 不解读的行不加色，跳过的行用 <span class="c"># ... 同样拆头 (B, 24, N, 64)</span> 一行带过，形状写在注释尾巴上。
• 右边 .notes：一张 .note.b|o|g|p 对应一种颜色，.h 一句标题（这段做了什么），.d 一两句解释， 行内 <code> 写变量名和形状。颜色靠卡片左边色条对应，.h 不写「蓝：」「橙：」这类颜色名前缀。
• 顺序对齐是硬约束：色块在代码里从上到下第一次出现的顺序，必须等于右边卡片从上到下的顺序， 颜色固定按 蓝 → 橙 → 绿 → 紫 的次序用。一段代码后面又回到前面的颜色就说明分段不对，拆成两页。
• 一页最多 4 段、代码 ≤ 18 行（含注释和空行）。超了就拆页，kicker 写「源码 1/3」「源码 2/3」串起来； 代码超宽就删无关参数、换行对齐，不缩字号。不直观的行在注释卡里逐行解释。
• kicker 写文件名和行号区间（attention_processor.py:1436-1498），标题写这段代码的结论， sub 写这页要说明什么、重点看哪几行；不写「代码解读」四个字。

素材与用词（硬规则）

• 截论文原图时，标题或 kicker 要写明模型名（如 Qwen-Image-Edit · 图 3），不能只写「论文图」。 放进页前先对照原文核对：截的确实是这篇、这张图（图号、标题、坐标轴对得上）。
• 结构图、流程图里不写句子：块内只放模块名、编号、短标签，解释放 .sub 和 .talk。
• 不编造：没有原文或实测支撑的数字不上页；示意数字在 kicker 标「示意」或「按公式算」，估读的标 ≈。

自查回路（这一步别跳，但只看改过的页）

默认只截改过的页，不整本渲染。 整本 deck 反复开 headless Chrome 会把本机 CPU 打满。 用户报问题时会点名是哪页：只改那一页，不顺手重生成、重截无关页。 改页从本地源改：直接改 deck.html 里那一页的结构，不要截图再按图反推怎么改；截图只用来验收。

有自绘 SVG 的先跑箭头检查（便宜），报 ✗ 的全部改掉再截图：

python3 check_arrows.py deck.html

它按浏览器实际排版量每根带箭头的线：头部悬空 / 扎进块里 / 打偏 / 穿过别的块或文字报 ✗， 没对准块的中线报 △（多根箭头扇入扇出时的错开不报）。△ 逐条看，是故意的就留着。

改完页后，只截这几页，逐页串行：

./render_pages.sh 57 58 59      # → /tmp/deck-pages/slide-57.png ...

然后用 Read 亲自看每一张：图是不是顶到卡边 / 卡片是不是空了一半 / 表格有没有挤成一团 / 标题有没有压住图 / 有没有小于 22px 的字 / 分步高亮页第 0 步是不是完整的图。有问题改完只重截这一页。 分步高亮页要看某一步，用 ?anim=2#14 打开。 改过的页没看过渲染图不算做完。

整本渲染只在两种情况用：新 deck 第一次搭完，或用户明确要求全量检查。只跑一次、前台跑：

python3 render_preview.py deck.html <页数> /tmp/deck-render 1 \
  && cp /tmp/deck-render/contact.png 预览-全部页面.png

它逐页截 1920×1080 再拼成 4 列缩略图，Read 打开 contact.png 一页页对，单页放大看 /tmp/deck-render/slide-NN.png。

两个脚本都要装在默认位置的 Google Chrome（路径不同用 CHROME=/path/to/chrome 指定）， render_preview.py 另需 PIL（pip install pillow）。

内容怎么排（建议，按需推翻）

• 标题里 <span class="thin"> 压灰次要的半句，<span class="acc"> 点一个数字或一个词——一页最多点一处。
• 一页一个点，装不下就拆页，不塞。一页的信息量 ≈ 读 20–60 秒的量。
• 主体块跟素材走：有现成好图就用图；没有现成图（产品 / 新闻 / 自家工作）就自绘 SVG。
• 结构：封面 → 背景 / 时间线 2–3 页 → 分段主体（每段 4–6 页，按「目的 → 限制 → 做法 → 效果」推进， 段与段之间用「但是……所以……」接上）→ 局限 / 启示，讲完就停。 23 页（单主题）到 42 页（一次讲五六个）都正常；段数 ≥ 6 时每段前加一页 .divider 过渡。
• 出处写进 kicker（· 论文图 2、· 官方文档、· 2026-09-22 查），或用右下角 .src 小字。

交付物

deck/
  deck.html            单文件，所有 CSS/JS 内联
  media/               图片、视频，全部本地化（deck 里不引外链）
  render_pages.sh      单页截图自查
  render_preview.py    整本渲染（首次搭完用）
  check_arrows.py      箭头检查
  说明.md              施工图（页码对应表）+ 自绘页画了什么 + 素材来源 + 重跑命令（讲稿在页上的 .talk）
  预览-全部页面.png     contact sheet

不自动导出 PDF / PPTX，用户明确要时再出（做法见 references/customize.md）。

常见坑

• 箭头别手写坐标：给块加 id，箭头写成 <path data-from="块id" data-to="块id" class="ar" marker-end="url(#ar)">， 模板 JS 按块的实际位置算端点，挪块箭头跟着走。要绕开中间的块用 data-route，见 references/svg.md。
• 箭头 <marker> 必须定义在 #stage 开头的全局 svg 里。放进某一页的 svg， 那页 display:none 时所有页的箭头会一起消失。
• 自绘图配色用类（b-core、t-mute、ar……），不写死色值，换主题时图才跟着变。
• .diagbox.pad 的留边只能写 inset:0;margin:auto;width:calc(100% - 88px);height:calc(100% - 68px)； 写成 inset:34px 44px + width:100% 会把右边距顶掉、图向右溢出 44px。
• 视频用 muted loop playsinline preload="auto"，翻页时 JS 会重置并预加载下一页的； 满屏 .film 页才加 controls。浏览器不允许带声音自动播，别去掉 muted。
• 中文字体链以 PingFang SC 打头；SVG 里的 <text> 要挂在 class="sv" 的元素下， 否则 headless Chrome 渲染时会掉成衬线体。公式用 .eq 的 HTML 排版（斜体变量、<sub>/<sup>），不用 LaTeX。
• 截图用 --force-device-scale-factor=1 就够，调到 2 只是文件更大。

更多

• references/style.md — 写页规则的理由、正反例、视觉 token 的来历
• references/svg.md — 自绘图：坐标系、五色语义配色类、字号表、四种画法、箭头自动连线、分步高亮、两个必踩的坑
• references/media.md — 素材：PDF 转图、裁白边拼图、切视频、网页截图、封面图条
• references/customize.md — 改造：换主题 / 配色 / 字体 / 比例、加页码、改键位、导出 PDF