{"meta":{"title":"与 GitHub Copilot CLI 一起使用挂钩","intro":"在代理执行期间，在关键点使用自定义 shell 命令扩展 GitHub Copilot 代理行为。","product":"GitHub Copilot","breadcrumbs":[{"href":"/zh/enterprise-cloud@latest/copilot","title":"GitHub Copilot"},{"href":"/zh/enterprise-cloud@latest/copilot/how-tos","title":"操作方法"},{"href":"/zh/enterprise-cloud@latest/copilot/how-tos/copilot-cli","title":"Copilot CLI"},{"href":"/zh/enterprise-cloud@latest/copilot/how-tos/copilot-cli/customize-copilot","title":"自定义 Copilot CLI"},{"href":"/zh/enterprise-cloud@latest/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 。 有关挂钩的概念性概述（包括可用挂钩触发器的详细信息），请参阅 [关于钩子 GitHub Copilot](/zh/enterprise-cloud@latest/copilot/concepts/agents/hooks)。\n\n## 先决条件\n\n**仅Windows用户：** 本文中的示例挂钩设计为在 Windows、Linux 和 macOS 上运行。 对于Windows，它们使用 PowerShell，并要求安装 PowerShell 7.0 或更高版本并在 PATH 中安装。 可以通过在终端中运行 `pwsh --version` 来检查 PowerShell 版本。 若要安装 PowerShell，请运行 `winget install Microsoft.PowerShell`，然后重启终端。\n\n## 创建仓库级钩子\n\n1. 在存储库的文件夹中创建一个新 `NAME.json` 文件（其中 `NAME` 描述了文件 `.github/hooks/` 的目的）。\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 > \\[!NOTE]\n > 包括 `bash` 键（包含适用于 Linux 和 macOS 的脚本）和 `powershell` 键（适用于 Windows 脚本），以允许挂钩在所有三个操作系统上运行。\n > Copilot 根据用户的操作系统使用相应的密钥。\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 以及示例脚本的完整参考，请参阅 [GitHub Copilot 挂钩参考](/zh/enterprise-cloud@latest/copilot/reference/hooks-reference)。\n\n4. 将文件提交到存储库，并将其合并到默认分支中。 你的挂钩现在将在智能体会话期间运行。\n\n## 创建用户级钩子\n\n用户级挂钩的配置就像存储库级挂钩一样，但挂钩文件存储在本地，位于主目录下方。\n\nmacOS 和 Windows 以下示例演示如何配置挂钩，这些挂钩将在 CLI 完成响应提示时以及退出 Copilot CLI时播放声音并显示消息框。 适用于 Linux 的挂钩类似于 macOS 示例，但使用 Linux 工具播放声音和显示消息。\n\n### macOS 的用户级示例\n\n1. 在`notification-hooks.json`中创建一个名为`~/.copilot/hooks/`的文件。\n\n > \\[!NOTE]\n > 如果设置了 `COPILOT_HOME`，请在 `$COPILOT_HOME/hooks/` 中创建该文件。\n\n2. 将以下 JSON 复制并粘贴到文件中：\n\n ```json copy\n {\n \"version\": 1,\n \"hooks\": {\n \"agentStop\": [\n {\n \"type\": \"command\",\n \"bash\": \"osascript -e 'do shell script \\\"afplay /System/Library/Sounds/Funk.aiff &> /dev/null &\\\"' -e 'display dialog \\\"Agent stopped.\\\" with title \\\"Hook-generated message\\\" buttons {\\\"OK\\\"} default button \\\"OK\\\"'\",\n \"timeoutSec\": 5\n }\n ],\n \"sessionEnd\": [\n {\n \"type\": \"command\",\n \"bash\": \"osascript -e 'do shell script \\\"afplay /System/Library/Sounds/Funk.aiff &> /dev/null &\\\"' -e 'display dialog \\\"Session ended.\\\" with title \\\"Hook-generated message\\\" buttons {\\\"OK\\\"} default button \\\"OK\\\"'\",\n \"timeoutSec\": 5\n }\n ]\n }\n }\n ```\n\n3. 启动或重启 Copilot CLI。\n\n > \\[!NOTE]\n > CLI 启动时会加载对挂钩配置的更改。\n\n4. 输入提示并检查是否听到声音，并在代理完成响应时以及退出 CLI 时看到消息框。\n\n5. 删除`notification-hooks.json`文件以移除这些挂钩。\n\n### Windows的用户级示例\n\n1. 在`notification-hooks.json`中创建一个名为`%USERPROFILE%\\.copilot\\hooks\\`的文件。\n\n > \\[!NOTE]\n > 如果设置了 `COPILOT_HOME`，请在 `%COPILOT_HOME%\\hooks\\` 中创建该文件。\n\n2. 将以下 JSON 复制并粘贴到文件中：\n\n ```json copy\n {\n \"version\": 1,\n \"hooks\": {\n \"agentStop\": [\n {\n \"type\": \"command\",\n \"powershell\": \"Add-Type -AssemblyName System.Windows.Forms; [System.Media.SystemSounds]::Asterisk.Play(); [System.Windows.Forms.MessageBox]::Show('Agent stopped.', 'Hook-generated message') | Out-Null\",\n \"timeoutSec\": 5\n }\n ],\n \"sessionEnd\": [\n {\n \"type\": \"command\",\n \"powershell\": \"Add-Type -AssemblyName System.Windows.Forms; [System.Media.SystemSounds]::Asterisk.Play(); [System.Windows.Forms.MessageBox]::Show('Session ended.', 'Hook-generated message') | Out-Null\",\n \"timeoutSec\": 5\n }\n ]\n }\n }\n ```\n\n3. 启动或重启 Copilot CLI。\n\n > \\[!NOTE]\n > CLI 启动时会加载对挂钩配置的更改。\n\n4. 输入提示并检查是否听到声音，并在代理完成响应时以及退出 CLI 时看到消息框。\n\n5. 删除`notification-hooks.json`文件以移除这些挂钩。\n\n## 故障排除\n\n如果使用挂钩遇到问题，请使用下表进行故障排除。\n\n| 問题 | Action |\n| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 钩子没有运行 | |\n| 挂钩超时 | |\n| JSON 输出无效 | |\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* [GitHub Copilot 挂钩参考](/zh/enterprise-cloud@latest/copilot/reference/hooks-reference)\n* [关于 GitHub Copilot 云代理](/zh/enterprise-cloud@latest/copilot/concepts/agents/cloud-agent/about-cloud-agent)\n* [关于 GitHub Copilot CLI](/zh/enterprise-cloud@latest/copilot/concepts/agents/copilot-cli/about-copilot-cli)\n* [配置开发环境](/zh/enterprise-cloud@latest/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/customize-the-agent-environment)"}