paper-deck-reveal

# paper-deck-reveal 把一篇学术论文做成**可汇报的 reveal.js HTML 成片**：逐页 Markdown 文字稿（内容先于形式）→ 套一套精调过的安静奢华设计语言渲染成离线 HTML deck → 在实验页**内嵌活交互**（复刻被试流程，或让听众亲做任务）→ 把脱稿讲稿写进 speaker notes → 支持演讲者双屏。产出经多 Agent 审到**论文级**（经得起实证主义导师逐字挑刺）。 这套方法与资产由两个真实验证案例反复返工提炼：**案例 A** ＝ 多实验中介篇（"Sad Art"，Venkatesan et al. 2025）、**案例 B** ＝ 单研究反转篇（Grisanzio et al. 2020）。下文及各 reference 中的 SadArt / Grisanzio 均指这两个案例——它们是规则的证据出处与参数化自检样本，不是要复制的模板。**body 是 hub：告诉你做什么、何时读哪个 reference；细节在 references/。** 五条方法论共识已直接内置、零外部依赖（findings-first / 投影字号下限 / quiet luxury / 去 AI 双扫 / 逐页专家精修——源自作者的 pptx 管线方法论 deck-craft，要点已内联进各 reference）；HTML 构建系统、嵌入式交互、双屏、论文级正确性是本 skill 独有。 > 阅读约定：行文中的 D-N / critic #N / Stage X 为构建期决策与评审记录的编号，保留作证据追溯标记（记录本身未随发布）；SubAgent / run_in_background 等编排术语来自 Claude Code 工作流，在其他 agent 环境取其语义等价物（后台任务 / 委派子任务）。 ## 动手前先切换到「创作态」（最高总开关 · 详见 `references/creative_stance.md`） 你不是"把论文转成不会崩的 HTML 的构建者"，你是**为这篇论文创作一场值得被认真观看的汇报的设计师**——成功标准是「无可挑剔」，不是「稳定运行」，「能用了」是失败态。harness 默认把你拉向"执行态"（遇不确定就退回样例→抄上一篇、堆元素、不敢凭品味判断），**对设计是致命的**。动手任何排版前，先读 `references/creative_stance.md` 把自己切到创作态，并记住分寸： > **在构图上像艺术家一样大胆，在手艺上像工匠一样一丝不苟。** 三件事落地（细节在 creative_stance）：① **三层架构**——L1 手艺（色/字/间距/**绝不自绘数据图**）铁板一块、L2 构图（archetype 菜单 + 每 deck 一个 signature 旋钮）大胆求变、L3 让形式追随**这篇**论文的特性（**因论文不同而形式不同**＝成功标准，不是复制上一场）；② **派任何构建 SubAgent，其提示词第一句即 creative_stance §1.2 的「激活咒语」**；③ 收尾走**三遍自检**（字号 / 溢出换行 / 对齐光学居中）。 ## 不可违反的 4 条硬约束（宪法级，最先满足） 1. **内容安全 file→file**：敏感刺激/用户讲稿正文经脚本抽为外置数据文件，HTML 只引用全局变量，**你（及任何子 Agent）绝不直接键入**敏感正文。用 `scripts/extract_stimuli.py` / `scripts/replace_notes_from_md.py`。 2. **零 CDN 离线**：reveal.js 与字体**已内置在 `assets/reveal/` 与 `assets/fonts/`**——装配时 copy 进 deck，绝不引外链；`file://` 双击可放映、0 网络请求。 3. **字体 woff2 本地内嵌**：只 Inter+Fraunces（`assets/fonts/`）；中文走系统 PingFang，**不内嵌**任何设计型中文字体。 4. **交付前论文级正确性门**（不可省）：统计斜体 + APA 引用 + 内容归因核实 + 图表审计 + 引用 DOI 核验——经得起实证主义导师逐字挑刺。见 `references/paper_correctness.md`。 **工序纪律（同等重要）**：改成片前先 `.before-{change}.html` 备份（可一键回滚）；单文件 deck 的**可见层 / `<aside>` notes 层 / iframe 交互层三者分离编辑**，改一层不碰另一层——这是 audit-then-execute 能在单文件 deck 上安全成立的前提。 ## 工作流（内容先于形式；完整依赖图见 `references/pipeline.md`） ``` 论文 →[判特性 + 判结构]→ 逐页 MD 文字稿 →[页型清单]→ 装配 HTML 成片 ├ 交互页 → faithful 组件（读材料 / 行为选择，零结果） └ render-QA #1（装配后） → 演讲稿（路径 A 生成 / 路径 B 用户自写）→ file→note 装入 → render-QA #2 → 三道把关（设计评审·有权打回重做 / render-QA / 正确性门）→ 离线投影就绪成片 ``` **输入判别**：默认入口是论文全文；若用户已有**逐页 MD 文字稿或现成非论文材料**，走 `pipeline.md §0.5` 直接装配入口——跳过判结构与拆解，从页型清单＋装配起步，讲稿/render-QA/三道把关照常，正确性门按输入性质裁剪。 **★ 三道把关缺一不可**（详 `references/pipeline.md §3.5`）：① **设计评审**（"美 / 贴合"，设计师之眼逐页挑刺、**有权打回重做**）② **render-QA**（"崩 / 溢出 / 断链"）③ **正确性门**（"统计 / 引用 / 真图"）。**设计评审是从"能用"到"成片水准"最该补的那道闸**——它把"用户在环逐页挑错"工程化（见 `references/creative_stance.md §6`）；**只跑 render-QA + 正确性门，会交出"初稿即终稿"＝本 skill 定义的失败态**。 **先写逐页 Markdown 内容稿、再套 HTML**——这是被验证的工作流锁定，不是偏好。装配靠 `assets/section_templates.html` **复制填充**（reveal 本身就是 HTML，**不用 build 脚本**）。 ## 上手前先和用户确认这几个参数（写死任一默认都会在别的论文上出错） - **★ 判特性（先于一切）**：先写一句话"**本篇核心张力 / 叙事骨架是什么**"（反转？多实验中介？综述对比？）——它决定整体形式与各页 archetype 的选择。写不出这一句不许动手排版。（这是**设计轨**的第一步，与下条"论文结构"的**内容轨**判断并列、都在动手前，互不替代。）详见 `references/creative_stance.md` §2(L3)/§4。 - **论文结构**：先判体裁（实证 / 理论建模 / 综述 / 方法工具 / 立场论证，见 `paper_decomposition.md §0.5`；实证是一等公民主场景）；实证再判多 Study（→逐实验四段式）还是单一研究（→降级模板）。体裁与结构共同决定走哪套 `md_templates`。 - **每个交互**：忠实还原被试当年看到/操作的**程序本身**（`mode:"faithful"`，纯被试第一人称、零结果、零旁白）。可让听众亲手做任务，但**仍不揭示任何结果**（结果在结果页）。"experiential 揭示结果作高潮"已废弃。务必读 `interactive_components.md` **§0 根本视角**。 - **讲稿路径**：A（AI 生成可改稿）还是 B（用户已自写、整篇 file→note 装入、只修笔误）？B 是首选交付。 - **narration_style**：`objective-with-critical-nodes`（介绍他人成果，默认）/ `argument-driven`（论证自己的切口）/ `user-authored`。 - **强调色**：四入口任选——① 报机构名（查 `references/accent_presets.md` 机构判定表）② 自报 hex（走校验修正流程，不过准入带给修正值、不偷改色相）③ 从 8 预设选 ④ 都不选则默认 `#8B0012` 不动。改色只改 `assets/tokens.css` 三行 `--accent*`（单一真源）；时机在 `pipeline.md §1.5` 外观决策点。 - **thesis_boundary**：是否需要在汇报里回避汇报人自己的研究方向（组会场景常需要）。 ## 何时读哪个 reference（触发式路由） | 当你要…… | 读 | |---|---| | **动手任何设计前（切创作态、判本篇特性、L1/L2/L3 哪层可动、archetype 菜单 / signature、一次成型流程）** | **`references/creative_stance.md`（姿态与架构 authority — 先读它，再读 design_spec）** | | **任何设计 / 版面 / 排版动作（红块、对齐、留白、间距、焦点带、组件库、交付前检查清单、翻车点）** | **`references/design_spec.md`（设计 authority — 第一版就一次成型靠它；冲突时它赢）** | | 不确定整体怎么走 / MD 怎么变成 `<section>` / 文件怎么放 / 验收落点 | `references/pipeline.md` | | 拆论文、写逐页 MD、判结构、做作者页/元数据页 | `references/paper_decomposition.md` | | 定/改设计 token、配色、字体、投影字号（"为什么这样定"） | `references/design_system.md` | | 选页型、排某一页、判某页质量（逐页审核 rubric） | `references/page_types_and_layout.md` | | 做交互、复刻实验流程、体验型交互、刺激 schema | `references/interactive_components.md` | | 双屏不同步 / 焦点丢失 / 方向键串到预览页 | `references/speaker_dual_screen.md` | | 写演讲稿、写 speaker notes、去 AI 味 | `references/speaker_notes_method.md` | | 统计量斜体、APA 引用、内容核实、图表审计、拼图 | `references/paper_correctness.md` | | 验收成片（render-QA 该查什么） | `references/render_qa.md` | | 换一套整体视觉世界观（非默认气质；**experimental**） | `references/worldviews/_index.md`（入口与时机在 `pipeline.md §1.5` 外观决策点） | | 判某页主内容「复用还是生成」、定 craft 权重（两速系统） | `references/reuse_spectrum.md`（世界观子系统 · **experimental**） | | 换肤/换世界观时守哪些科学底线（跨世界冻结不变量） | `references/science_invariants.md`（世界观子系统 · **experimental**；默认 #0 下这些底线由 design_spec / paper_correctness 直接承载） | | 想看「同一套 skill 因论文不同而异形」的实证对照自测 | `references/self_test_two_papers.md` | | 换强调色（机构色 / 自报 hex 校验修正 / 8 预设 / 数据色冲突判定） | `references/accent_presets.md`（可跑工具：`scripts/accent_tools.py`） | ## 你复制进 deck 的 assets / 跑的 scripts **assets/**（复制到 deck）：`tokens.css`(设计 token 单一真源，换肤只改这里) · `theme.css`(设计系统，@import tokens) · `deck_scaffold.html`(index.html 骨架) · `section_templates.html`(7 一级页型+15 子版式骨架) · `interactive_template/{faithful,faithful_choice}.html`+`speaker_sync.js`+`iframe_nav.js` · `reveal_focus_patch.js`(双屏焦点层) · `deck_edit_overlay.js`(**页内审阅 + 直接编辑工具**：注入即用、Shadow DOM 隔离、file:// 离线；**`e` 批注态**〔点元素/选文字写批注 → `a` 总览 → 复制 markdown 交 Agent·复制即清空〕；**`t` 直接编辑态**〔就地改字，localStorage 无感持久·刷新不丢·不必 Agent；FS 写回源文件为可选 opt-in〕) · `reveal/`+`fonts/`(本地内置) · `md_templates/` · `increment_points_template.md`。 **scripts/**：`extract_stimuli.py`(刺激 file→file) · `acquire_stimuli.py`(取 CC 代表性刺激图) · `render_qa.mjs`(Playwright 验收) · `stat_italic_lint.py`(扫裸统计符号) · `accent_tools.py`(强调色准入带校验+三槽推导) · `stitch_panels.py`(PIL 拼图) · `contact_sheet.py`(content-hash 辨图) · `check_notes_voice.py`(去 AI 硬禁忌扫) · `replace_notes_from_md.py`(用户讲稿机械装入，不改原文) · `inject_edit_ids.py`(生成期给可批注元素注入 `data-edit-id` + deck 根 `data-deck-id`；审阅批注工具三层定位的稳定主键，无损幂等)。 ## Gotchas（最高价值——每条都是返工挣来的，别重蹈） - **一致性 > 创新（同类页必须同构）**：结构相同的页面（各实验的目的/设计/结果页）必须用**完全相同的形式**，别给每页换花样——论文重复度高，强行换形式＝制造不一致＝降质。只有内容确实不同（如某实验是全新范式）才允许形式分化，且仍落在同一套组件语言里。改一类页就**一改全改**该类所有平行页（同一组 CSS 类驱动），交付前横向扫同构。完整规则与 12 翻车点见 `references/design_spec.md`（设计 authority）。 - **横贯带要对齐主内容右缘、别让 max-width 卡在中间**：焦点带/注释带/读图提示（`.callout` / 结论带 / `.read-hint` 一族）一律 `max-width:none`，对齐上方卡片/主内容的**右边缘**，绝不在页面中间就收边——通用类上的 em 上限（40em/46em 之类）是"带宽不对齐、卡在中间"的头号根因（design_spec §2 翻车9）。需要更窄由具体页面容器约束，不在通用类设 em 截断。 - **焦点带一律淡粉 + 左红线，无实心红块**：结论/预测/小结回答全用 `--accent-tint` + `border-left` 红线（与 `.callout`/`.sum-answer`/`.concl-band` 同语言）；整块实心红已退役，哪怕"最终结论"也不用（design_spec §1A.4）。**一页只一处粉底**：还要标记第二个块（概念页「本文测的那张」）用白底 + 3px 红顶线 `.focus-topline`，不开第二块粉底（design_spec §1A.5）。 - **页标题全片「红主词 · 灰点 · 黑副题」（`h2.t2`）**：主词是这页的名词、副题是这页的主张或张力（一行装得下）；整句标题不染红。封面默认「框界版心」（两道发丝线只夹标题组，kicker / 出处出框，上下镜像），**h1 是论文完整原题**——不截断、casing 照原文、不给原题加斜体重音；钩子进副题用近黑关键词。元数据页 / 作者页给 section 加 `fill-y`，行块均分页高、不留底部空白（2026-09 自 Claude Design 精修稿同步，见 design_spec §4 组件清单）。 - **被试信息别用一排等宽卡**：用「二级标题 + 紧凑信息行/小表」罗列；四页同模板就是"千篇一律"硬伤。 - **交互 = 还原被试当年真正用的程序本身（§0 根本视角，最高原则）**：判断每个元素只问"被试当年屏上看得到吗"。① 纯被试**第一人称、零旁白**——只放被试屏上所见（指导语/练习/做任务/结束），**绝不**出现"你将作为被试/室内设置/实验员在身后"这类第三方解释；② **结果永不进程序**（无均值/系数/曲线/"你像 X 岁组"——结果归结果页；旧 experiential"揭示结果作高潮"已废弃）；③ **一切说明/方法学/标签/版权声明/效价界定移到观众层**（设计页 / slide 小注 / 讲者备注），被试看不到的就不进程序；④ **删到不能再删**（如无必要勿增实体，第一版必过量、复盘就是删）；⑤ **动画极简**，选中只用红框、无悬浮上浮/阴影/花哨过渡。Grisanzio 连栽两轮（结果揭晓秀 + 旁白/标签堆砌）才逼出这条。 - **刺激/讲稿正文 file→file**，你绝不直接键入敏感正文（内容安全 + 单一真源）。 - **强调色 <5%**：红稀释即失效，只点睛关键数字/主线/焦点；底色永远纯白/灰。 - **统计斜体只用 `<em>`**：别用整块 `.stat`/`.bv` 套斜体（会把数字也斜，且斜体来自 class 不是 `<em>`——成片真出过这种"双容器漂移"）。按符号类别逐 token 判：拉丁单字母统计量斜体、希腊 χ²/缩写 ACME/AIC 正体、数字正体。 - **信成片不信规划**：页数/页型数以**渲染后的成片**为准，不以任何文档声称为准。 - **离线只认真外链，别扫裸字**：判据是 `src`/`href` 指向 `http(s)://` 或 `//host` 的资源（`render_qa.mjs` 就这么扫，运行期 `page.on('request')` 是权威判据）——**别用 `grep -i cdn`**：脚手架自带的「零 CDN」注释语义恰好相反，扫裸字只会自伤误报。reveal/字体走内置 assets。 - **改成片前先 `.before-{change}.html` 备份**；单文件 deck 的**可见层 / `<aside>` notes 层 / iframe 交互层三者分离编辑**，改一层不碰另一层。 - **演讲者视图在普通页按 S 开**（在交互页时焦点在 iframe、S 会被接走）。开一次后双屏一直同步。 - **视觉迭代看真实渲染**：每次改版面后用 `render_qa.mjs` 渲染再判，不靠想象。 ## 反过拟合（贯穿全程的头号纪律） 这套资产从**一篇**论文提炼，最大风险是把"这一篇的填充"当普适规律。**普适 = 方法/骨架/护栏进 skill；填充（实验数、强调色、刺激 schema、测量类型、缩写白名单、图清单、配色语义、具体增量点、用户口头禅）一律走参数槽，绝不写死。** 每建一页/一个交互/一段讲稿，问一句"这在另一篇不同范式的论文上还成立吗？要参数化什么？"——一个样本只能定义一个点。 > 本 skill 用 skill-creator 流程构建并经多轮对抗式评审；端到端验证用一篇范式不同的论文（单研究/行为指标/多作者）跑通"判结构→降级模板→faithful 行为选择交互（零结果）→argument 讲稿"。