paper-deck-reveal

name	paper-deck-reveal
description	把一篇学术论文（尤其实证心理学）做成可放映、投影就绪的 reveal.js HTML 汇报成片，含可内嵌幻灯片的「分步交互式实验演示」、去 AI 味演讲者备注、演讲者双屏，全程离线零 CDN。当用户要把论文/文献做成组会汇报、读书会、文献精读、journal club 的幻灯/deck/演示，说「把这篇论文做成 HTML 汇报」「做个能放映的 deck」「复刻实验流程给观众看」「写这篇汇报的演讲稿」，或英文说 "present this paper as a deck / slides for journal club / turn this paper into an interactive presentation" 时都触发，即便只说「帮我汇报这篇论文」。判别：要内嵌活交互、离线 HTML 放映、论文级排版→本 skill；要内容密集的 .pptx 报告成片→deck-craft（同仓 pptx 轨姊妹 skill）；轻量或单文件 .pptx→pptx。不适用：单图表、营销/商业 deck。
license	Apache-2.0. LICENSE.txt has complete terms
compatibility	Requires Node.js 18+ with Playwright (render QA) and Python 3.10+ with Pillow (figure tooling). Built for Claude Code; runs on any agent that loads SKILL.md.
metadata	{"version":"1.1.0"}

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 一级页型+12 子版式骨架) · 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）。
• 被试信息别用一排等宽卡：用「二级标题 + 紧凑信息行/小表」罗列；四页同模板就是"千篇一律"硬伤。
• 交互 = 还原被试当年真正用的程序本身（§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 会被接走）。开一次后双屏一直同步。

反过拟合（贯穿全程的头号纪律）

这套资产从一篇论文提炼，最大风险是把"这一篇的填充"当普适规律。普适 = 方法/骨架/护栏进 skill；填充（实验数、强调色、刺激 schema、测量类型、缩写白名单、图清单、配色语义、具体增量点、用户口头禅）一律走参数槽，绝不写死。 每建一页/一个交互/一段讲稿，问一句"这在另一篇不同范式的论文上还成立吗？要参数化什么？"——一个样本只能定义一个点。

本 skill 用 skill-creator 流程构建并经多轮对抗式评审；端到端验证用一篇范式不同的论文（单研究/行为指标/多作者）跑通"判结构→降级模板→faithful 行为选择交互（零结果）→argument 讲稿"。