Крючки для GitHub Copilot

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

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

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

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

В отличие от пользовательских инструкций, перехватчики выполняют код, а не запрашивают модель для выполнения правила. Например, перехватчик может запустить скрипт, который проверяет запрос средства перед выполнением.

Где можно использовать крючки

Крючки доступны в:

, GitHub Copilot app который поддерживает перехватчики репозитория и перехватчики, предоставляемые подключаемыми модулями. См . раздел AUTOTITLE.
GitHub Copilot CLI, где команды выполняются в среде выполнения.
Copilot cloud agent, где команды выполняются в облачной среде агента. Поддерживается только подмножество событий.
Visual Studio Code, где находится Публичный предварительный просмотропыт крючка. Поддерживаемые события и конфигурация зависят от агента, выполняемого сеансом. См. перехватчики агента в VS Code.

В приведенной ниже конфигурации и примерах описаны перехватчики для Copilot CLI и Copilot cloud agent. Не предполагайте, что одни и те же события, входные или выходные данные работают без изменений между поверхностями.

Для Copilot CLI и Copilot cloud agent, вы можете определить перехватчики репозитория в .github/hooks/*.json. Copilot CLI также поддерживает личные крючки в ~/.copilot/hooks/*.json. Сведения о средах выполнения, дополнительных расположениях и поддержке событий см. в разделе Ссылка на крючки GitHub Copilot.

Типы крючков

Это примеры Copilot CLI событий перехватчика. Copilot cloud agent поддерживает подмножество:

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

Ссылка на перехватчики содержит полный набор событий и их доступность.Copilot cloud agent

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

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

JSON

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

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

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

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

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

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

JSON

{
  "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
      }
    ]
  }
}

{
  "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 секунд.
Оптимизируйте логирование: используйте асинхронное логирование, например, добавление в файлы, вместо синхронного ввода-вывода.
Используйте фоновую обработку: для дорогих операций рассмотрите фоновую обработку.
Результаты кэша: кэшировать дорогие вычисления, когда это возможно.

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

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

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

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

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

Настраивайте рабочие процессы агента с помощью крючков для Copilot cloud agent
Использование крючков с GitHub Copilot CLI для GitHub Copilot CLI

В этой статье