{"meta":{"title":"与 GitHub Copilot 命令行界面 (CLI) 一起使用挂钩","intro":"在代理执行期间，在关键点使用自定义 shell 命令扩展 GitHub Copilot 代理行为。","product":"GitHub Copilot","breadcrumbs":[{"href":"/zh/copilot","title":"GitHub Copilot"},{"href":"/zh/copilot/how-tos","title":"操作方法"},{"href":"/zh/copilot/how-tos/copilot-cli","title":"Copilot 命令行界面（CLI）"},{"href":"/zh/copilot/how-tos/copilot-cli/customize-copilot","title":"自定义 Copilot CLI"},{"href":"/zh/copilot/how-tos/copilot-cli/customize-copilot/use-hooks","title":"使用挂钩"}],"documentType":"article"},"body":"# 与 GitHub Copilot 命令行界面 (CLI) 一起使用挂钩\n\n在代理执行期间，在关键点使用自定义 shell 命令扩展 GitHub Copilot 代理行为。\n\n挂钩允许你在代理执行过程中通过在关键点执行自定义 shell 命令来扩展和自定义代理的行为 GitHub Copilot 。 有关挂钩的概念性概述（包括可用挂钩触发器的详细信息），请参阅 [关于钩子](/zh/copilot/concepts/agents/cloud-agent/about-hooks)。\n\n## 在GitHub的存储库中创建挂钩\n\n1. 在存储库的`hooks.json`文件夹中，用您选择的名称创建新`.github/hooks/`文件。 钩子配置文件 **必须存在于** 存储库的默认分支上，才可被 Copilot云代理 使用。 对于 GitHub Copilot 命令行界面 (CLI)，挂钩是从当前工作目录加载的。\n\n2. 在文本编辑器中，复制并粘贴以下挂钩模板。 从 `hooks` 数组中删除您不打算使用的任何挂钩。\n\n   ```json copy\n   {\n     \"version\": 1,\n     \"hooks\": {\n       \"sessionStart\": [...],\n       \"sessionEnd\": [...],\n       \"userPromptSubmitted\": [...],\n       \"preToolUse\": [...],\n       \"postToolUse\": [...],\n       \"errorOccurred\": [...]\n     }\n   }\n   ```\n\n3. 在 `bash` 或 `powershell` 键下配置挂钩语法，或直接引用已创建的脚本文件。\n\n   * 此示例运行一个脚本，该脚本使用 `sessionStart` 挂钩将会话的开始日期输出到日志文件：\n\n     ```json copy\n     \"sessionStart\": [\n       {\n         \"type\": \"command\",\n         \"bash\": \"echo \\\"Session started: $(date)\\\" >> logs/session.log\",\n         \"powershell\": \"Add-Content -Path logs/session.log -Value \\\"Session started: $(Get-Date)\\\"\",\n         \"cwd\": \".\",\n         \"timeoutSec\": 10\n       }\n     ],\n     ```\n\n   * 此示例调用外部 `log-prompt` 脚本：\n\n     ```json copy\n     \"userPromptSubmitted\": [\n       {\n         \"type\": \"command\",\n         \"bash\": \"./scripts/log-prompt.sh\",\n         \"powershell\": \"./scripts/log-prompt.ps1\",\n         \"cwd\": \"scripts\",\n         \"env\": {\n           \"LOG_LEVEL\": \"INFO\"\n         }\n       }\n     ],\n     ```\n\n     有关代理会话中的输入 JSON 以及示例脚本的完整参考，请参阅 [挂钩配置](/zh/copilot/reference/hooks-configuration)。\n\n4. 将文件提交到存储库，并将其合并到默认分支中。 你的挂钩现在将在智能体会话期间运行。\n\n## 故障排除\n\n如果使用挂钩遇到问题，请使用下表进行故障排除。\n\n| 問题        | Action                                                                                                                                                                                                                                          |\n| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 钩子没有运行    | <ul><li>验证 JSON 文件是否在 `.github/hooks/` 目录中。</li><li>检查有效的 JSON 语法（例如 `jq .  hooks.json`）。</li><li>确保 `version: 1` 已在 `hooks.json` 文件中指定。</li><li>验证从挂钩调用的脚本是否可执行 （`chmod +x script.sh`）</li><li>检查该脚本是否有适当的 shebang（例如，`#!/bin/bash`）</li></ul> |\n| 挂钩超时      | <ul><li>默认超时值为 30 秒。 如有需要，增加配置中的 `timeoutSec`。</li><li>通过避免不必要的作来优化脚本性能。</li></ul>                                                                                                                                                              |\n| JSON 输出无效 | <ul><li>确保输出位于单行上。</li><li>在 Unix 上，用于 `jq -c` 压缩和验证 JSON 输出。</li><li>在 Windows 上，使用 PowerShell 中的 `ConvertTo-Json -Compress` 命令执行相同的操作。</li></ul>                                                                                              |\n\n## 调试\n\n可以使用以下方法调试挂钩：\n\n* 在脚本中**启用详细日志记录**以检查输入数据和跟踪脚本执行。\n\n  ```shell copy\n  #!/bin/bash\n  set -x  # Enable bash debug mode\n  INPUT=$(cat)\n  echo \"DEBUG: Received input\" >&2\n  echo \"$INPUT\" >&2\n  # ... rest of script\n  ```\n\n* 在本地测试挂钩的方法是，将测试输入通过管道传递到挂钩，以验证其行为\\*\\*\\*\\*。\n\n  ```shell copy\n  # Create test input\n  echo '{\"timestamp\":1704614400000,\"cwd\":\"/tmp\",\"toolName\":\"bash\",\"toolArgs\":\"{\\\"command\\\":\\\"ls\\\"}\"}' | ./my-hook.sh\n\n  # Check exit code\n  echo $?\n\n  # Validate output is valid JSON\n  ./my-hook.sh | jq .\n  ```\n\n## 延伸阅读\n\n* [挂钩配置](/zh/copilot/reference/hooks-configuration)\n* [关于 GitHub Copilot 云代理](/zh/copilot/concepts/agents/cloud-agent/about-cloud-agent)\n* [关于 GitHub Copilot CLI](/zh/copilot/concepts/agents/about-copilot-cli)\n* [配置开发环境](/zh/copilot/how-tos/use-copilot-agents/cloud-agent/customize-the-agent-environment)"}