Merge pull request #1019 from simple-robot/internal-interaction-event

增加若干内部事件、内部行为事件和相关的消息拦截事件

Author: ForteScarlet

README.md

@@ -142,7 +142,7 @@ fun Application.registerListeners() {
 ## 协助我们
 为我们点亮一个 **✨star🌟** 便是能够给予我们继续走下去的最大动力与支持！
 
-- 阅读 [贡献指南](docs/CONTRIBUTING_CN.md) 来了解如何贡献你的力量！ 
+- 阅读 [**贡献指南**](docs/CONTRIBUTING_CN.md) 来了解如何贡献你的力量！ 
 - 你可以通过 [**讨论区**][discussions] 与其他人或者simbot开发团队相互友好交流。
 - 如果你通过此项目创建了一个很酷的开源项目，欢迎通过 [ISSUES][issues]、[讨论区][discussions]
   等方式留下你的开源项目信息，并将你酷酷的项目展示在作品展示区。

docs/CONTRIBUTING.md

@@ -16,4 +16,7 @@ and the [Simple Robot Library](https://github.com/simple-robot-library)!
 
 ### Pull Request
 
+> [!info]
+> If you want to contribute code, please submit a Pull Request to the `v4-dev` development branch.
+
 TODO

docs/CONTRIBUTING_CN.md

@@ -57,6 +57,10 @@ override val developers: List<Developer> = developers {
 为其他来者留下一盏指路的明灯~
 
 ## 代码贡献
+
+> [!info]
+> 如果您要提交代码贡献，请向开发分支 `v4-dev` 提交 PR 。
+
 ### 注释风格
 
 simbot核心库对源代码的注释有着一些约定。

simbot-api/api/simbot-api.api

@@ -1,10 +1,10 @@
 /*
- *     Copyright (c) 2024. ForteScarlet.
+ *     Copyright (c) 2024-2025. ForteScarlet.
  *
  *     Project    https://github.com/simple-robot/simpler-robot
  *     Email      [email protected]
  *
- *     This file is part of the Simple Robot Library.
+ *     This file is part of the Simple Robot Library (Alias: simple-robot, simbot, etc.).
  *
  *     This program is free software: you can redistribute it and/or modify
  *     it under the terms of the GNU Lesser General Public License as published by
@@ -23,6 +23,7 @@
 
 package love.forte.simbot.ability
 
+import love.forte.simbot.event.InternalInterceptionException
 import love.forte.simbot.event.MessageEvent
 import love.forte.simbot.message.Message
 import love.forte.simbot.message.MessageContent
@@ -45,6 +46,8 @@ public interface ReplySupport {
      * 发送一段纯文本消息。
      *
      * @return 消息发送成功后的回执
+     * @throws InternalInterceptionException 在拦截事件处理过程中产生的异常，
+     * 每一个具体的异常都会被收集在 [InternalInterceptionException.suppressedExceptions] 中。
      * @throws Exception 可能产生任何异常
      */
     public suspend fun reply(text: String): MessageReceipt
@@ -53,6 +56,8 @@ public interface ReplySupport {
      * 发送一个消息 [Message]。
      *
      * @return 消息发送成功后的回执
+     * @throws InternalInterceptionException 在拦截事件处理过程中产生的异常，
+     * 每一个具体的异常都会被收集在 [InternalInterceptionException.suppressedExceptions] 中。
      * @throws Exception 可能产生任何异常
      */
     public suspend fun reply(message: Message): MessageReceipt
@@ -63,6 +68,8 @@ public interface ReplySupport {
      * 并在不支持的情况下降级为使用 [MessageContent.messages]。
      *
      * @return 消息发送成功后的回执
+     * @throws InternalInterceptionException 在拦截事件处理过程中产生的异常，
+     * 每一个具体的异常都会被收集在 [InternalInterceptionException.suppressedExceptions] 中。
      * @throws Exception 可能产生任何异常
      */
     public suspend fun reply(messageContent: MessageContent): MessageReceipt

simbot-api/src/commonMain/kotlin/love/forte/simbot/ability/ReplySupport.kt

@@ -1,10 +1,10 @@
 /*
- *     Copyright (c) 2024. ForteScarlet.
+ *     Copyright (c) 2024-2025. ForteScarlet.
  *
  *     Project    https://github.com/simple-robot/simpler-robot
  *     Email      [email protected]
  *
- *     This file is part of the Simple Robot Library.
+ *     This file is part of the Simple Robot Library (Alias: simple-robot, simbot, etc.).
  *
  *     This program is free software: you can redistribute it and/or modify
  *     it under the terms of the GNU Lesser General Public License as published by
@@ -25,6 +25,7 @@ package love.forte.simbot.ability
 
 import love.forte.simbot.definition.Actor
 import love.forte.simbot.definition.Contact
+import love.forte.simbot.event.InternalInterceptionException
 import love.forte.simbot.message.Message
 import love.forte.simbot.message.MessageContent
 import love.forte.simbot.message.MessageReceipt
@@ -42,6 +43,8 @@ public interface SendSupport {
      * 发送一段纯文本消息。
      *
      * @return 消息发送成功后的回执
+     * @throws InternalInterceptionException 在拦截事件处理过程中产生的异常，
+     * 每一个具体的异常都会被收集在 [InternalInterceptionException.suppressedExceptions] 中。
      * @throws Exception 可能产生任何异常
      */
     public suspend fun send(text: String): MessageReceipt
@@ -50,6 +53,8 @@ public interface SendSupport {
      * 发送一个消息 [Message]。
      *
      * @return 消息发送成功后的回执
+     * @throws InternalInterceptionException 在拦截事件处理过程中产生的异常，
+     * 每一个具体的异常都会被收集在 [InternalInterceptionException.suppressedExceptions] 中。
      * @throws Exception 可能产生任何异常
      */
     public suspend fun send(message: Message): MessageReceipt
@@ -60,6 +65,8 @@ public interface SendSupport {
      * 并在不支持的情况下降级为使用 [MessageContent.messages]。
      *
      * @return 消息发送成功后的回执
+     * @throws InternalInterceptionException 在拦截事件处理过程中产生的异常，
+     * 每一个具体的异常都会被收集在 [InternalInterceptionException.suppressedExceptions] 中。
      * @throws Exception 可能产生任何异常
      */
     public suspend fun send(messageContent: MessageContent): MessageReceipt

simbot-api/src/commonMain/kotlin/love/forte/simbot/ability/SendSupport.kt

@@ -1,5 +1,5 @@
 /*
- *     Copyright (c) 2024. ForteScarlet.
+ *     Copyright (c) 2024-2025. ForteScarlet.
  *
  *     Project    https://github.com/simple-robot/simpler-robot
  *     Email      [email protected]
@@ -33,7 +33,7 @@ import love.forte.simbot.bot.BotManager
  *
  * @author ForteScarlet
  */
-public interface BotStageEvent : BotEvent {
+public interface BotStageEvent : InternalNotificationEvent, BotEvent {
     /**
      * 相关的 bot.
      */

simbot-api/src/commonMain/kotlin/love/forte/simbot/event/BotStageEvent.kt

@@ -0,0 +1,133 @@
+/*
+ *     Copyright (c) 2025. ForteScarlet.
+ *
+ *     Project    https://github.com/simple-robot/simpler-robot
+ *     Email      [email protected]
+ *
+ *     This file is part of the Simple Robot Library (Alias: simple-robot, simbot, etc.).
+ *
+ *     This program is free software: you can redistribute it and/or modify
+ *     it under the terms of the GNU Lesser General Public License as published by
+ *     the Free Software Foundation, either version 3 of the License, or
+ *     (at your option) any later version.
+ *
+ *     This program is distributed in the hope that it will be useful,
+ *     but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *     Lesser GNU General Public License for more details.
+ *
+ *     You should have received a copy of the Lesser GNU General Public License
+ *     along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ *
+ */
+
+package love.forte.simbot.event
+
+import love.forte.simbot.ability.ReplySupport
+import love.forte.simbot.ability.SendSupport
+import kotlin.jvm.JvmStatic
+
+/**
+ * 拦截或通知中 [SendSupport.send] 或 [ReplySupport.reply] 的消息内容。
+ */
+public sealed class InteractionMessage {
+    /**
+     * 当参数类型为 [String] 时，表示发送的文本消息。
+     */
+    public class Text internal constructor(public val text: String) : InteractionMessage() {
+        override fun equals(other: Any?): Boolean {
+            if (this === other) return true
+            if (other !is Text) return false
+
+            if (text != other.text) return false
+
+            return true
+        }
+
+        override fun hashCode(): Int {
+            return text.hashCode()
+        }
+
+        override fun toString(): String {
+            return "Text(text='$text')"
+        }
+    }
+
+    /**
+     * 当参数类型为 [love.forte.simbot.message.Message] 时，表示发送的消息。
+     */
+    public class Message internal constructor(public val message: love.forte.simbot.message.Message) :
+        InteractionMessage() {
+        override fun equals(other: Any?): Boolean {
+            if (this === other) return true
+            if (other !is Message) return false
+
+            if (message != other.message) return false
+
+            return true
+        }
+
+        override fun hashCode(): Int {
+            return message.hashCode()
+        }
+
+        override fun toString(): String {
+            return "Message(message=$message)"
+        }
+
+    }
+
+    /**
+     * 当参数类型为 [love.forte.simbot.message.MessageContent] 时，表示发送的消息内容。
+     */
+    public class MessageContent internal constructor(
+        public val messageContent: love.forte.simbot.message.MessageContent
+    ) : InteractionMessage() {
+        override fun equals(other: Any?): Boolean {
+            if (this === other) return true
+            if (other !is MessageContent) return false
+
+            if (messageContent != other.messageContent) return false
+
+            return true
+        }
+
+        override fun hashCode(): Int {
+            return messageContent.hashCode()
+        }
+
+        override fun toString(): String {
+            return "MessageContent(messageContent=$messageContent)"
+        }
+    }
+
+    /**
+     * 如果组件或 [SendSupport] 的实现者提供了其他三个类型参数以外的参数，
+     * 则需要通过 [Extension] 对其进行扩展。
+     */
+    public abstract class Extension : InteractionMessage()
+
+    public companion object {
+        /**
+         * 创建一个文本消息。
+         * @see InteractionMessage
+         */
+        @JvmStatic
+        public fun valueOf(text: String): Text = Text(text)
+
+        /**
+         * 创建一个消息。
+         * @see InteractionMessage
+         */
+        @JvmStatic
+        public fun valueOf(message: love.forte.simbot.message.Message): Message = Message(message)
+
+        /**
+         * 创建一个消息内容。
+         * @see InteractionMessage
+         */
+        @JvmStatic
+        public fun valueOf(messageContent: love.forte.simbot.message.MessageContent): MessageContent =
+            MessageContent(messageContent)
+    }
+}

simbot-api/src/commonMain/kotlin/love/forte/simbot/event/InteractionMessage.kt

@@ -0,0 +1,82 @@
+/*
+ *     Copyright (c) 2025. ForteScarlet.
+ *
+ *     Project    https://github.com/simple-robot/simpler-robot
+ *     Email      [email protected]
+ *
+ *     This file is part of the Simple Robot Library (Alias: simple-robot, simbot, etc.).
+ *
+ *     This program is free software: you can redistribute it and/or modify
+ *     it under the terms of the GNU Lesser General Public License as published by
+ *     the Free Software Foundation, either version 3 of the License, or
+ *     (at your option) any later version.
+ *
+ *     This program is distributed in the hope that it will be useful,
+ *     but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *     Lesser GNU General Public License for more details.
+ *
+ *     You should have received a copy of the Lesser GNU General Public License
+ *     along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ *
+ */
+
+package love.forte.simbot.event
+
+
+/**
+ * 一个内部事件。
+ * 用于表示一个仅在内部流转、与外界无关的事件，
+ * 通常用于一些内部的状态通知或功能拦截，例如 [BotStageEvent] 或 [SendSupportInteractionEvent] 等。
+ *
+ * 通常由组件实现进行扩展，不过也提供了一些默认的定义。
+ *
+ * @see InternalNotificationEvent
+ * @see InternalInterceptionEvent
+ * @see BotStageEvent
+ * @see SendSupportInteractionEvent
+ *
+ * @since 4.11.0
+ * @author ForteScarlet
+ */
+public interface InternalEvent : Event
+
+/**
+ * 一个内部通知事件。
+ * 通知性质的内部事件通常仅用作“通知”，即它不会对某些行为造成影响。
+ *
+ * @since 4.11.0
+ */
+public interface InternalNotificationEvent : InternalEvent
+
+/**
+ * 一个内部拦截事件。
+ * 拦截性质的内部事件通常用作“拦截”，即它会对某些行为进行拦截，并有可能会产生影响，
+ * 例如改变原本行为的参数、或者通过抛出异常直接阻止某些行为的发生。
+ * 例如针对 [SendSupport.send][love.forte.simbot.ability.SendSupport.send]
+ * 进行拦截，并改变其入参。
+ *
+ * ## 异常处理
+ *
+ * 在拦截过程中，如果产生了异常，它们不会影响后续事件的继续调度，
+ * 而所有产生的异常都会被收集到 [InternalInterceptionException.suppressedExceptions] 中，
+ * 并在最终抛出并影响原函数的执行。
+ *
+ * @since 4.11.0
+ *
+ */
+public interface InternalInterceptionEvent : InternalEvent
+
+/**
+ * [InternalInterceptionEvent] 中产生的异常的收集与包装。
+ * 更多参考 [InternalInterceptionEvent] 中有关异常的说明。
+ *
+ * @see InternalInterceptionEvent
+ * @since 4.11.0
+ */
+public open class InternalInterceptionException : RuntimeException {
+    public constructor() : super()
+    public constructor(message: String?) : super(message)
+    public constructor(message: String?, cause: Throwable?) : super(message, cause)
+    public constructor(cause: Throwable?) : super(cause)
+}