[core] Introduce MessageIdentity

2025-04-25 04:50:26 +08:00 · 2023-07-26 17:56:15 +08:00 · 2023-07-26 17:56:15 +08:00 · 42de881e9d
commit 42de881e9d
parent 08041f34ab
6 changed files with 456 additions and 16 deletions
--- a/mirai-core-api/compatibility-validation/android/api/android.api
+++ b/mirai-core-api/compatibility-validation/android/api/android.api
@ -4577,7 +4577,7 @@ public final class net/mamoe/mirai/message/data/MessageOriginKind$Companion {
 	public final fun serializer ()Lkotlinx/serialization/KSerializer;
 }

-public abstract class net/mamoe/mirai/message/data/MessageSource : net/mamoe/mirai/message/data/ConstrainSingle, net/mamoe/mirai/message/data/Message, net/mamoe/mirai/message/data/MessageMetadata {
+public abstract class net/mamoe/mirai/message/data/MessageSource : net/mamoe/mirai/message/data/ConstrainSingle, net/mamoe/mirai/message/data/Message, net/mamoe/mirai/message/data/MessageMetadata, net/mamoe/mirai/message/source/FullyMessageIdentity {
 	public static final field Key Lnet/mamoe/mirai/message/data/MessageSource$Key;
 	public static final field SERIAL_NAME Ljava/lang/String;
 	public abstract fun getBotId ()J
@ -5411,6 +5411,112 @@ public final class net/mamoe/mirai/message/data/XmlMessageBuilder$ItemBuilder {
 public final class net/mamoe/mirai/message/data/visitor/MessageVisitorKt {
 }

+public abstract interface class net/mamoe/mirai/message/source/FullyMessageIdentity : net/mamoe/mirai/message/source/MessageIdentity {
+	public fun convertToRawFullyMessageIdentity ()Lnet/mamoe/mirai/message/source/RawFullyMessageIdentity;
+	public abstract fun getFromId ()J
+	public abstract fun getKind ()Lnet/mamoe/mirai/message/data/MessageSourceKind;
+	public abstract fun getTargetId ()J
+}
+
+public final class net/mamoe/mirai/message/source/FullyMessageIdentitySerializer : kotlinx/serialization/KSerializer {
+	public static final field INSTANCE Lnet/mamoe/mirai/message/source/FullyMessageIdentitySerializer;
+	public synthetic fun deserialize (Lkotlinx/serialization/encoding/Decoder;)Ljava/lang/Object;
+	public fun deserialize (Lkotlinx/serialization/encoding/Decoder;)Lnet/mamoe/mirai/message/source/FullyMessageIdentity;
+	public fun getDescriptor ()Lkotlinx/serialization/descriptors/SerialDescriptor;
+	public synthetic fun serialize (Lkotlinx/serialization/encoding/Encoder;Ljava/lang/Object;)V
+	public fun serialize (Lkotlinx/serialization/encoding/Encoder;Lnet/mamoe/mirai/message/source/FullyMessageIdentity;)V
+}
+
+public abstract interface class net/mamoe/mirai/message/source/MessageIdentity {
+	public fun convertToRawMessageIdentity ()Lnet/mamoe/mirai/message/source/RawMessageIdentity;
+	public abstract fun getIds ()[I
+	public abstract fun getInternalIds ()[I
+	public abstract fun getTime ()I
+}
+
+public final class net/mamoe/mirai/message/source/MessageIdentitySerializer : kotlinx/serialization/KSerializer {
+	public static final field INSTANCE Lnet/mamoe/mirai/message/source/MessageIdentitySerializer;
+	public synthetic fun deserialize (Lkotlinx/serialization/encoding/Decoder;)Ljava/lang/Object;
+	public fun deserialize (Lkotlinx/serialization/encoding/Decoder;)Lnet/mamoe/mirai/message/source/MessageIdentity;
+	public fun getDescriptor ()Lkotlinx/serialization/descriptors/SerialDescriptor;
+	public synthetic fun serialize (Lkotlinx/serialization/encoding/Encoder;Ljava/lang/Object;)V
+	public fun serialize (Lkotlinx/serialization/encoding/Encoder;Lnet/mamoe/mirai/message/source/MessageIdentity;)V
+}
+
+public final class net/mamoe/mirai/message/source/RawFullyMessageIdentity : net/mamoe/mirai/message/source/FullyMessageIdentity {
+	public static final field Companion Lnet/mamoe/mirai/message/source/RawFullyMessageIdentity$Companion;
+	public synthetic fun <init> (I[I[IIJJLnet/mamoe/mirai/message/data/MessageSourceKind;Lkotlinx/serialization/internal/SerializationConstructorMarker;)V
+	public fun <init> ([I[IIJJLnet/mamoe/mirai/message/data/MessageSourceKind;)V
+	public final fun component1 ()[I
+	public final fun component2 ()[I
+	public final fun component3 ()I
+	public final fun component4 ()J
+	public final fun component5 ()J
+	public final fun component6 ()Lnet/mamoe/mirai/message/data/MessageSourceKind;
+	public fun convertToRawFullyMessageIdentity ()Lnet/mamoe/mirai/message/source/RawFullyMessageIdentity;
+	public final fun copy ([I[IIJJLnet/mamoe/mirai/message/data/MessageSourceKind;)Lnet/mamoe/mirai/message/source/RawFullyMessageIdentity;
+	public static synthetic fun copy$default (Lnet/mamoe/mirai/message/source/RawFullyMessageIdentity;[I[IIJJLnet/mamoe/mirai/message/data/MessageSourceKind;ILjava/lang/Object;)Lnet/mamoe/mirai/message/source/RawFullyMessageIdentity;
+	public fun equals (Ljava/lang/Object;)Z
+	public fun getFromId ()J
+	public fun getIds ()[I
+	public fun getInternalIds ()[I
+	public fun getKind ()Lnet/mamoe/mirai/message/data/MessageSourceKind;
+	public fun getTargetId ()J
+	public fun getTime ()I
+	public fun hashCode ()I
+	public fun toString ()Ljava/lang/String;
+	public static final fun write$Self (Lnet/mamoe/mirai/message/source/RawFullyMessageIdentity;Lkotlinx/serialization/encoding/CompositeEncoder;Lkotlinx/serialization/descriptors/SerialDescriptor;)V
+}
+
+public final class net/mamoe/mirai/message/source/RawFullyMessageIdentity$$serializer : kotlinx/serialization/internal/GeneratedSerializer {
+	public static final field INSTANCE Lnet/mamoe/mirai/message/source/RawFullyMessageIdentity$$serializer;
+	public fun childSerializers ()[Lkotlinx/serialization/KSerializer;
+	public synthetic fun deserialize (Lkotlinx/serialization/encoding/Decoder;)Ljava/lang/Object;
+	public fun deserialize (Lkotlinx/serialization/encoding/Decoder;)Lnet/mamoe/mirai/message/source/RawFullyMessageIdentity;
+	public fun getDescriptor ()Lkotlinx/serialization/descriptors/SerialDescriptor;
+	public synthetic fun serialize (Lkotlinx/serialization/encoding/Encoder;Ljava/lang/Object;)V
+	public fun serialize (Lkotlinx/serialization/encoding/Encoder;Lnet/mamoe/mirai/message/source/RawFullyMessageIdentity;)V
+	public fun typeParametersSerializers ()[Lkotlinx/serialization/KSerializer;
+}
+
+public final class net/mamoe/mirai/message/source/RawFullyMessageIdentity$Companion {
+	public final fun serializer ()Lkotlinx/serialization/KSerializer;
+}
+
+public final class net/mamoe/mirai/message/source/RawMessageIdentity : net/mamoe/mirai/message/source/MessageIdentity {
+	public static final field Companion Lnet/mamoe/mirai/message/source/RawMessageIdentity$Companion;
+	public synthetic fun <init> (I[I[IILkotlinx/serialization/internal/SerializationConstructorMarker;)V
+	public fun <init> ([I[II)V
+	public final fun component1 ()[I
+	public final fun component2 ()[I
+	public final fun component3 ()I
+	public fun convertToRawMessageIdentity ()Lnet/mamoe/mirai/message/source/RawMessageIdentity;
+	public final fun copy ([I[II)Lnet/mamoe/mirai/message/source/RawMessageIdentity;
+	public static synthetic fun copy$default (Lnet/mamoe/mirai/message/source/RawMessageIdentity;[I[IIILjava/lang/Object;)Lnet/mamoe/mirai/message/source/RawMessageIdentity;
+	public fun equals (Ljava/lang/Object;)Z
+	public fun getIds ()[I
+	public fun getInternalIds ()[I
+	public fun getTime ()I
+	public fun hashCode ()I
+	public fun toString ()Ljava/lang/String;
+	public static final fun write$Self (Lnet/mamoe/mirai/message/source/RawMessageIdentity;Lkotlinx/serialization/encoding/CompositeEncoder;Lkotlinx/serialization/descriptors/SerialDescriptor;)V
+}
+
+public final class net/mamoe/mirai/message/source/RawMessageIdentity$$serializer : kotlinx/serialization/internal/GeneratedSerializer {
+	public static final field INSTANCE Lnet/mamoe/mirai/message/source/RawMessageIdentity$$serializer;
+	public fun childSerializers ()[Lkotlinx/serialization/KSerializer;
+	public synthetic fun deserialize (Lkotlinx/serialization/encoding/Decoder;)Ljava/lang/Object;
+	public fun deserialize (Lkotlinx/serialization/encoding/Decoder;)Lnet/mamoe/mirai/message/source/RawMessageIdentity;
+	public fun getDescriptor ()Lkotlinx/serialization/descriptors/SerialDescriptor;
+	public synthetic fun serialize (Lkotlinx/serialization/encoding/Encoder;Ljava/lang/Object;)V
+	public fun serialize (Lkotlinx/serialization/encoding/Encoder;Lnet/mamoe/mirai/message/source/RawMessageIdentity;)V
+	public fun typeParametersSerializers ()[Lkotlinx/serialization/KSerializer;
+}
+
+public final class net/mamoe/mirai/message/source/RawMessageIdentity$Companion {
+	public final fun serializer ()Lkotlinx/serialization/KSerializer;
+}
+
 public final class net/mamoe/mirai/network/BotAuthorizationException : net/mamoe/mirai/network/LoginFailedException {
 	public final fun getAuthorization ()Lnet/mamoe/mirai/auth/BotAuthorization;
 }
--- a/mirai-core-api/compatibility-validation/jvm/api/jvm.api
+++ b/mirai-core-api/compatibility-validation/jvm/api/jvm.api
@ -4577,7 +4577,7 @@ public final class net/mamoe/mirai/message/data/MessageOriginKind$Companion {
 	public final fun serializer ()Lkotlinx/serialization/KSerializer;
 }

-public abstract class net/mamoe/mirai/message/data/MessageSource : net/mamoe/mirai/message/data/ConstrainSingle, net/mamoe/mirai/message/data/Message, net/mamoe/mirai/message/data/MessageMetadata {
+public abstract class net/mamoe/mirai/message/data/MessageSource : net/mamoe/mirai/message/data/ConstrainSingle, net/mamoe/mirai/message/data/Message, net/mamoe/mirai/message/data/MessageMetadata, net/mamoe/mirai/message/source/FullyMessageIdentity {
 	public static final field Key Lnet/mamoe/mirai/message/data/MessageSource$Key;
 	public static final field SERIAL_NAME Ljava/lang/String;
 	public abstract fun getBotId ()J
@ -5411,6 +5411,112 @@ public final class net/mamoe/mirai/message/data/XmlMessageBuilder$ItemBuilder {
 public final class net/mamoe/mirai/message/data/visitor/MessageVisitorKt {
 }

+public abstract interface class net/mamoe/mirai/message/source/FullyMessageIdentity : net/mamoe/mirai/message/source/MessageIdentity {
+	public fun convertToRawFullyMessageIdentity ()Lnet/mamoe/mirai/message/source/RawFullyMessageIdentity;
+	public abstract fun getFromId ()J
+	public abstract fun getKind ()Lnet/mamoe/mirai/message/data/MessageSourceKind;
+	public abstract fun getTargetId ()J
+}
+
+public final class net/mamoe/mirai/message/source/FullyMessageIdentitySerializer : kotlinx/serialization/KSerializer {
+	public static final field INSTANCE Lnet/mamoe/mirai/message/source/FullyMessageIdentitySerializer;
+	public synthetic fun deserialize (Lkotlinx/serialization/encoding/Decoder;)Ljava/lang/Object;
+	public fun deserialize (Lkotlinx/serialization/encoding/Decoder;)Lnet/mamoe/mirai/message/source/FullyMessageIdentity;
+	public fun getDescriptor ()Lkotlinx/serialization/descriptors/SerialDescriptor;
+	public synthetic fun serialize (Lkotlinx/serialization/encoding/Encoder;Ljava/lang/Object;)V
+	public fun serialize (Lkotlinx/serialization/encoding/Encoder;Lnet/mamoe/mirai/message/source/FullyMessageIdentity;)V
+}
+
+public abstract interface class net/mamoe/mirai/message/source/MessageIdentity {
+	public fun convertToRawMessageIdentity ()Lnet/mamoe/mirai/message/source/RawMessageIdentity;
+	public abstract fun getIds ()[I
+	public abstract fun getInternalIds ()[I
+	public abstract fun getTime ()I
+}
+
+public final class net/mamoe/mirai/message/source/MessageIdentitySerializer : kotlinx/serialization/KSerializer {
+	public static final field INSTANCE Lnet/mamoe/mirai/message/source/MessageIdentitySerializer;
+	public synthetic fun deserialize (Lkotlinx/serialization/encoding/Decoder;)Ljava/lang/Object;
+	public fun deserialize (Lkotlinx/serialization/encoding/Decoder;)Lnet/mamoe/mirai/message/source/MessageIdentity;
+	public fun getDescriptor ()Lkotlinx/serialization/descriptors/SerialDescriptor;
+	public synthetic fun serialize (Lkotlinx/serialization/encoding/Encoder;Ljava/lang/Object;)V
+	public fun serialize (Lkotlinx/serialization/encoding/Encoder;Lnet/mamoe/mirai/message/source/MessageIdentity;)V
+}
+
+public final class net/mamoe/mirai/message/source/RawFullyMessageIdentity : net/mamoe/mirai/message/source/FullyMessageIdentity {
+	public static final field Companion Lnet/mamoe/mirai/message/source/RawFullyMessageIdentity$Companion;
+	public synthetic fun <init> (I[I[IIJJLnet/mamoe/mirai/message/data/MessageSourceKind;Lkotlinx/serialization/internal/SerializationConstructorMarker;)V
+	public fun <init> ([I[IIJJLnet/mamoe/mirai/message/data/MessageSourceKind;)V
+	public final fun component1 ()[I
+	public final fun component2 ()[I
+	public final fun component3 ()I
+	public final fun component4 ()J
+	public final fun component5 ()J
+	public final fun component6 ()Lnet/mamoe/mirai/message/data/MessageSourceKind;
+	public fun convertToRawFullyMessageIdentity ()Lnet/mamoe/mirai/message/source/RawFullyMessageIdentity;
+	public final fun copy ([I[IIJJLnet/mamoe/mirai/message/data/MessageSourceKind;)Lnet/mamoe/mirai/message/source/RawFullyMessageIdentity;
+	public static synthetic fun copy$default (Lnet/mamoe/mirai/message/source/RawFullyMessageIdentity;[I[IIJJLnet/mamoe/mirai/message/data/MessageSourceKind;ILjava/lang/Object;)Lnet/mamoe/mirai/message/source/RawFullyMessageIdentity;
+	public fun equals (Ljava/lang/Object;)Z
+	public fun getFromId ()J
+	public fun getIds ()[I
+	public fun getInternalIds ()[I
+	public fun getKind ()Lnet/mamoe/mirai/message/data/MessageSourceKind;
+	public fun getTargetId ()J
+	public fun getTime ()I
+	public fun hashCode ()I
+	public fun toString ()Ljava/lang/String;
+	public static final fun write$Self (Lnet/mamoe/mirai/message/source/RawFullyMessageIdentity;Lkotlinx/serialization/encoding/CompositeEncoder;Lkotlinx/serialization/descriptors/SerialDescriptor;)V
+}
+
+public final class net/mamoe/mirai/message/source/RawFullyMessageIdentity$$serializer : kotlinx/serialization/internal/GeneratedSerializer {
+	public static final field INSTANCE Lnet/mamoe/mirai/message/source/RawFullyMessageIdentity$$serializer;
+	public fun childSerializers ()[Lkotlinx/serialization/KSerializer;
+	public synthetic fun deserialize (Lkotlinx/serialization/encoding/Decoder;)Ljava/lang/Object;
+	public fun deserialize (Lkotlinx/serialization/encoding/Decoder;)Lnet/mamoe/mirai/message/source/RawFullyMessageIdentity;
+	public fun getDescriptor ()Lkotlinx/serialization/descriptors/SerialDescriptor;
+	public synthetic fun serialize (Lkotlinx/serialization/encoding/Encoder;Ljava/lang/Object;)V
+	public fun serialize (Lkotlinx/serialization/encoding/Encoder;Lnet/mamoe/mirai/message/source/RawFullyMessageIdentity;)V
+	public fun typeParametersSerializers ()[Lkotlinx/serialization/KSerializer;
+}
+
+public final class net/mamoe/mirai/message/source/RawFullyMessageIdentity$Companion {
+	public final fun serializer ()Lkotlinx/serialization/KSerializer;
+}
+
+public final class net/mamoe/mirai/message/source/RawMessageIdentity : net/mamoe/mirai/message/source/MessageIdentity {
+	public static final field Companion Lnet/mamoe/mirai/message/source/RawMessageIdentity$Companion;
+	public synthetic fun <init> (I[I[IILkotlinx/serialization/internal/SerializationConstructorMarker;)V
+	public fun <init> ([I[II)V
+	public final fun component1 ()[I
+	public final fun component2 ()[I
+	public final fun component3 ()I
+	public fun convertToRawMessageIdentity ()Lnet/mamoe/mirai/message/source/RawMessageIdentity;
+	public final fun copy ([I[II)Lnet/mamoe/mirai/message/source/RawMessageIdentity;
+	public static synthetic fun copy$default (Lnet/mamoe/mirai/message/source/RawMessageIdentity;[I[IIILjava/lang/Object;)Lnet/mamoe/mirai/message/source/RawMessageIdentity;
+	public fun equals (Ljava/lang/Object;)Z
+	public fun getIds ()[I
+	public fun getInternalIds ()[I
+	public fun getTime ()I
+	public fun hashCode ()I
+	public fun toString ()Ljava/lang/String;
+	public static final fun write$Self (Lnet/mamoe/mirai/message/source/RawMessageIdentity;Lkotlinx/serialization/encoding/CompositeEncoder;Lkotlinx/serialization/descriptors/SerialDescriptor;)V
+}
+
+public final class net/mamoe/mirai/message/source/RawMessageIdentity$$serializer : kotlinx/serialization/internal/GeneratedSerializer {
+	public static final field INSTANCE Lnet/mamoe/mirai/message/source/RawMessageIdentity$$serializer;
+	public fun childSerializers ()[Lkotlinx/serialization/KSerializer;
+	public synthetic fun deserialize (Lkotlinx/serialization/encoding/Decoder;)Ljava/lang/Object;
+	public fun deserialize (Lkotlinx/serialization/encoding/Decoder;)Lnet/mamoe/mirai/message/source/RawMessageIdentity;
+	public fun getDescriptor ()Lkotlinx/serialization/descriptors/SerialDescriptor;
+	public synthetic fun serialize (Lkotlinx/serialization/encoding/Encoder;Ljava/lang/Object;)V
+	public fun serialize (Lkotlinx/serialization/encoding/Encoder;Lnet/mamoe/mirai/message/source/RawMessageIdentity;)V
+	public fun typeParametersSerializers ()[Lkotlinx/serialization/KSerializer;
+}
+
+public final class net/mamoe/mirai/message/source/RawMessageIdentity$Companion {
+	public final fun serializer ()Lkotlinx/serialization/KSerializer;
+}
+
 public final class net/mamoe/mirai/network/BotAuthorizationException : net/mamoe/mirai/network/LoginFailedException {
 	public final fun getAuthorization ()Lnet/mamoe/mirai/auth/BotAuthorization;
 }
--- a/mirai-core-api/src/commonMain/kotlin/message/data/MessageSource.kt
+++ b/mirai-core-api/src/commonMain/kotlin/message/data/MessageSource.kt
@ -34,13 +34,10 @@ import net.mamoe.mirai.message.action.AsyncRecallResult
 import net.mamoe.mirai.message.data.MessageSource.Key.quote
 import net.mamoe.mirai.message.data.MessageSource.Key.recall
 import net.mamoe.mirai.message.data.visitor.MessageVisitor
+import net.mamoe.mirai.message.source.FullyMessageIdentity
 import net.mamoe.mirai.utils.DeprecatedSinceMirai
 import net.mamoe.mirai.utils.MiraiInternalApi
 import net.mamoe.mirai.utils.safeCast
-import kotlin.jvm.JvmMultifileClass
-import kotlin.jvm.JvmName
-import kotlin.jvm.JvmStatic
-import kotlin.jvm.JvmSynthetic

 /**
 * 表示聊天中的一条消息的定位信息, 即消息源.
@ -128,7 +125,7 @@ import kotlin.jvm.JvmSynthetic
 */
@Suppress("DEPRECATION")
@Serializable(MessageSource.Serializer::class)
-public sealed class MessageSource : Message, MessageMetadata, ConstrainSingle {
+public sealed class MessageSource : Message, MessageMetadata, ConstrainSingle, FullyMessageIdentity {
    public final override val key: MessageKey<MessageSource>
        get() = Key

@ -152,7 +149,7 @@ public sealed class MessageSource : Message, MessageMetadata, ConstrainSingle {
     *
     * [internalIds] 与 [ids] 以数组下标对应.
     */
-    public abstract val ids: IntArray
+    public abstract override val ids: IntArray

    /**
     * 内部 ids. **仅用于协议模块使用**
@ -165,15 +162,12 @@ public sealed class MessageSource : Message, MessageMetadata, ConstrainSingle {
     *
     * @see ids
     */
-    public abstract val internalIds: IntArray
+    public abstract override val internalIds: IntArray

    /**
     * 发送时间时间戳, 单位为秒.
-     *
-     * 自 2.8.0 起, 时间戳为服务器时区 (UTC+8).
-     * 在 2.8.0 以前, 时间戳可能来自服务器 (UTC+8), 也可能来自 mirai (本地), 且无法保证两者时间同步.
     */
-    public abstract val time: Int
+    public abstract override val time: Int

    /**
     * 发送人用户 ID.
@ -182,7 +176,7 @@ public sealed class MessageSource : Message, MessageMetadata, ConstrainSingle {
     * - 当 [OnlineMessageSource.Incoming] 时为发信 [来源用户][User.id] 或 [群][Group.id]
     * - 当 [OfflineMessageSource] 时取决于 [OfflineMessageSource.kind]
     */
-    public abstract val fromId: Long
+    public abstract override val fromId: Long

    /**
     * 消息发送目标用户或群号码.
@ -191,7 +185,7 @@ public sealed class MessageSource : Message, MessageMetadata, ConstrainSingle {
     * - 当 [OnlineMessageSource.Incoming] 时为 [机器人][Bot.id]
     * - 当 [OfflineMessageSource] 时取决于 [OfflineMessageSource.kind]
     */
-    public abstract val targetId: Long // groupCode / friendUin / memberUin
+    public abstract override val targetId: Long // groupCode / friendUin / memberUin

    /**
     * 该消息源指向的原消息的内容.
@ -215,7 +209,7 @@ public sealed class MessageSource : Message, MessageMetadata, ConstrainSingle {
     *
     * @since 2.15
     */
-    public abstract val kind: MessageSourceKind
+    public abstract override val kind: MessageSourceKind

    public abstract override fun toString(): String

--- a/mirai-core-api/src/commonMain/kotlin/message/source/MessageIdentity.data.kt
+++ b/mirai-core-api/src/commonMain/kotlin/message/source/MessageIdentity.data.kt
@ -0,0 +1,81 @@
+/*
+ * Copyright 2019-2023 Mamoe Technologies and contributors.
+ *
+ * 此源代码的使用受 GNU AFFERO GENERAL PUBLIC LICENSE version 3 许可证的约束, 可以在以下链接找到该许可证.
+ * Use of this source code is governed by the GNU AGPLv3 license that can be found through the following link.
+ *
+ * https://github.com/mamoe/mirai/blob/dev/LICENSE
+ */
+
+package net.mamoe.mirai.message.source
+
+import kotlinx.serialization.SerialName
+import kotlinx.serialization.Serializable
+import net.mamoe.mirai.message.data.MessageSourceKind
+
+@Serializable
+@SerialName("MessageIdentity")
+public data class RawMessageIdentity(
+    override val ids: IntArray,
+    override val internalIds: IntArray,
+    override val time: Int,
+) : MessageIdentity {
+    override fun equals(other: Any?): Boolean {
+        if (this === other) return true
+        if (other !is RawMessageIdentity) return false
+
+        if (!ids.contentEquals(other.ids)) return false
+        if (!internalIds.contentEquals(other.internalIds)) return false
+        return time == other.time
+    }
+
+    override fun hashCode(): Int {
+        var result = ids.contentHashCode()
+        result = 31 * result + internalIds.contentHashCode()
+        result = 31 * result + time
+        return result
+    }
+
+    override fun convertToRawMessageIdentity(): RawMessageIdentity {
+        return this
+    }
+}
+
+@Serializable
+@SerialName("FullyMessageIdentity")
+public data class RawFullyMessageIdentity(
+    override val ids: IntArray,
+    override val internalIds: IntArray,
+    override val time: Int,
+    override val fromId: Long,
+    override val targetId: Long,
+    override val kind: MessageSourceKind,
+) : FullyMessageIdentity {
+    override fun equals(other: Any?): Boolean {
+        if (this === other) return true
+        if (other !is RawFullyMessageIdentity) return false
+
+        if (!ids.contentEquals(other.ids)) return false
+        if (!internalIds.contentEquals(other.internalIds)) return false
+        if (time != other.time) return false
+        if (fromId != other.fromId) return false
+        if (targetId != other.targetId) return false
+        return kind == other.kind
+    }
+
+    override fun hashCode(): Int {
+        var result = ids.contentHashCode()
+        result = 31 * result + internalIds.contentHashCode()
+        result = 31 * result + time
+        result = 31 * result + fromId.hashCode()
+        result = 31 * result + targetId.hashCode()
+        result = 31 * result + kind.hashCode()
+        return result
+    }
+
+    override fun convertToRawFullyMessageIdentity(): RawFullyMessageIdentity {
+        return this
+    }
+}
+
+
--- a/mirai-core-api/src/commonMain/kotlin/message/source/MessageIdentity.kt
+++ b/mirai-core-api/src/commonMain/kotlin/message/source/MessageIdentity.kt
@ -0,0 +1,108 @@
+/*
+ * Copyright 2019-2023 Mamoe Technologies and contributors.
+ *
+ * 此源代码的使用受 GNU AFFERO GENERAL PUBLIC LICENSE version 3 许可证的约束, 可以在以下链接找到该许可证.
+ * Use of this source code is governed by the GNU AGPLv3 license that can be found through the following link.
+ *
+ * https://github.com/mamoe/mirai/blob/dev/LICENSE
+ */
+
+package net.mamoe.mirai.message.source
+
+import kotlinx.serialization.Serializable
+import net.mamoe.mirai.message.data.MessageSourceKind
+import net.mamoe.mirai.message.data.ids
+import net.mamoe.mirai.utils.NotStableForInheritance
+import org.jetbrains.annotations.ApiStatus
+
+/**
+ * 用于定位消息的消息凭证符
+ *
+ * @since 2.16.0
+ */
+@NotStableForInheritance
+@ApiStatus.NonExtendable
+@Serializable(MessageIdentitySerializer::class)
+public interface MessageIdentity {
+
+    /**
+     * 消息 ids (序列号). 在获取失败时 (概率很低) 为空数组.
+     *
+     * ### 顺序
+     * 群消息的 id 由服务器维护. 好友消息的 id 由 mirai 维护.
+     * 此 id 不一定从 0 开始.
+     *
+     * - 在同一个群的消息中此值随每条消息递增 1, 但此行为由服务器决定, mirai 不保证自增顺序.
+     * - 在好友消息中无法保证每次都递增 1. 也可能会产生大幅跳过的情况.
+     *
+     * ### 多 ID 情况
+     * 对于单条消息, [ids] 为单元素数组. 对于分片 (一种长消息处理机制) 消息, [ids] 将包含多元素.
+     *
+     * [internalIds] 与 [ids] 以数组下标对应.
+     */
+    public val ids: IntArray
+
+    /**
+     * 内部 ids. **仅用于协议模块使用**
+     *
+     * 值没有顺序, 也可能为 0, 取决于服务器是否提供.
+     *
+     * 在事件中和在引用中无法保证同一条消息的 [internalIds] 相同.
+     *
+     * [internalIds] 与 [ids] 以数组下标对应.
+     *
+     * @see ids
+     */
+    public val internalIds: IntArray
+
+    /**
+     * 发送时间时间戳, 单位为秒.
+     */
+    public val time: Int
+
+
+    public fun convertToRawMessageIdentity(): RawMessageIdentity {
+        return RawMessageIdentity(
+            ids = this.ids,
+            internalIds = this.internalIds,
+            time = this.time,
+        )
+    }
+}
+
+/**
+ * 用于定位消息的消息凭证符, 附带发送者 id 和消息类型
+ *
+ * @since 2.16.0
+ */
+@NotStableForInheritance
+@ApiStatus.NonExtendable
+@Serializable(FullyMessageIdentitySerializer::class)
+public interface FullyMessageIdentity : MessageIdentity {
+
+    /**
+     * 发送人用户 ID.
+     */
+    public val fromId: Long // sender
+
+    /**
+     * 消息发送目标用户或群号码.
+     */
+    public val targetId: Long // groupCode / friendUin / memberUin
+
+    /**
+     * 消息种类
+     */
+    public val kind: MessageSourceKind
+
+    public fun convertToRawFullyMessageIdentity(): RawFullyMessageIdentity {
+        return RawFullyMessageIdentity(
+            ids = ids,
+            internalIds = internalIds,
+            time = time,
+            fromId = fromId,
+            targetId = targetId,
+            kind = kind,
+        )
+    }
+}
--- a/mirai-core-api/src/commonMain/kotlin/message/source/MessageIdentity.serializer.kt
+++ b/mirai-core-api/src/commonMain/kotlin/message/source/MessageIdentity.serializer.kt
@ -0,0 +1,45 @@
+/*
+ * Copyright 2019-2023 Mamoe Technologies and contributors.
+ *
+ * 此源代码的使用受 GNU AFFERO GENERAL PUBLIC LICENSE version 3 许可证的约束, 可以在以下链接找到该许可证.
+ * Use of this source code is governed by the GNU AGPLv3 license that can be found through the following link.
+ *
+ * https://github.com/mamoe/mirai/blob/dev/LICENSE
+ */
+
+package net.mamoe.mirai.message.source
+
+import kotlinx.serialization.KSerializer
+import kotlinx.serialization.descriptors.SerialDescriptor
+import kotlinx.serialization.encoding.Decoder
+import kotlinx.serialization.encoding.Encoder
+
+public object MessageIdentitySerializer : KSerializer<MessageIdentity> {
+    private val delegate = RawMessageIdentity.serializer()
+
+    override val descriptor: SerialDescriptor
+        get() = delegate.descriptor
+
+    override fun deserialize(decoder: Decoder): MessageIdentity {
+        return delegate.deserialize(decoder)
+    }
+
+    override fun serialize(encoder: Encoder, value: MessageIdentity) {
+        delegate.serialize(encoder, value.convertToRawMessageIdentity())
+    }
+}
+
+public object FullyMessageIdentitySerializer : KSerializer<FullyMessageIdentity> {
+    private val delegate = RawFullyMessageIdentity.serializer()
+
+    override val descriptor: SerialDescriptor
+        get() = delegate.descriptor
+
+    override fun deserialize(decoder: Decoder): FullyMessageIdentity {
+        return delegate.deserialize(decoder)
+    }
+
+    override fun serialize(encoder: Encoder, value: FullyMessageIdentity) {
+        delegate.serialize(encoder, value.convertToRawFullyMessageIdentity())
+    }
+}