关于钩子 GitHub Copilot

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

在本文中

什么是钩子？

挂钩是在代理工作流的战略点（例如代理会话开始或结束、输入提示时或调用工具时）执行自定义 shell 命令的方法。

挂钩通过 JSON 输入接收有关代理操作的详细信息，从而启用上下文感知自动化。 例如，您可以使用钩子来：

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

挂钩可用于：

  • **Copilot云代理 ** on GitHub.
  • **GitHub Copilot 命令行界面 (CLI) ** 在终端中。

可以在存储在存储库 .github/hooks/*.json中的 JSON 文件中定义挂钩。 每当 Copilot 存储库中使用代理时，这些都适用。 Copilot 命令行界面（CLI） 还支持你可以在主目录中~/.copilot/hooks/*.json存储的个人钩子。 每当使用 Copilot 命令行界面（CLI）时，这些都适用。

挂钩类型

可以使用以下类型的挂钩：

  • sessionStart：在新代理会话开始或恢复现有会话时执行。 可用于初始化环境、日志会话开始用于审核、验证项目状态和设置临时资源。
  • sessionEnd：在代理会话完成或终止时执行。 可用于清理临时资源、生成和存档会话报告和日志，或发送有关会话完成的通知。
  • userPromptSubmitted：当用户向代理提交提示时执行。 可用于记录用户审核和使用情况分析的请求。
  • preToolUse：在代理使用任何工具（如 bash， edit，） view之前执行。 这是最强大的挂钩，因为它可以 批准或拒绝工具执行。 使用此挂钩程序可阻止危险命令、强制实施安全策略和编码标准、要求批准敏感操作，或记录工具使用情况以实现合规性。
  • postToolUse：在工具完成执行后执行（无论是成功还是失败）。 可用于记录执行结果、跟踪使用情况统计信息、生成审核线索、监视性能指标以及发送故障警报。
  • agentStop：在主代理完成对提示的响应后执行。
  • subagentStop：在子代理完成时执行，然后再将结果返回到父代理。
  • errorOccurred：在代理执行期间发生错误时执行。 可用于记录用于调试的错误、发送通知、跟踪错误模式和生成报告。

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

钩子配置格式

使用特殊 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 转义措施。 这可以防止命令注入漏洞。
  • 从不记录敏感数据，例如令牌或密码。
  • 确保挂钩脚本和日志具有适当的权限。
  • 请谨慎使用会进行外部网络调用的钩子。 这可能会导致延迟、故障或向第三方公开数据。
  • 设置适当的超时以防止资源耗尽。 长时间运行的挂钩可能会阻止代理执行并降低性能。

后续步骤

若要开始创建挂钩，请参阅：