Converter PDF para Markdown

Quando usar esta habilidade

Acione esta habilidade sempre que houver um arquivo .pdf que precise ser entendido ou processado — por exemplo, um usuário anexa um PDF e faz perguntas sobre ele, quer um resumo, quer dados ou tabelas específicas extraídas, ou quer que vários PDFs em uma pasta sejam processados juntos. PDF é um formato de layout/impressão, não é confiavelmente legível como texto puro, então sempre o converta para Markdown primeiro usando o script nesta habilidade em vez de tentar abrir ou analisar o arquivo diretamente.

Esta habilidade suporta apenas .pdf — esse é o único formato da família PDF do MarkItDown, então não há formato legado para se preocupar aqui (ao contrário do .doc do Word ou do .xls do Excel).

Tipos de arquivo mistos: Quando o usuário referencia uma pasta ou conjunto de documentos contendo vários tipos de arquivo suportados (.pdf, .docx, .xlsx), esta habilidade lida apenas com arquivos .pdf. O agente DEVE também invocar as habilidades irmãs em paralelo:

• convert-word-to-md para quaisquer arquivos .docx
• convert-excel-to-md para quaisquer arquivos .xlsx

Nunca processe uma pasta e ignore silenciosamente um tipo de arquivo suportado. Todas as três habilidades devem ser invocadas juntas quando tipos mistos estiverem presentes.

Configuração (uma vez por ambiente)

Antes da primeira conversão em um determinado ambiente, siga references/setup.md passo a passo para garantir que Python, pip, markitdown e pymupdf (para extração de imagens) estejam instalados. Faça isso proativamente em vez de adivinhar se o ambiente está pronto — o script em si também falhará com um ponteiro claro de volta para esse arquivo se uma dependência acabar faltando, então é seguro apenas tentar a conversão primeiro se você tiver confiança razoável de que a configuração já foi feita.

Uso

O script de conversão está localizado em scripts/convert_pdf_to_md.py.

Estrutura de saída: O conversor de PDF do MarkItDown extrai apenas texto e tabelas — ele não tem conceito de imagens incorporadas. Este script extrai separadamente imagens incorporadas reais via PyMuPDF e grava uma pasta autônoma por documento:

<name>/
    img/
        page001_img001.<ext>
        page002_img001.<ext>
        ...
    <name>.md

Como o texto em PDF do MarkItDown não preserva marcadores confiáveis por página, não há maneira segura de saber exatamente onde uma imagem está em linha. Em vez de arriscar colocar imagens ao lado do parágrafo errado, o script anexa uma seção ## Extracted Images no final do Markdown, com um subtítulo ### Page N por página que tem imagens — leia esta seção separadamente do texto principal do corpo. Se o documento não tiver imagens incorporadas, nenhuma pasta img/ ou seção Extracted Images é criada.

Arquivo único:

python scripts\convert_pdf_to_md.py "C:\path\to\document.pdf"

Isso cria uma pasta document\ ao lado do arquivo de origem (contendo document.md e, se presente, document\img\). Para controlar a pasta de destino explicitamente:

python scripts\convert_pdf_to_md.py "C:\path\to\document.pdf" -o "C:\path\to\output_folder"

Uma pasta de PDFs (modo em lote):

python scripts\convert_pdf_to_md.py "C:\path\to\folder"

Adicione --recursive para incluir também subpastas:

python scripts\convert_pdf_to_md.py "C:\path\to\folder" --recursive

Cada .pdf encontrado recebe sua própria pasta de saída <name>\ ao lado dele por padrão. Passe -o "C:\path\to\output_parent" para coletar todas as pastas <name>\ geradas sob um diretório pai separado em vez disso (a estrutura de subpasta é preservada quando combinada com --recursive).

Após a conversão, leia o(s) arquivo(s) .md resultante(s) para realizar a análise real que o usuário solicitou — o trabalho do script é apenas produzir Markdown preciso (e imagens), não interpretar o conteúdo.

Decidindo onde a saída vai

Padrão — sempre saída ao lado do arquivo de origem. A pasta <name>/ é criada no mesmo diretório do .pdf de origem. Este é o padrão obrigatório para todos os casos. NÃO o substitua a menos que o usuário solicite explicitamente um local diferente.

Use -o apenas quando o usuário fornecer explicitamente um caminho de saída (por exemplo, "salve a saída em C:\output", "coloque os resultados em D:\work"). NÃO passe -o com base no diretório de trabalho atual do agente, na pasta de estado da sessão ou em qualquer local implícito.

Se o caminho do arquivo de origem não puder ser totalmente resolvido — por exemplo, o usuário fornece apenas um nome de arquivo sem diretório, ou o caminho é ambíguo — use ask_user para confirmar o caminho absoluto completo antes de executar o …