Recuperação de JSON

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:

Problema	Exemplo	Frequencia
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 objeto	`main.go` em vez de `{"file":"main.go"}`	Frequente
Mix de estilos	`{cmd: 'read', "file": main.go}`	Ocasional
Texto CLI em vez de JSON	`read --file main.go`	Frequente
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:

1. Parse JSON Padrão

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

2. Aspas Simples para Duplas

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.

3. Chaves sem Aspas

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"}

4. Combinado: Aspas + Chaves

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"}

5. Virgulas Finais

Remove virgulas antes de } ou ] que tornam o JSON invalido.

Entrada: {"cmd":"read","file":"main.go",}
Saida:   {"cmd":"read","file":"main.go"}

6. Plain String Wrapping

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).

7. Fix Agressivo de Literais de Objeto

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:

Ferramentas Nativas
Subcomandos Coder
Aliases Genericos

Ferramenta	Campo	Exemplo
`read_file`	`file`	`main.go` → `{"file":"main.go"}`
`write_file`	`file`	`output.txt` → `{"file":"output.txt"}`
`list_directory`	`dir`	`./src` → `{"dir":"./src"}`
`search_files`	`term`	`TODO` → `{"term":"TODO"}`
`run_command`	`cmd`	`go build` → `{"cmd":"go build"}`
`run_tests`	`dir`	`./pkg` → `{"dir":"./pkg"}`

Subcomando	Campo	Exemplo
`read`	`file`	`config.yaml` → `{"file":"config.yaml"}`
`write`	`file`	`data.json` → `{"file":"data.json"}`
`exec`	`cmd`	`make test` → `{"cmd":"make test"}`
`search`	`term`	`func main` → `{"term":"func main"}`
`tree`	`dir`	`./internal` → `{"dir":"./internal"}`

Alias	Campo
`bash` / `shell`	`command`
`Bash`	`command`
`Read` / `Write`	`file_path`
`Glob` / `Grep`	`pattern`
`Edit`	`file_path`

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:

Caracter	Unicode	Substituicao
`'` `'`	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ável	Descricao	Default
(nenhuma)	O JSON recovery não possui variáveis de ambiente dedicadas	Ativo 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.

Início

Primeiros Passos

Conceitos Fundamentais

Funcionalidades

Segurança

Suporte

Recuperação de JSON

Por que JSON Malformado?

As 7 Estrategias de Recuperação

Mapeamento Tool → Campo

Normalizacao de Aspas Unicode

Configuração

Próximos Passos

Plugin @coder

Tool Use Nativo

Gerenciamento de Resultados

Modo Coder

​Por que JSON Malformado?

​As 7 Estrategias de Recuperação

​Mapeamento Tool → Campo

​Normalizacao de Aspas Unicode

​Configuração

​Próximos Passos

Plugin @coder

Tool Use Nativo

Gerenciamento de Resultados

Modo Coder

Por que JSON Malformado?

As 7 Estrategias de Recuperação

Mapeamento Tool → Campo

Normalizacao de Aspas Unicode

Configuração

Próximos Passos