Add members to make ForwardMessageBuilder easier to use from Java, close #1087

binary-compatibility-validator/android/api/binary-compatibility-validator-android.api

@@ -4224,14 +4224,30 @@ public final class net/mamoe/mirai/message/data/ForwardMessageBuilder : java/uti
 	public fun <init> (Lnet/mamoe/mirai/contact/Contact;I)V
 	public synthetic fun add (ILjava/lang/Object;)V
 	public fun add (ILnet/mamoe/mirai/message/data/ForwardMessage$INode;)V
+	public final fun add (JLjava/lang/String;ILkotlin/jvm/functions/Function1;)Lnet/mamoe/mirai/message/data/ForwardMessageBuilder;
+	public final fun add (JLjava/lang/String;Lkotlin/jvm/functions/Function1;)Lnet/mamoe/mirai/message/data/ForwardMessageBuilder;
+	public final fun add (JLjava/lang/String;Lnet/mamoe/mirai/message/data/Message;)Lnet/mamoe/mirai/message/data/ForwardMessageBuilder;
+	public final fun add (JLjava/lang/String;Lnet/mamoe/mirai/message/data/Message;I)Lnet/mamoe/mirai/message/data/ForwardMessageBuilder;
 	public synthetic fun add (Ljava/lang/Object;)Z
+	public final fun add (Lnet/mamoe/mirai/contact/User;Lnet/mamoe/mirai/message/data/Message;)Lnet/mamoe/mirai/message/data/ForwardMessageBuilder;
+	public final fun add (Lnet/mamoe/mirai/contact/User;Lnet/mamoe/mirai/message/data/Message;I)Lnet/mamoe/mirai/message/data/ForwardMessageBuilder;
+	public final fun add (Lnet/mamoe/mirai/contact/UserOrBot;ILkotlin/jvm/functions/Function1;)Lnet/mamoe/mirai/message/data/ForwardMessageBuilder;
+	public final fun add (Lnet/mamoe/mirai/contact/UserOrBot;Lkotlin/jvm/functions/Function1;)Lnet/mamoe/mirai/message/data/ForwardMessageBuilder;
+	public final fun add (Lnet/mamoe/mirai/contact/UserOrBot;Lnet/mamoe/mirai/message/data/Message;)Lnet/mamoe/mirai/message/data/ForwardMessageBuilder;
+	public final fun add (Lnet/mamoe/mirai/contact/UserOrBot;Lnet/mamoe/mirai/message/data/Message;I)Lnet/mamoe/mirai/message/data/ForwardMessageBuilder;
 	public final fun add (Lnet/mamoe/mirai/event/events/MessageEvent;)Lnet/mamoe/mirai/message/data/ForwardMessageBuilder;
 	public fun add (Lnet/mamoe/mirai/message/data/ForwardMessage$INode;)Z
+	public static synthetic fun add$default (Lnet/mamoe/mirai/message/data/ForwardMessageBuilder;JLjava/lang/String;ILkotlin/jvm/functions/Function1;ILjava/lang/Object;)Lnet/mamoe/mirai/message/data/ForwardMessageBuilder;
+	public static synthetic fun add$default (Lnet/mamoe/mirai/message/data/ForwardMessageBuilder;JLjava/lang/String;Lnet/mamoe/mirai/message/data/Message;IILjava/lang/Object;)Lnet/mamoe/mirai/message/data/ForwardMessageBuilder;
+	public static synthetic fun add$default (Lnet/mamoe/mirai/message/data/ForwardMessageBuilder;Lnet/mamoe/mirai/contact/User;Lnet/mamoe/mirai/message/data/Message;IILjava/lang/Object;)Lnet/mamoe/mirai/message/data/ForwardMessageBuilder;
+	public static synthetic fun add$default (Lnet/mamoe/mirai/message/data/ForwardMessageBuilder;Lnet/mamoe/mirai/contact/UserOrBot;ILkotlin/jvm/functions/Function1;ILjava/lang/Object;)Lnet/mamoe/mirai/message/data/ForwardMessageBuilder;
+	public static synthetic fun add$default (Lnet/mamoe/mirai/message/data/ForwardMessageBuilder;Lnet/mamoe/mirai/contact/UserOrBot;Lnet/mamoe/mirai/message/data/Message;IILjava/lang/Object;)Lnet/mamoe/mirai/message/data/ForwardMessageBuilder;
 	public fun addAll (ILjava/util/Collection;)Z
 	public fun addAll (Ljava/util/Collection;)Z
 	public final fun at (II)Lnet/mamoe/mirai/message/data/ForwardMessageBuilder$BuilderNode;
 	public final fun at (JI)Lnet/mamoe/mirai/message/data/ForwardMessageBuilder$BuilderNode;
 	public final fun at (Lnet/mamoe/mirai/contact/User;I)Lnet/mamoe/mirai/message/data/ForwardMessageBuilder$BuilderNode;
+	public final fun at (Lnet/mamoe/mirai/contact/UserOrBot;I)Lnet/mamoe/mirai/message/data/ForwardMessageBuilder$BuilderNode;
 	public final fun build ()Lnet/mamoe/mirai/message/data/ForwardMessage;
 	public fun clear ()V
 	public final fun contains (Ljava/lang/Object;)Z
@@ -4254,6 +4270,7 @@ public final class net/mamoe/mirai/message/data/ForwardMessageBuilder : java/uti
 	public final fun named (ILjava/lang/String;)Lnet/mamoe/mirai/message/data/ForwardMessageBuilder$BuilderNode;
 	public final fun named (JLjava/lang/String;)Lnet/mamoe/mirai/message/data/ForwardMessageBuilder$BuilderNode;
 	public final fun named (Lnet/mamoe/mirai/contact/User;Ljava/lang/String;)Lnet/mamoe/mirai/message/data/ForwardMessageBuilder$BuilderNode;
+	public final fun named (Lnet/mamoe/mirai/contact/UserOrBot;Ljava/lang/String;)Lnet/mamoe/mirai/message/data/ForwardMessageBuilder$BuilderNode;
 	public synthetic fun remove (I)Ljava/lang/Object;
 	public final fun remove (I)Lnet/mamoe/mirai/message/data/ForwardMessage$INode;
 	public final fun remove (Ljava/lang/Object;)Z
@@ -4273,6 +4290,8 @@ public final class net/mamoe/mirai/message/data/ForwardMessageBuilder : java/uti
 	public final fun says (Lnet/mamoe/mirai/contact/User;Ljava/lang/String;)Lnet/mamoe/mirai/message/data/ForwardMessageBuilder;
 	public final fun says (Lnet/mamoe/mirai/contact/User;Lkotlin/jvm/functions/Function1;)Lnet/mamoe/mirai/message/data/ForwardMessageBuilder;
 	public final fun says (Lnet/mamoe/mirai/contact/User;Lnet/mamoe/mirai/message/data/Message;)Lnet/mamoe/mirai/message/data/ForwardMessageBuilder;
+	public final fun says (Lnet/mamoe/mirai/contact/UserOrBot;Lkotlin/jvm/functions/Function1;)Lnet/mamoe/mirai/message/data/ForwardMessageBuilder;
+	public final fun says (Lnet/mamoe/mirai/contact/UserOrBot;Lnet/mamoe/mirai/message/data/Message;)Lnet/mamoe/mirai/message/data/ForwardMessageBuilder;
 	public synthetic fun set (ILjava/lang/Object;)Ljava/lang/Object;
 	public fun set (ILnet/mamoe/mirai/message/data/ForwardMessage$INode;)Lnet/mamoe/mirai/message/data/ForwardMessage$INode;
 	public final fun setCurrentTime (I)V
@@ -4297,6 +4316,7 @@ public final class net/mamoe/mirai/message/data/ForwardMessageBuilder$BuilderNod
 	public final fun says (Lkotlin/jvm/functions/Function1;)Lnet/mamoe/mirai/message/data/ForwardMessageBuilder;
 	public final fun says (Lnet/mamoe/mirai/message/data/Message;)Lnet/mamoe/mirai/message/data/ForwardMessageBuilder;
 	public final fun sender (Lnet/mamoe/mirai/contact/User;)Lnet/mamoe/mirai/message/data/ForwardMessageBuilder$BuilderNode;
+	public final fun sender (Lnet/mamoe/mirai/contact/UserOrBot;)Lnet/mamoe/mirai/message/data/ForwardMessageBuilder$BuilderNode;
 	public final fun senderId (I)Lnet/mamoe/mirai/message/data/ForwardMessageBuilder$BuilderNode;
 	public final fun senderId (J)Lnet/mamoe/mirai/message/data/ForwardMessageBuilder$BuilderNode;
 	public final fun senderName (Ljava/lang/String;)Lnet/mamoe/mirai/message/data/ForwardMessageBuilder$BuilderNode;
@@ -4708,8 +4728,8 @@ public final class net/mamoe/mirai/message/data/MessageUtils {
 	public static final synthetic fun FileMessage (Ljava/lang/String;ILjava/lang/String;J)Lnet/mamoe/mirai/message/data/FileMessage;
 	public static final synthetic fun Image (Ljava/lang/String;)Lnet/mamoe/mirai/message/data/Image;
 	public static final synthetic fun at (Lnet/mamoe/mirai/contact/Member;)Lnet/mamoe/mirai/message/data/At;
-	public static final synthetic fun buildMessageChain (ILkotlin/jvm/functions/Function1;)Lnet/mamoe/mirai/message/data/MessageChain;
+	public static final fun buildMessageChain (ILkotlin/jvm/functions/Function1;)Lnet/mamoe/mirai/message/data/MessageChain;
-	public static final synthetic fun buildMessageChain (Lkotlin/jvm/functions/Function1;)Lnet/mamoe/mirai/message/data/MessageChain;
+	public static final fun buildMessageChain (Lkotlin/jvm/functions/Function1;)Lnet/mamoe/mirai/message/data/MessageChain;
 	public static final synthetic fun buildMessageSource (Lnet/mamoe/mirai/Bot;Lnet/mamoe/mirai/message/data/MessageSourceKind;Lkotlin/jvm/functions/Function1;)Lnet/mamoe/mirai/message/data/OfflineMessageSource;
 	public static final synthetic fun buildMessageSource (Lnet/mamoe/mirai/IMirai;JLnet/mamoe/mirai/message/data/MessageSourceKind;Lkotlin/jvm/functions/Function1;)Lnet/mamoe/mirai/message/data/OfflineMessageSource;
 	public static final synthetic fun buildXmlMessage (ILkotlin/jvm/functions/Function1;)Lnet/mamoe/mirai/message/data/ServiceMessage;

binary-compatibility-validator/api/binary-compatibility-validator.api

@@ -4224,14 +4224,30 @@ public final class net/mamoe/mirai/message/data/ForwardMessageBuilder : java/uti
 	public fun <init> (Lnet/mamoe/mirai/contact/Contact;I)V
 	public synthetic fun add (ILjava/lang/Object;)V
 	public fun add (ILnet/mamoe/mirai/message/data/ForwardMessage$INode;)V
+	public final fun add (JLjava/lang/String;ILkotlin/jvm/functions/Function1;)Lnet/mamoe/mirai/message/data/ForwardMessageBuilder;
+	public final fun add (JLjava/lang/String;Lkotlin/jvm/functions/Function1;)Lnet/mamoe/mirai/message/data/ForwardMessageBuilder;
+	public final fun add (JLjava/lang/String;Lnet/mamoe/mirai/message/data/Message;)Lnet/mamoe/mirai/message/data/ForwardMessageBuilder;
+	public final fun add (JLjava/lang/String;Lnet/mamoe/mirai/message/data/Message;I)Lnet/mamoe/mirai/message/data/ForwardMessageBuilder;
 	public synthetic fun add (Ljava/lang/Object;)Z
+	public final fun add (Lnet/mamoe/mirai/contact/User;Lnet/mamoe/mirai/message/data/Message;)Lnet/mamoe/mirai/message/data/ForwardMessageBuilder;
+	public final fun add (Lnet/mamoe/mirai/contact/User;Lnet/mamoe/mirai/message/data/Message;I)Lnet/mamoe/mirai/message/data/ForwardMessageBuilder;
+	public final fun add (Lnet/mamoe/mirai/contact/UserOrBot;ILkotlin/jvm/functions/Function1;)Lnet/mamoe/mirai/message/data/ForwardMessageBuilder;
+	public final fun add (Lnet/mamoe/mirai/contact/UserOrBot;Lkotlin/jvm/functions/Function1;)Lnet/mamoe/mirai/message/data/ForwardMessageBuilder;
+	public final fun add (Lnet/mamoe/mirai/contact/UserOrBot;Lnet/mamoe/mirai/message/data/Message;)Lnet/mamoe/mirai/message/data/ForwardMessageBuilder;
+	public final fun add (Lnet/mamoe/mirai/contact/UserOrBot;Lnet/mamoe/mirai/message/data/Message;I)Lnet/mamoe/mirai/message/data/ForwardMessageBuilder;
 	public final fun add (Lnet/mamoe/mirai/event/events/MessageEvent;)Lnet/mamoe/mirai/message/data/ForwardMessageBuilder;
 	public fun add (Lnet/mamoe/mirai/message/data/ForwardMessage$INode;)Z
+	public static synthetic fun add$default (Lnet/mamoe/mirai/message/data/ForwardMessageBuilder;JLjava/lang/String;ILkotlin/jvm/functions/Function1;ILjava/lang/Object;)Lnet/mamoe/mirai/message/data/ForwardMessageBuilder;
+	public static synthetic fun add$default (Lnet/mamoe/mirai/message/data/ForwardMessageBuilder;JLjava/lang/String;Lnet/mamoe/mirai/message/data/Message;IILjava/lang/Object;)Lnet/mamoe/mirai/message/data/ForwardMessageBuilder;
+	public static synthetic fun add$default (Lnet/mamoe/mirai/message/data/ForwardMessageBuilder;Lnet/mamoe/mirai/contact/User;Lnet/mamoe/mirai/message/data/Message;IILjava/lang/Object;)Lnet/mamoe/mirai/message/data/ForwardMessageBuilder;
+	public static synthetic fun add$default (Lnet/mamoe/mirai/message/data/ForwardMessageBuilder;Lnet/mamoe/mirai/contact/UserOrBot;ILkotlin/jvm/functions/Function1;ILjava/lang/Object;)Lnet/mamoe/mirai/message/data/ForwardMessageBuilder;
+	public static synthetic fun add$default (Lnet/mamoe/mirai/message/data/ForwardMessageBuilder;Lnet/mamoe/mirai/contact/UserOrBot;Lnet/mamoe/mirai/message/data/Message;IILjava/lang/Object;)Lnet/mamoe/mirai/message/data/ForwardMessageBuilder;
 	public fun addAll (ILjava/util/Collection;)Z
 	public fun addAll (Ljava/util/Collection;)Z
 	public final fun at (II)Lnet/mamoe/mirai/message/data/ForwardMessageBuilder$BuilderNode;
 	public final fun at (JI)Lnet/mamoe/mirai/message/data/ForwardMessageBuilder$BuilderNode;
 	public final fun at (Lnet/mamoe/mirai/contact/User;I)Lnet/mamoe/mirai/message/data/ForwardMessageBuilder$BuilderNode;
+	public final fun at (Lnet/mamoe/mirai/contact/UserOrBot;I)Lnet/mamoe/mirai/message/data/ForwardMessageBuilder$BuilderNode;
 	public final fun build ()Lnet/mamoe/mirai/message/data/ForwardMessage;
 	public fun clear ()V
 	public final fun contains (Ljava/lang/Object;)Z
@@ -4254,6 +4270,7 @@ public final class net/mamoe/mirai/message/data/ForwardMessageBuilder : java/uti
 	public final fun named (ILjava/lang/String;)Lnet/mamoe/mirai/message/data/ForwardMessageBuilder$BuilderNode;
 	public final fun named (JLjava/lang/String;)Lnet/mamoe/mirai/message/data/ForwardMessageBuilder$BuilderNode;
 	public final fun named (Lnet/mamoe/mirai/contact/User;Ljava/lang/String;)Lnet/mamoe/mirai/message/data/ForwardMessageBuilder$BuilderNode;
+	public final fun named (Lnet/mamoe/mirai/contact/UserOrBot;Ljava/lang/String;)Lnet/mamoe/mirai/message/data/ForwardMessageBuilder$BuilderNode;
 	public synthetic fun remove (I)Ljava/lang/Object;
 	public final fun remove (I)Lnet/mamoe/mirai/message/data/ForwardMessage$INode;
 	public final fun remove (Ljava/lang/Object;)Z
@@ -4273,6 +4290,8 @@ public final class net/mamoe/mirai/message/data/ForwardMessageBuilder : java/uti
 	public final fun says (Lnet/mamoe/mirai/contact/User;Ljava/lang/String;)Lnet/mamoe/mirai/message/data/ForwardMessageBuilder;
 	public final fun says (Lnet/mamoe/mirai/contact/User;Lkotlin/jvm/functions/Function1;)Lnet/mamoe/mirai/message/data/ForwardMessageBuilder;
 	public final fun says (Lnet/mamoe/mirai/contact/User;Lnet/mamoe/mirai/message/data/Message;)Lnet/mamoe/mirai/message/data/ForwardMessageBuilder;
+	public final fun says (Lnet/mamoe/mirai/contact/UserOrBot;Lkotlin/jvm/functions/Function1;)Lnet/mamoe/mirai/message/data/ForwardMessageBuilder;
+	public final fun says (Lnet/mamoe/mirai/contact/UserOrBot;Lnet/mamoe/mirai/message/data/Message;)Lnet/mamoe/mirai/message/data/ForwardMessageBuilder;
 	public synthetic fun set (ILjava/lang/Object;)Ljava/lang/Object;
 	public fun set (ILnet/mamoe/mirai/message/data/ForwardMessage$INode;)Lnet/mamoe/mirai/message/data/ForwardMessage$INode;
 	public final fun setCurrentTime (I)V
@@ -4297,6 +4316,7 @@ public final class net/mamoe/mirai/message/data/ForwardMessageBuilder$BuilderNod
 	public final fun says (Lkotlin/jvm/functions/Function1;)Lnet/mamoe/mirai/message/data/ForwardMessageBuilder;
 	public final fun says (Lnet/mamoe/mirai/message/data/Message;)Lnet/mamoe/mirai/message/data/ForwardMessageBuilder;
 	public final fun sender (Lnet/mamoe/mirai/contact/User;)Lnet/mamoe/mirai/message/data/ForwardMessageBuilder$BuilderNode;
+	public final fun sender (Lnet/mamoe/mirai/contact/UserOrBot;)Lnet/mamoe/mirai/message/data/ForwardMessageBuilder$BuilderNode;
 	public final fun senderId (I)Lnet/mamoe/mirai/message/data/ForwardMessageBuilder$BuilderNode;
 	public final fun senderId (J)Lnet/mamoe/mirai/message/data/ForwardMessageBuilder$BuilderNode;
 	public final fun senderName (Ljava/lang/String;)Lnet/mamoe/mirai/message/data/ForwardMessageBuilder$BuilderNode;
@@ -4708,8 +4728,8 @@ public final class net/mamoe/mirai/message/data/MessageUtils {
 	public static final synthetic fun FileMessage (Ljava/lang/String;ILjava/lang/String;J)Lnet/mamoe/mirai/message/data/FileMessage;
 	public static final synthetic fun Image (Ljava/lang/String;)Lnet/mamoe/mirai/message/data/Image;
 	public static final synthetic fun at (Lnet/mamoe/mirai/contact/Member;)Lnet/mamoe/mirai/message/data/At;
-	public static final synthetic fun buildMessageChain (ILkotlin/jvm/functions/Function1;)Lnet/mamoe/mirai/message/data/MessageChain;
+	public static final fun buildMessageChain (ILkotlin/jvm/functions/Function1;)Lnet/mamoe/mirai/message/data/MessageChain;
-	public static final synthetic fun buildMessageChain (Lkotlin/jvm/functions/Function1;)Lnet/mamoe/mirai/message/data/MessageChain;
+	public static final fun buildMessageChain (Lkotlin/jvm/functions/Function1;)Lnet/mamoe/mirai/message/data/MessageChain;
 	public static final synthetic fun buildMessageSource (Lnet/mamoe/mirai/Bot;Lnet/mamoe/mirai/message/data/MessageSourceKind;Lkotlin/jvm/functions/Function1;)Lnet/mamoe/mirai/message/data/OfflineMessageSource;
 	public static final synthetic fun buildMessageSource (Lnet/mamoe/mirai/IMirai;JLnet/mamoe/mirai/message/data/MessageSourceKind;Lkotlin/jvm/functions/Function1;)Lnet/mamoe/mirai/message/data/OfflineMessageSource;
 	public static final synthetic fun buildXmlMessage (ILkotlin/jvm/functions/Function1;)Lnet/mamoe/mirai/message/data/ServiceMessage;

mirai-core-api/src/commonMain/kotlin/message/data/ForwardMessage.kt

@@ -16,10 +16,7 @@ import io.ktor.util.*
 import kotlinx.serialization.SerialName
 import kotlinx.serialization.Serializable
 import net.mamoe.mirai.Bot
-import net.mamoe.mirai.contact.Contact
+import net.mamoe.mirai.contact.*
-import net.mamoe.mirai.contact.Group
-import net.mamoe.mirai.contact.User
-import net.mamoe.mirai.contact.nameCardOrNick
 import net.mamoe.mirai.event.events.MessageEvent
 import net.mamoe.mirai.message.data.ForwardMessage.DisplayStrategy
 import net.mamoe.mirai.utils.MiraiExperimentalApi
@@ -110,9 +107,7 @@ public data class ForwardMessage(
 ) : MessageContent, ConstrainSingle {
     override val key: MessageKey<ForwardMessage> get() = Key
 
-    override fun contentToString(): String {
+    override fun contentToString(): String = "[转发消息]"
-        return "[转发消息]"
-    }
 
     // use data-class generated toString()
 
@@ -152,11 +147,26 @@ public data class ForwardMessage(
     }
 
 
+    /**
+     * 消息节点
+     */
     @Serializable
     public data class Node(
+        /**
+         * 发送人 [User.id]
+         */
         override val senderId: Long,
+        /**
+         * 时间戳 秒
+         */
         override val time: Int,
+        /**
+         * 发送人昵称
+         */
         override val senderName: String,
+        /**
+         * 消息内容
+         */
         override val messageChain: MessageChain
     ) : INode {
         public constructor(
@@ -167,6 +177,9 @@ public data class ForwardMessage(
         ) : this(senderId, time, senderName, message.toMessageChain())
     }
 
+    /**
+     * 请构造 [Node]
+     */
     @MiraiExperimentalApi
     public interface INode {
         /**
@@ -271,7 +284,44 @@ public annotation class ForwardMessageDsl
  *
  * # 总览
  *
- * 使用 DSL 构造一个转发:
+ *
+ * 在 Java 使用一般方法添加消息构建转发:
+ * ```
+ * ForwardMessageBuilder builder = new ForwardMessageBuilder(group);
+ *
+ * builder.add(123456L, "群员A", new PlainText("消息"))
+ * builder.add(user, new PlainText("msg"));
+ * builder.add(user, (chain) -> {
+ *     chain.add(new At(user));
+ *     chain.add(new PlainText("Hello"))
+ * }); // 使用 Java 8 lambda 语法, MessageChainBuilder 快速构建消息链
+ * builder.add(event); // 可添加 MessageEvent
+ *
+ * builder.setDisplayStrategy(new ForwardMessage.DisplayStrategy() {
+ * }); // 可选, 修改显示策略
+ *
+ * ForwardMessage forward = builder.build();
+ * group.sendMessage(forward);
+ * ```
+ *
+ * 在 Kotlin 使用一般方法添加消息构建转发:
+ * ```
+ * val forward: ForwardMessage = buildForwardMessage {
+ *     add(123456L, "群员A", PlainText("消息"))
+ *     add(user, PlainText("msg"))
+ *     add(user) {
+ *         // this: MessageChainBuilder
+ *         add(At(user))
+ *         add(PlainText("msg"))
+ *     };
+ *     add(event) // 可添加 MessageEvent
+ * }
+ *
+ * group.sendMessage(forward);
+ * friend.sendMessage(forward);
+ * ```
+ *
+ * 在 Kotlin 也可以使用 DSL 构建一个转发:
  * ```
  * buildForwardMessage {
  *     123456789 named "鸽子 A" says "咕" // 意为 名为 "鸽子 A" 的用户 123456789 发送了一条内容为 "咕" 的消息
@@ -279,15 +329,18 @@ public annotation class ForwardMessageDsl
  *     987654321 named "鸽子 B" says "咕" // 未指定时间, 则自动顺序安排时间
  *     myFriend says "咕" // User.says
  *     bot says { // 构造消息链, 同 `buildMessageChain`
- *         +"发个图片试试"
+ *         add("发个图片试试")
- *         +Image("{90CCED1C-2D64-313B-5D66-46625CAB31D7}.jpg")
+ *         add(Image("{90CCED1C-2D64-313B-5D66-46625CAB31D7}.jpg"))
  *     }
  *     val member: Member = ...
  *     member says "我是幸运群员" // 使用 `User says` 则会同时设置发送人名称
  * }
  * ```
+ * DSL 语法在下文详细解释.
  *
- * # 语法
+ * 上述示例效果一样, 根据个人偏好选择.
+ *
+ * # Kotlin DSL 语法
  *
  * 下文中 `S` 代表消息发送人. 可接受: 发送人账号 id([Long] 或 [Int]) 或 [User]
  *
@@ -382,6 +435,14 @@ public class ForwardMessageBuilder private constructor(
         public infix fun sender(user: User): BuilderNode =
             apply { this.senderId(user.id); this.named(user.nameCardOrNick) }
 
+        /**
+         * 指定发送人 id 和名称.
+         * @since 2.6
+         */
+        @ForwardMessageDsl
+        public infix fun sender(user: UserOrBot): BuilderNode =
+            apply { this.senderId(user.id); this.named(user.nameCardOrNick) }
+
         /**
          * 指定发送人 id.
          */
@@ -501,6 +562,14 @@ public class ForwardMessageBuilder private constructor(
     @ForwardMessageDsl
     public infix fun User.says(message: Message): ForwardMessageBuilder = this.id named this.nameCardOrNick says message
 
+    /**
+     * 添加一条消息, 自动按顺序调整时间
+     * @since 2.6
+     */
+    @ForwardMessageDsl
+    public infix fun UserOrBot.says(message: Message): ForwardMessageBuilder =
+        this.id named this.nameCardOrNick says message
+
     /** 添加一条消息, 自动按顺序调整时间 */
     @ForwardMessageDsl
     public infix fun Bot.says(message: Message): ForwardMessageBuilder = this.id named this.smartName() says message
@@ -510,6 +579,14 @@ public class ForwardMessageBuilder private constructor(
     public inline infix fun User.says(chain: @ForwardMessageDsl MessageChainBuilder.() -> Unit): ForwardMessageBuilder =
         this says (MessageChainBuilder().apply(chain).asMessageChain())
 
+    /**
+     * 构造并添加一个 [MessageChain], 自动按顺序调整时间
+     * @since 2.6
+     */
+    @ForwardMessageDsl
+    public inline infix fun UserOrBot.says(chain: @ForwardMessageDsl MessageChainBuilder.() -> Unit): ForwardMessageBuilder =
+        this says (MessageChainBuilder().apply(chain).asMessageChain())
+
     /** 构造并添加一个 [MessageChain], 自动按顺序调整时间 */
     @ForwardMessageDsl
     public inline infix fun Bot.says(chain: @ForwardMessageDsl MessageChainBuilder.() -> Unit): ForwardMessageBuilder =
@@ -541,6 +618,14 @@ public class ForwardMessageBuilder private constructor(
     @ForwardMessageDsl
     public infix fun User.at(time: Int): BuilderNode = this.id named this.nameCardOrNick at time
 
+    /**
+     * 为一条消息指定时间和发送人名称.
+     * @time 时间戳, 单位为秒
+     * @since 2.6
+     */
+    @ForwardMessageDsl
+    public infix fun UserOrBot.at(time: Int): BuilderNode = this.id named this.nameCardOrNick at time
+
     // endregion
 
 
@@ -559,6 +644,13 @@ public class ForwardMessageBuilder private constructor(
     @ForwardMessageDsl
     public infix fun User.named(name: String): BuilderNode = this.id.named(name)
 
+    /**
+     * 为一条消息指定发送人名称.
+     * @since 2.6
+     */
+    @ForwardMessageDsl
+    public infix fun UserOrBot.named(name: String): BuilderNode = this.id.named(name)
+
     @Suppress("INVISIBLE_MEMBER", "INVISIBLE_REFERENCE")
     @kotlin.internal.LowPriorityInOverloadResolution // due to inference problem, `add(MessageEvent)` results in resolution ambiguity
     override fun add(element: ForwardMessage.INode): Boolean = container.add(element)
@@ -577,6 +669,70 @@ public class ForwardMessageBuilder private constructor(
 
     // endregion
 
+    // region common
+
+    /**
+     * 添加一个消息. 若不指定 [time], 将会使用 [currentTime] 自增 1 的时间.
+     * @since 2.6
+     */
+    @JvmOverloads
+    public fun add(sender: User, message: Message, time: Int = -1): ForwardMessageBuilder {
+        return if (time == -1) sender says message
+        else sender at time says message
+    }
+
+    /**
+     * 添加一个消息. 若不指定 [time], 将会使用 [currentTime] 自增 1 的时间.
+     * @since 2.6
+     */
+    @JvmOverloads
+    public fun add(sender: UserOrBot, message: Message, time: Int = -1): ForwardMessageBuilder {
+        return if (time == -1) sender says message
+        else sender at time says message
+    }
+
+    /**
+     * 添加一个消息. 若不指定 [time], 将会使用 [currentTime] 自增 1 的时间.
+     * @since 2.6
+     */
+    @JvmOverloads
+    public fun add(senderId: Long, senderName: String, message: Message, time: Int = -1): ForwardMessageBuilder {
+        return if (time == -1) senderId named senderName says message
+        else senderId named senderName at time says message
+    }
+
+    /**
+     * 构建并添加一个消息. 若不指定 [time], 将会使用 [currentTime] 自增 1 的时间.
+     * @since 2.6
+     * @see buildMessageChain
+     */
+    @JvmOverloads
+    public inline fun add(
+        senderId: Long,
+        senderName: String,
+        time: Int = -1,
+        builderAction: MessageChainBuilder.() -> Unit
+    ): ForwardMessageBuilder {
+        return add(senderId, senderName, time = time, message = buildMessageChain(builderAction))
+    }
+
+    /**
+     * 构建并添加一个消息. 若不指定 [time], 将会使用 [currentTime] 自增 1 的时间.
+     * @since 2.6
+     * @see buildMessageChain
+     */
+    @JvmOverloads
+    public inline fun add(
+        sender: UserOrBot,
+        time: Int = -1,
+        builderAction: MessageChainBuilder.() -> Unit
+    ): ForwardMessageBuilder {
+        return add(sender, time = time, message = buildMessageChain(builderAction))
+    }
+
+    // endregion
+
+
     /** 构造 [ForwardMessage] */
     public fun build(): ForwardMessage = RawForwardMessage(container.map {
         ForwardMessage.Node(