Verwenden von Hooks mit GitHub Copilot-CLI

Hooks ermöglichen es Ihnen, das Verhalten von GitHub Copilot Agents zu erweitern und anzupassen, indem Sie benutzerdefinierte Shellbefehle an wichtigen Stellen während der Agentausführung ausführen. Eine konzeptionelle Übersicht über Hooks – einschließlich Details zu den verfügbaren Hook-Triggern – finden Sie unter Informationen zu Hooks für GitHub Copilot.

Voraussetzung

For Windows only: Die Beispiele in diesem Artikel verwenden PowerShell. Wenn Sie Windows verwenden, müssen Sie PowerShell 7.0 oder höher und in Ihrem PATH installiert haben. Sie können Ihre PowerShell-Version überprüfen, indem Sie pwsh --version in einem Terminal ausführen. Um PowerShell zu installieren, führen Sie winget install Microsoft.PowerShell aus, und starten Sie das Terminal neu.

Erstellen eines Hooks auf Repositoryebene

1. Erstellen Sie eine neue NAME.json-Datei (wobei NAME den Zweck der Datei beschreibt) im Ordner .github/hooks/ Ihres Repositorys.

2. Kopieren Sie in Ihrem Text-Editor die folgende Hook-Vorlage, und fügen Sie sie ein. Entfernen Sie alle Hooks, die Sie nicht aus dem hooks Array verwenden möchten.

   JSON

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

3. Konfigurieren Sie Ihre Hook-Syntax unter den Schlüsseln bash und powershell, oder referenzieren Sie direkt Skriptdateien, die Sie erstellt haben.

   Hinweis

   Schließen Sie sowohl einen bash-Schlüssel (mit einem Skript für Linux und macOS) als auch einen powershell-Schlüssel (für ein Skript für Windows) ein, damit die Hooks auf allen drei Betriebssystemen ausgeführt werden können. Copilot verwendet den entsprechenden Schlüssel basierend auf dem Betriebssystem des Benutzers.

   • In diesem Beispiel wird ein Skript ausgeführt, das das Startdatum der Sitzung mithilfe des sessionStart Hooks in eine Protokolldatei ausgibt:

     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
       }
     ],
     

   • In diesem Beispiel wird ein externes log-prompt Skript aufgerufen:

     JSON

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

     Eine vollständige Referenz zu den Eingabe-JSON aus Agentsitzungen sowie Beispielskripts finden Sie unter Referenz zu GitHub Copilot Hooks.

4. Commit die Datei in das Repository und füge sie in den Standard Branch ein. Ihre Hooks werden jetzt während Agentsitzungen ausgeführt.

Erstellen eines Hooks auf Benutzerebene

Hooks auf Benutzerebene werden wie Hooks auf Repositoryebene konfiguriert, aber die Hookdateien werden lokal unter Ihrem Heimverzeichnis gespeichert.

Die folgenden Beispiele für macOS und Windows zeigen, wie Hooks konfiguriert werden, die einen Sound wiedergeben und ein Meldungsfeld anzeigen, wenn die CLI die Antwort auf eine Eingabeaufforderung beendet hat und wenn Sie Copilot CLI beenden. Hooks für Linux wären dem macOS-Beispiel ähnlich, würden aber Linux-Tools zum Wiedergeben von Sounds und anzeigen von Nachrichten verwenden.

Beispiel für MacOS auf Benutzerebene

1. Erstellen Sie eine Datei namens notification-hooks.json in ~/.copilot/hooks/.

   Hinweis

   Falls COPILOT_HOME festgelegt ist, erstellen Sie die Datei in $COPILOT_HOME/hooks/.

2. Kopieren Sie den folgenden JSON-Code, und fügen Sie ihn in die Datei ein:

   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. Starten Sie, oder starten Sie neu Copilot CLI.

   Hinweis

   Änderungen an Hook-Konfigurationen werden geladen, wenn die CLI gestartet wird.

4. Geben Sie eine Eingabeaufforderung ein, und überprüfen Sie, ob Sie einen Sound hören, und sehen Sie ein Meldungsfeld, wenn der Agent fertig ist, und wenn Sie die CLI beenden.

5. Löschen Sie die notification-hooks.json Datei, um diese Hooks zu entfernen.

Beispiel für Windows auf Benutzerebene

1. Erstellen Sie in %USERPROFILE%\.copilot\hooks\ eine Datei mit dem Namen notification-hooks.json.

   Hinweis

   Wenn COPILOT_HOME festgelegt ist, erstellen Sie die Datei in %COPILOT_HOME%\hooks\.

2. Kopieren Sie den folgenden JSON-Code, und fügen Sie ihn in die Datei ein:

   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. Starten Sie, oder starten Sie neu Copilot CLI.

   Hinweis

   Änderungen an Hook-Konfigurationen werden geladen, wenn die CLI gestartet wird.

4. Geben Sie eine Eingabeaufforderung ein, und überprüfen Sie, ob Sie einen Sound hören, und sehen Sie ein Meldungsfeld, wenn der Agent fertig ist, und wenn Sie die CLI beenden.

5. Löschen Sie die notification-hooks.json Datei, um diese Hooks zu entfernen.

Problembehandlung

Wenn Probleme bei der Verwendung von Hooks auftreten, verwenden Sie die folgende Tabelle, um Probleme zu beheben.

Thema	Action
Hooks werden nicht ausgeführt	Überprüfen Sie, ob sich die JSON-Datei im .github/hooks/ Verzeichnis befindet. Überprüfen Sie die gültige JSON-Syntax (z. B jq . hooks.json. ). Stellen Sie sicher, dass version: 1 in Ihrer hooks.json-Datei angegeben ist. Vergewissern Sie sich, dass das Skript, das Sie von Ihrem Hook aufrufen, ausführbar ist (chmod +x script.sh) Überprüfen Sie, ob das Skript über einen richtigen Shebang verfügt (z. B. #!/bin/bash).
Hooks laufen ab	Der Standardzeitraum bis zum Timeout beträgt 30 Sekunden. Erhöhen Sie timeoutSec in der Konfiguration bei Bedarf. Optimieren Sie die Skriptleistung, indem Sie unnötige Vorgänge vermeiden.
Ungültige JSON-Ausgabe	Stellen Sie sicher, dass sich die Ausgabe in einer einzelnen Zeile befindet. Um auf Unix die JSON-Ausgabe zu komprimieren und zu validieren, verwenden Sie jq -c. Verwenden Sie auf Windows den Befehl ConvertTo-Json -Compress in PowerShell, um dasselbe zu tun.

Fehlersuche

Sie können Hooks mit den folgenden Methoden debuggen:

• Aktivieren Sie die ausführliche Protokollierung im Skript, um die Eingabedaten zu überprüfen und die Skriptausführung nachzuverfolgen.

  Shell

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

• Testen Sie Hooks lokal, indem Sie die Testeingaben in Ihre Hooks weiterleiten, um ihr Verhalten zu überprüfen.

  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 .
  

Weiterführende Lektüre

• Referenz zu GitHub Copilot Hooks
• Informationen zu GitHub Copilot Cloud-Agent
• Informationen zu GitHub Copilot CLI
• Konfigurieren der Entwicklungsumgebung