{"meta":{"title":"Usando ganchos com GitHub Copilot CLI","intro":"Estenda o comportamento do agente GitHub Copilot usando comandos de shell personalizados em pontos-chave durante a execução do agente.","product":"GitHub Copilot","breadcrumbs":[{"href":"/pt/enterprise-cloud@latest/copilot","title":"GitHub Copilot"},{"href":"/pt/enterprise-cloud@latest/copilot/how-tos","title":"Instruções"},{"href":"/pt/enterprise-cloud@latest/copilot/how-tos/copilot-cli","title":"Copilot CLI"},{"href":"/pt/enterprise-cloud@latest/copilot/how-tos/copilot-cli/customize-copilot","title":"Personalizar Copilot CLI"},{"href":"/pt/enterprise-cloud@latest/copilot/how-tos/copilot-cli/customize-copilot/use-hooks","title":"Usar ganchos"}],"documentType":"article"},"body":"# Usando ganchos com GitHub Copilot CLI\n\nEstenda o comportamento do agente GitHub Copilot usando comandos de shell personalizados em pontos-chave durante a execução do agente.\n\nOs 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](/pt/enterprise-cloud@latest/copilot/concepts/agents/hooks).\n\n## Pré-requisito\n\n**Somente para usuários do Windows:** Os hooks de exemplo neste artigo foram projetados para ser executados no Windows, Linux e macOS. Para Windows, eles usam o PowerShell e exigem que você tenha 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.\n\n## Criando um gancho em nível de repositório\n\n1. Crie um novo `NAME.json` arquivo (em que `NAME` descreve a finalidade do arquivo) na `.github/hooks/` pasta do repositório.\n\n2. 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.\n\n ```json copy\n {\n \"version\": 1,\n \"hooks\": {\n \"sessionStart\": [...],\n \"sessionEnd\": [...],\n \"userPromptSubmitted\": [...],\n \"preToolUse\": [...],\n \"postToolUse\": [...],\n \"errorOccurred\": [...]\n }\n }\n ```\n\n3. Configure a sintaxe do gancho nos campos das chaves `bash` e `powershell`, ou referencie diretamente os arquivos de script que você criou.\n\n > \\[!NOTE]\n > 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.\n > Copilot usa a chave apropriada com base no sistema operacional do usuário.\n\n * Este exemplo executa um script que gera a data de início da sessão para um arquivo de log usando o `sessionStart` gancho:\n\n ```json copy\n \"sessionStart\": [\n {\n \"type\": \"command\",\n \"bash\": \"echo \\\"Session started: $(date)\\\" >> logs/session.log\",\n \"powershell\": \"Add-Content -Path logs/session.log -Value \\\"Session started: $(Get-Date)\\\"\",\n \"cwd\": \".\",\n \"timeoutSec\": 10\n }\n ],\n ```\n\n * Este exemplo chama um script externo `log-prompt`:\n\n ```json copy\n \"userPromptSubmitted\": [\n {\n \"type\": \"command\",\n \"bash\": \"./scripts/log-prompt.sh\",\n \"powershell\": \"./scripts/log-prompt.ps1\",\n \"cwd\": \"scripts\",\n \"env\": {\n \"LOG_LEVEL\": \"INFO\"\n }\n }\n ],\n ```\n\n Para obter uma referência completa do JSON de entrada das sessões de agente, juntamente com scripts de exemplo, consulte [Referência de ganchos do GitHub Copilot](/pt/enterprise-cloud@latest/copilot/reference/hooks-reference).\n\n4. 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.\n\n## Criando um hook de nível de usuário\n\nOs 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.\n\nOs 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 Copilot CLI. Os ganchos para Linux seriam semelhantes ao exemplo do macOS, mas usariam ferramentas do Linux para reproduzir sons e exibir mensagens.\n\n### Exemplo de nível de usuário para macOS\n\n1. Crie um arquivo chamado `notification-hooks.json` em `~/.copilot/hooks/`.\n\n > \\[!NOTE]\n > Se `COPILOT_HOME` estiver definido, crie o arquivo em `$COPILOT_HOME/hooks/`.\n\n2. Copie e cole o seguinte JSON no arquivo:\n\n ```json copy\n {\n \"version\": 1,\n \"hooks\": {\n \"agentStop\": [\n {\n \"type\": \"command\",\n \"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\\\"'\",\n \"timeoutSec\": 5\n }\n ],\n \"sessionEnd\": [\n {\n \"type\": \"command\",\n \"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\\\"'\",\n \"timeoutSec\": 5\n }\n ]\n }\n }\n ```\n\n3. Iniciar ou reiniciar. Copilot CLI\n\n > \\[!NOTE]\n > As alterações nas configurações de gancho são carregadas quando a CLI é iniciada.\n\n4. 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.\n\n5. Exclua o `notification-hooks.json` arquivo para remover esses ganchos.\n\n### Exemplo de nível de usuário para Windows\n\n1. Crie um arquivo chamado `notification-hooks.json` em `%USERPROFILE%\\.copilot\\hooks\\`.\n\n > \\[!NOTE]\n > Se `COPILOT_HOME` estiver definido, crie o arquivo em `%COPILOT_HOME%\\hooks\\`.\n\n2. Copie e cole o seguinte JSON no arquivo:\n\n ```json copy\n {\n \"version\": 1,\n \"hooks\": {\n \"agentStop\": [\n {\n \"type\": \"command\",\n \"powershell\": \"Add-Type -AssemblyName System.Windows.Forms; [System.Media.SystemSounds]::Asterisk.Play(); [System.Windows.Forms.MessageBox]::Show('Agent stopped.', 'Hook-generated message') | Out-Null\",\n \"timeoutSec\": 5\n }\n ],\n \"sessionEnd\": [\n {\n \"type\": \"command\",\n \"powershell\": \"Add-Type -AssemblyName System.Windows.Forms; [System.Media.SystemSounds]::Asterisk.Play(); [System.Windows.Forms.MessageBox]::Show('Session ended.', 'Hook-generated message') | Out-Null\",\n \"timeoutSec\": 5\n }\n ]\n }\n }\n ```\n\n3. Iniciar ou reiniciar. Copilot CLI\n\n > \\[!NOTE]\n > As alterações nas configurações de gancho são carregadas quando a CLI é iniciada.\n\n4. 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.\n\n5. Exclua o `notification-hooks.json` arquivo para remover esses ganchos.\n\n## Resolução de problemas\n\nSe você encontrar problemas ao usar hooks, utilize a tabela a seguir para solucioná-los.\n\n| Questão | Ação |\n| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| Os ganchos não estão sendo executados | |\n| Ganchos estão atingindo o tempo limite | |\n| Saída JSON inválida | |\n\n## Resolução de Erros\n\nVocê pode depurar ganchos usando os seguintes métodos:\n\n* **Habilite o log detalhado** no script para inspecionar os dados de entrada e rastrear a execução do script.\n\n ```shell copy\n #!/bin/bash\n set -x # Enable bash debug mode\n INPUT=$(cat)\n echo \"DEBUG: Received input\" >&2\n echo \"$INPUT\" >&2\n # ... rest of script\n ```\n\n* **Teste ganchos localmente** canalizando a entrada de teste para o seu gancho para validar seu comportamento.\n\n ```shell copy\n # Create test input\n echo '{\"timestamp\":1704614400000,\"cwd\":\"/tmp\",\"toolName\":\"bash\",\"toolArgs\":\"{\\\"command\\\":\\\"ls\\\"}\"}' | ./my-hook.sh\n\n # Check exit code\n echo $?\n\n # Validate output is valid JSON\n ./my-hook.sh | jq .\n ```\n\n## Leitura adicional\n\n* [Referência de ganchos do GitHub Copilot](/pt/enterprise-cloud@latest/copilot/reference/hooks-reference)\n* [Sobre o agente de nuvem do GitHub Copilot](/pt/enterprise-cloud@latest/copilot/concepts/agents/cloud-agent/about-cloud-agent)\n* [Sobre GitHub Copilot CLI](/pt/enterprise-cloud@latest/copilot/concepts/agents/copilot-cli/about-copilot-cli)\n* [Configurar o ambiente de desenvolvimento](/pt/enterprise-cloud@latest/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/customize-the-agent-environment)"}