Merge pull request #1017 from simple-robot/offlineimage-subclass-optin

为OfflineImage增加 subclass opt-in 标记，并为几个未来弃用的 resolver 类型增加 opt 标记

Author: ForteScarlet

simbot-api/api/simbot-api.api

@@ -2199,6 +2199,9 @@ public final class love/forte/simbot/message/OfflineImage$Companion {
 	public final fun ofResource (Llove/forte/simbot/resource/Resource;)Llove/forte/simbot/message/OfflineImage;
 }
 
+public abstract interface annotation class love/forte/simbot/message/OfflineImageImplementation : java/lang/annotation/Annotation {
+}
+
 public abstract interface class love/forte/simbot/message/OfflineImageResolver {
 	public static final field Companion Llove/forte/simbot/message/OfflineImageResolver$Companion;
 	public static fun resolve (Llove/forte/simbot/message/OfflineImageResolver;Llove/forte/simbot/message/OfflineImage;Ljava/lang/Object;)V
@@ -2335,6 +2338,9 @@ public abstract interface class love/forte/simbot/message/RemoteUrlAwareImage :
 public abstract interface class love/forte/simbot/message/RichMediaMessage : love/forte/simbot/message/StandardMessage {
 }
 
+public abstract interface annotation class love/forte/simbot/message/ScheduledDeprecatedOfflineImageResolverApi : java/lang/annotation/Annotation {
+}
+
 public final class love/forte/simbot/message/SimpleOfflineResourceImage : love/forte/simbot/message/OfflineResourceImage {
 	public static final field Companion Llove/forte/simbot/message/SimpleOfflineResourceImage$Companion;
 	public fun <init> (Llove/forte/simbot/resource/Resource;)V

simbot-api/build.gradle.kts

@@ -67,8 +67,9 @@ kotlin {
         freeCompilerArgs.addAll(
             "-Xexpect-actual-classes"
         )
-        optIn.add(
-            "love.forte.simbot.resource.ResourceImplementation"
+        optIn.addAll(
+            "love.forte.simbot.resource.ResourceImplementation",
+            "love.forte.simbot.message.OfflineImageImplementation",
         )
     }
 

simbot-api/src/commonMain/kotlin/love/forte/simbot/message/OfflineImageImplementation.kt

@@ -0,0 +1,41 @@
+/*
+ *     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.message
+
+/**
+ * [OfflineImage] 的外部实现是不稳定的，
+ * [OfflineImage] 的实现应该是内部的，目前 [OfflineImage] 不保证第三方实现未来的稳定与兼容。
+ *
+ * @since 4.11.0
+ */
+@Target(AnnotationTarget.CLASS, AnnotationTarget.ANNOTATION_CLASS)
+@RequiresOptIn(
+    message = "`OfflineImage` implementation is unstable. " +
+        "The implementation of `OfflineImage` should be internal. " +
+        "Currently, `OfflineImage` does not guarantee the stability " +
+        "and compatibility of third-party implementations in the future.",
+    level = RequiresOptIn.Level.WARNING
+)
+@MustBeDocumented
+public annotation class OfflineImageImplementation

simbot-api/src/commonMain/kotlin/love/forte/simbot/message/OfflineImageResolver.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]
@@ -25,8 +25,25 @@ package love.forte.simbot.message
 
 import love.forte.simbot.resource.*
 import love.forte.simbot.resource.ResourceResolver.Companion.resolve
+import kotlin.annotation.AnnotationRetention.BINARY
+import kotlin.annotation.AnnotationTarget.CLASS
+import kotlin.annotation.AnnotationTarget.FUNCTION
 import kotlin.jvm.JvmStatic
 
+/**
+ * 计划被废弃的与 [OfflineImageResolver] 相关的API
+ *
+ * @since 4.11.0
+ */
+@RequiresOptIn(
+    message = "计划被废弃的与 `OfflineImageResolver` 相关的API. 详见 " +
+        "`love.forte.simbot.message.OfflineImageResolver` 中的有关说明。",
+    level = RequiresOptIn.Level.ERROR
+)
+@Retention(BINARY)
+@Target(CLASS, FUNCTION)
+@MustBeDocumented
+public annotation class ScheduledDeprecatedOfflineImageResolverApi
 
 /**
  * 使用 [OfflineImageResolver] 分析处理一个 [OfflineImage].
@@ -37,6 +54,7 @@ import kotlin.jvm.JvmStatic
  *
  * @author ForteScarlet
  */
+@ScheduledDeprecatedOfflineImageResolverApi
 public interface OfflineImageResolver<C> {
 
     /**
@@ -63,7 +81,6 @@ public interface OfflineImageResolver<C> {
             when (image) {
                 is OfflineByteArrayImage -> resolveByteArray(image, context)
                 is OfflineResourceImage -> resolveResource(image, context)
-                else -> resolveUnknown(image, context)
             }
         }
     }
@@ -74,6 +91,7 @@ public interface OfflineImageResolver<C> {
  * 对其中可能出现的实际内容物（例如 [ByteArray] 或 [String]）进行处理。
  */
 @ScheduledDeprecatedResourceApi
+@ScheduledDeprecatedOfflineImageResolverApi
 public interface OfflineImageValueResolver<C> :
     OfflineImageResolver<C>,
     ResourceResolver<C> {

simbot-api/src/commonMain/kotlin/love/forte/simbot/message/StandardMessages.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]
@@ -380,6 +380,7 @@ public sealed interface OfflineImage : Image {
 /**
  * 一个基于 [Resource] 的 [OfflineImage] 实现。
  */
+@SubclassOptInRequired(OfflineImageImplementation::class)
 public interface OfflineResourceImage : OfflineImage {
     /**
      * 关联的资源对象

simbot-api/src/jvmMain/kotlin/love/forte/simbot/message/OfflineImageResolver.jvm.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]
@@ -32,6 +32,7 @@ import kotlin.io.path.toPath
 /**
  * JVM 平台下的 [OfflineImageResolver] 扩展类型。
  */
+@ScheduledDeprecatedOfflineImageResolverApi
 public interface JvmOfflineImageResolver<C> : OfflineImageResolver<C> {
     /**
      * 处理类型为 [OfflineFileImage] 的 resource.
@@ -72,6 +73,7 @@ public interface JvmOfflineImageResolver<C> : OfflineImageResolver<C> {
  * 对其中可能出现的实际内容物（例如 [File] 或 [Path]）进行处理。
  */
 @ScheduledDeprecatedResourceApi
+@ScheduledDeprecatedOfflineImageResolverApi
 public abstract class JvmOfflineImageValueResolver<C> :
     OfflineImageValueResolver<C>,
     JvmOfflineImageResolver<C>,