feat: rich text parameters

Aliorpse · Aliorpse · commit 3d667e76e8c9 · 2026-04-19T22:01:13.000+08:00
diff --git a/detekt.yml b/detekt.yml
@@ -5,3 +5,5 @@ style:
     active: false
   MagicNumber:
     active: false
+  MaxLineLength:
+    maxLineLength: 150
diff --git a/saltify-core/src/commonMain/kotlin/org/ntqqrev/saltify/dsl/CommandBuilder.kt b/saltify-core/src/commonMain/kotlin/org/ntqqrev/saltify/dsl/CommandBuilder.kt
@@ -1,5 +1,6 @@
 package org.ntqqrev.saltify.dsl
 
+import org.ntqqrev.milky.IncomingSegment
 import org.ntqqrev.saltify.annotation.SaltifyDsl
 import org.ntqqrev.saltify.model.command.CommandError
 import org.ntqqrev.saltify.model.command.CommandRequirement
@@ -73,15 +74,19 @@ public class SaltifyParameterBuilder(@PublishedApi internal val context: Command
     /**
      * 定义一个指令参数。请搭配 [CommandExecutionContext.value] 使用。
      *
-     * @param isGreedy 是否是贪婪参数，即是否包含后面的所有剩余文本。
-     * @param transform 将原始文本转化为目标类型的函数。
+     * @param isGreedy 是否是贪婪参数，即是否包含后面的所有剩余内容。
+     * @param transform 将原始内容转化为目标类型的函数。
      */
     public inline fun <reified T : Any> from(
         name: String,
         description: String,
         isGreedy: Boolean = false,
-        noinline transform: (String) -> T?
-    ): CommandParameter<T> = CommandParameter(transform, T::class, name, description, isGreedy).also {
-            context.parameters.add(it)
-        }
+        noinline transform: (IncomingSegment) -> T?
+    ): CommandParameter<T> = CommandParameter(
+        transform,
+        T::class,
+        name,
+        description,
+        isGreedy
+    ).also { context.parameters.add(it) }
 }
diff --git a/saltify-core/src/commonMain/kotlin/org/ntqqrev/saltify/extension/ApplicationExtension.kt b/saltify-core/src/commonMain/kotlin/org/ntqqrev/saltify/extension/ApplicationExtension.kt
@@ -54,7 +54,7 @@ public inline fun ApplicationContext.regex(
     }
 }
 
-private val spaceRegex = Regex("\\s+")
+private val spaceOrWordRegex = Regex("([^ ]+| +)")
 
 /**
  * 注册一个指令。
@@ -72,29 +72,42 @@ public fun ApplicationContext.command(
 
     client.commandRegistry.add(
         RegisteredCommand(
-            name = name,
-            prefix = prefix,
-            description = rootDsl.description,
-            parameters = rootDsl.parameters.toList(),
-            subCommands = rootDsl.subCommands.map { (subName, subCtx) ->
+            name,
+            prefix,
+            rootDsl.description,
+            rootDsl.parameters.toList(),
+            rootDsl.subCommands.map { (subName, subCtx) ->
                 subCtx.toSubCommand(subName)
             },
-            pluginName = pluginName
+            pluginName
         )
     )
 
     return on<Event.MessageReceive> {
-        val rawText = event.segments.filterIsInstance<IncomingSegment.Text>()
-            .joinToString("") { it.text }
-            .trim()
+        val segments = event.segments.flatMap { segment ->
+            if (segment is IncomingSegment.Text) {
+                spaceOrWordRegex.findAll(segment.text)
+                    .mapNotNull { match ->
+                        val str = match.value
+
+                        val processedStr = if (str.startsWith(" ")) str.drop(1) else str
+                        if (processedStr.isNotEmpty()) {
+                            IncomingSegment.Text(IncomingSegment.Text.Data(processedStr))
+                        } else {
+                            null
+                        }
+                    }.toList()
+            } else {
+                listOf(segment)
+            }
+        }
+        val leadingText = (segments[0] as? IncomingSegment.Text)?.text ?: return@on
 
-        val tokens = if (rawText.isEmpty()) emptyList() else rawText.split(spaceRegex)
-        if (tokens.isEmpty() || tokens[0] != "$prefix$name") return@on
+        if (!leadingText.startsWith("$prefix$name")) return@on
 
         CommandEngine.execute(
             rootDsl,
-            tokens.drop(1),
-            rawText.removePrefix("$prefix$name").removePrefix(" "),
+            segments.drop(1),
             client,
             event,
             name
diff --git a/saltify-core/src/commonMain/kotlin/org/ntqqrev/saltify/extension/CommandContextExtension.kt b/saltify-core/src/commonMain/kotlin/org/ntqqrev/saltify/extension/CommandContextExtension.kt
@@ -1,5 +1,8 @@
+@file:Suppress("TooManyFunctions")
+
 package org.ntqqrev.saltify.extension
 
+import org.ntqqrev.milky.IncomingSegment
 import org.ntqqrev.saltify.dsl.SaltifyParameterBuilder
 import org.ntqqrev.saltify.runtime.command.CommandParameter
 import org.ntqqrev.saltify.runtime.context.CommandExecutionContext
@@ -8,34 +11,64 @@ import org.ntqqrev.saltify.runtime.context.CommandExecutionContext
  * 定义一个指令参数。请搭配 [CommandExecutionContext.value] 使用。
  */
 public fun SaltifyParameterBuilder.string(name: String, desc: String = ""): CommandParameter<String> =
-    from(name, desc) { it }
+    from(name, desc) { (it as? IncomingSegment.Text)?.text }
 
 /**
  * 定义一个指令参数。请搭配 [CommandExecutionContext.value] 使用。
  */
 public fun SaltifyParameterBuilder.int(name: String, desc: String = ""): CommandParameter<Int> =
-    from(name, desc) { it.toIntOrNull() }
+    from(name, desc) { (it as? IncomingSegment.Text)?.text?.toIntOrNull() }
 
 /**
  * 定义一个指令参数。请搭配 [CommandExecutionContext.value] 使用。
  */
 public fun SaltifyParameterBuilder.long(name: String, desc: String = ""): CommandParameter<Long> =
-    from(name, desc) { it.toLongOrNull() }
+    from(name, desc) { (it as? IncomingSegment.Text)?.text?.toLongOrNull() }
 
 /**
  * 定义一个指令参数。请搭配 [CommandExecutionContext.value] 使用。
  */
 public fun SaltifyParameterBuilder.boolean(name: String, desc: String = ""): CommandParameter<Boolean> =
-    from(name, desc) { it.toBooleanStrictOrNull() }
+    from(name, desc) { (it as? IncomingSegment.Text)?.text?.toBooleanStrictOrNull() }
 
 /**
  * 定义一个指令参数。请搭配 [CommandExecutionContext.value] 使用。
  */
 public fun SaltifyParameterBuilder.double(name: String, desc: String = ""): CommandParameter<Double> =
-    from(name, desc) { it.toDoubleOrNull() }
+    from(name, desc) { (it as? IncomingSegment.Text)?.text?.toDoubleOrNull() }
 
 /**
  * 定义一个贪婪字符串参数。该参数会捕获剩余的**所有**文本内容。请搭配 [CommandExecutionContext.value] 使用。
  */
 public fun SaltifyParameterBuilder.greedyString(name: String, desc: String = ""): CommandParameter<String> =
-    from(name, desc, isGreedy = true) { it }
+    from(name, desc, isGreedy = true) { (it as? IncomingSegment.Text)?.text }
+
+/**
+ * 定义一个指令参数。请搭配 [CommandExecutionContext.value] 使用。
+ */
+public fun SaltifyParameterBuilder.image(name: String, desc: String = ""): CommandParameter<IncomingSegment.Image.Data> =
+    from(name, desc) { (it as? IncomingSegment.Image)?.data }
+
+/**
+ * 定义一个指令参数。请搭配 [CommandExecutionContext.value] 使用。
+ */
+public fun SaltifyParameterBuilder.mention(name: String, desc: String = ""): CommandParameter<IncomingSegment.Mention.Data> =
+    from(name, desc) { (it as? IncomingSegment.Mention)?.data }
+
+/**
+ * 定义一个指令参数。请搭配 [CommandExecutionContext.value] 使用。
+ */
+public fun SaltifyParameterBuilder.mentionAll(name: String, desc: String = ""): CommandParameter<Unit> =
+    from(name, desc) { if (it is IncomingSegment.MentionAll) Unit else null }
+
+/**
+ * 定义一个指令参数。请搭配 [CommandExecutionContext.value] 使用。
+ */
+public fun SaltifyParameterBuilder.face(name: String, desc: String = ""): CommandParameter<IncomingSegment.Face.Data> =
+    from(name, desc) { (it as? IncomingSegment.Face)?.data }
+
+/**
+ * 定义一个指令参数。请搭配 [CommandExecutionContext.value] 使用。
+ */
+public fun SaltifyParameterBuilder.reply(name: String, desc: String = ""): CommandParameter<IncomingSegment.Reply.Data> =
+    from(name, desc) { (it as? IncomingSegment.Reply)?.data }
diff --git a/saltify-core/src/commonMain/kotlin/org/ntqqrev/saltify/extension/IncomingMessageExtension.kt b/saltify-core/src/commonMain/kotlin/org/ntqqrev/saltify/extension/IncomingMessageExtension.kt
@@ -2,27 +2,28 @@ package org.ntqqrev.saltify.extension
 
 import org.ntqqrev.milky.IncomingSegment
 
+public val IncomingSegment.plainText: String
+    get() = when (this) {
+        is IncomingSegment.Text -> text
+        is IncomingSegment.Face -> "[表情]"
+        is IncomingSegment.Image -> "[图片]"
+        is IncomingSegment.Record -> "[语音]"
+        is IncomingSegment.Video -> "[视频]"
+        is IncomingSegment.File -> "[文件]"
+        is IncomingSegment.Mention -> "@$name"
+        is IncomingSegment.MentionAll -> "@全体成员"
+        is IncomingSegment.Reply -> "[回复]"
+        is IncomingSegment.Forward -> "[合并转发]"
+        is IncomingSegment.MarketFace -> "[商城表情]"
+        is IncomingSegment.LightApp -> "[小程序]"
+        is IncomingSegment.Xml -> "[XML消息]"
+    }
+
 /**
  * 将当前 `List<IncomingSegment>` 强制转换为文本形式，非文本形式的 segments 将以预定义文本占位。
  */
 public val List<IncomingSegment>.plainText: String
-    get() = joinToString("") { segment ->
-        when (segment) {
-            is IncomingSegment.Text -> segment.text
-            is IncomingSegment.Face -> "[表情]"
-            is IncomingSegment.Image -> "[图片]"
-            is IncomingSegment.Record -> "[语音]"
-            is IncomingSegment.Video -> "[视频]"
-            is IncomingSegment.File -> "[文件]"
-            is IncomingSegment.Mention -> "@${segment.name}"
-            is IncomingSegment.MentionAll -> "@全体成员"
-            is IncomingSegment.Reply -> "[回复]"
-            is IncomingSegment.Forward -> "[合并转发]"
-            is IncomingSegment.MarketFace -> "[商城表情]"
-            is IncomingSegment.LightApp -> "[小程序]"
-            is IncomingSegment.Xml -> "[XML消息]"
-        }
-    }
+    get() = joinToString("") { it.plainText }
 
 /**
  * 判断当前 `List<IncomingSegment>` 是否由指定的 `IncomingSegment` 组成。
diff --git a/saltify-core/src/commonMain/kotlin/org/ntqqrev/saltify/internal/engine/CommandEngine.kt b/saltify-core/src/commonMain/kotlin/org/ntqqrev/saltify/internal/engine/CommandEngine.kt
@@ -4,6 +4,7 @@ package org.ntqqrev.saltify.internal.engine
 
 import org.ntqqrev.milky.Event
 import org.ntqqrev.milky.IncomingMessage
+import org.ntqqrev.milky.IncomingSegment
 import org.ntqqrev.saltify.SaltifyApplication
 import org.ntqqrev.saltify.dsl.CommandBuilder
 import org.ntqqrev.saltify.model.command.CommandError
@@ -16,8 +17,7 @@ import kotlin.time.Clock
 internal object CommandEngine {
     suspend fun execute(
         dsl: CommandBuilder,
-        tokens: List<String>,
-        rawParameters: String,
+        segments: List<IncomingSegment>,
         client: SaltifyApplication,
         event: Event.MessageReceive,
         name: String
@@ -26,21 +26,20 @@ internal object CommandEngine {
         val execution = CommandExecutionContext(client, event, argumentMap, name)
 
         if (!checkRequirements(dsl, execution)) return
-        if (tokens.isNotEmpty()) {
-            val subName = tokens[0]
+        if (segments.isNotEmpty()) {
+            val subName = (segments[0] as? IncomingSegment.Text)?.text
             val subCommand = dsl.subCommands.find { it.first == subName }
 
             if (subCommand != null) return execute(
-                dsl = subCommand.second,
-                tokens = tokens.drop(1),
-                rawParameters = rawParameters.removePrefix(subCommand.first).removePrefix(" "),
-                client = client,
-                event = event,
-                name = "$name $subName"
+                subCommand.second,
+                segments.drop(1),
+                client,
+                event,
+                "$name $subName"
             )
         }
 
-        val error = parseParameters(dsl, tokens, rawParameters, argumentMap)
+        val error = parseParameters(dsl, segments, argumentMap)
         if (error != null) {
             dsl.failureBlock?.invoke(execution, error)
             return
@@ -60,25 +59,28 @@ internal object CommandEngine {
      */
     private fun parseParameters(
         dsl: CommandBuilder,
-        tokens: List<String>,
-        rawParameters: String,
+        segments: List<IncomingSegment>,
         argumentMap: MutableMap<CommandParameter<*>, ParameterParseResult<Any>>
     ): CommandError? {
-        val currentTokens = tokens.toMutableList()
-        var currentRaw = rawParameters
+        val currentTokens = segments.toMutableList()
 
         for (param in dsl.parameters) {
             val result: ParameterParseResult<Any> = when {
                 currentTokens.isEmpty() -> ParameterParseResult.MissingParam
                 param.isGreedy -> {
-                    val greedyValue = currentRaw
+                    val greedyValue = currentTokens.joinToString(" ") { segment ->
+                        if (segment is IncomingSegment.Text) {
+                            segment.text
+                        } else {
+                            segment.toString()
+                        }
+                    }
+
                     currentTokens.clear()
-                    currentRaw = ""
                     ParameterParseResult.Success(greedyValue)
                 }
                 else -> {
                     val rawValue = currentTokens.removeFirst()
-                    currentRaw = currentRaw.trimStart().removePrefix(rawValue).removePrefix(" ")
 
                     param.transform(rawValue)?.let { ParameterParseResult.Success(it) }
                         ?: ParameterParseResult.InvalidParam(rawValue)
diff --git a/saltify-core/src/commonMain/kotlin/org/ntqqrev/saltify/model/command/CommandError.kt b/saltify-core/src/commonMain/kotlin/org/ntqqrev/saltify/model/command/CommandError.kt
@@ -1,5 +1,7 @@
 package org.ntqqrev.saltify.model.command
 
+import org.ntqqrev.milky.IncomingSegment
+import org.ntqqrev.saltify.extension.plainText
 import org.ntqqrev.saltify.runtime.command.CommandParameter
 
 /**
@@ -13,13 +15,13 @@ public sealed class CommandError {
             get() = "缺少必要的参数: ${parameter.name}"
     }
 
-    public data class InvalidParam(val parameter: CommandParameter<*>, val token: String) : CommandError() {
+    public data class InvalidParam(val parameter: CommandParameter<*>, val segment: IncomingSegment) : CommandError() {
         override val message: String
-            get() = "参数 ${parameter.name} 无效: \"$token\""
+            get() = "参数 ${parameter.name} 无效: \"${segment.plainText}\""
     }
 
-    public data class TooManyArguments(val extraTokens: List<String>) : CommandError() {
+    public data class TooManyArguments(val extraSegments: List<IncomingSegment>) : CommandError() {
         override val message: String
-            get() = "提供参数过多: ${extraTokens.joinToString(" ")}"
+            get() = "提供参数过多: ${extraSegments.joinToString(" ") { it.plainText }}"
     }
 }
diff --git a/saltify-core/src/commonMain/kotlin/org/ntqqrev/saltify/model/command/ParameterParseResult.kt b/saltify-core/src/commonMain/kotlin/org/ntqqrev/saltify/model/command/ParameterParseResult.kt
@@ -1,7 +1,9 @@
 package org.ntqqrev.saltify.model.command
 
+import org.ntqqrev.milky.IncomingSegment
+
 internal sealed class ParameterParseResult<out T : Any> {
     data class Success<T : Any>(val value: T) : ParameterParseResult<T>()
-    data class InvalidParam(val rawValue: String) : ParameterParseResult<Unit>()
+    data class InvalidParam(val rawValue: IncomingSegment) : ParameterParseResult<Unit>()
     object MissingParam : ParameterParseResult<Unit>()
 }
diff --git a/saltify-core/src/commonMain/kotlin/org/ntqqrev/saltify/runtime/command/CommandParameter.kt b/saltify-core/src/commonMain/kotlin/org/ntqqrev/saltify/runtime/command/CommandParameter.kt
@@ -1,12 +1,13 @@
 package org.ntqqrev.saltify.runtime.command
 
+import org.ntqqrev.milky.IncomingSegment
 import kotlin.reflect.KClass
 
 /**
  * 指令参数
  */
 public class CommandParameter<T : Any>(
-    internal val transform: (String) -> T?,
+    internal val transform: (IncomingSegment) -> T?,
     public val type: KClass<T>,
     public val name: String,
     public val description: String = "",
diff --git a/saltify-core/src/jvmTest/kotlin/org/ntqqrev/saltify/PluginTest.kt b/saltify-core/src/jvmTest/kotlin/org/ntqqrev/saltify/PluginTest.kt
@@ -16,8 +16,7 @@ class PluginTest {
     fun test(): Unit = runBlocking {
         val client = SaltifyApplication {
             connection {
-                baseUrl = "http://aliorpse.tech:3010"
-                accessToken = "Ali081023"
+                baseUrl = "http://localhost:3010"
 
                 events {
                     type = EventConnectionType.WebSocket
@@ -159,5 +158,15 @@ class PluginTest {
                 respond("Order #${id.value} created\nnote：${note.value}")
             }
         }
+
+        // rich text param test
+        command("rich") {
+            val mention = parameter.mention("mention")
+            val image = parameter.image("image")
+
+            onExecute {
+                respond("You mentioned ${mention.value.name}, and sent an image: ${image.value.tempUrl}")
+            }
+        }
     }
 }

Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,7 @@`
`1`	`1`	`package org.ntqqrev.saltify.model.command`
`2`	`2`
	`3`	`+import org.ntqqrev.milky.IncomingSegment`
	`4`	`+import org.ntqqrev.saltify.extension.plainText`
`3`	`5`	`import org.ntqqrev.saltify.runtime.command.CommandParameter`
`4`	`6`
`5`	`7`	`/**`
`@@ -13,13 +15,13 @@ public sealed class CommandError {`
`13`	`15`	`get() = "缺少必要的参数: ${parameter.name}"`
`14`	`16`	`}`
`15`	`17`
`16`		`- public data class InvalidParam(val parameter: CommandParameter<*>, val token: String) : CommandError() {`
	`18`	`+ public data class InvalidParam(val parameter: CommandParameter<*>, val segment: IncomingSegment) : CommandError() {`
`17`	`19`	`override val message: String`
`18`		`- get() = "参数 ${parameter.name} 无效: \"$token\""`
	`20`	`+ get() = "参数 ${parameter.name} 无效: \"${segment.plainText}\""`
`19`	`21`	`}`
`20`	`22`
`21`		`- public data class TooManyArguments(val extraTokens: List<String>) : CommandError() {`
	`23`	`+ public data class TooManyArguments(val extraSegments: List<IncomingSegment>) : CommandError() {`
`22`	`24`	`override val message: String`
`23`		`- get() = "提供参数过多: ${extraTokens.joinToString(" ")}"`
	`25`	`+ get() = "提供参数过多: ${extraSegments.joinToString(" ") { it.plainText }}"`
`24`	`26`	`}`
`25`	`27`	`}`
Original file line number	Diff line number	Diff line change
`@@ -16,8 +16,7 @@ class PluginTest {`
`16`	`16`	`fun test(): Unit = runBlocking {`
`17`	`17`	`val client = SaltifyApplication {`
`18`	`18`	`connection {`
`19`		`- baseUrl = "http://aliorpse.tech:3010"`
`20`		`- accessToken = "Ali081023"`
	`19`	`+ baseUrl = "http://localhost:3010"`
`21`	`20`
`22`	`21`	`events {`
`23`	`22`	`type = EventConnectionType.WebSocket`
`@@ -159,5 +158,15 @@ class PluginTest {`
`159`	`158`	`respond("Order #${id.value} created\nnote：${note.value}")`
`160`	`159`	`}`
`161`	`160`	`}`
	`161`	`+`
	`162`	`+ // rich text param test`
	`163`	`+ command("rich") {`
	`164`	`+ val mention = parameter.mention("mention")`
	`165`	`+ val image = parameter.image("image")`
	`166`	`+`
	`167`	`+ onExecute {`
	`168`	`+ respond("You mentioned ${mention.value.name}, and sent an image: ${image.value.tempUrl}")`
	`169`	`+ }`
	`170`	`+ }`
`162`	`171`	`}`
`163`	`172`	`}`