update genek skills: paper-2-all with pptx-playbook and qa-checklists

Made-with: Cursor

genek-paper-2-all/SKILL.md

@@ -1,11 +1,19 @@
 ---
 name: genek-paper-2-all
-description: 从论文生成海报、网页版 PPT、PPTX 的统一 pipeline。内容一致，海报使用原图，slides 和 PPT 使用拆分后的 panel 图。当用户提及"论文转海报"、"论文转PPT"、"学术海报"、"网页PPT"时使用此技能。
+description: 从论文生成 HTML 海报和 PPTX 的统一 pipeline。海报使用原图，PPT 使用拆分后的 panel 图。当用户提及"论文转海报"、"论文转PPT"、"学术海报"、"论文转网页"时使用此技能。
 ---
 
 # Paper2All 统一 Pipeline
 
-从单篇论文生成三种展示格式，**内容一致**。图片策略：**海报使用原图**（`figures/fig{N}.png`），**slides 和 PPT 使用拆分后的 panel 图**（`figures/panels/`）。
+从单篇论文生成两种展示格式，**内容一致**。图片策略：**海报（HTML）使用原图**（`figures/fig{N}.png`），**PPT 使用拆分后的 panel 图**（`figures/panels/`）。
+
+网页展示统一采用 poster 布局（三列 Grid + 交互组件），不再单独生成 slides 页面。
+
+## 适用边界（职责分层）
+
+- `genek-paper-2-all` 只定义 **What**（内容结构、映射规则、命名规范、验收门禁）
+- `pptx` skill 负责 **How**（具体排版渲染与 PPT 文件生成）
+- `genek-paper-2-all` 不重复实现 `pptx` 内部逻辑，只通过契约调用
 
 ## 目录结构（按论文隔离）
 
@@ -21,12 +29,30 @@ papers/
     │       ├── fig1_A.png                   (拆分后的 panel)
     │       ├── fig1_BC.png
     │       └── ...
-    ├── poster.html
-    ├── slides.html
+    ├── poster.html                          (网页海报，唯一的 HTML 输出)
     ├── create_pptx.js
     └── presentation.pptx
 ```
 
+## 最小可执行流程（MVP）
+
+本节是执行入口。满足前置条件后，按 S0-S6 顺序执行。
+
+| 步骤 | 目标 | 输入 | 输出 | 成功判据 |
+|------|------|------|------|----------|
+| **S0** | 建立论文目录 | `paper.pdf` | `papers/{Author}{Year}/` | 目录结构正确 |
+| **S1** | 抽取结构化内容 | `paper.pdf` | 标题/作者/Background/Design/Methods/Results/Conclusions | 字段齐全，无空段 |
+| **S2** | 提取原图 | `paper.pdf` | `figures/fig1..figN.png` | 图片数与主图数一致 |
+| **S3** | 拆分 panel | `figures/figN.png` | `figures/panels/fig{N}_{group}.png` | 每个 Result 有对应 panel |
+| **S4** | 生成海报 | 结构化内容 + 原图 | `poster.html` | 页面可打开，图文完整 |
+| **S5** | 生成 PPT | 结构化内容 + panel 图 | `presentation.pptx` | 可打开，页序与映射一致 |
+| **S6** | QA 门禁 | 两种输出 | 通过/不通过 | 满足本文件 QA Gate |
+
+失败策略：
+- S2 失败：回退到 `genek-extract-figures` 的备选路径
+- S3 失败：允许人工校正 panel 分组后重跑
+- S5 失败：返回到 PPT 契约检查，定位为“输入缺失”或“渲染失败”
+
 ## 五步通用流程
 
 | 步骤 | 内容 | 依赖 |
@@ -34,8 +60,76 @@ papers/
 | **S1** | 阅读论文，提取结构化内容（标题/作者/项目设计/Introduction/Methods/Results/Conclusions） | — |
 | **S2** | 提取 Figure 原图 → `figures/fig1.png` … | `genek-extract-figures` |
 | **S3** | 对每张 Figure 拆分 panel → `figures/panels/fig{N}_{panels}.png` | `genek-split-figures` |
-| **S4** | 用同一份内容 + panel 图生成 poster.html、slides.html、presentation.pptx | 见 [poster-components](references/poster-components.md)、[slides-components](references/slides-components.md)、`pptx` skill |
-| **S5** | 本地预览，检查图片、交互、双语、三格式内容一致 | — |
+| **S4** | 用同一份内容生成 poster.html（原图）和 presentation.pptx（panel 图） | 见 [poster-components](references/poster-components.md)、`pptx` skill |
+| **S5** | 本地预览，检查图片、交互、双语、两格式内容一致 | — |
+
+## PPT 调用契约（核心）
+
+本节是 `genek-paper-2-all` 与 `pptx` skill 的接口定义。`pptx` 侧实现可变化，但契约必须稳定。
+
+### 0) 内容源契约（必须遵守）
+
+- `presentation.pptx` 的文本内容以 `poster.html` 为唯一事实来源（SSOT）
+- 禁止 PPT 与 poster 出现语义漂移：标题、关键发现、结论必须一一可追溯
+- 建议先从 poster 抽取结构化字段，再交给 `pptx` skill 渲染
+
+### 1) 固定输入契约
+
+- 论文目录：`papers/{Author}{Year}/`
+- panel 输入：`papers/{Author}{Year}/figures/panels/*.png`
+- 命名格式：`fig{N}_{GROUP}.png`，例如 `fig3_A.png`、`fig3_BC.png`
+- 结构化内容必须包含：
+  - `title`, `authors`, `affiliation`
+  - `background`, `study_design`, `methods`, `results[]`, `conclusions[]`
+  - `results[]` 中每项需含 `result_id`, `headline`, `key_points`, `source_figure`
+
+### 2) 固定输出契约
+
+- 产物：`papers/{Author}{Year}/presentation.pptx`
+- 平台兼容产物（macOS 默认启用）：
+  - `papers/{Author}{Year}/presentation_keynote_compatible.pptx`
+  - 若 Keynote 仍存在导入问题，额外导出 `papers/{Author}{Year}/presentation_keynote_compatible.ppt`
+- 页序：
+  1. Title
+  2. Background
+  3. Study Design
+  4. Methods
+  5. Result Panels（1 panel = 1 页）
+  6. Conclusion
+  7. End / Acknowledgment（可与 Conclusion 合并）
+
+### 3) panel -> slide 映射规则
+
+- 规则：**1 张 panel 图 = 1 张 Result 幻灯片**
+- 排序：先按 `figN` 数字升序，再按 `GROUP` 字典序（A < B < BC < DEFG）
+- 推荐标题：`Result {k}: {headline}`，副标题显示来源 `Figure {N} / Panel {GROUP}`
+- 详细解读要求（每张子图必须具备）：
+  1. **What is shown**：该子图展示了什么数据/现象
+  2. **Evidence**：关键数值、统计关系或对照结果
+  3. **Biological interpretation**：生物学含义或机制推断
+  4. **Cross-species implication**：跨物种比较下的意义
+  5. **Take-home message**：一句话结论
+- 若 `results[]` 条目数与 panel 数不一致，按以下优先级处理：
+  1. 若 panel 更多：允许复用同一 `headline`，但必须在 notes 标注“same finding, different panel”
+  2. 若 panel 更少：阻断交付，返回“不通过（输入不完整）”
+
+### 4) 双语契约
+
+- 默认模式：英文正文 + 中文 speaker notes
+- 可选模式：双语双套 slides（EN 全套后接 ZH 全套）
+- 必填规则：
+  - 每页必须有英文可读正文
+  - 中文 notes 不得为空（若开启默认模式）
+
+### 5) 错误与降级契约
+
+- 缺失 panel 文件：禁止“空白页占位”，直接 fail-fast
+- panel 文件损坏：跳过该文件并计入错误，最终判定不通过
+- 渲染后页数不一致：按 Gate 判定不通过，不可直接交付
+- macOS 导出策略：
+  - 先生成标准 `presentation.pptx`
+  - 默认执行一次兼容中转导出，生成 `presentation_keynote_compatible.pptx`
+  - 若兼容版仍不可用，再降级导出 `presentation_keynote_compatible.ppt`
 
 ### Panel 命名规范
 
@@ -44,19 +138,20 @@ papers/
 - 单 panel：`fig1_A.png`
 - 多 panel 合并为一组：`fig1_BC.png`、`fig1_DEFG.png`
 
-### 图片使用规则
+### 图片使用规则与 Result 对应关系
 
-| 格式 | 使用图片 | 路径 |
-|------|---------|------|
-| poster.html | **原图** | `figures/fig{N}.png` |
-| slides.html | **panel 图** | `figures/panels/fig{N}_{panels}.png` |
-| presentation.pptx | **panel 图** | `figures/panels/fig{N}_{panels}.png` |
+| 格式 | 使用图片 | 路径 | Result 对应 |
+|------|---------|------|------------|
+| poster.html | **原图** | `figures/fig{N}.png` | **1 张原图 = 1 个 Result 卡片** |
+| presentation.pptx | **panel 图** | `figures/panels/fig{N}_{panels}.png` | **1 张子图 = 1 页 PPT** |
+
+**海报**：每个 Result 卡片对应论文的一张完整 Figure 原图。Result 数量 = 论文主图数量（通常 4–7 张）。海报空间充裕，用原图展示完整 Figure 更直观。
 
-海报空间充裕，用原图展示完整 Figure 更直观；slides/PPT 逐页讲解，用拆分后的 panel 图对应每个 Result 更清晰。
+**PPT**：每页 PPT 对应一张拆分后的 panel 子图，逐张讲解。一张 Figure 可能拆分为多个 panel，因此 PPT 页数通常多于海报 Result 卡片数。PPT 按 panel 粒度展开，便于口头演讲时逐步讲解。
 
 ### 项目设计（Study Design）
 
-从论文 Methods/Results 中提取实验设计信息，以**表格 + 关键统计数字**呈现。三格式均需包含。
+从论文 Methods/Results 中提取实验设计信息，以**表格 + 关键统计数字**呈现。两种格式均需包含。
 
 常见字段（按论文实际内容选取，不同领域可增减）：
 
@@ -106,7 +201,7 @@ Footer   ──────────────────── 全宽 ─
 
 **第 1 行 = 概览行**：Background（Col 1）和 Study Design（Col 2–3）并排，让读者一眼获得研究背景与实验设计全貌。Study Design 跨 2 列以容纳表格和 cladogram。
 
-**第 1 列 Row 2 = Methods**：紧接 Background 下方，优先用流程图替代文字。流程图中每一步必须标注所使用的**软件工具名称**（如 HiC-Pro、Juicer、cooltools、FitHiC 等），便于读者复现。
+**第 1 列 Row 2 = Methods**：紧接 Background 下方，使用**分阶段流程图（Pipeline）**替代文字。分 3 个视觉阶段：Stage 1（实验，深色渐变）→ Stage 2（数据处理，浅灰 + tool-tag 标签）→ Stage 3（多维分析，白底蓝边分组框 + 2×N 分析卡片网格）。每步必须标注所使用的**软件工具名称**（如 HiC-Pro、Juicer、cooltools、FitHiC 等），便于读者复现。详见 [poster-components.md → 分阶段流程图](references/poster-components.md)。
 
 **第 1 列 Row 3 = Conclusions**：紧接 Methods 下方，深色渐变背景 + 编号列表，作为第 1 列的视觉终点。
 
@@ -125,26 +220,26 @@ Footer   ──────────────────── 全宽 ─
 - Conclusions 位于 Col 1 底部，使用**深色渐变背景 + 编号列表**，作为第 1 列视觉终点
 - Footer 包含：数据可用性、致谢/资助、通讯作者联系方式
 
-## 三格式内容映射
+## 两格式内容映射
 
 同一内容在不同格式中的呈现方式：
 
-| 内容 | poster.html | slides.html | presentation.pptx |
-|------|-------------|-------------|--------------------|
-| 标题/作者/单位 | Header 区域 | 标题 slide | Title slide |
-| Background | Row 1 Col 1，含 finding-card 高亮研究空白 | 1–2 页 slide | 1–2 张幻灯片 |
-| 项目设计 | Row 1 Col 2–3，Stat box + 表格（多物种时含 cladogram） | 1 页表格 slide | 1 张表格幻灯片 |
-| Methods | Row 2 Col 1，流程图（每步标注软件工具名） | 1–2 页 slide | 1–2 张幻灯片 |
-| 每个 Result | 编号圆标 + Finding card + **原图**（折叠/展开） | 每 result 1 页，内嵌 **panel 图** | 每 result 1 张，插入 **panel 图** |
-| Conclusions | Row 3 Col 1，深色渐变背景，编号列表 | 总结 slide | Summary slide |
-| Figure 图片 | **原图** `figures/fig{N}.png`，折叠 + Lightbox | **panel 图** `figures/panels/`，内嵌可放大 | **panel 图**，插入幻灯片 |
-| Footer | 数据可用性 / 致谢 / 联系方式 | 末页 slide | 末页幻灯片 |
+| 内容 | poster.html | presentation.pptx |
+|------|-------------|--------------------|
+| 标题/作者/单位 | Header 区域 | Title slide |
+| Background | Row 1 Col 1，含 finding-card 高亮研究空白 | 1–2 张幻灯片 |
+| 项目设计 | Row 1 Col 2–3，Stat box + 表格（多物种时含 cladogram） | 1 张表格幻灯片 |
+| Methods | Row 2 Col 1，分阶段流程图（每步标注软件工具名） | 1–2 张幻灯片 |
+| 每个 Result | 编号圆标 + Finding card + **1 张原图**（折叠/展开）；1 原图 = 1 卡片 | 每 panel 子图 1 页；1 子图 = 1 页 PPT |
+| Conclusions | Row 3 Col 1，深色渐变背景，编号列表 | Summary slide |
+| Figure 图片 | **原图** `figures/fig{N}.png`，折叠 + Lightbox | **panel 图** `figures/panels/`，逐张插入 |
+| Footer | 数据可用性 / 致谢 / 联系方式 | 末页幻灯片 |
 
 ## 双语要求
 
-三种格式均需支持中英文切换：
+两种格式均需支持中英文：
 
-- **poster.html / slides.html**：`data-lang="en"` / `data-lang="zh"` 标记文本，右上角语言切换按钮，默认英文。
+- **poster.html**：`data-lang="en"` / `data-lang="zh"` 标记文本，右上角语言切换按钮，默认英文。
 - **presentation.pptx**：在 speaker notes 中放中文翻译，或按需生成两套 slide（先英文再中文）。
 
 ## 依赖 skill
@@ -155,5 +250,58 @@ Footer   ──────────────────── 全宽 ─
 
 ## 组件与参考
 
-- 海报：布局与交互组件 → [references/poster-components.md](references/poster-components.md)
-- 网页 PPT：翻页、全屏、slide 类型 → [references/slides-components.md](references/slides-components.md)
+- 海报布局与交互组件 → [references/poster-components.md](references/poster-components.md)
+- PPT 调用手册（参数、重试、问题排查）→ [references/pptx-playbook.md](references/pptx-playbook.md)
+- 统一 QA 门禁清单 → [references/qa-checklists.md](references/qa-checklists.md)
+
+## QA 门禁（交付前必须通过）
+
+满足以下全部条件才可交付：
+
+1) 资产完整性
+- `figures/fig{N}.png` 连续且可读
+- `figures/panels/*.png` 存在且非空
+- 不存在临时/验证残留文件（如 `*_verify.png`）
+
+2) 内容完整性
+- `poster.html` 含 Background / Study Design / Methods / Results / Conclusions / Footer
+- `presentation.pptx` 含 Title / Background / Design / Methods / Result / Conclusion
+- 每个 Result 页至少包含：标题、图、详细解读（建议 4-5 条）
+
+3) 一致性校验
+- 海报 `Result` 卡片与 PPT `Result` 页语义对齐
+- PPT Result 页数 = panel 图数量
+- 编号顺序一致，不跳号
+- 每页可追溯到 poster 对应 Result（标题或备注中标记来源）
+
+4) 版式质量底线
+- 无明显文本溢出/重叠
+- 无占位符残留（如 lorem/xxxx/template text）
+- 无空白结果页、无破图
+
+5) 交付清单
+- 必交付：`poster.html` + `presentation.pptx`
+- macOS 必交付：`poster.html` + `presentation.pptx` + `presentation_keynote_compatible.pptx`
+
+## Li2022 文档级回归模板（示例）
+
+用于验证规范可执行，不要求改动任何其他 skill。
+
+### 输入
+
+- `papers/Li2022/paper.pdf`
+- `papers/Li2022/figures/fig1.png` ... `fig6.png`
+- `papers/Li2022/figures/panels/*.png`（若缺失，先完成 panel 拆分）
+
+### 预期输出
+
+- `papers/Li2022/poster.html`
+- `papers/Li2022/presentation.pptx`
+
+### 抽样验收（最小）
+
+- 随机检查 3 张 Result 幻灯片：
+  - 图像来源是否与 panel 文件一致
+  - 标题与要点是否对应同一发现
+  - 是否存在截断/重叠/空白
+- 若任一项失败，判定回归未通过，需回到契约或 QA Gate 处理

genek-paper-2-all/references/poster-components.md

@@ -336,50 +336,186 @@ HTML 示例（12 物种比较基因组学）：
 
 ---
 
-## CSS 流程图
+## 分阶段流程图（Pipeline）
+
+采用 3 阶段分层设计，避免反复的分支箭头。每个阶段有独立视觉风格：
+
+- **Stage 1（实验）**：深色渐变背景，用 `→` 串联实验步骤
+- **Stage 2（数据处理）**：浅灰背景，tool-tag 标签展示软件工具
+- **Stage 3（多维分析）**：白底蓝边分组框，内含 2×N 网格的分析卡片
+
+```
+┌─────────────────────────────┐
+│ Stage 1 — Experiment        │  ← 深色渐变 (stage-exp)
+│ 实验步骤 → 用箭头串联       │
+└──────────────┬──────────────┘
+               ▼
+┌─────────────────────────────┐
+│ Stage 2 — Data Processing   │  ← 浅灰背景 (stage-proc)
+│ 处理步骤 + tool-tag 标签     │
+└──────────────┬──────────────┘
+               ▼
+┌─ Stage 3 — Analysis ────────┐  ← 白底蓝边 (stage-analysis)
+│ ┌─────────┐ ┌─────────┐    │
+│ │ Card 1  │ │ Card 2  │    │  ← analysis-card 网格
+│ ├─────────┤ ├─────────┤    │     每张卡片不同色彩左边框
+│ │ Card 3  │ │ Card 4  │    │
+│ ├─────────┤ ├─────────┤    │
+│ │ Card 5  │ │ Card 6  │    │
+│ └─────────┘ └─────────┘    │
+└──────────────────────────────┘
+```
+
+### CSS
 
 ```css
-.flowchart {
+.pipeline {
   display: flex; flex-direction: column;
-  align-items: center; gap: 0;
-  margin: 0.1in 0;
+  gap: 0; margin: 0.1in 0;
 }
-.flow-node {
-  background: white; border: 2px solid var(--secondary);
-  border-radius: 0.06in; padding: 0.1in 0.15in;
-  text-align: center; width: 90%;
-  font-size: 0.13in; font-weight: 600;
-  color: var(--primary);
+.pipeline-stage {
+  position: relative;
+  padding: 0.14in;
+  border-radius: 0.06in;
+  margin-bottom: 0;
 }
-.flow-node.primary-node {
-  background: var(--secondary); color: white;
-  border-color: var(--secondary);
+.pipeline-stage.stage-exp {
+  background: linear-gradient(135deg, var(--secondary), var(--primary));
+  color: white;
 }
-.flow-node .flow-detail {
-  font-size: 0.11in; font-weight: 400;
-  color: var(--text-muted); margin-top: 0.03in;
+.pipeline-stage.stage-proc {
+  background: var(--bg-light);
+  border: 1.5px solid #D0D7DE;
 }
-.flow-node.primary-node .flow-detail {
-  color: rgba(255,255,255,0.75);
+.pipeline-stage.stage-analysis {
+  background: white;
+  border: 2px solid var(--secondary);
 }
-.flow-arrow {
-  width: 2px; height: 0.18in;
-  background: var(--secondary); position: relative;
+.stage-label {
+  font-size: 0.1in; font-weight: 700;
+  text-transform: uppercase; letter-spacing: 1.5px;
+  margin-bottom: 0.08in; opacity: 0.7;
 }
-.flow-arrow::after {
+.stage-exp .stage-label { color: rgba(255,255,255,0.7); }
+.stage-proc .stage-label { color: var(--text-muted); }
+.stage-analysis .stage-label { color: var(--secondary); }
+.stage-title {
+  font-family: 'Playfair Display', serif;
+  font-size: 0.2in; font-weight: 700;
+  margin-bottom: 0.04in;
+}
+.stage-exp .stage-title { color: white; }
+.stage-proc .stage-title { color: var(--primary); }
+.stage-detail {
+  font-size: 0.12in; opacity: 0.8; line-height: 1.5;
+}
+.stage-exp .stage-detail { color: rgba(255,255,255,0.8); }
+.stage-proc .stage-detail { color: var(--text-muted); }
+.stage-tools {
+  display: inline-flex; flex-wrap: wrap; gap: 0.04in;
+  margin-top: 0.05in;
+}
+.tool-tag {
+  display: inline-block;
+  font-size: 0.1in; font-weight: 600;
+  padding: 0.02in 0.07in;
+  border-radius: 3px;
+  letter-spacing: 0.3px;
+}
+.stage-exp .tool-tag {
+  background: rgba(255,255,255,0.18); color: white;
+}
+.stage-proc .tool-tag {
+  background: white; color: var(--secondary);
+  border: 1px solid #D0D7DE;
+}
+
+/* 阶段间连接线 */
+.pipeline-connector {
+  display: flex; justify-content: center;
+  padding: 0.04in 0;
+}
+.pipeline-connector .conn-line {
+  width: 2px; height: 0.14in;
+  background: var(--secondary);
+  position: relative;
+}
+.pipeline-connector .conn-line::after {
   content: ''; position: absolute;
-  bottom: -4px; left: -4px;
-  border-left: 5px solid transparent;
-  border-right: 5px solid transparent;
-  border-top: 6px solid var(--secondary);
+  bottom: -4px; left: -3.5px;
+  border-left: 4.5px solid transparent;
+  border-right: 4.5px solid transparent;
+  border-top: 5px solid var(--secondary);
 }
-.flow-branch {
+
+/* 分析卡片网格 */
+.analysis-grid {
   display: grid;
-  grid-template-columns: repeat(auto-fit, minmax(1in, 1fr));
-  gap: 0.08in; width: 100%;
+  grid-template-columns: 1fr 1fr;
+  gap: 0.08in;
+}
+.analysis-card {
+  background: var(--bg-light);
+  border-radius: 0.05in;
+  padding: 0.1in;
+  border-left: 3px solid var(--accent);
 }
+.analysis-card .ac-name {
+  font-size: 0.13in; font-weight: 700;
+  color: var(--primary); margin-bottom: 0.03in;
+}
+.analysis-card .ac-tools {
+  font-size: 0.1in; color: var(--text-muted);
+  line-height: 1.4;
+}
+```
+
+### HTML 示例
+
+```html
+<div class="pipeline">
+  <!-- Stage 1: Experiment -->
+  <div class="pipeline-stage stage-exp">
+    <div class="stage-label">Stage 1 — Experiment</div>
+    <div class="stage-title">Dilution Hi-C + RNA-seq</div>
+    <div class="stage-detail">Formaldehyde crosslinking &#x2192; HindIII digestion &#x2192; Biotin ligation &#x2192; Sequencing</div>
+  </div>
+
+  <div class="pipeline-connector"><div class="conn-line"></div></div>
+
+  <!-- Stage 2: Data Processing -->
+  <div class="pipeline-stage stage-proc">
+    <div class="stage-label">Stage 2 — Data Processing</div>
+    <div class="stage-title">Mapping &#x2192; Filtering &#x2192; Normalization</div>
+    <div class="stage-tools">
+      <span class="tool-tag">Bowtie2</span>
+      <span class="tool-tag">Hiclib</span>
+      <span class="tool-tag">ICE</span>
+    </div>
+  </div>
+
+  <div class="pipeline-connector"><div class="conn-line"></div></div>
+
+  <!-- Stage 3: Multi-dimensional Analysis -->
+  <div class="pipeline-stage stage-analysis">
+    <div class="stage-label">Stage 3 — Multi-dimensional Analysis</div>
+    <div class="analysis-grid">
+      <div class="analysis-card">
+        <div class="ac-name">A/B Compartments</div>
+        <div class="ac-tools">PCA, AB index, Phylo-HMGP</div>
+      </div>
+      <div class="analysis-card">
+        <div class="ac-name">TAD Calling</div>
+        <div class="ac-tools">DomainCaller (DI + HMM)</div>
+      </div>
+      <!-- 按需添加更多 analysis-card -->
+    </div>
+  </div>
+</div>
 ```
 
+分析卡片数量按论文实际分析维度调整（常见 4–6 张），每张卡片可通过 `border-left-color` 赋予独立色彩以区分不同分析类型。
+
 ---
 
 ## 折叠图表

genek-paper-2-all/references/pptx-playbook.md

@@ -0,0 +1,100 @@
+# PPTX 生成操作手册（Paper2All）
+
+本手册用于 `genek-paper-2-all` 调用 `pptx` skill 时的最小执行标准。  
+注意：本手册只定义论文场景规则，不覆盖 `pptx` skill 的通用排版细节。
+
+## 1. 参数约定
+
+建议统一使用以下参数：
+
+| 参数 | 必填 | 默认值 | 说明 |
+|------|------|--------|------|
+| `AUTHOR_YEAR` | 是 | - | 例如 `Li2022` |
+| `LANG_MODE` | 否 | `en_notes_zh` | `en_notes_zh` 或 `dual_slides` |
+| `THEME` | 否 | `scientific_clean` | 与论文主题一致的配色 |
+| `PANEL_SORT` | 否 | `fig_then_group` | `figN` 升序，再 `GROUP` 升序 |
+| `NOTES_MODE` | 否 | `required_zh` | `required_zh` / `optional_zh` |
+
+## 2. 生成前检查（Preflight）
+
+必须全部通过再进入 PPT 生成：
+
+1. 目录存在：`papers/{AUTHOR_YEAR}/`
+2. panel 目录存在：`papers/{AUTHOR_YEAR}/figures/panels/`
+3. panel 命名合法：`fig{N}_{GROUP}.png`
+4. 结构化内容齐全：`title/authors/background/study_design/methods/results/conclusions`
+5. `results` 至少 1 条，且每条有 `headline` 和 `key_points`
+
+## 3. 生成规则（最小）
+
+固定页序建议：
+
+1. Title
+2. Background
+3. Study Design
+4. Methods
+5. Result slides（每张 panel 一页）
+6. Conclusion
+7. End / Acknowledgment
+
+Result 页要求：
+
+- 每页绑定唯一 panel 文件
+- 页标题必须可追溯：`Result {k}` + `Figure {N}/Panel {GROUP}`
+- 每页 2-3 条要点（避免整段长文本）
+
+## 4. 失败重试策略
+
+### A. panel 缺失或不合法
+
+- 行为：立即停止（fail-fast）
+- 处理：回到 panel 拆分流程，修复后重试
+
+### B. 页数与 panel 数不一致
+
+- 行为：判定失败，不交付
+- 处理：检查排序和过滤逻辑，确保 1:1 映射
+
+### C. 中文 notes 缺失（默认模式）
+
+- 行为：判定失败
+- 处理：补齐对应页 notes 后重试导出
+
+## 5. 常见问题速查
+
+| 问题 | 根因 | 修复动作 |
+|------|------|----------|
+| panel 顺序错乱 | 文件排序规则未统一 | 强制 `fig_then_group` 排序 |
+| 图片拉伸 | 未保持纵横比 | 统一等比缩放，保留白边 |
+| 文本溢出 | 单页信息过多 | 压缩要点到 2-3 条，长句拆分 |
+| notes 缺中文 | 仅填英文正文 | 增加中文 notes 校验步骤 |
+| 空白结果页 | panel 路径引用失败 | 检查路径和文件存在性 |
+
+## 6. 最小调用示例（伪流程）
+
+1) 从 `papers/{AUTHOR_YEAR}/figures/panels/` 收集并排序 panel 列表  
+2) 组装幻灯片数据：`meta + sections + result_panels`  
+3) 调用 `pptx` skill 生成 `presentation.pptx`  
+4) 执行 QA：页数、映射、可读性、notes 完整性  
+5) 通过后与 `poster.html` 一并交付
+
+## 7. macOS 兼容导出（默认）
+
+当运行环境为 macOS 时，默认执行兼容导出，减少 Keynote 打开失败风险。
+
+### 标准流程
+
+1. 先生成标准文件：`presentation.pptx`  
+2. 使用 LibreOffice/soffice 进行兼容中转，输出：`presentation_keynote_compatible.pptx`  
+3. 若仍不兼容，再导出：`presentation_keynote_compatible.ppt`
+
+### 建议命令（示例）
+
+```bash
+soffice --headless --convert-to ppt --outdir "papers/${AUTHOR_YEAR}" "papers/${AUTHOR_YEAR}/presentation.pptx"
+soffice --headless --convert-to pptx --outdir "papers/${AUTHOR_YEAR}" "papers/${AUTHOR_YEAR}/presentation_keynote_compatible.ppt"
+```
+
+说明：
+- 兼容中转后务必保留原始 `presentation.pptx`，避免信息丢失
+- 交付时优先提供 `presentation_keynote_compatible.pptx`

genek-paper-2-all/references/qa-checklists.md

@@ -0,0 +1,57 @@
+# Paper2All QA 门禁清单
+
+交付前，按以下清单逐项核对。任一硬门禁失败即不允许交付。
+
+## A. 资产门禁（Hard Gate）
+
+- [ ] `paper.pdf` 存在于 `papers/{AuthorYear}/`
+- [ ] `figures/fig{N}.png` 连续、无缺号、可打开
+- [ ] `figures/panels/*.png` 存在且文件非空
+- [ ] 无临时残留：`tmp-*`、`page-*`、`*_verify.png`
+
+## B. 内容门禁（Hard Gate）
+
+- [ ] `poster.html` 包含：Background / Study Design / Methods / Results / Conclusions / Footer
+- [ ] `presentation.pptx` 包含：Title / Background / Study Design / Methods / Result / Conclusion
+- [ ] 每个 Result 幻灯片包含：标题 + 图 + 2-3 条要点
+- [ ] 无占位文本（例如 lorem、xxxx、template）
+
+## C. 一致性门禁（Hard Gate）
+
+- [ ] PPT Result 页数 = panel 文件数
+- [ ] Result 页编号连续且与 panel 顺序一致
+- [ ] 海报与 PPT 的 Result 语义一致（同编号表达同发现）
+- [ ] Figure/Panel 溯源信息可追踪（至少在标题或备注中体现）
+
+## D. 双语门禁（Conditional Gate）
+
+默认模式 `en_notes_zh`：
+- [ ] 所有页面英文正文可读
+- [ ] 所有页面中文 notes 非空
+
+双套模式 `dual_slides`：
+- [ ] EN 套与 ZH 套页数一致
+- [ ] 同页内容语义一致，无遗漏
+
+## E. 视觉门禁（Soft Gate，建议全通过）
+
+- [ ] 无明显文字溢出/重叠
+- [ ] 图片未被拉伸变形
+- [ ] 字体大小在可读范围（正文建议 >= 14pt）
+- [ ] 关键信息未被页脚或图形遮挡
+
+## F. 交付清单（Hard Gate）
+
+- [ ] `poster.html`
+- [ ] `presentation.pptx`
+- [ ] macOS 环境下额外交付 `presentation_keynote_compatible.pptx`
+
+---
+
+## Li2022 抽样验收模板
+
+最小抽样策略：
+
+1. 随机抽查 3 页 Result 幻灯片  
+2. 每页检查 3 项：图像来源、要点对应性、版式可读性  
+3. 任意一页任一项失败，判定整体验收未通过