在 GitHub Copilot CLI 中使用钩子

钩子允许您通过在代理执行的关键节点运行自定义 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 .
  

延伸阅读

• 钩子配置
• 关于 GitHub Copilot 云代理
• 关于 GitHub Copilot CLI
• 为 GitHub Copilot 云代理定制开发环境