Uso de enlaces con agentes de GitHub Copilot

Los ganchos permiten ampliar y personalizar el comportamiento de los agentes ejecutando comandos de shell personalizados en puntos clave durante la ejecución del agente. Para obtener información general conceptual sobre los enlaces, incluidos los detalles de los desencadenadores de enlace disponibles, consulte Acerca de los ganchos.

Creación de un enlace en un repositorio GitHub

1. Cree un nuevo hooks.json archivo con el nombre que prefiera en la .github/hooks/ carpeta del repositorio. El archivo de configuración de enlaces debe estar presente en la rama predeterminada del repositorio que va a usar agente en la nube de Copilot. Para CLI de GitHub Copilot, los hooks se cargan desde el directorio de trabajo actual.

2. En el editor de texto, copie y pegue la siguiente plantilla de enlace. Elimine los ganchos que no planee usar del hooks array.

   JSON

   {
     "version": 1,
     "hooks": {
       "sessionStart": [...],
       "sessionEnd": [...],
       "userPromptSubmitted": [...],
       "preToolUse": [...],
       "postToolUse": [...],
       "errorOccurred": [...]
     }
   }
   

3. Configure la sintaxis de hook en las claves bash o las powershell, o haga referencia directamente a los archivos de script que haya creado.

   • En este ejemplo, se ejecuta un script que registra la fecha de inicio de la sesión en un archivo de registro mediante el gancho sessionStart.

     JSON

     "sessionStart": [
       {
         "type": "command",
         "bash": "echo \"Session started: $(date)\" >> logs/session.log",
         "powershell": "Add-Content -Path logs/session.log -Value \"Session started: $(Get-Date)\"",
         "cwd": ".",
         "timeoutSec": 10
       }
     ],
     

   • En este ejemplo se llama a un script externo log-prompt :

     JSON

     "userPromptSubmitted": [
       {
         "type": "command",
         "bash": "./scripts/log-prompt.sh",
         "powershell": "./scripts/log-prompt.ps1",
         "cwd": "scripts",
         "env": {
           "LOG_LEVEL": "INFO"
         }
       }
     ],
     

     Para obtener una referencia completa sobre el JSON de entrada de las sesiones del agente junto con scripts de ejemplo, consulte Configuración de hooks.

4. Confirme el archivo en el repositorio y combítelo en la rama predeterminada. Tus ganchos se ejecutarán ahora durante las sesiones de los agentes.

Solución de problemas

Si tiene problemas al usar enlaces, use la tabla siguiente para solucionar problemas.

Cuestión	Acción
Los ganchos no se están ejecutando	Compruebe que el archivo JSON está en el .github/hooks/ directorio . Compruebe si hay sintaxis JSON válida (por ejemplo, jq . hooks.json). Asegúrese de que version: 1 está especificado en su archivo hooks.json. Compruebe que el script al que llama desde el enlace es ejecutable (chmod +x script.sh) Compruebe que el script tiene un shebang adecuado (por ejemplo, #!/bin/bash).
Los hooks se están agotando en tiempo de espera	El tiempo de expiración predeterminado es de 30 segundos. Aumente timeoutSec en la configuración si es necesario. Optimice el rendimiento del script evitando operaciones innecesarias.
Salida JSON no válida	Asegúrese de que la salida está en una sola línea. En Unix, use jq -c para compactar y validar la salida JSON. En Windows, use el comando ConvertTo-Json -Compress en PowerShell para hacer lo mismo.

Depuración

Puede depurar enlaces mediante los métodos siguientes:

•         **Habilite el registro detallado** en el script para inspeccionar los datos de entrada y trazar la ejecución del script.
  

  Shell

  #!/bin/bash
  set -x  # Enable bash debug mode
  INPUT=$(cat)
  echo "DEBUG: Received input" >&2
  echo "$INPUT" >&2
  # ... rest of script
  

•         **Pruebe los hooks localmente** canalizando los datos de prueba en su hook para validar su comportamiento:
  

  Shell

  # Create test input
  echo '{"timestamp":1704614400000,"cwd":"/tmp","toolName":"bash","toolArgs":"{\"command\":\"ls\"}"}' | ./my-hook.sh
  
  # Check exit code
  echo $?
  
  # Validate output is valid JSON
  ./my-hook.sh | jq .
  

Lectura adicional

• Para obtener más información sobre cómo configurar enlaces, consulte Configuración de hooks.
• Para obtener más información sobre agente en la nube de Copilot, vea Acerca de GitHub Copilot agente en la nube.
• Para obtener más información sobre CLI de GitHub Copilot, vea Acerca de GitHub Copilot CLI.
• Para obtener información sobre cómo personalizar el entorno del agente, consulte Personalización del entorno de desarrollo para GitHub Copilot agente en la nube.