Informationen zu Hooks

Hooks ermöglichen es Ihnen, benutzerdefinierte Shellbefehle an strategischen Punkten im Workflow eines Agents auszuführen, z. B. wenn eine Agentsitzung startet oder endet, oder bevor und nachdem eine Eingabeaufforderung eingegeben wurde 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.

Copilot Agents unterstützen Hooks, die in JSON-Dateien in Ihrem Repository bei .github/hooks/*.json gespeichert sind.

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

Copilot-Programmier-Agent auf GitHub
GitHub Copilot-CLI im Terminal

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, Sitzungsbeginne für die Überwachung zu protokollieren, den Projektzustand zu validieren 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.

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

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:

Eigentum	Erforderlich	Description
`type`	Yes	Muss gleich `"command"` sein.
`bash`	Ja (auf Unix-Systemen)	Pfad zum auszuführenden Bash-Skript
`powershell`	Ja (unter 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 Ausführung des Agents. 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.

Sicherheitsüberlegungen

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.

          **Verwendet beim Konstruieren von Befehlen das richtige Shell-Escaping**. 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

Um mit dem Erstellen von Hooks zu beginnen, siehe Verwenden von Hooks mit GitHub Copilot-Agenten.

Informationen zu Hooks

Wer kann dieses Feature verwenden?

In diesem Artikel