Hook 基础与内置 Hook

约 1294 字大约 4 分钟

2026-03-19

NcatBot 的请求处理中间件——在事件处理器执行前后拦截、过滤、增强行为，以及开箱即用的内置 Hook 和参数绑定。

概述

Hook 是 NcatBot 的中间件机制，可以在事件处理器（Handler）执行的不同阶段插入逻辑：

常见用途：过滤（按关键词、权限拦截）、日志、错误处理、参数注入。

Hook 三阶段模型

阶段	`HookStage`	触发时机	可返回的 Action
前置	`BEFORE_CALL`	Handler 执行之前	`CONTINUE`（继续）/ `SKIP`（跳过 Handler）
后置	`AFTER_CALL`	Handler 执行之后	`CONTINUE`
错误	`ON_ERROR`	Handler 执行异常时	`CONTINUE`

HookContext 上下文

每个 Hook 的 execute() 方法接收一个 HookContext：

字段	类型	说明
`ctx.event`	`Event`	当前事件
`ctx.event_type`	`str`	事件类型字符串
`ctx.handler_entry`	`HandlerEntry`	处理器注册信息（含 `func` 属性）
`ctx.api`	`BotAPIClient`	Bot API 客户端
`ctx.services`	`ServiceManager`	服务管理器（可选）
`ctx.kwargs`	`Dict[str, Any]`	Hook 间共享的参数字典
`ctx.result`	`Any`	Handler 返回值（仅 AFTER_CALL）
`ctx.error`	`Exception`	异常信息（仅 ON_ERROR）

编写自定义 Hook

基本结构

from ncatbot.core.registry.hook import Hook, HookAction, HookContext, HookStage

class MyHook(Hook):
    stage = HookStage.BEFORE_CALL
    priority = 50

    async def execute(self, ctx: HookContext) -> HookAction:
        return HookAction.CONTINUE  # 或 HookAction.SKIP

附加 Hook 到 Handler

方式一：@add_hooks() 批量绑定

@add_hooks(keyword_filter, logging_hook, error_notify)
@registrar.on_group_command("回声")
async def on_echo(self, event: GroupMessageEvent, content: str):
    await event.reply(f"🔊 {content}")

方式二：@hook 装饰器语法

@error_notify
@registrar.on_group_command("除零")
async def on_divide_by_zero(self, event: GroupMessageEvent):
    _ = 1 / 0

完整三阶段 Hook 示例：examples/common/03_hook_and_filter/main.py

内置 Hook 一览

过滤类 Hook（BEFORE_CALL）

Hook	构造参数	说明
`MessageTypeFilter(message_type)`	`"group"` / `"private"`	按消息类型过滤
`PostTypeFilter(post_type)`	`"message"` / `"notice"` 等	按 post_type 过滤
`SubTypeFilter(sub_type)`	`"poke"` / `"invite"` 等	按 sub_type 过滤
`NoticeTypeFilter(notice_type)`	`"group_increase"` 等	按通知类型过滤
`RequestTypeFilter(request_type)`	`"friend"` / `"group"`	按请求类型过滤
`SelfFilter()`	—	过滤 Bot 自身发送的消息
`PlatformFilter(platform)`	`"qq"` / `"telegram"` 等	按平台过滤

文本匹配类 Hook（BEFORE_CALL）

Hook	构造参数	说明
`StartsWithHook(prefix)`	前缀字符串	消息以指定前缀开头
`KeywordHook(*words)`	关键词列表	消息包含任一关键词
`RegexHook(pattern, flags=0)`	正则表达式	正则匹配，匹配结果存入 `ctx.kwargs['match']`

便捷工厂函数

from ncatbot.core.registry.builtin_hooks import (
    startswith, keyword, regex, group_only, private_only, non_self,
)

装饰器自动附加

装饰器	自动附加的 Hook
`on_group_command("x")`	`MessageTypeFilter("group")` + `CommandHook("x")`
`on_private_command("x")`	`MessageTypeFilter("private")` + `CommandHook("x")`
`on_group_message()`	`MessageTypeFilter("group")`
`on_poke()`	`NoticeTypeFilter("notify")` + `SubTypeFilter("poke")`

CommandHook 与参数绑定

CommandHook 是 on_command() / on_group_command() / on_private_command() 内部使用的核心 Hook，负责命令匹配和参数提取。

执行流程

预处理：将消息段中首个 PlainText 移到 index 0（解决 Reply 开头的消息匹配不到命令的问题）
命令匹配：对首段文本使用 shlex 分词，首 token 匹配命令名即触发（统一前缀匹配）
构建 binding stream：命令后剩余文本 + 后续段按序排列为绑定流
参数绑定：对 Handler 的每个参数从 binding stream 中逐项匹配
缺失处理：必选参数无法绑定时 → WARNING + 自动回复正确用法 + SKIP

绑定规则

参数类型	提取方式	示例
`str`	命令名后的文本 token	`"回声你好"` → `content="你好"`
`int`	从文本 token 转换	`"禁言 @xxx 60"` → `duration=60`
`float`	从文本 token 转换	`"设置 3.14"` → `value=3.14`
`At`	从消息段中匹配 @段	`"踢 @xxx"` → `target=At(user_id=xxx)`
引号包裹	双引号/单引号内容作为单个 token	`echo "hello world"` → `"hello world"`

特殊行为：

不匹配的段被跳过并永久消耗（不参与后续参数匹配）
最后一个 str 参数收集剩余所有文本 token（拼接为空格分隔字符串）
有默认值的参数在缺失时使用默认值
必选参数缺失 → 自动回复 "用法: /cmd <param: 类型> [param: 类型 = 默认值]"

@registrar.on_group_command("禁言")
async def on_ban(
    self, event: GroupMessageEvent,
    target: At = None,        # 从 @ 段提取
    duration: int = 60        # 从文本中提取数字
):
    ...

参数绑定的实际示例：examples/qq/02_command_binding/。

Hook 优先级与执行顺序

同一阶段的 Hook 按 priority 降序执行（数值越大越先执行）。

Hook 类别	默认 priority
`DispatchFilterHook`（全局）	200（全局 Hook，最先执行）
`SelfFilter`	200（最先执行）
`MessageTypeFilter` / `PostTypeFilter` / `SubTypeFilter`	100
`StartsWithHook` / `KeywordHook` / `RegexHook`	90
自定义 Hook	0（默认）

全局 Hook vs Handler 级 Hook：DispatchFilterHook 是全局 Hook，通过 HandlerDispatcher(global_hooks=[...]) 注册，在每个 handler 的 handler 级 hooks 之前执行。即使 handler 级没有任何 Hook，全局 Hook 仍会执行。

当 BEFORE_CALL 阶段的任何 Hook 返回 HookAction.SKIP 时，立即跳过当前 Handler，后续 Hook 和 AFTER_CALL/ON_ERROR 均不触发。

下一步

常用模式 — 多步对话、状态机、插件通信
事件注册与装饰器 — Hook 如何与装饰器注册配合工作

版权所有

版权归属：MI

许可证：署名 4.0 国际 (CC-BY-4.0)

通用

QQ

Bilibili

GitHub

通用

QQ