# Paper Explainer

> >

- **Type:** Skill
- **Install:** `agentstack add skill-zju-real-easel-paper-explainer`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [ZJU-REAL](https://agentstack.voostack.com/s/zju-real)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [ZJU-REAL](https://github.com/ZJU-REAL)
- **Source:** https://github.com/ZJU-REAL/Easel/tree/main/skills/openclaw/paper-explainer
- **Website:** https://zju-real.github.io/Easel/

## Install

```sh
agentstack add skill-zju-real-easel-paper-explainer
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 科研论文解读（论文 → 视频 / 图文）

> 把一篇论文讲成普通人/同行都爱看的视频号视频或图文。核心中间产物是一份
> **结构化 asset library**（一次解析+提炼，视频与图文两条产线共用，不重复调 LLM）。
> 确定性 IO（拉论文/解析 PDF/骨架）走 `scripts/paper_ingest.py`；**提炼与分镜脚本由你 LLM 完成**——这是本 SKILL 的核心价值。

> 视频转图文（反向）见 **video-to-article**；纯格式转换见 **doc-convert**；
> 只做图表见 **chart-visualization / infographic**；发视频号见 **skill-channels-upload**。

## 输入

| 字段 | 必填 | 说明 |
|------|------|------|
| 论文 | 是 | arxiv id（2401.12345）/ arxiv 链接 / 本地 PDF 路径（没给就问） |
| 目标形态 | 否 | 视频（默认，视频号/B站）/ 图文（知乎/公众号）/ 两者都要 |
| 视频画幅 | 视频时必填 | 用户或上游任务未明确横版/竖版（或 16:9/9:16/具体分辨率）时，进入视频制作前必须追问并等确认；不得按平台、Profile 或默认值静默推断，已明确则不重复问 |
| 受众深度 | 否 | 大众科普（默认）/ 同行向（更专业） |
| 时长 | 否 | 视频默认 2–4 分钟（视频号中视频） |

## 产物结构（`outputs/论文简称/`）

```
article.md               图文版（知乎/公众号）
final.mp4                成片
assets/                  paper.pdf / parsed/ / asset-library.json / script.md
  slide-plan.json        结构化分页（页面唯一输入，口播与屏幕文字分离）
  slides/                稳定渲染的逐页 PNG + HTML + audit report
  slides-contact-sheet.jpg  整套视觉复核图
```

脚本（相对项目根）：`paper_ingest.py`（解析）+ `render_slides.py`（分页校验/渲染/审计）。

## 执行步骤

### 1. 取原文 + 解析

1. **环境自检**：`python skills/openclaw/paper-explainer/scripts/paper_ingest.py check`
   （看 pdfplumber / MinerU token / 代理；缺 pdfplumber 则 `pip install pdfplumber`）。
2. **拉论文**：`paper_ingest.py fetch --paper  -o outputs/论文简称/assets/paper.pdf`。
3. **解析**：`paper_ingest.py parse -i outputs/论文简称/assets/paper.pdf -o outputs/论文简称/assets/parsed/`
   （有 `MINERU_API_TOKEN` 走 MinerU 含公式/图表结构化，否则 pdfplumber 纯文本 + 尽力抽图）。

### 2. 结构化提炼（你来做，核心）

4. 生成骨架：`paper_ingest.py skeleton -o outputs/论文简称/assets/asset-library.json`。
5. 读 `assets/parsed/content.*`，按 `references/paper-distill-schema.md` 填满 `assets/asset-library.json`：
   `one_liner`（一句话讲清干了啥）、`problem`/`prior_gap`、`contributions`（≤3 条）、
   `method`（含**通俗类比** analogy）、`key_figures`（挑 2–4 张关键图，每张写 `plain` 大白话解释）、
   `results`（含关键数字）、`limitations`、`takeaway`、`terms`（术语通俗表）。
   **通俗化方法**见 `references/explain-methodology.md`（公式/图表→大白话、类比法、避免堆术语）。
6. **忠于原文**：不夸大、不编造结论；拿不准的地方标注，别臆测（学术内容错了会被同行抓）。

### 3A. 视频产线（视频号/B站）

7. **分镜脚本**：按 `references/video-storyboard.md` 结构（钩子→问题→已有不足→贡献→方法一图讲清→结果→意义）把 asset-library 写成 `assets/script.md`。
   分镜/留存/口播节奏**复用 video-script** 的方法（喂论文语境）。可选**双人问答口播**（主持人提问+讲解者回答）比单人旁白更抓耳——用双人时把口播写成逐行 `lines.json`（`{speaker,text,emotion}`，speaker=主讲/提问）。
8. **视觉素材盘点 + 配图**：先列出每页的视觉角色（证据图/重绘图/概念线稿/字体图形/motif），再写 slide-plan。论文原图从 `assets/parsed/figures/` 选用；复杂原图先裁关键区域，方法流程/结果图用 **infographic / chart-visualization** 重绘。封面/概念页缺图时，主动找或制作与主题直接相关的线稿、局部图或符号素材，不用随机机器人/blob 填空。图中文字在目标分辨率不可读就不得直接使用。
9. **稳定 slide 产线（强制，不得在 outputs 临时写 make_slides 脚本）**：先读 [card-design](../card-design/SKILL.md) 的设计原则和 `references/slide-design.md`，把 script 写成 `assets/slide-plan.json`。把用户/Profile/参考图的原始风格意图原样写入 `style`，再分别选 `base_style`、`treatment`、`theme`、`motif` 和视觉素材来实现；不得把用户风格强行归为某个预设，也不得因没有同名预设而拒绝。迁移的是可观察特征（氛围、配色、线条、纹理、构图、角色/物件素材），不是穷举风格名。未指定风格时用 `editorial`，但默认也必须有明确的编辑网格、纸张层次、章节锚点和图片框法，不得交付“素底 + 字”。整套锁定一个设计立场，页面骨架与审计门保持稳定。运行：
   ```bash
   python skills/openclaw/paper-explainer/scripts/render_slides.py validate --plan outputs//assets/slide-plan.json
   python skills/openclaw/paper-explainer/scripts/render_slides.py render --plan outputs//assets/slide-plan.json --out-dir outputs//assets/slides
   python skills/openclaw/paper-explainer/scripts/render_slides.py audit --plan outputs//assets/slide-plan.json --slides-dir outputs//assets/slides --contact-sheet outputs//assets/slides-contact-sheet.jpg
   ```
   任一非 0 退出必须改 plan 后重渲；`validate` 会按页面职能拦截“只有口号、缺少解释”的低信息页，并检查合并主题后所有正文色在实际背景上的对比度；明亮 accent 可继续用于装饰，文字会使用可读的语义前景色。`render` 会硬拦文字/元素越界、重叠、组内不对齐、卡内文字左边漂移与结构页过度空洞。脚本全过后当前 Agent **必须肉眼查看 contact sheet 和至少 3 张原尺寸 slide**，检查暂停/静音时页面能否独立读懂、论文图可读、文字是否和所属元素对齐、留白是否有叙事作用、视觉素材是否相关、节奏是否重复；只过脚本不等于合格。不要把 narration 整段搬上屏。只有论文图本身承载主要信息时才可在该页设 `density: visual`，不得把它当作跳过内容提炼的开关。
10. **成片（配音+字幕+合成，缺一不可）**：从 slide-plan 的 narration 生成口播——单人用 **tts-voiceover**，双人用 **multi-voice-dubbing**；同步 SRT，缺则跑 **auto-subtitle**。把 `assets/slides/slide_*.png`、配音和字幕写入 auto-short-video storyboard 后合成，必须设顶层 `"image_motion": "static"`；slide/图表禁用 Ken Burns，不得缩放、平移或裁掉边缘。页面停留时长按对应 narration 音频/字幕分段，不均分整轨。不能只交静态图或无声视频。
11. 用 `manifest.py meta` 登记 `final.mp4` 或 `article.md` 为 deliverable；中间解析、slide 和音频只放 `assets/`。
12. **发布**：交 **skill-channels-upload**（视频号）/ B站 biliup。

### 3B. 图文产线（知乎/公众号）

13. 用**同一份 asset-library** 写 `article.md`：标题（钩子）+ 用大白话讲清 problem→method→results→takeaway，配 `assets/` 的图。
    平台适配见 `references/platform-adapt.md`（知乎逻辑链、公众号成文起承转合）。排版/长图交 **doc-convert**；发布交 **skill-zhihu-publisher / skill-wechat-publisher**。

## Profile 感知

- **有 Profile**：`platforms.md` 定主平台并给出形态/画幅/时长建议，但视频画幅仍须用户确认；`audience.md` 定受众深度（大众 vs 同行）；`style.md` 定讲解调性；`identity.md` 定领域垂类（AI/生物/材料…影响类比取材）。
- **无 Profile**：默认视频号 2–4 分钟中视频、大众科普深度，先问领域与受众。

## 规则

1. **忠于原文**：不夸大贡献、不编造数字/结论；术语拿不准先查原文，别臆测。
2. **一次提炼、两处复用**：asset-library.json 是唯一真相源，视频与图文都从它出，避免重复提炼与口径不一。
3. **通俗但不失真**：用类比降低门槛，但类比不能扭曲原意；关键术语给一句通俗解释而非回避。
4. **图优先**：论文靠图讲方法/结果，视频/图文尽量用图（原图或重绘信息图）承载信息。
5. **刻意不做**：数字人讲座（太重）、依赖 LaTeX 源（从 PDF 入覆盖更广）。
6. **页面不是口播稿，也不是口号板**：一页一个中心结论，但必须用解释、证据或数字口径让页面在暂停/静音时也能独立读懂；细节留给 narration，不得靠缩小字号容纳过量文字。

## 参考来源

见 `EASEL-META.md`。流程沉淀自 QuZhan51496/paper2anything（本身即 Claude Skills：parse_pdf/MinerU + 提炼方法论外置 references + 多形态扇出）、
showlab/Paper2Video（按内容块切段、字幕先行）、Paper2Poster（结构化 asset library 中间产物）、
Azzedde/paper_to_podcast（双人问答口播）、OpenDCAI/Paper2Any（一次解析扇出多形态）。

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [ZJU-REAL](https://github.com/ZJU-REAL)
- **Source:** [ZJU-REAL/Easel](https://github.com/ZJU-REAL/Easel)
- **License:** Apache-2.0
- **Homepage:** https://zju-real.github.io/Easel/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-zju-real-easel-paper-explainer
- Seller: https://agentstack.voostack.com/s/zju-real
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.