1 Commits
Author SHA1 Message Date
itxiaohui 1bbecbfaa1 Allow group owners and admins to manage MOTD server settings 2026-10-05 13:38:37 +08:00
8 changed files with 352 additions and 14 deletions

No files matched your search

+13 -4
View File
@@ -7,7 +7,7 @@ Minecraft Java 服务器状态查询插件,适用于 AstrBot 的 QQ 官方机
## 保留的功能 ## 保留的功能
- `/motd`、`/mc`、`/mcstatus` 三个命令入口;群默认服务器查询与临时地址查询。 - `/motd`、`/mc`、`/mcstatus` 三个命令入口;群默认服务器查询与临时地址查询。
- 机器人管理员设置/清除群默认服务器,支持 `set / 设置`、`unset / clear / 清除 / 取消`。设置成功后立即查询。 - 本群群主、群管理员或机器人管理员均可设置/清除群默认服务器,支持 `set / 设置`、`unset / clear / 清除 / 取消`。设置成功后立即查询。
- 查询在线/离线、版本、MOTD、在线/上限人数、人数进度条、公开玩家样本、服务器图标。没有图标时显示像素苦力怕。 - 查询在线/离线、版本、MOTD、在线/上限人数、人数进度条、公开玩家样本、服务器图标。没有图标时显示像素苦力怕。
- Minecraft 状态握手和 ping/pong 测得的真实 RTT;保留域名 SRV 解析与显式端口。 - Minecraft 状态握手和 ping/pong 测得的真实 RTT;保留域名 SRV 解析与显式端口。
- 保留原像素风图片;图片渲染或上传失败时回复文字,包含人数历史摘要。 - 保留原像素风图片;图片渲染或上传失败时回复文字,包含人数历史摘要。
@@ -69,17 +69,26 @@ Windows 自动使用系统微软雅黑。Linux / Docker 建议在 AstrBot 运行
| `/motd` | 查询本群默认服务器,并显示波动图 | | `/motd` | 查询本群默认服务器,并显示波动图 |
| `/motd mc.example.com` | 临时查询,不改变群默认设置 | | `/motd mc.example.com` | 临时查询,不改变群默认设置 |
| `/motd mc.example.com:25565` | 指定端口查询 | | `/motd mc.example.com:25565` | 指定端口查询 |
| `/motd set mc.example.com` | 管理员设置本群服务器并立即查询 | | `/motd set mc.example.com` | 群主/群管理员/机器人管理员设置本群服务器并立即查询 |
| `/motd unset` | 管理员清除本群服务器 | | `/motd unset` | 群主/群管理员/机器人管理员清除本群服务器 |
| `/motd identity` | 查看当前用户在本群的授权标识(不会授予权限) |
| `/motd history` | 默认服务器的状态与 24 小时波动 | | `/motd history` | 默认服务器的状态与 24 小时波动 |
| `/motd history mc.example.com` | 指定服务器的状态与波动 | | `/motd history mc.example.com` | 指定服务器的状态与波动 |
| `/motd help` | 帮助 | | `/motd help` | 帮助 |
私聊可以临时查询地址;默认服务器设置/清除在群聊中使用。当前查询 Minecraft **Java 版**,保持旧项目的查询范围。 私聊可以临时查询地址;默认服务器设置/清除在群聊中使用。当前查询 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`。后台采样参数修改后重载插件。
## 本地验证与打包 ## 本地验证与打包
+1
View File
@@ -1,6 +1,7 @@
{ {
"bot_name": {"description": "状态卡署名", "type": "string", "default": "xiaohuicat"}, "bot_name": {"description": "状态卡署名", "type": "string", "default": "xiaohuicat"},
"admin_ids": {"description": "额外机器人管理员 ID", "type": "list", "default": [], "hint": "AstrBot 管理员自动拥有权限。QQ 官方机器人请填写平台用户 ID/openid,可通过 /sid 查看,不要填写旧机器人的数字 QQ 号。"}, "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 格式。"}, "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}, "request_timeout": {"description": "备用 API 超时(秒)", "type": "float", "default": 10.0},
"ping_timeout": {"description": "Minecraft 直连超时(秒)", "type": "float", "default": 4.0}, "ping_timeout": {"description": "Minecraft 直连超时(秒)", "type": "float", "default": 4.0},
+38 -6
View File
@@ -14,13 +14,15 @@ from .services.address import normalize_address
from .services.mc_api import MinecraftServerAPI from .services.mc_api import MinecraftServerAPI
from .services.monitor import PlayerMonitor from .services.monitor import PlayerMonitor
from .services.motd_card import render_motd_card from .services.motd_card import render_motd_card
from .services.permissions import get_group_role
from .services.storage import MotdStore from .services.storage import MotdStore
HELP = """Minecraft MOTD 查询 HELP = """Minecraft MOTD 查询
/motd 查询本群默认服务器 /motd 查询本群默认服务器
/motd 服务器地址 临时查询(不改变默认设置) /motd 服务器地址 临时查询(不改变默认设置)
/motd set 服务器地址 设置本群服务器(机器人管理员) /motd set 服务器地址 设置本群服务器(群主/群管理员/机器人管理员)
/motd unset 清除本群设置(机器人管理员) /motd unset 清除本群设置(群主/群管理员/机器人管理员)
/motd identity 查看本群授权标识(平台无法识别群角色时使用)
/motd history [服务器地址] 查看最近 24 小时玩家波动 /motd history [服务器地址] 查看最近 24 小时玩家波动
/motd help 查看帮助 /motd help 查看帮助
别名:/mc、/mcstatus;设置、清除、取消、波动、趋势也可使用。 别名:/mc、/mcstatus;设置、清除、取消、波动、趋势也可使用。
@@ -70,6 +72,19 @@ class MotdPlugin(Star):
str(value) for value in self.config.get("admin_ids", []) 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"}) @filter.command("motd", alias={"mc", "mcstatus"})
async def motd(self, event: AstrMessageEvent, action: str = "", address: str = ""): async def motd(self, event: AstrMessageEvent, action: str = "", address: str = ""):
"""查询 Minecraft 状态、设置群默认服务器,以及查看 24 小时玩家波动图。""" """查询 Minecraft 状态、设置群默认服务器,以及查看 24 小时玩家波动图。"""
@@ -93,12 +108,18 @@ class MotdPlugin(Star):
if verb in {"help", "帮助"}: if verb in {"help", "帮助"}:
await event.send(event.plain_result(HELP)) await event.send(event.plain_result(HELP))
return return
if verb in {"set", "设置", "unset", "clear", "清除", "取消"}: if verb in {"identity", "身份"}:
if not self._is_admin(event): if not event.get_group_id():
await event.send(event.plain_result("⚠️ 请在群内查看授权标识。"))
else:
await event.send( 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(): if not event.get_group_id():
await event.send( await event.send(
event.plain_result( event.plain_result(
@@ -106,6 +127,17 @@ class MotdPlugin(Star):
) )
) )
return 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 verb in {"set", "设置"}:
if not address: if not address:
raise ValueError("格式: /motd set 服务器地址") raise ValueError("格式: /motd set 服务器地址")
+1 -1
View File
@@ -1,7 +1,7 @@
name: astrbot_plugin_motd name: astrbot_plugin_motd
display_name: Minecraft MOTD 与玩家波动 display_name: Minecraft MOTD 与玩家波动
desc: Minecraft Java 服务器状态图片、群默认服务器、真实 Ping、玩家名单和最近 24 小时人数波动图。 desc: Minecraft Java 服务器状态图片、群默认服务器、真实 Ping、玩家名单和最近 24 小时人数波动图。
version: v1.0.0 version: v1.0.1
author: itxiaohui author: itxiaohui
support_platforms: support_platforms:
- qq_official - qq_official
+100
View File
@@ -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
+115
View File
@@ -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
+78 -2
View File
@@ -10,8 +10,19 @@ import pytest
class Event: 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, 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.image_error = image_error
self.unified_msg_origin = f"{platform}:private:user" self.unified_msg_origin = f"{platform}:private:user"
self.messages = [] self.messages = []
@@ -23,8 +34,11 @@ class Event:
def get_platform_id(self): def get_platform_id(self):
return self.platform return self.platform
def get_platform_name(self):
return self.platform_name
def get_sender_id(self): def get_sender_id(self):
return "user-openid" return self.user
def is_admin(self): def is_admin(self):
return self.admin return self.admin
@@ -146,3 +160,65 @@ async def test_missing_default_invalid_and_private_setting(plugin_class):
await plugin.motd(event, "help") await plugin.motd(event, "help")
assert "/mcstatus" in event.messages[-1][1] assert "/mcstatus" in event.messages[-1][1]
await plugin.terminate() 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()
+6 -1
View File
@@ -1,5 +1,6 @@
"""Build an installable archive without local data, test stubs, or development downloads.""" """Build an installable archive without local data, test stubs, or development downloads."""
import re
from pathlib import Path from pathlib import Path
from zipfile import ZIP_DEFLATED, ZipFile from zipfile import ZIP_DEFLATED, ZipFile
@@ -7,7 +8,11 @@ ROOT = Path(__file__).resolve().parents[1]
def main(): 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) target.parent.mkdir(exist_ok=True)
files = ( files = (
[ [