Diagnóstico de problemas na modernização do GitHub Copilot

Este artigo aborda problemas comuns que pode encontrar ao usar a modernização do GitHub Copilot para .NET, organizados por categoria. 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"

Cause: O agente não reconhece o espaço de trabalho como um projeto .NET.

Solution:

1. Certifique-se de que a raiz do espaço de trabalho contém um .sln, .csproj, ou .vbproj ficheiro.
2. Pergunte ao agente: "Que solução ou ficheiro de projeto está a usar?"
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 a pasta foi apagada acidentalmente, 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 para "marcar a tarefa atual como pendente e reiniciá-la" ou "reavaliar e continuar a partir do último passo concluído."
3. Verifique o ficheiro correspondente progress-details.md da tarefa 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 migrar de Newtonsoft.Json para System.Text.Json."
• "Converter o meu projeto para formato ao estilo SDK."

Também adicione preferências de cenários em scenario-instructions.md para evitar incompatibilidades no futuro.

Problemas de construção e compilação

Estes problemas estão relacionados com falhas de compilação, problemas de restauração do NuGet 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 automaticamente os erros.
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 execution-log.md para entender que alterações o agente fez 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 o feed antes de iniciar 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: Verifica se consegues executar dotnet restore manualmente. Corrige primeiro quaisquer problemas de alimentação e depois deixe o agente tentar novamente.

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 a ter 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 se o mesmo problema aparecer noutro local.

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. Compromete ou guarda as alterações pendentes antes de começares um cenário.
2. Verifique se o Git está inicializado: executa 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. Volte ao seu ramo original: git checkout main (ou qualquer que seja o seu 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: git branch -D <agent-branch-name>.
4. Para manter algumas alterações, selecione a dedo commits específicos: 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 muito 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 é preciso fazer nada.
2. Monitorizar o progresso no painel Output (selecione AppModernizationExtension no menu pendente do Visual Studio).
3. A avaliação só ocorre 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 ou tem metadados em falta ou inválidos, ou o formato da skill está 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. Certifique-se de que o discovery campo (se definido) é um dos seguintes: lazy, preload, ou scenario.
4. Verifica se a description competência 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. Certifique-se de que 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. Revise o registo de execução: Abrir execution-log.md em .github/upgrades/{scenarioId}/. O registo mostra um registo cronológico do que o agente fez, incluindo quaisquer erros que o agente tenha encontrado.
3. Regista um problema: Se encontrares um bug ou se o agente falhar consistentemente em algo, regista um problema no repositório GitHub @modernize-dotnet.

Conteúdo relacionado

• O que é a modernização do GitHub Copilot?
• Melhores práticas
• Conceitos fundamentais
• FAQ sobre modernização do GitHub Copilot