Peytontalismanic424/paper-share-skills

Konvertiert ein PDF (insb. wissenschaftliche Arbeiten) mit MinerU in sauberes Markdown – erhält Lesereihenfolge, LaTeX-Formeln, Tabellen und Abbildungen und läuft auf der GPU. Verwenden, wenn der Benutzer bittet, ein PDF in Markdown/Text zu konvertieren/extrahieren. Direkt aufrufen – der Benutzer muss den Skill-Namen nicht eingeben.

Was ist paper-share-skills?

Dieser Skill wandelt PDFs, insbesondere wissenschaftliche Arbeiten, mithilfe von MinerU (opendatalab/MinerU) in sauberes, strukturerhaltendes Markdown um. Er nutzt die GPU (CUDA) für die Pipeline-Verarbeitung und bewahrt die Hierarchie von Überschriften, LaTeX-Mathematik (`$...$`), Abbildungen und Tabellen (als HTML). Er ist ideal für mehrspaltige Layouts, LaTeX-Formeln und Referenzen. Der Skill wird über einen Wrapper (`convert.py`) gesteuert, der einen isolierten MinerU-Interpreter verwendet und die direkte Verwendung des `mineru` CLI vermeidet (das unter Windows 502-Fehler verursacht). Für nicht-akademische Dokumente wird eine leichtere Alternative mit MarkItDown angeboten. Der Skill meldet den Ausgabepfad und liefert optional eine Vorschau. Voraussetzung ist eine CUDA-fähige Umgebung mit vorinstallierten Modellen.

Funktioniert mit~Claude Code~Codex CLI~Cursor

npx skills add https://github.com/Peytontalismanic424/paper-share-skills/tree/HEAD/pdf-to-markdown

Dokumentation

PDF → Markdown (MinerU)

Konvertiert PDFs in sauberes, strukturerhaltendes Markdown mit MinerU (opendatalab/MinerU), der hochwertigsten Open-Source-Engine für wissenschaftliche Arbeiten. Läuft die Pipeline-Backend auf der GPU (CUDA). Die Ausgabe bewahrt die Überschriftenhierarchie, inline-LaTeX-Mathematik ( $...$ ), Abbildungen und Tabellen (als HTML).

Wann verwenden

Der Benutzer bittet darum, „dieses PDF in Markdown (oder Text) zu konvertieren/extrahieren/umzuwandeln.“
Am besten geeignet: wissenschaftliche Arbeiten – mehrspaltige Layouts, LaTeX-Mathematik, Tabellen, Referenzen.
Verarbeitet auch Bilder, .docx, .pptx, .xlsx (Datei direkt übergeben).

Wie ausführen

MinerU lebt in einer dedizierten isolierten Umgebung und wird über den gebündelten Wrapper convert.py gesteuert, der MinerUs Python-API im gleichen Prozess aufruft.

Verwenden Sie hier nicht das CLI mineru – in Version 3.4.0 startet es einen lokalen API-Server, der auf Windows 502 Bad Gateway zurückgibt. Der Wrapper umgeht das.

"$MINERU_PYTHON" \
  "<SKILLS_DIR>/pdf-to-markdown/convert.py" \
  "<input.pdf>" "<output_dir>" --lang de

Argument 1 – Eingabedatei (pdf/image/docx/pptx/xlsx).
Argument 2 – Ausgabeverzeichnis.
--lang – OCR-Sprachhinweis: en für Englisch, ch für Chinesisch/gemischt (Standard ch, verarbeitet auch Englisch). Betrifft nur OCR-te (gescannte) Seiten.
Das Skript gibt bei Erfolg DONE -> <pfad zur .md> aus.

Ausgabelayout

<output_dir>/<name>/auto/<name>.md       # das Markdown
<output_dir>/<name>/auto/images/          # extrahierte Abbildungen (aus der md referenziert)
<output_dir>/<name>/auto/<name>_*.json    # Layout-/Inhaltsmetadaten (können ignoriert werden)

Nach der Konvertierung

Lesen Sie den ausgegebenen Pfad DONE -> ...md und melden Sie ihn dem Benutzer.
Optional eine kurze Vorschau anzeigen (Titel + erste Überschriften).
Hinweisen, wo extrahierte Bilder geschrieben wurden.
Die Qualität ist normalerweise hoch: Überschriften als #, inline-Mathematik als $...$ , Tabellen als <table>-HTML (mit LaTeX in Zellen). Falls ein gescanntes PDF verstümmelt erscheint, erneut mit --method ocr ausführen.

Vorbereitung / Einrichtung (nur wenn etwas fehlt)

Interpreter mit MinerU (Umgebungsvariable MINERU_PYTHON, Standard python).
CUDA überprüfen: $MINERU_PYTHON -c "import torch; print(torch.cuda.is_available())" → True.
Modelle sind bereits heruntergeladen nach ~/.cache/huggingface/hub/ (einmalig).

Falls die Umgebung fehlt, neu erstellen (zuerst uv installieren, falls nötig):

uv venv --python 3.12 "<your-env>"
uv pip install --python "<your-env>/Scripts/python.exe" torch torchvision --index-url https://download.pytorch.org/whl/cu124
uv pip install --python "<your-env>/Scripts/python.exe" -U "mineru[core]"
"<your-env>/Scripts/mineru-models-download.exe" -s huggingface -m pipeline

Dann setzen Sie MINERU_PYTHON auf <your-env>/Scripts/python.exe (Windows) oder <your-env>/bin/python (macOS/Linux). Auf macOS/Linux heißt das Modell-Download-Binary mineru-models-download (ohne .exe-Suffix).

Fehlerbehebung

cuda.is_available() ist False → Torch neu installieren vom cu124-Index (siehe Einrichtung). Die Pipeline läuft notfalls auch auf der CPU, nur langsamer.
Modell-Download fehlgeschlagen/langsam → mineru-models-download erneut ausführen mit -s modelscope.
Gescanntes PDF verstümmelt → --method ocr zum Aufruf von convert.py hinzufügen.
vlm-engine / hybrid-engine Backends → diese benötigen vLLM/SGLang (Linux); sie führen auf Windows zu 502. Verwenden Sie das Standard-pipeline-Backend, das vom Wrapper genutzt wird.

Leichter Fallback (einfache / Office-Dokumente)

Für Nicht-Paper-Dateien, bei denen Layoutgenauigkeit nicht wichtig ist, ist Microsofts MarkItDown schneller und einfacher – aber es zerstört zweispaltige PDFs und Tabellen, daher für wissenschaftliche Arbeiten MinerU bevorzugen:

"$MINERU_PYTHON" -m pip install markitdown
"$MINERU_PYTHON" -m markitdown "<input>" > out.md