Pular para o conteúdo principal
O ChatCLI implementa um sistema de recuperação de JSON que corrige automaticamente argumentos malformados gerados por LLMs durante chamadas de ferramenta. Isso aumenta drasticamente a taxa de sucesso de tool calls, especialmente com modelos menores ou via XML parsing.

​
Por que JSON Malformado?

LLMs frequentemente geram JSON invalido em seus argumentos de tool call. Isso acontece porque modelos de linguagem trabalham com tokens, não com validação de sintaxe:
ProblemaExemploFrequencia
Aspas simples em vez de duplas{'cmd': 'read'}Muito comum
Chaves sem aspas{cmd: "read", file: "main.go"}Comum
Virgulas finais{"cmd":"read","file":"main.go",}Comum
Valor puro sem objetomain.go em vez de {"file":"main.go"}Frequente
Mix de estilos{cmd: 'read', "file": main.go}Ocasional
Texto CLI em vez de JSONread --file main.goFrequente
Literais de objeto JS{cmd: read, file: main.go}Ocasional
Sem recuperação de JSON, esses erros causam falhas de parsing que interrompem o loop do agente. Em modelos menores, até 30% das tool calls podem ter JSON invalido.

​
As 7 Estrategias de Recuperação

O sistema NormalizeToolArgs aplica até 7 estrategias em sequencia, parando na primeira que produz JSON valido:
Tenta parsing direto com json.Unmarshal. Se o JSON já e valido, retorna imediatamente sem modificacoes.
{"cmd":"read","args":{"file":"main.go"}}  =>  valido, retorna direto
Converte aspas simples para duplas com tratamento correto de escaping. Preserva aspas simples dentro de strings e escapa aspas duplas internas.
Entrada: {'cmd':'read','file':'main.go'}
Saida:   {"cmd":"read","file":"main.go"}
O conversor usa um parser stateful que rastreia contexto (dentro/fora de string) para evitar substituicoes incorretas.
Adiciona aspas duplas a chaves que não estao entre aspas. Usa regex para detectar o padrão {key: ou , key:.
Entrada: {cmd: "read", file: "main.go"}
Saida:   {"cmd": "read", "file": "main.go"}
Aplica a correcao de aspas simples primeiro e depois a correcao de chaves sem aspas. Resolve casos onde ambos os problemas coexistem.
Entrada: {cmd: 'read', file: 'main.go'}
Saida:   {"cmd": "read", "file": "main.go"}
Remove virgulas antes de } ou ] que tornam o JSON invalido.
Entrada: {"cmd":"read","file":"main.go",}
Saida:   {"cmd":"read","file":"main.go"}
Quando o modelo envia apenas um valor puro em vez de um objeto JSON, o sistema o envolve no campo correto baseado no nome da ferramenta.
Tool: read_file    Entrada: main.go     => {"file":"main.go"}
Tool: run_command  Entrada: ls -la      => {"cmd":"ls -la"}
Tool: search_files Entrada: TODO        => {"term":"TODO"}
O mapeamento cobre 30+ ferramentas e aliases, incluindo funções nativas (read_file, write_file) e subcomandos do coder (read, exec, search).
Para literais de objeto sem nenhum tipo de aspas, o sistema faz parse manual de pares chave: valor e reconstroi JSON valido.
Entrada: {cmd: read, file: main.go, append: true}
Saida:   {"cmd":"read","file":"main.go","append":true}
Valores sao interpretados inteligentemente:
  • true/false → booleans
  • Numeros → numeros JSON
  • null/none → null
  • Strings entre aspas → strings (aspas removidas)
  • Tudo mais → string

​
Mapeamento Tool → Campo

O plain string wrapping usa um mapeamento extenso de nomes de ferramenta para o campo primário de entrada:
FerramentaCampoExemplo
read_filefilemain.go → {"file":"main.go"}
write_filefileoutput.txt → {"file":"output.txt"}
list_directorydir./src → {"dir":"./src"}
search_filestermTODO → {"term":"TODO"}
run_commandcmdgo build → {"cmd":"go build"}
run_testsdir./pkg → {"dir":"./pkg"}
O wrapping so e aplicado quando o valor não se parece com argumentos CLI (sem --flags) e não comeca com { ou [. Isso evita conflitos com o parser de argumentos CLI existente.

​
Normalizacao de Aspas Unicode

Alem do JSON recovery, o ChatCLI normaliza aspas curvas (Unicode) para aspas retas (ASCII) automaticamente. LLMs frequentemente geram aspas tipograficas que causam erros de compilacao:
CaracterUnicodeSubstituicao
' 'U+2018, U+2019' (aspas simples reta)
" "U+201C, U+201D" (aspas dupla reta)
'U+2032 (primo)'
"U+2033 (duplo primo)"
<< >>U+00AB, U+00BB<< >>
A normalizacao e aplicada automaticamente em arquivos de código (60+ extensoes reconhecidas) e sempre em argumentos de tool call.

​
Configuração

O sistema de recuperação funciona automaticamente sem configuração. Todas as estrategias sao aplicadas em ordem até que uma produza JSON valido.
VariávelDescricaoDefault
(nenhuma)O JSON recovery não possui variáveis de ambiente dedicadasAtivo sempre
As estrategias de recuperação sao não-destrutivas: se nenhuma produzir JSON valido, o texto original e passado adiante para que o parser CLI tente interpretar como argumentos posicionais.

​
Próximos Passos

Plugin @coder

Referência completa das ferramentas que usam JSON recovery.

Tool Use Nativo

Com tool use nativo, o JSON vem validado pela API — menos necessidade de recovery.

Gerenciamento de Resultados

Como resultados de ferramentas sao gerenciados após execução.

Modo Coder

O fluxo completo de engenharia com tool calls.