Iayce/paperdown2md

paperdown2md — Descarga de PDF de artículos + MinerU a Markdown

Convierte los identificadores de uno o varios artículos dados por el usuario en una estructura estándar bajo un directorio de salida específico:

<directorio-salida>/
└── <nombre-carpeta-artículo>/
    ├── <nombre-artículo>.pdf      # Mismo nombre que la carpeta o un nombre corto especificado por el usuario
    ├── full.md           # Texto completo Markdown extraído por MinerU
    └── images/           # Recursos de imágenes del artículo

Ejemplo de referencia: paperdown2md/example/CIDD: Collaborative Intelligence for Structure-Based Drug Design Empowered by LLMs/ (la carpeta puede usar un nombre corto representativo como CIDD o el título completo).

Cuándo activarlo

• El usuario proporciona el título del artículo, enlace arXiv/DOI, enlace de artículo de WeChat/Xiaohongshu, o una URL directa de PDF (pueden ser varios)
• El usuario especifica un directorio de destino (ej. paperdown2md/example/, ~/papers/)
• Se necesita el paquete PDF + full.md + images, y la extracción debe realizarse con MinerU extract (Token), no sustituir con flash-extract para artículos grandes

Flujo principal (por cada artículo)

1. Confirmar el directorio de salida

• El usuario debe proporcionar --output-dir / ruta de destino; si no se especifica, preguntar primero, no adivinar.
• Si la ruta no existe, crearla; si ya existe una carpeta con el mismo nombre, indicar si se sobrescribe o se omite.

2. Decidir el nombre de la carpeta y el nombre del archivo PDF

Elegir el nombre de la carpeta (que será también la base del nombre del PDF, con extensión .pdf) según esta prioridad:

Tipo de artículo	Sugerencia de nombre	Ejemplo
Propone un nuevo modelo/método	Abreviatura del modelo/método o nombre propio	CIDD, TargetDiff
Artículo de Benchmark	Nombre del benchmark	CrossDocked2020
Artículo de dataset	Nombre del dataset	ImageNet
Otros	Título del artículo (puede truncarse a ~120 caracteres)	Igual que el título original del PDF

Reglas:

• Eliminar caracteres no permitidos en el sistema de archivos: \ / : * ? " < > |
• Si el usuario dice explícitamente «que la carpeta se llame CIDD», seguir al usuario
• Al procesar varios artículos en lote, cada uno en su propia carpeta; no mezclar en un mismo directorio

3. Resolver identificador y descargar PDF

Usar preferentemente el script empaquetado (resuelve arXiv, DOI, enlaces directos de PDF, publicaciones de WeChat/Xiaohongshu, búsqueda por título en OpenAlex/arXiv).

Python debe ejecutarse en el entorno skillsplace — usar scripts/run.sh (localiza automáticamente el Python de skillsplace), no usar python3 directamente:

bash paperdown2md/scripts/run.sh \
  -o "<directorio-salida>" \
  --name "<nombre-carpeta>" \
  "<identificador>"

O especificar explícitamente el intérprete (macOS local):

/Users/jaycexu/anaconda3/envs/skillsplace/bin/python paperdown2md/scripts/paperdown2md.py \
  -o "<directorio-salida>" --name "<nombre-carpeta>" "<identificador>"

Entorno	Ruta de skillsplace
macOS local	/Users/jaycexu/anaconda3/envs/skillsplace
Portátil Windows	D:\Anaconda\envs\skillsplace
jumphost-inner	~/xsjenv/miniconda3/envs/skillsplace

El identificador puede ser:

• arXiv: https://arxiv.org/abs/xxxx.xxxxx o xxxx.xxxxx
• DOI: 10.1038/... o https://doi.org/...
• PDF directo: https://....pdf
• Artículo de WeChat: https://mp.weixin.qq.com/s/...
• Publicación de Xiaohongshu: https://www.xiaohongshu.com/explore/... (se recomienda conservar parámetros como xsec_token en los enlaces compartidos)
• Título en inglés: el script busca en OpenAlex y obtiene el mejor PDF de acceso abierto disponible

Publicaciones en redes sociales (WeChat / Xiaohongshu, v1.1+)

Cuando se parte de una publicación de WeChat o Xiaohongshu, el script:

1. WeChat: primero intenta obtener el HTML por HTTP; Xiaohongshu: por defecto usa navegación CDP (el contenido suele renderizarse con JS)
2. Si HTTP falla o hay bloqueo anti-scraping (ej. «entorno anómalo», nota no visible) → cambia automáticamente a navegación CDP (proxy Chrome de web-access, localhost:3456)
3. Extrae arXiv / DOI / enlaces directos de PDF del texto; si no hay enlaces directos → usa el título y palabras clave de la publicación para una búsqueda en OpenAlex + arXiv API (con filtro de relevancia)
4. Usa el título de la publicación como nombre de carpeta (se puede sobrescribir con --name), luego descarga el PDF y lo procesa con MinerU como siempre

# WeChat
bash paperdown2md/scripts/run.sh -o "<directorio-salida>" \
  "https://mp.weixin.qq.com/s/jMW2lbgiHDka8CASFtQ81w"

# Xiaohongshu (conservar la URL completa compartida)
bash paperdown2md/scripts/run.sh -o "<directorio-salida>" \
  "https://www.xiaohongshu.com/explore/6a1c2d75000000000603739b?xsec_token=..."

Requisito previo para el modo navegación: Chrome con depuración remota habilitada (chrome://inspect/#remote-debugging) y que se pueda ejecutar:

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

Si la búsqueda sigue sin dar resultados, el agente puede usar lr search, web-access o WebSearch para localizar el artículo y pasar el enlace arXiv/DOI a run.sh.

Si el script falla, entonces:

1. Usar lr search arxiv "<título en inglés>" --format json o lr search "<título>" --format json para encontrar la URL y obtener el PDF de arXiv
2. Seguir web-access para consultar la página del editor (respetar derechos de autor; priorizar OA / arXiv)
3. Si aún no hay PDF → informar al usuario de que debe colocarlo manualmente en la carpeta, y luego ejecutar MinerU solo sobre el PDF existente

Nombre del PDF tras la descarga: --name CIDD → CIDD.pdf; si no se especifica --name, se usa el título resuelto.

4. MinerU extract → full.md + images/

Siempre usar la versión Token extract (para tablas/fórmulas/archivos grandes). Antes de ejecutar:

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

• Token faltante: decir claramente al usuario que configure ~/.cursor/skills/mineru/key o MINERU_TOKEN, no usar flash-extract para PDF grandes como solución parche.
• PDF >10MB o con muchas páginas: --model vlm, --timeout 3600 (por defecto para artículos académicos)
• Documentos escaneados: añadir --ocr

El script ya incluye los pasos de extracción y organización; para ejecución manual:

mineru-open-api extract "<directorio-artículo>/<nombre>.pdf" \
  -o "<directorio-artículo>/_mineru_out" -f md --model vlm --timeout 3600

# Mover _mineru_out/*.md → full.md, _mineru_out/images → images/, eliminar _mineru_out

Después de organizar, comprobar que las rutas ![](images/...) en full.md existen localmente.

5. Procesamiento por lotes

Repetir los pasos 2–4 para cada identificador. Se pueden pasar varios sources a la vez (solo si no comparten el mismo --name, ejecutar por separado):

bash paperdown2md/scripts/run.sh -o "<directorio-salida>" \
  "https://arxiv.org/abs/2301.00001" \
  "10.1038/s41586-020-00000" \
  "Otro Título de Artículo en Inglés"

En lotes, cada artículo con su propio --name: llamar al script varias veces, o que el agente decida un nombre corto basado en el título antes de ejecutar.

Criterios de finalización (informar al usuario)

Para cada artículo, informar:

• Ruta de la carpeta
• Nombre y tamaño del archivo PDF
• Número de líneas/tamaño de full.md, número de imágenes en images/
• Si algún artículo falló: motivo (sin PDF OA, sin Token, timeout de MinerU, etc.) y sugerencias para el siguiente paso

Dependencias y resolución de problemas

Problema	Manejo
no API token found	Configurar el Token de MinerU, ver mineru
mineru-open-api: command not found	Instalar CLI de MinerU (script de instalación del skill mineru)
OpenAlex sin PDF	Probar con enlace arXiv, lr search, o pedir al usuario que proporcione el PDF
WeChat «entorno anómalo»	El script intentará automáticamente CDP browser; si falla, pedir al usuario que complete la verificación o envíe directamente arXiv/DOI
Nota de Xiaohongshu no visible	Usar la URL completa compartida desde la app (incluyendo xsec_token); o enviar directamente arXiv/DOI
Publicación sin enlace directo	El script buscará en OpenAlex + arXiv usando título/palabras clave; si falla, usar lr search / web-access
extract timeout	Aumentar --timeout o indicar al usuario que reintente
Usuario solo quiere PDF sin Markdown	paperdown2md.py --skip-extract

Ejemplos

Artículo individual (CIDD, nombre de carpeta representativo):

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"

Desde un artículo de WeChat (cambio automático a CDP browser si HTTP falla):

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

Desde una publicación de Xiaohongshu (búsqueda automática en arXiv/OpenAlex si no hay enlace directo):

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

O usar un PDF existente únicamente para MinerU (el PDF debe estar en la carpeta):

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
# Luego organizar en full.md + images/

División de trabajo con otros skills

• mineru: solo convierte PDF/archivos existentes → consultar skill mineru
• lightread-cli: bases de datos de LightRead, notas, resúmenes → no es la estructura de directorios local de paperdown2md
• web-access: búsqueda web, descargas no estructuradas
• paperdown2md (este skill): directorio local + PDF + full.md + images, todo en uno
• aiforbio-paper-reading (downstream): una vez que full.md + images/ están listos, escribe en el mismo directorio del artículo un {ModelName}record.md con lectura detallada biomédica (derivación de fórmulas paso a paso + flujo de datos de ejemplo). Ver aiforbio-paper-reading

Integración con aiforbio-paper-reading (flujo recomendado)

Este skill se encarga de la obtención y conversión; la lectura detallada corresponde a aiforbio-paper-reading:

paperdown2md  -o <directorio-bibliografía> "<identificador>"
    →  <directorio-bibliografía>/<nombre-artículo>/{pdf, full.md, images/}
aiforbio-paper-reading
    →  <directorio-bibliografía>/<nombre-artículo>/{ModelName}record.md

Una vez generados full.md + images/, si el usuario quiere «leer el artículo / escribir record / lectura detallada / derivación de fórmulas / ejemplos de flujo de datos», recordar y enlazar a aiforbio-paper-reading, no escribir notas extensas dentro de este skill.

Descripción del script

• scripts/run.sh: única entrada recomendada; usa automáticamente el Python de skillsplace.
• scripts/paperdown2md.py: solo con stdlib; al iniciar verifica si está en skillsplace; resolve → descarga → mineru-open-api extract → full.md / images/.

Cuando el agente ejecute este skill: usar primero run.sh, no python3 paperdown2md.py.

Instalación en skills globales de Cursor:

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

O enlace simbólico a un checkout local: ln -s /path/to/paperdown2md ~/.cursor/skills/paperdown2md