diff --git a/README.md b/README.md index 373a6f1..feda84c 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ Minecraft Java 服务器状态查询插件,适用于 AstrBot 的 QQ 官方机 ## 保留的功能 - `/motd`、`/mc`、`/mcstatus` 三个命令入口;群默认服务器查询与临时地址查询。 -- 机器人管理员设置/清除群默认服务器,支持 `set / 设置`、`unset / clear / 清除 / 取消`。设置成功后立即查询。 +- 本群群主、群管理员或机器人管理员均可设置/清除群默认服务器,支持 `set / 设置`、`unset / clear / 清除 / 取消`。设置成功后立即查询。 - 查询在线/离线、版本、MOTD、在线/上限人数、人数进度条、公开玩家样本、服务器图标。没有图标时显示像素苦力怕。 - Minecraft 状态握手和 ping/pong 测得的真实 RTT;保留域名 SRV 解析与显式端口。 - 保留原像素风图片;图片渲染或上传失败时回复文字,包含人数历史摘要。 @@ -69,17 +69,26 @@ Windows 自动使用系统微软雅黑。Linux / Docker 建议在 AstrBot 运行 | `/motd` | 查询本群默认服务器,并显示波动图 | | `/motd mc.example.com` | 临时查询,不改变群默认设置 | | `/motd mc.example.com:25565` | 指定端口查询 | -| `/motd set mc.example.com` | 管理员设置本群服务器并立即查询 | -| `/motd unset` | 管理员清除本群服务器 | +| `/motd set mc.example.com` | 群主/群管理员/机器人管理员设置本群服务器并立即查询 | +| `/motd unset` | 群主/群管理员/机器人管理员清除本群服务器 | +| `/motd identity` | 查看当前用户在本群的授权标识(不会授予权限) | | `/motd history` | 默认服务器的状态与 24 小时波动 | | `/motd history mc.example.com` | 指定服务器的状态与波动 | | `/motd help` | 帮助 | 私聊可以临时查询地址;默认服务器设置/清除在群聊中使用。当前查询 Minecraft **Java 版**,保持旧项目的查询范围。 +### 群管理权限 + +`set` 和 `unset` 都允许本群群主、本群管理员以及机器人管理员操作,普通群成员可以查询状态和历史。群角色取自平台消息中的 `sender.role` / `author.member_role`;消息没有角色时尝试通过平台群成员接口核实,不能用 AstrBot 全局 `event.is_admin()` 代替群角色。 + +OneBot 支持读取群消息角色及查询成员信息。QQ 官方(WebSocket / Webhook)支持读取消息原始角色,并复用当前适配器的鉴权请求查询 `/v2/groups/{group_openid}/members/{member_openid}`。实际可用性取决于机器人接口权限;[QQ SDK 的群成员接口说明](https://zhinjs.github.io/qq-official-bot/api/group.html#群成员查询) 介绍了接口权限限制。角色无法核实会明确提示,不会把普通成员当作管理员。 + +如果 QQ 官方接口无法提供角色,可以由机器人管理员配置**单群授权**:让该群管理人员在对应群发送 `/motd identity`,把返回的 `平台ID|群ID|用户ID` 加入插件 `group_admin_ids`。该授权只允许此人在此群管理 MOTD,不会获得全局机器人权限,也不对其他群生效。群管理人员变更后应移除旧授权。 + ## 配置 -在 WebUI 插件配置中调整:`bot_name`、`admin_ids`、`api_url`、`request_timeout`、`ping_timeout`、`history_enabled`、`sample_interval`、`retention_hours`、`monitor_servers`、`font_path`。后台采样参数修改后重载插件。 +在 WebUI 插件配置中调整:`bot_name`、`admin_ids`、`group_admin_ids`、`api_url`、`request_timeout`、`ping_timeout`、`history_enabled`、`sample_interval`、`retention_hours`、`monitor_servers`、`font_path`。后台采样参数修改后重载插件。 ## 本地验证与打包 diff --git a/_conf_schema.json b/_conf_schema.json index 5896efc..3152e49 100644 --- a/_conf_schema.json +++ b/_conf_schema.json @@ -1,6 +1,7 @@ { "bot_name": {"description": "状态卡署名", "type": "string", "default": "xiaohuicat"}, "admin_ids": {"description": "额外机器人管理员 ID", "type": "list", "default": [], "hint": "AstrBot 管理员自动拥有权限。QQ 官方机器人请填写平台用户 ID/openid,可通过 /sid 查看,不要填写旧机器人的数字 QQ 号。"}, + "group_admin_ids": {"description": "本群管理授权(平台无法获取群角色时)", "type": "list", "default": [], "hint": "通常自动识别群主/群管理员,无需填写。QQ 官方接口无法获取角色时,让该群管理人员在对应群发送 /motd identity,把返回的 平台ID|群ID|用户ID 填入此列表,只授权该用户管理该群 MOTD,不授予全局机器人管理权限。群管理人员变更后请及时移除旧授权。"}, "api_url": {"description": "备用查询 API", "type": "string", "default": "https://api.mcsrvstat.us/2/{address}", "hint": "直连失败时使用,保留 {address} 占位符。响应应为 mcsrvstat.us 格式。"}, "request_timeout": {"description": "备用 API 超时(秒)", "type": "float", "default": 10.0}, "ping_timeout": {"description": "Minecraft 直连超时(秒)", "type": "float", "default": 4.0}, diff --git a/main.py b/main.py index e24d16b..205d6b3 100644 --- a/main.py +++ b/main.py @@ -14,13 +14,15 @@ from .services.address import normalize_address from .services.mc_api import MinecraftServerAPI from .services.monitor import PlayerMonitor from .services.motd_card import render_motd_card +from .services.permissions import get_group_role from .services.storage import MotdStore HELP = """Minecraft MOTD 查询 /motd 查询本群默认服务器 /motd 服务器地址 临时查询(不改变默认设置) -/motd set 服务器地址 设置本群服务器(机器人管理员) -/motd unset 清除本群设置(机器人管理员) +/motd set 服务器地址 设置本群服务器(群主/群管理员/机器人管理员) +/motd unset 清除本群设置(群主/群管理员/机器人管理员) +/motd identity 查看本群授权标识(平台无法识别群角色时使用) /motd history [服务器地址] 查看最近 24 小时玩家波动 /motd help 查看帮助 别名:/mc、/mcstatus;设置、清除、取消、波动、趋势也可使用。 @@ -70,6 +72,19 @@ class MotdPlugin(Star): str(value) for value in self.config.get("admin_ids", []) } + @staticmethod + def _group_authorization_key(event): + return f"{event.get_platform_id()}|{event.get_group_id()}|{event.get_sender_id()}" + + async def _can_manage_group(self, event): + if self._is_admin(event): + return True, True + # Manual grants are confined to one adapter instance, group and user. + if self._group_authorization_key(event) in self.config.get("group_admin_ids", []): + return True, True + role = await get_group_role(event) + return role in {"owner", "admin"}, role is not None + @filter.command("motd", alias={"mc", "mcstatus"}) async def motd(self, event: AstrMessageEvent, action: str = "", address: str = ""): """查询 Minecraft 状态、设置群默认服务器,以及查看 24 小时玩家波动图。""" @@ -93,12 +108,18 @@ class MotdPlugin(Star): if verb in {"help", "帮助"}: await event.send(event.plain_result(HELP)) return - if verb in {"set", "设置", "unset", "clear", "清除", "取消"}: - if not self._is_admin(event): + if verb in {"identity", "身份"}: + if not event.get_group_id(): + await event.send(event.plain_result("⚠️ 请在群内查看授权标识。")) + else: await event.send( - event.plain_result("❌ 只有机器人管理员可以设置或清除本群 MOTD 服务器。") + event.plain_result( + "本群授权标识(仅供机器人管理员配置,本命令不会授予权限):\n" + + self._group_authorization_key(event) + ) ) - return + return + if verb in {"set", "设置", "unset", "clear", "清除", "取消"}: if not event.get_group_id(): await event.send( event.plain_result( @@ -106,6 +127,17 @@ class MotdPlugin(Star): ) ) return + allowed, verified = await self._can_manage_group(event) + if not allowed: + message = "❌ 只有本群群主、群管理员或机器人管理员可以设置或清除 MOTD 服务器。" + if not verified: + message += ( + "\n⚠️ 平台未提供可用的群角色信息,暂时无法核实身份。" + "请检查群成员查询接口权限,或发送 /motd identity," + "由机器人管理员在插件配置 group_admin_ids 中按群授权。" + ) + await event.send(event.plain_result(message)) + return if verb in {"set", "设置"}: if not address: raise ValueError("格式: /motd set 服务器地址") diff --git a/metadata.yaml b/metadata.yaml index 361639a..a8fb403 100644 --- a/metadata.yaml +++ b/metadata.yaml @@ -1,7 +1,7 @@ name: astrbot_plugin_motd display_name: Minecraft MOTD 与玩家波动 desc: Minecraft Java 服务器状态图片、群默认服务器、真实 Ping、玩家名单和最近 24 小时人数波动图。 -version: v1.0.0 +version: v1.0.1 author: itxiaohui support_platforms: - qq_official diff --git a/services/permissions.py b/services/permissions.py new file mode 100644 index 0000000..6b2443f --- /dev/null +++ b/services/permissions.py @@ -0,0 +1,100 @@ +"""Resolve the sender's group role without confusing it with AstrBot's global admin role.""" + +import asyncio +import logging +from collections.abc import Mapping +from urllib.parse import quote + +logger = logging.getLogger(__name__) +ROLES = {"owner", "admin", "member"} + + +def field(value, key, default=None): + return value.get(key, default) if isinstance(value, Mapping) else getattr(value, key, default) + + +def role_of(value): + for key in ("member_role", "role"): + role = field(value, key) + if isinstance(role, str) and role.lower() in ROLES: + return role.lower() + return None + + +async def get_group_role(event) -> str | None: + """Return owner/admin/member, or None if the platform cannot verify membership.""" + group_id, user_id = str(event.get_group_id()), str(event.get_sender_id()) + if not group_id or not user_id: + return None + platform = event.get_platform_name() + message = getattr(event, "message_obj", None) + raw = field(message, "raw_message") + if platform == "aiocqhttp": + if ( + field(raw, "group_id", group_id) is not None + and str(field(raw, "group_id", group_id)) != group_id + ): + return None + if str(field(field(raw, "sender"), "user_id", user_id)) != user_id: + return None + role = role_of(field(raw, "sender")) + elif platform in {"qq_official", "qq_official_webhook"}: + # New AstrBot parsers retain raw_data even when botpy drops author fields. + raw_data = field(raw, "raw_data") + if str(field(raw_data, "group_openid", field(raw, "group_openid", group_id))) != group_id: + return None + author = field(raw_data, "author", field(raw, "author")) + if str(field(author, "member_openid", user_id)) != user_id: + return None + role = role_of(field(raw_data, "author")) or role_of(field(raw, "author")) + else: + return None + if role: + return role + + async def lookup(): + bot = getattr(event, "bot", None) + if platform == "aiocqhttp": + routing = {} + self_id = field(raw, "self_id") + if self_id is not None: + routing["self_id"] = self_id + info = await bot.call_action( + "get_group_member_info", + group_id=int(group_id), + user_id=int(user_id), + no_cache=True, + **routing, + ) + if not isinstance(info, Mapping): + return None + if str(info.get("user_id", "")) != user_id or str(info.get("group_id", "")) != group_id: + return None + return role_of(info) + # Reuse the adapter's authenticated SDK client; do not duplicate secrets. + from botpy.http import Route + + info = await bot.api._http.request( + Route( + "GET", + "/v2/groups/{group_openid}/members/{member_openid}", + group_openid=quote(group_id, safe=""), + member_openid=quote(user_id, safe=""), + ) + ) + if not isinstance(info, Mapping): + return None + # Some clients wrap the member response; never accept a different user's role. + info = info.get("data", info) + if not isinstance(info, Mapping) or str(info.get("member_openid", "")) != user_id: + return None + response_group = info.get("group_openid") + if response_group is not None and str(response_group) != group_id: + return None + return role_of(info) + + try: + return await asyncio.wait_for(lookup(), timeout=5) + except Exception as exc: + logger.warning("MOTD 群角色查询不可用 (%s): %s", platform, type(exc).__name__) + return None diff --git a/tests/test_permissions.py b/tests/test_permissions.py new file mode 100644 index 0000000..b68e0f7 --- /dev/null +++ b/tests/test_permissions.py @@ -0,0 +1,115 @@ +import sys +import types + +import pytest + +from services.permissions import get_group_role + + +class Event: + def __init__(self, platform="qq_official", raw=None, group="g", user="u", bot=None): + self.platform, self.group, self.user, self.bot = platform, group, user, bot + self.message_obj = types.SimpleNamespace(raw_message=raw) + + def get_group_id(self): + return self.group + + def get_sender_id(self): + return self.user + + def get_platform_name(self): + return self.platform + + +@pytest.mark.parametrize("role", ["owner", "admin", "member"]) +async def test_official_preserved_raw_data(role): + raw = types.SimpleNamespace( + author=types.SimpleNamespace(member_openid="u"), + raw_data={"author": {"member_openid": "u", "member_role": role}, "group_openid": "g"}, + ) + assert await get_group_role(Event(raw=raw)) == role + + +@pytest.fixture +def fake_botpy(monkeypatch): + class Route: + def __init__(self, method, path, **kwargs): + self.method, self.path, self.parameters = method, path, kwargs + + module = types.ModuleType("botpy.http") + module.Route = Route + monkeypatch.setitem(sys.modules, "botpy", types.ModuleType("botpy")) + monkeypatch.setitem(sys.modules, "botpy.http", module) + + +@pytest.mark.parametrize("platform", ["qq_official", "qq_official_webhook"]) +@pytest.mark.parametrize("role", ["owner", "admin", "member"]) +async def test_official_authenticated_member_lookup(fake_botpy, platform, role): + seen = [] + + async def request(route): + seen.append(route) + return {"member_openid": "u", "member_role": role} + + bot = types.SimpleNamespace( + api=types.SimpleNamespace(_http=types.SimpleNamespace(request=request)) + ) + assert await get_group_role(Event(platform=platform, bot=bot)) == role + assert seen[0].method == "GET" + assert seen[0].path == "/v2/groups/{group_openid}/members/{member_openid}" + assert seen[0].parameters == {"group_openid": "g", "member_openid": "u"} + + +@pytest.mark.parametrize( + "response", + [ + {"member_openid": "wrong-user", "member_role": "owner"}, + {"member_openid": "u", "member_role": "admin", "group_openid": "wrong-group"}, + {"code": 11253, "message": "API not enabled"}, + None, + ], +) +async def test_wrong_identity_or_unavailable_official_api_never_grants(fake_botpy, response): + async def request(route): + return response + + bot = types.SimpleNamespace( + api=types.SimpleNamespace(_http=types.SimpleNamespace(request=request)) + ) + assert await get_group_role(Event(bot=bot)) is None + + +async def test_onebot_live_lookup_passes_routing_and_no_cache(): + seen = [] + + async def action(name, **kwargs): + seen.append((name, kwargs)) + return {"user_id": 2, "group_id": 1, "role": "owner"} + + bot = types.SimpleNamespace(call_action=action) + event = Event("aiocqhttp", raw={"self_id": 123}, group="1", user="2", bot=bot) + assert await get_group_role(event) == "owner" + assert seen == [ + ("get_group_member_info", {"group_id": 1, "user_id": 2, "no_cache": True, "self_id": 123}) + ] + + +async def test_api_failure_denies_without_crashing(fake_botpy): + async def request(route): + raise PermissionError("not enabled") + + bot = types.SimpleNamespace( + api=types.SimpleNamespace(_http=types.SimpleNamespace(request=request)) + ) + assert await get_group_role(Event(bot=bot)) is None + + +async def test_mismatched_incoming_author_and_message_text_do_not_grant(): + assert ( + await get_group_role( + Event(raw={"author": {"member_openid": "wrong", "member_role": "owner"}}) + ) + is None + ) + assert await get_group_role(Event(raw={"content": '{"member_role": "owner"}'})) is None + assert await get_group_role(Event(raw={"author": {"member_role": "admin"}}, group="")) is None diff --git a/tests/test_plugin.py b/tests/test_plugin.py index d63a1d1..bd13bce 100644 --- a/tests/test_plugin.py +++ b/tests/test_plugin.py @@ -10,8 +10,19 @@ import pytest class Event: - def __init__(self, platform="qq-main", group="group-openid", admin=False, image_error=False): + def __init__( + self, + platform="qq-main", + group="group-openid", + admin=False, + image_error=False, + platform_name="qq_official", + raw=None, + user="user-openid", + ): self.platform, self.group, self.admin = platform, group, admin + self.platform_name, self.user = platform_name, user + self.message_obj = types.SimpleNamespace(raw_message=raw) self.image_error = image_error self.unified_msg_origin = f"{platform}:private:user" self.messages = [] @@ -23,8 +34,11 @@ class Event: def get_platform_id(self): return self.platform + def get_platform_name(self): + return self.platform_name + def get_sender_id(self): - return "user-openid" + return self.user def is_admin(self): return self.admin @@ -146,3 +160,65 @@ async def test_missing_default_invalid_and_private_setting(plugin_class): await plugin.motd(event, "help") assert "/mcstatus" in event.messages[-1][1] await plugin.terminate() + + +@pytest.mark.parametrize("platform_name", ["qq_official", "qq_official_webhook", "aiocqhttp"]) +@pytest.mark.parametrize("role", ["owner", "admin", "member"]) +async def test_group_roles_can_set_and_clear_only_when_privileged( + plugin_class, platform_name, role +): + plugin = plugin_class(object(), {"history_enabled": False}) + + async def no_send(*args): + pass + + plugin._query_and_send = no_send + raw = ( + {"sender": {"role": role}} + if platform_name == "aiocqhttp" + else {"author": {"member_role": role}} + ) + event = Event(platform_name=platform_name, raw=raw) + await plugin.motd(event, "set", "a.test") + scope = plugin._scope(event) + if role == "member": + assert await plugin.store.get_binding(scope) is None + assert "暂时无法核实" not in event.messages[-1][1] + await plugin.store.set_binding(scope, "original.test", "bot-admin") + await plugin.motd(event, "unset") + assert await plugin.store.get_binding(scope) == "original.test" + else: + assert await plugin.store.get_binding(scope) == "a.test" + await plugin.motd(event, "unset") + assert await plugin.store.get_binding(scope) is None + await plugin.terminate() + + +async def test_group_grant_is_limited_to_one_group_and_adapter(plugin_class): + plugin = plugin_class( + object(), + {"history_enabled": False, "group_admin_ids": ["qq-main|group-openid|user-openid"]}, + ) + + async def no_send(*args): + pass + + plugin._query_and_send = no_send + event = Event() + await plugin.motd(event, "set", "a.test") + assert await plugin.store.get_binding(plugin._scope(event)) == "a.test" + for outsider in [ + Event(group="another-group"), + Event(platform="another-bot"), + Event(user="another-user"), + ]: + await plugin.motd(outsider, "set", "unauthorized.test") + assert "无法核实" in outsider.messages[-1][1] + if outsider.group != event.group or outsider.platform != event.platform: + assert await plugin.store.get_binding(plugin._scope(outsider)) is None + else: + assert await plugin.store.get_binding(plugin._scope(outsider)) == "a.test" + await plugin.motd(event, "identity") + assert "qq-main|group-openid|user-openid" in event.messages[-1][1] + assert not plugin._is_admin(event) + await plugin.terminate() diff --git a/tools/package.py b/tools/package.py index 16e81de..6ab2b53 100644 --- a/tools/package.py +++ b/tools/package.py @@ -1,5 +1,6 @@ """Build an installable archive without local data, test stubs, or development downloads.""" +import re from pathlib import Path from zipfile import ZIP_DEFLATED, ZipFile @@ -7,7 +8,11 @@ ROOT = Path(__file__).resolve().parents[1] def main(): - target = ROOT / "dist" / "astrbot_plugin_motd-v1.0.0.zip" + metadata = (ROOT / "metadata.yaml").read_text(encoding="utf-8") + version = re.search(r"^version:\s*(v[0-9]+\.[0-9]+\.[0-9]+)\s*$", metadata, re.MULTILINE).group( + 1 + ) + target = ROOT / "dist" / f"astrbot_plugin_motd-{version}.zip" target.parent.mkdir(exist_ok=True) files = ( [