Iayce/paperdown2md

paperdown2md — 論文 PDF 下載 + MinerU 轉 Markdown

把用戶給出的一篇或多篇論文標識，在指定輸出目錄下落成標準結構：

<output-dir>/
└── <論文資料夾名>/
    ├── <論文名>.pdf      # 與資料夾同名或用戶指定的短名
    ├── full.md           # MinerU extract 全文 Markdown
    └── images/           # 文中圖片資源

參考範例：paperdown2md/example/CIDD: Collaborative Intelligence for Structure-Based Drug Design Empowered by LLMs/（資料夾可用代表性短名 CIDD，也可用完整標題）。

何時觸發

• 用戶給出論文標題、arXiv/DOI/連結、微信公眾號/小紅書貼文連結、或直接 PDF URL（可多個）
• 用戶指定目標目錄（如 paperdown2md/example/、~/papers/）
• 需要 PDF + full.md + images 三件套，且解析要走 MinerU extract（Token），不要用 flash-extract 代替大論文

核心流程（每篇論文）

1. 確認輸出目錄

• 用戶必須給出 --output-dir / 目標路徑；未指定時先問，不要猜。
• 路徑不存在則建立；已有同名資料夾時先說明是否覆蓋或跳過。

2. 決定資料夾名與 PDF 檔名

按優先級選擇資料夾名（同時作為預設 PDF 基名，副檔名 .pdf）：

論文類型	命名建議	範例
提出新模型/方法	模型/方法縮寫或專名	CIDD、TargetDiff
Benchmark 論文	benchmark 名稱	CrossDocked2020
資料集 論文	資料集名稱	ImageNet
其他	論文標題（可截斷至 ~120 字符）	與 PDF 原標題一致

規則：

• 去掉檔案系統非法字符 \ / : * ? " < > |
• 用戶若明確說「資料夾叫 CIDD」，以用戶為準
• 多篇論文批次處理時，每篇單獨資料夾；不要混在一個目錄裡

3. 解析標識並下載 PDF

優先使用 bundled 腳本（解析 arXiv、DOI、直鏈 PDF、公眾號/小紅書貼文、OpenAlex/arXiv 標題檢索）。

Python 必須在 skillsplace 環境執行——用 scripts/run.sh（自動定位 skillsplace 的 Python），不要直接 python3：

bash paperdown2md/scripts/run.sh \
  -o "<輸出目錄>" \
  --name "<資料夾名>" \
  "<標識>"

或顯式指定直譯器（macOS 本機）：

/Users/jaycexu/anaconda3/envs/skillsplace/bin/python paperdown2md/scripts/paperdown2md.py \
  -o "<輸出目錄>" --name "<資料夾名>" "<標識>"

環境	skillsplace 路徑
macOS 本機	/Users/jaycexu/anaconda3/envs/skillsplace
Windows 筆電	D:\Anaconda\envs\skillsplace
jumphost-inner	~/xsjenv/miniconda3/envs/skillsplace

標識 可以是：

• arXiv：https://arxiv.org/abs/xxxx.xxxxx 或 xxxx.xxxxx
• DOI：10.1038/... 或 https://doi.org/...
• 直接 PDF：https://....pdf
• 微信公眾號文章：https://mp.weixin.qq.com/s/...
• 小紅書貼文：https://www.xiaohongshu.com/explore/...（建議保留分享連結中的 xsec_token 等參數）
• 英文標題：腳本經 OpenAlex 搜尋並取最佳開放獲取 PDF

社群媒體貼文（公眾號 / 小紅書，v1.1+）

以公眾號或小紅書貼文為起點時，腳本會：

1. 公眾號：先用 HTTP 拉 HTML；小紅書：預設走瀏覽器 CDP（內容多為 JS 渲染）
2. 若 HTTP 失敗或被反爬（如「環境異常」、筆記無法瀏覽）→ 自動切瀏覽器 CDP（web-access 的 Chrome Proxy，localhost:3456）
3. 從正文提取 arXiv / DOI / PDF 直鏈；若無直鏈 → 用貼文標題與正文關鍵詞做 OpenAlex + arXiv API 文獻檢索（含相關性過濾）
4. 用貼文標題作資料夾名（可用 --name 覆蓋），再按既有流程下載 PDF + MinerU

# 公眾號
bash paperdown2md/scripts/run.sh -o "<輸出目錄>" \
  "https://mp.weixin.qq.com/s/jMW2lbgiHDka8CASFtQ81w"

# 小紅書（保留完整分享 URL）
bash paperdown2md/scripts/run.sh -o "<輸出目錄>" \
  "https://www.xiaohongshu.com/explore/6a1c2d75000000000603739b?xsec_token=..."

瀏覽器兜底前提：Chrome 已開啟遠端偵錯（chrome://inspect/#remote-debugging），且可執行：

node ~/.cursor/skills/web-access/scripts/check-deps.mjs

檢索仍無結果時，Agent 可再用 lr search、web-access 或 WebSearch 定位論文，把 arXiv/DOI 連結傳給 run.sh。

腳本搞不定時，再：

1. 用 lr search arxiv "<英文標題>" --format json 或 lr search "<標題>" --format json 找 url，取 arXiv PDF
2. 按 web-access 查出版方頁面（注意版權；優先 OA / arXiv）
3. 仍無 PDF → 告知用戶需手動放入資料夾，再只對已有 PDF 跑 MinerU

下載後 PDF 命名：--name CIDD → CIDD.pdf；未指定 --name 時用解析到的標題。

4. MinerU extract → full.md + images/

一律使用 Token 版 extract（表格/公式/大檔案）。操作前：

export MINERU_TOKEN="$(tr -d '\n' < "$HOME/.cursor/skills/mineru/key")"
mineru-open-api auth --verify

• Token 缺失：明確告訴用戶配置 ~/.cursor/skills/mineru/key 或 MINERU_TOKEN，不要改用 flash-extract 糊弄大 PDF。
• PDF >10MB 或頁數多：--model vlm，--timeout 3600（學術論文預設）
• 掃描件：加 --ocr

腳本已包含 extract 與整理步驟；手動執行時：

mineru-open-api extract "<paper-dir>/<name>.pdf" \
  -o "<paper-dir>/_mineru_out" -f md --model vlm --timeout 3600

# 將 _mineru_out/*.md → full.md，_mineru_out/images → images/，刪除 _mineru_out

整理後檢查：full.md 中 ![](images/...) 路徑在本機存在。

5. 批次多篇

對每個標識重複步驟 2–4。可一次傳多個 source（僅當共用同一 --name 不適用時分開跑）：

bash paperdown2md/scripts/run.sh -o "<輸出目錄>" \
  "https://arxiv.org/abs/2301.00001" \
  "10.1038/s41586-020-00000" \
  "Another Paper Title In English"

批次時每篇單獨 --name：多次呼叫腳本，或先由你根據標題決定短名再執行。

完成標準（向用戶回報）

每篇論文回報：

• 資料夾路徑
• PDF 檔名與大小
• full.md 行數/大小、images/ 圖片數量
• 若某篇失敗：原因（無 OA PDF、無 Token、MinerU 逾時等）與建議下一步

依賴與排障

問題	處理
no API token found	配置 MinerU Token，見 mineru
mineru-open-api: command not found	安裝 MinerU CLI（mineru skill 安裝腳本）
OpenAlex 無 PDF	換 arXiv 連結、lr search、或請用戶提供 PDF
公眾號「環境異常」	腳本會自動嘗試 CDP 瀏覽器；仍失敗則請用戶完成驗證或直傳 arXiv/DOI
小紅書筆記無法瀏覽	使用 App 分享的完整 URL（含 xsec_token）；或直傳 arXiv/DOI
貼文無論文直鏈	腳本會用標題/關鍵詞檢索 OpenAlex + arXiv；仍失敗再用 lr search / web-access
extract 逾時	增大 --timeout 或向用戶說明重試
用戶只要 PDF 不要 Markdown	paperdown2md.py --skip-extract

範例

單篇（CIDD，代表性資料夾名）：

bash paperdown2md/scripts/run.sh \
  -o "paperdown2md/example" \
  --name "CIDD: Collaborative Intelligence for Structure-Based Drug Design Empowered by LLMs" \
  "CIDD Collaborative Intelligence Structure-Based Drug Design LLMs"

從微信公眾號文章起步（HTTP 失敗時自動走瀏覽器 CDP）：

bash paperdown2md/scripts/run.sh \
  -o "paperdown2md/example" \
  "https://mp.weixin.qq.com/s/jMW2lbgiHDka8CASFtQ81w"

從小紅書貼文起步（無直鏈時自動檢索 arXiv/OpenAlex）：

bash paperdown2md/scripts/run.sh \
  -o "paperdown2md/example" \
  "https://www.xiaohongshu.com/explore/6a1c2d75000000000603739b?xsec_token=..."

或使用已有 PDF 僅做 MinerU（需 PDF 已在資料夾內）：

export MINERU_TOKEN="$(tr -d '\n' < "$HOME/.cursor/skills/mineru/key")"
mineru-open-api extract "paperdown2md/example/CIDD.../CIDD....pdf" \
  -o "paperdown2md/example/CIDD.../_mineru_out" -f md --model vlm --timeout 3600
# 再整理為 full.md + images/

與其他 skill 的分工

• mineru：只轉已有 PDF/檔案 → 讀 mineru skill
• lightread-cli：LightRead 資料庫、筆記、綜述 → 不是本地 paperdown2md 目錄結構
• web-access：網頁檢索、非結構化下載
• paperdown2md（本 skill）：本地目錄 + PDF + full.md + images 一條龍
• aiforbio-paper-reading（下游）：在 full.md + images/ 就緒後，於同一論文目錄寫 {ModelName}record.md 生物醫學精讀（公式逐元素推導 + 樣本數據流）。見 aiforbio-paper-reading

與 aiforbio-paper-reading 聯動（推薦流水線）

本 skill 負責獲取與轉換；精讀記錄交給 aiforbio-paper-reading：

paperdown2md  -o <文獻目錄> "<標識>"
    →  <文獻目錄>/<論文名>/{pdf, full.md, images/}
aiforbio-paper-reading
    →  <文獻目錄>/<論文名>/{ModelName}record.md

full.md + images/ 生成後，若用戶要「讀論文 / 寫 record / 精讀 / 公式推導 / 數據流範例」，提醒並銜接 aiforbio-paper-reading，勿在本 skill 內寫長篇閱讀筆記。

腳本說明

• scripts/run.sh：唯一推薦的入口；自動選用 skillsplace 裡的 Python。
• scripts/paperdown2md.py：stdlib only；啟動時校驗是否在 skillsplace；resolve → 下載 → mineru-open-api extract → full.md / images/。

Agent 執行本 skill 時：先 run.sh，不要 python3 paperdown2md.py。

安裝到 Cursor 全域 skills：

git clone https://github.com/Iayce/paperdown2md.git ~/.cursor/skills/paperdown2md

或 symlink 本地 checkout：ln -s /path/to/paperdown2md ~/.cursor/skills/paperdown2md