Usando ganchos com CLI do GitHub Copilot

Os ganchos permitem estender e personalizar o comportamento dos agentes executando comandos de shell personalizados em pontos-chave durante a execução do GitHub Copilot agente. Para obter uma visão geral conceitual dos ganchos, incluindo detalhes dos gatilhos disponíveis para os ganchos, consulte Sobre ganchos para GitHub Copilot.

Pré-requisito

Para Windows only: Os exemplos neste artigo usam o PowerShell. Se você estiver usando Windows, deverá ter o PowerShell 7.0 ou posterior instalado e em seu PATH. Você pode verificar sua versão do PowerShell em execução pwsh --version em um terminal. Para instalar o PowerShell, execute winget install Microsoft.PowerShell, em seguida, reinicie o terminal.

Criando um gancho em nível de repositório

1. Crie um novo NAME.json arquivo (em que NAME descreve a finalidade do arquivo) na .github/hooks/ pasta do repositório.

2. No editor de texto, copie e cole o modelo de gancho a seguir. Remova os ganchos que você não planeja usar da hooks matriz.

   JSON

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

3. Configure a sintaxe do gancho nos campos das chaves bash e powershell, ou referencie diretamente os arquivos de script que você criou.

   Observação

   Inclua uma chave bash (com um script para Linux e macOS) e uma chave powershell (para um script para Windows) para permitir que os ganchos sejam executados em todos os três sistemas operacionais. Copilot usa a chave apropriada com base no sistema operacional do usuário.

   • Este exemplo executa um script que gera a data de início da sessão para um arquivo de log usando o sessionStart gancho:

     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
       }
     ],
     

   • Este exemplo chama um 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 obter uma referência completa do JSON de entrada das sessões de agente, juntamente com scripts de exemplo, consulte Referência dos hooks do GitHub Copilot.

4. Confirme o arquivo no repositório e faça a mesclagem na ramificação padrão. Agora, os ganchos serão executados durante as sessões do agente.

Criando um hook de nível de usuário

Os ganchos no nível do usuário são configurados como ganchos no nível do repositório, mas os arquivos de gancho são armazenados localmente, abaixo do diretório base.

Os exemplos a seguir para macOS e Windows mostram como configurar ganchos que reproduzirão um som e exibirão uma caixa de mensagem quando a CLI terminar de responder a um prompt e quando você sair CLI do Copilot. Os ganchos para Linux seriam semelhantes ao exemplo do macOS, mas usariam ferramentas do Linux para reproduzir sons e exibir mensagens.

Exemplo de nível de usuário para macOS

1. Crie um arquivo chamado notification-hooks.json em ~/.copilot/hooks/.

   Observação

   Se COPILOT_HOME estiver definido, crie o arquivo em $COPILOT_HOME/hooks/.

2. Copie e cole o seguinte JSON no arquivo:

   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. Iniciar ou reiniciar. CLI do Copilot

   Observação

   As alterações nas configurações de gancho são carregadas quando a CLI é iniciada.

4. Insira um prompt e verifique se você ouve um som e vê uma caixa de mensagem quando o agente termina de responder e quando você sai da CLI.

5. Exclua o notification-hooks.json arquivo para remover esses ganchos.

Exemplo de nível de usuário para Windows

1. Crie um arquivo chamado notification-hooks.json em %USERPROFILE%\.copilot\hooks\.

   Observação

   Se COPILOT_HOME estiver definido, crie o arquivo em %COPILOT_HOME%\hooks\.

2. Copie e cole o seguinte JSON no arquivo:

   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. Iniciar ou reiniciar. CLI do Copilot

   Observação

   As alterações nas configurações de gancho são carregadas quando a CLI é iniciada.

4. Insira um prompt e verifique se você ouve um som e vê uma caixa de mensagem quando o agente termina de responder e quando você sai da CLI.

5. Exclua o notification-hooks.json arquivo para remover esses ganchos.

Resolução de problemas

Se você encontrar problemas ao usar hooks, utilize a tabela a seguir para solucioná-los.

Questão	Ação
Os ganchos não estão sendo executados	Verifique se o arquivo JSON está no .github/hooks/ diretório. Verifique se há uma sintaxe JSON válida (por exemplo, jq . hooks.json). Verifique se version: 1 está especificado em seu hooks.json arquivo. Verifique se o script chamado pelo gancho é executável (chmod +x script.sh) Verifique se o script tem um shebang adequado (por exemplo, #!/bin/bash)
Ganchos estão atingindo o tempo limite	O tempo limite padrão é 30 segundos. Aumente timeoutSec na configuração, se necessário. Otimize o desempenho do script evitando operações desnecessárias.
Saída JSON inválida	Verifique se a saída está em uma única linha. No Unix, use jq -c para compactar e validar a saída JSON. Em Windows, use o comando ConvertTo-Json -Compress no PowerShell para fazer o mesmo.

Resolução de Erros

Você pode depurar ganchos usando os seguintes métodos:

• Habilite o log detalhado no script para inspecionar os dados de entrada e rastrear a execução do script.

  Shell

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

• Teste ganchos localmente canalizando a entrada de teste para o seu gancho para validar seu comportamento.

  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 .
  

Leitura adicional

• Referência dos hooks do GitHub Copilot
• Sobre o agente de nuvem do GitHub Copilot
• Sobre GitHub Copilot CLI
• Configurar o ambiente de desenvolvimento