feat: implements support for KOOK role mentions (#7626)

* feat: 实现kook适配器响应`@`角色(role)的能力

* refactor: kook适配器处理role时,`At`组件保留`@`角色的名称而不是id

* fix: kook适配器处理role时,role_id的判断问题

* refactor: 移除kook适配器中的一个# type: ignore

* fix: 修复kook适配器 role mention转换成`At`组件时保留不是角色名称的bug;

* unittest: 给kook适配器添加带有role mention的事件消息的单测,并添加消息组件转换判断单测

* unittest: 部分重构test_kook_event.py和test_kook_types.py 单测

* unittest: 添加kook适配器的 `user/me` `user/view` 接口响应数据验证单测

* fix: 修复kook适配器接收频道权限更新消息会报错的bug

* fix:  不额外处理kook的道具消息

* fix: 使用async with self._http_client.get

* refactor: kook适配器转换文本内容为消息组件时,只strip mention之间的空格

* fix: 修复 role_mention_counter 计数不正确的问题

* fix: 修复kook适配器发送卡片失败的问题;区分两类kook 数据类的to_dict to_json行为

* chore: 添加注释

* refactor: 重构kook适配器的角色缓存功能,使其无锁,性能更好且具备良好的重试机制

* refactor: kook适配器的channel_id 改为 guild_id

* feat: kook适配器响应频道角色更新事件时不再清空整个角色id缓存,而是只清理特定频道的角色id缓存

* unittest: 添加kook适配器的update_role事件的数据类验证单测

* refactor: 补上了一些打印的日志消息文本

refactor: 补上了一些打印的日志消息文本

refactor: 补上了一些打印的日志消息文本

* refactor: 修复kook适配器潜在可能的类型问题

* refactor: `clean_roles_cache`重命名为`clear_guild_roles_cache`

Author: shuiping233

astrbot/core/platform/sources/kook/kook_adapter.py

@@ -13,12 +13,13 @@
     PlatformMetadata,
     register_platform_adapter,
 )
-from astrbot.core.message.components import File, Record, Video
+from astrbot.core.message.components import BaseMessageComponent, File, Record, Video
 from astrbot.core.platform.astr_message_event import MessageSesion
 
 from .kook_client import KookClient
 from .kook_config import KookConfig
 from .kook_event import KookEvent
+from .kook_roles_record import KookRolesRecord
 from .kook_types import (
     ContainerModule,
     FileModule,
@@ -27,14 +28,18 @@
     KmarkdownElement,
     KookCardMessageContainer,
     KookChannelType,
+    KookMarkdownMentionRolePart,
+    KookMentionTagName,
     KookMessageEventData,
     KookMessageType,
     KookModuleType,
+    KookRoleExtraType,
     PlainTextElement,
     SectionModule,
 )
 
-KOOK_AT_SELECTOR_REGEX = re.compile(r"\(met\)([^()]+)\(met\)")
+KOOK_AT_SELECTOR_REGEX = re.compile(r"\((met|rol)\)([^()]+)\(\1\)")
+AT_MENTION_PREFIX_REGEX = re.compile(r"^@[^\s]+(\s*-\s*[^\s]+)?\s*")
 
 
 @register_platform_adapter(
@@ -53,6 +58,7 @@ def __init__(
         self._reconnect_task = None
         self.running = False
         self._main_task = None
+        self._roles_cache = KookRolesRecord("", self.client.http_client)
 
     async def send_by_session(
         self, session: MessageSesion, message_chain: MessageChain
@@ -84,16 +90,26 @@ async def _on_received(self, event: KookMessageEventData):
         event_type = event.type
         if event_type in (KookMessageType.KMARKDOWN, KookMessageType.CARD):
             if self._should_ignore_event_by_bot_nickname(event.author_id):
-                logger.debug("[KOOK] 收到来自机器人自身的消息, 忽略此消息")
+                logger.debug("[KOOK] 判断此消息为来自机器人自身的消息, 忽略此消息")
                 return
             try:
                 abm = await self.convert_message(event)
                 await self.handle_msg(abm)
             except Exception as e:
                 logger.error(f"[KOOK] 消息处理异常: {e}")
         elif event_type == KookMessageType.SYSTEM:
-            logger.debug(f'[KOOK] 消息为系统通知, 通知类型为: "{event.extra.type}"')
-            logger.debug(f"[KOOK] 原始消息数据: {event.to_json()}")
+            match event.extra.type:
+                case KookRoleExtraType():
+                    # 此时 target_id 就是频道id(guild_id)
+                    guild_id = event.target_id
+                    logger.info(
+                        f'[KOOK] 收到频道"{guild_id}"的角色更新通知, 类型为"{event.extra.type.value}", 刷新角色id缓存'
+                    )
+                    self._roles_cache.clear_guild_roles_cache(int(guild_id))
+                case _:
+                    logger.debug(
+                        f'[KOOK] 判断此消息为"{event.extra.type}"类型的系统通知, 因未实现此消息的处理流程而忽略此消息, 原始消息数据: {event.to_json()}'
+                    )
 
     async def run(self):
         """主运行循环"""
@@ -124,6 +140,8 @@ async def _main_loop(self):
                 logger.info("[KOOK] 尝试连接KOOK服务器...")
 
                 # 尝试连接
+                await self.client.get_bot_info()
+                self._roles_cache.set_bot_id(self.client.bot_id)
                 success = await self.client.connect()
 
                 if success:
@@ -191,47 +209,86 @@ async def _cleanup(self):
 
         logger.info("[KOOK] 资源清理完成")
 
-    def _parse_kmarkdown_text_message(
-        self, data: KookMessageEventData, self_id: str
-    ) -> tuple[list, str]:
-        kmarkdown = data.extra.kmarkdown
-        content = data.content or ""
-        if kmarkdown is None:
-            logger.error(
-                f'[KOOK] 无法转换"{KookMessageType.KMARKDOWN.name}"消息, 消息中找不到kmarkdown字段'
-            )
-            logger.error(f"[KOOK] 原始消息内容: {data.to_json()}")
-            return [], ""
+    async def _convert_text_message_to_component(
+        self,
+        content: str,
+        raw_content: str,
+        mention_role_part: list[KookMarkdownMentionRolePart] | None = None,
+        guild_id: str | None = None,
+        mention_name_map: dict[str, str] | None = None,
+    ) -> tuple[list[BaseMessageComponent], str]:
+        # kook平台有一个角色(role)的概念,他表示拥有某一类权限的许多用户
+        # 且角色本身也有一个自己的id,与正常用户id不同
+        # 而在频道中是可以`@`角色的,而想要知道bot是否属于某个角色
+        # 需要通过 `/user/view` 接口获取当前bot账号的某个频道下所属角色的id
+        # 为了解决 https://github.com/AstrBotDevs/AstrBot/issues/7539
+        # 在确定机器人需要响应某个`(rol)xxx(rol)`时,需要将角色id替换装当前的bot id
+        # 包装成`At`机器人自己,而`At`的name就保留角色名称
+        # 如果没有查询到角色id或者bot不属于某类角色, 则不处理此`(rol)xxx(rol)`
+        # 暂时想不到能在不修改原有消息内容的情况下处理这个角色mention的方案
 
-        raw_content = kmarkdown.raw_content or content
-        if not isinstance(content, str):
-            content = str(content)
-        if not isinstance(raw_content, str):
-            raw_content = str(raw_content)
+        message_str = raw_content
+        bot_id = self.client.bot_id
+        bot_nickname = self.client.bot_nickname
+        bot_username = self.client.bot_username
+        components: list[BaseMessageComponent] = []
+        if mention_name_map is None:
+            mention_name_map = {}
+        cursor = 0
 
-        # TODO 后面的pydantic类型替换,以后再来探索吧 :(
-        mention_name_map: dict[str, str] = {}
-        mention_part = kmarkdown.mention_part
-        if isinstance(mention_part, list):
-            for item in mention_part:
-                if not isinstance(item, dict):
-                    continue
-                mention_id = item.get("id")
-                if mention_id is None:
-                    continue
-                mention_name_map[str(mention_id)] = str(item.get("username", ""))
+        role_mention_counter = -1
 
-        components = []
-        cursor = 0
         for match in KOOK_AT_SELECTOR_REGEX.finditer(content):
             if match.start() > cursor:
-                plain_text = content[cursor : match.start()]
+                plain_text = content[cursor : match.start()].strip(" ")
                 if plain_text:
                     components.append(Plain(text=plain_text))
 
-            mention_target = match.group(1).strip()
-            if mention_target == "all":
+            tag_name = match.group(1)
+            mention_target = match.group(2).strip()
+            if tag_name == KookMentionTagName.MENTION and mention_target == "all":
                 components.append(AtAll())
+            elif tag_name == KookMentionTagName.ROLE:
+                role_mention_counter += 1
+                role_id = 0
+                role_mention_name = mention_target
+                if mention_role_part is not None:
+                    if len(mention_role_part) > role_mention_counter:
+                        role_mention_name = mention_role_part[role_mention_counter].name
+                        role_id = mention_role_part[role_mention_counter].role_id
+                        if (
+                            bot_nickname == role_mention_name
+                            or bot_username == role_mention_name
+                        ):
+                            components.append(
+                                At(
+                                    qq=bot_id,
+                                    name=role_mention_name,  # 保留角色名称
+                                )
+                            )
+                            continue
+                if not mention_target.isdigit() and role_id == 0:
+                    continue
+
+                role_id = role_id or int(mention_target)
+                if not guild_id:
+                    continue
+
+                if not guild_id.isdigit():
+                    continue
+
+                if not await self._roles_cache.has_role_in_channel(
+                    role_id, int(guild_id)
+                ):
+                    continue
+
+                components.append(
+                    At(
+                        qq=bot_id,
+                        name=role_mention_name,  # 保留角色名称
+                    )
+                )
+
             elif mention_target:
                 components.append(
                     At(
@@ -242,21 +299,20 @@ def _parse_kmarkdown_text_message(
             cursor = match.end()
 
         if cursor < len(content):
-            tail_text = content[cursor:]
+            tail_text = content[cursor:].strip(" ")
             if tail_text:
                 components.append(Plain(text=tail_text))
 
-        message_str = raw_content
+        message_str = raw_content.strip()
         if components:
             for comp in components:
                 if isinstance(comp, Plain):
                     if not comp.text.strip():
                         continue
                     break
                 if isinstance(comp, At):
-                    if str(comp.qq) == str(self_id):
-                        message_str = re.sub(
-                            r"^@[^\s]+(\s*-\s*[^\s]+)?\s*",
+                    if str(comp.qq) == str(self.client.bot_id):
+                        message_str = AT_MENTION_PREFIX_REGEX.sub(
                             "",
                             message_str,
                             count=1,
@@ -270,10 +326,44 @@ def _parse_kmarkdown_text_message(
 
         return components, message_str
 
-    def _parse_card_message(self, data: KookMessageEventData) -> tuple[list, str]:
+    async def _parse_kmarkdown_message(
+        self, data: KookMessageEventData
+    ) -> tuple[list[BaseMessageComponent], str]:
+        kmarkdown = data.extra.kmarkdown
+        guild_id = data.extra.guild_id
+        mention_role_part = None
+        if kmarkdown:
+            mention_role_part = kmarkdown.mention_role_part
+        # 无法处理可能会收到的道具消息content,只能保留原样
+        content = str(data.content) or ""
+        if kmarkdown is None:
+            logger.error(
+                f'[KOOK] 无法转换"{KookMessageType.KMARKDOWN.name}"消息, 消息中找不到kmarkdown字段'
+            )
+            logger.error(f"[KOOK] 原始消息内容: {data.to_json()}")
+            return [], ""
+
+        raw_content = kmarkdown.raw_content or content
+
+        mention_name_map: dict[str, str] = {}
+        mention_part = kmarkdown.mention_part
+        for item in mention_part:
+            mention_id = item.id
+            if mention_id is None:
+                continue
+            mention_name_map[str(mention_id)] = str(item.username)
+
+        return await self._convert_text_message_to_component(
+            content, raw_content, mention_role_part, guild_id, mention_name_map
+        )
+
+    async def _parse_card_message(
+        self, data: KookMessageEventData
+    ) -> tuple[list[BaseMessageComponent], str]:
         content = data.content
         if not isinstance(content, str):
             content = str(content)
+        guild_id = data.extra.guild_id
 
         card_list = KookCardMessageContainer.from_dict(json.loads(content))
 
@@ -304,18 +394,13 @@ def _parse_card_message(self, data: KookMessageEventData) -> tuple[list, str]:
                         logger.debug(f"[KOOK] 跳过或未处理模块: {module.type}")
 
         text = "".join(text_parts)
-        message = []
+        message: list[BaseMessageComponent] = []
 
         if text:
-            for search in KOOK_AT_SELECTOR_REGEX.finditer(text):
-                search_text = search.group(1).strip()
-                if search_text == "all":
-                    message.append(AtAll())
-                    continue
-                message.append(At(qq=search_text))
-                text = text.replace(f"(met){search_text}(met)", "")
-
-            message.append(Plain(text=text))
+            component_parts, text = await self._convert_text_message_to_component(
+                text, text, guild_id=guild_id
+            )
+            message.extend(component_parts)
 
         for img_url in images:
             message.append(Image(file=img_url))
@@ -387,12 +472,10 @@ async def convert_message(self, data: KookMessageEventData) -> AstrBotMessage:
         abm.message_id = data.msg_id or "unknown"
 
         if data.type == KookMessageType.KMARKDOWN:
-            message, message_str = self._parse_kmarkdown_text_message(data, abm.self_id)
-            abm.message = message
-            abm.message_str = message_str
+            abm.message, abm.message_str = await self._parse_kmarkdown_message(data)
         elif data.type == KookMessageType.CARD:
             try:
-                abm.message, abm.message_str = self._parse_card_message(data)
+                abm.message, abm.message_str = await self._parse_card_message(data)
             except Exception as exp:
                 logger.error(f"[KOOK] 卡片消息解析失败: {exp}")
                 logger.error(f"[KOOK] 原始消息内容: {data.to_json()}")

astrbot/core/platform/sources/kook/kook_client.py

@@ -3,6 +3,7 @@
 import os
 import random
 import time
+import traceback
 import zlib
 from pathlib import Path
 
@@ -59,12 +60,18 @@ def bot_id(self):
 
     @property
     def bot_nickname(self):
+        """机器人昵称"""
         return self._bot_nickname
 
     @property
     def bot_username(self):
+        """机器人名称"""
         return self._bot_username
 
+    @property
+    def http_client(self):
+        return self._http_client
+
     async def get_bot_info(self) -> None:
         """获取机器人账号信息"""
         url = KookApiPaths.USER_ME
@@ -151,7 +158,6 @@ async def connect(self, resume=False):
             gateway_url = await self.get_gateway_url(
                 resume=resume, sn=self.last_sn, session_id=self.session_id
             )
-            await self.get_bot_info()
 
             if not gateway_url:
                 return False
@@ -215,8 +221,8 @@ async def listen(self):
                 except websockets.exceptions.ConnectionClosed:
                     logger.warning("[KOOK] WebSocket连接已关闭")
                     break
-                except Exception as e:
-                    logger.error(f"[KOOK] 消息处理异常: {e}")
+                except Exception:
+                    logger.error(f"[KOOK] 消息处理异常: {traceback.format_exc()}")
                     break
 
         except Exception as e:
@@ -236,11 +242,15 @@ async def _handle_signal(self, event: KookWebsocketEvent):
                 await self.event_callback(data)
 
             case KookMessageSignal.HELLO:
-                assert isinstance(data, KookHelloEventData)
+                assert isinstance(data, KookHelloEventData), (
+                    f"期望 data 为 {KookHelloEventData.__name__}, 实际为 {type(data).__name__}，"
+                )
                 await self._handle_hello(data)
 
             case KookMessageSignal.RESUME_ACK:
-                assert isinstance(data, KookResumeAckEventData)
+                assert isinstance(data, KookResumeAckEventData), (
+                    f"期望 data 为 {KookResumeAckEventData.__name__}, 实际为 {type(data).__name__}，"
+                )
                 await self._handle_resume_ack(data)
 
             case KookMessageSignal.PONG:
@@ -367,8 +377,8 @@ async def send_text(
             "type": kook_message_type,
         }
         if reply_message_id:
-            payload["quote"] = reply_message_id
-            payload["reply_msg_id"] = reply_message_id
+            payload["quote"] = str(reply_message_id)
+            payload["reply_msg_id"] = str(reply_message_id)
 
         try:
             async with self._http_client.post(url, json=payload) as resp: