paper-reader

开始前: 先跟用户打个招呼 🐕

学术论文阅读助手 (Paper Reader)

专注 CV/DL 领域，支持 Zotero 集成和 Obsidian 笔记保存。

Step 0: 读取共享配置

先读取 ../_shared/user-config.json，如果 ../_shared/user-config.local.json 存在，再用它覆盖默认值。

显式生成并在后续统一使用这些变量：

• VAULT_PATH
• NOTES_PATH
• CONCEPTS_PATH
• ZOTERO_DB
• ZOTERO_STORAGE
• AUTO_REFRESH_INDEXES
• GIT_COMMIT_ENABLED
• GIT_PUSH_ENABLED

其中：

• NOTES_PATH = {VAULT_PATH}/{paper_notes_folder}
• CONCEPTS_PATH = {NOTES_PATH}/{concepts_folder}
• GIT_PUSH_ENABLED 只有在 GIT_COMMIT_ENABLED=true 时才可能为真

后续统一使用上面的变量。

1. 接收论文

无 PDF 时的获取流程

1. python3 assets/zotero_helper.py info {item_id} 获取论文信息
2. 按优先级获取：arXiv HTML > arXiv PDF > DOI > WebSearch 标题
3. 判断 arXiv ID：从 URL / Zotero extra 字段 / 标题搜索
4. 推荐直接 WebFetch https://arxiv.org/html/{arxiv_id}，无需下载
5. 跳过条件：既无 PDF 也无在线来源 / 非论文内容

Zotero 详细操作见 references/zotero-guide.md

2. 阅读模式

3. 笔记生成

模板: 严格遵循 assets/paper-note-template.md，不可自行简化。

核心质量规则

1. 零遗漏: 论文中所有 Figure、所有公式、所有 Table 必须全部出现在笔记中
2. 内联概念链接: 正文中首次出现的技术术语必须用 [[概念]] 链接，不仅仅是结尾
3. 严禁 ASCII 流程图: 用结构化 Markdown 列表 + $数学符号$ 描述架构
4. 公式完整性: 每个公式必须有名称（[[概念|名称]]）、LaTeX 公式、含义、符号说明
5. 图片外链优先: arXiv HTML / 项目主页 / GitHub，找不到再本地下载

公式/图片/表格的详细质量规范见 references/quality-standards.md

图片获取流程（多源 fallback）

目标: 确保笔记中包含论文的所有 Figure，先统计论文 Figure 总数再逐一获取。

1. WebSearch "{论文标题} arxiv" 获取 arXiv ID
2. 来源 A — arXiv HTML（首选）：

• WebFetch https://arxiv.org/html/{arxiv_id} 提取所有 <figure> 的标题与 img src URL
• 统计论文 Figure 总数，确认提取数量是否完整

1. 来源 B — 项目主页（HTML 404 或图片不全时）：

• 从摘要/HTML 中查找项目主页 URL（常见模式：project page、github.io、our website）
• WebFetch 项目主页，提取展示图片（通常包含 teaser / demo 图）

1. 来源 C — PDF 提取（前两者都失败时）：

• pdfimages -png 从 PDF 中提取，筛选 >10KB 的有效图片

1. 笔记中用 ![Figure X](url) 外链嵌入
2. 验证：外链可加载 / 本地文件 >10KB
3. URL 去重（必做）：写入前检查每个 URL，如果 https://arxiv.org/html/ 后出现了连续两段相同的 arxiv_id（如 2607.04988v1/2607.04988v1/），删除重复段。这是高频 bug，详见 references/image-troubleshooting.md

• 原因：arXiv HTML 中 img src 已含 {id}v1/ 前缀，拼接时不要再加一次
• 正确：https://arxiv.org/html/ + src（如 https://arxiv.org/html/2607.04988v1/x1.png）
• 错误：https://arxiv.org/html/2607.04988v1/ + src（导致路径重复，返回 404）

ar5iv 编号不一定对应 Figure 编号，排错见 references/image-troubleshooting.md

图片可靠性保障（生成后自动执行）

笔记保存后，运行图片可达性检查脚本，自动将不可访问的外链图片下载到本地：

python3 ../daily-papers/download_note_images.py "{笔记完整路径}"

• 可达的外链保持不动，不可达的自动下载到 assets/ 并替换为 Obsidian wikilink
• 如有本地化操作，frontmatter image_source 自动更新为 mixed

公式格式

每个公式必须包含：名称（[[概念|名称]]）、LaTeX $$ 块（前后留空行）、含义、符号列表。 $$ 块前后必须有空行否则 Obsidian 不渲染。超长公式用 aligned 拆分。

4. Obsidian 保存

文件命名

只用方法名/模型名：{方法名}.md（如 Pi05.md，不加年份前缀）。 方法名判断：标题冒号前 / Abstract 中 "We propose XXX" / 希腊字母转 ASCII。 不确定时保存到 _待整理/。

保存路径

按 Zotero 分类层级：{NOTES_PATH}/{zotero_collection_path}/{方法名}.md

YAML frontmatter

---
title: "论文标题"
method_name: "MethodName"
authors: [Author1, Author2]
year: 2025
venue: arXiv
tags: [tag1, tag2]  # 小写连字符，3-8 个
zotero_collection: 3-Robotics/1-VLX/VLA
image_source: online
created: YYYY-MM-DD
---

Tags 判断：看 Related Work 小标题 + Abstract 关键词。第一个 tag 是最核心主题。

保存后自动执行

1. 只有在 AUTO_REFRESH_INDEXES=true 时才刷新目录页：

   python3 ../_shared/generate_concept_mocs.py
   python3 ../_shared/generate_paper_mocs.py

1. 只有在 GIT_COMMIT_ENABLED=true 时才做 git：

• 先确认 VAULT_PATH/.git 存在
• git add {新增文件} {paper_notes_folder}/ 后必须真的有 staged changes
• 满足条件后再执行：

   cd {VAULT_PATH} && git add {新增文件} {paper_notes_folder}/ && git commit -m "add paper note: {方法名}"

• 只有在 GIT_PUSH_ENABLED=true 且仓库已配置远端时才 push

5. 概念库维护（每篇论文必做）

概念库位置：{CONCEPTS_PATH}

流程

1. 扫描论文笔记中所有 [[概念]] 链接
2. 检查每个链接对应的概念笔记是否存在（ls + find）
3. 创建不存在的概念（不可跳过），自动归类到对应子目录

分类规则和模板见 references/concept-categories.md

自检

• [ ] 笔记中所有 [[概念]] 链接的概念笔记都存在？
• [ ] 概念笔记包含本论文作为"代表工作"？

6. 完成后自检（合并 checklist）

• [ ] 所有 Figure 都在笔记中（数量与论文一致）？
• [ ] 所有公式都在笔记中（变量一致、无冲突）？
• [ ] 所有 Table 完整保留（所有行列）？
• [ ] 正文中技术术语有 [[概念]] 内联链接？
• [ ] 概念库已更新（缺失的概念已创建）？
• [ ] 图片可用（外链可加载 / 本地 >10KB）？

7. 交互式功能

完成解析后询问：深入解释？对比其他论文？保存到 Obsidian？ 保存后自动创建缺失概念笔记，报告新增概念数量。

8. 批量处理

支持 Zotero 分类批量处理（默认递归子分类）。流程：递归获取论文 → 去重 → 跳过已有笔记 → 依次处理 → 汇总。

参考文件（按需查阅）

• `references/zotero-guide.md` — Zotero 查询、分类、PDF 路径获取、智能分类判断
• `references/image-troubleshooting.md` — ar5iv 图片编号对应、PDF 提取备选
• `references/concept-categories.md` — 概念自动归类的 16 个子目录规则 + 模板
• `references/quality-standards.md` — 公式/图片/表格的详细质量规范 + 自检清单