Converter Excel para Markdown

Quando usar esta habilidade

Acione esta habilidade sempre que houver um arquivo .xlsx que precise ser entendido ou processado — por exemplo, um usuário anexa uma planilha e faz perguntas sobre ela, quer um resumo dos dados, quer linhas ou valores específicos extraídos, ou quer que vários arquivos de trabalho em uma pasta sejam processados juntos. O formato nativo .xlsx do Excel é um pacote XML compactado que não é confiavelmente legível como texto puro, portanto, 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 .xlsx. Se for solicitado a converter um arquivo legado .xls, diga ao usuário que ele não é suportado e peça para salvá-lo como .xlsx (Excel: Arquivo > Salvar Como > Pasta de Trabalho do Excel (.xlsx)) primeiro.

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 .xlsx. O agente DEVE também acionar as habilidades irmãs em paralelo:

• convert-pdf-to-md para quaisquer arquivos .pdf
• convert-word-to-md para quaisquer arquivos .docx

Nunca processe uma pasta e ignore silenciosamente um tipo de arquivo suportado. Todas as três habilidades devem ser acionadas 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 e o pacote markitdown estejam instalados. Faça isso proativamente em vez de adivinhar se o ambiente está pronto — o próprio script também falhará com um ponteiro claro de volta para esse arquivo se markitdown estiver faltando, então é seguro apenas tentar a conversão primeiro se você estiver razoavelmente confiante de que a configuração já foi feita.

Uso

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

Estrutura de saída: O conversor XLSX do MarkItDown renderiza cada planilha como sua própria tabela Markdown ## <SheetName> — ele não tem suporte para imagens incorporadas de forma alguma. Este script extrai separadamente imagens reais incorporadas (fotos raster, não gráficos) e as mapeia para a planilha a que pertencem, gravando uma pasta autônoma por documento:

<name>/
    img/
        sheet001_<sheetname>_img001.<ext>
        sheet002_<sheetname>_img001.<ext>
        ...
    <name>.md          (each sheet's images appear right after its table,
                         under a "#### Images in this sheet" heading)

Isso é posicionamento por planilha, não posição exata da célula — a granularidade mais fina que os âncoras de saída estáveis do MarkItDown (os cabeçalhos ## <SheetName>) permitem. Se uma pasta de trabalho não tiver imagens incorporadas, nenhuma pasta img/ ou seções de imagem são criadas. Gráficos nativos do Excel não são extraídos como imagens (apenas imagens incorporadas reais são — gráficos precisariam ser renderizados pelo Excel/LibreOffice, o que esta habilidade leve não faz).

Arquivo único:

python scripts\convert_excel_to_md.py "C:\path\to\workbook.xlsx"

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

python scripts\convert_excel_to_md.py "C:\path\to\workbook.xlsx" -o "C:\path\to\output_folder"

Uma pasta de pastas de trabalho (modo em lote):

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

Adicione --recursive para incluir também subpastas:

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

Cada .xlsx 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 subpastas é 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 (e imagens) precisos, não interpretar o conteúdo.

Decidindo onde a saída vai

Padrão — sempre saia ao lado do arquivo de origem. A pasta <name>/ é criada no mesmo diretório que a .xlsx 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, no estado da sessão

…