Uso de enlaces con CLI 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 para GitHub Copilot.

Prerrequisito

For Windows only: Los ejemplos de este artículo usan PowerShell. Si usas Windows, debes tener instalado PowerShell 7.0 o una versión posterior y en la variable PATH. Puede comprobar la versión de PowerShell mediante la ejecución pwsh --version en un terminal. Para instalar PowerShell, ejecute winget install Microsoft.PowerShell reinicie el terminal.

Creación de un enlace de nivel de repositorio

1. Cree un nuevo NAME.json archivo (donde NAME describe el propósito del archivo) en la .github/hooks/ carpeta del repositorio.

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 y powershell, o hacer referencia directamente a los archivos de script que ha creado.

   Nota:

   Incluya una clave de bash (con un script para Linux y macOS) y una clave de powershell (para un script para Windows) para permitir que los enlaces se ejecuten en los tres sistemas operativos. Copilot usa la clave adecuada en función del sistema operativo del usuario.

   • 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 Referencia de enlaces de GitHub Copilot.

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

Creación de un enlace de nivel de usuario

Los enlaces de nivel de usuario se configuran igual que los enlaces de nivel de repositorio, pero los archivos de enlace se almacenan localmente, debajo del directorio principal.

Los siguientes ejemplos para macOS y Windows muestran cómo configurar ganchos que reproduzcan un sonido y muestren un cuadro de diálogo cuando la CLI termine de responder a una solicitud y cuando salga de CLI de Copilot. Los enlaces para Linux serían similares al ejemplo de macOS, pero usarían herramientas de Linux para reproducir sonidos y mostrar mensajes.

Ejemplo de nivel de usuario para macOS

1. Cree un archivo denominado notification-hooks.json en ~/.copilot/hooks/.

   Nota:

   Si COPILOT_HOME se establece, cree el archivo en $COPILOT_HOME/hooks/.

2. Copie y pegue el siguiente JSON en el archivo:

   JSON

   {
     "version": 1,
     "hooks": {
       "agentStop": [
         {
           "type": "command",
           "bash": "osascript -e 'do shell script \"afplay /System/Library/Sounds/Funk.aiff &> /dev/null &\"' -e 'display dialog \"Agent stopped.\" with title \"Hook-generated message\" buttons {\"OK\"} default button \"OK\"'",
           "timeoutSec": 5
         }
       ],
       "sessionEnd": [
         {
           "type": "command",
           "bash": "osascript -e 'do shell script \"afplay /System/Library/Sounds/Funk.aiff &> /dev/null &\"' -e 'display dialog \"Session ended.\" with title \"Hook-generated message\" buttons {\"OK\"} default button \"OK\"'",
           "timeoutSec": 5
         }
       ]
     }
   }
   

3. Inicie, o reinicie, CLI de Copilot.

   Nota:

   Los cambios en las configuraciones de enlace se cargan cuando se inicia la CLI.

4. Ingrese un aviso y compruebe que escucha un sonido y ve un cuadro de mensaje cuando el agente termina de responder y cuando salga de la CLI.

5. Elimine el notification-hooks.json archivo para quitar estos enlaces.

Ejemplo de nivel de usuario para Windows

1. Cree un archivo denominado notification-hooks.json en %USERPROFILE%\.copilot\hooks\.

   Nota:

   Si COPILOT_HOME está establecido, cree el archivo en %COPILOT_HOME%\hooks\.

2. Copie y pegue el siguiente JSON en el archivo:

   JSON

   {
     "version": 1,
     "hooks": {
       "agentStop": [
         {
           "type": "command",
           "powershell": "Add-Type -AssemblyName System.Windows.Forms; [System.Media.SystemSounds]::Asterisk.Play(); [System.Windows.Forms.MessageBox]::Show('Agent stopped.', 'Hook-generated message') | Out-Null",
           "timeoutSec": 5
         }
       ],
       "sessionEnd": [
         {
           "type": "command",
           "powershell": "Add-Type -AssemblyName System.Windows.Forms; [System.Media.SystemSounds]::Asterisk.Play(); [System.Windows.Forms.MessageBox]::Show('Session ended.', 'Hook-generated message') | Out-Null",
           "timeoutSec": 5
         }
       ]
     }
   }
   

3. Inicie, o reinicie, CLI de Copilot.

   Nota:

   Los cambios en las configuraciones de enlace se cargan cuando se inicia la CLI.

4. Ingrese un aviso y compruebe que escucha un sonido y ve un cuadro de mensaje cuando el agente termina de responder y cuando salga de la CLI.

5. Elimine el notification-hooks.json archivo para quitar estos enlaces.

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

• Referencia de enlaces de GitHub Copilot
• Acerca de GitHub Copilot agente en la nube
• Acerca de GitHub Copilot CLI
• Configuración del entorno de desarrollo