配置云端 Hooks

从默认分支加载 Hook，核对非交互环境、文件路径和执行平台。

This page has not been translated into English yet. The original Chinese version is shown below.

云端 Hooks 在会话与工具事件发生时运行命令或 HTTP 请求，适合固定校验、审计和补充上下文。它们与项目初始化用的 setup steps 不同：后者在代理开始工作前准备环境。

配置文件

将 JSON 放在仓库根目录的 .github/hooks/ 中，例如 .github/hooks/context.json。文件必须合入默认分支，才会用于 cloud agent。

下面在会话开始时提供一条上下文提示，按官方配置与输出字段组织：

{
  "version": 1,
  "hooks": {
    "sessionStart": [
      {
        "type": "command",
        "bash": "printf '%s\\n' '{\"additionalContext\":\"Report the validation performed before completing the task.\"}'",
        "cwd": ".",
        "timeoutSec": 5
      }
    ]
  }
}

示例只注入说明，不会自行运行测试；实际校验需要实现相应脚本，并使用合适的事件和返回值。

云端与 CLI 的差别

项目	云端 Hooks 参考规定
加载来源	已克隆仓库中的 `.github/hooks/*.json`
用户配置、settings.json、插件	默认云端环境没有这些来源；云端不加载 settings.json
Policy Hooks	不支持，是 CLI 能力
执行方式	Linux，使用 `bash`；`command` 作为后备；忽略 `powershell`
`exec` / `args` 直接执行	仅 CLI 支持
交互	非交互，工具权限已预授予，没有权限弹窗或系统通知
prompt 类型 Hook	参考称非交互任务可能不触发，不能依赖其必然运行

通用创建教程展示 Bash 与 PowerShell，开发环境专题还支持 Windows runner；但专门 Hooks 参考明确其云端实现为 Linux、忽略 PowerShell。这些来源未解释自定义 Windows runner 下的 Hook 支持关系，本文不把跨平台模板当作已验证保证。

工作目录与输出

参考列出克隆仓库时工作目录为 /workspace，否则 /root；HOME 为 /root。这些描述针对该参考的云端 Hook 环境。使用 cwd 或脚本相对路径时，要根据实际任务日志核对，而不是照搬本地绝对路径。

文件系统随任务结束销毁；仅写日志文件不会使日志永久保留。需要外部留存时，可配置适当的 HTTP 接收端，并满足网络允许规则。

参考列出 COPILOT_AGENT_PROMPT 为任务初始提示，并说明设置了 GITHUB_COPILOT_API_TOKEN、GITHUB_COPILOT_GIT_TOKEN，没有 GITHUB_TOKEN。脚本不要输出 token 或原始敏感输入来诊断环境。

配置校验与禁用

JSON、version 或事件列表结构错误会拒绝整个文件；某一个 Hook 条目错误只会跳过该条目，其他有效条目仍加载。

在单个文件顶层设置 disableAllHooks: true，只跳过该文件的 Hooks。CLI 的 repository settings.json 全局禁用方式不能套用到云端。

事件选择见云端 Hook 事件，阻止工具和错误行为见权限与失败处理。