feat(core): 实现 KookVoiceChannel, KookVoiceMember 并支持语音频道的相关操作

ForteScarlet · ForteScarlet · commit 38a3e4015c79 · 2025-08-22T14:55:58.000+08:00
- Added support for managing voice channel members (e.g., move and kickout functionalities).
- Implemented the KookVoiceMember interface and its core logic.
- Integrated voice channel handling in the guild structure.
- Updated related APIs for consistency.
diff --git a/simbot-component-kook-api/src/commonMain/kotlin/love/forte/simbot/kook/api/channel/ChannelKickoutApi.kt b/simbot-component-kook-api/src/commonMain/kotlin/love/forte/simbot/kook/api/channel/ChannelKickoutApi.kt
@@ -39,8 +39,6 @@ public class ChannelKickoutApi private constructor(
     channelId: String,
     userId: String
 ) : KookPostApi<Unit>() {
-    // TODO 在 KookVoiceChannel 中添加支持的上层API
-
     public companion object Factory {
         private val PATH = ApiPath.create("channel", "kickout")
 
diff --git a/simbot-component-kook-api/src/commonMain/kotlin/love/forte/simbot/kook/api/channel/ChannelMoveUserApi.kt b/simbot-component-kook-api/src/commonMain/kotlin/love/forte/simbot/kook/api/channel/ChannelMoveUserApi.kt
@@ -23,8 +23,7 @@ package love.forte.simbot.kook.api.channel
 import kotlinx.serialization.DeserializationStrategy
 import kotlinx.serialization.SerialName
 import kotlinx.serialization.Serializable
-import kotlinx.serialization.builtins.ListSerializer
-import kotlinx.serialization.json.JsonElement
+import kotlinx.serialization.builtins.serializer
 import love.forte.simbot.kook.api.KookPostApi
 import kotlin.jvm.JvmStatic
 
@@ -40,7 +39,7 @@ import kotlin.jvm.JvmStatic
 public class ChannelMoveUserApi private constructor(
     targetId: String,
     userIds: List<String>
-) : KookPostApi<List<JsonElement>>() {
+) : KookPostApi<Unit>() {
 
     public companion object Factory {
         private val PATH = ApiPath.create("channel", "move-user")
@@ -66,8 +65,8 @@ public class ChannelMoveUserApi private constructor(
             ChannelMoveUserApi(targetId, userIds.asList())
     }
 
-    override val resultDeserializationStrategy: DeserializationStrategy<List<JsonElement>>
-        get() = ListSerializer(JsonElement.serializer())
+    override val resultDeserializationStrategy: DeserializationStrategy<Unit>
+        get() = Unit.serializer()
 
     override val apiPath: ApiPath
         get() = PATH
diff --git a/simbot-component-kook-core/src/commonMain/kotlin/love/forte/simbot/component/kook/KookGuild.kt b/simbot-component-kook-core/src/commonMain/kotlin/love/forte/simbot/component/kook/KookGuild.kt
@@ -117,6 +117,26 @@ public interface KookGuild : Guild, CoroutineScope, KookRoleOperator {
      * 获取此频道服务器内的所有聊天频道集合。
      */
     override val chatChannels: Collectable<KookChatChannel>
+
+    /**
+     * 尝试根据指定ID获取匹配的 [KookVoiceChannel]。未找到时得到null。
+     *
+     * @since 4.2.0
+     * @see channel
+     */
+    @ST(
+        blockingBaseName = "getVoiceChannel",
+        blockingSuffix = "",
+        asyncBaseName = "getVoiceChannel",
+        reserveBaseName = "getVoiceChannel"
+    )
+    public suspend fun voiceChannel(id: ID): KookVoiceChannel?
+
+    /**
+     * 获取此频道服务器内的所有语音频道集合。
+     */
+    public val voiceChannels: Collectable<KookVoiceChannel>
+
     // categories
 
     /**
diff --git a/simbot-component-kook-core/src/commonMain/kotlin/love/forte/simbot/component/kook/KookVoiceChannel.kt b/simbot-component-kook-core/src/commonMain/kotlin/love/forte/simbot/component/kook/KookVoiceChannel.kt
@@ -20,12 +20,56 @@
 
 package love.forte.simbot.component.kook
 
+import love.forte.simbot.common.collectable.Collectable
+import love.forte.simbot.common.id.ID
+import love.forte.simbot.suspendrunner.ST
+
 /**
  * 一个 KOOK 中的语音子频道。
  *
+ * 语音子频道也是 [KookChatChannel] 的一种，因为它也可以发送消息。
+ *
  * @since 4.2.0
  * @author ForteScarlet
  */
 public interface KookVoiceChannel : KookChatChannel {
-    // TODO 相关整合
+    /**
+     * 获取当前语音频道中在线的用户列表。
+     */
+    public val members: Collectable<KookVoiceMember>
+
+    /**
+     * 语音频道之间移动用户
+     *
+     * 只能在语音频道之间移动，用户也必须在其他语音频道在线才能够移动到目标频道。
+     *
+     * @throws love.forte.simbot.kook.api.ApiResponseException 如果API的相应结果不是正确结果
+     * @throws love.forte.simbot.kook.api.ApiResultException 如果API的相应结果不是正确结果
+     */
+    @ST
+    public suspend fun moveMember(targetChannel: ID, vararg targetMembers: ID) {
+        moveMember(targetChannel, targetMembers.asList())
+    }
+
+    /**
+     * 语音频道之间移动用户
+     *
+     * 只能在语音频道之间移动，用户也必须在其他语音频道在线才能够移动到目标频道。
+     *
+     * @throws love.forte.simbot.kook.api.ApiResponseException 如果API的相应结果不是正确结果
+     * @throws love.forte.simbot.kook.api.ApiResultException 如果API的相应结果不是正确结果
+     */
+    @ST
+    public suspend fun moveMember(targetChannel: ID, targetMembers: Iterable<ID>)
+
+    /**
+     * 踢出语音频道中的用户。
+     *
+     * @see KookVoiceMember.kickout
+     *
+     * @throws love.forte.simbot.kook.api.ApiResponseException 如果API的相应结果不是正确结果
+     * @throws love.forte.simbot.kook.api.ApiResultException 如果API的相应结果不是正确结果
+     */
+    @ST
+    public suspend fun kickoutMember(targetMember: ID)
 }
diff --git a/simbot-component-kook-core/src/commonMain/kotlin/love/forte/simbot/component/kook/KookVoiceMember.kt b/simbot-component-kook-core/src/commonMain/kotlin/love/forte/simbot/component/kook/KookVoiceMember.kt
@@ -0,0 +1,48 @@
+/*
+ *     Copyright (c) 2025. ForteScarlet.
+ *
+ *     This file is part of simbot-component-kook.
+ *
+ *     simbot-component-kook 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.
+ *
+ *     simbot-component-kook 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
+ *     GNU Lesser General Public License for more details.
+ *
+ *     You should have received a copy of the GNU Lesser General Public License
+ *     along with simbot-component-kook,
+ *     If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package love.forte.simbot.component.kook
+
+import love.forte.simbot.common.id.ID
+
+/**
+ * Kook 语音频道内的成员。
+ * @since 4.2.0
+ * @author ForteScarlet
+ */
+public interface KookVoiceMember : KookMember {
+    /**
+     * 语音频道之间移动用户
+     *
+     * 只能在语音频道之间移动，用户也必须在其他语音频道在线才能够移动到目标频道。
+     *
+     * @throws love.forte.simbot.kook.api.ApiResponseException 如果API的相应结果不是正确结果
+     * @throws love.forte.simbot.kook.api.ApiResultException 如果API的相应结果不是正确结果
+     */
+    public suspend fun move(targetChannel: ID)
+
+    /**
+     * 将成员踢出语音频道。
+     *
+     * @throws love.forte.simbot.kook.api.ApiResponseException 如果API的相应结果不是正确结果
+     * @throws love.forte.simbot.kook.api.ApiResultException 如果API的相应结果不是正确结果
+     */
+    public suspend fun kickout()
+}
diff --git a/simbot-component-kook-core/src/commonMain/kotlin/love/forte/simbot/component/kook/bot/internal/KookBotImpl.kt b/simbot-component-kook-core/src/commonMain/kotlin/love/forte/simbot/component/kook/bot/internal/KookBotImpl.kt
@@ -36,6 +36,7 @@ import love.forte.simbot.common.id.literal
 import love.forte.simbot.component.kook.KookChannel
 import love.forte.simbot.component.kook.KookChatChannel
 import love.forte.simbot.component.kook.KookComponent
+import love.forte.simbot.component.kook.KookVoiceChannel
 import love.forte.simbot.component.kook.bot.KookBot
 import love.forte.simbot.component.kook.bot.KookBotConfiguration
 import love.forte.simbot.component.kook.bot.KookContactRelation
@@ -152,12 +153,15 @@ internal class KookBotImpl(
 
     private val internalCache = InternalCache()
 
-    internal fun internalGuild(guildId: String) = internalCache.guilds[guildId]
-    internal fun internalChatChannel(channelId: String) = internalCache.channels[channelId]
-    internal fun internalCategory(categoryId: String) = internalCache.categories[categoryId]
+    internal fun internalGuild(guildId: String): KookGuildImpl? = internalCache.guilds[guildId]
+    internal fun internalChatChannel(channelId: String): KookChatChannel? = internalCache.channels[channelId]
+    internal fun internalVoiceChannel(channelId: String): KookVoiceChannel? = internalChatChannel(channelId) as? KookVoiceChannel?
+    internal fun internalCategory(categoryId: String): KookCategoryChannelImpl? = internalCache.categories[categoryId]
     internal fun internalChatChannels(guildId: String): Sequence<KookChatChannel> =
         internalCache.channels.values.asSequence().filter { it.source.guildId == guildId }
 
+    internal fun internalVoiceChannels(guildId: String): Sequence<KookVoiceChannel> =
+        internalChatChannels(guildId).filterIsInstance<KookVoiceChannel>()
 
     internal fun internalMembers(guildId: String): Sequence<KookMemberImpl> {
         return internalCache.members.entries.asSequence().filter { it.key.guildId == guildId }.map { it.value }
diff --git a/simbot-component-kook-core/src/commonMain/kotlin/love/forte/simbot/component/kook/internal/KookGuildImpl.kt b/simbot-component-kook-core/src/commonMain/kotlin/love/forte/simbot/component/kook/internal/KookGuildImpl.kt
@@ -81,6 +81,12 @@ internal class KookGuildImpl(
     override suspend fun chatChannel(id: ID): KookChatChannel? =
         bot.internalChatChannel(id.literal)
 
+    override suspend fun voiceChannel(id: ID): KookVoiceChannel? =
+        bot.internalVoiceChannel(id.literal)
+
+    override val voiceChannels: Collectable<KookVoiceChannel>
+        get() = bot.internalVoiceChannels(source.id).asCollectable()
+
     @ExperimentalSimbotAPI
     override val categories: Collectable<KookCategoryChannel>
         get() = bot.internalCategories(source.id).asCollectable()
diff --git a/simbot-component-kook-core/src/commonMain/kotlin/love/forte/simbot/component/kook/internal/KookVoiceChannelImpl.kt b/simbot-component-kook-core/src/commonMain/kotlin/love/forte/simbot/component/kook/internal/KookVoiceChannelImpl.kt
@@ -20,9 +20,22 @@
 
 package love.forte.simbot.component.kook.internal
 
+import kotlinx.coroutines.flow.asFlow
+import kotlinx.coroutines.flow.emitAll
+import kotlinx.coroutines.flow.mapNotNull
+import love.forte.simbot.common.collectable.Collectable
+import love.forte.simbot.common.collectable.flowCollectable
+import love.forte.simbot.common.id.ID
+import love.forte.simbot.common.id.literal
 import love.forte.simbot.component.kook.KookVoiceChannel
+import love.forte.simbot.component.kook.KookVoiceMember
 import love.forte.simbot.component.kook.bot.internal.KookBotImpl
+import love.forte.simbot.component.kook.util.requestData
+import love.forte.simbot.kook.api.channel.ChannelKickoutApi
+import love.forte.simbot.kook.api.channel.ChannelMoveUserApi
+import love.forte.simbot.kook.api.channel.GetChannelUserListApi
 import love.forte.simbot.kook.objects.Channel
+import love.forte.simbot.logger.LoggerFactory
 import kotlin.coroutines.CoroutineContext
 
 /**
@@ -35,9 +48,43 @@ internal class KookVoiceChannelImpl(
     source: Channel,
 ) : AbstractKookChatCapableChannelImpl(bot, source),
     KookVoiceChannel {
+    companion object {
+        private val logger = LoggerFactory.getLogger("love.forte.simbot.component.kook.KookVoiceChannel")
+    }
+
     override val coroutineContext: CoroutineContext
         get() = bot.subContext
 
+    override suspend fun kickoutMember(targetMember: ID) {
+        val api = ChannelKickoutApi.create(source.id, targetMember.literal)
+        bot.requestData(api)
+    }
+
+    override val members: Collectable<KookVoiceMember>
+        get() = flowCollectable {
+            val api = GetChannelUserListApi.create(source.id)
+            val userList = bot.requestData(api)
+            val bot = this@KookVoiceChannelImpl.bot
+
+            emitAll(userList.asFlow().mapNotNull {
+                val delegateMember = bot.internalMember(guildId = source.guildId, userId = it.id)
+                logger.trace("Processing voice channel user-list(id={})'s delegate member: {}", it.id, delegateMember)
+                if (delegateMember == null) {
+                    logger.warn("Delegate member for voice channel's user(id={}) is null.", it)
+                    return@mapNotNull null
+                }
+                it.toVoiceMember(bot, source.id, delegateMember)
+            })
+        }
+
+    override suspend fun moveMember(
+        targetChannel: ID,
+        targetMembers: Iterable<ID>
+    ) {
+        val api = ChannelMoveUserApi.create(targetChannel.literal, targetMembers.map { it.literal })
+        bot.requestData(api)
+    }
+
     override fun toString(): String {
         return "KookVoiceChannel(id=${source.id}, name=${source.name}, guildId=${source.guildId})"
     }
diff --git a/simbot-component-kook-core/src/commonMain/kotlin/love/forte/simbot/component/kook/internal/KookVoiceMemberImpl.kt b/simbot-component-kook-core/src/commonMain/kotlin/love/forte/simbot/component/kook/internal/KookVoiceMemberImpl.kt
@@ -0,0 +1,55 @@
+/*
+ *     Copyright (c) 2025. ForteScarlet.
+ *
+ *     This file is part of simbot-component-kook.
+ *
+ *     simbot-component-kook 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.
+ *
+ *     simbot-component-kook 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
+ *     GNU Lesser General Public License for more details.
+ *
+ *     You should have received a copy of the GNU Lesser General Public License
+ *     along with simbot-component-kook,
+ *     If not, see <https://www.gnu.org/licenses/>.
+ */
+
+package love.forte.simbot.component.kook.internal
+
+import love.forte.simbot.common.id.ID
+import love.forte.simbot.common.id.literal
+import love.forte.simbot.component.kook.KookMember
+import love.forte.simbot.component.kook.KookVoiceMember
+import love.forte.simbot.component.kook.bot.internal.KookBotImpl
+import love.forte.simbot.component.kook.util.requestDataBy
+import love.forte.simbot.kook.api.channel.ChannelKickoutApi
+import love.forte.simbot.kook.api.channel.ChannelMoveUserApi
+import love.forte.simbot.kook.api.channel.VoiceChannelUser
+
+/**
+ *
+ * @author ForteScarlet
+ */
+internal class KookVoiceMemberImpl(
+    private val bot: KookBotImpl,
+    private val delegate: KookMember,
+    private val voiceChannelId: String,
+    private val voiceChannelUser: VoiceChannelUser
+) : KookVoiceMember, KookMember by delegate {
+
+    override suspend fun move(targetChannel: ID) {
+        ChannelMoveUserApi.create(targetChannel.literal, voiceChannelUser.id).requestDataBy(bot)
+    }
+
+    override suspend fun kickout() {
+        ChannelKickoutApi.create(voiceChannelId, voiceChannelUser.id).requestDataBy(bot)
+    }
+}
+
+
+internal fun VoiceChannelUser.toVoiceMember(bot: KookBotImpl, voiceChannelId: String, delegate: KookMember): KookVoiceMemberImpl =
+    KookVoiceMemberImpl(bot, delegate, voiceChannelId, this)
diff --git a/simbot-component-kook-core/src/commonMain/kotlin/love/forte/simbot/component/kook/internal/Utils.kt b/simbot-component-kook-core/src/commonMain/kotlin/love/forte/simbot/component/kook/internal/Utils.kt
@@ -23,7 +23,6 @@ package love.forte.simbot.component.kook.internal
 import love.forte.simbot.ability.DeleteOption
 import love.forte.simbot.ability.StandardDeleteOption
 import love.forte.simbot.component.kook.KookCategory
-import love.forte.simbot.component.kook.KookChannel
 import love.forte.simbot.component.kook.KookChatChannel
 import love.forte.simbot.component.kook.bot.KookBot
 import love.forte.simbot.component.kook.bot.internal.KookBotImpl
@@ -54,18 +53,6 @@ internal fun Channel.category(bot: KookBotImpl): KookCategory? {
         ?.let { bot.internalCategory(it) }?.category
 }
 
-/**
- * 将Channel对象转换为对应的KookChannel实现
- * @return 根据频道类型返回分类频道或聊天频道
- */
-internal fun Channel.toChannel(bot: KookBotImpl): KookChannel {
-    if (isCategory) {
-        return toCategoryChannel(bot, sourceCategory = toCategory(bot))
-    }
-
-    return toChatChannel(bot, typeValueOrNull)
-}
-
 
 /**
  * 根据频道类型将 Channel 转换为对应的聊天频道实现
