Hooks

步骤一：创建脚本

mkdir -p ~/.lingma/hooks
cat > ~/.lingma/hooks/block-rm.sh << 'EOF'
#!/bin/bash
input=$(cat)
command=$(echo "$input" | jq -r '.tool_input.command')

if echo "$command" | grep -q 'rm -rf'; then
  echo "危险命令已被阻止: $command" >&2
  exit 2
fi

exit 0
EOF
chmod +x ~/.lingma/hooks/block-rm.sh

步骤二：添加配置

在 ~/.lingma/settings.json 中添加：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "~/.lingma/hooks/block-rm.sh"
          }
        ]
      }
    ]
  }
}

步骤三：验证效果

重启 IDE，在Qoder CN面板中让 Agent 执行包含 rm -rf 的命令。Hook 会阻止执行，并把错误信息反馈给 Agent。

步骤一： 确定需求：选择事件和匹配范围

首先明确您要在哪个节点介入，以及匹配什么条件：

我想在「什么时候」拦截 / 处理「什么操作」？
        ↓                         ↓
     选择事件                  编写 matcher

步骤二：编写 Hook 脚本

Hook 脚本是一个标准的 shell 脚本，遵循以下协议：

• 输入：通过 stdin 接收 JSON 格式的事件上下文

• 输出：通过 exit code 控制行为

exit 0   →  放行（继续执行）
exit 2   →  阻断（停止操作，stderr 注入对话）
其他值   →  错误（继续执行，stderr 展示给用户）

脚本模板：

#!/bin/bash

# 1. 读取 stdin 的 JSON 输入
input=$(cat)

# 2. 用 jq 提取你关心的字段
#    不同事件有不同的字段，具体见「事件参考」章节
tool_name=$(echo "$input" | jq -r '.tool_name')
tool_input=$(echo "$input" | jq -r '.tool_input')

# 3. 编写你的判断逻辑
if [ "$tool_name" = "Bash" ]; then
  command=$(echo "$input" | jq -r '.tool_input.command')

  # 检查是否包含危险操作
  if echo "$command" | grep -qE 'rm\s+-rf|DROP\s+TABLE'; then
    # 阻断：exit 2 + stderr 消息会反馈给 Agent
    echo "操作被拒绝: $command" >&2
    exit 2
  fi
fi

# 4. 放行
exit 0

除了 exit code，您还可以在 exit 0时输出 JSON 来提供更精细的控制：

#!/bin/bash
input=$(cat)

# 输出 JSON 实现精细控制（仅 exit 0 时生效）
echo '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"该操作不被允许"}}'
exit 0

步骤三：注册到配置文件

将脚本路径写入配置文件的对应事件下：

{
  "hooks": {
    "事件名": [
      {
        "matcher": "匹配条件（可选）",
        "hooks": [
          {
            "type": "command",
            "command": "脚本路径"
          }
        ]
      }
    ]
  }
}

步骤四：测试与调试

可以直接在终端用管道模拟测试：

# 模拟 PreToolUse 事件
echo '{"tool_name":"Bash","tool_input":{"command":"rm -rf /"},"hook_event_name":"PreToolUse"}' \
  | ~/.lingma/hooks/block-rm.sh
echo "Exit code: $?"

检查 stderr 输出（阻断消息）：

echo '{"tool_name":"Bash","tool_input":{"command":"rm -rf /"}}' \
  | ~/.lingma/hooks/block-rm.sh 2>&1

配置文件位置

Hook 配置从以下文件加载，多级配置会被合并执行（优先级从低到高）：

配置格式

{
  "hooks": {
    "事件名": [
      {
        "matcher": "匹配条件",
        "hooks": [
          {
            "type": "command",
            "command": "要执行的命令"
          }
        ]
      }
    ]
  }
}

一个事件下可以配置多个 matcher 分组，每个分组可以包含多个 Hook 命令。

matcher 匹配规则

matcher 用于过滤 Hook 的触发范围，不同事件匹配不同的字段（见各事件说明）。

工具名映射

Qoder CN支持两套工具名——原生工具名与兼容工具名。配置 Hook 时可使用任意一套，运行时会统一映射后执行匹配。例如 matcher: "Bash" 和 matcher: "run_in_terminal" 等价。

输入

Hook 脚本通过 stdin 接收 JSON 数据。所有事件都包含以下通用字段：

不同事件会在此基础上附加额外字段（见下文事件参考）。用 jq 解析输入：

#!/bin/bash
input=$(cat)
tool_name=$(echo "$input" | jq -r '.tool_name')

输出

Hook 通过 exit code 和 stdout 控制行为。

exit code 决定基本行为：

stdout JSON（仅 exit 0 时生效，可选）：

{
  "continue": true,
  "stopReason": "",
  "suppressOutput": false,
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow | deny | ask",
    "permissionDecisionReason": "说明原因"
  }
}

UserPromptSubmit

• 触发：用户提交 Prompt 后、Agent 处理前

• 可阻断：是（exit 2 阻止本次请求）

• 额外字段：prompt（用户输入的原始文本）

PreToolUse

• 触发：工具调用执行前

• 可阻断：是（exit 2 拒绝本次工具调用）

• 匹配字段：tool_name

• 额外字段：tool_name、tool_input

PostToolUse

• 触发：工具调用成功后

• 可阻断：否

• 匹配字段：tool_name

• 额外字段：tool_name、tool_input、tool_response

PostToolUseFailure

• 触发：工具调用失败后

• 可阻断：否

• 匹配字段：tool_name

• 额外字段：tool_name、tool_input、error

Stop

• 触发：Agent 完成响应时

• 可阻断：否

• 额外字段：stop_hook_active、last_assistant_message

修改配置后为什么没生效？

当前版本不支持热加载，修改 settings.json 后需要重启 IDE。

Hook 脚本执行超时会怎样？

默认 30 秒超时，超时视为错误（继续执行，stderr 展示给用户）。

多个 Hook 执行顺序如何确定？

同一事件下按配置声明顺序执行；跨配置文件时，按「用户级 → 项目级 → 项目本地」优先级从低到高依次执行。

Hook 脚本能访问哪些环境变量？

Hook 在当前项目根目录（cwd）下以当前用户身份执行，继承 IDE 进程的环境变量。

如何查看 Hook 执行日志？

Hook 的 stderr 输出会反馈给 Agent 或用户；详细调用日志可在Qoder CN运行时日志中查找 [hook] 前缀的条目。