paper-ingest

name	paper-ingest
description	论文资产入库：接收 arXiv ID、PDF URL 或本地 PDF，稳定获取 PDF，并调用 MinerU 生成标准 Markdown/图片资产；正式分析交给 paper-analyze。
allowed-tools	Read, Write, Bash, WebFetch

目标

把论文原始资产完整、稳定地放进 Obsidian，作为后续阅读、分析、翻译、审稿的证据底座。

paper-ingest 只负责资产入库，不负责正式分析笔记、导师七问、综述五字段，也不负责审稿意见。它要做好的事情只有几件：

• 稳定获取论文 PDF
• 验证拿到的确实是可用 PDF，而不是跳转页或错误页
• 调用 MinerU 把 PDF 转成标准 Markdown 和图片资产
• 把产物整理成统一、可复用的目录结构
• 写出 assets.md 和 ingest_manifest.json
• 为 paper-translate、paper-analyze、paper-review 提供干净资产入口

必须产出

• 原始 PDF
• MinerU 转换得到的英文 Markdown
• MinerU 提取的图片 / 媒体资产
• 资产索引 assets.md
• 机器可读清单 ingest_manifest.json

关键原则

1. 下载成功和 MinerU 成功分开判断

   • PDF 成功落盘并通过校验，就算资产入库成功。
   • MinerU 失败不能伪装成“已经完整转好 Markdown”。

2. 优先做真实 PDF 校验

   • 不能只看 HTTP 200。
   • 至少检查：
     • 文件存在
     • 文件头是 %PDF
     • 文件大小足够

3. 多源回退下载

   • 优先顺序通常是：
     • arXiv PDF
     • OpenReview PDF
     • venue / DOI 页面解析出的 PDF
     • DBLP 或其他外链

4. 产物结构必须稳定

   • 标准目录形态应尽量保持为：
     • 20_Research/Papers/_assets/<paper-slug>/<paper-slug>.pdf
     • 20_Research/Papers/_assets/<paper-slug>/mineru/<paper-id-or-stem>/auto/<paper-id-or-stem>.md
     • 20_Research/Papers/_assets/<paper-slug>/mineru/<paper-id-or-stem>/auto/images/...
   • <paper-slug> 和 <paper-id-or-stem> 必须优先使用短命名：
     • paper_id / arxiv_id
     • 其次是显式稳定 ID
     • 最后才是压缩短 slug
   • 不再允许直接用长标题主导 asset 顶层目录名。

5. 图片真实文件名必须短

   • 默认把正文引用图重命名成短名：
     • fig01.jpg
     • fig02.jpg
     • fig03.png
   • 不要默认把长语义直接写进真实文件名，例如：
     • fig5-workflow.jpg
     • fig8-latency-breakdown.jpg
   • 图的语义信息应放进 manifest / assets.md 的映射层，而不是放进长文件名。
   • 这样做是为了避免 Windows 深路径再次导致 MinerU / 文件复制失败。

6. 未引用图片与 artifact 分开看

   • 被 Markdown 正文引用的 figure 图片，应统一进 figNN 短名体系。
   • 未被正文引用的 MinerU artifact 图可以保留原名，或单独标记为未引用资产。
   • 不要为了追求整齐，把所有 hash 图都强行混进主 figure 编号里。

7. 不把历史补丁文件当作标准成功产物

   • simple.pdf
   • simple.txt
   • fallback.md
   • 这些如果只是特殊事故里的残留，最多作为历史记录，不能当成标准 ingest 产物去鼓励复用。

8. 所有关键信息都要写进 manifest

   • 后续必须能看出问题到底发生在：
     • 输入解析
     • PDF 下载
     • PDF 校验
     • MinerU 转换
     • 图片重命名 / 映射

支持输入

• arXiv ID，例如 2402.12345
• arXiv URL
• DBLP 论文记录页
• 直接 PDF URL
• 论文 landing page URL
• 本地 PDF 路径

默认路径

• Obsidian vault：C:/Users/peng/Documents/PHR/obsidian_phr
• 配置文件：C:/Users/peng/Documents/PHR/obsidian_phr/99_System/Config/research_interests.yaml
• 资产目录：20_Research/Papers/_assets/<paper-slug>/
• 脚本：scripts/ingest_paper.py

目录规则

• 如果论文目录里已经有 PDF，ingest 必须直接使用这份 PDF，并把这个目录视为唯一 asset directory。
• 如果用户明确指定了某个论文目录，那么 PDF、MinerU、assets.md、ingest_manifest.json 都必须写回这个目录。
• 只有当目标论文目录里没有 PDF 时，才允许下载。
• 不再把 MinerU 完整输出先写到中介目录再整棵搬回。
• MinerU 默认直接写入最终 asset_dir/mineru/<short-name>/auto/。
• 如需短路径辅助手段，只允许用于输入 PDF 的短别名或运行期链接，不允许额外保留输出中介目录。

工作流程

1. 先调用 paper-search 查重，确认是否已存在 PDF、MinerU Markdown 或正式笔记。
2. 解析输入，识别 arXiv / DBLP / landing page / PDF URL / 本地 PDF。
3. 如果目标论文目录中已有 PDF，直接复用，不再下载。
4. 如果没有 PDF，再生成 PDF 候选源列表并按优先级依次尝试。
5. 下载后做 PDF 校验。
6. 只有 PDF 校验通过时，才调用 MinerU：

mineru -p <pdf> -o <output> -b pipeline

7. 保存 MinerU 输出的 Markdown、图片和相关资产，保持标准目录层级。
8. 对正文引用图片统一做短名重命名为 figNN，并把原名到短名、短名到语义说明的映射写进 manifest 和 assets.md。
9. 在写入 manifest 前，必须检查：
   • pdf_download_status
   • pdf_validation
   • mineru_status
   • mineru_md
   • 图片引用是否仍残留 hash 名
10. 写入 assets.md 和 ingest_manifest.json。
11. 返回下一步建议：

• 先调用 paper-translate 生成中文版 Markdown
• 再调用 paper-analyze 生成正式论文笔记

推荐命令

python scripts/ingest_paper.py `
  --input "2402.12345" `
  --vault "C:/Users/peng/Documents/PHR/obsidian_phr" `
  --domain "LLM Inference Systems"

python scripts/ingest_paper.py `
  --input "https://dblp.org/rec/conf/asplos/xxxx" `
  --vault "C:/Users/peng/Documents/PHR/obsidian_phr"

python scripts/ingest_paper.py `
  --input "C:/path/to/paper.pdf" `
  --title "Paper Title" `
  --authors "Author A, Author B" `
  --domain "Hierarchical State Optimization"

输出要求

assets.md 至少应包含：

• 论文标题 / 作者 / 年份 / venue / 链接
• PDF 链接
• 来源链接
• MinerU Markdown 链接
• 资产目录
• manifest 链接
• 推荐正式笔记路径
• 分类结果与原因
• 图片目录与图片映射
• MinerU 状态

ingest_manifest.json 至少应包含：

• 论文元数据
• 命名来源与冲突回退信息
• PDF 下载状态与尝试记录
• PDF 校验信息
• MinerU 状态与尝试记录
• MinerU 恢复信息或失败阶段摘要
• 资产路径
• 图片映射
• 图片归一化校验结果
• 代理隔离策略摘要
• 推荐正式笔记路径

规则

• 缺失证据就写 TBD，不要编造。
• 保留 MinerU Markdown 作为原始证据。
• 不创建或覆盖正式论文分析笔记，除非用户明确要求。
• 如果 MinerU 没有产出标准 Markdown 结构，不要把半成品静默冒充成标准成功结果。

与其他 skill 的关系

• paper-search：先查重，再决定是否入库
• paper-translate：在入库完成后生成中文版 Markdown
• paper-analyze：基于英文原始证据生成正式分析笔记
• paper-review：基于原文、笔记和模板生成严格审稿意见
• start-my-day / conf-papers：会调用本 skill 完成批量资产入库