feat: built-in plugins

Aliorpse · Aliorpse · commit 94692a34fe95 · 2026-03-28T18:28:59.000+08:00
close #10
diff --git a/saltify-core/src/commonMain/kotlin/org/ntqqrev/saltify/builtin/plugin/CommandHelp.kt b/saltify-core/src/commonMain/kotlin/org/ntqqrev/saltify/builtin/plugin/CommandHelp.kt
@@ -0,0 +1,104 @@
+package org.ntqqrev.saltify.builtin.plugin
+
+import org.ntqqrev.saltify.core.forward
+import org.ntqqrev.saltify.core.node
+import org.ntqqrev.saltify.core.text
+import org.ntqqrev.saltify.dsl.SaltifyPlugin
+import org.ntqqrev.saltify.entity.RegisteredCommandInfo
+import org.ntqqrev.saltify.entity.RegisteredSubCommandInfo
+import org.ntqqrev.saltify.extension.respond
+
+/**
+ * Saltify 内置全局帮助指令插件。
+ */
+public val commandHelp: SaltifyPlugin<Unit> = SaltifyPlugin("command-help") {
+    command("help") {
+        description = "显示所有已注册指令的帮助信息"
+
+        onExecute {
+            val registry = client.commandRegistry
+            if (registry.isEmpty()) {
+                respond("当前没有已注册的指令。")
+                return@onExecute
+            }
+
+            val grouped = registry
+                .groupBy { it.pluginName }
+                .entries
+                .sortedWith(compareBy { it.key ?: "\uFFFF" })
+
+            respond {
+                forward {
+                    node(event.senderId, "Command Help") {
+                        text(buildString {
+                            appendLine("指令帮助")
+                            append("当前共注册了 ${registry.size} 条指令")
+                        })
+                    }
+
+                    for ((pluginName, commands) in grouped) {
+                        node(event.senderId, "Command Help") {
+                            text(buildCommandGroupText(pluginName, commands))
+                        }
+                    }
+                }
+            }
+        }
+    }
+}
+
+private fun buildCommandGroupText(
+    pluginName: String?,
+    commands: List<RegisteredCommandInfo>
+): String = buildString {
+    if (pluginName != null) {
+        appendLine("插件 $pluginName: ")
+    } else {
+        appendLine("其他指令: ")
+    }
+
+    for (cmd in commands) {
+        appendLine()
+        // 指令名 + 描述
+        val header = "${cmd.prefix}${cmd.name}"
+        if (cmd.description.isNotEmpty()) {
+            appendLine("$header - ${cmd.description}")
+        } else {
+            appendLine(header)
+        }
+        // 参数
+        if (cmd.parameters.isNotEmpty()) {
+            val params = cmd.parameters.joinToString(" ") { p ->
+                "<${p.name}: ${p.type.simpleName ?: p.type}>"
+            }
+            appendLine("  参数: $params")
+        }
+        // 子指令
+        for (sub in cmd.subCommands) {
+            appendSubCommand(sub, "${cmd.prefix}${cmd.name}", depth = 1)
+        }
+    }
+}.trimEnd()
+
+private fun StringBuilder.appendSubCommand(
+    sub: RegisteredSubCommandInfo,
+    parentPath: String,
+    depth: Int
+) {
+    val indent = "  ".repeat(depth)
+    val path = "$parentPath ${sub.name}"
+    if (sub.description.isNotEmpty()) {
+        appendLine("$indent$path - ${sub.description}")
+    } else {
+        appendLine("$indent$path")
+    }
+    if (sub.parameters.isNotEmpty()) {
+        val params = sub.parameters.joinToString(" ") { p ->
+            "<${p.name}: ${p.type.simpleName ?: p.type}>"
+        }
+        appendLine("$indent  参数: $params")
+    }
+    for (nested in sub.subCommands) {
+        appendSubCommand(nested, path, depth + 1)
+    }
+}
diff --git a/saltify-core/src/commonMain/kotlin/org/ntqqrev/saltify/builtin/plugin/DefaultLogging.kt b/saltify-core/src/commonMain/kotlin/org/ntqqrev/saltify/builtin/plugin/DefaultLogging.kt
@@ -0,0 +1,67 @@
+package org.ntqqrev.saltify.builtin.plugin
+
+import kotlinx.coroutines.CancellationException
+import kotlinx.coroutines.launch
+import org.ntqqrev.milky.Event
+import org.ntqqrev.milky.IncomingMessage
+import org.ntqqrev.saltify.dsl.SaltifyPlugin
+import org.ntqqrev.saltify.extension.plainText
+import org.ntqqrev.saltify.model.EventConnectionState
+import org.ntqqrev.saltify.model.SaltifyComponentType
+import org.ntqqrev.saltify.util.coroutine.saltifyComponent
+
+/**
+ * Saltify 内置日志插件。
+ *
+ * 负责输出事件服务连接状态变更、未捕获异常以及收到的消息日志。
+ */
+public val defaultLogging: SaltifyPlugin<Unit> = SaltifyPlugin("default-logging") {
+    // 事件服务连接状态日志
+    launch {
+        client.eventConnectionStateFlow.collect { state ->
+            when (state) {
+                is EventConnectionState.Connected ->
+                    client.logger.info("事件服务已连接, 使用协议：${state.type.name}")
+                is EventConnectionState.Disconnected -> {
+                    val error = state.throwable
+                    if (error != null && error !is CancellationException)
+                        client.logger.error("事件服务已断开", error)
+                }
+                is EventConnectionState.Connecting ->
+                    client.logger.info("事件服务正在连接...")
+                is EventConnectionState.Reconnecting ->
+                    client.logger.warn(
+                        "事件服务断开, 将在 ${state.delay}ms 后尝试重连... (重试次数: ${state.attempt})",
+                        state.throwable
+                    )
+            }
+        }
+    }
+
+    // 未捕获异常日志
+    launch {
+        client.exceptionFlow.collect { (context, throwable) ->
+            val component = context.saltifyComponent!!
+            when (component.type) {
+                SaltifyComponentType.Application ->
+                    client.logger.error("Saltify 根组件异常", throwable)
+                SaltifyComponentType.Plugin ->
+                    client.logger.error("Saltify 插件 ${component.name} 异常", throwable)
+                SaltifyComponentType.Extension ->
+                    client.logger.error("Saltify 基础扩展组件异常", throwable)
+            }
+        }
+    }
+
+    // 收到消息日志
+    on<Event.MessageReceive> { event ->
+        when (val data = event.data) {
+            is IncomingMessage.Group ->
+                logger.debug(
+                    "${data.groupMember.userId}(${data.group.groupId}): ${event.segments.plainText}"
+                )
+            else ->
+                logger.debug("${event.peerId}: ${event.segments.plainText}")
+        }
+    }
+}
diff --git a/saltify-core/src/commonMain/kotlin/org/ntqqrev/saltify/core/SaltifyApplication.kt b/saltify-core/src/commonMain/kotlin/org/ntqqrev/saltify/core/SaltifyApplication.kt
@@ -19,14 +19,13 @@ import org.ntqqrev.saltify.annotation.WithApiExtension
 import org.ntqqrev.saltify.dsl.SaltifyPluginContext
 import org.ntqqrev.saltify.dsl.config.SaltifyApplicationConfig
 import org.ntqqrev.saltify.entity.InstalledPlugin
+import org.ntqqrev.saltify.entity.RegisteredCommandInfo
 import org.ntqqrev.saltify.exception.ApiCallException
-import org.ntqqrev.saltify.extension.plainText
 import org.ntqqrev.saltify.model.EventConnectionState
 import org.ntqqrev.saltify.model.EventConnectionType
 import org.ntqqrev.saltify.model.SaltifyComponentType
 import org.ntqqrev.saltify.util.coroutine.SaltifyComponent
 import org.ntqqrev.saltify.util.coroutine.SaltifyExceptionHandlerProvider
-import org.ntqqrev.saltify.util.coroutine.saltifyComponent
 import kotlin.coroutines.CoroutineContext
 import kotlin.time.Clock
 
@@ -101,6 +100,8 @@ public sealed class SaltifyApplication(internal val config: SaltifyApplicationCo
 
     private val loadedPlugins = mutableListOf<SaltifyPluginContext>()
 
+    internal val commandRegistry: MutableList<RegisteredCommandInfo> = mutableListOf()
+
     @PublishedApi
     internal val httpClient: HttpClient = HttpClient {
         install(ContentNegotiation) {
@@ -125,14 +126,10 @@ public sealed class SaltifyApplication(internal val config: SaltifyApplicationCo
         }
     }
 
-    private lateinit var loggingListenerJob: Job
-
     public suspend fun start(): SaltifyApplication {
         logger.info("Saltify 正在启动...")
         val startInstant = Clock.System.now()
 
-        loggingListenerJob = startLoggingListeners()
-
         // 插件初始化
         config.installedPlugins.map { installed ->
             @Suppress("UNCHECKED_CAST")
@@ -198,64 +195,9 @@ public sealed class SaltifyApplication(internal val config: SaltifyApplicationCo
         loadedPlugins.forEach {
             it.onStopHooks.forEach { block -> block() }
         }
-        loggingListenerJob.cancel()
         httpClient.close()
         applicationScope.cancel()
 
         logger.info("Saltify 已关闭")
     }
 }
-
-private fun SaltifyApplication.startLoggingListeners() = applicationScope.launch {
-    // 事件服务状态日志
-    applicationScope.launch {
-        eventConnectionStateFlow.collect {
-            when (it) {
-                is EventConnectionState.Connected ->
-                    logger.info("事件服务已连接, 使用协议：${it.type.name}")
-                is EventConnectionState.Disconnected -> {
-                    val error = it.throwable
-                    if (error != null && error !is CancellationException) logger.error("事件服务已断开", error)
-                }
-                is EventConnectionState.Connecting ->
-                    logger.info("事件服务正在连接...")
-                is EventConnectionState.Reconnecting ->
-                    logger.warn("事件服务断开, 将在 ${it.delay}ms 后尝试重连... (重试次数: ${it.attempt})", it.throwable)
-            }
-        }
-    }
-
-    // 错误日志
-    applicationScope.launch {
-        exceptionFlow.collect {
-            val component = it.first.saltifyComponent!!
-            when (component.type) {
-                SaltifyComponentType.Application ->
-                    logger.error("Saltify 根组件异常", it.second)
-                SaltifyComponentType.Plugin ->
-                    logger.error("Saltify 插件 ${component.name} 异常", it.second)
-                SaltifyComponentType.Extension ->
-                    logger.error("Saltify 基础扩展组件异常", it.second)
-            }
-        }
-    }
-
-    // 事件日志
-    applicationScope.launch {
-        eventFlow.collect {
-            when (it) {
-                is Event.MessageReceive -> {
-                    when (val data = it.data) {
-                        is IncomingMessage.Group ->
-                            logger.debug(
-                                "${data.groupMember.userId}(${data.group.groupId}): ${it.segments.plainText}"
-                            )
-                        else ->
-                            logger.debug("${it.peerId}: ${it.segments.plainText}")
-                    }
-                }
-                else -> {}
-            }
-        }
-    }
-}
diff --git a/saltify-core/src/commonMain/kotlin/org/ntqqrev/saltify/dsl/SaltifyCommandContext.kt b/saltify-core/src/commonMain/kotlin/org/ntqqrev/saltify/dsl/SaltifyCommandContext.kt
@@ -27,6 +27,11 @@ public class SaltifyCommandContext internal constructor() {
     internal val subCommands = mutableListOf<Pair<String, SaltifyCommandContext>>()
     internal val parameters = mutableListOf<SaltifyCommandParamDef<*>>()
     internal var executionBlock: (suspend SaltifyCommandExecutionContext.() -> Unit)? = null
+
+    /**
+     * 指令的描述信息。
+     */
+    public var description: String = ""
     internal var groupExecutionBlock: (suspend SaltifyCommandExecutionContext.() -> Unit)? = null
     internal var privateExecutionBlock: (suspend SaltifyCommandExecutionContext.() -> Unit)? = null
     internal var failureBlock: (suspend SaltifyCommandExecutionContext.(CommandError) -> Unit)? = null
diff --git a/saltify-core/src/commonMain/kotlin/org/ntqqrev/saltify/entity/RegisteredCommandInfo.kt b/saltify-core/src/commonMain/kotlin/org/ntqqrev/saltify/entity/RegisteredCommandInfo.kt
@@ -0,0 +1,25 @@
+package org.ntqqrev.saltify.entity
+
+import org.ntqqrev.saltify.dsl.SaltifyCommandParamDef
+
+/**
+ * 子指令的注册信息
+ */
+public data class RegisteredSubCommandInfo(
+    val name: String,
+    val description: String,
+    val parameters: List<SaltifyCommandParamDef<*>>,
+    val subCommands: List<RegisteredSubCommandInfo> = emptyList()
+)
+
+/**
+ * 已注册指令的信息
+ */
+public data class RegisteredCommandInfo(
+    val name: String,
+    val prefix: String,
+    val description: String,
+    val parameters: List<SaltifyCommandParamDef<*>>,
+    val subCommands: List<RegisteredSubCommandInfo>,
+    val pluginName: String?
+)
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
@@ -12,10 +12,14 @@ import org.ntqqrev.saltify.dsl.ParameterParseResult
 import org.ntqqrev.saltify.dsl.SaltifyCommandContext
 import org.ntqqrev.saltify.dsl.SaltifyCommandExecutionContext
 import org.ntqqrev.saltify.dsl.SaltifyCommandParamDef
+import org.ntqqrev.saltify.entity.RegisteredCommandInfo
+import org.ntqqrev.saltify.entity.RegisteredSubCommandInfo
 import org.ntqqrev.saltify.entity.SaltifyBotConfig
 import org.ntqqrev.saltify.entity.SaltifyCommandRequirementContext
 import org.ntqqrev.saltify.model.CommandError
+import org.ntqqrev.saltify.model.SaltifyComponentType
 import org.ntqqrev.saltify.util.coroutine.runCatchingToExceptionFlow
+import org.ntqqrev.saltify.util.coroutine.saltifyComponent
 import kotlin.reflect.KClass
 import kotlin.time.Clock
 
@@ -67,6 +71,21 @@ public fun SaltifyApplication.command(
 ): Job {
     val rootDsl = SaltifyCommandContext().apply(builder)
 
+    val component = scope.coroutineContext.saltifyComponent
+    val pluginName = if (component?.type == SaltifyComponentType.Plugin) component.name else null
+    commandRegistry.add(
+        RegisteredCommandInfo(
+            name = name,
+            prefix = prefix,
+            description = rootDsl.description,
+            parameters = rootDsl.parameters.toList(),
+            subCommands = rootDsl.subCommands.map { (subName, subCtx) ->
+                subCtx.toSubCommandInfo(subName)
+            },
+            pluginName = pluginName
+        )
+    )
+
     return on<Event.MessageReceive>(scope) { event ->
         val rawText = event.segments.filterIsInstance<IncomingSegment.Text>()
             .joinToString("") { it.text }
@@ -144,6 +163,14 @@ private suspend fun executeCommand(
     execution.logger.info("seq=${event.messageSeq} 处理完成, 用时 ${Clock.System.now() - startInstant}")
 }
 
+private fun SaltifyCommandContext.toSubCommandInfo(name: String): RegisteredSubCommandInfo =
+    RegisteredSubCommandInfo(
+        name = name,
+        description = description,
+        parameters = parameters.toList(),
+        subCommands = subCommands.map { (subName, subCtx) -> subCtx.toSubCommandInfo(subName) }
+    )
+
 @Suppress("UNCHECKED_CAST")
 private fun <T : Any> convertValue(value: String, type: KClass<T>): T? {
     return when (type) {
diff --git a/saltify-core/src/jvmTest/kotlin/org/ntqqrev/saltify/PluginTest.kt b/saltify-core/src/jvmTest/kotlin/org/ntqqrev/saltify/PluginTest.kt
@@ -3,6 +3,8 @@ package org.ntqqrev.saltify
 import kotlinx.coroutines.delay
 import kotlinx.coroutines.runBlocking
 import org.ntqqrev.milky.IncomingMessage
+import org.ntqqrev.saltify.builtin.plugin.commandHelp
+import org.ntqqrev.saltify.builtin.plugin.defaultLogging
 import org.ntqqrev.saltify.core.SaltifyApplication
 import org.ntqqrev.saltify.core.getLoginInfo
 import org.ntqqrev.saltify.dsl.SaltifyPlugin
@@ -32,6 +34,9 @@ class PluginTest {
             install(testPlugin) {
                 response = "Hello!!"
             }
+
+            install(commandHelp)
+            install(defaultLogging)
         }.start()
 
         client.connectEvent()
diff --git a/saltify-docs/content/docs-core/_meta.ts b/saltify-docs/content/docs-core/_meta.ts
@@ -6,4 +6,5 @@ export default {
   command: '指令开发',
   permission: '权限管理',
   logging: '日志实现',
+  'builtin-plugins': '内置插件',
 } satisfies MetaRecord;
diff --git a/saltify-docs/content/docs-core/application.md b/saltify-docs/content/docs-core/application.md
diff --git a/saltify-docs/content/docs-core/builtin-plugins.md b/saltify-docs/content/docs-core/builtin-plugins.md
