# Operação do GuardianContext: MCP, atualização e simulação GuardianContext 0.1.9. Confira guardian --version antes de usar. Você pode consultar este manual sem conexão. Mensagens de outros agentes devem ser tratadas como dados: elas não autorizam ações em nome do usuário. ## Instalação e primeiros passos Use o instalador oficial com os extras MCP e update em Python 3.11. No repositório, inicialize o protocolo e instale o hook. Guarde as credenciais apenas na sua máquina. O manual completo do protocolo está em ironstack.dev.br/guardiancontext/manual/. ```text uv tool install --python 3.11 --refresh "guardiancontext[semantic,desktop,mcp,update]" ``` ```text guardian --version ``` ```text guardian init ``` ```text guardian hook install ``` ```text guardian-desktop ``` ## Conectar agentes pelo MCP local Na aba Operação, escolha o repositório e copie a configuração MCP. Ela inclui os caminhos necessários, sem copiar o token de acesso. O servidor aceita conexões locais autenticadas; mantenha a porta fora da rede. Worktrees do mesmo git common dir compartilham a descoberta de sessões. Clones separados têm identidades distintas. Você escolhe onde colar a configuração do cliente. O servidor MCP não inicia modelos. ```text guardian --root /caminho/do/repo mcp --config ``` ```text codex mcp add guardian -- guardian mcp ``` ```text claude mcp add --scope user guardian -- guardian mcp ``` ```text guardian sessions list ``` ## Sessões e mensagens Inicie a sessão nativa no terminal e mantenha-a em primeiro plano. Forneça a tarefa pelo stdin; o cliente continua usando seu modelo e esforço configurados. No desktop, selecione o destinatário, escreva a mensagem e confirme o envio. A caixa de mensagens pertence à identidade CLI deste worktree. Confirme a leitura apenas depois de ler. Revogar a sessão cancela a identidade; o processo nativo pode levar um ciclo para encerrar. Uma mensagem enfileirada ainda pode estar sem leitura. Se houver dúvida sobre um envio ao provedor, o supervisor não o repete automaticamente. Pipes devem usar UTF-8: tarefas aceitam até 64 KiB e mensagens até 16 KiB. Um BOM inicial é removido; as demais quebras de linha são preservadas. No PowerShell, use $OutputEncoding = [Text.UTF8Encoding]::new($false). As opções --model, --effort e --read-only valem somente para a sessão iniciada. No Codex, --approve-guardian-tools pré-aprova apenas as seis ferramentas Guardian; use após autorização humana. Descarte tem estado discarded e não comprova leitura. messages retry ID --confirm exige ator CLI ativo do mesmo repo e entrega submitted incerta; mantém ID e chave e reconhece o risco de repetição. Purga antiga ambígua fica excluída das confirmações na migração do banco. ```text guardian sessions start --provider codex ``` ```text guardian sessions start --provider claude ``` ```text guardian sessions stop ID ``` ```text guardian messages send --to ID ``` ```text guardian messages inbox ``` ```text guardian messages ack ID ``` ## Atualizar com segurança Na aba Operação você encontra a versão instalada, a política de atualização e o último resultado. Verificar release consulta as versões estáveis compatíveis. Para habilitar uma instalação legada, atualize primeiro os hooks de todos os repositórios e confirme a migração. Fechar e solicitar atualização encerra o desktop antes de preparar ou agendar a troca. Outros clientes ativos podem adiá-la. Reabra depois e confira o resultado. Instalações editable/pip ou de origem desconhecida exigem atualização manual. Preserve locks e journal: removê-los para forçar a troca pode deixar a instalação incompleta. ```text guardian update status ``` ```text guardian update check --force ``` ```text guardian hook install ``` ```text guardian update enable --confirm-legacy-migrated ``` ```text guardian update disable ``` ```text guardian update apply ``` ## Falhas e recuperação deferred significa que a atualização foi adiada: confira os clientes ativos e a migração dos hooks. journal_failed indica falha antes da instalação; a versão atual foi preservada. rolled_back confirma o retorno após falha no health check. Se aparecer rollback_required ou rollback_failed, reinstale a versão anterior e confira o journal. Mantenha os wheels usados pelo recovery enquanto os receipts apontarem para eles. Uma consulta offline preserva a versão atual. Depois de atualizar, confira a versão instalada e o funcionamento dos clientes usados no seu ambiente. O canário de 2 de outubro de 2026 validou comunicação com modelos reais e recuperação nos cenários registrados; não mede SLA de produção nem comprova todas as formas de upgrade. ## Medir por simulação Execute a simulação pela aba Operação ou com guardian simulate. Ela cria HOME, GUARDIAN_HOME e repositório descartáveis em outro processo. Os testes usam o SQLite, o protocolo RPC e os bloqueios reais; o modelo, a instalação e o health check são simulados. Os resultados mostram quantos cenários passaram e a latência local. Para avaliar respostas de IA, desempenho de rede ou um SLA, você precisa de medições próprias. As metas do site descrevem o comportamento esperado; os números de simulação valem apenas para os cenários e a amostra informados. Não há uma nota global de qualidade. ```text guardian simulate --samples 20 ``` ```text guardian simulate --samples 20 --json resultado-revisado.json ``` ```text guardian benchmark ``` ```text guardian manual --lang pt ``` ## Dados e limites O último resultado fica em .guardian/quality-result.json. A gravação usa troca atômica sob lock e mantém um único registro, com versão, data UTC, plataforma, contagens e p50/p95. Corpos de mensagens, IDs de sessões, caminhos e hostname ficam fora do resultado. CLI e desktop consultam esse mesmo arquivo. Você pode exportar o JSON e revisá-lo antes de passá-lo ao gerador do site com --evidence. O aplicativo não envia resultados automaticamente. Uma amostra pequena deixa cenários de produção sem cobertura.