llms.txt: machine-readable documentation index. Markdown version of this page is also available.

Simple Robot 5.x Help

消息发送拦截

在 MessageSendInterceptionPoint 上注册拦截器,可以在组件提交消息前读取或替换消息和发送选项,也可以终止发送。发送 send 和回复 reply 共用这个拦截点。

注册

下面的拦截器去掉待发送纯文本的首尾空白。其他消息类型按原样交给下游。通过 Application 注册一次,即可覆盖该应用管理的、使用此拦截点的 Bot。Spring Boot 的注册方式见 Spring Boot 集成。

导入 love.forte.simbot.application.interceptors 和 love.forte.simbot.interception.onMessageSend 后,在应用启动后注册。

application.interceptors { onMessageSend { _, context, chain -> val text = context.message as? InteractionMessage.Text val next = if (text == null) context else { context.withMessage(InteractionMessage.valueOf(text.text.trim())) } chain.proceed(next) } }

注册时显式传入优先级。下例中的 Interceptors 位于 love.forte.simbot.interception ,响应式写法使用 Reactor 的 Mono。

application.getInterceptorManager().register( MessageSendInterceptionPoint.INSTANCE, PriorityConstant.DEFAULT, Interceptors.blocking((point, context, chain) -> { if (context.getMessage() instanceof InteractionMessage.Text) { var text = (InteractionMessage.Text) context.getMessage(); context = context.withMessage(InteractionMessage.valueOf(text.getText().trim())); } return chain.proceed(context); }));
application.getInterceptorManager().register( MessageSendInterceptionPoint.INSTANCE, PriorityConstant.DEFAULT, Interceptors.async((point, context, chain) -> { if (context.getMessage() instanceof InteractionMessage.Text) { var text = (InteractionMessage.Text) context.getMessage(); context = context.withMessage(InteractionMessage.valueOf(text.getText().trim())); } return chain.proceed(context); }));
application.getInterceptorManager().register( MessageSendInterceptionPoint.INSTANCE, PriorityConstant.DEFAULT, Interceptors.reactive((point, context, chain) -> { if (context.getMessage() instanceof InteractionMessage.Text) { var text = (InteractionMessage.Text) context.getMessage(); context = context.withMessage(InteractionMessage.valueOf(text.getText().trim())); } return Mono.from(chain.proceed(context)); }));

读取和替换上下文

拦截器的业务上下文是 MessageSendContext 。普通发送、按 ID 直发和消息扩展发送都使用 MessageSendContext.Send ,回复使用 MessageSendContext.Reply 。需要读取平台特有信息时,可以进一步判断组件提供的上下文类型。

属性或方法

含义

bot

执行这次操作的 Bot。

source

发起操作的对象,类型为 Any 。例如频道对象、消息事件、直发入口的 Bot,或调用扩展函数的消息对象。

destination

入口已知且读取时无副作用的目标描述,通常包含目标类别与 ID。无法提供描述时为 null。

target()

按需解析入口确定的目标实体。可能挂起、查询平台、抛出异常或返回 null ,例如按 ID 直发时可能没有可用实体。

originalMessage

调用发送或回复入口时的消息。

message

当前将交给下游的消息。多层拦截器可以依次替换。

options

Send 持有 List<SendOption>, Reply 持有 List<ReplyOption> 。初始选项按原顺序保留调用方传入的内容。

InteractionMessage.valueOf(...) 可包装字符串、 Message 或 MessageContent 。组件也可以用 InteractionMessage.Extension 包装原生请求。调用 withMessage(...) 或 withOptions(...) 后,将返回的上下文传给 chain.proceed(...) 。副本保留具体上下文类型、Bot、来源、原始消息和入口目标信息。 withOptions(...) 会复制传入的集合。

当组件允许替换带有目标字段的原生请求时,实际请求的目标可以变化。 destination 和 target() 仍按入口确定的目标提供信息。只需判断目标类别或 ID 时,优先读取 destination 。Java 可按所用 API 风格调用 targetBlocking()、 targetAsync() 或 targetReactive()。

放行、短路与回执

  • 建议每层至多调用一次 chain.proceed(context) 。重复调用会重新执行后续链,可能导致重复发送。在拦截器中再次调用 send 或 reply 会开启一条新链,应避免由此递归进入同一拦截器。

  • 需要阻止发送时,可以在调用 proceed 前抛出业务异常。异常和取消向调用方传播,尚未执行的下游和发送逻辑会被跳过。

  • 常规放行直接返回 proceed 的结果。短路返回或替换回执时,必须满足当前入口声明的非空回执类型。组件在整条链返回后校验一次最终类型,类型不符会抛出 IllegalStateException 。若下游已经发送,遇到此异常时应先确认结果再决定是否重试。

  • proceed 返回的是下游链的结果,下游也可能短路。要观察实际发送成功,监听 MessageSentEvent。

使用发送与回复选项

MessageSendContext.Send 提供发送选项, MessageSendContext.Reply 提供回复选项。可通过 withOptions(...) 传递新列表。若只改其中一项,把要保留的选项一并传入。发送终端按下游收到的列表解析选项,默认引用等组件参数在构造请求时补全。

选项类型、调用示例及标准选项的规则见 发送与回复选项。

适用范围

标准组件实现已将常规发送与回复入口接入拦截链。组件专用方法和原生请求入口的适用范围见对应的组件文档。直接使用通用 API 客户端请求平台接口时会绕过拦截链。

为组件接入消息拦截

在插件配置阶段从 PluginConfigureContext.interceptorManager 取得应用的管理器,并将它作为 InterceptorContainer 传给实际执行发送的对象。通常由 Bot 管理器传给各个 Bot。

针对公开发送或回复入口构造 MessageSendContext.Send 或 Reply 的实现。复制方法应保留组件字段与入口信息,构造和复制时应延迟到需要时再解析目标。每次逻辑发送只在外层调用一次 MessageSendInterceptionPoint.invoke 或 invokeWithReceipt<R> 。入口承诺具体回执类型时使用 invokeWithReceipt<R> 。委托方法、消息拆分后的平台请求和其他内部发送步骤直接执行。

发送终端使用收到的当前消息和选项,在构造平台请求时补全默认引用等组件参数。实际发送取得回执后,由组件在 Bot 作用域异步投递 MessageSentEvent ,携带终端收到的上下文和实际回执。使用自定义拦截点的方式见 通用拦截链。

19 November 2026