Anpassen von Agentworkflows mit Hooks

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.

Erstellen eines Hooks in einem Repository auf GitHub

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

Wichtig

Die Hooks-Konfigurationsdatei muss vorhanden sein in der Standardverzweigung Ihres Repositorys, um von Copilot-Cloud-Agent verwendet zu werden.

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": [...]
  }
}

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

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

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

"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.

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

Troubleshooting

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

#!/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 .

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

In diesem Artikel

Erstellen eines Hooks in einem Repository auf GitHub

Troubleshooting

Fehlersuche

Weiterführende Lektüre