Copilot Cloud Agent Hooks 让你在 AI 工作流的关键节点插入自定义逻辑：会话开始时初始化环境、工具调用前做权限检查、工具调用后运行 lint、会话结束时提交日志。配置在 .github/hooks/hooks.json，支持 Bash 和 PowerShell 双平台。

GitHub Copilot Cloud Agent Hooks：在任务执行节点插入自定义逻辑

什么是 Hooks

Hooks 允许你在 Copilot Cloud Agent 执行流程的特定时间点运行自定义 Shell 命令。常见用途：

• 强制执行代码规范（lint、format）
• 记录会话日志
• 安全检查（防止敏感操作）
• 通知外部系统

配置文件位置

在仓库的 .github/hooks/hooks.json（合并到默认分支后生效）。

Copilot CLI 中的 hooks 放在工作目录下。

基本格式

{
  "version": 1,
  "hooks": {
    "sessionStart": [],
    "sessionEnd": [],
    "userPromptSubmitted": [],
    "preToolUse": [],
    "postToolUse": [],
    "errorOccurred": []
  }
}

Hook 事件类型

事件	触发时机
sessionStart	会话启动时
sessionEnd	会话结束时
userPromptSubmitted	用户提交每条提示词后
preToolUse	工具调用前（可用于权限拦截）
postToolUse	工具调用后（可用于质量检查）
errorOccurred	发生错误时

配置示例

记录会话日志

{
  "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
      }
    ]
  }
}

工具调用后运行 Lint

{
  "hooks": {
    "postToolUse": [
      {
        "type": "command",
        "bash": "npm run lint --silent 2>&1 | head -20",
        "powershell": "npm run lint --silent 2>&1 | Select-Object -First 20",
        "timeoutSec": 30
      }
    ]
  }
}

调用脚本（复杂逻辑）

{
  "hooks": {
    "userPromptSubmitted": [
      {
        "type": "command",
        "bash": "./scripts/log-prompt.sh",
        "powershell": "./scripts/log-prompt.ps1",
        "cwd": "scripts",
        "env": {
          "LOG_LEVEL": "INFO"
        }
      }
    ]
  }
}

故障排查

Hooks 不执行时检查：

• JSON 文件路径是否正确：.github/hooks/hooks.json
• JSON 语法是否有效（推荐用 JSON 校验工具检查）
• 是否设置了 "version": 1
• Shell 脚本是否有执行权限（chmod +x），是否有 shebang 行

Hooks 超时：

增加 timeoutSec 值，或优化脚本执行速度。

本地调试脚本：

echo '{"timestamp":1704614400000,"cwd":"/tmp"}' | ./my-hook.sh

在脚本开头加 set -x 开启详细日志。

常见问题

Q: Hooks 和 Copilot CLI 的 Hooks 是同一套配置吗？

A: 格式相同，但位置不同。Cloud Agent Hooks 放在 .github/hooks/hooks.json；CLI Hooks 放在工作目录（可以通过 CLI 设置或 ~/.copilot/hooks.json）。

Q: preToolUse Hook 可以阻止工具执行吗？

A: 可以。如果 preToolUse Hook 返回非零退出码，工具调用会被阻止，Copilot 会收到错误信息并调整执行方案。

Q: Hook 脚本的标准输出会影响 Copilot 的行为吗？

A: 一般不会直接影响。但如果脚本输出格式化的 JSON，某些情况下 Copilot 可能会读取这些数据。建议 Hooks 脚本的副作用（日志写入等）明确且可控。