xls-skill: Excel -> Markdown, imagens mantidas em suas células
Por que esta skill existe
A maioria dos leitores de Excel (openpyxl, pandas, exportação CSV) vê apenas os valores das células. Dois tipos de imagens são perdidos:
- Imagens em célula. A imagem é o conteúdo de uma célula.
- WPS Office "incorporar na célula": a célula mostra apenas
=DISPIMG("ID_...",1); a imagem está emxl/cellimages.xml. - Microsoft 365 "Place in Cell" /
IMAGE: a célula mostra#VALUE!; a imagem é alcançada por meio dexl/metadata.xmlexl/richData/.
- WPS Office "incorporar na célula": a célula mostra apenas
- Imagens flutuantes e caixas de texto desenhadas sobre a grade (processar fotos, etiquetas, números de formulários).
Esta skill extrai todas elas, salva cada imagem como um arquivo e as insere de volta na tabela Markdown na célula onde vive, para que um leitor veja a tabela e suas imagens juntas:
| # | A | B | C | D |
|---|---|---|---|---|
| 2 | Suporte |  | Suporte \| imagem em célula | 4 |
Como executar
python <skill-dir>/scripts/xlsx_to_md.py <arquivo-ou-pasta> [...] -o <dir-saida> [--ocr auto|off] [--ocr-lang eng+chi_sim]
- Aceita
.xlsx,.xlsm,.xlsou pastas (recursivo). Imprime uma linha por pasta de trabalho com contagens de imagens. - Requer Python 3.9+ e
openpyxl. Opcional:Pillow(tamanhos de imagem), Tesseract OCR (texto dentro de imagens), Microsoft Excel ou LibreOffice (para abrir.xls). - Autoteste:
python <skill-dir>/tests/run_tests.pyconstrói pastas de trabalho sintéticas do WPS e Microsoft 365 e verifica se cada imagem está em sua célula.
O que você obtém por pasta de trabalho (<dir-saida>/<nome>/)
| Arquivo | Conteúdo |
|---|---|
<nome>.md | Índice da pasta de trabalho, depois cada planilha como uma tabela Markdown completa (sem truncamento) com imagens inline em suas células; fatos da planilha (estado oculto, intervalos mesclados, linhas/colunas ocultas, comentários, caixas de texto, contagem de gráficos) acima de cada tabela |
<nome>.images.md | Uma entrada por imagem: a imagem, planilha!célula, tipo, tamanho, texto de célula vizinha, texto OCR e um espaço para descrição |
images/ | Cada imagem como um arquivo, nomeado `<plan#><célula>_<célula |
sheets_csv/ | Valores da planilha; células de imagem contêm [image: images/...] |
image_manifest.csv | planilha, célula, tipo (in-cell (WPS DISPIMG) / in-cell (Microsoft 365) / flutuante), arquivo, parte do pacote, texto alternativo, tamanho, OCR, texto vizinho |
formula_manifest.csv | Texto da fórmula e valor em cache por célula |
shapes_manifest.csv | Texto de caixas de texto/formas flutuantes, com célula de âncora |
conversion_report.json | Contagens, avisos, review_required |
Fluxo de trabalho para o agente
- Converter. Execute o script na(s) pasta(s) de trabalho.
- Leia o relatório primeiro. Abra
conversion_report.json. Aja sobre cada aviso:image not found in package-> a célula está marcada como[image missing: ID]; informe isso, não adivinhe a imagem..emf/.wmf saved as-is-> converta para PNG (ex.: Pillow no Windows, LibreOffice em outros lugares) antes de examiná-la.charts> 0 -> gráficos são contados, não renderizados; abra ou exporte a planilha se o gráfico for importante.- OCR ignorado ou idioma ausente -> confie em examinar as imagens você mesmo.
- Observe as imagens. Abra cada arquivo listado em
<nome>.images.mde substitua cada espaço reservadodescriptionpelo que a imagem mostra: objeto, texto legível (etiquetas, números de modelo, marcas), símbolos e como se relaciona com as células vizinhas. OCR é uma dica, não a resposta; texto de etiqueta pequena geralmente precisa de um recorte ou zoom. - Responda a partir da tabela e das imagens juntas. Use a tabela Markdown para valores exatos de células, fórmulas e estrutura; use as imagens para "como é / o que está escrito na peça". Cite
planilha!célulapara ambos. - Relate lacunas honestamente. Se algo na etapa 2 permaneceu não resolvido, marque a pasta de trabalho como necessitando de revisão manual.
Regras
- Uma tabela CSV ou apenas de valores não é evidência completa quando a pasta de trabalho tem imagens, caixas de texto, cores ou conteúdo oculto. Verifique os fatos da planilha e manifestos.
- Emparelhe cada imagem com sua célula e vizinhas; nunca confie apenas na ordem das imagens.
- Texto importante pode viver fora das células: caixas de texto (números de formulário, marcas de revisão), comentários, cabeçalhos/rodapés. Caixas de texto e comentários são extraídos; cabeçalhos/rodapés não - verifique-os no Excel se um número de documento estiver faltando.
- Cor pode ser dado (aprovado/reprovado, nível de risco, status). Este script não decodifica preenchimentos ou formatação condicional; se as cores carregam significado, inspecione-as com openpyxl ou uma exportação de página e declare o mapeamento.
- Intervalos mesclados mantêm seu valor apenas na célula superior esquerda; leia a linha
merged:antes de interpretar células em branco. - Planilhas, linhas e colunas ocultas são convertidas e listadas, não descartadas. Diga quando uma resposta vem de conteúdo oculto.
- Não confie em caminhos mojibake em um terminal; verifique se o caminho real existe antes de relatar um arquivo como ausente.
Limitações
- Imagens flutuantes são vinculadas em sua célula âncora superior esquerda; uma imagem abrangendo muitas células é listada com seu
to_cellno manifesto. - Formas agrupadas são lidas, mas setas e balões desenhados como formas separadas mantêm sua relação com uma foto apenas em uma renderização de página. Quando o layout importa ("qual seta aponta para onde"), exporte a planilha para PDF/PNG com Excel ou LibreOffice e observe-a junto com o Markdown.
- Imagens em cabeçalhos/rodapés (VML) e em comentários não são extraídas.
.xlsprecisa do Microsoft Excel (Windows, pywin32) ou LibreOffice para converter primeiro; sem eles, apenas os valores das células são lidos e o relatório informa isso.
