Arquitetura e Estrutura do Código

chatcli/
|-- main.go                    # Entrypoint
|-- cli/                       # Interface do usuário e modos
|   |-- cli.go                 # Struct principal ChatCLI + Start() (~923 linhas)
|   |-- cli_helpers.go         # Métodos auxiliares extraídos de cli.go
|   |-- cli_history.go         # Gerenciamento de histórico
|   |-- cli_llm.go             # processLLMRequest + spinner
|   |-- cli_mode.go            # Lógica de troca de modos
|   |-- cli_output.go          # Formatação de saída
|   |-- cli_prompt.go          # Construção de prompts
|   |-- cli_session.go         # Gerenciamento de sessões
|   |-- cli_tools.go           # Registro e tratamento de tools
|   |-- agent_mode.go          # Modo agente core (~1498 linhas)
|   |-- agent_mode_helpers.go  # Helpers do modo agente
|   |-- agent_mode_tools.go    # Tratamento de tools do agente
|   |-- agent_mode_ui.go       # Renderização UI do agente
|   |-- agent_tool_sanitizer.go # Pipeline de sanitização de args
|   |-- command_handler.go     # Roteamento de comandos / (~185 linhas)
|   |-- command_handler_session.go  # Comandos de sessão
|   |-- command_handler_context.go  # Comandos de contexto
|   |-- command_handler_plugins.go  # Comandos de plugins
|   |-- command_handler_agent.go    # Comandos de agente
|   |-- context_handler.go     # Gerenciamento de contexto (~385 linhas)
|   |-- context_handler_attach.go   # Lógica de attach
|   |-- context_handler_create.go   # Lógica de criação
|   |-- context_handler_resolve.go  # Resolução de contexto
|   |-- rewind.go              # Checkpoints e restauracao de conversa
|   |-- compact_command.go     # Compactação guiada de histórico
|   |-- history_compactor.go   # Pipeline de compactação (3 níveis)
|   |-- history_trimmer.go     # Trimming near-lossless (nivel 1)
|   |-- memory_worker.go       # Worker background de memória
|   |-- agent/                 # Sistema multi-agent
|   |   |-- workers/           # 12 agents especialistas
|   |   |-- toolcall_parser.go # Parser stateful de tool calls
|   |   |-- ui_renderer.go     # Renderizacao da UI
|   |   +-- dispatcher.go      # Dispatcher assincrono
|   |-- bus/                   # Message bus interno
|   |-- workspace/             # Bootstrap files + memória + context builder
|   |   |-- bootstrap.go       # BootstrapLoader com cache mtime
|   |   |-- memory.go          # MemoryStore facade (delega ao memory.Manager)
|   |   |-- context_builder.go # Combina bootstrap + memória no prompt (smart retrieval)
|   |   +-- memory/            # Sistema de memória estruturado
|   |       |-- store.go       # Manager (orquestrador central)
|   |       |-- facts.go       # FactIndex (fatos com scores e decay)
|   |       |-- profile.go     # UserProfile (perfil automático)
|   |       |-- topics.go      # TopicTracker (tópicos recorrentes)
|   |       |-- projects.go    # ProjectTracker (projetos ativos)
|   |       |-- patterns.go    # PatternDetector (padrões de uso)
|   |       |-- retriever.go   # Smart retrieval por keywords + expansão do grafo
|   |       |-- graph_cache.go # Cache persistido do grafo (graph.json)
|   |       |-- compactor.go   # Compactação LLM + score-based
|   |       +-- migration.go   # Migração do MEMORY.md legado
|   |-- skills/                # Sistema de skills
|   |-- mcp/                   # Gerenciador MCP
|   +-- ctxmgr/                # Pacote de gerenciamento de contexto
|-- config/                    # Configuração e migração
|-- i18n/                      # Internacionalização (892 chaves de tradução)
|-- llm/                       # Comunicação com LLMs
|   |-- registry/              # Auto-registro de provedores
|   |-- fallback/              # Cadeia de fallback
|   |-- client/                # Interface LLMClient + ToolAwareClient
|   |-- openai/                # Provedor OpenAI
|   |-- claudeai/              # Provedor Anthropic
|   |-- googleai/              # Provedor Google
|   |-- xai/                   # Provedor xAI
|   |-- zai/                   # Provedor ZAI
|   |-- minimax/               # Provedor MiniMax
|   |-- moonshot/              # Provedor Moonshot (Kimi)
|   |-- ollama/                # Provedor Ollama
|   +-- copilot/               # Provedor GitHub Copilot
|-- models/                    # Structs: ToolDefinition, ToolCall, LLMResponse
|-- server/                    # Servidor gRPC (`chatcli server`)
|   |-- server.go              # Listener, TLS 1.3, cadeia de interceptors, keepalive, limites de mensagem
|   |-- bind_guard.go          # Recusa bind alcançável sem credencial
|   |-- auth.go, auth_jwt_config.go, auth_mtls.go  # Token compartilhado, JWT (HS256/RS256), identidade por certificado de cliente
|   |-- rate_limiter.go        # Token bucket por sujeito autenticado
|   |-- health_service.go      # Serviço padrão grpc.health.v1
|   |-- audit.go               # Log de auditoria JSONL encadeado por hash (CHATCLI_AUDIT_LOG_PATH)
|   |-- handler.go             # Handler principal (Health, GetServerInfo, ...)
|   |-- handler_session.go     # RPCs de prompt e sessão
|   |-- llm_route.go           # Roteamento: fallback chain, max_tokens, refresh de credencial, retry de recusa, usage
|   |-- handler_remote.go      # RPCs de descoberta de recursos
|   |-- handler_analysis.go    # RPCs AIOps (AnalyzeIssue, AgenticStep, ...)
|   |-- alerts_stream.go       # StreamAlerts (alertas do watcher para o operator)
|   |-- handler_hub.go         # RPCs do hub de conversas
|   +-- pipeline.go            # RPCs de pipeline (engine de turno hospedado no servidor)
|-- metrics/                   # Métricas Prometheus e /healthz do servidor (HTTP puro)
|-- client/remote/             # Cliente gRPC (`chatcli connect`)
|-- k8s/                       # Kubernetes Watcher (pacote Go, não manifests)
|-- operator/                  # K8s Operator (AIOps), módulo Go separado
|   |-- main.go                # Manager, leader election, API REST + dashboard
|   |-- api/v1alpha1/          # Tipos dos 17 CRDs
|   |-- api/rest/              # API REST (auth por X-API-Key, papéis, CORS, rate limit)
|   |-- controllers/           # Reconcilers e engines (Instance, Issue, Remediation, ...)
|   |-- internal/setup/        # Registro dos controllers e WatcherBridge
|   |-- channels/              # Canais de notificação
|   +-- web/                   # Dashboard web embutido
|-- deploy/helm/               # Charts Helm: chatcli (servidor) e chatcli-operator
|-- proto/                     # Definições protobuf
|-- utils/                     # Funções auxiliares
+-- version/                   # Informações de versão

main.go
  |
  +-- Checa subcomandos (server/serve, connect, watch, mcp-server, acp, gateway, tool, web, daemon, storage, update, ...)
  +-- cli.PreprocessArgs() + cli.Parse() -> opts
  +-- i18n.Init()
  +-- godotenv.Load(.env)
  +-- utils.InitializeLogger() -> zap.Logger
  +-- config.InitGlobal() + config.Global.Load()
  |
  +-- manager.NewLLMManager(logger)
  |     +-- Provedores se auto-registram via init() no registry
  |     +-- Manager itera providers, checa env vars, cria clientes
  |
  +-- cli.NewChatCLI(manager, logger)
  |     +-- plugins.NewManager() -> registra built-in (CoderPlugin)
  |     +-- configureProviderAndModel() (config.Global + env)
  |     +-- manager.GetClient(provider, model) -> LLMClient
  |     +-- NewSessionManager()
  |     +-- NewContextHandler()
  |     +-- detectProjectDir(): caminha até raiz procurando .agent ou .git
  |     +-- workspace.NewBootstrapLoader(workspaceDir, globalDir)
  |     +-- workspace.NewMemoryStore(memDir)
  |     +-- workspace.NewContextBuilder(bootstrap, memory)
  |     +-- memoryWorker.start() (goroutine background)
  |     +-- NewPersonaHandler() + SetProjectDir()
  |     +-- NewSkillHandler()
  |     +-- NewCommandHandler(cli)
  |     +-- NewAgentMode(cli, logger)
  |     +-- historyManager.LoadHistory() (histórico de comandos)
  |
  +-- chatCLI.ApplyOverrides(provider, model) (flags CLI)
  +-- HandleOneShotOrFatal(ctx, opts) -> retorna se -p flag
  +-- handleGracefulShutdown(cancel, logger)
  +-- chatCLI.Start(ctx)
        +-- PrintWelcomeScreen()
        +-- Loop: prompt.New() com panic/recover para troca de modos

Usuário digita texto
       |
       v
  executor(in string)
       |
       +-- Detecção de paste (BracketedPasteParser)
       +-- Append ao commandHistory
       +-- Checa comandos / (roteamento via CommandHandler)
       +-- Checa /run, /agent, /coder -> panic(agentModeRequest)
       |
       v
  processLLMRequest(in)
       |
       +-- Suprime animação (go-prompt gerencia spinner no prefix)
       +-- Inicia spinner goroutine (250ms tick + SIGWINCH)
       +-- saveCheckpoint() (deep copy do histórico)
       +-- Append mensagem do usuário ao history
       +-- BuildPromptMessages() (system prompt + contextos attached)
       +-- Client.SendPrompt(ctx, prompt, history, maxTokens)
       |
       v
  Resposta do LLM
       |
       +-- Append resposta ao history
       +-- Renderiza via Glamour (markdown)
       +-- memWorker.nudge() (trigger extração de memória)
       +-- Drena messageQueue (type-ahead)

Usuário digita "/agent QUERY" ou "/coder QUERY" ou "/run QUERY"
       |
       v
  executor() -> panic(agentModeRequest)
       |
       v
  Start() recover -> detecta agentModeRequest
       +-- restoreTerminal() (no modo coder)
       |
       v
  agentMode.Run(ctx, query, additionalContext, systemPromptOverride)
       |
       v
  === CONFIGURAÇÃO ===
  1. saveCheckpoint()
  2. Composição do system prompt:
     |-- Se persona ativa: Persona + FormatInstructions (Coder ou Agent)
     |-- Se não: Prompt padrão (CoderSystemPrompt ou Agent default)
  3. Prepend workspace context (SOUL.md, USER.md, IDENTITY.md, RULES.md, MEMORY.md)
     |-- Smart retrieval: extrai keywords das últimas 3 mensagens
  4. Append tool context (descrição dos plugins disponíveis)
  5. Append orchestrator prompt (se multi-agent ativo)
       |
       v
  === LOOP ReAct ===
  Para cada turno (até maxTurns):
       |
       +-- Constroi turn history com anchor reminder
       +-- Checa budget de tokens -> compactação se > 60%
       +-- Client.SendPrompt(ctx, systemInstruction, turnHistory, 0)
       |
       v
  Parse da resposta (reasoning, explanation, tool_calls, agent_calls, commands)
       |
       +-- Prioridade 0: agent_calls -> dispatch para workers paralelos
       +-- Prioridade 1: tool_calls -> sanitize args -> security check -> execute plugin -> acumula output
       +-- Prioridade 2: command blocks (formato legado)
       +-- Prioridade 3: resposta final (nenhuma ação = fim do loop)
       |
       v
  Injeta resultados batch no histórico -> próximo turno

<!-- XML self-closing -->
<tool_call name="@coder" args="--file main.go --content '...'" />

<!-- XML paired -->
<tool_call name="@coder" args="..."></tool_call>

<!-- JSON fallback -->
{"tool_call":"@coder","args":{"file":"main.go"}}

Raw args do LLM
       |
  1. HTML unescape (" -> ", 
 -> \n, > -> >)
  2. Normalização de linhas (CRLF -> LF)
  3. Continuação de linha (backslash + newline -> espaço)
  3b. Unescape de JSON-ish strings (se detectado)
  4. Remoção de backslash+espaço bogus (fora de aspas)
  4b. Correção de aspas desbalanceadas com barra final
  5. Remoção de barras invertidas finais pendentes
  6. Normalização de espaços múltiplos (preserva dentro de aspas)
  7. Correções semânticas para @coder (se aplicável)
       |
       v
  Detecção de formato:
  +-- Se JSON válido -> buildArgvFromJSONMap()
  +-- Se CLI-style -> splitToolArgsMultiline()
       |
       v
  Args limpos prontos para execução

Histórico excede budget de tokens
       |
       v
  NIVEL 1: Trimming (near-lossless)
  |-- Remove mensagens de contexto injetado (>3000 chars)
  |-- Remove blocos <plan> do assistente
  |-- Compacta XML verboso em tool outputs
  |-- Deduplica mensagens identicas consecutivas
  |-- Trunca outputs de ferramentas muito longos
  |
  +-- Se dentro do budget -> retorna
       |
       v
  NIVEL 2: Sumarização estruturada
  |-- Divide histórico em: [system | meio (sumarizar) | recentes (manter)]
  |-- Preserva as 8 mensagens mais recentes verbatim
  |-- Envia bloco do meio para LLM com prompt de extração de fatos
  |-- Resultado: mensagem única "summary" substituindo o bloco
  |-- Timeout independente (10 min) para não bloquear o fluxo
  |
  +-- Se dentro do budget -> retorna
       |
       v
  NIVEL 3: Truncamento de emergência
  |-- Último recurso: descarta mensagens do meio sem sumarização
  |-- Mantém system messages + mensagens recentes
  |-- Logga warning para visibilidade

type conversationCheckpoint struct {
    Timestamp time.Time
    Label     string           // resumo auto-gerado da última mensagem do usuário
    History   []models.Message // deep copy do histórico naquele ponto
    MsgCount  int              // número de mensagens no checkpoint
}

llm/openai/register.go      -> init() { registry.Register(ProviderInfo{...}) }
llm/claudeai/register.go    -> init() { registry.Register(ProviderInfo{...}) }
llm/googleai/register.go    -> init() { registry.Register(ProviderInfo{...}) }
llm/xai/register.go         -> init() { registry.Register(ProviderInfo{...}) }
llm/zai/register.go         -> init() { registry.Register(ProviderInfo{...}) }
llm/minimax/register.go     -> init() { registry.Register(ProviderInfo{...}) }
llm/ollama/register.go      -> init() { registry.Register(ProviderInfo{...}) }
llm/copilot/register.go     -> init() { registry.Register(ProviderInfo{...}) }

type ProviderInfo struct {
    Name         string           // chave única (ex: "OPENAI")
    DisplayName  string           // nome para exibição (ex: "OpenAI")
    Factory      ProviderFactory  // função que cria LLMClient a partir de ProviderConfig
    EnvKeys      []string         // variáveis de ambiente para descoberta de API key
    RequiresAuth bool             // se precisa de autenticação OAuth
}

manager.NewLLMManager(logger)
       |
       +-- registry.List() -> nomes de todos os provedores registrados
       +-- Para cada provedor:
       |     +-- Checa EnvKeys (os.Getenv)
       |     +-- Se encontrou key ou RequiresAuth: marca como disponível
       +-- GetClient(provider, model):
             +-- registry.Get(provider) -> ProviderInfo
             +-- info.Factory(ProviderConfig{...}) -> LLMClient

nudge() ou ticker
       |
       v
  maybeExtract()
       +-- Checa: >= 4 novas mensagens && cooldown expirado
       +-- Envia conversa recente para LLM com prompt de extração
       +-- LLM retorna JSON estruturado com categorias:
       |     - DAILY: notas do dia (efêmeras)
       |     - LONGTERM: fatos permanentes
       |     - PROFILE_UPDATE: atualizações de perfil do usuário
       |     - TOPICS: tópicos recorrentes
       |     - PROJECTS: projetos ativos
       |
       +-- Resultados armazenados em arquivos JSON estruturados
       +-- PatternDetector registra padrões de uso