{"meta":{"title":"О крючках для GitHub Copilot","intro":"Расширяйте и настраивайте GitHub Copilot поведение агента, выполняя пользовательские команды оболочки в ключевых точках выполнения агента.","product":"GitHub Copilot","breadcrumbs":[{"href":"/ru/copilot","title":"GitHub Copilot"},{"href":"/ru/copilot/concepts","title":"Основные понятия"},{"href":"/ru/copilot/concepts/agents","title":"Агенты"},{"href":"/ru/copilot/concepts/agents/hooks","title":"Хуки"}],"documentType":"article"},"body":"# О крючках для GitHub Copilot\n\nРасширяйте и настраивайте GitHub Copilot поведение агента, выполняя пользовательские команды оболочки в ключевых точках выполнения агента.\n\n## Что такое крючки?\n\nХуки — это способ выполнения пользовательских команд shell в стратегических точках рабочего процесса агента, например, когда сессия агента начинается или заканчивается, когда вы вводите подстрымку или вызываете инструмент.\n\nХуки получают подробную информацию о действиях агентов через JSON-вход, что позволяет автоматизацию с учетом контекста. Например, вы можете использовать крючки, чтобы:\n\n* Программно одобряйте или отклоняйте выполнение инструментов.\n* Используйте встроенные функции безопасности, такие как секретное сканирование, чтобы предотвратить утечку учетных данных.\n* Внедрить пользовательские правила валидации и вести журналы аудита на соответствие.\n\nКрючки доступны для использования:\n\n* **Copilot cloud agent** на GitHub.\n* **GitHub Copilot CLI** в твоём терминале.\n\nВы определяете крючки в JSON-файлах, хранящихся в вашем репозитории по адресу `.github/hooks/*.json`. Они применяются встуда, когда Copilot агенты используются в репозитории.\nCopilot CLI Также поддерживает личные крючки, которые вы храните в домашнем каталоге по `~/.copilot/hooks/*.json`адресу . Они применяются всякий раз, когда вы используете Copilot CLI.\n\n## Типы крючков\n\nДоступны следующие типы крючков:\n\n* **sessionStart**: выполняется при начале новой сессии агента или возобновлении существующей сессии. Может использоваться для инициализации среды, запуска сессий для аудита, проверки состояния project и настройки временных ресурсов.\n* **sessionEnd**: Выполняется после завершения или завершения сессии агента. Можно использовать для очистки временных ресурсов, генерации и архивирования отчётов и журналов сессий, а также для отправки уведомлений о завершении сессии.\n* **userPromptSubmitted**: Выполняется, когда пользователь отправляет запрос агенту. Может использоваться для регистрации запросов пользователей на аудит и анализ использования.\n* **preToolUse**: Выполняется до того, как агент использует любой инструмент (например`bash`, , `edit`). `view` Это самый мощный крючок, так как он может **одобрять или отклонять выполнение инструментов**. Используйте этот крючок для блокировки опасных команд, обеспечения политики безопасности и стандартов кода, необходимости одобрения для конфиденциальных операций или логирования использования инструмента для соответствия.\n* **postToolUse**: выполняется после завершения выполнения инструмента (независимо от того, был ли он успешным или неудачным). Можно использовать для ведения результатов выполнения, отслеживания статистики использования, создания аудиторских следов, мониторинга показателей производительности и отправки оповещений о сбоях.\n* **agentStop**: Выполняется, когда основной агент завершил ответ на ваш запрос.\n* **subagentStop**: выполняется после завершения субагента, перед возвращением результатов родительскому агенту.\n* **errorOccurled**: Выполняется при возникновении ошибки во время выполнения агента. Можно использовать для регистрации ошибок при отладке, отправки уведомлений, отслеживания ошибок и генерации отчетов.\n\nЧтобы увидеть полный справочник по типам хуков с примерами применения, лучшими практиками и продвинутыми шаблонами, см. [Ссылка на крючки GitHub Copilot](/ru/copilot/reference/hooks-reference).\n\n## Формат конфигурации крючка\n\nВы настраиваете хуки с помощью специального формата JSON. JSON должен содержать `version` поле со значением `1` , а `hooks` объект с массивами определений крючков.\n\n```json copy\n{\n  \"version\": 1,\n  \"hooks\": {\n    \"sessionStart\": [\n      {\n        \"type\": \"command\",\n        \"bash\": \"string (optional)\",\n        \"powershell\": \"string (optional)\",\n        \"cwd\": \"string (optional)\",\n        \"env\": { \"KEY\": \"value\" },\n        \"timeoutSec\": 30\n      }\n    ],\n  }\n}\n```\n\nОбъект крючка может содержать следующие клавиши:\n\n| Недвижимость | Обязательный          | Description                                                                 |\n| ------------ | --------------------- | --------------------------------------------------------------------------- |\n| `type`       | Да                    | Должен содержать значение `\"command\"`.                                      |\n| `bash`       | Да (на Unix-системах) | Путь к bash-скрипту для выполнения                                          |\n| `powershell` | Да (на Windows)       | Путь к скрипту PowerShell для выполнения                                    |\n| `cwd`        | Нет                   | Рабочая директория скрипта (относительно корня репозитория)                 |\n| `env`        | Нет                   | Дополнительные переменные среды, которые объединяются с существующей средой |\n| `timeoutSec` | Нет                   | Максимальное время выполнения в секундах (по умолчанию: 30)                 |\n\n## Пример конфигурационного файла крючка\n\nЭто пример конфигурационного файла, который находится в `~/.github/hooks/project-hooks.json` внутри репозитория.\n\n```json copy\n{\n  \"version\": 1,\n  \"hooks\": {\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    \"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    \"preToolUse\": [\n      {\n        \"type\": \"command\",\n        \"bash\": \"./scripts/security-check.sh\",\n        \"powershell\": \"./scripts/security-check.ps1\",\n        \"cwd\": \"scripts\",\n        \"timeoutSec\": 15\n      },\n      {\n        \"type\": \"command\",\n        \"bash\": \"./scripts/log-tool-use.sh\",\n        \"powershell\": \"./scripts/log-tool-use.ps1\",\n        \"cwd\": \"scripts\"\n      }\n    ],\n    \"postToolUse\": [\n      {\n        \"type\": \"command\",\n        \"bash\": \"cat >> logs/tool-results.jsonl\",\n        \"powershell\": \"$input | Add-Content -Path logs/tool-results.jsonl\"\n      }\n    ],\n    \"sessionEnd\": [\n      {\n        \"type\": \"command\",\n        \"bash\": \"./scripts/cleanup.sh\",\n        \"powershell\": \"./scripts/cleanup.ps1\",\n        \"cwd\": \"scripts\",\n        \"timeoutSec\": 60\n      }\n    ]\n  }\n}\n```\n\n## Вопросы производительности\n\nХуки работают синхронно и блокируют выполнение агентов. Чтобы обеспечить оперативный опыт, учитывайте следующие моменты:\n\n* **Минимизировать время выполнения**: по возможности ограничивайте время выполнения хука менее 5 секунд.\n* **Оптимизируйте логирование**: используйте асинхронное логирование, например, добавление в файлы, вместо синхронного ввода-вывода.\n* **Используйте фоновую обработку**: для дорогих операций рассмотрите фоновую обработку.\n* **Результаты кэша**: кэшировать дорогие вычисления, когда это возможно.\n\n## Вопросы безопасности\n\nЧтобы обеспечить безопасность при использовании крючков, учитывайте следующие моменты:\n\n* **Всегда проверяйте и дезинфицируйте данные, обработанные крючками**. Ненадёжный ввод может привести к неожиданному поведению.\n* **Используйте правильное выход из оболочки при построении команд**. Это предотвращает уязвимости инъекции команд.\n* **Никогда не записывайте конфиденциальные данные, такие как токены или пароли**.\n* **Убедитесь, что скрипты и логи крючков имеют соответствующие права**.\n* **Будьте осторожны с крючками, которые совершают внешние сетевые звонки**. Они могут вызывать задержки, сбои или раскрывать данные третьим лицам.\n* **Устанавливайте соответствующие тайм-ауты, чтобы предотвратить истощение ресурсов**. Долгосрочные крючки могут блокировать работу агентов и снижать производительность.\n\n## Дальнейшие действия\n\nЧтобы начать создавать крючки, см.:\n\n* [Настраивайте рабочие процессы агента с помощью крючков](/ru/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/use-hooks) для Copilot cloud agent\n* [Использование крючков с GitHub Copilot CLI](/ru/copilot/how-tos/copilot-cli/customize-copilot/use-hooks) для GitHub Copilot CLI"}