Compartir a través de

Resolución de problemas de la modernización de GitHub Copilot

En este artículo se tratan los problemas comunes que pueden surgir al usar la función de modernización de GitHub Copilot para .NET, organizados por categoría. Cada entrada sigue un problema, causa y formato de solución para que pueda encontrar y resolver problemas rápidamente.

Problemas de flujo de trabajo

Estos problemas se relacionan con la detección de escenarios, la reanudación del trabajo y el estado de la tarea.

El agente dice "no se encontraron escenarios"

Cause: El agente no reconoce el área de trabajo como un proyecto de .NET.

Solution:

  1. Asegúrese de que la raíz del área de trabajo contenga un archivo .sln, .csproj o .vbproj.
  2. Pregunte al agente: "¿Qué solución o archivo de proyecto está usando?"
  3. Si el archivo de solución o proyecto está en un subdirectorio, abra ese directorio como raíz del área de trabajo o apunte el agente al archivo explícitamente.

El agente no puede reanudar el trabajo anterior

Causa: La .github/upgrades/ carpeta, donde el agente almacena todo su estado, falta o está dañada.

Solution:

  1. Compruebe si la carpeta existe en la .github/upgrades/ raíz del repositorio.
  2. Si la carpeta se eliminó accidentalmente, inicie el escenario nuevo. El agente no se puede recuperar sin sus archivos de estado.
  3. Si la carpeta existe pero los archivos parecen estar corruptos, pida al agente que "evalúe nuevamente y replanee" para regenerarlos.

Sugerencia

Confirme la carpeta en la .github/upgrades/ rama para que se conserve entre sesiones y máquinas.

Tareas bloqueadas en curso

Causa: La sesión anterior finalizó mientras el agente estaba a mitad de una tarea.

Solution:

  1. El agente detecta automáticamente tareas obsoletas en la mayoría de los casos. Indique al agente "reanudar" o "reiniciar la tarea actual".
  2. Si el estado bloqueado persiste, indique al agente que "marque la tarea actual como pendiente y reiníciela" o "vuelva a evaluarla y continuar desde el último paso completado".
  3. Compruebe el archivo correspondiente progress-details.md para que la tarea comprenda dónde se detuvo la sesión anterior.

El agente sigue sugiriendo el escenario incorrecto

Causa: El análisis del agente ha recogido características inesperadas del proyecto e infiere un escenario diferente al previsto.

Solution:

Sé explícito sobre lo que quieres. En lugar de "actualizar mi proyecto", diga:

  • "Quiero actualizar a .NET 10."
  • "Quiero migrar de Newtonsoft.Json a System.Text.Json".
  • "Convertir mi proyecto en formato de estilo SDK".

Agregue también preferencias de escenario a scenario-instructions.md para evitar errores de coincidencia futuros.

Problemas de construcción y compilación

Estos problemas se relacionan con errores de compilación, problemas de restauración de NuGet y errores de generación de código.

Se produce un error en la compilación después de los cambios del agente

Causa: Las actualizaciones pueden introducir cambios importantes en la API, paquetes que faltan o patrones de código incompatibles.

Solution:

  1. Informe al agente sobre el error. El agente analiza los errores automáticamente.
  2. Si el agente no puede resolver el problema, revierta la última confirmación (git revert HEAD) y pida al agente que pruebe otro enfoque.
  3. Para errores complejos, compruebe execution-log.md qué cambios realizó el agente y en qué orden.

Error en la restauración de NuGet

Causa: Incompatibilidad de paquetes con la plataforma de destino o errores de autenticación con fuentes de NuGet privadas.

Solution:

  • Para fuentes privadas: Autentíquese en la fuente antes de iniciar la actualización.
  • Para paquetes incompatibles: Indique al agente qué paquete es problemático. El agente puede buscar versiones compatibles o sugerir paquetes alternativos.
  • Para problemas de conectividad del feed: Verifique que puede ejecutar dotnet restore manualmente. Corrija primero los problemas de fuente y, a continuación, deje que el agente vuelva a intentarlo.

El agente genera código que no se compila

Causa: El código generado por ia puede contener errores, especialmente en casos perimetrales o con patrones de API poco comunes.

Solution:

  1. El agente detecta automáticamente errores de compilación. Si el agente tiene dificultades, proporcione instrucciones o corrija el código manualmente e indique al agente que continúe.
  2. Si el agente tiene problemas con una corrección específica después de varios intentos, edite el código manualmente e indique al agente: "He corregido el error de compilación en MyClass.cs, marque esta tarea completa".
  3. El agente aprende de la corrección manual y aplica patrones similares si el mismo problema aparece en otro lugar.

Problemas de Git

Nota:

El agente también funciona con carpetas que no son de Git. Si el área de trabajo no es un repositorio de Git, el agente omite las operaciones de Git (bifurcación, confirmación) y aplica los cambios directamente a los archivos. Sin Git, realice una copia de seguridad manual del proyecto antes de empezar para que pueda revertir si es necesario.

El agente no puede crear una rama

Causa: Los cambios no confirmados en el árbol de trabajo, un conflicto de nomenclatura de rama o Git no se inicializan en el área de trabajo.

Solution:

  1. Confirme o guarde los cambios pendientes antes de iniciar un escenario.
  2. Verifique que Git está inicializado: ejecute git status en la raíz del área de trabajo.
  3. Si ya existe una rama con el nombre previsto del agente, elimine la rama existente o pida al agente que use otro nombre de rama.

Deshacer todos los cambios realizados por el agente

Causa: La actualización no fue según lo planeado y quieres empezar de nuevo.

Solution:

  1. Vuelva a la rama original: git checkout main (o sea cual sea la rama base).
  2. La rama de trabajo del agente contiene todos los cambios aislados de la rama principal.
  3. Para eliminar la rama del agente por completo: git branch -D <agent-branch-name>.
  4. Para mantener algunos cambios, aplique selectivamente confirmaciones específicas: git cherry-pick <commit-hash>.

Sugerencia

El agente realiza confirmaciones granulares por tarea, por lo que puede mantener selectivamente los cambios que han funcionado.

Problemas de rendimiento

Estos problemas se relacionan con la velocidad de actualización y la duración de la evaluación.

El agente es lento o tarda mucho tiempo

Causa: Las soluciones grandes con muchos proyectos, gráficos de dependencias complejos o numerosos cambios importantes tardan naturalmente más tiempo.

Solution:

Para soluciones muy grandes (más de 50 proyectos), considere la posibilidad de actualizar en lotes. Agrupar proyectos relacionados y actualizarlos juntos.

La evaluación tarda mucho tiempo

Causa: La evaluación analiza las dependencias de cada proyecto, paquetes NuGet, marcos de destino y cambios importantes aplicables. En el caso de soluciones grandes, la evaluación tarda más tiempo.

Solution:

  1. Los tiempos de evaluación largos son normales para soluciones grandes. No es necesario realizar ninguna acción.
  2. Supervise el progreso en el panel Output (seleccione AppModernizationExtension en la lista desplegable de Visual Studio).
  3. La evaluación solo se ejecuta una vez por escenario. Las fases posteriores usan los resultados almacenados en caché.

Problemas de personalización

Estos problemas se relacionan con las habilidades personalizadas y los archivos de instrucciones para escenarios.

No se reconoce la habilidad personalizada

Causa: El archivo de aptitud está en la ubicación incorrecta o tiene metadatos que faltan o no son válidos, o el formato de aptitud es incorrecto.

Solution:

  1. Asegúrese de que el archivo de habilidad está en una de las ubicaciones admitidas:
    • .github/skills/ (nivel de repositorio, en todo el equipo)
    • .github/upgrades/skills/ (nivel de escenario)
    • %UserProfile%/.copilot/skills/ (nivel de usuario, personal)
  2. Compruebe que los metadatos de la habilidad incluyen al menos los campos name y description.
  3. Asegúrese de que el discovery campo (si se establece) es uno de: lazy, preloado scenario.
  4. Compruebe que la aptitud description coincide con el tipo de tarea a la que espera que se aplique. El agente usa la coincidencia de descripciones para seleccionar habilidades.

Los cambios en scenario-instructions.md no surten efecto

Causa: Es posible que el agente no vuelva a leer el archivo midsession o las modificaciones se encuentren en la sección incorrecta.

Solution:

  1. Pida al agente que "vuelva a cargar instrucciones" o inicie una nueva sesión de chat para forzar una nueva lectura.
  2. Asegúrese de que las modificaciones se encuentran en las secciones correctas del archivo:
    • Preferencias de usuario: Para las preferencias y restricciones generales.
    • Decisiones clave: Para registrar decisiones importantes tomadas durante la actualización.
    • Instrucciones personalizadas: Para anulaciones de comportamiento específicas.
  3. Compruebe que el archivo se ha guardado y está en la ruta de acceso esperada: .github/upgrades/{scenarioId}/scenario-instructions.md.

Obtención de ayuda

Cuando algo no funciona según lo esperado:

  1. Pregunte al agente: Pregunte "¿Qué ha ido mal con la última tarea?" El agente a menudo puede explicar lo que ha ocurrido y sugerir los pasos siguientes.
  2. Revise el registro de ejecución: Abra execution-log.md en .github/upgrades/{scenarioId}/. El registro muestra un registro cronológico de lo que hizo el agente, incluidos los errores detectados por el agente.
  3. Informe de un problema: Si ha encontrado un error o el agente falla constantemente en algo, informe un problema en el repositorio de GitHub @modernize-dotnet.

Contenido relacionado

  • Last updated on