> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devin.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 钩子

> 在会话期间发生特定事件时运行自定义逻辑

钩子 让你能够在 Agent 生命周期中的特定事件发生时运行自定义逻辑。你可以使用 钩子 来强制执行策略、添加上下文、记录操作、修改权限，或与外部系统集成。

钩子 使用 JSON 格式进行配置。请将它们放在你项目的 `.devin/` 目录 (或用户级配置) 中，Devin CLI 会在匹配的生命周期事件发生时运行它们。`.claude/` 目录中的现有 钩子 也会被自动识别——请参阅 [Where Hooks Live](#where-hooks-live)。

***

<div id="what-can-hooks-do">
  ## Hooks 有什么作用？
</div>

<CardGroup cols={2}>
  <Card title="执行策略" icon="shield">
    阻止危险命令、要求对特定操作进行确认，或限制文件访问。
  </Card>

  <Card title="添加上下文" icon="message">
    在调用特定工具时注入额外指示或信息。
  </Card>

  <Card title="触发副作用" icon="bolt">
    在事件发生时执行脚本、发送通知或记录日志。
  </Card>

  <Card title="修改权限" icon="lock">
    根据具体情况动态授予或限制权限。
  </Card>
</CardGroup>

***

<div id="quick-example">
  ## 快速示例
</div>

在你的项目中创建 `.devin/hooks.v1.json`：

```json theme={null}
{
  "PreToolUse": [
    {
      "matcher": "exec",
      "hooks": [
        {
          "type": "command",
          "command": "./scripts/check-command.sh"
        }
      ]
    }
  ]
}
```

这会在每次执行 shell 命令前运行 `./scripts/check-command.sh`。该脚本会通过 stdin 接收事件数据，并可通过返回非零退出码来阻止该操作。

***

<div id="hook-events">
  ## Hook 事件
</div>

Hook 可以响应以下生命周期事件：

| 事件                  | 触发时机        |
| ------------------- | ----------- |
| `PreToolUse`        | 工具执行前       |
| `PostToolUse`       | 工具完成后       |
| `PermissionRequest` | 需要做出权限决策时   |
| `UserPromptSubmit`  | 用户提交消息时     |
| `Stop`              | Agent 想要停止时 |
| `SessionStart`      | 会话开始时       |
| `SessionEnd`        | 会话结束时       |

有关各个事件及其可用数据的详细信息，请参阅[生命周期 Hook](/zh/cli/extensibility/hooks/lifecycle-hooks)。

***

<div id="hook-format">
  ## 钩子格式
</div>

每个钩子都有一个**类型** (`command` 或 `prompt`) 、一个可选的**匹配器** (用于匹配钩子事件 `tool_name` 的正则表达式) ，以及配置：

```json theme={null}
{
  "PreToolUse": [
    {
      "matcher": "exec",
      "hooks": [
        {
          "type": "command",
          "command": "./scripts/validate.sh",
          "timeout": 10
        }
      ]
    }
  ]
}
```

| Field     | 说明                                                             |
| --------- | -------------------------------------------------------------- |
| `matcher` | 用于匹配 hook 事件 `tool_name` 的正则表达式。空字符串或省略 `matcher` 时，会匹配所有工具名称。 |
| `type`    | `"command"` 表示运行 shell 命令，`"prompt"` 表示评估 LLM 提示。              |
| `command` | 要运行的 shell 命令 (用于 `command` 类型) 。                              |
| `prompt`  | 要评估的 LLM 提示 (用于 `prompt` 类型) 。                                 |
| `timeout` | 超时时间 (以秒为单位，可选) 。                                              |

<div id="command-hooks">
  ### 命令钩子
</div>

命令钩子会执行 shell 命令。事件数据会以 JSON 格式通过 **stdin** 传入，命令也可以通过 **stdout** 返回 JSON 来控制执行结果 (请参阅下方的[输出格式](#output-format)) 。

**输入** (stdin) ：

```json theme={null}
{
  "hook_event_name": "PreToolUse",
  "tool_name": "exec",
  "tool_input": {
    "command": "rm -rf /"
  }
}
```

`DEVIN_PROJECT_DIR` 环境变量会自动设置为项目根目录。

内置工具名称以及可匹配的 MCP 工具名称格式，请参阅[使用 Matcher](/zh/cli/extensibility/hooks/lifecycle-hooks#using-the-matcher)。

<div id="output-format">
  ### 输出格式
</div>

命令钩子可以将 JSON 对象打印到 **stdout**，以控制执行结果。

要批准或阻止某个 action，请返回顶层的 `decision` (可选附带 `reason`) ：

```json theme={null}
{
  "decision": "block",
  "reason": "Destructive command blocked by policy"
}
```

要向 Agent 的上下文中注入文本，请在以该事件名称标记的 `hookSpecificOutput` 对象中返回 `additionalContext`：

```json theme={null}
{
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": "Remember: deploys require an approved change ticket."
  }
}
```

| 输出字段                                   | 说明                                                                     |
| -------------------------------------- | ---------------------------------------------------------------------- |
| `decision`                             | 用 `"approve"` 允许该操作，或用 `"block"` 阻止该操作                                 |
| `reason`                               | 显示给 Agent 的解释                                                          |
| `hookSpecificOutput.hookEventName`     | 该输出适用的事件 (例如 `UserPromptSubmit`、`SessionStart`、`PostToolUse`)          |
| `hookSpecificOutput.additionalContext` | 注入到 Agent 上下文中的文本 (用于 `UserPromptSubmit`、`SessionStart`、`PostToolUse`) |

<div id="exit-codes">
  ### 退出代码
</div>

| 代码 | 含义              |
| -- | --------------- |
| 0  | 成功——hook 正常继续执行 |
| 2  | 阻止——操作被拒绝       |
| 其他 | 错误——会被记录，但不会阻止  |

***

<div id="where-hooks-live">
  ## Hooks 的存放位置
</div>

Devin CLI 会从以下位置读取 hooks。它们都使用相同的 JSON 格式。

<div id="project-level">
  ### 项目级
</div>

| 位置                            | 说明                               |
| ----------------------------- | -------------------------------- |
| `.devin/hooks.v1.json`        | 独立的 hooks 文件 (推荐)                |
| `.devin/config.json`          | 配置文件中的 `"hooks"` 键               |
| `.devin/config.local.json`    | `"hooks"` 键 (本地覆盖，已加入 gitignore) |
| `.claude/settings.json`       | `"hooks"` 键 (Claude Code 格式)     |
| `.claude/settings.local.json` | `"hooks"` 键 (Claude Code 格式)     |

<div id="user-level-global">
  ### 用户级 (全局)
</div>

| 位置                                                                       | 说明                            |
| ------------------------------------------------------------------------ | ----------------------------- |
| `~/.config/devin/config.json` (Windows 上为 `%APPDATA%\devin\config.json`) | 用户配置中的 `"hooks"` 密钥           |
| `~/.claude.json`                                                         | `"hooks"` 密钥 (Claude Code 格式) |
| `~/.claude/settings.json`                                                | `"hooks"` 密钥 (Claude Code 格式) |
| `~/.claude/settings.local.json`                                          | `"hooks"` 密钥 (Claude Code 格式) |

<Note>
  在 `.devin/hooks.v1.json` 中，hooks 对象就是**整个文件** (无需外层包装密钥) 。在其他所有位置，hooks 都位于设置文件中的 `"hooks"` 密钥下。
</Note>

<Note>
  启用 `read_config_from.claude` 时 (默认启用) ，会加载来自 `.claude/` 路径的 hooks。如有需要，你可以在[用户配置](/zh/cli/reference/configuration/read-config-from)中禁用此功能。
</Note>

***

<div id="verifying-hooks">
  ## 检查 Hooks
</div>

使用 `/hooks` 斜杠命令，查看当前已加载的所有 Hooks 及其源文件：

```
/hooks
```

***

<div id="next-steps">
  ## 后续步骤
</div>

<CardGroup cols={2}>
  <Card title="生命周期钩子" icon="rotate" href="/zh/cli/extensibility/hooks/lifecycle-hooks">
    深入了解各类事件及其可用数据。
  </Card>

  <Card title="配置" icon="gear" href="/zh/cli/reference/configuration/read-config-from">
    控制 Devin CLI 从哪些配置位置读取钩子配置。
  </Card>
</CardGroup>