Solucionar problemas de atualização de GitHub Copilot

Este artigo aborda problemas comuns que você pode encontrar ao usar GitHub Copilot atualização. Cada entrada segue um problema, uma causa e um formato de solução para que você possa encontrar e resolver problemas rapidamente.

Problemas de fluxo de trabalho

Esses problemas estão relacionados à descoberta de cenários, à retomada do trabalho e ao estado da tarefa.

Agente diz "nenhum cenário encontrado"

Causa: O agente não reconhece um projeto com suporte ou não consegue encontrar seus arquivos de projeto da raiz do workspace.

Solution:

1. Verifique se o workspace contém arquivos de projeto reconhecíveis. Por exemplo, verifique se há um .sln arquivo ou projeto em um workspace .NET ou um package.json arquivo em um workspace JavaScript ou TypeScript.
2. Pergunte ao agente: "Quais arquivos e tecnologias de projeto você detectou?"
3. Se a solução ou o arquivo de projeto estiver em um subdiretório, abra esse diretório como a raiz do workspace ou aponte o agente para o arquivo explicitamente.

O agente não pode retomar o trabalho anterior

Causa: A .github/upgrades/ pasta, na qual o agente armazena todo o seu estado, está ausente ou corrompida.

Solution:

1. Verifique se a .github/upgrades/ pasta existe na raiz do repositório.
2. Se você excluiu acidentalmente a pasta, inicie o cenário novamente. O agente não pode se recuperar sem seus arquivos de estado.
3. Se a pasta existir, mas os arquivos parecerem corrompidos, peça ao agente para "reavaliar e planejar novamente" para regenerá-los.

Tarefas paralisadas em andamento

Causa: A sessão anterior terminou enquanto o agente estava no meio da tarefa.

Solution:

1. O agente detecta automaticamente tarefas obsoletas na maioria dos casos. Informe ao agente "retomar" ou "reiniciar a tarefa atual".
2. Se o estado travado persistir, diga ao agente "marcar a tarefa atual como pendente e reiniciá-la" ou "reavaliar e continuar da última etapa concluída".
3. Verifique o arquivo correspondente progress-details.md para entender onde a sessão anterior foi interrompida.

O agente continua sugerindo o cenário errado

Causa: A análise do agente pegou características inesperadas do projeto e inferiu um cenário diferente do que você pretendia.

Solution:

Seja explícito sobre o que você quer. Em vez de "atualizar meu projeto", diga:

• "Quero atualizar para .NET 10."
• "Quero atualizar de Newtonsoft.Json para System.Text.Json."
• "Converter meu projeto em formato estilo SDK."
• "Atualize todas as dependências neste projeto JavaScript."
• "Atualize este projeto para o TypeScript 7."

Adicione preferências de cenário ao scenario-instructions.md para evitar incompatibilidades futuras.

Problemas de build e compilação

Esses problemas estão relacionados a falhas de build, restauração de pacote ou problemas de instalação e erros de geração de código.

O build falha após as alterações do agente

Causa: As atualizações podem introduzir alterações de API interruptivas, pacotes ausentes ou padrões de código incompatíveis.

Solution:

1. Conte ao agente sobre a falha. O agente analisa erros automaticamente.
2. Se o agente não puder resolver o problema, reverta a última confirmação (git revert HEAD) e peça ao agente para tentar uma abordagem diferente.
3. Para falhas complexas, verifique tasks.md para localizar a ID da tarefa com falha e examine tasks/{taskId}/progress-details.md para entender o que o agente mudou e em que ordem.

Falha na restauração do NuGet

Causa: Incompatibilidade de pacotes com a estrutura de destino ou falhas de autenticação com feeds NuGet privados.

Solution:

• Para feeds privados: Autentique-se no feed antes de iniciar a atualização.
• Para pacotes incompatíveis: Diga ao agente qual pacote é problemático. O agente pode pesquisar versões compatíveis ou sugerir pacotes alternativos.
• Para problemas de conectividade de feed: Verifique se você pode executar dotnet restore manualmente. Corrija os problemas de feed primeiro e, em seguida, deixe o agente tentar novamente.

Falha na instalação do pacote npm

Causa: O gerenciador de pacotes configurado não está disponível, o arquivo de bloqueio entra em conflito com o manifesto do pacote, um registro privado requer autenticação ou as versões do pacote não podem satisfazer restrições de dependência de par.

Solution:

1. Confirme se o repositório declara e usa o gerenciador de pacotes esperado.
2. Autentique-se em registros privados antes de reiniciar a atualização.
3. Peça ao agente para relatar o conflito de dependência ou de dependência entre pares sem alterar pacotes não relacionados.
4. Resolva problemas de instalação do ambiente ou do gerenciador de pacotes e, em seguida, peça ao agente para repetir a tentativa pelo fluxo de trabalho de atualização de JavaScript e TypeScript.

O agente gera um código que não é compilado

Causa: O código gerado por IA pode conter erros, especialmente em casos de borda ou com padrões de API incomuns.

Solution:

1. O agente detecta erros de compilação automaticamente. Se o agente estiver em dificuldades, forneça diretrizes ou corrija o código manualmente e diga ao agente para continuar.
2. Se o agente tiver dificuldades com uma correção específica após várias tentativas, edite o código manualmente e diga ao agente: "Corrigi o erro de compilação em MyClass.cs, marque esta tarefa concluída".
3. O agente aprende com a sua correção manual e aplica padrões semelhantes quando o mesmo problema ocorre em outro lugar.

Problemas do Git

O agente não pode criar uma ramificação

Causa: Alterações não confirmadas na árvore de trabalho, um conflito de nomenclatura de ramificação ou o Git não está inicializado no espaço de trabalho.

Solution:

1. Confirme ou armazene suas alterações pendentes antes de iniciar um cenário.
2. Verifique se o Git é inicializado executando git status na raiz do workspace.
3. Caso já exista um ramo com o nome desejado pelo agente, exclua o ramo existente ou peça ao agente que use um nome de ramo diferente.

Desfazer todas as alterações do agente

Causa: A atualização não foi conforme o planejado e você deseja recomeçar.

Solution:

1. Retorne à ramificação original com git checkout main (ou à sua ramificação base).
2. A ramificação de trabalho do agente contém todas as alterações que estão isoladas da ramificação principal.
3. Para remover totalmente a ramificação do agente, execute git branch -D <agent-branch-name>.
4. Para manter algumas alterações, selecione commits específicos com git cherry-pick <commit-hash>.

Problemas de desempenho

Esses problemas estão relacionados à velocidade de atualização e à duração da avaliação.

O agente está lento ou leva muito tempo

Causa: Soluções grandes com muitos projetos, grafos de dependência complexos ou várias alterações interruptivas naturalmente levam mais tempo.

Solution:

Para soluções grandes (mais de 50 projetos), considere a atualização em lotes. Agrupe projetos relacionados e atualize-os juntos.

A avaliação leva muito tempo

Causa: A avaliação analisa as dependências de cada projeto, pacotes NuGet, frameworks de destino e alterações de ruptura aplicáveis. Para soluções grandes, a avaliação naturalmente leva mais tempo.

Solution:

1. Tempos de avaliação longos são normais para soluções grandes. Nenhuma ação é necessária.
2. Monitore o progresso no painel Output (selecione AppModernizationExtension na lista suspensa em Visual Studio).
3. A avaliação é executada apenas uma vez por cenário. As fases subsequentes usam os resultados armazenados em cache.

Problemas de personalização

Esses problemas estão relacionados a habilidades personalizadas e arquivos de instrução de cenário.

A habilidade personalizada não é detectada

Causa: O arquivo de habilidade está no local errado, tem metadados ausentes ou inválidos ou tem um formato incorreto.

Solution:

1. Verifique se o arquivo de habilidade está em um dos locais com suporte:
   • .github/skills/ (nível de repositório, a nível de toda a equipe)
   • .github/upgrades/skills/ (nível de cenário)
   • %UserProfile%/.copilot/skills/ (nível do usuário, pessoal)
2. Verifique se os metadados de habilidade incluem pelo menos name e description campos.
3. Confirme se o discovery campo (se definido) é um dos seguintes: lazy, preloadou scenario.
4. Verifique se a habilidade corresponde description ao tipo de tarefa à qual você espera que ela se aplique. O agente usa a correspondência de descrições para selecionar habilidades.

As alterações no scenario-instructions.md não entrarão em vigor

Causa: O agente pode não reler o arquivo durante a sessão, ou suas edições estão na seção errada.

Solution:

1. Peça ao agente para "recarregar instruções" ou iniciar uma nova sessão de chat para forçar uma releitura.
2. Verifique se as edições estão nas seções corretas do arquivo:
   • Preferências do usuário: Para preferências e restrições gerais.
   • Principais decisões: Para registrar decisões importantes tomadas durante a atualização.
   • Instruções personalizadas: Para ajustes comportamentais específicos.
3. Verifique se o arquivo foi salvo e no caminho esperado: .github/upgrades/{scenarioId}/scenario-instructions.md.

Obter ajuda

Quando algo não está funcionando conforme o esperado:

1. Pergunte ao agente: Pergunte "O que deu errado com a última tarefa?" O agente geralmente pode explicar o que aconteceu e sugerir as próximas etapas.
2. Examine o progresso da tarefa: Abra tasks.md para localizar a última ID da tarefa e, em .github/upgrades/{scenarioId}/ seguida, abra tasks/{taskId}/progress-details.md. Os detalhes de progresso mostram o que o agente fez, incluindo os erros encontrados.
3. Arquive um problema: Se você tiver encontrado um bug ou o agente falhar consistentemente em algo, registre um problema no repositório GitHub de plug-ins do agente de atualização.

Conteúdo relacionado

• O que é a atualização do GitHub Copilot?
• Práticas recomendadas
• Conceitos básicos
• Perguntas frequentes sobre GitHub Copilot atualização