Pular para o conteúdo principal
O ChatCLI implementa um sistema de deteccao de staleness de arquivos que rastreia o estado dos arquivos entre operacoes de leitura e escrita. Quando um arquivo e modificado externamente (pelo usuario, IDE, ou outro processo) apos 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 apos leitura e verifica antes de escrita:
1

Leitura (RecordRead)

Apos cada operacao read bem-sucedida, o tracker registra:
  • mtime: timestamp de modificacao do arquivo
  • SHA-256: hash criptografico do conteudo completo
  • Size: tamanho em bytes
  • ReadAt: timestamp de quando a leitura ocorreu
2

Verificacao (CheckStaleness)

Antes de cada operacao 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 nao mudou, a escrita prossegue normalmente.

​
Verificacao em 2 Etapas

A verificacao 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 nao esta stale (retorno imediato, sem I/O adicional).
mtime inalterado + size inalterado → nao stale (fast path)
Essa otimizacao evita leitura e hash do arquivo na maioria dos casos, mantendo o overhead proximo 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 nao modificadoNao stalemtime e size identicos
touch sem edicaoNao stalemtime muda mas SHA-256 identico
Edicao real por usuario/IDEStalemtime e hash diferentes
Arquivo deletadoStaleArquivo nao existe mais
Arquivo nunca lidoNao staleSem registro para comparar
Erro ao verificarNao staleAssume nao-stale para nao bloquear

​
Normalizacao de Aspas

O ChatCLI tambem normaliza aspas Unicode em arquivos de codigo 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 codigo (.go, .py, .js, .ts, .java, .rs, .sh, .sql, .json, .yaml, etc.) e em nomes de arquivo especiais (Makefile, Dockerfile, .gitignore, etc.).
Arquivos de documentacao (.md, .txt, .rst) nao 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. (usuario 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): nao stale
                            → Escrita normal
6. (apos write bem-sucedido) → Clear(main.go): remove registro

​
Proximos Passos

Plugin @coder

Referencia completa das operacoes de read/write/patch.

Permissoes

Sistema de permissoes que protege operacoes de escrita.

Recuperacao de JSON

Como argumentos de ferramenta sao corrigidos antes da execucao.

Seguranca do Coder

Validacao de caminhos e protecoes de seguranca.