Verwenden von Hooks mit GitHub Copilot-CLI

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

Erstellen eines Hooks in einem Repository auf GitHub

1. Erstellen Sie eine neue hooks.json Datei mit dem Namen Ihrer Wahl im .github/hooks/ Ordner Ihres Repositorys. Die Hooks-Konfigurationsdatei muss im Standard Branch deines Repositorys vorhanden sein, damit sie von Copilot-Programmierassistent verwendet werden kann. Für GitHub Copilot-CLI werden die Hooks aus deinem aktuellen Arbeitsverzeichnis geladen.

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 Hooksyntax unter den Schlüsseln bash``powershell , oder verweisen Sie direkt auf skriptdateien, die Sie erstellt haben.

   • 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 Hooks-Konfiguration.

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.

Problembehandlung

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

Thema	Maßnahme
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üfe, ob das Skript einen richtigen Shebang hat (z.B. #!/bin/bash)
Timeout der Hooks	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 unter Windows den ConvertTo-Json -Compress Befehl 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

•         [AUTOTITLE](/copilot/reference/hooks-configuration)
  

•         [AUTOTITLE](/copilot/concepts/agents/coding-agent/about-coding-agent)
  

•         [AUTOTITLE](/copilot/concepts/agents/about-copilot-cli)
  

•         [AUTOTITLE](/copilot/how-tos/use-copilot-agents/coding-agent/customize-the-agent-environment)