Использование крючков с GitHub Copilot CLI

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

В этой статье

Хуки позволяют расширять и настраивать поведение GitHub Copilot агентов, выполняя пользовательские команды оболочки в ключевых точках выполнения агента. Для концептуального обзора крючков — включая детали доступных триггеров крюка — см. О крючках для GitHub Copilot.

Предпосылка

Только для Windows: Примеры в этой статье используют PowerShell. Если вы используете Windows, у вас должен быть установлен PowerShell 7.0 или выше в вашем PATH. Вы можете проверить версию для PowerShell, запустив pwsh --version в терминале. Чтобы установить PowerShell, запустите winget install Microsoft.PowerShell затем перезагрузите терминал.

Создание крючка уровня репозитория

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

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

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

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

    Примечание.

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

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

      JSON
      "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
      "userPromptSubmitted": [
  {
    "type": "command",
    "bash": "./scripts/log-prompt.sh",
    "powershell": "./scripts/log-prompt.ps1",
    "cwd": "scripts",
    "env": {
      "LOG_LEVEL": "INFO"
    }
  }
],

      Для полной информации о входном JSON из сессий агентов вместе с примерами скриптов см. Ссылка на крючки GitHub Copilot.

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

Создание хука на уровне пользователя

Хуки пользовательского уровня настроены так же, как и хуки на уровне репозитория, но файлы хуков хранятся локально, под вашей домашней директорией.

Следующие примеры для macOS и Windows показывают, как настроить крючки, которые воспроизводят звук и отображают окно сообщений, когда CLI завершает ответ на запрос и когда вы выходите из Второй пилот CLI. Крючки для Linux будут похожи на пример с macOS, но используют инструменты Linux для воспроизведения звуков и отображения сообщений.

Пример на уровне пользователя для macOS

  1. Создайте файл с позывом notification-hooks.json в ~/.copilot/hooks/.

    Примечание.

    Если COPILOT_HOME установлено, создайте файл в $COPILOT_HOME/hooks/.

  2. Скопируйте и вставьте следующий код JSON в файл:

    JSON
    {
  "version": 1,
  "hooks": {
    "agentStop": [
      {
        "type": "command",
        "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\"'",
        "timeoutSec": 5
      }
    ],
    "sessionEnd": [
      {
        "type": "command",
        "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\"'",
        "timeoutSec": 5
      }
    ]
  }
}

  3. Запустить или перезапустить. Второй пилот CLI

    Примечание.

    Изменения в конфигурации крюков загружаются при запуске CLI.

  4. Введите запрос и проверьте, слышите ли вы звук и видите окно сообщений, когда агент заканчивает ответ и когда вы выходите из CLI.

  5. Удалите файл, notification-hooks.json чтобы убрать эти крючки.

Пример на уровне пользователя для Windows

  1. Создайте файл с позывом notification-hooks.json в %USERPROFILE%\.copilot\hooks\.

    Примечание.

    Если COPILOT_HOME установлено, создайте файл в %COPILOT_HOME%\hooks\.

  2. Скопируйте и вставьте следующий код JSON в файл:

    JSON
    {
  "version": 1,
  "hooks": {
    "agentStop": [
      {
        "type": "command",
        "powershell": "Add-Type -AssemblyName System.Windows.Forms; [System.Media.SystemSounds]::Asterisk.Play(); [System.Windows.Forms.MessageBox]::Show('Agent stopped.', 'Hook-generated message') | Out-Null",
        "timeoutSec": 5
      }
    ],
    "sessionEnd": [
      {
        "type": "command",
        "powershell": "Add-Type -AssemblyName System.Windows.Forms; [System.Media.SystemSounds]::Asterisk.Play(); [System.Windows.Forms.MessageBox]::Show('Session ended.', 'Hook-generated message') | Out-Null",
        "timeoutSec": 5
      }
    ]
  }
}

  3. Запустить или перезапустить. Второй пилот CLI

    Примечание.

    Изменения в конфигурации крюков загружаются при запуске CLI.

  4. Введите запрос и проверьте, слышите ли вы звук и видите окно сообщений, когда агент заканчивает ответ и когда вы выходите из CLI.

  5. Удалите файл, notification-hooks.json чтобы убрать эти крючки.

Устранение неполадок

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

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

Отладка

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

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

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

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

    Shell
    # 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 .

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