paperdown2md — 논문 PDF 다운로드 + MinerU → Markdown 변환

사용자가 제공한 하나 이상의 논문 식별자를 지정된 출력 디렉터리에 표준 구조로 저장합니다:

<출력-디렉터리>/
└── <논문-폴더명>/
    ├── <논문명>.pdf      # 폴더명과 동일하거나 사용자가 지정한 짧은 이름
    ├── full.md           # MinerU extract 전체 Markdown
    └── images/           # 논문 내 이미지 리소스

참고 예시: paperdown2md/example/CIDD: Collaborative Intelligence for Structure-Based Drug Design Empowered by LLMs/ (폴더는 대표적인 짧은 이름 CIDD 또는 전체 제목 사용 가능)

실행 조건

사용자가 논문 제목, arXiv/DOI/링크, WeChat 공개 계정/Xiaohongshu 게시물 링크, 또는 직접 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 다운로드

bundle된 스크립트를 우선 사용 (arXiv, DOI, 직접 PDF 링크, 공개 계정/Xiaohongshu 게시물, 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
WeChat 공개 계정 게시물: https://mp.weixin.qq.com/s/...
Xiaohongshu 게시물: https://www.xiaohongshu.com/explore/... (공유 링크의 xsec_token 등 매개변수 보존 권장)
영문 제목: 스크립트가 OpenAlex를 통해 검색하고 최상의 오픈 액세스 PDF 선택

소셜 미디어 게시물 (공개 계정 / Xiaohongshu, v1.1+)

공개 계정 또는 Xiaohongshu 게시물에서 시작할 경우, 스크립트는:

공개 계정: 먼저 HTTP로 HTML 가져오기; Xiaohongshu: 기본적으로 브라우저 CDP 사용 (내용이 주로 JS 렌더링)
HTTP 실패 또는 반크롤링(예: '환경 이상', 노트를 볼 수 없음) → 자동으로 브라우저 CDP로 전환 (web-access의 Chrome Proxy, localhost:3456)
본문에서 arXiv / DOI / PDF 직접 링크 추출; 직접 링크 없음 → 게시물 제목과 본문 키워드를 사용하여 OpenAlex + arXiv API 문헌 검색 (관련성 필터링 포함)
게시물 제목을 폴더명으로 사용 (--name으로 재정의 가능), 이후 기존 프로세스에 따라 PDF 다운로드 + MinerU

# 공개 계정
bash paperdown2md/scripts/run.sh -o "<출력 디렉터리>" \
  "https://mp.weixin.qq.com/s/jMW2lbgiHDka8CASFtQ81w"

# Xiaohongshu (전체 공유 URL 유지)
bash paperdown2md/scripts/run.sh -o "<출력 디렉터리>" \
  "https://www.xiaohongshu.com/explore/6a1c2d75000000000603739b?xsec_token=..."

브라우저 fallback 전제: Chrome이 원격 디버깅 활성화 (chrome://inspect/#remote-debugging) 및 다음 명령어 실행 가능:

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

검색해도 결과가 없으면 Agent가 lr search, web-access 또는 WebSearch를 사용하여 논문을 찾고 arXiv/DOI 링크를 run.sh에 전달할 수 있음.

스크립트가 처리하지 못할 경우:

lr search arxiv "<영문 제목>" --format json 또는 lr search "<제목>" --format json으로 url을 찾아 arXiv PDF 가져오기
web-access에 따라 출판사 페이지 확인 (저작권 주의; OA / arXiv 우선)
여전히 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 "<논문-디렉터리>/<이름>.pdf" \
  -o "<논문-디렉터리>/_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 직접 전달
Xiaohongshu 노트를 볼 수 없음	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"

WeChat 공개 계정 게시물에서 시작 (HTTP 실패 시 자동 브라우저 CDP):

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

Xiaohongshu 게시물에서 시작 (직접 링크 없을 시 자동 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

또는 로컬 checkout 심볼릭 링크: ln -s /path/to/paperdown2md ~/.cursor/skills/paperdown2md

paperdown2md — 논문 PDF 다운로드 + MinerU 변환 to Markdown