使用 GitHub Copilot 代理的钩子

钩子允许你在代理执行的关键节点运行自定义 shell 命令，从而扩展和定制 GitHub Copilot 代理的行为。有关钩子的概念概述（包括可用的触发器详情），请参阅 关于钩子。

在 GitHub 上的仓库中创建钩子

1. 在仓库的 .github/hooks/ 目录下创建一个任意命名的 hooks.json 文件。钩子配置文件 必须 位于仓库默认分支上，才能被 Copilot 云代理使用。对于 GitHub Copilot CLI，钩子会从当前工作目录加载。

2. 在你的文本编辑器中，复制并粘贴以下钩子模板。请从 hooks 数组中移除所有不打算使用的钩子。

   JSON

   {
     "version": 1,
     "hooks": {
       "sessionStart": [...],
       "sessionEnd": [...],
       "userPromptSubmitted": [...],
       "preToolUse": [...],
       "postToolUse": [...],
       "errorOccurred": [...]
     }
   }
   

3. 在 bash 或 powershell 键下配置钩子语法，或直接引用你已创建的脚本文件。

   • 此示例使用 sessionStart 钩子运行一个脚本，将会话的开始日期输出到日志文件。

     JSON

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

   • 此示例调用外部的 log-prompt 脚本。

     JSON

     "userPromptSubmitted": [
       {
         "type": "command",
         "bash": "./scripts/log-prompt.sh",
         "powershell": "./scripts/log-prompt.ps1",
         "cwd": "scripts",
         "env": {
           "LOG_LEVEL": "INFO"
         }
       }
     ],
     

     有关来自代理会话的输入 JSON 的完整参考以及示例脚本，请参阅 钩子配置。

4. 将文件提交到仓库并合并至默认分支。你的钩子现在将在代理会话期间运行。

故障排除

如果在使用钩子时遇到问题，请使用下表进行故障排除。

议题	操作
钩子未执行	确认 JSON 文件位于 .github/hooks/ 目录下。 检查 JSON 语法是否有效（例如，jq . hooks.json）。 确保在 hooks.json 文件中指定了 version: 1。 确认你在钩子中调用的脚本具有可执行权限（chmod +x script.sh）。 检查脚本是否包含正确的 shebang（例如，#!/bin/bash）。
钩子超时	默认超时时间为 30 秒。如有需要，可在配置中增加 timeoutSec。 通过避免不必要的操作来优化脚本性能。
JSON 输出无效	确保输出位于单行。 在 Unix 系统上，使用 jq -c 对 JSON 输出进行压缩和校验。 在 Windows 系统上，使用 PowerShell 的 ConvertTo-Json -Compress 命令实现同样的功能。

调试

你可以使用以下方法调试钩子

• 在脚本中启用详细日志，以检查输入数据并追踪脚本执行过程。

  Shell

  #!/bin/bash
  set -x  # Enable bash debug mode
  INPUT=$(cat)
  echo "DEBUG: Received input" >&2
  echo "$INPUT" >&2
  # ... rest of script
  

• 在本地测试钩子，通过向钩子管道输入测试数据来验证其行为。

  Shell

  # Create test input
  echo '{"timestamp":1704614400000,"cwd":"/tmp","toolName":"bash","toolArgs":"{\"command\":\"ls\"}"}' | ./my-hook.sh
  
  # Check exit code
  echo $?
  
  # Validate output is valid JSON
  ./my-hook.sh | jq .
  

延伸阅读

• 有关配置钩子的更多信息，请参阅 钩子配置
• 有关 Copilot 云代理的更多信息，请参阅 关于 GitHub Copilot 云代理
• 有关 GitHub Copilot CLI 的更多信息，请参阅 关于 GitHub Copilot CLI
• 有关自定义代理环境的更多信息，请参阅 自定义 GitHub Copilot 云代理的开发环境