Pular para o conteúdo principal
O ChatCLI implementa um sistema de detecção de staleness de arquivos que rastreia o estado dos arquivos entre operações de leitura e escrita. Quando um arquivo e modificado externamente (pelo usuário, IDE, ou outro processo) após o agente te-lo lido, o sistema emite um aviso antes de sobrescrever — prevenindo a perda silenciosa de alteracoes externas.

​
Como Funciona

O tracker registra o estado de cada arquivo após leitura e verifica antes de escrita:
1

Leitura (RecordRead)

Após cada operação read bem-sucedida, o tracker registra:
  • mtime: timestamp de modificacao do arquivo
  • SHA-256: hash criptografico do conteúdo completo
  • Size: tamanho em bytes
  • ReadAt: timestamp de quando a leitura ocorreu
2

Verificação (CheckStaleness)

Antes de cada operação write ou patch, o tracker verifica se o arquivo mudou.
3

Aviso ou Prosseguimento

Se o arquivo mudou, um aviso e injetado no resultado da ferramenta para que o modelo decida como proceder. Se não mudou, a escrita prossegue normalmente.

​
Verificação em 2 Etapas

A verificação usa uma estrategia otimizada de fast path seguida de full hash:
Primeiro, o tracker compara o mtime e size atuais com os registrados. Se ambos sao identicos, o arquivo não esta stale (retorno imediato, sem I/O adicional).
mtime inalterado + size inalterado → não stale (fast path)
Essa otimização evita leitura e hash do arquivo na maioria dos casos, mantendo o overhead próximo de zero.

​
Mensagem de Aviso

Quando um arquivo stale e detectado, o sistema gera um aviso formatado: 
WARNING: File "/path/to/file.go" has been modified externally since you last read it.
Reason: file modified externally (mtime: 2026-04-10T10:30:00Z → 2026-04-10T10:35:22Z,
  size: 2048 → 2156)
You should re-read the file before making changes to avoid overwriting external edits.
If you proceed anyway, external changes will be lost.
O aviso instrui o modelo a:
  1. Re-ler o arquivo antes de fazer alteracoes
  2. Entender que continuar sobrescrevera as alteracoes externas

​
Cenarios Cobertos

CenarioResultadoDescricao
Arquivo não modificadoNão stalemtime e size identicos
touch sem edicaoNão stalemtime muda mas SHA-256 identico
Edicao real por usuário/IDEStalemtime e hash diferentes
Arquivo deletadoStaleArquivo não existe mais
Arquivo nunca lidoNão staleSem registro para comparar
Erro ao verificarNão staleAssume não-stale para não bloquear

​
Normalizacao de Aspas

O ChatCLI também normaliza aspas Unicode em arquivos de código para prevenir erros de compilacao causados por aspas tipograficas geradas por LLMs:
CaracterDescricaoSubstituicao
' 'Aspas simples curvas'
" "Aspas duplas curvas"
'Primo'
"Duplo primo"
<< >>Aspas angulares<< >>
A normalizacao e aplicada automaticamente em 60+ tipos de arquivo de código (.go, .py, .js, .ts, .java, .rs, .sh, .sql, .json, .yaml, etc.) e em nomes de arquivo especiais (Makefile, Dockerfile, .gitignore, etc.).
Arquivos de documentação (.md, .txt, .rst) não sao normalizados para preservar a tipografia intencional.

​
Ciclo de Vida do Tracking

1. @coder read main.go     → RecordRead(main.go): registra mtime + SHA-256
2. (usuário edita main.go no IDE)
3. @coder write main.go    → CheckStaleness(main.go): detecta mudanca
                            → WARNING injetado no resultado
                            → Modelo decide: re-ler ou prosseguir
4. @coder read main.go     → RecordRead(main.go): atualiza registro
5. @coder write main.go    → CheckStaleness(main.go): não stale
                            → Escrita normal
6. (após write bem-sucedido) → Clear(main.go): remove registro

​
Próximos Passos

Plugin @coder

Referência completa das operações de read/write/patch.

Permissoes

Sistema de permissões que protege operações de escrita.

Recuperação de JSON

Como argumentos de ferramenta sao corrigidos antes da execução.

Segurança do Coder

Validação de caminhos e protecoes de segurança.