paper-interpreter

# 论文解读助手

## 适用场景

- 用户发来 `https://arxiv.org/...` 链接，并明确要求"论文解读""论文拆解""详细总结""生成报告""下载论文"
- 用户希望把论文资料落到本地目录，再生成一份结构完整、适合持续完善的中文报告
- 用户接受以本地文件为主交付，而不是只在对话里看一段摘要

如果用户只要一段 200 字左右的推荐语，优先使用 `paper-recommendation`，不要使用本 skill。

## 设计模式

本 skill 主要采用：
- **Pipeline**：严格按“下载资料 → 阅读材料 → 生成初稿 → 交付 → 如有需要再复查”的顺序执行
- **Generator**：基于固定报告结构生成可长期迭代的文档
- **Inversion（轻度）**：开始前先确认范围，复查前再次征求用户同意

## Gotchas

- 不要把“论文推荐语”误判成“论文解读”，这两者要分流到不同 skill
- 不要默认安排复查；是否复查必须先征求用户确认
- 不要假装已经读完全文；如果只重点看了摘要、方法、实验，要明确说明
- 不要编造论文中不存在的实验、公式、结论或数据
- 不要只发路径不发文件；如果当前渠道支持发文件，应优先直接发送报告文件

## 工作流

### 0. 先确认执行范围（必须先做）

开始前先给用户一个简短确认，至少说清这 3 件事：

- 会把论文下载到本地并生成报告
- 初版默认先完成一版，不自动安排复查
- 最终以文件为主交付，而不是直接在对话里长篇输出全文

如果用户已经明确接受“下载到本地 + 生成报告”的工作方式，可以直接继续，不必反复确认。

### 1. 确定保存目录

按以下优先级选择基础目录：

1. 用户明确指定的目录
2. 当前上下文中明显属于用户常用工作区的目录
3. `~/Documents/working/papers`

不要凭空发明新目录。无法确定时直接使用默认值。

### 2. 初始化论文工作区

先运行脚本，创建论文目录并下载资源：

```bash
python3 skills/paper-interpreter/scripts/bootstrap_arxiv_paper.py '<arxiv_url>' '<base_dir>'
```

脚本会：

- 解析 arXiv ID
- 使用论文标题创建子文件夹
- 下载 PDF（以论文标题命名）
- 尝试下载 `TeX Source`
- 可识别时自动解包到 `source/`
- 写入 `metadata.json`
- 如报告文件 `{论文标题}_报告.md` 不存在，则创建报告骨架

优先读取脚本输出中的 `paper_dir`、`report_path`、`pdf_path`、`source_path`。

### 3. 阅读材料并生成初版报告

生成报告前，按以下顺序获取信息：

1. `metadata.json`
2. arXiv 摘要页
3. `TeX Source`（如果下载成功，优先用它确认公式、模块名、算法步骤）
4. PDF 文件（以论文标题命名）

报告必须写入论文目录下的 `{论文标题}_报告.md`，并满足：

- 中文输出
- 结构完整，适合长期迭代
- 不编造论文中不存在的实验、公式或结论
- 对不确定内容明确写"论文未明确说明"或"需要进一步核对"
- 在合适位置调用 [`mermaid`](../mermaid/SKILL.md) skill 生成 Mermaid 图，至少 1 张，通常 2-3 张更合适
- 如果需要产出多份报告，继续沿用标题做前缀，并通过后缀区分，例如 `{论文标题}_报告_复查1.md`、`{论文标题}_报告_分享版.md`

优先使用 [report-outline.md](references/report-outline.md) 中的结构。

### 4. 初稿完成要求（必须执行）⚠️

**生成初版报告后，必须立即把报告文件交付给用户**：

- 交付报告文件：`{论文标题}_报告.md`
- 如果当前渠道支持文件发送，优先直接发送文件
- 如果当前渠道不支持文件发送，至少明确给出可访问路径
- 提醒用户这是初稿
- 如果你判断值得继续复查，可以补一句“如有需要我可以再复查一轮”，但不要默认已安排

示例：
```
✅ 论文初稿已生成！

📄 报告文件：<报告文件路径或文件>
📝 当前版本：v1.0 初稿
如果你要，我可以再复查一轮，补实验细节和边界条件。
```

### 5. 报告写作要求

报告至少覆盖这些内容：

- 论文基本信息
- 一句话总结
- 要解决的问题与研究动机
- 方法拆解
- 训练或推理流程
- 实验设置与关键结果
- 亮点、局限、适用边界
- 对实际应用或研究延展的判断
- 术语解释
- 复查记录

调用 [`mermaid`](../mermaid/SKILL.md) skill 时可优先考虑这些图：

- 方法总览：`flowchart LR` / `flowchart TD`
- 训练或推理阶段：`sequenceDiagram` 或 `flowchart`
- 模块关系：`graph TD`

只保留真正能帮助理解的图；调用 [`mermaid`](../mermaid/SKILL.md) skill 时不要为了凑数量而加图。

### 6. 如需复查，必须先征得用户确认

初版报告完成后，默认流程到此结束。

只有在用户明确同意“继续复查”之后，才可以进入后续完善流程。具体要求如下：

- 先问用户要不要复查，不要自己默认安排
- 用户同意后，才可安排 1 次或多次延迟复查
- 如果当前环境支持定时任务、后台任务或提醒能力，可以在获得确认后再安排
- 如果当前环境不支持真正的定时执行，要明确告诉用户限制，并在报告中写明建议复查方向

### 7. 复查任务的更新原则

复查时不要整篇推倒重写，遵循增量更新：

- 先读取当前报告文件
- 再检查论文原文、PDF、Source 与当前报告的差异
- 优先补充遗漏的实验细节、方法边界、限制条件、图示或术语解释
- 在 `复查记录` 一节写明本次更新时间、主要新增内容、修正内容
- 不删除用户手工补充的内容，除非确认其与论文事实冲突

## 输出要求

### 初版报告完成后的必须操作⚠️

**第一步：交付报告文件**
- 如果当前渠道支持文件发送，直接发送 `{论文标题}_报告.md`
- 如果当前渠道不支持文件发送，提供清晰可访问的文件路径
- 附带简短说明：
  - 初稿已完成
  - 当前版本信息
  - 如需复查可继续提出

**第二步：汇报基本信息**
- 论文目录路径
- PDF 文件是否下载成功（以论文标题命名）
- `TeX Source` 是否下载成功
- 报告文件路径（默认是 `{论文标题}_报告.md`）
- 是否建议复查，以及如需复查必须先征求用户确认

**注意**：必须先发送文件，再汇报信息。不要反过来。

如果 `TeX Source` 不存在或下载失败，要明确说明"源文件不可得"，但仍继续完成报告。