# Настраивайте рабочие процессы агента с помощью крючков

Запускайте автоматические проверки — такие как линтинг, форматирование или сканирование безопасности — в ключевые моменты выполнения агента для обеспечения соблюдения стандартов качества.

Хуки позволяют расширять и настраивать поведение GitHub Copilot агентов, выполняя пользовательские команды оболочки в ключевых точках выполнения агента. Для концептуального обзора крючков — включая детали доступных триггеров крюка — см. [О крючках для GitHub Copilot](/ru/copilot/concepts/agents/hooks).

## Создание крючка в репозитории на GitHub

1. Создайте новый `NAME.json` файл (где `NAME` описывается назначение файла) в `.github/hooks/` папке вашего репозитория.

   > \[!IMPORTANT]
   > Конфигурационный файл hooks **должен находиться** на стандартной ветке вашего репозитория, чтобы использовать Copilot cloud agent.

2. В вашем текстовом редакторе скопируйте и вставьте следующий шаблон крючка. Уберите все крючки, которые не планируете использовать, из массива `hooks` .

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

3. Настройте синтаксис крюка под `bash` клавишами и `powershell` или напрямую ссылайтесь на созданные вами скрипт-файлы.

   > \[!NOTE]
   > Включите клавишу `bash` (с скриптом для Linux и macOS) и клавишу `powershell` (для скрипта для Windows), чтобы хуки могли работать на всех трёх операционных системах.
   > Copilot использует соответствующий ключ в зависимости от операционной системы пользователя.

   * В этом примере запускается скрипт, который выводит дату начала сессии в файл журнала с помощью хука `sessionStart` :

     ```json copy
     "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
       }
     ],
     ```

   * Этот пример вызывает внешний `log-prompt` скрипт:

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

     Для полной информации о входном JSON из сессий агентов вместе с примерами скриптов см. [Ссылка на крючки GitHub Copilot](/ru/copilot/reference/hooks-reference).

4. Зафиксируйте файл в репозитории и объедините его в ветвь по умолчанию. Теперь ваши крючки будут работать во время сессий агентов.

## Troubleshooting

Если возникнут проблемы с крючками, используйте следующую таблицу для устранения неполадок.

| Проблема                | Действие                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Крючки не выполняются   | <ul><li>Проверьте, что JSON-файл находится в `.github/hooks/` каталоге.</li><li>Проверьте правильный синтаксис JSON (например, `jq .  hooks.json`).</li><li>Убедитесь `version: 1` , что указано в вашем `hooks.json` деле.</li><li>Проверьте, что скрипт, который вы вызываете с вашего хука, исполняемый (`chmod +x script.sh`)</li><li>Проверьте, есть ли у скрипта правильный shebang (например, `#!/bin/bash`)</li></ul> |
| Зацепки заканчиваются   | <ul><li>По умолчанию время ожидания составляет 30 секунд. При необходимости увеличивайте `timeoutSec` конфигурацию.</li><li>Оптимизируйте производительность скриптов, избегая ненужных операций.</li></ul>                                                                                                                                                                                                                   |
| Некорректный вывод JSON | <ul><li>Убедитесь, что выход находится на одной линии.</li><li>В Unix используйте `jq -c` для компакта и валидации JSON-вывода.</li><li>В Windows используйте команду `ConvertTo-Json -Compress` в PowerShell, чтобы сделать то же самое.</li></ul>                                                                                                                                                                           |

## Отладка

Вы можете отладить хуки следующими методами:

* **Включите подробное логирование** скрипта для проверки входных данных и трассировки выполнения скрипта.

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

* **Тестируйте хуки локально** , проводя тестовый вход в ваш хук для проверки его поведения:

  ```shell copy
  # 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 .
  ```

## Дополнительные материалы

* [Ссылка на крючки GitHub Copilot](/ru/copilot/reference/hooks-reference)
* [О облачном агенте GitHub Copilot](/ru/copilot/concepts/agents/cloud-agent/about-cloud-agent)
* [О GitHub Copilot CLI](/ru/copilot/concepts/agents/copilot-cli/about-copilot-cli)
* [Настройка среды разработки](/ru/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/customize-the-agent-environment)