DeepPaperNote

把一篇难读的论文，变成一份真正值得保留的 Obsidian 深度笔记。

English | 简体中文

你是否经常遇到这种情况：准备精读一篇经典论文时，最累的往往不是看，而是整理成笔记。真正耗时间的，通常是这些环节：

• 在 PDF、Zotero、网页和笔记软件之间来回切换
• 手动整理元数据、摘要、图表和方法主线
• 明明已经读懂了一部分，却还要花很多时间把它写成结构化笔记
• 最后留下的仍然只是一篇“看起来完整，但以后未必还想回看”的笔记

DeepPaperNote 想解决的，就是这一层重复、机械、但又非常耗时的工作。它会先把整理、结构化、图表定位和笔记成形这些环节做掉，让你把精力留给真正的思考。

DeepPaperNote 是一个面向论文深度阅读的技能，同一套核心能力可以运行在 Claude Code 和 Codex 上。它更关注：

• 论文到底在解决什么问题
• 方法机制是怎么工作的
• 关键公式、实验结论和图表信息是否被保留下来
• 最终能不能沉淀成一份适合长期积累的 Obsidian 笔记

[!tip] 如果你已经有自己的 Obsidian / Zotero 工作流，DeepPaperNote 会把最耗时、最容易出错的取证、整理和成稿环节自动化。

🎯 它帮你解决什么问题？

✨ 它是怎么做到的？

DeepPaperNote 不是靠“把摘要重新措辞一遍”来显得更完整，而是靠下面这几条工作流原则，把笔记质量往上抬：

一句话说：

DeepPaperNote 更像一个“论文读书笔记生成工作流”，而不是“论文摘要总结器”。

👀 它更适合谁

🚀 快速上手

1) 将 DeepPaperNote 安装到你的 agent 技能目录

DeepPaperNote 同时支持 Claude Code 和 Codex。

npx Skills（推荐）

大多数情况下，可以直接从npx安装：

npx skills add 917Dhj/DeepPaperNote

此命令会默认安装到共享的.agent/skills目录，这个目录中的 skill 可以被 Codex 等大部分 agent 识别并使用。如果你也想在 Claude Code 里使用，在 Additional agents 提示中选择 Claude Code即可。

你也可以直接指定安装给某个 agent：

npx skills add 917Dhj/DeepPaperNote -a codex
npx skills add 917Dhj/DeepPaperNote -a claude-code

手动安装

如果你更习惯手动安装，推荐去 release 页面下载最新版本的 zip 包并解压。

Codex 用户可以把解压出来的 DeepPaperNote 文件夹放到：

~/.codex/skills/DeepPaperNote

Claude Code 用户可以把解压出来的 DeepPaperNote 文件夹放到：

~/.claude/skills/DeepPaperNote

也可以直接 git clone：

git clone https://github.com/917Dhj/DeepPaperNote.git ~/.codex/skills/DeepPaperNote
git clone https://github.com/917Dhj/DeepPaperNote.git ~/.claude/skills/DeepPaperNote

安装完成后，重启你的 agent 让技能生效。

2) 安装核心 Python 依赖

在正式处理论文前，需要安装最核心的 Python 依赖：

python3 -m pip install PyMuPDF

为什么这一步很重要：

• DeepPaperNote 读取 PDF 主要依赖 PyMuPDF
• 如果没装 PyMuPDF，最核心的 PDF 抽取流程就跑不起来

3) 直接开始使用

接下来你只需要把论文丢给 agent 就行，标题、DOI、URL、本地 PDF 都可以，你可以直接给出类似这样的指令：

• 💬 给这篇论文生成深度笔记：Attention Is All You Need
• 💬 把这篇文章整理成 Obsidian 笔记：https://arxiv.org/abs/1706.03762
• 💬 帮我精读一下这篇 PDF，生成带图表的 Markdown
• 💬 请用 DeepPaperNote 处理这篇论文：10.48550/arXiv.1706.03762

默认情况下，DeepPaperNote 会生成中文笔记。当前写作规范和格式校验也主要围绕中文笔记构建；目前中文是唯一能够发挥 skill 完全能力的笔记语言，如需生成英文版笔记，请期待后续更新。

默认情况下，DeepPaperNote 会自己完成：

• 精准识别论文身份
• 获取 PDF、元数据和正文证据
• 规划图表占位并尝试高置信度图片替换
• 生成最终 Markdown 笔记
• 自动写入 Obsidian；如果没有配置 Obsidian，则会先询问你是否有库路径，再决定是否降级输出到当前目录

4) 首次使用不必追求完整配置

如果你还没有完整配置 Obsidian / Zotero / OCR，也可以先试跑。

如果你想先检查环境，也可以直接对 agent 说：

• 💬 请帮我检查这台机器上的 DeepPaperNote 是否已经准备好
• 💬 查看 deeppapernote 的可用情况
• 💬 deeppapernote 有什么功能

🔧 配置指南（开箱即用，按需进阶）

如果你已经安装好了 PyMuPDF，那么你就可以直接开始使用 DeepPaperNote 生成笔记了。以下介绍的配置都是核心功能的扩展，让你能够将 DeepPaperNote 生成的笔记真正融入你的科研工作流中。

• 如果你没有配置 Obsidian，它也能把笔记输出到当前工作目录。
• 但如果你想要更好的长期管理体验，还是强烈建议配置你的 Obsidian 库路径。

📍 核心配置：指定你的 Obsidian 库

export DEEPPAPERNOTE_OBSIDIAN_VAULT="/你的/Obsidian_Documents/绝对路径"

如果你希望 agent 在之后的新终端会话里也一直读到这个默认配置：

• 在 macOS / Linux 上，建议把它写进 ~/.zshrc 之类的 shell 配置文件，然后重新加载 shell 或重启 agent：

echo 'export DEEPPAPERNOTE_OBSIDIAN_VAULT="/你的/Obsidian_Documents/绝对路径"' >> ~/.zshrc
source ~/.zshrc

• 在 Windows PowerShell 上，可以把它持久化成用户环境变量，然后重新打开终端：

setx DEEPPAPERNOTE_OBSIDIAN_VAULT "C:\Users\YourName\Documents\Obsidian_Documents"

🛠️ 展开查看更多进阶配置（目录自定义 / Zotero / Semantic Scholar / OCR）

目录相关配置

如果你希望自定义论文目录或中间产物目录，也可以再加：

export DEEPPAPERNOTE_PAPERS_DIR="Research/Papers"
export DEEPPAPERNOTE_OUTPUT_DIR="tmp/DeepPaperNote"

如果你希望 agent 后续一直默认使用这些值：

• 在 macOS / Linux 上，也建议把它们写进 ~/.zshrc：

echo 'export DEEPPAPERNOTE_PAPERS_DIR="Research/Papers"' >> ~/.zshrc
source ~/.zshrc

• 在 Windows PowerShell 上，可以把它们持久化成用户环境变量：

setx DEEPPAPERNOTE_PAPERS_DIR "Research/Papers"

这些可选路径配置的实际好处是：

• DEEPPAPERNOTE_PAPERS_DIR 如果你的 Obsidian 库不是把论文放在 Research/Papers 下，或者你已经有自己的目录约定，这个配置可以让 DeepPaperNote 直接适配你的现有结构，减少后续手动移动文件。
• DEEPPAPERNOTE_OUTPUT_DIR 如果你希望中间产物统一落在一个固定位置，方便调试、清理或做实验，这个配置会比较有用。

领域路由由 references/domain_rules.yaml 中的可编辑分类表控制。DeepPaperNote 会先判断应用领域，再回退到方法领域；只有标题或摘要能提供相对保守的证据时，才会复用已有的 Obsidian 一级领域目录。

可选：用于本地文献库优先工作流的 Zotero

DeepPaperNote 不依赖 Zotero 才能工作。 但如果你本来就用 Zotero 做文献管理，配置一个你的 agent 真的能用的 Zotero 集成会很值。

它最适合这样的人： - 你本来就用 Zotero 做文献管理 - 你平时主要在 Zotero 里读论文、整理附件和元数据

可以这样理解不同路线：

为什么值得配：

• 本地 Zotero 命中通常是最可靠的论文身份锚点
• 如果论文已经在你的本地 Zotero 库里，DeepPaperNote 往往可以直接复用本地条目和附件信息，不必再重新联网搜索和下载，因此生成速度通常也会更快
• agent 可以先查你的本地论文库，再决定要不要联网
• 本地附件也更有助于减少标题误匹配
• 如果你本来就用 Zotero 做论文管理，这会比重新去网上“猜测这篇论文是谁”稳得多
• 对正式发表版、预印本、镜像页面标题相似的场景，Zotero 优先通常会明显降低误匹配概率

⚠️需要特别说明的是：

• DeepPaperNote 不强依赖某一个固定的 Zotero 集成仓库
• 对 DeepPaperNote 来说，需要的关键能力是：让 agent 能搜索 Zotero 条目、查看元数据、最好还能读取本地 PDF 附件
• 上面提到的两条路线目前都不一定是即插即用方案，如果你想稳定使用，通常还需要自己做一层适配或改造

可选：Semantic Scholar API Key

这不是必需项，但如果你有 Semantic Scholar API key，可以设置：

export DEEPPAPERNOTE_SEMANTIC_SCHOLAR_API_KEY="your_api_key"

它的好处主要是：

• 元数据补全通常会更稳一些
• 对一些标题不好匹配的论文，身份解析会更可靠
• 在作者、venue、摘要等信息回填上，有时会更完整
• 它能给 DeepPaperNote 多一个较强的元数据来源，减少退回到弱匹配的概率

可选：OCR 工具

很多现代 PDF 并不需要 OCR。 但如果论文是下面这些情况，OCR 会很有帮助：

• 扫描版 PDF
• 以图片为主、嵌入文本质量很差的 PDF
• 一些比较老的论文，直接抽文本时内容残缺

DeepPaperNote 当前的 OCR 使用逻辑是：

• 先用 PyMuPDF 做正常的 PDF 文本提取
• 对每一页统计可搜索文本的字符数
• 如果某一页直接抽到的文本太少，就把这页视为 OCR 回退候选
• 只对这类页面单独做 OCR
• OCR 恢复出的文本，主要用于补页级证据和后续图表/页面语义匹配的上下文

需要特别说明的是：

• OCR 目前只是 页文本兜底方案
• 它 不是 所有 PDF 的主提取路径
• 它 不会 代替模型去理解论文
• 它 不会 直接负责“理解图片内容”

如果没有 OCR，DeepPaperNote 处理普通数字版 PDF 依然没问题。面对扫描版或低质量 PDF 时，如果抽取到的证据不足以支撑真正的深度笔记，流程应该要求补充 OCR 或更好的来源，而不是完成一篇低质量输出。

OCR 需要的依赖如下：

在 macOS 上的安装方式：

brew install tesseract
python3 -m pip install --user pytesseract Pillow

在 Windows 上，可以用下面这种方式：

winget install UB-Mannheim.TesseractOCR
py -m pip install --user pytesseract Pillow

如果 winget 不可用，也可以手动安装 Tesseract OCR，再执行：

py -m pip install --user pytesseract Pillow

快速验证：

tesseract --version
python3 -c "import pytesseract, PIL; print('python_ok')"
python3 -c "import pytesseract; print(pytesseract.get_tesseract_version())"

📝 更新日志概览

更完整的版本级更新请见 CHANGELOG.md。

⚙️ 工作流

默认流程是：

1. 解析论文身份
2. 收集元数据
3. 获取最佳可用 PDF
4. 抽取完整原文与 source manifest
5. 抽取结构化索引和 PDF 图像资产
6. 规划图表位置和全量图表决策表
7. 构建 manifest synthesis bundle
8. 让模型读取 raw sections 并规划笔记
9. 对 note_plan 运行 grounding lint
10. 让模型写笔记
11. 校验最终笔记
12. 做最终内容质量复核
13. 做最终可读性复核并写入 Obsidian

核心原则：

• 脚本负责原文、元数据、资产和质量信号
• 模型负责写作
• 格式校验、最终内容质量复核和最终可读性复核在写入前兜底

相关文档：

• 工作流
• 架构
• 模型综合写作

🖼️ 图表策略

对于论文笔记工具，一旦图表处理不顺利，整份笔记质量就会明显下降。

这就是为什么 DeepPaperNote 采用了一种更偏向“结构优先”的图像占位策略：

• 尽量保留图表在笔记中的语义位置
• 即使图表抽取不理想，也尽量不破坏整体阅读流
• 让你知道某个位置原本对应什么图，为什么值得看。这样你后续读文章的时候可以自己截图，将图片放在笔记中标记好的位置。

笔记中的图像占位格式如下：

> [!figure] Fig. 3 数据分布与质量评估
> 建议位置：数据与任务定义
> 放置原因：这张图同时展示样本构成、对话长度统计和专家质检结果，是理解 `PsyInterview` 数据边界最重要的图之一。
> 当前状态：保留占位；当前提取结果只拿到局部子图，无法稳定恢复成可独立解释的完整原图。

也就是说，我们更重视：

笔记的完整性和可读性，而不是为了追求“图全部自动抽取出来”，而降低笔记的质量。

详见 图表放置规则。

✅ 质量标准

DeepPaperNote 对“什么算一篇合格笔记”有明确门槛。

最终笔记应该：

• 区分研究问题和任务定义
• 讲清楚真正的方法或分析流程
• 抓住真正重要的关键数字
• 指出哪些地方最容易被误读
• 至少写出一个真实局限
• 使用真实标题层级：#、##、###
• 避免正文出现半中半英的句子

如果证据质量不够，就应该降级或直接失败，而不是假装完成了深度精读。

相关文档：

• 证据优先
• 深度分析
• 最终写作
• 笔记质量标准

🗂️ 仓库结构

DeepPaperNote/
├── SKILL.md
├── README.md
├── README.zh-CN.md
├── CHANGELOG.md
├── LICENSE
├── pyproject.toml
├── agents/
│   └── openai.yaml
├── assets/
│   ├── hero-academic.svg
│   ├── usage-example.png
│   └── note_template.md
├── references/
│   ├── architecture.md
│   ├── deep-analysis.md
│   ├── evidence-first.md
│   ├── figure-placement.md
│   ├── final-writing.md
│   ├── metadata-sources.md
│   ├── model-synthesis.md
│   ├── note-quality.md
│   ├── obsidian-format.md
│   ├── paper-types.md
│   └── workflow.md
└── scripts/
    ├── build_synthesis_bundle.py
    ├── check_environment.py
    ├── collect_metadata.py
    ├── common.py
    ├── contracts.py
    ├── create_input_record.py
    ├── extract_evidence.py
    ├── extract_pdf_assets.py
    ├── extract_source_text.py
    ├── fetch_pdf.py
    ├── lint_grounding.py
    ├── lint_note.py
    ├── locate_zotero_attachment.py
    ├── materialize_figure_asset.py
    ├── plan_figure_table_decisions.py
    ├── plan_figures.py
    ├── resolve_paper.py
    ├── run_pipeline.py
    └── write_obsidian_note.py

🧰 推荐环境

🧭 设计原则

DeepPaperNote 背后的基本判断很简单：

1. 好的论文笔记，不等于段落式摘要

真正有价值的笔记，应该帮助你理解：

• 方法怎么工作
• 证据在哪里
• 实验说明了什么

• 有哪些边界与局限

• 论文的阅读目标，是沉淀的可复用资产

不是当下“懂了一点”，而是未来还能回看、能引用、能接着研究。

1. 笔记生成应该服务真实研究工作流

所以它更贴近：

• Obsidian
• Zotero
• 本地论文管理
• 长期知识库构建和管理

🧭 致谢与灵感

DeepPaperNote 在工作流设计上受到了这些论文阅读 / 笔记生成项目的启发：

• heleninsights-dot/phd-deepread-workflow
• juliye2025/evil-read-arxiv

Star History

<source