VS Code Copilot Chat 中的 Hooks 定制：创建 `.github/hooks/` 钩子以强制执行策略与自动化 Agent 生命周期

VS Code Copilot Chat 中的 Hooks 定制：创建.github/hooks/钩子以强制执行策略与自动化 Agent 生命周期

【免费下载链接】vscode-copilot-chatCopilot Chat extension for VS Code项目地址: https://gitcode.com/gh_mirrors/vs/vscode-copilot-chat

本篇技术指南聚焦 VS Code Copilot Chat 的Hooks（钩子）定制能力：它如何通过.json配置文件在 Agent 会话的生命周期节点上挂载确定性命令，用于强制执行团队策略、自动化校验和注入运行时上下文。文章以仓库中的 create-hook.prompt.md 提示词为工作流骨架，结合 hooks.md 参考文档的完整配置契约，并佐证以 hookExecutor.ts 等源码实现。读完本文，你将掌握从对话中提炼策略需求、设计 hook JSON、编写配套脚本、理解 stdin/stdout 与退出码契约，以及测试与迭代钩子的完整实战能力。

一、Hook 是什么：Agent 生命周期上的确定性自动化

Hooks 是 VS Code Copilot Chat Agent 定制体系中的一种原语，用于对 Agent 会话进行确定性的生命周期自动化。与 Instructions、Prompts、Skills、Agents 等"指导性（非确定性）"原语不同，Hook 通过执行外部 shell 命令在特定生命周期事件点强制行为——例如阻止危险命令、强制运行校验、自动注入上下文。

从仓库源码看，hook 的职责被严格定义为运行时强制与确定性自动化：hookExecutor.ts 中定义了IHookExecutor服务接口，其职责是"执行单个 hook 命令，向 stdin 写入 JSON 输入并捕获 stdout/stderr"。而 SKILL.md 的决策流程表中对 Hook 的定位是："在 Agent 生命周期节点上执行的确定性 shell 命令（阻止工具调用、自动格式化、注入上下文）"。

选择 Hook 而非普通指令的判据在于：当行为必须被保证（例如阻止危险命令、强制校验、自动注入上下文）时使用 Hook；仅靠提示文本"建议"Agent 去做某件事并不够时，就需要用 Hook 强制执行。

二、Hook 文件的存放位置与生效范围

参考 hooks.md，Hook 配置存放于以下位置：

关键行为：来自所有配置位置的 Hook 会被收集并全部执行，工作区与用户级 Hook 之间不存在互相覆盖的关系。这意味着一方面 Hook 具备叠加效应——团队策略（工作区）与个人自动化（用户级）可以同时生效；另一方面也要求你设计 Hook 时考虑叠加执行后的可预期性。

在 create-hook.prompt.md 中，创建向导明确将钩子引导到.github/hooks/目录下创建——这是团队共享策略的首选位置。如果需要个人化的跨工作区自动化，则应使用用户配置文件。

三、Hook 事件：可以挂在哪些生命周期节点

Hook 支持在以下生命周期事件上触发（来源：hooks.md）：

这八个事件覆盖了会话从开始到结束、从主 Agent 到子 Agent、从工具调用前到调用后的完整生命周期。设计 Hook 时的第一件事，就是确定你的策略/自动化需求应该挂在哪个事件上。

四、create-hook 工作流第一步：从对话中提取策略需求

create-hook.prompt.md 给出的创建流程，第一步是回顾对话历史。如果用户反复表达对 Agent 行为的关切（例如"不要运行这个命令""做 X 之前总是先检查""注入这个上下文"），就应该把这些关切**泛化（generalize）**为一条 Hook 策略。需要提取的内容有三类：

• 应被阻止或设闸（gated）的操作（Actions that should be blocked or gated）——例如不允许 Agent 直接执行git push或rm -rf这类高风险命令，应映射到PreToolUse事件上做权限决策；
• 应在特定节点注入的上下文（Context that should be injected at certain points）——例如每次会话开始或每次工具调用时注入当前分支、环境变量、构建状态等运行时信息，应映射到SessionStart、UserPromptSubmit或PreToolUse等节点，通过输出的additionalContext字段实现；
• 会话开始/结束或工具使用时的自动化需求（Automation needs at session start/end or tool use）——例如会话结束时自动运行清理脚本，或工具调用后自动格式化产物，应映射到SessionStart、Stop、PostToolUse等事件。

五、create-hook 工作流第二步：澄清关键决策点

如果从对话中无法明确浮现出清晰的策略需求，创建向导会向用户澄清以下三个核心问题（对应 create-hook.prompt.md 的 "Clarify if Needed" 章节）：

1. 什么事件应触发这条 Hook？（例如PreToolUse、SessionStart、Stop）——事件决定挂载点，直接对应上一节的生命周期事件表；
2. 它应该阻止（block）、警告（warn）还是注入上下文（inject context）？——行为模式决定输出契约：阻止对应permissionDecision: 'deny'，警告对应permissionDecision: 'ask'或非阻塞退出码，注入对应additionalContext字段；
3. 它是否需要配套脚本（companion script）？——复杂校验逻辑通常无法内联在 JSON 里，需要独立的 shell 脚本，JSON 中的command字段指向该脚本。

这三个问题的答案共同决定 Hook 的形态：一个 JSON 条目 + 可能的一个或多个脚本文件。

六、create-hook 工作流第三步：迭代起草与完善

起草与完善是一个迭代过程，create-hook.prompt.md 给出了三步循环：

1. 起草 Hook JSON（以及任何需要的脚本）并保存到.github/hooks/下；
2. 识别最模糊或最薄弱的部分，就这些点提问——不要一次问完所有问题，而是针对草稿中真正不确定的地方（例如退出码策略、权限决策的默认值、跨平台命令差异）进行聚焦澄清；
3. 定稿后总结：概括这条 Hook 强制了什么行为，建议如何测试，并提议接下来还可以创建哪些相关的定制（例如配套的 Instructions、Prompt 或 Agent）。

6.1 配置格式详解

Hook 配置文件的核心结构如下（完整示例来自 hooks.md）：

{ "hooks": { "PreToolUse": [ { "type": "command", "command": "./scripts/validate-tool.sh", "timeout": 15 } ] } }

每个 hook 命令支持以下字段：

• type：必须是command；
• command：默认要执行的命令；
• windows、linux、osx：平台覆盖命令，可在不同操作系统上指定不同实现；
• cwd：命令工作目录；从 NodeHookExecutor 源码 可见，未指定时默认使用用户主目录（homedir()）；
• env：传递给命令的附加环境变量，源码中通过{ ...process.env, ...hook.env }与当前进程环境合并；
• timeout：超时秒数。注意源码中的默认值：DEFAULT_TIMEOUT_SEC = 30（30 秒），超时后子进程会被终止（SIGKILL_DELAY_MS = 5000表示发送终止信号后额外等待 5 秒再强制 kill）。

6.2 输入 / 输出契约：JSON 进出

Hook 命令通过stdin 接收 JSON 输入，通过 stdout 返回 JSON 输出。这是 Agent 与外部脚本之间的标准化协议。仓库 hookCommandTypes.ts 给出了类型层面的精确契约：

PreToolUse 的 stdin 输入包含：

{ "tool_name": "要调用的工具名", "tool_input": "工具的输入参数", "tool_use_id": "本次工具调用的唯一 ID" }

PostToolUse 的 stdin 输入比 PreToolUse 多一个tool_response字段（工具执行后的响应内容），即四个字段：tool_name、tool_input、tool_response、tool_use_id。

公共输出字段（所有 Hook 通用）：

• continue：是否继续；
• stopReason：停止原因——从 hookResultProcessor.ts 可见，当结果包含stopReason时会抛出HookAbortError（"Hook ${hookType} aborted: ${stopReason}"）终止当前处理；
• systemMessage：系统消息。

PreToolUse 权限决策从hookSpecificOutput.permissionDecision读取，取值为allow|ask|deny：

{ "hookSpecificOutput": { "hookEventName": "PreToolUse", "permissionDecision": "ask", "permissionDecisionReason": "Needs user confirmation" } }

类型定义 IPreToolUseHookSpecificCommandOutput 还包含updatedInput（修改后的工具输入）和additionalContext（附加注入的上下文）两个可选字段。PostToolUse的输出可以通过decision: block阻止后续处理，其类型定义同样支持additionalContext用于在工具执行后注入上下文。

6.3 退出码语义：成功、阻塞错误与非阻塞警告

Hook 命令的退出码决定了执行结果如何被处理（来源：hooks.md 与 hookExecutor.ts 源码）：

• 退出码0：成功；stdout 若为合法 JSON 则按对象解析，否则按字符串处理；
• 退出码2：阻塞错误（blocking error）；错误信息会展示给模型，终止当前流程；
• 其他非零退出码：非阻塞警告；仅展示给用户，不阻塞流程。

源码中的HookCommandResultKind枚举（Success/Error/NonBlockingError）正是对这三类结果的建模。此外有一个重要的边界细节：进程被信号终止等没有数值退出码的情况会被归一化为退出码1（即非阻塞警告）；而命令本身无法启动（如命令不存在）时，NodeHookExecutor 会将其捕获为"非阻塞警告"而非硬错误。

另一个值得一提的源码细节：对于SessionStart/SubagentStart这类"开始型"事件，hookResultProcessor.ts 提供了ignoreErrors选项，当为true时错误和stopReason会被完全忽略（不抛错、不警告、不显示进度）——因为会话开始时的阻塞错误没有意义，应当静默吞掉；而对Stop/SubagentStop这类"结束型"事件，错误会通过onError回调被收集为阻塞原因。这意味着同一套退出码语义在不同事件上的处理策略是不同的，设计 Hook 时需要了解目标事件的错误处理行为。

七、测试你的 Hook：验证策略真的被强制执行

create-hook.prompt.md 要求定稿后"建议测试方式"。测试 Hook 可以从以下维度展开：

1. 单测脚本本身：直接用固定 JSON 输入管道测试脚本，例如：

   echo '{"tool_name":"Git","tool_input":{"command":"push"},"tool_use_id":"t1"}' | ./scripts/validate-tool.sh

   检查 stdout 输出的 JSON 是否符合契约、退出码是否符合预期（0/2/ 其他）；

2. 在真实会话中触发：在 VS Code Copilot Chat 中发起会触发该事件的操作（如让 Agent 执行被 Hook 拦截的命令），观察是否出现预期的权限决策提示、阻塞消息或注入的上下文；
3. 验证输出契约的三种行为：分别测试allow/ask/deny三种permissionDecision，确认 UI 行为符合预期；测试非阻塞警告（退出码非 0 非 2）与阻塞错误（退出码 2）的区别；
4. 检查超时与平台差异：如果脚本可能执行较久，验证timeout生效；如果配置了windows/linux/osx平台覆盖，分别在目标平台上验证；
5. 错误处理验证：故意让命令启动失败（例如指向不存在的脚本），确认它被按非阻塞警告处理而非中断整个会话。

八、设计原则与反模式

hooks.md 给出了四条核心原则：

1. 保持 Hook 小而可审计（Keep hooks small and auditable）——Hook 是确定性强制机制，代码越简单越容易审查其行为；
2. 校验并净化 Hook 输入（Validate and sanitize hook inputs）——stdin 输入来自不可信的模型上下文，脚本必须做输入校验；
3. 避免在脚本中硬编码密钥（Avoid hardcoded secrets in scripts）——Hook 脚本与配置文件通常提交到仓库，硬编码密钥会直接泄露；
4. 团队策略优先用工作区 Hook，个人自动化用用户级 Hook——对应配置文件的位置选择。

同时要避免以下反模式：

• 运行长时间阻塞的 Hook——这会阻塞正常流程（默认超时 30 秒、超时强制 kill 正是为了兜底此类问题）；
• 在纯指令（Instructions）足够的情况下使用 Hook——过度使用确定性强制会增加复杂性和维护成本；
• 让 Agent 在没有审批控制的情况下编辑 Hook 脚本——Hook 是策略强制点，让被约束的对象随意修改约束本身就是安全漏洞。

九、Hook 与其他定制原语的协同

在 Agent 定制体系中，Hook 与其余原语各司其职（决策流程详见 SKILL.md）：

选型判断可以参考：

• Instructions vs Hooks：Instructions引导Agent 行为（非确定性）；Hooks强制行为——需要阻塞操作、要求审批或确定性运行格式化器时用 Hook；
• Hooks vs MCP：MCP 用于集成外部系统、API 或数据；Hook 用于生命周期节点上的确定性命令执行；
• Hooks vs Skills：Skills 是按需执行的打包工作流（含脚本/模板）；Hooks 是自动挂载在生命周期事件上的强制点。

在 create-hook.prompt.md 的收尾步骤中，向导还会"提议接下来创建哪些相关定制"——一条新 Hook 落地后，往往需要配套的 Instructions（说明策略意图）、Prompt（触发特定任务）或 Agent（隔离上下文）才能形成完整的定制闭环，这正是 Hook 在定制体系中的协同价值所在。

十、总结

创建 Hook 的本质是一个"从需求到强制策略"的转化过程：从对话中提炼出应被阻止的操作、应注入的上下文、应自动化的环节 → 澄清事件挂载点、行为模式与配套脚本 → 起草 JSON 并迭代完善 → 依据 stdin/stdout JSON 契约与退出码语义测试验证。整个过程由 create-hook.prompt.md 作为 Agent 侧的工作流模板，由 hooks.md 提供完整的配置契约，并由 hookExecutor.ts、hookCommandTypes.ts、hookResultProcessor.ts 等源码落实执行语义。掌握了这套流程，你就可以为团队工作区构建可审计、可叠加、确定性的 Agent 行为约束层。

【免费下载链接】vscode-copilot-chatCopilot Chat extension for VS Code项目地址: https://gitcode.com/gh_mirrors/vs/vscode-copilot-chat