pdf-to-interactive-web

PDF → 可交互网页

把一份难读的 PDF 变成一个单文件 HTML 网页：读者花比原文少得多的时间拿到最重要的东西，而且每个数字都能点回原文核对。

这套做法来自一次对照实验：5 种难读的 PDF（小说章节、技术论文、数学教材、上市公司年报、桌游规则书），4 轮提示词迭代，2 个模型，4 轮逐条事实核查。下面每条规则背后都有实验里踩过的坑，原因写在旁边，遇到规则覆盖不到的情况时，按原因去判断。

工作流程

按顺序做。第 3 步（事实账本）最容易被跳过，也最不能跳过。

1. 定范围

• PDF 超过约 30 页时，不要整本做。整本塞进一个网页，只能做成很浅的目录站，失去「读」的体验。先挑一节：自成一体、有画面感、有能动手的东西。用户在场就给 2–3 个候选让他挑；不在场就自己挑，并在交付说明里写明挑了哪段、为什么。
• 用户要的是整本书的地图（人物关系、章节结构）时，做「导览层」，并说明它来自目录或外部知识，不是全文。

2. 读原文，定读法

逐页读，记下页码。图表里的数字也要读：有些关键数字只存在于图片里，不在文字层。

然后判断这份内容主要怎么读，选对应的交互形式。读法定错，后面全错：规则书被做成线性的翻页教程，读者最需要的「随手查」就没了。

内容	读法	主交互
故事、历史、传记	叙事沉浸	沿路线或时间线走，场景随进度切换
概念、原理、定理	概念探索	实验台：改参数、拖节点，马上看到结果
规则、手册、说明书	查读	可搜索的卡片和索引，术语即点即查，查完能回原处
财报、数据报告	数据钻取	先给结论，再一层层往下钻的图表
论文、论证	论证拆解	「问题 → 方法 → 证据 → 结论」的论证地图

可以主次搭配。每种读法的场景模板和交互点子见 references/reading-modes.md。

3. 建事实账本（写页面之前）

把页面要用到的每个数字、引语、人名、年份、规则、因果说法，先列成一张表：id → 原文页码 → 原文原句（保留原语言）→ 你的中文转述。页面里的出处角标就直接引用这张表。

这样做的原因：核查实验里的错误几乎都出在「转述」这一步，不在「读」这一步。模型读对了原句，但在压缩成一句大白话时，把单位换算错、把主客体说反、把例外条件丢掉。先把原句和转述并排写下来，每一条转述都有原句可以对照，这一步就能拦下大部分错误。

转述时逐条对照 references/fidelity-checklist.md 里的 9 类常见错误，规则书和财报尤其要逐条过。

4. 定结构（少而精）

• 首屏是「30 秒版」：一句大白话讲清最重要的结论，配一张全局图（地图、结构图、流程图、论证地图）。读者看完首屏就该知道这份东西讲什么、值不值得往下看。
• 最多 7 个场景。每个场景三层：一句话要点（一直可见）→ 一个能动手的交互（默认展开）→ 细节和原文（默认折叠）。
• 默认可见的文字全篇不超过 2500 个汉字，多出来的放进折叠层。不要用「简洁」「省时间」这种形容词来约束自己，要数字数：实验里只写「省时间」时，字数反而翻倍；写明 2500 字上限，同一章从 11,495 字降到了 2,710 字。
• 术语先打日常比方，再给正式说法。
• 至少 2 处「先猜再看」：先让读者猜一个数或选一个答案，再揭晓原文答案。猜过再看，记得更牢，而且这是最好玩的部分。
• 结尾 3 道「你答得上来吗」，答案附出处。
• 解释用自己的话写，只有原文对照里才引用原句（也避开大段搬运受版权保护的注释和讲解）。

5. 定风格，画主视觉

• 用户给了风格就照做；没给就按内容定一个。全篇的配色、字体、线条、质感保持统一。风格预设见 references/style-presets.md。
• 只画 2–4 幅大的主视觉，挑最关键的时刻，每幅当成独立作品来画：讲究构图、前中后景，把原文写到的细节（器物、服饰、文字、数字、地名）画进去。其余场景用排版、图表和小装饰撑起来。原因：插画数量一多，每幅分到的注意力就少，最后满屏都是草率的小图。
• 不要用圆形、矩形这类基本几何形拼人物，不要卡通脸，不要 emoji。 人物画不好时，改画背影、剪影、局部或器物，或者干脆用排版本身做视觉。
• 写美术方向，不要写技法细节。实验里只写「模拟中国古画」画得比写满白描、界画、SVG 滤镜参数的版本更好：技法写得越细，模型越在意笔触对不对，构图和细节反而弱了。

6. 写页面

按 references/page-contract.md 做：单文件、零外部依赖、出处角标、一键回到原处、记住阅读进度、字号和明暗切换、尊重减弱动画设置、手机竖屏可用。

不需要任何 JS 库。实验里 20 个成品全部手写 SVG、Canvas 和 CSS。

7. 自检，再交付

1. 运行 python3 scripts/audit_html.py <你的 index.html>。它会列出外部资源、默认可见字数、出处角标数量、必备功能是否齐全，以及页面上所有带数字的句子。按报告修。
2. 挑页面上最「硬」的 12 处说法（数字、引语、规则、因果、首屏那句结论），逐条回原文核对。核对不上的，要么改正，要么删掉，要么明确标成「推测」。这一步替代不了读者自己核对，但能挡住最常见的错。
3. 如果能在浏览器里打开，检查控制台没有报错，在手机宽度下没有横向溢出。

交付

• 文件：index.html。
• 给用户 3–5 行说明：读法、场景、2–4 幅主视觉画了什么、原文里有哪些没放进去、哪些内容是推算或示意。
• 提醒一句：关键数字和规则，请点开角标对一下原句。

没有 Skill 的环境

用户如果要在 Gemini、DeepSeek、ChatGPT 这类网页聊天里做，没法装 Skill，就把 references/prompt-standalone.md 里那段提示词给他，附上 PDF 一起发。