read-research-paper

阅读研究论文

其他两个技能的作用如下：

技能	功能
get-research-paper	查找特定主题的真实论文
research-paper	撰写新论文
read-research-paper（本技能）	阅读一篇论文，并让阅读过程更引人入胜

提供 URL、arXiv ID、DOI 或粘贴的文本。它会生成多层次的可视化呈现：技术深度分析 + 通俗易懂的说明 + 思维导图 + 方法流程图 + 关键发现信息图 + 对比表格 + 相关工作时间线。

此文件是入口点。更详尽的指南存放在主题文件夹中，需要时才会加载。

---

1. 何时激活

斜杠命令

命令	功能
/read-research-paper <input>	完整的可视化呈现（默认）
/read-paper <input>	别名
/explain-paper <input>	同上，并增加通俗易懂的说明层
/visualize-paper <input>	同上，侧重视觉呈现而非文字
/tldr-paper <input>	仅生成一页信息图摘要

<input> 可以是：

• URL：https://arxiv.org/abs/2403.01234、https://doi.org/...、 https://example.com/paper.pdf、期刊主页等。
• arXiv ID：2403.01234 或 cs.LG/0701002
• DOI：10.1145/3589334
• 粘贴的文本：论文摘要或全文
• 本地文件，格式不限（见下文）。

支持的文件格式

此技能可读取以下任意格式的输入：

格式	扩展名	使用的库	是否始终可用？
Markdown	.md、.markdown	stdlib	是
纯文本	.txt	stdlib	是
LaTeX	.tex、.latex	stdlib + regex de-LaTeX	是
JSON	.json	stdlib	是
HTML	.html、.htm	beautifulsoup4（或 regex）	是（regex 回退方案）
CSV / TSV	.csv、.tsv	pandas（或 stdlib）	是（stdlib 基础支持）
RTF	.rtf	striprtf（或 regex）	是（regex 回退方案）
PDF	.pdf	pdfplumber / pypdf	需安装一个
DOCX	.docx	python-docx	需安装
PPTX	.pptx	python-pptx	需安装
XLSX	.xlsx、.xls	pandas + openpyxl	需安装
EPUB	.epub	ebooklib	需安装
图像	.png、.jpg、.tiff、.bmp	pytesseract + PIL	需安装（OCR）

一行命令安装所有内容：

pip install pdfplumber python-docx python-pptx pandas openpyxl \
            beautifulsoup4 striprtf ebooklib pytesseract Pillow

（此外，还需在系统范围内安装 Tesseract OCR 才能处理图像。）

读取器位于 toolchains/read_any_file.py。自测命令：

python toolchains/read_any_file.py --self-test
python toolchains/read_any_file.py --list-formats

完整参考文档：sources/file-formats.md。

常用选项

选项	默认值	效果
--depth	standard	快速 / 标准 / 深入
--audience	mixed	学术 / 技术 / 通俗 / 混合
--visuals	auto	自动 / 最多 / 最少 / 无
--include-figures	true	尝试提取 / 重新创建论文自身的图表
--cache	true	使用本地缓存（重新提问时自动填充）
--language	en	通俗易懂的英语
--out	./<paper-slug>/	工作目录
--with-related	false	为相关工作触发 get-research-paper
--with-handoff	false	为 research-paper 输出 bibliography.yaml

自然语言模式

• “阅读这篇研究论文 ”
• “解释这篇论文 ”
• “将这篇论文可视化 ”
• “我想理解这篇论文 ”
• “总结这篇论文 ”
• “用一句话概括这篇论文 ”
• “这篇论文讲了什么 ”

不触发的情况

请勿在以下情况下触发：

• 请求查找某个主题的论文（转至 get-research-paper）。
• 请求撰写一篇新论文（转至 research-paper）。
• 粘贴的文本并非论文形式的输入（“这是一篇文章……”）。
• 关于某个主题的随意提问，且未提及特定论文。

---

2. 输出约定

每次运行都会生成：

1. paper-visual.md — 主要交付内容，包含多个层次：
   • 顶部为单页信息图（思维导图 + 关键数字）。
   • 简要概述，共 5–8 句。
   • 通俗易懂的摘要，共 5–10 句。
   • 逐节讲解：每节开头先用一段通俗易懂的文字介绍，然后提供技术内容及提取 / 生成的视觉素材。
   • 方法流程图（Mermaid）。
   • 关键发现信息图（展示论文核心数据的图表）。
   • 与基准方法的对比表（如有）。
   • 相关工作时间线（如有参考文献）。
   • “为何这很重要”页脚。
2. paper-data.json — 提取的结构化元数据：标题、 作者、年份、摘要、章节、图表、表格、关键数字、 参考文献。架构见 schemas/visual-paper.json。
3. figures/ — 生成的图表 / 示意图 / 思维导图，以 PNG + SVG + Mermaid 源文件形式提供。
4. cache/<paper-id>.json — 缓存以供重复使用。
5. Known-gaps.md — 无法获取 / 解析的内容。

如果设置了 --with-handoff，还会生成可直接用于 research-paper 技能的 bibliography.yaml。

如果设置了 --with-related，协调器会针对论文的关键主题调用 get-research-paper，以提供相关工作部分的素材。

---

3. 运作原则

0. 以今天的日期为准。 当输入是主题式查询（而非特定 URL/DOI/路径）时，先确定今天的实际日期（通过 date -u +%Y-%m-%d、运行时上下文或询问用户）。对于特定论文输入，新鲜度检查会将论文的发表日期与今天比较，并标记过时的发现。完整协议：instructions/freshness.md。
1. 不要虚张声势。 如果 URL 无法访问或 PDF 无法解析，请如实说明。标记 [FETCH FAILED — fallback to cache | model knowledge | corpus]，并在 Known-gaps.md 中注明。
2. 缓存所有内容。 每篇成功获取的论文都会写入 ~/.agents/skills/read-research-paper/cache/。再次请求时可即时获取。
3. 随附语料库。 当输入是主题式查询而非特定论文时，先搜索随附的小型经典论文语料库（corpus/anchor-papers.yaml）。
4. 默认采用可视化。 至少生成：1 张思维导图 + 1 张方法流程图 + 1 张关键发现图 + 1 张比较表。
5. 兼顾双重表达。 每个部分都同时包含通俗易懂的内容和技术内容。绝不删减技术深度——同时补充更简单的说明。
6. 如实解读。 不要夸大研究发现。与论文自身的确定程度保持一致。如果论文使用审慎措辞，可视化论文也应如此。

---

4. 顶层工作流

intake → fetch → parse → extract-figures-and-data →
plan-visuals → render → assemble → cache → output

每个阶段都有专门的操作手册。主流程： workflows/ingestion.md。

---

5. 来源检测

该技能会自动检测输入类型：

输入模式	路径
arxiv.org/abs/...	arXiv API
\d{4}\.\d{4,5}（裸 arXiv ID）	arXiv API
doi.org/... 或 10\..../...	Crossref → URL → 获取
*.pdf（URL 或本地路径）	PDF 提取
期刊落地页 URL	URL 抓取 + Crossref 补充
粘贴的文本（无 URL）	视为论文正文；通过启发式方法构建结构

参见 workflows/ingestion.md §1。

---

6. 三级回退

1. Local cache (~/.agents/skills/read-research-paper/cache/)
   ├── Hit  → return immediately (instant)
   └── Miss → next tier

2. Live fetch (arXiv API / Crossref / WebFetch / PDF parser)
   ├── Success → render + cache
   └── Fail    → next tier

3. Bundled corpus (corpus/anchor-papers.yaml)
   ├── Hit  → return + flag as "from bundled corpus"
   └── Miss → next tier

4. Model knowledge
   ├── Confident → render + flag every fact [UNVERIFIED — offline]
   └── Not confident → fail honestly with a Known-gaps entry

每次层级切换都会记录在 Known-gaps.md 中，让用户知道呈现的论文来自何处。

---

7. 可视化呈现方案

对于每篇论文，该技能都会生成：

可视化内容	来源	渲染器
思维导图	论文结构（章节 + 关键观点）	Mermaid mindmap
方法流程图	方法部分	Mermaid flowchart
关键发现信息图	结果中的核心数据	如果可用则使用 matplotlib，否则使用 Markdown 表格
比较表	论文自己的基准测试表	Markdown 表格
相关工作时间线	参考文献及其年份	Mermaid gantt 风格时间线
作者网络	作者 + 所属机构	Mermaid flowchart（小型）
概念图	论文术语	Mermaid mindmap
图表说明重写	原始图表（可提取时）	直接沿用并添加新说明

决策逻辑：workflows/visualization.md。

---

8. 缓存架构

缓存位于：

~/.agents/skills/read-research-paper/cache/
├── manifest.json              # index of all cached papers
├── arxiv/
│   ├── 2403.01234.json
│   └── 2005.11401.json
├── doi/
│   ├── 10.1145_3589334.json
│   └── ...
├── url/
│   └── <sha256-hash>.json
└── topics/
    └── <topic-slug>.json      # topic → list of cached paper IDs

当用户询问某个主题（而非特定论文）时，会先搜索缓存的 topics/ 索引，再进行任何实时获取。

缓存架构：workflows/caching.md。

---

9. 随附语料库

包含在 corpus/ 中：

• anchor-papers.yaml — 涵盖主要主题的约 30 篇经典高影响力论文（包括 Transformer、RAG、RLHF、对比学习、RCT 方法论、PRISMA 等）。
• topics-index.yaml — 将主题关键词映射到基准论文。

当用户询问语料库中的论文时，此技能会使用语料库版本（始终可用，即使处于离线状态）。用户可以通过向 corpus/user/ 添加文件来扩展语料库。

---

10. 故障处理

• URL 无法解析 → 尝试提取 arXiv ID，然后查询 DOI，最后将问题记录到 Known-gaps.md。
• PDF 无法解析 → 退回到仅呈现摘要，并发出警告。
• 模型无法提取图表 → 生成 Mermaid 替代方案。
• 结果中没有关键数值 → 使用定性研究结果。
• 网页工具不可用 → 按缓存 + 语料库 + 模型知识的顺序处理。

完整矩阵：workflows/ingestion.md §10。

---

11. 后续查看位置

• 规划数据导入 → workflows/ingestion.md
• 选择可视化内容 → workflows/visualization.md
• 缓存协议 → workflows/caching.md
• 通俗易懂的表达层 → prompts/plain-english.md
• 思维导图生成 → prompts/generate-mindmap.md
• 输出格式 → templates/visual-paper.md
• 随附语料库 → corpus/
• 获取工具 → toolchains/fetch_paper.py、toolchains/extract_pdf.py

此技能可与其他两个技能互补，但不依赖它们：

• get-research-paper → 查找论文
• research-paper → 撰写论文
• read-research-paper → 阅读论文（本技能）