paperflow-reader

name	paperflow-reader
description	Use when user asks to "read paper", "analyze paper", "summarize paper", "读论文", "分析文献", "帮我看一下这篇paper", "论文笔记", or provides a PDF file that appears to be an academic paper. Specialized for CV/DL papers. Also supports Zotero integration: "读一下这篇论文 ...", "快速看一下这篇论文 ...", "批判性分析这篇论文 ...", "读一下 Zotero 里的 XXX", "批量读一下 Zotero 里 VLA 分类下的论文" **重要触发词**: "读一下 XXX"、"读一下这篇"、"帮我读" → 必须调用此 skill

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

学术论文阅读助手 (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
• MINERU_CONFIG

其中：

• NOTES_PATH = {VAULT_PATH}/{paper_notes_folder}
• CONCEPTS_PATH = {NOTES_PATH}/{concepts_folder}
• GIT_PUSH_ENABLED 只有在 GIT_COMMIT_ENABLED=true 时才可能为真
• MINERU_CONFIG = mineru 配置块。默认本地优先：脚本检测到系统已安装 mineru 命令时直接走本地解析，否则才走线上 mineru-open-api。可通过 mineru.prefer (auto/local/remote) 显式覆盖；本地后端通过 mineru.local.backend (pipeline/vlm/hybrid) 选择。线上模式下 token 从 api_token、api_token_env 指向的环境变量、MINERU_TOKEN 或 mineru-open-api auth 配置读取。

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

1. 接收论文

输入方式	示例	处理方法
PDF 路径	/path/to/paper.pdf	先用 MinerU 解析成 Markdown，再 Read Markdown
arXiv 链接	https://arxiv.org/abs/xxxx	优先转成 PDF URL 后用 MinerU 解析成 Markdown；必要时 WebFetch HTML
Zotero 分类	"VLA 分类的论文"	查询数据库 → 列出 → 用户选择
Zotero 搜索	"Zotero 里的 π0.5"	搜索标题 → 找到 PDF
无 PDF	Zotero 条目无附件	从网上获取（见下方）

PDF 预解析（MinerU 优先）

目标: 不直接让 Claude 读原始 PDF；先把 PDF 结构化为 Markdown，再基于 Markdown 做阅读总结。这样公式、表格、多栏版式和章节层级更稳定。

使用脚本：assets/mineru_parse.py

本地 PDF：

python3 assets/mineru_parse.py --file "/path/to/paper.pdf"

远程 PDF URL：

python3 assets/mineru_parse.py --url "https://arxiv.org/pdf/xxxx.pdf"

脚本会输出 Markdown 文件路径。正式流程不要使用默认输出目录；必须先在 PaperNotes/ 下确定论文工作目录，再用 --output "{论文工作目录}/{arxiv_id或slug}.mineru.md" 让 MinerU 直接把解析 Markdown 和同级 images/ 保存到该目录。后续阅读必须优先 Read 这个 Markdown 文件，并把它当作论文正文的主来源。

本地 vs 线上

脚本会自动选择 runner：

• 本地优先（默认）：检测到系统已装 mineru CLI（pip install -U "mineru[all]"）时，直接调用本地命令 mineru -p <input> -o <tmp> -b <backend>，输出 Markdown 和 images/ 移到论文工作目录。--url 输入会先下载到临时 PDF 再交给本地解析。
• 线上回退：未装本地 mineru 命令时，调用 mineru-open-api 生态 CLI 走线上 https://mineru.net/api/...。可选 API：
  • --api standard / --api extract: mineru-open-api extract，适合论文、复杂版式、长文档
  • --api flash / --api agent: mineru-open-api flash-extract，无需 token，但受 10 MB / 20 页限制

显式控制：

python3 assets/mineru_parse.py --runner local --file "/path/to/paper.pdf"   # 强制本地，未装则报错
python3 assets/mineru_parse.py --runner remote --file "/path/to/paper.pdf"  # 强制线上
python3 assets/mineru_parse.py --runner auto --file "/path/to/paper.pdf"    # 默认行为：本地有就本地

实现要求：必须用 --output <目标.md> 保存结果（无论 runner），不要使用 stdout Markdown 作为最终输入；stdout 模式不会保留图片资源。线上 extract 模式与本地 pipeline/vlm 模式都会保留 Markdown 及其同级 images/ 目录。禁止把正式产物放到 _mineru/ 后再让总结笔记散落到其他位置。

配置

推荐配置（写到 _shared/user-config.local.json，不要污染仓库跟踪的 user-config.json）：

{
  "mineru": {
    "prefer": "auto",
    "local": {
      "backend": "vlm",
      "fallback_to_remote": true
    },
    "api": "standard",
    "api_token": "（仅当走线上时需要）",
    "model_version": "vlm",
    "language": "en"
  }
}

字段说明：

• prefer: auto（默认；本地有就用本地）/ local（强制本地，未装报错）/ remote（强制线上）。
• local.backend: vlm（默认，精度 95+，需要 GPU 8GB+ 显存或 Apple Silicon）/ pipeline（纯 CPU 即可，精度 85+）/ hybrid。
• local.binary: 默认 mineru，装在虚拟环境时可改成绝对路径。
• local.extra_args: 透传给 mineru CLI 的额外参数（数组）。
• local.fallback_to_remote: 本地解析失败（非 0 / 超时 / 无输出）时是否自动重试线上 API，默认 true。

线上 token 配置优先级（仅当 runner=remote 或本地不可用时才需要）：

1. 命令行 --token
2. 环境变量 MINERU_TOKEN 或 MINERU_API_TOKEN
3. _shared/user-config.local.json 中的 mineru.api_token
4. mineru-open-api auth 写入的 ~/.mineru/config.yaml

也可以不写 token，改用环境变量：

export MINERU_TOKEN="你的 MinerU Token"

手动指定线上精准模式：

python3 assets/mineru_parse.py --runner remote --api standard --file "/path/to/paper.pdf"

线上快速无 token 模式：

python3 assets/mineru_parse.py --runner remote --api flash --file "/path/to/paper.pdf"

失败 fallback

按顺序尝试：

1. 本地 → 线上自动回退：本地 mineru 安装但解析失败（非 0 / 超时 / 无输出）且 mineru.local.fallback_to_remote=true 时，stderr 提示 [mineru] local failed: ...; falling back to remote API 后自动重试线上。
2. 如果 MinerU（本地+线上都）失败但有 arXiv HTML，WebFetch https://arxiv.org/html/{arxiv_id}。
3. HTML 未编译完的特殊处理：如果 HTML 返回 404 或正文空白，并且论文的 arXiv submission 时间在 24h 内（从 abs 页或 frontmatter published 字段判断），不要直接退化到 abs-only。这种情况下 arXiv 通常还在编译 HTML，几小时后会可用。处理：
   • 在最终回复中明确告知用户："arXiv HTML 还未编译完（论文提交于 X 小时前），建议 1-3 小时后重试。已暂存当前任务到 _inbox/，frontmatter 写 content_source: webfetch-abs + incomplete: true + retry_after: {submitted+6h}。"
   • 不要假装完整解析过，不要凑笔记内容
4. 如果 HTML 也不可用，再读取 PDF 或用其它本地工具兜底。
5. 所有 fallback 都必须在 frontmatter 写 content_source_attempted 列表 + 最终 content_source，并在回复中说明没有使用 MinerU Markdown 的原因。可用的失败标记后缀示例：mineru-local-failed-timeout、mineru-local-failed-no-output、mineru-remote-failed-401。

论文工作目录（强制）

正式保存到 Obsidian 时，同一篇论文的所有文件必须放在同一个论文工作目录：

{NOTES_PATH}/{最合适类别}/{论文标题}/
  {arxiv_id或slug}.mineru.md
  images/
  {方法名}.md

目录选择规则：

1. 在 PaperNotes/ 下按论文内容选择最合适的类别，而不是按临时来源保存。
   • 视觉生成 / diffusion / flow / autoregressive 论文优先放到 1-Visual-Generation/ 下的对应子类。
   • 视觉表征论文放到 2-Visual-Representation/。
   • 机器人 / VLA 论文放到 3-Robotics/。
2. 如果已有类别不够细，按论文内容创建新类别目录。例如 diffusion/flow 生成论文可创建 1-Visual-Generation/Diffusion/。
3. 在类别目录下创建以论文标题命名的文件夹；解析 Markdown、images/、最终总结笔记都必须在该文件夹内。
4. 总结笔记里的本地图片引用应直接使用 images/...。不要复制为 iMF_images/、assets/ 或其他分散目录，除非已有同名冲突且必须说明。
5. 如果阅读后发现类别判断不合适，移动整个论文工作目录，不能只移动总结 Markdown。

无 PDF 时的获取流程

1. python3 assets/zotero_helper.py info {item_id} 获取论文信息
2. 按优先级获取：arXiv HTML > arXiv PDF > DOI > WebSearch 标题
3. 判断 arXiv ID：从 URL / Zotero extra 字段 / 标题搜索
4. 推荐先用 MinerU 解析 https://arxiv.org/pdf/{arxiv_id}.pdf 成 Markdown；如果失败，再 WebFetch https://arxiv.org/html/{arxiv_id}
5. 跳过条件：既无 PDF 也无在线来源 / 非论文内容

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

2. 阅读模式

模式	触发词	输出
快速摘要	"快速看一下"、"quick"	3-5 句核心贡献
完整解析	"详细分析"、默认	结构化笔记（用模板）
批判分析	"批判性分析"、"critique"	方法论优缺点评估
知识提取	"提取公式"、"技术细节"	公式 + 算法伪代码

3. 笔记生成

模板: 严格遵循 assets/paper-note-template-integrated.md，不可自行简化。旧版分区式模板保留在 assets/paper-note-template.md，仅作历史参考；正式阅读论文时默认使用 integrated 模板。

核心质量规则

1. 零遗漏: 论文中所有 Figure、所有公式、所有 Table 必须全部出现在笔记中
2. 内联概念链接: 正文中首次出现的技术术语必须用 [[概念]] 链接，不仅仅是结尾
3. 严禁 ASCII 流程图: 用结构化 Markdown 列表 + $数学符号$ 描述架构
4. 公式完整性: 每个公式必须有名称（[[概念|名称]]）、LaTeX 公式、含义、符号说明
5. 图片外链优先: arXiv HTML / 项目主页 / GitHub，找不到再本地下载
6. 图文公式共址: 方法解释、关键图、相关公式和支撑表格必须放在同一个理解单元中；不要重新生成“方法详解 → 关键公式 → 关键图表”的分离式结构
7. 证据链阅读: 实验表格和可视化必须说明它们支撑哪个模块、能证明什么、不能证明什么
8. 索引用于查漏: ## 全量图表与公式索引 只作为 completeness checklist；正文首次相关位置必须已经嵌入对应 Figure/Table/Equation

公式/图片/表格的详细质量规范见 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 总数，确认提取数量是否完整
3. 来源 B — 项目主页（HTML 404 或图片不全时）：
   • 从摘要/HTML 中查找项目主页 URL（常见模式：project page、github.io、our website）
   • WebFetch 项目主页，提取展示图片（通常包含 teaser / demo 图）
4. 来源 C — MinerU Markdown（HTML/项目主页不完整时）：
   • 从 MinerU 输出 Markdown 中提取 Figure 标题、图片链接、表格和公式上下文
   • 如果使用 MinerU 本地图片，保存 Obsidian 笔记时必须把 Markdown 引用到的 images/ 文件夹一并复制到笔记附近，保持相对路径可用
5. 来源 D — PDF 提取（前面都失败时）：
   • pdfimages -png 从 PDF 中提取，筛选 >10KB 的有效图片
6. 笔记中用 ![Figure X](url) 外链嵌入
7. 验证：外链可加载 / 本地文件 >10KB
8. URL 去重：写入前检查 URL 中是否有重复的 arxiv_id 路径段（如 2603.05312v1/2603.05312v1/），有则删除重复段。详见 references/image-troubleshooting.md

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

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

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

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

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

公式格式

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

4. Obsidian 保存

文件命名

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

保存路径

保存到论文工作目录中：{NOTES_PATH}/{最合适类别}/{论文标题}/{方法名}.md。

同一目录内必须同时包含：

• MinerU 解析 Markdown：{arxiv_id或slug}.mineru.md
• MinerU 图片目录：images/
• 总结笔记：{方法名}.md

如果 Zotero 分类层级与论文内容明显不符，以论文内容为准，并移动整个论文工作目录。

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
content_source: mineru        # mineru | arxiv-html | webfetch-abs | search-only
content_source_attempted: [mineru]  # 实际尝试过的来源（按顺序），失败的标 `-failed-原因` 后缀
incomplete: false              # 仅当 content_source ∈ {webfetch-abs, search-only} 时为 true
created: YYYY-MM-DD
---

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

content_source 取值规则（按论文正文实际来源填，不要乱写）：

• mineru：成功用 MinerU 解析得到完整 Markdown（含公式、表格、章节、图片）
• arxiv-html：MinerU 失败但 WebFetch arxiv.org/html/{id} 成功，能拿到正文 + 章节 + Figure caption
• webfetch-abs：以上都失败，只拿到 arXiv abs 页（仅 title + abstract + author）→ 必须同时设 incomplete: true
• search-only：连 abs 页都拿不到，仅靠 WebSearch 搜到的零散信息拼凑 → 必须同时设 incomplete: true

content_source_attempted 例子：[mineru-failed-timeout, arxiv-html] 表示先试 MinerU 超时，再 fallback 到 HTML 成功。这个列表用于后续诊断为什么某些笔记缺失内容。

保存后自动执行

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

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

2. 只有在 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. 别名归一化（先做，避免后续步骤建出重复概念）：

   python3 ../_shared/concept_alias_resolver.py --normalize "{笔记完整路径}"
   

   把笔记里的 [[QFormer]] / [[BLIP2]] / [[Rotary Position Embedding]] 等改写成 canonical 形式（[[Q-Former]] / [[BLIP-2]] / [[RoPE]]）。如果发现写笔记时常出现某个未在 concept_aliases.json 中的别名，追加到 _shared/concept_aliases.json 再重跑。
2. 扫描论文笔记中所有 [[概念]] 链接（已经是 canonical 形式）
3. 检查每个链接对应的概念笔记是否存在：
   • 优先用 concept_alias_resolver.find_concept_note(name)，能自动按 canonical 名查找
   • 如果脚本不可用，用 ls + find
4. 创建不存在的概念（不可跳过），自动归类到对应子目录，文件名用 canonical 形式

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

自检

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

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

6a 内容完整性

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

6b 内容质量（脚本验证）

python3 ../_shared/note_quality_check.py "{笔记完整路径}"

PASS 才算合格。FAIL 时不能手改凑指标，必须找出 paperflow-reader 偷工的环节重做。

6c claim 一致性（防止编造数字）

python3 ../_shared/verify_claims.py "{笔记完整路径}" --arxiv-id {arxiv_id}
# 或：
python3 ../_shared/verify_claims.py "{笔记完整路径}" --abstract-file "{论文工作目录}/{arxiv_id}.mineru.md"

• 0 unverified → 通过
• 有 unverified → 必须对每条手动核对原文：
  • 真的能在论文里找到 → 数字写对了但脚本召回不足，可加 ⚠️ verified-manual 注释跳过
  • 找不到 → 笔记里编造了数字，必须修正或删除该 claim，不要留着

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 — 公式/图片/表格的详细质量规范 + 自检清单