关于钩子

钩子使您能够在代理工作流的关键点（例如代理会话开始或结束时，或在输入提示前后以及调用工具时）执行自定义 shell 命令。

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

以编程方式批准或拒绝工具执行。
利用内置安全功能，如机密扫描，防止凭证泄露。
实现自定义验证规则和审计日志以满足合规要求。

Copilot 代理支持存放在仓库 .github/hooks/*.json 下的 JSON 文件中的钩子。

钩子可用于以下场景

GitHub 上的 Copilot 云代理
终端中的 GitHub Copilot CLI

钩子类型

以下类型的钩子可用

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

要查看包含示例用例、最佳实践和高级模式的完整钩子类型参考，请参阅钩子配置。

钩子配置格式

您使用一种特殊的 JSON 格式来配置钩子。JSON 必须包含一个值为 1 的 version 字段，以及一个包含钩子定义数组的 hooks 对象。

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

钩子对象可以包含以下键

属性	是否必填	描述
`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
      }
    ]
  }
}

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