{"meta":{"title":"关于钩子 GitHub Copilot","intro":"通过在代理执行过程中在关键点执行自定义 shell 命令来扩展和自定义 GitHub Copilot 代理行为。","product":"GitHub Copilot","breadcrumbs":[{"href":"/zh/copilot","title":"GitHub Copilot"},{"href":"/zh/copilot/concepts","title":"概念"},{"href":"/zh/copilot/concepts/agents","title":"智能体"},{"href":"/zh/copilot/concepts/agents/hooks","title":"钩子"}],"documentType":"article"},"body":"# 关于钩子 GitHub Copilot\n\n通过在代理执行过程中在关键点执行自定义 shell 命令来扩展和自定义 GitHub Copilot 代理行为。\n\n## 什么是钩子？\n\n挂钩是在代理工作流的战略点（例如代理会话开始或结束、输入提示时或调用工具时）执行自定义 shell 命令的方法。\n\n挂钩通过 JSON 输入接收有关代理操作的详细信息，从而启用上下文感知自动化。 例如，您可以使用钩子来：\n\n* 以编程方式批准或拒绝工具执行。\n* 使用内置安全功能（如机密扫描）来防止凭据泄漏。\n* 实现自定义验证规则和审核日志记录以实现符合性。\n\n挂钩可用于：\n\n* **Copilot cloud agent** 在 GitHub。\n* **GitHub Copilot CLI** 在终端中。\n\n可以在存储在存储库 `.github/hooks/*.json`中的 JSON 文件中定义挂钩。 每当 Copilot 存储库中使用代理时，这些都适用。\nCopilot CLI 还支持你可以在主目录中`~/.copilot/hooks/*.json`存储的个人钩子。 每当使用 Copilot CLI时，这些都适用。\n\n## 挂钩类型\n\n可以使用以下类型的挂钩：\n\n* **sessionStart**：在新代理会话开始或恢复现有会话时执行。 可用于初始化环境、日志会话开始用于审核、验证项目状态和设置临时资源。\n* **sessionEnd**：在代理会话完成或终止时执行。 可用于清理临时资源、生成和存档会话报告和日志，或发送有关会话完成的通知。\n* **userPromptSubmitted**：当用户向代理提交提示时执行。 可用于记录用户审核和使用情况分析的请求。\n* **preToolUse**：在代理使用任何工具（如 `bash`， `edit`，） `view`之前执行。 这是最强大的挂钩，因为它可以 **批准或拒绝工具执行**。 使用此挂钩程序可阻止危险命令、强制实施安全策略和编码标准、要求批准敏感操作，或记录工具使用情况以实现合规性。\n* **postToolUse**：在工具完成执行后执行（无论是成功还是失败）。 可用于记录执行结果、跟踪使用情况统计信息、生成审核线索、监视性能指标以及发送故障警报。\n* **agentStop**：在主代理完成对提示的响应后执行。\n* **subagentStop**：在子代理完成时执行，然后再将结果返回到父代理。\n* **errorOccurred**：在代理执行期间发生错误时执行。 可用于记录用于调试的错误、发送通知、跟踪错误模式和生成报告。\n\n若要查看具有示例用例、最佳做法和高级模式的挂钩类型的完整参考，请参阅 [GitHub Copilot 挂钩参考](/zh/copilot/reference/hooks-reference)。\n\n## 钩子配置格式\n\n使用特殊 JSON 格式配置钩子。 JSON 必须包含一个字段`version`，其值为`1`，并含有一个`hooks`对象，该对象包含挂钩定义的数组。\n\n```json copy\n{\n  \"version\": 1,\n  \"hooks\": {\n    \"sessionStart\": [\n      {\n        \"type\": \"command\",\n        \"bash\": \"string (optional)\",\n        \"powershell\": \"string (optional)\",\n        \"cwd\": \"string (optional)\",\n        \"env\": { \"KEY\": \"value\" },\n        \"timeoutSec\": 30\n      }\n    ],\n  }\n}\n```\n\n挂钩对象可以包含以下键：\n\n| 财产           | 必需             | Description           |\n| ------------ | -------------- | --------------------- |\n| `type`       | 是的             | 必须是 `\"command\"`       |\n| `bash`       | 是（在 Unix 系统上）  | 要执行的 bash 脚本的路径       |\n| `powershell` | 是（在 Windows 上） | 要执行的 PowerShell 脚本的路径 |\n| `cwd`        | 否              | 脚本的工作目录（相对于存储库根目录）    |\n| `env`        | 否              | 与现有环境合并的其他环境变量        |\n| `timeoutSec` | 否              | 最大执行时间（默认值：30）        |\n\n## 示例挂钩配置文件\n\n这是一个位于存储库中的 `~/.github/hooks/project-hooks.json` 中的示例配置文件。\n\n```json copy\n{\n  \"version\": 1,\n  \"hooks\": {\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    \"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    \"preToolUse\": [\n      {\n        \"type\": \"command\",\n        \"bash\": \"./scripts/security-check.sh\",\n        \"powershell\": \"./scripts/security-check.ps1\",\n        \"cwd\": \"scripts\",\n        \"timeoutSec\": 15\n      },\n      {\n        \"type\": \"command\",\n        \"bash\": \"./scripts/log-tool-use.sh\",\n        \"powershell\": \"./scripts/log-tool-use.ps1\",\n        \"cwd\": \"scripts\"\n      }\n    ],\n    \"postToolUse\": [\n      {\n        \"type\": \"command\",\n        \"bash\": \"cat >> logs/tool-results.jsonl\",\n        \"powershell\": \"$input | Add-Content -Path logs/tool-results.jsonl\"\n      }\n    ],\n    \"sessionEnd\": [\n      {\n        \"type\": \"command\",\n        \"bash\": \"./scripts/cleanup.sh\",\n        \"powershell\": \"./scripts/cleanup.ps1\",\n        \"cwd\": \"scripts\",\n        \"timeoutSec\": 60\n      }\n    ]\n  }\n}\n```\n\n## 性能注意事项\n\n挂钩同步运行并阻止代理执行。 若要确保响应式体验，请记住以下注意事项：\n\n* **最小化执行时间**：尽可能将挂钩执行时间保持在 5 秒以内。\n* **优化日志记录**：使用异步日志记录操作，例如将日志追加到文件中，而不是同步输入/输出操作。\n* **使用后台处理**：对于昂贵的操作，请考虑后台处理。\n* **缓存结果**：尽可能缓存昂贵的计算。\n\n## 安全注意事项\n\n若要确保在使用挂钩时保持安全性，请记住以下注意事项：\n\n* **始终验证并清理由钩子处理的输入**。 不受信任的输入可能导致意外行为。\n* **在构造命令时使用正确的 shell 转义措施**。 这可以防止命令注入漏洞。\n* **从不记录敏感数据，例如令牌或密码**。\n* **确保挂钩脚本和日志具有适当的权限**。\n* **请谨慎使用会进行外部网络调用的钩子**。 这可能会导致延迟、故障或向第三方公开数据。\n* **设置适当的超时以防止资源耗尽**。 长时间运行的挂钩可能会阻止代理执行并降低性能。\n\n## 后续步骤\n\n若要开始创建挂钩，请参阅：\n\n* [使用挂钩自定义代理工作流](/zh/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/use-hooks) 适用于 Copilot cloud agent\n* [与 GitHub Copilot CLI 一起使用挂钩](/zh/copilot/how-tos/copilot-cli/customize-copilot/use-hooks) 适用于 GitHub Copilot CLI"}