feat(v11): 实现并支持 MessageReference 相关API

Author: ForteScarlet

simbot-component-onebot-v11/simbot-component-onebot-v11-core/src/commonMain/kotlin/love/forte/simbot/component/onebot/v11/core/utils/MessageUtil.kt

@@ -18,6 +18,7 @@
 package love.forte.simbot.component.onebot.v11.core.utils
 
 import love.forte.simbot.common.id.ID
+import love.forte.simbot.component.onebot.common.annotations.InternalOneBotAPI
 import love.forte.simbot.component.onebot.v11.core.api.OneBotMessageOutgoing
 import love.forte.simbot.component.onebot.v11.core.api.SendMsgApi
 import love.forte.simbot.component.onebot.v11.message.segment.OneBotMessageSegment
@@ -29,7 +30,8 @@ import love.forte.simbot.component.onebot.v11.message.segment.OneBotText
  *
  * @param messageType see [SendMsgApi]`.MESSAGE_TYPE_*`
  */
-internal fun sendTextMsgApi(
+@InternalOneBotAPI
+public fun sendTextMsgApi(
     messageType: String,
     target: ID,
     text: String,
@@ -58,7 +60,8 @@ internal fun sendTextMsgApi(
     }
 }
 
-internal fun sendPrivateTextMsgApi(
+@InternalOneBotAPI
+public fun sendPrivateTextMsgApi(
     target: ID,
     text: String,
     reply: ID? = null,
@@ -69,7 +72,8 @@ internal fun sendPrivateTextMsgApi(
     reply = reply,
 )
 
-internal fun sendGroupTextMsgApi(
+@InternalOneBotAPI
+public fun sendGroupTextMsgApi(
     target: ID,
     text: String,
     reply: ID? = null,
@@ -86,7 +90,8 @@ internal fun sendGroupTextMsgApi(
  *
  * @param messageType see [SendMsgApi]`.MESSAGE_TYPE_*`
  */
-internal fun sendMsgApi(
+@InternalOneBotAPI
+public fun sendMsgApi(
     messageType: String,
     target: ID,
     message: List<OneBotMessageSegment>,
@@ -112,7 +117,8 @@ internal fun sendMsgApi(
     }
 }
 
-internal fun resolveReplyMessageSegmentList(
+@InternalOneBotAPI
+public fun resolveReplyMessageSegmentList(
     message: List<OneBotMessageSegment>,
     reply: ID,
 ): List<OneBotMessageSegment> {
@@ -132,7 +138,8 @@ internal fun resolveReplyMessageSegmentList(
     return newMessage
 }
 
-internal fun sendPrivateMsgApi(
+@InternalOneBotAPI
+public fun sendPrivateMsgApi(
     target: ID,
     message: List<OneBotMessageSegment>,
     reply: ID? = null,
@@ -143,7 +150,8 @@ internal fun sendPrivateMsgApi(
     reply = reply,
 )
 
-internal fun sendGroupMsgApi(
+@InternalOneBotAPI
+public fun sendGroupMsgApi(
     target: ID,
     message: List<OneBotMessageSegment>,
     reply: ID? = null,

simbot-component-onebot-v11/simbot-component-onebot-v11-message/src/commonMain/kotlin/love/forte/simbot/component/onebot/v11/message/MessageElementResolvers.kt

@@ -87,23 +87,24 @@ public suspend fun Message.Element.resolveToOneBotSegment(
         is Face -> OneBotFace.create(id)
         is At -> OneBotAt.create(target)
         is AtAll -> OneBotAt.createAtAll()
-        is Image -> {
-            when (this) {
-                // offline image
-                is OfflineImage -> suspendCancellableCoroutine<OneBotMessageSegment?> { continuation ->
-                    offlineImageResolver(defaultImageAdditionalParams)
-                        .resolve(this, continuation)
-                }
-
-                // remote images, OneBot组件中实际上没有此类型的实现
-                // 将它的 id 直接视为 file
-                is RemoteImage -> OneBotImage.create(id.literal)
-
-                // 其他未知类型，不管
-                else -> null
+        is Image -> when (this) {
+            // offline image
+            is OfflineImage -> suspendCancellableCoroutine<OneBotMessageSegment?> { continuation ->
+                offlineImageResolver(defaultImageAdditionalParams)
+                    .resolve(this, continuation)
             }
+
+            // remote images, OneBot组件中实际上没有此类型的实现
+            // 将它的 id 直接视为 file
+            is RemoteImage -> OneBotImage.create(id.literal)
+
+            // 其他未知类型，不管
+            else -> null
         }
 
+        // since 1.2.0
+        is MessageReference -> OneBotReply.create(id)
+
         // 其他未知类型，不管
         else -> null
     }

simbot-component-onebot-v11/simbot-component-onebot-v11-message/src/commonMain/kotlin/love/forte/simbot/component/onebot/v11/message/OneBotMessageContent.kt

@@ -22,10 +22,12 @@ import love.forte.simbot.ability.StandardDeleteOption
 import love.forte.simbot.common.id.ID
 import love.forte.simbot.component.onebot.v11.message.segment.OneBotMessageSegment
 import love.forte.simbot.component.onebot.v11.message.segment.OneBotMessageSegmentElement
+import love.forte.simbot.component.onebot.v11.message.segment.OneBotReply
 import love.forte.simbot.component.onebot.v11.message.segment.OneBotText
 import love.forte.simbot.message.MessageContent
 import love.forte.simbot.message.Messages
 import love.forte.simbot.message.PlainText
+import love.forte.simbot.suspendrunner.STP
 
 
 /**
@@ -55,6 +57,19 @@ public interface OneBotMessageContent : MessageContent {
      */
     override val messages: Messages
 
+    /**
+     * 寻找 [messages] 中第一个 [OneBotReply] 类型的元素，
+     * 如果没有则得到 `null`。
+     * 寻找的过程是即时的，不会发生挂起。
+     *
+     * @since 1.2.0
+     * @see messages
+     * @see OneBotReply
+     */
+    @STP
+    override suspend fun reference(): OneBotReply? =
+        messages.firstNotNullOfOrNull { it as? OneBotReply }
+
     /**
      * 消息中所有的 [文本消息][PlainText]
      * (或者说 [sourceSegments] 中所有的 [OneBotText])