| name | paper-to-html |
| version | 1.0.0 |
| description | 把学术论文 PDF 整理成中文交互式 HTML 笔记页面。三栏 docs 布局（左章节树/中正文/右页内目录），
原图嵌入（自动从 PDF 裁剪），中英对照（可折叠原文引用），交互组件（Step Walker 步骤导览、
Image Hotspot 图上热点、Quiz 理解检查、Mermaid 流程图、Tab 切换）。暗/亮主题切换。
适合个人精读笔记。Use when 用户说"整理论文/写论文笔记/把这篇 paper 做成网页/embodied/VLA 论文解读"。
|
| allowed-tools | ["Bash","Read","Write","Edit","Grep","Glob"] |
paper-to-html
把论文 PDF 转成可交互的中文 HTML 精读页面。这个 skill 抓住的核心痛点是：论文太长不想读、读了记不住、图表看不懂——通过中文导读+原图+点击式交互来解决。
触发场景
- "帮我把这篇 paper 整理成 HTML"
- "做成那种 docs 网站的样式"
- "把论文做成可以交互的笔记"
- 用户已有 paper-notes 类项目，往里加新论文
工作流（必须按顺序）
0. 检查项目结构
如果项目根目录没有以下结构，先建立：
project-root/
├── index.html
├── assets/css/style.css
├── assets/js/theme.js
├── assets/js/interactive.js
├── assets/figures/<paper-slug>/
├── papers/<paper-slug>.html
└── pdfs/<category>/<paper-slug>.pdf
把 assets/css/style.css、assets/js/theme.js、assets/js/interactive.js、templates/paper-template.html 从本 skill 的 assets/ 拷过去（如果用户项目里没有同名同等功能的版本）。
0.5 拿 PDF —— 优先从 Zotero 找，不用等用户手动放
用户只给了论文名/作者而没给 PDF 路径时，先用 zotero skill（.claude/skills/zotero/SKILL.md）
在 ~/Zotero/zotero.sqlite 里按标题/作者搜条目，拿到
~/Zotero/storage/<key>/<file>.pdf 后复制到 pdfs/<category>/<paper-slug>.pdf 再继续。
Zotero 里也没有时才让用户提供 PDF。
1. 读 PDF —— 不要凭印象写
铁律：从来不要凭对作者/领域的"了解"写内容。具体来说：
- 用
Read 工具读 PDF（pages 参数分批，每批 5-15 页）
- 边读边记关键术语原文 + 图编号 + 页码
- 写每节前必须有对应 PDF 段落作为依据
- 引用原文时短引用 + 标 §章节 p.页码
2. 提取并裁剪图
pdfinfo <pdf>
pdftoppm -png -r 150 -f <page> -l <page> <pdf> assets/figures/<slug>/page
sips --cropToHeightWidth <h> <w> --cropOffset <y> <x> <input> --out <output>
python3 -c "
from PIL import Image
img = Image.open('assets/figures/<slug>/page-XX.png')
# 估计图区域 (left, top, right, bottom)，裁掉
img.crop((50, 100, img.width-50, int(img.height*0.65))).save('assets/figures/<slug>/fig-X.png')
"
裁剪后命名：fig-2.png、fig-3.png...（不是 page-XX.png）。这样图和论文 Figure 编号对应。
3. 搭页面骨架
复制 templates/paper-template.html 到 papers/<slug>.html，填入：
<title>- breadcrumb 路径
- 论文标题/作者/年份/版本
- 左章节树（按论文目录结构，用
<details> 折叠）
布局默认 2 栏（左章节树 + 中正文）。右侧页内 TOC 和左章节树在精读笔记场景下高度重复，不要默认加。只有当论文特别长、单章内还要小目录定位时才 opt-in 加 .has-right 类。对应 CSS：
.docs-layout { grid-template-columns: 240px minmax(0, 1fr); max-width: 1280px; }
.docs-layout.has-right { grid-template-columns: 240px minmax(0, 1fr) 220px; max-width: 1400px; }
如果删掉右 TOC，同时把 JS 里 document.getElementById('page-toc') 相关的生成/IntersectionObserver 代码一起删掉。否则 null.querySelectorAll 会把同 <script> 块里的 Tab / Mermaid 逻辑一起搞挂。
4. 逐节写内容（每节都要这五样）
论文五问（★★★ §01 总览必须回答，缺一不可）
每篇论文的 §01 总览必须显式回答以下五个问题 + 数据集交代。推荐固定用一个"五问速答"结构（kv-table 或小节），让读者 2 分钟建立全局：
- 背景：这个问题为什么存在、为什么难？（领域现状，用自己的话讲，不是摘要复述）
- 基于什么工作：论文直接站在哪些前人工作上？（backbone / 控制器 / 数据集 / 范式，逐个点名）
- 前人工作的缺陷：之前的方法具体卡在哪？（从 Intro / Related Work 提炼，必须具体到"哪类方法 + 什么缺陷"，不许写"效果不好"这种空话）
- 他们的 insight：一句话说清核心洞察——最好写成"别人都以为/都在做 X，这篇发现其实 Y"的形式
- 最后效果：关键数字（和谁比、提升多少、代价是什么——数据量/算力/硬件）
数据集必须单独说清楚：训练/评测分别用了哪些数据集；每个数据集是什么（规模、怎么采的、什么模态、谁做的）；分别喂给哪个训练阶段。只报名字不解释 = 没写。
叙事流（★★★ 每节必须承上启下 · 跟着作者思路走）
铁律：笔记不是原论文章节的翻译搬运，是重构后的一条"思想链"。每一节 .cn-read 必须做三件事：
- 承上：一句话说"上一节讲到这里，留了什么问题没解决"
- 启下：一句话说"作者为什么接下来要讲这个，是在回答什么问题"
- 小结：读完本节你能知道什么
这不是凑字数——是把论文作者隐藏的 reasoning chain 显式写出来。论文为了正式性常常跳过动机句（"We now introduce X"），笔记必须把"为什么是 X、不是 Y"讲清楚。
反例警告：这是真实犯过的错。在写 LeCun paper 时，§3.3 讲"四种架构坍缩类型"（概念图），§3.4 讲"对比 vs 正则两种防坍缩思路"（概念图），§3.5 直接跳到 JEPA 架构。读者反馈"章节之间没关联"——因为中间跳过了关键一步：每种架构对应哪种正则器？loss 公式具体长什么样？ 必须补一个 §3.4b 桥段，把"坍缩分类 → 每架构的正则器 → JEPA 架构设计决定"这条链显式写出来。
自查信号：如果你能把本节标题和上一节标题的连接词写成一句话（"因为上节 X，所以本节 Y"），说明链是通的。如果写不出来——要么缺了 bridge section，要么本节位置不对。
常见要补的 bridge 类型：
- 从概念到公式：概念章（e.g. "EBM 的两种训练思路"）后面必须有公式章（"loss 具体长什么样"），不然读者不会写 loss
- 从公式到具体架构：公式章（e.g. "防坍缩正则器的通用形式"）后面要有"每架构对应哪条正则"的映射章
- 从架构到实现：架构图（e.g. "JEPA"）后面要有"工业实现怎么做"（e.g. "VICReg"）
- 章节转场：每个 h2 之间至少一句话 recap 前一章 + 预告本章要回答什么
在 .cn-read 里怎么写：开头直接写"上一节讲了 X、但漏了 Y 没讲——这一节补上"。不要写"本节介绍 X"（那是论文腔，不是笔记腔）。
A. .cn-read 中文导读块（每节开头必须有）
<div class="cn-read">
<div class="cn-label">这一节解决什么</div>
<p>用最白话告诉小白：这一节<strong>在解决什么问题</strong>，结论<strong>是什么</strong>。
避免直接堆术语，先建立直觉。</p>
</div>
B. .en-quote 原文引用（关键论点必须配）
<details class="en-quote">
<summary>展开原文 · <段落主题></summary>
<div class="quote-body">
<p>"短段引用，1-3 句话，**不要整段照抄**"</p>
<div class="quote-cite">— §X.Y, p.N</div>
</div>
</details>
C. .fig-block + Image Hotspot（每张图都要）
必须用 .fig-interactive 把图和 panel 包成 2 栏并排。否则图在上、panel 在下，用户点完要滚下去看讲解，再滚回图——体验极差（来自用户直接反馈）。
<div class="fig-interactive">
<div class="fig-block">
<div class="hotspot-wrap" data-hotspot-group="figN">
<img src="../assets/figures/<slug>/fig-N.png" alt="Figure N: ...">
<div class="hotspot" data-id="elem1" style="left:50%; top:30%;"
data-title="元素名 · English Name"
data-body="这个元素是什么、为什么重要、怎么和别的元素连接"></div>
</div>
<div class="fig-cap">
<span class="fig-num">Fig N · p.X</span>
论文原文 caption（英文）
<span class="fig-cn">中文翻译/解释</span>
</div>
</div>
<div class="hotspot-panel"></div>
</div>
.fig-interactive 在 ≥1200px 屏幕上是 minmax(0,1fr) 260px 两栏（panel 右侧 sticky 跟随滚动），窄屏自动降级为单列堆叠。样式已在 style.css 里，直接用。
热点视觉平衡：默认 opacity: 0.55、size 20px；hover/active 全不透明放大。不要把 dot 做大做实心——图缩小后会把图本身盖住（用户直接反馈过）。
热点坐标 SOP（★★★ 关键）
不要再凭 Read 看图瞎估坐标。每个新 paper 的新图必须用浏览器里的 edit mode 当场取点。已经在 interactive.js 里实装：
- 页面加
?edit-hotspots=1 query，所有 .hotspot-wrap 进入 edit mode
- 点图任意位置 → 右上角 toast 显示
left:X.X%; top:Y.Y%;，同时写入剪贴板
- 直接粘进 HTML
style="..."，去掉 ?edit-hotspots=1 刷新验证
工作流：先写好所有 hotspot 的 data-title / data-body，坐标先填占位 left:50%; top:50%;，然后开 edit mode 一个个取坐标替换。
别再走"估一轮 → 用户指出错 → 再估一轮"的老路。LeCun 那篇 Fig 8/9/10/11/12 五张图的热点坐标全部一次估偏（panel 区域被当成图，caption 被当成子图），改回来比一次取对贵得多。
D. .step-walker 步骤导览（复杂图必配，关联 hotspot）
<div class="step-walker" data-hotspot-group="figN">
<div class="sw-header">
<div class="sw-title">🪜 跟着信号走一遍</div>
<div class="sw-controls">
<button class="sw-btn prev">◀</button>
<span class="sw-counter">1 / 5</span>
<button class="sw-btn next">▶</button>
</div>
</div>
<div class="sw-progress">
<div class="sw-dot"></div>
</div>
<div class="sw-body">
<div class="sw-step active" data-hotspot="elem1">
<h4>第 1 步：标题</h4>
<p>这一步在做什么、看图哪个地方</p>
</div>
</div>
</div>
E. .quiz 理解检查（每章/每节末尾配 1-2 道）
<div class="quiz"
data-correct="b"
data-explain="解释为什么 b 对，引用论文证据"
data-explain-wrong="解释为什么用户选的不对（点错时显示）">
<div class="q-label">🧠 理解检查</div>
<div class="q-text">问题文本？</div>
<div class="q-options">
<button class="q-opt" data-k="a">选项 A</button>
<button class="q-opt" data-k="b">选项 B（正确）</button>
<button class="q-opt" data-k="c">选项 C</button>
<button class="q-opt" data-k="d">选项 D</button>
</div>
<div class="q-feedback"></div>
</div>
Quiz 设计原则：
- 错的选项要"看似合理"，不能明显错（否则没意义）
- 正确答案的解释要引用论文具体段落
- 测概念理解，不测细节背诵
5. 其他可用组件
.term：行内术语 hover 出英文。<span class="term" data-en="model-predictive control">模型预测控制</span>.tab-switcher：多个并列概念切换（如六大模块定义）- Mermaid：自定义流程图。
<pre class="mermaid">flowchart LR\n A --> B</pre>
.module-grid + .module-card：2 列卡片网格，列举多个并列示例
6. 工作节奏（重要）
绝对不要一次写完整篇 60 页论文。会失控、会瞎编、用户没法验证。
正确节奏：
- 先读 §1-§2（前 10-15 页），建立全文结构理解
- 写出布局骨架 + §1 总览给用户看
- 用户确认方向 → 写 §2，先做一节当样板
- 用户确认样板 OK → 按同样模式扩到其他章节
- 每写完 1-2 节就停下让用户看效果
- 改交互细节（热点位置、步骤数、quiz 难度）时只改一个地方测，不要批量
7. 提交粒度
每完成一个有意义的单元就 git commit：
- "feat(): 三栏布局骨架 + §1 总览"
- "feat(): §2 架构 + Fig 2 hotspot + step walker"
- "feat(): §3 JEPA + Fig 8/9/10"
- "fix(): Fig 2 热点坐标修正"
反模式（不要做）
- ❌ 凭对作者/领域的"印象"写内容，没读 PDF
- ❌ 一次性写完所有章节再给用户看
- ❌ 自己用 SVG 重画论文图（用户原话："会不准确"）
- ❌ 长段引用论文原文（短引 + 页码）
- ❌ 中文导读用术语堆砌，没有"小白能秒懂的类比"
- ❌ Step Walker 没关联 hotspot，纯文字流程
- ❌ Quiz 答案明显，没有迷惑性
- ❌ 不裁图直接用整页 PNG（百分比坐标会全错）
- ❌ 图和
.hotspot-panel 上下堆（用户点热点要滚下去看讲解，体验崩）——必须 .fig-interactive 并排
- ❌ 凭
Read 看裁剪图瞎估热点坐标——用 ?edit-hotspots=1 edit mode 当场取
- ❌ 热点 dot 做大做实心——图缩小后会遮图，默认半透明 + hover 放大
- ❌ 默认开三栏布局（左 tree + 右 TOC）——右 TOC 和左 tree 重复，默认两栏就够
- ❌ 删右 TOC aside 时漏删
#page-toc 的 JS（会 null.querySelectorAll 把同 script 块其他功能搞挂）
验证清单（每节写完自查）
项目脚手架（首次用）
如果用户项目还没建立基础，按本 skill 同目录 assets/ 和 templates/ 拷贝以下文件：
style.css（含三栏布局 + 暗亮主题 + 所有交互组件样式）theme.js（暗亮主题切换 + localStorage 持久化）interactive.js（Step Walker / Hotspot / Quiz 逻辑）paper-template.html（论文页骨架）index-template.html（首页骨架，按方向分组）
之后每篇新论文只需复制 paper-template.html 改内容。
