Resolver problemas de atualização do GitHub Copilot

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

Questões de fluxo de trabalho

Estas questões relacionam-se com a descoberta de cenários, a retomada do trabalho e o estado da tarefa.

O agente diz "não foram encontrados cenários"

Causa: O agente não reconhece um projeto suportado ou não consegue encontrar os ficheiros do projeto a partir da raiz do workspace.

Solution:

1. Verifique se o espaço de trabalho contém ficheiros de projeto reconhecíveis. Por exemplo, verifique um .sln ficheiro de projeto ou num espaço de trabalho .NET, ou um package.json ficheiro num espaço de trabalho JavaScript ou TypeScript.
2. Pergunte ao agente: "Que ficheiros e tecnologias do projeto detetou?"
3. Se a sua solução ou ficheiro de projeto estiver num subdiretório, abra esse diretório como raiz do workspace ou aponte explicitamente o agente para o ficheiro.

O agente não pode retomar trabalhos anteriores

Causa: A .github/upgrades/ pasta, onde o agente armazena todo o seu estado, está em falta ou corrompida.

Solution:

1. Verifica se a .github/upgrades/ pasta existe na raiz do teu repositório.
2. Se acidentalmente apagaste a pasta, começa o cenário do zero. O agente não consegue recuperar sem os seus ficheiros de estado.
3. Se a pasta existir mas os ficheiros parecerem corrompidos, peça ao agente para "reavaliar e replanear" para os regenerar.

Tarefas bloqueadas em curso

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

Solution:

1. Na maioria dos casos, o agente deteta automaticamente tarefas obsoletas. Diz ao agente "retomar" ou "reiniciar a tarefa atual".
2. Se o estado bloqueado persistir, diga ao agente "marque a tarefa atual como pendente e reinicie-a" ou "reavalie e continue a partir do último passo concluído."
3. Verifique o ficheiro correspondente progress-details.md para perceber onde terminou a sessão anterior.

O agente continua a sugerir o cenário errado

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

Solution:

Sê explícito sobre o que queres. Em vez de "atualizar o meu projeto", diga:

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

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

Problemas de construção e compilação

Estes problemas estão relacionados com falhas de compilação, problemas de restauração ou instalação de pacotes e erros de geração de código.

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

Causa: As atualizações podem introduzir alterações disruptivas na API, pacotes em falta ou padrões de código incompatíveis.

Solution:

1. Informa o agente sobre a falha. O agente analisa os erros automaticamente.
2. Se o agente não conseguir resolver o problema, reverte o último commit (git revert HEAD) e pede ao agente para tentar uma abordagem diferente.
3. Para falhas complexas, verifique tasks.md para encontrar o ID da tarefa com falha e depois reveja tasks/{taskId}/progress-details.md para perceber o que o agente alterou e em que ordem.

Falhas na restauração do NuGet

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

Solution:

• Para transmissões privadas: Autentica-te no feed antes de começares a atualização.
• Para pacotes incompatíveis: Diga ao agente qual a encomenda problemática. O agente pode procurar versões compatíveis ou sugerir pacotes alternativos.
• Para problemas de conectividade ao feed: Confirma se consegues correr dotnet restore manualmente. Corrige primeiro quaisquer problemas de alimentação e depois deixe o agente tentar novamente.

Falha na instalação do pacote NPM

Causa: O gestor de pacotes configurado não está disponível, o ficheiro de bloqueio entra em conflito com o manifesto do pacote, um registo privado requer autenticação, ou as versões dos pacotes não conseguem satisfazer restrições de dependência entre pares.

Solution:

1. Confirme que o repositório declara e utiliza o gestor de pacotes esperado.
2. Autentique em registos privados antes de reiniciar a atualização.
3. Peça ao agente para reportar a dependência ou o conflito de dependência entre pares sem alterar pacotes não relacionados.
4. Resolver problemas de instalação do ambiente ou do gestor de pacotes e depois pedir ao agente para tentar novamente através do fluxo de trabalho de atualização em JavaScript e TypeScript.

O agente gera código que não compila

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

Solution:

1. O agente deteta automaticamente erros de compilação. Se o agente estiver com dificuldades, forneça orientações 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 como concluída."
3. O agente aprende com a sua correção manual e aplica padrões semelhantes quando o mesmo problema surge em outros contextos.

Problemas de git

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

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

Solution:

1. Comprometa ou armazene as alterações pendentes antes de iniciar um cenário.
2. Verifique se o Git está inicializado executando git status na raiz do workspace.
3. Se já existir um ramo com o nome pretendido pelo agente, elimine o ramo existente ou peça ao agente para usar um nome diferente.

Desfazer todas as alterações no agente

Causa: A atualização não correu como planeado e queres recomeçar.

Solution:

1. Volta ao ramo original ( git checkout main ou ao ramo base).
2. O ramo de trabalho do agente contém todas as alterações isoladas do ramo principal.
3. Para remover completamente o ramo do agente, execute git branch -D <agent-branch-name>.
4. Para manter algumas alterações, selecione a dedo commits específicos com git cherry-pick <commit-hash>.

Problemas de desempenho

Estas questões estão relacionadas com a velocidade de atualização e a duração da avaliação.

O agente é lento ou demora muito tempo

Causa: Soluções grandes com muitos projetos, grafos de dependência complexos ou inúmeras alterações disruptivas naturalmente demoram mais tempo.

Solution:

Para soluções grandes (50+ projetos), considere atualizar em lotes. Agrupa os projetos relacionados e atualiza-os juntos.

A avaliação demora muito tempo

Causa: A avaliação analisa as dependências de cada projeto, pacotes NuGet, frameworks-alvo e alterações de quebra aplicáveis. Para soluções de grande dimensão, a avaliação demora naturalmente mais tempo.

Solution:

1. Tempos de avaliação longos são normais para soluções grandes. Não é necessária nenhuma ação.
2. Monitorizar o progresso no painel Output (selecione AppModernizationExtension no menu pendente do Visual Studio).
3. A avaliação realiza-se apenas uma vez por cenário. As fases subsequentes utilizam os resultados em cache.

Problemas de personalização

Estas questões dizem respeito a competências personalizadas e ficheiros de instruções de cenários.

A habilidade personalizada não é reconhecida

Causa: O ficheiro de skill está no local errado, tem metadados em falta ou inválidos, ou tem um formato incorreto.

Solution:

1. Verifique se o ficheiro de skill está numa das localizações suportadas:
   • .github/skills/ (ao nível do repositório, em toda a equipa)
   • .github/upgrades/skills/ (nível de cenário)
   • %UserProfile%/.copilot/skills/ (nível de utilizador, pessoal)
2. Verifica se os metadados da competência incluem pelo menos os campos name e description.
3. Confirme que o discovery corpo (se definido) é um dos seguintes: lazy, preload, ou scenario.
4. Confirma se a competência description corresponde ao tipo de tarefa a que esperas que se aplique. O agente utiliza a correspondência de descrições para escolher habilidades.

As alterações à scenario-instructions.md não entram em vigor

Causa: O agente pode não reler o ficheiro a meio da sessão, ou as tuas edições estão na secção errada.

Solution:

1. Pede ao agente para "recarregar instruções" ou iniciar uma nova sessão de chat para forçar uma releitura.
2. Verifique se as suas edições estão nas secções corretas do ficheiro:
   • Preferências do Utilizador: Para preferências e restrições gerais.
   • Decisões-chave: Para registar decisões importantes tomadas durante a atualização.
   • Instruções Personalizadas: Para intervenções comportamentais específicas.
3. Verifique se o ficheiro está guardado e no caminho esperado: .github/upgrades/{scenarioId}/scenario-instructions.md.

Obter ajuda

Quando algo não está a funcionar como esperado:

1. Pergunte ao agente:Pergunte "O que correu mal na última tarefa?" O agente pode muitas vezes explicar o que aconteceu e sugerir os próximos passos.
2. Reveja o progresso da tarefa: Abra tasks.md em .github/upgrades/{scenarioId}/ para encontrar o ID da última tarefa e, em seguida, abra tasks/{taskId}/progress-details.md. Os detalhes do progresso mostram o que o agente fez, incluindo quaisquer erros encontrados.
3. Apresenta uma reclamação: Se encontrares um bug ou se o agente falha consistentemente em algo, apresenta um problema no repositório GitHub do update-agent-plugins.

Conteúdo relacionado

• O que é a atualização do GitHub Copilot?
• Melhores práticas
• Conceitos fundamentais
• Perguntas Frequentes sobre atualizações do GitHub Copilot