pdf2md-agent-skill - PDF/文档转 Markdown

Que fait 文档转 Markdown ?

Quand déclencher

Lorsque vous devez lire le contenu d'un PDF, utilisez d'abord ce skill pour le convertir en Markdown.

Convertissez d'abord le PDF en Markdown, puis utilisez l'outil de lecture de texte de l'agent actuel pour lire le fichier de sortie.

Scénarios de déclenchement :

• L'utilisateur a fourni le chemin d'un PDF et demande à le lire, le résumer, l'analyser, le traduire ou poser des questions
• Vous devez référencer un contenu spécifique du PDF
• Vous devez extraire des tableaux, des formules ou des références du PDF

Flux de travail standard

Résolvez d'abord <skill_dir> comme le répertoire contenant ce SKILL.md. Ne présumez pas que le skill est installé dans ~/.claude/skills, car les chemins diffèrent pour Codex, les installations personnalisées et Windows.

Exécutez dans l'ordre fixe :

# Étape 1 : Conversion (gère automatiquement tous les types de PDF, pas besoin de les distinguer)
python3 "<skill_dir>/scripts/md_convert.py" "<chemin_du_pdf>" -o "<répertoire_temporaire_du_projet>/<nom>.md"

# Étape 2 : Utilisez l'outil de lecture de texte de l'agent actuel pour lire le fichier .md généré

Exemple :

python3 "<skill_dir>/scripts/md_convert.py" \
  "/chemin/vers/un-article.pdf" \
  -o "./article.md"

Lisez ensuite ./article.md.

Pourquoi cette conception

Les PDF comportent plusieurs types de pages, nécessitant des stratégies différentes. Le script détermine automatiquement le type de chaque page, vous n'avez pas à vous en soucier :

Type de page	Stratégie du script	Explication
Pages de texte normales	Extraction PyMuPDF	Rapide, gratuit, fusion de paragraphes + tri en deux colonnes + filtrage d'en-têtes
Pages denses en formules	OCR visuel Ark	Transcription des formules en LaTeX (\( E_i \)), évite la fragmentation
Pages scannées	OCR visuel Ark	Rendu en image + reconnaissance par modèle visuel
Pages mixtes	Routage automatique page par page	Un article ne sera OCRisé que sur les pages de formules, équilibrant vitesse et qualité

Stratégie hybride intelligente : Le script détecte la densité de symboles mathématiques par page. Les pages de formules (densité > 1,5 %) sont automatiquement OCRisées pour transcrire les formules en LaTeX, tandis que les pages de texte sont traitées par PyMuPDF.

Comportements interdits :

• ❌ Ne déterminez pas le type de PDF avant d'appeler la commande – appelez directement, le script est entièrement automatique
• ❌ N'utilisez pas la commande brute markitdown pour convertir des PDF (le backend pdfminer par défaut perd les espaces)
• ❌ Ne lisez pas le PDF comme un fichier texte brut
• ❌ N'omettez pas le paramètre -o (ce paramètre est obligatoire)

Paramètres

Paramètre	Description	Quand l'utiliser
input	Chemin du fichier d'entrée (obligatoire)	Toujours
-o, --output	Chemin du fichier .md de sortie (obligatoire)	Toujours
--ocr	Forcer l'OCR complet sur tout le document	Uniquement si la détection automatique échoue clairement (rare)
-m, --model	Modèle visuel, par défaut doubao-seed-1-6-flash-250828	Si vous devez changer de modèle
--allow-partial	Permet de réussir même si des pages OCR échouent	Uniquement si l'utilisateur accepte explicitement une sortie incomplète
--no-llm	Désactive l'augmentation LLM pour les formats non-PDF	Uniquement pour les formats non-PDF
--version	Affiche le numéro de version	Pour vérifier la version

L'appel par défaut ne doit inclure aucun paramètre optionnel :

python3 "<skill_dir>/scripts/md_convert.py" input.pdf -o ./out.md

Formats non-PDF

Word/PPT/Excel/images sont également pris en charge, en utilisant le chemin natif de markitdown :

python3 "<skill_dir>/scripts/md_convert.py" rapport.docx -o ./rapport.md

Ces formats peuvent être lus directement avec les outils de document correspondants ; convertissez-les en Markdown uniquement si une structure unifiée est nécessaire.

Environnement et dépendances

Variables d'environnement :

• ARK_API_KEY – Obligatoire pour les pages denses en formules, pages scannées ou pages vides déclenchant un OCR visuel. Les PDF textuels qui ne déclenchent pas d'OCR n'ont pas besoin de cette variable.
• ARK_BASE_URL – Optionnel, par défaut https://ark.cn-beijing.volces.com/api/v3. Ark est vérifié ; les autres points de terminaison doivent être compatibles avec Chat Completions, les entrées visuelles et les data URL. Testez-les avant utilisation.

Dépendances :

• pymupdf (extraction de texte PDF + rendu)
• openai (client du modèle visuel Ark)
• markitdown (backend pour les formats non-PDF)

Nécessite Python 3.10+.

Gestion des erreurs

Message d'erreur	Cause	Traitement
ARK_API_KEY non défini	Les pages de formules/scannées/vides nécessitent un OCR visuel	Configurez la clé, ou utilisez une entrée ne déclenchant pas d'OCR
Fichier inexistant	Chemin erroné ou contenant des espaces sans guillemets	Entourez le chemin de guillemets
openai/markitdown/pymupdf non installé	Dépendance manquante	pip install <nom_du_paquet>
PDF chiffré	Le PDF est protégé par un mot de passe	Déchiffrez d'abord le PDF
Pages OCR manquantes détectées	Clé invalide / problème réseau / nom de modèle	Vérifiez l'erreur puis réessayez ; utilisez --allow-partial uniquement si une sortie incomplète est acceptée
Le chemin de sortie ne peut pas être identique au fichier d'entrée	La sortie écraserait le document original	Spécifiez un chemin différent pour le Markdown
Conversion réussie mais contenu vide	Il s'agit peut-être d'un PDF purement image mal interprété	Ajoutez --ocr pour forcer un OCR complet

En cas d'échec de la conversion : ne réessayez pas la même commande à plusieurs reprises, consultez d'abord les messages d'erreur sur stderr pour identifier le problème.

Conventions de sortie

• Le script écrit le Markdown dans le fichier spécifié par -o, et envoie les logs de traitement (type de chaque page, progression) sur stderr
• En cas de succès, la dernière ligne est : OK: <entrée> -> <sortie> (XX Ko)
• Par défaut, si une page OCR échoue, le script retourne un code de sortie non nul ; utilisez explicitement --allow-partial pour accepter une sortie incomplète
• Lisez le fichier de sortie avec un outil de lecture de texte avant de poursuivre le travail basé sur son contenu

Répartition avec les autres outils

Scénario	Outil
Lire du contenu PDF	Ce skill (obligatoire)
Lire Word/PPT/Excel	Ce skill ou l'outil document de l'agent actuel
Lire texte pur/code/Markdown	L'outil de lecture de texte de l'agent actuel