> ## Documentation Index
> Fetch the complete documentation index at: https://chatcli.edilsonfreitas.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Recuperação de JSON

> Sistema de recuperação automatica para JSON malformado gerado por LLMs em chamadas de ferramenta

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 |

<Warning>
  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.
</Warning>

***

## As 7 Estrategias de Recuperação

O sistema `NormalizeToolArgs` aplica até 7 estrategias em sequencia, parando na primeira que produz JSON valido:

<AccordionGroup>
  <Accordion title="1. Parse JSON Padrão" icon="check">
    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
    ```
  </Accordion>

  <Accordion title="2. Aspas Simples para Duplas" icon="quote-right">
    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"}
    ```

    <Tip>
      O conversor usa um parser stateful que rastreia contexto (dentro/fora de string) para evitar substituicoes incorretas.
    </Tip>
  </Accordion>

  <Accordion title="3. Chaves sem Aspas" icon="key">
    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"}
    ```
  </Accordion>

  <Accordion title="4. Combinado: Aspas + Chaves" icon="layer-group">
    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"}
    ```
  </Accordion>

  <Accordion title="5. Virgulas Finais" icon="comma">
    Remove virgulas antes de `}` ou `]` que tornam o JSON invalido.

    ```
    Entrada: {"cmd":"read","file":"main.go",}
    Saida:   {"cmd":"read","file":"main.go"}
    ```
  </Accordion>

  <Accordion title="6. Plain String Wrapping" icon="box">
    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`).
  </Accordion>

  <Accordion title="7. Fix Agressivo de Literais de Objeto" icon="hammer">
    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
  </Accordion>
</AccordionGroup>

***

## Mapeamento Tool → Campo

O plain string wrapping usa um mapeamento extenso de nomes de ferramenta para o campo primário de entrada:

<Tabs>
  <Tab title="Ferramentas Nativas">
    | 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"}` |
  </Tab>

  <Tab title="Subcomandos Coder">
    | 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"}` |
  </Tab>

  <Tab title="Aliases Genericos">
    | Alias | Campo |
    | :- | :- |
    | `bash` / `shell` | `command` |
    | `Bash` | `command` |
    | `Read` / `Write` | `file_path` |
    | `Glob` / `Grep` | `pattern` |
    | `Edit` | `file_path` |
  </Tab>
</Tabs>

<Note>
  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.
</Note>

***

## 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 |

<Info>
  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.
</Info>

***

## Próximos Passos

<CardGroup cols={2}>
  <Card title="Plugin @coder" icon="hammer" href="/pt/coder/coder-plugin">
    Referência completa das ferramentas que usam JSON recovery.
  </Card>

  <Card title="Tool Use Nativo" icon="wrench" href="/pt/agents/native-tool-use">
    Com tool use nativo, o JSON vem validado pela API — menos necessidade de recovery.
  </Card>

  <Card title="Gerenciamento de Resultados" icon="database" href="/pt/context/tool-result-management">
    Como resultados de ferramentas sao gerenciados após execução.
  </Card>

  <Card title="Modo Coder" icon="code" href="/pt/usage/coder-mode">
    O fluxo completo de engenharia com tool calls.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.