关于钩子

通过在代理执行过程中于关键点执行自定义 shell 命令，来拓展和定制 GitHub Copilot 代理的行为。

谁可以使用此功能？

Copilot 编码智能体 可用于 GitHub Copilot Pro、GitHub Copilot Pro+、GitHub Copilot Business 和 GitHub Copilot Enterprise 计划。 该代理在 GitHub 上存储的所有仓库中均可用，但以下情况除外：由 托管用户帐户 拥有的仓库，以及已显式禁用该代理的仓库。
Sign up for Copilot

本文内容

关于钩子

挂钩使你可以在代理工作流中的战略点执行自定义 shell 命令，例如代理会话启动或结束，或者在输入提示或调用工具之前和之后。

挂钩通过 JSON 输入接收有关智能体操作的详细信息，支持上下文感知自动化。 例如，您可以使用钩子来：

  • 以编程方式批准或拒绝工具执行。
  • 利用机密扫描等内置安全功能来防止凭据泄漏。
  • 实现自定义验证规则和审核日志记录以实现符合性。

Copilot 智能体支持存储在仓库中 .github/hooks/*.json 路径下 JSON 文件中的挂钩。

挂钩可用于：

  • Copilot 编码智能体 上的 GitHub
  • 终端中的 GitHub Copilot 命令行界面

挂钩类型

提供以下类型的挂钩：

  •         **sessionStart**：在新代理会话开始或恢复现有会话时执行。 可用于初始化环境、日志会话开始用于审核、验证项目状态和设置临时资源。

  •         **sessionEnd**：在代理会话完成或终止时执行。 可用于清理临时资源、生成和存档会话报告和日志，或发送有关会话完成的通知。

  •         **userPromptSubmitted**：当用户向代理提交提示时执行。 可用于记录用户审核和使用情况分析的请求。 

  •         **preToolUse**：在代理使用任何工具（如 `bash`， `edit`，） `view`之前执行。 这是最强大的挂钩，因为它可以 **批准或拒绝工具执行**。 使用此挂钩程序可阻止危险命令、强制实施安全策略和编码标准、要求批准敏感操作，或记录工具使用情况以实现合规性。

  •         **postToolUse**：在工具完成执行后执行（无论是成功还是失败）。 可用于记录执行结果、跟踪使用情况统计信息、生成审核线索、监视性能指标以及发送故障警报。

  •         **errorOccurred**：在代理执行期间发生错误时执行。 可用于记录用于调试的错误、发送通知、跟踪错误模式和生成报告。

若要查看具有示例用例、最佳做法和高级模式的挂钩类型的完整参考，请参阅 挂钩配置。

钩子配置格式

使用特殊 JSON 格式配置钩子。 JSON 必须包含一个字段version，其值为1，并含有一个hooks对象，该对象包含挂钩定义的数组。

JSON
{
  "version": 1,
  "hooks": {
    "sessionStart": [
      {
        "type": "command",
        "bash": "string (optional)",
        "powershell": "string (optional)",
        "cwd": "string (optional)",
        "env": { "KEY": "value" },
        "timeoutSec": 30
      }
    ],
  }
}

挂钩对象可以包含以下键：

资产必选Description
type是的必须是 "command"
bash是（在 Unix 系统上）要执行的 bash 脚本的路径
powershell是（在 Windows 上）要执行的 PowerShell 脚本的路径
cwd否脚本的工作目录（相对于存储库根目录）
env否与现有环境合并的其他环境变量
timeoutSec否最大执行时间（默认值：30）

示例挂钩配置文件

这是位于存储库中的 ~/.github/hooks/project-hooks.json 示例配置文件。

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

性能注意事项

挂钩同步运行并阻止代理执行。 若要确保响应式体验，请记住以下注意事项：

  •         **最小化执行时间**：尽可能将挂钩执行时间保持在 5 秒以内。

  •         **优化日志记录**：使用异步日志记录操作，例如将日志追加到文件中，而不是同步输入/输出操作。

  •         **使用后台处理**：对于昂贵的操作，请考虑后台处理。

  •         **缓存结果**：尽可能缓存昂贵的计算。

安全注意事项

若要确保在使用挂钩时保持安全性，请记住以下注意事项：

  •           **始终验证和清理挂钩处理的输入**。 不受信任的输入可能导致意外行为。

  •           **构造命令时使用适当的 Shell 转义**。 这可以防止命令注入漏洞。

  •         **从不记录敏感数据，例如令牌或密码**。

  •         **确保挂钩脚本和日志具有适当的权限**。 

  •         **请谨慎使用会进行外部网络调用的钩子**。 这可能会导致延迟、故障或向第三方公开数据。

  •         **设置适当的超时以防止资源耗尽**。 长时间运行的挂钩可能会阻止代理执行并降低性能。

后续步骤

若要开始创建挂钩，请参阅 在 GitHub Copilot 智能体中使用挂钩。