Informationen zu Hooks für GitHub Copilot

Was sind Hooks?

Hooks sind eine Möglichkeit, benutzerdefinierte Shellbefehle an strategischen Punkten im Workflow eines Agents auszuführen, z. B. wenn eine Agentsitzung gestartet oder beendet wird, wenn Sie eine Eingabeaufforderung eingeben oder ein Tool aufgerufen wird.

Hooks erhalten detaillierte Informationen zu Agentaktionen über JSON-Eingaben und ermöglichen die kontextabhängige Automatisierung. Sie können beispielsweise Hooks verwenden, um:

Programmgesteuertes Genehmigen oder Verweigern von Toolausführungen.
Verwenden Sie integrierte Sicherheitsfeatures wie geheime Überprüfungen, um Anmeldeinformationenlecks zu verhindern.
Implementieren Sie benutzerdefinierte Überprüfungsregeln und Überwachungsprotokollierung für die Compliance.

"Hooks stehen zur Verfügung für die Verwendung mit:"

**Copilot-Cloud-Agent ** auf GitHub.
**GitHub Copilot-CLI ** in Ihrem Terminal.

Sie definieren Hooks in JSON-Dateien, die in Ihrem Repository unter .github/hooks/*.json. Diese gelten, wenn Copilot Agents im Repository verwendet werden. Copilot CLI unterstützt auch persönliche Hooks, die Sie in Ihrem Heimverzeichnis speichern unter ~/.copilot/hooks/*.json. Diese gelten immer dann, wenn Sie es verwenden Copilot CLI.

Arten von Haken

Die folgenden Arten von Hooks sind verfügbar:

sessionStart: Ausgeführt, wenn eine neue Agentsitzung beginnt oder wenn eine vorhandene Sitzung fortgesetzt wird. Kann verwendet werden, um Umgebungen zu initialisieren, Sitzungsstarts für die Überwachung zu protokollieren, den Projektstatus zu überprüfen und temporäre Ressourcen einzurichten.
sessionEnd: Ausgeführt, wenn die Agentsitzung abgeschlossen oder beendet wird. Kann verwendet werden, um temporäre Ressourcen zu bereinigen, Sitzungsberichte und Protokolle zu generieren und zu archivieren oder Benachrichtigungen zum Abschluss der Sitzung zu senden.
userPromptSubmitted: Wird ausgeführt, wenn der Benutzer eine Eingabeaufforderung an den Agent sendet. Kann verwendet werden, um Benutzeranforderungen für die Überwachung und Nutzungsanalyse zu protokollieren.
preToolUse: Ausgeführt, bevor der Agent ein beliebiges Tool verwendet (z. B. bash, edit, view). Dies ist der leistungsfähigste Hook, da er Toolausführungen genehmigen oder verweigern kann. Verwenden Sie diesen Hook, um gefährliche Befehle zu blockieren, Sicherheitsrichtlinien und Codierungsstandards zu erzwingen, eine Genehmigung für vertrauliche Vorgänge oder die Verwendung von Protokolltools für die Compliance zu erfordern.
postToolUse: Ausgeführt, nachdem ein Tool die Ausführung abgeschlossen hat (ob erfolgreich oder fehlgeschlagen). Kann verwendet werden, um Ausführungsergebnisse zu protokollieren, Nutzungsstatistiken nachzuverfolgen, Überwachungspfade zu generieren, Leistungsmetriken zu überwachen und Fehlerwarnungen zu senden.
agentStop: Ausgeführt, wenn der Haupt-Agent die Antwort auf Ihre Eingabeaufforderung abgeschlossen hat.
subagentStop: Ausgeführt, wenn ein Subagent abgeschlossen ist, bevor Ergebnisse an den übergeordneten Agent zurückgegeben werden.
errorOccurred: Ausgeführt, wenn während der Agentausführung ein Fehler auftritt. Kann verwendet werden, um Fehler beim Debuggen zu protokollieren, Benachrichtigungen zu senden, Fehlermuster nachzuverfolgen und Berichte zu generieren.

Eine vollständige Referenz zu Hook-Typen mit Beispielanwendungsfällen, bewährten Methoden und erweiterten Mustern finden Sie unter Referenz zu GitHub Copilot Hooks.

Hook-Konfigurationsformat

Sie konfigurieren Hooks mit einem speziellen JSON-Format. Der JSON-Code muss ein version Feld mit einem Wert 1 und einem hooks Objekt enthalten, das Arrays von Hookdefinitionen enthält.

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

Das Hook-Objekt kann die folgenden Schlüssel enthalten:

Eigenschaft	Erforderlich	Description
`type`	Ja	Muss `"command"` sein
`bash`	Ja (auf Unix-Systemen)	Pfad zum auszuführenden Bash-Skript
`powershell`	Ja (auf Windows)	Pfad zum auszuführenden PowerShell-Skript
`cwd`	Nein	Arbeitsverzeichnis für das Skript (relativ zum Repositorystamm)
`env`	Nein	Zusätzliche Umgebungsvariablen, die mit der vorhandenen Umgebung zusammengeführt werden
`timeoutSec`	Nein	Maximale Ausführungszeit in Sekunden (Standard: 30)

Beispielkonfigurationsdatei für Hooks

Dies ist eine Beispielkonfigurationsdatei, die sich in ~/.github/hooks/project-hooks.json innerhalb eines Repositories befindet.

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

Leistungsüberlegungen

Hooks werden synchron ausgeführt und blockieren die Agentausführung. Beachten Sie die folgenden Überlegungen, um eine reaktionsfähige Erfahrung zu gewährleisten:

Minimieren Sie die Ausführungszeit: Halten Sie die Ausführungszeit des Hooks nach Möglichkeit unter 5 Sekunden.
Protokollierung optimieren: Verwenden Sie die asynchrone Protokollierung, z. B. das Anfügen an Dateien, anstatt synchrone E/A.
Verwenden Sie Hintergrundverarbeitung: Für teure Vorgänge sollten Sie die Hintergrundverarbeitung in Betracht ziehen.
Ergebnisse im Cache speichern: Cachen Sie teure Berechnungen, sofern möglich.

Sicherheitshinweise

Beachten Sie die folgenden Überlegungen, um sicherzustellen, dass die Sicherheit bei der Verwendung von Hooks beibehalten wird:

Überprüfen Sie immer die Eingabe, die von Hooks verarbeitet wird, und bereinigen Sie sie. Nicht vertrauenswürdige Eingaben können zu unerwartetem Verhalten führen.
Verwenden Sie beim Erstellen von Befehlen die richtige Shell-Escapeing. Dadurch werden Sicherheitsrisiken beim Einfügen von Befehlen verhindert.
Protokollieren Sie niemals vertrauliche Daten, z. B. Token oder Kennwörter.
Stellen Sie sicher, dass Hook-Skripts und Protokolle über die entsprechenden Berechtigungen verfügen.
Seien Sie vorsichtig mit Hooks, die externe Netzwerkanrufe tätigen. Diese können Latenz, Fehler oder Daten Dritten zugänglich machen.
Legen Sie geeignete Timeouts fest, um die Ressourcenausschöpfung zu verhindern. Lange ausgeführte Hooks können die Ausführung des Agents blockieren und die Leistung beeinträchtigen.

Nächste Schritte

Eine Anleitung zum Erstellen von Hooks finden Sie unter:

Anpassen von Agentworkflows mit Hooks für Copilot-Cloud-Agent
Verwenden von Hooks mit GitHub Copilot-CLI für GitHub Copilot-CLI

Informationen zu Hooks für GitHub Copilot

In diesem Artikel