将钩子与 GitHub Copilot 命令行界面 配合使用

挂钩允许你在智能体执行过程中的关键节点执行自定义 Shell 命令，从而扩展和自定义 GitHub Copilot 智能体的行为。 有关挂钩的概念性概述（包括可用挂钩触发器的详细信息），请参阅 关于钩子。

在 GitHub

上的存储库中创建钩子

1. 在存储库的hooks.json文件夹中，用您选择的名称创建新.github/hooks/文件。 挂钩配置文件必须存在于你的仓库的默认分支中，才能被 Copilot 编码智能体 使用。 对于 GitHub Copilot 命令行界面，挂钩从你当前的工作目录加载。

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. 将文件提交到存储库，并将其合并到默认分支中。 你的挂钩现在将在智能体会话期间运行。

故障排除

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

問题	Action
挂钩未执行	验证 JSON 文件是否在 .github/hooks/ 目录中。 检查有效的 JSON 语法（例如 jq . hooks.json）。 确保 version: 1 已在 hooks.json 文件中指定。 验证从挂钩调用的脚本是否可执行 （chmod +x script.sh） 检查脚本是否有正确的解释器声明（例如，#!/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 .
  

延伸阅读

•         [AUTOTITLE](/copilot/reference/hooks-configuration)
  

•         [AUTOTITLE](/copilot/concepts/agents/coding-agent/about-coding-agent)
  

•         [AUTOTITLE](/copilot/concepts/agents/about-copilot-cli)
  

•         [AUTOTITLE](/copilot/how-tos/use-copilot-agents/coding-agent/customize-the-agent-environment)