Copilot CLI Hooks 让你在 AI 操作的前后"插入"自定义脚本：AI 修改代码后自动跑 eslint，提交前自动跑测试，或者记录每次会话的操作日志。Hooks 通过项目目录下的 hooks.json 配置，不影响 Copilot 的核心行为，只是在特定时机触发你的脚本。

GitHub Copilot CLI Hooks：在会话关键节点自动执行自定义脚本

什么是 Hooks

Hooks 是在 Copilot CLI 会话生命周期的特定节点，自动执行你预定义的 Shell 命令或脚本的机制。

与 Claude Code 的 Hooks 概念相同：你不改变 AI 的行为逻辑，而是在 AI 动作的"前后"挂载自己的操作，实现自动化质量保证、日志记录或与现有工具链的集成。

配置文件

在项目目录（或 ~/.copilot/）创建 hooks.json 文件：

{
  "hooks": [
    {
      "event": "postToolUse",
      "command": "npm run lint:fix"
    },
    {
      "event": "sessionEnd",
      "command": "echo \"Session ended: $(date)\" >> logs/copilot-session.log"
    }
  ]
}

支持的 Hook 事件

事件	触发时机
sessionStart	CLI 会话启动时
sessionEnd	CLI 会话结束时
userPromptSubmitted	用户发送 Prompt 后、Copilot 处理前
preToolUse	Copilot 调用工具（如写文件）前
postToolUse	Copilot 调用工具后
errorOccurred	发生错误时

配置字段

每个 Hook 条目支持以下字段：

字段	必须	说明
event	✅	触发事件名称
command	✅	要执行的 Shell 命令（bash 或 PowerShell）
cwd	❌	命令的工作目录，默认为当前目录
timeoutSec	❌	命令超时时间（秒），超时后强制终止
env	❌	额外的环境变量（JSON 格式）

实用示例

代码修改后自动 Lint

{
  "hooks": [
    {
      "event": "postToolUse",
      "command": "npm run lint:fix",
      "timeoutSec": 30
    }
  ]
}

运行测试（超时保护）

{
  "hooks": [
    {
      "event": "postToolUse",
      "command": "npm test --passWithNoTests",
      "timeoutSec": 60
    }
  ]
}

记录会话操作日志

{
  "hooks": [
    {
      "event": "sessionStart",
      "command": "echo \"[$(date)] Copilot session started\" >> ~/.copilot/session.log"
    },
    {
      "event": "sessionEnd",
      "command": "echo \"[$(date)] Copilot session ended\" >> ~/.copilot/session.log"
    }
  ]
}

每次 Prompt 时检查 TypeScript 类型

{
  "hooks": [
    {
      "event": "postToolUse",
      "command": "npx tsc --noEmit",
      "timeoutSec": 30
    }
  ]
}

与自定义指令的区别

	Hooks	自定义指令
作用	执行外部脚本	为 AI 提供上下文信息
执行时机	特定事件触发	每次对话注入
适合场景	自动化质量检查、日志	项目规范、架构约定

调试技巧

• 在命令中加 echo 或写入日志文件，确认 Hook 是否被触发
• 使用 timeoutSec 防止 Hook 因子进程挂起而阻塞 Copilot
• 先在终端手动运行命令确认无误，再写入 hooks.json

常见问题

Q: Hooks 中的命令执行失败会影响 Copilot 的后续操作吗？

A: 默认情况下，Hook 执行失败（非零退出码）不会中断 Copilot 的工作流，但会在日志中记录错误。如果需要在某些情况下阻止操作继续，可以结合 preToolUse 事件实现门控逻辑。

Q: hooks.json 应该放在项目目录还是全局目录？

A: 项目相关的质量检查（如 npm test）放在项目目录的 hooks.json；通用的日志记录等放在 ~/.copilot/hooks.json。两个文件都存在时，都会生效。

Q: 这个 Hooks 系统和 Claude Code 的 Hooks 有什么区别？

A: 概念相同，但配置格式和事件名称有差异。Claude Code 使用 settings.json 中的 hooks 字段；Copilot CLI 使用独立的 hooks.json。两者的核心理念一致：在 AI 操作前后自动执行自定义逻辑。