O screenshot está ali, mas o Hermes diz que o arquivo não existe: há um espaço invisível no nome


Você joga um screenshot novo no chat e pede ao Hermes para olhar o erro na tela. O arquivo salva bem, o path imprime bem, e então a etapa que abre a imagem falha: media file not found. Você confere no Finder. O arquivo está ali, com exatamente aquele nome.

A pegadinha está em “exatamente aquele nome”. Quando o macOS nomeia um screenshot, o espaço antes de AM/PM não é um espaço normal. É U+202F, um espaço estreito não separável. Na tela ele parece idêntico a um espaço comum — um fio mais estreito, invisível num relance. Quando um modelo redigita o nome, ele emite U+0020, e dois bytes diferentes significam que o path aponta para um arquivo que não existe.

O PR #154046, mergeado em 12 de novembro, faz a análise de vision, a análise de vídeo e a geração de imagem/vídeo encontrarem sozinhas a grafia em disco.

Um caractere, uma cadeia inteira quebrada

A falha corre assim:

  1. O path chega ao contexto: Screenshot 2026-11-12 at 9.51.42 AM.png — o caractere 26 é U+202F.
  2. O modelo recebe uma string que parece normal, mas quando gera texto os espaços que produz são todos U+0020.
  3. O visualizador de imagem chama open() nesse path, o SO compara bytes e não encontra nada.
  4. O erro diz media file not found. Não diz “um argumento difere em um byte”.

A pior parte é como isso soa: parece um problema de permissão ou de path, então você vai auditar paths, permissões e sandboxes enquanto a causa real é um caractere que você não consegue ver.

Um detalhe pequeno que fazia parecer inconsistente: o read_file já tratava esse caso. Então o mesmo arquivo era legível pelo read_file e ilegível pelo vision_analyze.

A correção: casar pelo que o olho vê, mas só quando um arquivo serve

Funciona em duas camadas.

Uma chave de match. tools/file_operations_common.py ganhou filename_match_key, que normaliza um nome para “o que um humano lê como o mesmo”: composições Unicode NFC e NFD, espaços estreitos e especiais, apóstrofos curvos.

Uma busca em disco. _on_disk_spelling em tools/image_source.py roda depois de um erro de path e procura no mesmo diretório o único arquivo cujo nome difere apenas de forma invisível:

target (normalised):  screenshot 2026-11-12 at 9.51.42 am.png
actually on disk:     Screenshot 2026-11-12 at 9.51.42<U+202F>AM.png   <- match

Dois detalhes valem guardar:

  • Um único candidato. Se um diretório tem tanto a AM.png quanto a<U+202F>AM.png, ele não adivinha — ler a imagem errada é pior do que falhar.
  • A segurança continua valendo. O path resolvido passa pelo mesmo confinamento de diretório de mídia e pela mesma guarda de leitura de credenciais, então a correção não burla nenhuma fronteira. Ela também só roda em backend local (TERMINAL_ENV=local); sob um sandbox, um erro de path ainda precisa chegar à leitura dentro do container, senão a fronteira do sandbox quebraria.

Quais ferramentas se beneficiam agora

Um único resolvedor para “a grafia em disco” é compartilhado por estes pontos de chamada:

Ferramenta Antes Depois
vision_analyze (olhando uma imagem) media file not found encontra o arquivo, analisa normalmente
Análise de vídeo o mesmo erro também encontra (_materialize_video retorna o path com U+202F)
Geração de imagem / vídeo com um arquivo de referência local falhava direto _confine_source_images reescreve image_url e referências para a grafia em disco, deixando URLs e arquivos realmente ausentes em paz
read_file já tratava sem mudança

A linha mais clara no registro de verificação: para o mesmo screenshot, a linha da ferramenta no branch antigo diz "success": false … media file not found, a do branch novo diz "success": true, e o modelo então responde corretamente a cor na imagem. Um novo arquivo de teste, tests/tools/test_image_source_unicode_space.py, falha no branch antigo com SourceNotFound.

O que você pode fazer sozinho

A correção faz o Hermes se virar sozinho, mas você também pode contornar:

  • Renomeie o arquivo. shot-1.png e nenhum caractere invisível pode entrar no nome. Vale a pena em qualquer script de lote.
  • Para ver se há caracteres escondidos: ls -b escapa caracteres invisíveis, ou imprima repr(path) em Python — U+202F aparece na hora.
  • Prefira arrastar e soltar. Deixar a ferramenta pegar o path sozinha (arrastar, upload de anexo) é melhor do que um modelo redigitar um nome de arquivo longo.

Isso nunca foi só sobre um caractere. Nomes NFD (comuns no macOS para nomes acentuados) e apóstrofos curvos causavam a mesma classe de erro, e a mesma chave de match agora cobre todos eles.

Se erros de imagem continuam voltando, duas leituras relacionadas: o orçamento de contexto da vision para o que acontece depois que uma imagem grande é reduzida, e fotos HEIC de um iPhone. Dois outros caminhos que evitam completamente “o modelo redigita um path”: colar imagens no terminal e o comando de imagem da área de transferência.

Status de release

O PR #154046 entrou em main em 12 de novembro de 2026. Ele corrige a issue #76334 e faz cherry-pick do #62126 anterior mantendo a autoria. A v0.23.1 saiu em 10 de novembro e não o inclui. Duas issues relacionadas, #76376 e #124742, cobriam casos sobrepostos (não idênticos) — orientação no prompt, NFD e aspas curvas — e esta chave de match absorve todas.

Atualização (17/11/2026): essas mudanças saíram na v0.23.2 (16 de novembro): um hermes update as traz. O « não está na v0.23.1 » acima é um retrato da data de publicação.