Lendo Arquivos - Processar Uploads do Usuario

Script Principal

ler.py

source .venv/bin/activate && \
python .claude/skills/lendo-arquivos/scripts/ler.py [opcoes]

Tipos de Arquivo

FORMATOS SUPORTADOS
│
├── Excel (.xlsx)
│   Engine: openpyxl
│   Usar: Planilhas modernas (2007+)
│
├── Excel (.xls)
│   Engine: xlrd
│   Usar: Planilhas legado (97-2003)
│
└── CSV (.csv)
    Separadores: ; , \t |
    Deteccao automatica (sem precisar informar)
    Usar: Arquivos texto estruturados

Parametros

Parametros Principais

Quando usar --cabecalho

O default (--cabecalho 0) assume que a primeira linha e o cabecalho. Use --cabecalho 1 quando a planilha tem titulo ou linhas de metadados acima dos dados. Se nao souber, tente primeiro sem o parametro. Se as colunas vierem estranhas (ex: "Unnamed: 0"), tente --cabecalho 1.

Quando usar --url com caminho absoluto

O --url aceita TANTO URLs do agente (/agente/api/files/...) QUANTO caminhos absolutos (/home/.../arquivo.xlsx, /tmp/arquivo.csv). Para arquivos locais do projeto, use o caminho absoluto completo.

Exemplos de Uso

Ler arquivo Excel

source .venv/bin/activate && \
python .claude/skills/lendo-arquivos/scripts/ler.py \
  --url "/agente/api/files/default/abc123_planilha.xlsx"

Ler com caminho absoluto

source .venv/bin/activate && \
python .claude/skills/lendo-arquivos/scripts/ler.py \
  --url "/tmp/dados_cliente.xlsx"

Ler com limite de linhas

python .../ler.py --url "/agente/api/files/default/dados.xlsx" --limite 50

Ler aba especifica

python .../ler.py --url "/agente/api/files/default/multi.xlsx" --aba "Vendas"

Ler CSV

python .../ler.py --url "/agente/api/files/default/dados.csv"

Retorno JSON

{
  "sucesso": true,
  "arquivo": {
    "nome": "planilha.xlsx",
    "tipo": "excel",
    "tamanho": 15234,
    "tamanho_formatado": "14.9 KB",
    "abas": ["Dados", "Resumo"],
    "aba_lida": "Dados"
  },
  "dados": {
    "colunas": ["Pedido", "Cliente", "Valor"],
    "total_linhas": 150,
    "linhas_retornadas": 100,
    "registros": [
      {"Pedido": "VCD123", "Cliente": "ATACADAO", "Valor": 50000},
      {"Pedido": "VCD456", "Cliente": "ASSAI", "Valor": 75000}
    ]
  },
  "resumo": "Arquivo EXCEL com 150 linhas e 3 colunas (limitado). Colunas: Pedido, Cliente, Valor"
}

Campos importantes no retorno

Cenarios Compostos

"Leia o arquivo e some a coluna X"

1. Execute o script normalmente
2. Percorra dados.registros e some os valores da coluna
3. Use apenas os valores retornados — nao invente valores extras
4. Se total_linhas > linhas_retornadas, avise que a soma e parcial

"Compare este arquivo com dados do sistema"

1. Primeiro leia o arquivo com esta skill
2. Depois consulte o sistema com a skill apropriada (consultando-sql, etc.)
3. Cruze os dados manualmente na resposta

"O arquivo tem dados de quais clientes?"

1. Execute o script
2. Liste valores UNICOS da coluna de clientes encontrados nos registros
3. NAO consulte o banco — a pergunta e sobre o ARQUIVO

Tratamento de Erros

Conversoes Automaticas

Notas

• Limite padrao: 1000 linhas (para evitar respostas muito grandes)
• Para arquivos grandes, use --limite para obter amostra
• Separador CSV eh detectado automaticamente (;, ,, \t, |)
• Encoding: UTF-8 com BOM suportado
• Booleanos em Excel: True/False sao convertidos para 1.0/0.0 pelo pandas

Fluxo de Uso

Quando o usuario anexar um arquivo e pedir "analise essa planilha":

1. Identificar caminho do arquivo (URL do anexo ou caminho local)
2. Executar script (OBRIGATORIO — nao usar Read tool para ler planilhas):

   source .venv/bin/activate && python .claude/skills/lendo-arquivos/scripts/ler.py --url "CAMINHO_DO_ARQUIVO"
   

3. Verificar sucesso no JSON retornado
4. Analisar dados usando APENAS os registros retornados
5. Responder ao usuario com insights dos dados reais

Relacionado

NOTA: Esta skill eh para LEITURA de arquivos do usuario. Para criar arquivos para download, use exportando-arquivos.