# О крючках для GitHub Copilot

Расширяйте и настраивайте GitHub Copilot поведение агента, выполняя пользовательские команды оболочки в ключевых точках выполнения агента.

## Что такое крючки?

Хуки — это способ выполнения пользовательских команд shell в стратегических точках рабочего процесса агента, например, когда сессия агента начинается или заканчивается, когда вы вводите подстрымку или вызываете инструмент.

Хуки получают подробную информацию о действиях агентов через JSON-вход, что позволяет автоматизацию с учетом контекста. Например, вы можете использовать крючки, чтобы:

* Программно одобряйте или отклоняйте выполнение инструментов.
* Используйте встроенные функции безопасности, такие как секретное сканирование, чтобы предотвратить утечку учетных данных.
* Внедрить пользовательские правила валидации и вести журналы аудита на соответствие.

Крючки доступны для использования:

* **Copilot cloud agent** на GitHub.
* **GitHub Copilot CLI** в твоём терминале.

Вы определяете крючки в JSON-файлах, хранящихся в вашем репозитории по адресу `.github/hooks/*.json`. Они применяются встуда, когда Copilot агенты используются в репозитории.
Copilot CLI Также поддерживает личные крючки, которые вы храните в домашнем каталоге по `~/.copilot/hooks/*.json`адресу . Они применяются всякий раз, когда вы используете Copilot CLI.

## Типы крючков

Доступны следующие типы крючков:

* **sessionStart**: выполняется при начале новой сессии агента или возобновлении существующей сессии. Может использоваться для инициализации среды, запуска сессий для аудита, проверки состояния project и настройки временных ресурсов.
* **sessionEnd**: Выполняется после завершения или завершения сессии агента. Можно использовать для очистки временных ресурсов, генерации и архивирования отчётов и журналов сессий, а также для отправки уведомлений о завершении сессии.
* **userPromptSubmitted**: Выполняется, когда пользователь отправляет запрос агенту. Может использоваться для регистрации запросов пользователей на аудит и анализ использования.
* **preToolUse**: Выполняется до того, как агент использует любой инструмент (например`bash`, , `edit`). `view` Это самый мощный крючок, так как он может **одобрять или отклонять выполнение инструментов**. Используйте этот крючок для блокировки опасных команд, обеспечения политики безопасности и стандартов кода, необходимости одобрения для конфиденциальных операций или логирования использования инструмента для соответствия.
* **postToolUse**: выполняется после завершения выполнения инструмента (независимо от того, был ли он успешным или неудачным). Можно использовать для ведения результатов выполнения, отслеживания статистики использования, создания аудиторских следов, мониторинга показателей производительности и отправки оповещений о сбоях.
* **agentStop**: Выполняется, когда основной агент завершил ответ на ваш запрос.
* **subagentStop**: выполняется после завершения субагента, перед возвращением результатов родительскому агенту.
* **errorOccurled**: Выполняется при возникновении ошибки во время выполнения агента. Можно использовать для регистрации ошибок при отладке, отправки уведомлений, отслеживания ошибок и генерации отчетов.

Чтобы увидеть полный справочник по типам хуков с примерами применения, лучшими практиками и продвинутыми шаблонами, см. [Ссылка на крючки GitHub Copilot](/ru/copilot/reference/hooks-reference).

## Формат конфигурации крючка

Вы настраиваете хуки с помощью специального формата JSON. JSON должен содержать `version` поле со значением `1` , а `hooks` объект с массивами определений крючков.

```json copy
{
  "version": 1,
  "hooks": {
    "sessionStart": [
      {
        "type": "command",
        "bash": "string (optional)",
        "powershell": "string (optional)",
        "cwd": "string (optional)",
        "env": { "KEY": "value" },
        "timeoutSec": 30
      }
    ],
  }
}
```

Объект крючка может содержать следующие клавиши:

| Недвижимость | Обязательный          | Description                                                                 |
| ------------ | --------------------- | --------------------------------------------------------------------------- |
| `type`       | Да                    | Должен содержать значение `"command"`.                                      |
| `bash`       | Да (на Unix-системах) | Путь к bash-скрипту для выполнения                                          |
| `powershell` | Да (на Windows)       | Путь к скрипту PowerShell для выполнения                                    |
| `cwd`        | Нет                   | Рабочая директория скрипта (относительно корня репозитория)                 |
| `env`        | Нет                   | Дополнительные переменные среды, которые объединяются с существующей средой |
| `timeoutSec` | Нет                   | Максимальное время выполнения в секундах (по умолчанию: 30)                 |

## Пример конфигурационного файла крючка

Это пример конфигурационного файла, который находится в `~/.github/hooks/project-hooks.json` внутри репозитория.

```json copy
{
  "version": 1,
  "hooks": {
    "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
      }
    ],
    "userPromptSubmitted": [
      {
        "type": "command",
        "bash": "./scripts/log-prompt.sh",
        "powershell": "./scripts/log-prompt.ps1",
        "cwd": "scripts",
        "env": {
          "LOG_LEVEL": "INFO"
        }
      }
    ],
    "preToolUse": [
      {
        "type": "command",
        "bash": "./scripts/security-check.sh",
        "powershell": "./scripts/security-check.ps1",
        "cwd": "scripts",
        "timeoutSec": 15
      },
      {
        "type": "command",
        "bash": "./scripts/log-tool-use.sh",
        "powershell": "./scripts/log-tool-use.ps1",
        "cwd": "scripts"
      }
    ],
    "postToolUse": [
      {
        "type": "command",
        "bash": "cat >> logs/tool-results.jsonl",
        "powershell": "$input | Add-Content -Path logs/tool-results.jsonl"
      }
    ],
    "sessionEnd": [
      {
        "type": "command",
        "bash": "./scripts/cleanup.sh",
        "powershell": "./scripts/cleanup.ps1",
        "cwd": "scripts",
        "timeoutSec": 60
      }
    ]
  }
}
```

## Вопросы производительности

Хуки работают синхронно и блокируют выполнение агентов. Чтобы обеспечить оперативный опыт, учитывайте следующие моменты:

* **Минимизировать время выполнения**: по возможности ограничивайте время выполнения хука менее 5 секунд.
* **Оптимизируйте логирование**: используйте асинхронное логирование, например, добавление в файлы, вместо синхронного ввода-вывода.
* **Используйте фоновую обработку**: для дорогих операций рассмотрите фоновую обработку.
* **Результаты кэша**: кэшировать дорогие вычисления, когда это возможно.

## Вопросы безопасности

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

* **Всегда проверяйте и дезинфицируйте данные, обработанные крючками**. Ненадёжный ввод может привести к неожиданному поведению.
* **Используйте правильное выход из оболочки при построении команд**. Это предотвращает уязвимости инъекции команд.
* **Никогда не записывайте конфиденциальные данные, такие как токены или пароли**.
* **Убедитесь, что скрипты и логи крючков имеют соответствующие права**.
* **Будьте осторожны с крючками, которые совершают внешние сетевые звонки**. Они могут вызывать задержки, сбои или раскрывать данные третьим лицам.
* **Устанавливайте соответствующие тайм-ауты, чтобы предотвратить истощение ресурсов**. Долгосрочные крючки могут блокировать работу агентов и снижать производительность.

## Дальнейшие действия

Чтобы начать создавать крючки, см.:

* [Настраивайте рабочие процессы агента с помощью крючков](/ru/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/use-hooks) для Copilot cloud agent
* [Использование крючков с GitHub Copilot CLI](/ru/copilot/how-tos/copilot-cli/customize-copilot/use-hooks) для GitHub Copilot CLI