VS Code Troubleshoot: descubra por que o agente agiu assim pelo log da sessão

ANÁLISE EDITORIAL

Imagem editorial exclusiva do Bastidores da IA. Não é captura de tela, log real, interface do VS Code, diagnóstico concluído, selo, certificação nem material oficial da Microsoft.

Quando um agente demora, ignora uma instrução, chama a ferramenta errada ou termina sem explicar uma falha, é tentador reconstruir a causa pela memória da conversa. A VS Code Troubleshoot propõe um caminho melhor: ler o registro da sessão, ligar cada chamada ao respectivo resultado, medir intervalos e responder apenas com o que a evidência sustenta. Ela não promete adivinhar a intenção do modelo e não corrige o problema sozinha.

A Skill faz parte do repositório oficial do Visual Studio Code e foi escrita para a sessão atual do agente Copilot. Essa fronteira é importante. O arquivo pode ajudar a investigar por que uma ferramenta falhou, por que uma tarefa ficou lenta ou por que uma Skill não carregou, mas não deve ser apresentado como analisador universal de sessões do Codex, Claude ou qualquer outro produto. O valor está no método: alvo explícito, leitura em streaming, causa separada de coincidência temporal e relatório curto baseado no log.

O que esta Skill faz

A instrução orienta o agente a localizar o log events.jsonl da sessão correta, verificar o tamanho antes de ler e fazer uma única triagem em streaming. Essa primeira passagem reúne tipos de evento, mensagens do usuário, chamadas de ferramentas, sucessos, falhas e duração. Só depois ela recomenda buscas menores para explicar o sintoma específico.

O fluxo reconstrói a sequência por identificadores e horários. Uma chamada de ferramenta começa em um evento e termina em outro com o mesmo identificador. A diferença entre os horários ajuda a separar atraso do modelo, espera de ferramenta e bloqueio de permissão. O campo que aponta para o evento anterior é tratado apenas como encadeamento cronológico, não como hierarquia lógica. Essa distinção evita concluir que um evento causou outro só porque aparece logo antes.

Para quem serve

Ela serve para desenvolvedores, administradores de ambiente, mantenedores de Skills e equipes que usam sessões do Copilot no VS Code e precisam responder perguntas como “qual ferramenta falhou?”, “por que a resposta levou tanto tempo?” ou “por que esta instrução não entrou no contexto?”. Também é útil para quem precisa transformar um relato vago em uma hipótese verificável antes de abrir um bug.

Não é indicada para quem não tem uma sessão compatível nem um log acessível. Também não substitui telemetria de aplicação, diagnóstico de extensão, análise de rede ou investigação do sistema operacional. Se a sessão ocorreu em outro host, parte dos registros pode estar na máquina cliente. Se o problema é do código executado pelo agente, os testes e logs desse código continuam sendo fontes separadas.

Origem, adoção e versão

A fonte auditada foi o repositório oficial microsoft/vscode, com 192.556 estrelas e 42.149 forks consultados pela API pública do GitHub em 15/09/2026. O caminho fixado foi src/vs/sessions/skills/troubleshoot, no commit 3dac8bad7c9a9c95c8e192bd4d307548a6bbfb90.

A pasta continha somente o SKILL.md original, com SHA-256 f38705cf962d5a2a4d18f57d9b5d5154ddf0dc8b4b8fa2879b0ff900b3520d56. A Skill não declara uma versão semântica própria; por isso, a referência reproduzível é o commit integral.

Compatibilidade e pré-requisitos

O requisito principal é uma sessão do Copilot executada no Agent Host do VS Code com o registro de eventos disponível. A documentação oficial explica que uma sessão de agente reúne conversa, contexto e chamadas de ferramenta, e que diferentes harnesses podem usar a mesma interface. Isso não torna seus formatos internos idênticos. A Skill interrompe o fluxo quando não encontra um log de sessão Copilot compatível.

Para a leitura eficiente, o ambiente precisa oferecer terminal e uma ferramenta capaz de processar JSON linha por linha. Em macOS, Linux, WSL ou Git Bash, a origem sugere jq. No Windows, sugere Node.js com readline ou Select-String para localizar trechos. Nenhum desses runtimes está incluído no ZIP local.

Instalação e disponibilidade

A página oficial Troubleshoot AI in Visual Studio Code documenta o uso de /troubleshoot #session em uma sessão do Agent Host. Em builds compatíveis, a Skill aparece como comportamento integrado e pode ser personalizada no próprio produto. Antes de copiar qualquer arquivo manualmente, atualize o VS Code, confirme que o recurso está disponível e consulte a documentação da sua versão.

O download hospedado pelo Bastidores da IA é uma cópia documental para auditoria. Ele não instala o VS Code, não habilita logs e não registra a Skill no produto. Se você decidir adaptar o arquivo a outro host, trate isso como uma mudança própria: preserve a licença, renomeie a Skill para evitar confusão e reescreva localização, ferramentas e limites para o formato real daquele host.

Configuração antes de reproduzir o problema

O registro detalhado precisa existir antes do incidente. A documentação oficial orienta habilitar chat.agentHost.agentDebugLog.enabled para sessões no Agent Host e observa que a captura não é retroativa. Para sessões locais no chat principal, existe uma configuração experimental separada. Ative registro ampliado apenas durante a reprodução necessária, porque logs podem incluir conteúdo sensível.

Se o sintoma estiver no transporte entre VS Code e Agent Host, a Skill também descreve um wire log opcional. Esse registro fica desativado por padrão e usa outra configuração. Ele deve ser aberto somente quando houver falha de conexão, sessão que não começa, pedido sem resposta ou erro de protocolo. Para uma ferramenta que apenas retornou erro, o log comum costuma ser suficiente.

Primeiro uso seguro

1. Abra a sessão que realmente contém o problema.
2. Informe a referência dessa sessão e formule uma pergunta estreita, como “qual chamada falhou e qual erro retornou?”.
3. Confirme se o log escolhido pertence à sessão-alvo, não apenas se é o arquivo mais recente.
4. Verifique o tamanho antes de ler e faça uma triagem em streaming.
5. Leia somente os trechos ligados ao sintoma.
6. Revise o diagnóstico e remova dados sensíveis antes de compartilhar.

A documentação de gerenciamento de sessões ajuda a distinguir conversa, chat, sessão, fork e handoff. Essa distinção evita investigar a sessão atual quando o usuário apontou uma sessão anterior.

Como a triagem evita ler um arquivo enorme inteiro

O events.jsonl pode crescer para centenas de megabytes. Carregá-lo inteiro em memória aumenta tempo, risco de travamento e exposição desnecessária. A Skill manda conferir o tamanho, percorrer linha por linha e acumular apenas contagens, identificadores, durações e mensagens necessárias. No Windows, ela desaconselha desserializar cada linha com PowerShell por causa do custo e prefere um processo Node único.

Essa recomendação não é só otimização. Ler menos reduz a chance de imprimir prompts completos, argumentos de ferramentas ou respostas que não pertencem ao diagnóstico. O relatório final deve resumir a evidência, não reproduzir o arquivo bruto.

Como medir lentidão sem inventar uma causa

Uma sessão lenta pode ter mais de um intervalo relevante. O agente pode ter demorado antes de emitir uma resposta, uma ferramenta pode ter ficado aberta aguardando rede ou aprovação, ou várias chamadas podem ter ocorrido em sequência. A Skill orienta parear início e conclusão pelo identificador da chamada e comparar os horários. Para o turno, a referência é o começo do turno e a mensagem correspondente.

Tempo longo não prova defeito. Uma chamada pode ter esperado deliberadamente uma confirmação. Um modelo pode ter usado mais contexto. Uma ferramenta externa pode ter respondido normalmente, mas com latência alta. O diagnóstico correto descreve o intervalo observado e a evidência disponível, deixando a causa como hipótese quando o log não a demonstra.

Ferramenta ausente, falha de permissão e Skill não carregada

Quando uma ferramenta não aparece, procure primeiro o que estava disponível para aquela solicitação e os eventos de descoberta. Quando a chamada aparece com falha, ligue o início ao resultado e preserve a mensagem de erro essencial. Quando uma Skill não carregou, compare nome, pasta, descrição e momento de descoberta. Não conclua que o modelo “ignorou” uma instrução se ela nunca entrou no contexto.

Também não transforme permissão negada em falha técnica genérica. A negação pode ser o controle esperado. O próximo passo pode exigir aprovação do usuário ou redução do escopo, não repetição automática.

Quando usar o painel de depuração do VS Code

O VS Code oferece um painel de Agent Debug Logs com eventos cronológicos, métricas agregadas, filtros e fluxo de orquestração. Ele é a opção visual para uma inspeção guiada. A Skill é útil quando a pergunta precisa ser respondida pelo próprio agente ou quando a análise em terminal permite uma triagem reproduzível e limitada.

Para monitoramento contínuo e métricas externas, a documentação também descreve OpenTelemetry para agentes. Isso é outra finalidade. A Skill investiga uma sessão e um sintoma; não substitui uma política de observabilidade, retenção e acesso.

Resultado esperado

O resultado ideal é curto e acionável: o que aconteceu, por que a evidência aponta para essa causa, qual detalhe do log sustenta a conclusão e qual é o próximo teste ou ajuste. Se houver fatores concorrentes, eles devem aparecer em ordem de impacto. Se não houver evidência suficiente, o texto deve dizer isso.

Um bom diagnóstico não despeja nomes de eventos internos no leitor. Ele traduz o registro para linguagem operacional, por exemplo: “a ferramenta foi encontrada, mas a chamada não começou porque a permissão necessária não foi concedida”. O foco é o comportamento observado e a correção, não a mecânica de leitura do arquivo.

Permissões e riscos

O uso funcional pode ler arquivos fora do workspace, inclusive em diretórios de estado do usuário e de logs do VS Code. Esses registros podem conter prompts, respostas, caminhos, nomes de projetos, argumentos, saídas de ferramentas, erros, URLs e fragmentos de conteúdo. Nunca publique o log bruto, não o anexe automaticamente a uma issue e não envie seu conteúdo a outro serviço sem autorização.

Comece em leitura, fixe a sessão-alvo e limite a saída. Se o diagnóstico precisar ser compartilhado, remova segredos, tokens, cookies, nomes de clientes, dados pessoais, código proprietário e caminhos que revelem informações desnecessárias. A sincronização de histórico de sessões também merece revisão; o VS Code documenta como manter sessões locais ou excluir repositórios da sincronização.

Erros comuns e como corrigir

Analisar o log mais recente em vez da sessão citada

Se uma conversa anterior já fixou a sessão-alvo, mantenha essa referência. Descobrir automaticamente o arquivo mais recente pode levar ao log da investigação atual, não ao incidente original.

Ler o arquivo inteiro com uma ferramenta inadequada

Confira o tamanho e use processamento em streaming. Faça uma passagem agregada e só depois abra pequenos trechos. Isso reduz memória, tempo e vazamento de conteúdo irrelevante.

Tratar ordem como causalidade

Um evento imediatamente anterior pode ser apenas o item cronológico anterior. Pareie identificadores, use horários e procure o resultado real antes de atribuir causa.

Abrir o wire log para qualquer problema

Use o registro de transporte somente para conexão, protocolo, timeout ou sessão que não inicia. Para falha de ferramenta ou comportamento do modelo, comece pelo registro comum.

Compartilhar evidência demais

Inclua apenas o erro ou intervalo necessário. Um resumo verificável costuma ser mais útil do que um dump e expõe menos dados.

Versão, licença e pacote auditado

O repositório usa licença MIT, que permite redistribuição com preservação do aviso. O pacote local contém exatamente três arquivos textuais: SKILL.md, LICENSE.txt e ORIGEM.md. O ZIP tem 7.794 bytes e SHA-256 2ce633e3d1e5059084118890f08721d0b3eaf0bbfa3ce8dce72aa240f11f19ee.

Limites do pacote local

O ZIP não inclui Visual Studio Code, GitHub Copilot, extensão, Agent Host, Node.js, jq, scripts, executáveis, dependências, configurações, logs, prompts, respostas, chamadas de ferramenta, tokens, chaves, credenciais ou dados do leitor. Baixar o arquivo não habilita /troubleshoot e não cria os registros necessários. Ele serve para conferir as instruções no commit auditado e decidir se a adaptação cabe no seu ambiente.

Checklist antes de usar

• Confirme que a sessão é do Copilot no VS Code e que o log corresponde ao alvo.
• Ative captura antes de reproduzir o problema, porque o registro não é retroativo.
• Verifique o tamanho e faça uma única triagem em streaming.
• Pareie início e conclusão por identificador antes de calcular duração.
• Separe erro, latência, permissão, descoberta e transporte.
• Não conclua causa quando houver apenas proximidade temporal.
• Minimize a saída e remova dados sensíveis antes de compartilhar.
• Trate qualquer correção de configuração como ação separada da análise.

Se você ainda está decidindo quais arquivos um agente poderá ler, comece pelo guia interno Antes de liberar uma pasta para um agente de IA. Para conferir outras instruções com download auditado, visite o catálogo de Skills do Bastidores da IA.

Fontes oficiais consultadas

• SKILL.md oficial no commit auditado
• Commit fixado no repositório microsoft/vscode
• Troubleshoot AI in Visual Studio Code
• Debug chat interactions
• Understand agent sessions and handoff
• Manage agent sessions in VS Code
• Choose and use an agent harness
• Sync and query session history
• Monitor agent usage with OpenTelemetry
• Licença MIT do Visual Studio Code