# GitHub Copilot 的 Hook

在 Copilot 代理工作时，在预定义时机运行自己的检查、日志记录或其他命令。

## 什么是钩子？

挂钩是在代理工作流的战略点（例如代理会话开始或结束、输入提示时或调用工具时）执行自定义 shell 命令的方法。

挂钩通过 JSON 输入接收有关代理操作的详细信息，从而启用上下文感知自动化。 例如，您可以使用钩子来：

* 以编程方式批准或拒绝工具执行。
* 使用内置安全功能（如机密扫描）来防止凭据泄漏。
* 实现自定义验证规则和审核日志记录以实现符合性。

与自定义说明不同，钩子运行代码，而不是要求模型遵循规则。 例如，挂钩可以运行脚本，在工具请求执行前检查该请求。

## 可在何处使用钩子

钩子在以下功能中可用：

* **支持 GitHub Copilot app** 的功能，支持存储库挂钩和插件提供的挂钩。 请参阅“[自定义 GitHub Copilot 应用](/zh/copilot/how-tos/github-copilot-app/customize-github-copilot-app)”。
* **GitHub Copilot CLI**，其中命令在其执行环境中运行。
* **Copilot cloud agent**，其中命令在代理的云环境中运行。 仅支持一部分事件。
* **Visual Studio Code**，其中 Hooks 体验位于 公开预览。 支持的事件和配置取决于运行会话的代理。 请参阅[VS Code中的Agent hooks](https://code.visualstudio.com/docs/agent-customization/hooks)。

下面的配置和示例介绍了用于 Copilot CLI 和 Copilot cloud agent 的挂钩。 不要假定同一事件、输入或输出在不同界面上都能原样工作。

对于  和 ，可以在  中定义存储库挂钩。
Copilot CLI还支持`~/.copilot/hooks/*.json`中的个人钩子。 有关执行环境、其他附加位置和事件支持，请参阅 [GitHub Copilot 挂钩参考](/zh/copilot/reference/hooks-reference)。

## 挂钩类型

这些是挂钩事件的示例 Copilot CLI 。
Copilot cloud agent 支持以下部分内容：

* **sessionStart**：在新代理会话开始或恢复现有会话时执行。 可用于初始化环境、日志会话开始用于审核、验证项目状态和设置临时资源。
* **sessionEnd**：在代理会话完成或终止时执行。 可用于清理临时资源、生成和存档会话报告和日志，或发送有关会话完成的通知。
* **userPromptSubmitted**：当用户向代理提交提示时执行。 可用于记录用户审核和使用情况分析的请求。
* **preToolUse**：在代理使用任何工具（如 `bash`， `edit`，） `view`之前执行。 这是最强大的挂钩，因为它可以 **批准或拒绝工具执行**。 使用此挂钩程序可阻止危险命令、强制实施安全策略和编码标准、要求批准敏感操作，或记录工具使用情况以实现合规性。
* **postToolUse**：在工具完成执行后执行（无论是成功还是失败）。 可用于记录执行结果、跟踪使用情况统计信息、生成审核线索、监视性能指标以及发送故障警报。
* **agentStop**：在主代理完成对提示的响应后执行。
* **subagentStop**：在子代理完成时执行，然后再将结果返回到父代理。
* **errorOccurred**：在代理执行期间发生错误时执行。 可用于记录用于调试的错误、发送通知、跟踪错误模式和生成报告。

Hook 参考列出了完整的事件集及其在 Copilot cloud agent 中的可用性。

## 钩子配置格式

使用特殊 JSON 格式配置钩子。 JSON 必须包含一个字段`version`，其值为`1`，并含有一个`hooks`对象，该对象包含挂钩定义的数组。

```json copy
{
  "version": 1,
  "hooks": {
    "sessionStart": [
      {
        "type": "command",
        "bash": "string (optional)",
        "powershell": "string (optional)",
        "cwd": "string (optional)",
        "env": { "KEY": "value" },
        "timeoutSec": 30
      }
    ]
  }
}
```

挂钩对象可以包含以下键：

| Property     | Required       | Description           |
| ------------ | -------------- | --------------------- |
| `type`       | Yes            | 必须是 `"command"`       |
| `bash`       | 是（在 Unix 系统上）  | 要执行的 bash 脚本的路径       |
| `powershell` | 是（在 Windows 上） | 要执行的 PowerShell 脚本的路径 |
| `cwd`        | No             | 脚本的工作目录（相对于存储库根目录）    |
| `env`        | No             | 与现有环境合并的其他环境变量        |
| `timeoutSec` | No             | 最大执行时间（默认值：30）        |

## 示例挂钩配置文件

这是一个位于存储库中的 `.github/hooks/project-hooks.json` 中的示例配置文件。

```json copy
{
  "version": 1,
  "hooks": {
    "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
      }
    ],
    "userPromptSubmitted": [
      {
        "type": "command",
        "bash": "./scripts/log-prompt.sh",
        "powershell": "./scripts/log-prompt.ps1",
        "cwd": "scripts",
        "env": {
          "LOG_LEVEL": "INFO"
        }
      }
    ],
    "preToolUse": [
      {
        "type": "command",
        "bash": "./scripts/security-check.sh",
        "powershell": "./scripts/security-check.ps1",
        "cwd": "scripts",
        "timeoutSec": 15
      },
      {
        "type": "command",
        "bash": "./scripts/log-tool-use.sh",
        "powershell": "./scripts/log-tool-use.ps1",
        "cwd": "scripts"
      }
    ],
    "postToolUse": [
      {
        "type": "command",
        "bash": "cat >> logs/tool-results.jsonl",
        "powershell": "$input | Add-Content -Path logs/tool-results.jsonl"
      }
    ],
    "sessionEnd": [
      {
        "type": "command",
        "bash": "./scripts/cleanup.sh",
        "powershell": "./scripts/cleanup.ps1",
        "cwd": "scripts",
        "timeoutSec": 60
      }
    ]
  }
}
```

## 性能注意事项

挂钩同步运行并阻止代理执行。 若要确保响应式体验，请记住以下注意事项：

* **最小化执行时间**：尽可能将挂钩执行时间保持在 5 秒以内。
* **优化日志记录**：使用异步日志记录操作，例如将日志追加到文件中，而不是同步输入/输出操作。
* **使用后台处理**：对于昂贵的操作，请考虑后台处理。
* **缓存结果**：尽可能缓存昂贵的计算。

## 安全注意事项

若要确保在使用挂钩时保持安全性，请记住以下注意事项：

* **始终验证并清理由钩子处理的输入**。 不受信任的输入可能导致意外行为。
* **在构造命令时使用正确的 shell 转义措施**。 这可以防止命令注入漏洞。
* **从不记录敏感数据，例如令牌或密码**。
* **确保挂钩脚本和日志具有适当的权限**。
* **请谨慎使用会进行外部网络调用的钩子**。 这可能会导致延迟、故障或向第三方公开数据。
* **设置适当的超时以防止资源耗尽**。 长时间运行的挂钩可能会阻止代理执行并降低性能。

## 后续步骤

若要开始创建挂钩，请参阅：

* [使用挂钩自定义代理工作流](/zh/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/use-hooks) 适用于 Copilot cloud agent
* [与 GitHub Copilot CLI 一起使用挂钩](/zh/copilot/how-tos/copilot-cli/customize-copilot/use-hooks) 适用于 GitHub Copilot CLI