Converter Word para Markdown

Quando usar esta habilidade

Acione esta habilidade sempre que houver um arquivo .docx que precise ser entendido ou processado — por exemplo, um usuário anexa um documento do Word e faz perguntas sobre ele, quer um resumo, quer dados específicos extraídos, ou quer que vários documentos do Word em uma pasta sejam processados juntos. O formato nativo do Word, .docx, é um pacote XML compactado que não é confiavelmente legível como texto puro, portanto, sempre o converta para Markdown primeiro usando o script desta habilidade, em vez de tentar abrir ou analisar o arquivo diretamente.

Esta habilidade suporta apenas .docx. Se for solicitado a converter um arquivo legado .doc, diga ao usuário que ele não é suportado e peça para salvá-lo novamente como .docx (Word: Arquivo > Salvar Como > Documento do Word (.docx)) 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 .docx. O agente DEVE também acionar as habilidades irmãs em paralelo:

• convert-pdf-to-md para quaisquer arquivos .pdf
• convert-excel-to-md para quaisquer arquivos .xlsx

Nunca processe uma pasta e silenciosamente pule 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 uma indicação clara de volta para esse arquivo se markitdown estiver 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_word_to_md.py.

Estrutura de saída: MarkItDown incorpora imagens como um espaço reservado de URI data:image/png;base64... truncado (não dados reais de imagem), portanto, o script extrai imagens reais diretamente do .docx e grava uma pasta autocontida por documento em vez de um único arquivo .md solto:

<name>/
    img/
        img001.<ext>
        img002.<ext>
        ...
    <name>.md          (image references are relative: img/imgNNN.ext)

Se o documento não tiver imagens incorporadas, nenhuma pasta img/ é criada.

Arquivo único:

# Windows
python scripts\convert_word_to_md.py "C:\path\to\document.docx"

# macOS / Linux
python scripts/convert_word_to_md.py "/path/to/document.docx"

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_word_to_md.py "C:\path\to\document.docx" -o "C:\path\to\output_folder"

Uma pasta de documentos do Word (modo em lote):

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

Adicione --recursive para incluir também subpastas:

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

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

Decidindo onde a saída vai

Padrão — sempre produza a saída ao lado do arquivo de origem. A pasta <name>/ é criada no mesmo diretório do .docx 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 a conversão. Nunca adivinhe ou assuma o diretório.

Solução de problemas

…