improve(nonstandard-apis): 添加非标准API的OPT经过，重构转发消息API以使用OneBotForwardNode

Author: ForteScarlet

build.gradle.kts

@@ -148,7 +148,10 @@ apiValidation {
             "love.forte.simbot.component.onebot.v11.core.event.ExperimentalCustomEventResolverApi",
 
             // CustomOneBotApi
-            "love.forte.simbot.component.onebot.v11.core.api.ExperimentalCustomOneBotApi"
+            "love.forte.simbot.component.onebot.v11.core.api.ExperimentalCustomOneBotApi",
+
+            // OneBotNonStandardApi
+            "love.forte.simbot.component.onebot.v11.core.api.nonstandard.OneBotNonStandardApi"
         ),
     )
 

simbot-component-onebot-common/src/commonMain/kotlin/love/forte/simbot/component/onebot/common/annotations/ComponentOpts.kt

@@ -1,18 +1,24 @@
 /*
- * Copyright (c) 2024. ForteScarlet.
+ *     Copyright (c) 2024-2025. ForteScarlet.
  *
- * This file is part of simbot-component-onebot.
+ *     Project    https://github.com/simple-robot/simbot-component-onebot
+ *     Email      [email protected]
  *
- * simbot-component-onebot 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 project and this file are part of the Simple Robot Library (Alias: simple-robot, simbot, etc.).
  *
- * simbot-component-onebot 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 GNU Lesser General Public License for more details.
+ *     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/>.
  *
- * You should have received a copy of the GNU Lesser General Public License along with simbot-component-onebot.
- * If not, see <https://www.gnu.org/licenses/>.
  */
 
 package love.forte.simbot.component.onebot.common.annotations
@@ -27,6 +33,7 @@ package love.forte.simbot.component.onebot.common.annotations
 )
 @Target(
     AnnotationTarget.CLASS,
+    AnnotationTarget.TYPEALIAS,
     AnnotationTarget.ANNOTATION_CLASS,
     AnnotationTarget.PROPERTY,
     AnnotationTarget.FUNCTION,

simbot-component-onebot-v11/simbot-component-onebot-v11-core/api/simbot-component-onebot-v11-core.api

@@ -1800,31 +1800,11 @@ public final class love/forte/simbot/component/onebot/v11/core/api/SetRestartApi
 	public static synthetic fun create$default (Llove/forte/simbot/component/onebot/v11/core/api/SetRestartApi$Factory;Ljava/lang/Long;ILjava/lang/Object;)Llove/forte/simbot/component/onebot/v11/core/api/SetRestartApi;
 }
 
-public final class love/forte/simbot/component/onebot/v11/core/api/nonstandard/SendGroupForwardMsgApi : love/forte/simbot/component/onebot/v11/core/api/OneBotApi {
-	public static final field Factory Llove/forte/simbot/component/onebot/v11/core/api/nonstandard/SendGroupForwardMsgApi$Factory;
-	public synthetic fun <init> (Ljava/lang/Object;Lkotlin/jvm/internal/DefaultConstructorMarker;)V
-	public static final fun create (Llove/forte/simbot/common/id/ID;Llove/forte/simbot/component/onebot/v11/core/api/OneBotMessageOutgoing;)Llove/forte/simbot/component/onebot/v11/core/api/nonstandard/SendGroupForwardMsgApi;
-	public fun getAction ()Ljava/lang/String;
-	public fun getApiResultDeserializer ()Lkotlinx/serialization/DeserializationStrategy;
-	public fun getBody ()Ljava/lang/Object;
-	public fun getResultDeserializer ()Lkotlinx/serialization/DeserializationStrategy;
+public abstract interface annotation class love/forte/simbot/component/onebot/v11/core/api/nonstandard/OneBotNonStandardApi : java/lang/annotation/Annotation {
 }
 
 public final class love/forte/simbot/component/onebot/v11/core/api/nonstandard/SendGroupForwardMsgApi$Factory {
-	public final fun create (Llove/forte/simbot/common/id/ID;Llove/forte/simbot/component/onebot/v11/core/api/OneBotMessageOutgoing;)Llove/forte/simbot/component/onebot/v11/core/api/nonstandard/SendGroupForwardMsgApi;
-}
-
-public final class love/forte/simbot/component/onebot/v11/core/api/nonstandard/SendGroupForwardMsgResult {
-	public static final field Companion Llove/forte/simbot/component/onebot/v11/core/api/nonstandard/SendGroupForwardMsgResult$Companion;
-	public final fun component1 ()Llove/forte/simbot/common/id/IntID;
-	public final fun component2 ()Llove/forte/simbot/common/id/StringID;
-	public final fun copy (Llove/forte/simbot/common/id/IntID;Llove/forte/simbot/common/id/StringID;)Llove/forte/simbot/component/onebot/v11/core/api/nonstandard/SendGroupForwardMsgResult;
-	public static synthetic fun copy$default (Llove/forte/simbot/component/onebot/v11/core/api/nonstandard/SendGroupForwardMsgResult;Llove/forte/simbot/common/id/IntID;Llove/forte/simbot/common/id/StringID;ILjava/lang/Object;)Llove/forte/simbot/component/onebot/v11/core/api/nonstandard/SendGroupForwardMsgResult;
-	public fun equals (Ljava/lang/Object;)Z
-	public final fun getForwardId ()Llove/forte/simbot/common/id/StringID;
-	public final fun getMessageId ()Llove/forte/simbot/common/id/IntID;
-	public fun hashCode ()I
-	public fun toString ()Ljava/lang/String;
+	public final fun create (Llove/forte/simbot/common/id/ID;Ljava/util/List;)Llove/forte/simbot/component/onebot/v11/core/api/nonstandard/SendGroupForwardMsgApi;
 }
 
 public synthetic class love/forte/simbot/component/onebot/v11/core/api/nonstandard/SendGroupForwardMsgResult$$serializer : kotlinx/serialization/internal/GeneratedSerializer {
@@ -1842,18 +1822,8 @@ public final class love/forte/simbot/component/onebot/v11/core/api/nonstandard/S
 	public final fun serializer ()Lkotlinx/serialization/KSerializer;
 }
 
-public final class love/forte/simbot/component/onebot/v11/core/api/nonstandard/SendPrivateForwardMsgApi : love/forte/simbot/component/onebot/v11/core/api/OneBotApi {
-	public static final field Factory Llove/forte/simbot/component/onebot/v11/core/api/nonstandard/SendPrivateForwardMsgApi$Factory;
-	public synthetic fun <init> (Ljava/lang/Object;Lkotlin/jvm/internal/DefaultConstructorMarker;)V
-	public static final fun create (Llove/forte/simbot/common/id/ID;Llove/forte/simbot/component/onebot/v11/core/api/OneBotMessageOutgoing;)Llove/forte/simbot/component/onebot/v11/core/api/nonstandard/SendPrivateForwardMsgApi;
-	public fun getAction ()Ljava/lang/String;
-	public fun getApiResultDeserializer ()Lkotlinx/serialization/DeserializationStrategy;
-	public fun getBody ()Ljava/lang/Object;
-	public fun getResultDeserializer ()Lkotlinx/serialization/DeserializationStrategy;
-}
-
 public final class love/forte/simbot/component/onebot/v11/core/api/nonstandard/SendPrivateForwardMsgApi$Factory {
-	public final fun create (Llove/forte/simbot/common/id/ID;Llove/forte/simbot/component/onebot/v11/core/api/OneBotMessageOutgoing;)Llove/forte/simbot/component/onebot/v11/core/api/nonstandard/SendPrivateForwardMsgApi;
+	public final fun create (Llove/forte/simbot/common/id/ID;Ljava/util/List;)Llove/forte/simbot/component/onebot/v11/core/api/nonstandard/SendPrivateForwardMsgApi;
 }
 
 public abstract interface class love/forte/simbot/component/onebot/v11/core/bot/OneBotBot : love/forte/simbot/bot/Bot, love/forte/simbot/component/onebot/v11/core/api/OneBotApiExecutable {

simbot-component-onebot-v11/simbot-component-onebot-v11-core/src/commonMain/kotlin/love/forte/simbot/component/onebot/v11/core/api/OneBotMessageOutgoing.kt

@@ -1,18 +1,24 @@
 /*
- * Copyright (c) 2024. ForteScarlet.
+ *     Copyright (c) 2024-2025. ForteScarlet.
  *
- * This file is part of simbot-component-onebot.
+ *     Project    https://github.com/simple-robot/simbot-component-onebot
+ *     Email      [email protected]
  *
- * simbot-component-onebot 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 project and this file are part of the Simple Robot Library (Alias: simple-robot, simbot, etc.).
  *
- * simbot-component-onebot 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 GNU Lesser General Public License for more details.
+ *     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/>.
  *
- * You should have received a copy of the GNU Lesser General Public License along with simbot-component-onebot.
- * If not, see <https://www.gnu.org/licenses/>.
  */
 
 package love.forte.simbot.component.onebot.v11.core.api
@@ -26,10 +32,16 @@ import kotlinx.serialization.descriptors.buildClassSerialDescriptor
 import kotlinx.serialization.encoding.Decoder
 import kotlinx.serialization.encoding.Encoder
 import love.forte.simbot.annotations.FragileSimbotAPI
+import love.forte.simbot.component.onebot.common.annotations.ExperimentalOneBotAPI
+import love.forte.simbot.component.onebot.v11.core.bot.OneBotBot
+import love.forte.simbot.component.onebot.v11.core.utils.resolveToOneBotSegmentList
 import love.forte.simbot.component.onebot.v11.message.OneBotMessageElement
 import love.forte.simbot.component.onebot.v11.message.OneBotMessageElementSerializer
 import love.forte.simbot.component.onebot.v11.message.segment.OneBotMessageSegment
 import love.forte.simbot.component.onebot.v11.message.segment.OneBotMessageSegmentSerializer
+import love.forte.simbot.message.Message
+import love.forte.simbot.message.Messages
+import kotlin.jvm.JvmOverloads
 import kotlin.jvm.JvmStatic
 
 
@@ -60,16 +72,31 @@ public sealed class OneBotMessageOutgoing {
 
     @Serializable
     public data class SegmentsValue(
-
         public val segments: List<OneBotMessageSegment>
     ) : OneBotMessageOutgoing()
 
     public companion object {
+        /**
+         * 通过字符串值构建 [StringValue]。
+         */
         @JvmStatic
         public fun create(value: String): StringValue = StringValue(value)
 
+        /**
+         * 通过消息段列表构建 [SegmentsValue]。
+         */
         @JvmStatic
         public fun create(segments: List<OneBotMessageSegment>): SegmentsValue = SegmentsValue(segments)
+
+        /**
+         * 通过 [Messages] 构建 [SegmentsValue]。
+         * @since 1.9.0
+         */
+        @JvmStatic
+        @ExperimentalOneBotAPI
+        @JvmOverloads
+        public fun create(message: Message, bot: OneBotBot? = null): SegmentsValue =
+            create(message.resolveToOneBotSegmentList(bot))
     }
 }
 

simbot-component-onebot-v11/simbot-component-onebot-v11-core/src/commonMain/kotlin/love/forte/simbot/component/onebot/v11/core/api/nonstandard/OneBotNonStandardApi.kt

@@ -0,0 +1,36 @@
+/*
+ *     Copyright (c) 2025. ForteScarlet.
+ *
+ *     Project    https://github.com/simple-robot/simbot-component-onebot
+ *     Email      [email protected]
+ *
+ *     This project and this file are 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.component.onebot.v11.core.api.nonstandard
+
+/**
+ * 与非标准API相关的内容。
+ * 非标准API的实现目前尚处于实验阶段。它们不保证兼容性，并且可能在未来发生变更或被移除。
+ *
+ * @since 1.9.0
+ * @author ForteScarlet
+ */
+@Retention(AnnotationRetention.BINARY)
+@Target(AnnotationTarget.CLASS, AnnotationTarget.FUNCTION, AnnotationTarget.PROPERTY)
+@RequiresOptIn("This api is not part of the onebot protocol standard, and may not be available in the future.")
+public annotation class OneBotNonStandardApi

simbot-component-onebot-v11/simbot-component-onebot-v11-core/src/commonMain/kotlin/love/forte/simbot/component/onebot/v11/core/api/nonstandard/SendGroupForwardMsgApi.kt

@@ -1,18 +1,24 @@
 /*
- * Copyright (c) 2025. ForteScarlet.
+ *     Copyright (c) 2025. ForteScarlet.
  *
- * This file is part of simbot-component-onebot.
+ *     Project    https://github.com/simple-robot/simbot-component-onebot
+ *     Email      [email protected]
  *
- * simbot-component-onebot 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 project and this file are part of the Simple Robot Library (Alias: simple-robot, simbot, etc.).
  *
- * simbot-component-onebot 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 GNU Lesser General Public License for more details.
+ *     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/>.
  *
- * You should have received a copy of the GNU Lesser General Public License along with simbot-component-onebot.
- * If not, see <https://www.gnu.org/licenses/>.
  */
 
 package love.forte.simbot.component.onebot.v11.core.api.nonstandard
@@ -22,12 +28,11 @@ import kotlinx.serialization.SerialName
 import kotlinx.serialization.Serializable
 import love.forte.simbot.common.id.ID
 import love.forte.simbot.common.id.IntID
-import love.forte.simbot.common.id.StringID
 import love.forte.simbot.common.id.literal
 import love.forte.simbot.component.onebot.common.annotations.ApiResultConstructor
 import love.forte.simbot.component.onebot.v11.core.api.OneBotApi
 import love.forte.simbot.component.onebot.v11.core.api.OneBotApiResult
-import love.forte.simbot.component.onebot.v11.core.api.OneBotMessageOutgoing
+import love.forte.simbot.component.onebot.v11.message.segment.OneBotForwardNode
 import kotlin.jvm.JvmStatic
 
 /**
@@ -36,6 +41,7 @@ import kotlin.jvm.JvmStatic
  * @since 1.9.0
  * @author Aliorpse
  */
+@OneBotNonStandardApi
 public class SendGroupForwardMsgApi private constructor(
     override val body: Any,
 ) : OneBotApi<SendGroupForwardMsgResult> {
@@ -62,7 +68,7 @@ public class SendGroupForwardMsgApi private constructor(
         @JvmStatic
         public fun create(
             groupId: ID,
-            messages: OneBotMessageOutgoing,
+            messages: List<OneBotForwardNode>,
         ): SendGroupForwardMsgApi = SendGroupForwardMsgApi(Body(groupId.literal, messages))
     }
 
@@ -74,7 +80,7 @@ public class SendGroupForwardMsgApi private constructor(
     internal data class Body(
         @SerialName("group_id")
         val groupId: String,
-        val messages: OneBotMessageOutgoing,
+        val messages: List<OneBotForwardNode>,
     )
 }
 
@@ -85,9 +91,10 @@ public class SendGroupForwardMsgApi private constructor(
  * @property forwardId RES ID
  */
 @Serializable
+@OneBotNonStandardApi
 public data class SendGroupForwardMsgResult @ApiResultConstructor constructor(
     @SerialName("message_id")
     public val messageId: IntID,
     @SerialName("forward_id")
-    public val forwardId: StringID
+    public val forwardId: ID
 )

simbot-component-onebot-v11/simbot-component-onebot-v11-core/src/commonMain/kotlin/love/forte/simbot/component/onebot/v11/core/api/nonstandard/SendPrivateForwardMsgApi.kt

@@ -1,18 +1,24 @@
 /*
- * Copyright (c) 2025. ForteScarlet.
+ *     Copyright (c) 2025. ForteScarlet.
  *
- * This file is part of simbot-component-onebot.
+ *     Project    https://github.com/simple-robot/simbot-component-onebot
+ *     Email      [email protected]
  *
- * simbot-component-onebot 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 project and this file are part of the Simple Robot Library (Alias: simple-robot, simbot, etc.).
  *
- * simbot-component-onebot 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 GNU Lesser General Public License for more details.
+ *     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/>.
  *
- * You should have received a copy of the GNU Lesser General Public License along with simbot-component-onebot.
- * If not, see <https://www.gnu.org/licenses/>.
  */
 
 package love.forte.simbot.component.onebot.v11.core.api.nonstandard
@@ -24,8 +30,8 @@ import love.forte.simbot.common.id.ID
 import love.forte.simbot.common.id.literal
 import love.forte.simbot.component.onebot.v11.core.api.OneBotApi
 import love.forte.simbot.component.onebot.v11.core.api.OneBotApiResult
-import love.forte.simbot.component.onebot.v11.core.api.OneBotMessageOutgoing
 import love.forte.simbot.component.onebot.v11.core.api.SendMsgResult
+import love.forte.simbot.component.onebot.v11.message.segment.OneBotForwardNode
 import kotlin.jvm.JvmStatic
 
 /**
@@ -34,6 +40,7 @@ import kotlin.jvm.JvmStatic
  * @since 1.9.0
  * @author Aliorpse
  */
+@OneBotNonStandardApi
 public class SendPrivateForwardMsgApi private constructor(
     override val body: Any
 ) : OneBotApi<SendMsgResult> {
@@ -59,7 +66,7 @@ public class SendPrivateForwardMsgApi private constructor(
         @JvmStatic
         public fun create(
             userId: ID,
-            messages: OneBotMessageOutgoing,
+            messages: List<OneBotForwardNode>,
         ): SendPrivateForwardMsgApi = SendPrivateForwardMsgApi(Body(userId.literal, messages))
     }
 
@@ -71,6 +78,6 @@ public class SendPrivateForwardMsgApi private constructor(
     internal data class Body(
         @SerialName("user_id")
         val userId: String,
-        val messages: OneBotMessageOutgoing,
+        val messages: List<OneBotForwardNode>,
     )
 }