paper-interpreter - SKILL.md Agent Skill

name: paper-interpreter description: 深度解读学术论文，将论文 PDF（文件或 URL）转化为通俗易懂、图文并茂的 Markdown 解读文档，保存到项目的 markdown/ 目录。触发条件：用户上传或提供论文 PDF、提到"解读论文"/"读论文"/"分析这篇论文"/"帮我看这篇 paper"，或任何需要深入理解一篇学术论文的场景。即使用户只说"帮我看这个 PDF"但内容是论文，也应使用本 skill。输出文件包含：论文定位、知识地图、5W1H精读、术语词典、批判性评估五大板块，并在关键位置插入 mermaid/svg/text 图表辅助理解。

Paper Interpreter Skill

将学术论文转化为通俗易懂、图文并茂的深度解读文档。

工作流程总览

输入(PDF文件/URL) → 全文提取 → 5步解读 → 输出 Markdown 文件到 markdown/

Step 0：获取论文内容

情况A：用户上传了 PDF 文件

读取路径 /mnt/user-data/uploads/ 下的 PDF 文件，用 bash_tool 提取文本：

pip install pdfminer.six --break-system-packages -q
python3 - <<'EOF'
from pdfminer.high_level import extract_text
text = extract_text("/mnt/user-data/uploads/论文文件名.pdf")
print(text[:50000])  # 先输出前50000字符
EOF

若论文有图表密集或文字提取不完整，追加用 pymupdf 逐页提取并描述图表内容：

pip install pymupdf --break-system-packages -q
python3 - <<'EOF'
import fitz
doc = fitz.open("/mnt/user-data/uploads/论文文件名.pdf")
for i, page in enumerate(doc):
    print(f"\n=== Page {i+1} ===")
    print(page.get_text())
    # 列出图片
    imgs = page.get_images()
    if imgs:
        print(f"[此页含 {len(imgs)} 张图片]")
EOF

情况B：用户提供了 PDF URL

使用 web_fetch 工具抓取 PDF，或者先用 web_search 找到 arXiv/DOI 页面，再抓取 HTML 摘要 + 全文。

web_fetch(url)  →  提取文本内容

重要：提取完成后，记录以下信息备用：

论文标题、作者、发表年份、期刊/会议
摘要（Abstract）
章节结构
所有图表的标题和描述
实验数据和核心结论

Step 1：确定输出路径

mkdir -p markdown
# 文件名格式：论文标题关键词（英文）+ _解读.md
# 例：attention_is_all_you_need_解读.md

Step 2：执行五步解读法，生成 Markdown

按以下结构逐步撰写输出文档。每一步都必须完成，不可跳过。

📍 第0步：论文定位

目标：让读者在30秒内判断"这篇论文值不值得读、跟我有什么关系"。

写法要求：

一句话摘要：用最简单的语言说清楚这篇论文做了什么
价值标注：
- 🎓 学术价值：在学界填补了什么空白 / 突破了什么瓶颈
- 🏭 工业价值：在业界可以用来做什么、解决什么实际问题
直觉类比：用一个生活化的类比帮助读者建立第一印象

示例格式：

## 📍 论文定位

**一句话**：本文提出了 XXX 方法，解决了 YYY 场景下 ZZZ 的问题。

**🎓 学术价值**：首次将...应用于...领域，填补了...的空白。

**🏭 工业价值**：可直接用于...系统，降低...成本，提升...效率。

**💡 直觉类比**：这篇论文就像是给 AI 配了一个...，让它能够...

🗺️ 第1步：知识地图

目标：用结构化方式呈现读懂本文所需的前置知识，降低阅读门槛。

写法要求：

用 Mermaid 图 画出知识树（三层：核心→支撑→扩展）
对每个核心概念，用「是什么 + 为什么重要 + 现实类比」三件套讲解
标注难度等级（⭐ 简单 / ⭐⭐ 中等 / ⭐⭐⭐ 较难）

Mermaid 知识树模板：

graph TD
    A[读懂本文需要] --> B[核心概念 必须懂]
    A --> C[支撑概念 有助理解]
    A --> D[扩展概念 感兴趣再看]
    B --> B1[概念1 ⭐⭐]
    B --> B2[概念2 ⭐⭐⭐]
    C --> C1[概念3 ⭐]
    D --> D1[概念4 ⭐⭐]

🔬 第2步：论文精读（5W1H框架）

目标：按"问题-方案-验证"三段式完整解读论文内容。

2.1 Why — 为什么要做这个研究？

现有方法的痛点是什么？
作者的 motivation 是什么？
用对比表格展示"之前 vs 本文"

2.2 What — 提出了什么方法/系统？

核心方法/架构是什么？
用 Mermaid 流程图或架构图 展示系统结构
如果论文有架构图，用文字 + mermaid 重新描述

Mermaid 架构图示例：

graph LR
    输入 --> 模块A
    模块A --> 模块B
    模块B --> 模块C
    模块C --> 输出

2.3 How — 具体怎么实现的？

关键技术细节（公式可以保留，但必须加白话解释）
重要的设计选择和背后的直觉
如有伪代码/算法，用代码块呈现并注释

2.4 So What — 结果怎么样？

主要实验结果（用表格整理核心指标对比）
消融实验说明了什么？
结果中最令人印象深刻的发现是什么？

2.5 Now What — 对我们意味着什么？

学术界：开了哪些新方向？
工业界：可以怎么落地？有哪些应用场景？

📖 第3步：术语词典

目标：让读者看完就记住关键术语的含义和重要性。

每个术语使用固定三件套模板：

### 术语名（英文原名）
- **是什么**：...
- **为什么重要**：...
- **现实类比**：就像...

只收录论文中真正关键的术语（5~15个），不要堆砌所有专业词汇。

⚖️ 第4步：批判性评估

目标：培养读者的独立思考能力，呈现论文的局限性与未来方向。

必须覆盖以下四个维度：

假设前提的合理性
- 论文依赖哪些假设？
- 这些假设在现实场景中是否成立？
实验设计的可质疑之处
- 基线选择是否公平？
- 数据集是否有代表性？
- 有没有重要的对比实验缺失？
方法的适用边界
- 这个方法在什么场景下会失效？
- 有哪些已知限制（计算成本、数据依赖、场景限制等）？
未来改进方向
- 作者自己提出的 future work 是什么？
- 读者/你认为还可以从哪些角度改进？

Step 3：写入文件

完整的 Markdown 文件结构如下：

# 📄 论文解读：{论文标题}

> **原文信息**：作者 | 年份 | 期刊/会议
> **解读日期**：{今天日期}

---

## 📍 论文定位
...

---

## 🗺️ 知识地图
...

---

## 🔬 论文精读
### Why — 研究动机
### What — 核心方法
### How — 技术细节
### So What — 实验结果
### Now What — 价值总结

---

## 📖 术语词典
...

---

## ⚖️ 批判性评估
...

---

## 📚 参考资料
- 原文链接
- 相关论文（如论文中引用的关键文献）

最后执行：

# 保存文件
cp /home/claude/解读文件.md markdown/文件名.md
echo "✅ 解读文档已保存至 markdown/文件名.md"

质量检查清单

生成文档后，逐项确认：

包含至少 1 个 Mermaid 图（知识树或架构图）
包含至少 1 个对比表格（方法对比或实验结果）
每个核心概念都有现实类比
术语词典覆盖 5 个以上关键术语
批判性评估覆盖全部 4 个维度
文件已保存到 markdown/ 目录
文档语言通俗，无堆砌定义的段落

常见注意事项

关于图片：论文中的图片无法直接嵌入 Markdown，应用文字描述 + mermaid 重新表达其核心信息。

关于公式：保留核心公式（使用 LaTeX 格式 $公式$ ），但每个公式后面必须跟一段白话解释。

关于篇幅：解读文档通常在 2000~5000 字之间。太短说明解读不够深入，太长可能存在不必要的堆砌。

关于语气：用"我们"和"读者"的视角写作，像一位熟悉该领域的朋友在讲解，避免学术腔。