nonebot-plugin-ts3-tracker 1.0.0__py3-none-any.whl

nonebot_plugin_ts3_tracker/__init__.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+import re
+
+from nonebot import get_driver, get_plugin_config, logger, on_command, on_regex
+from nonebot.adapters.onebot.v11 import GroupMessageEvent, MessageEvent
+from nonebot.plugin import PluginMetadata
+
+from .config import Config
+from .runtime import Ts3TrackerRuntime
+from .service import Ts3TrackerService
+
+plugin_config = get_plugin_config(Config).ts3_tracker
+service = Ts3TrackerService(plugin_config)
+runtime = Ts3TrackerRuntime(plugin_config, service)
+
+__plugin_meta__ = PluginMetadata(
+    name="TS3 Tracker",
+    description="查询 TeamSpeak 3 服务器在线状态与频道在线成员。",
+    usage=(
+        "上号\n"
+        "/ts\n"
+        "/tsinfo\n\n"
+        "可选：开启轮询后发送 TS3 进服/退服通知"
+    ),
+    type="application",
+    homepage="https://github.com/moeneri/nonebot-plugin-ts3-tracker",
+    config=Config,
+    supported_adapters={"nonebot.adapters.onebot.v11"},
+)
+
+
+def _ensure_group_allowed(event: MessageEvent) -> str | None:
+    if not isinstance(event, GroupMessageEvent):
+        return None
+    if plugin_config.is_group_allowed(event.group_id):
+        return None
+    return "当前群未开启 TS3 查询白名单权限。"
+
+
+ts3_status = on_command(
+    "上号",
+    aliases={"ts", "tsinfo"},
+    priority=plugin_config.command_priority,
+    block=True,
+)
+ts3_status_regex = on_regex(
+    r"^(?:/)?(?:上号|ts|tsinfo)$",
+    flags=re.IGNORECASE,
+    priority=plugin_config.command_priority,
+    block=True,
+)
+
+
+@ts3_status.handle()
+async def handle_ts3_status(event: MessageEvent) -> None:
+    denied_message = _ensure_group_allowed(event)
+    if denied_message is not None:
+        await ts3_status.finish(denied_message)
+
+    group_id = getattr(event, "group_id", None)
+    logger.info(
+        "群号 {} 查询了服务器信息。",
+        group_id if group_id is not None else event.get_session_id(),
+    )
+    message = await service.build_server_message()
+    await ts3_status.finish(message)
+
+
+@ts3_status_regex.handle()
+async def handle_ts3_status_regex(event: MessageEvent) -> None:
+    denied_message = _ensure_group_allowed(event)
+    if denied_message is not None:
+        await ts3_status_regex.finish(denied_message)
+
+    group_id = getattr(event, "group_id", None)
+    logger.info(
+        "群号 {} 查询了服务器信息。",
+        group_id if group_id is not None else event.get_session_id(),
+    )
+    message = await service.build_server_message()
+    await ts3_status_regex.finish(message)
+
+
+driver = get_driver()
+driver.on_startup(runtime.startup)
+driver.on_shutdown(runtime.shutdown)

nonebot_plugin_ts3_tracker/config.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, Field, field_validator
+
+
+class Ts3TrackerSettings(BaseModel):
+    server_host: str = ""
+    server_port: int = 9987
+    serverquery_port: int = 10011
+    serverquery_username: str = ""
+    serverquery_password: str = ""
+    debug: bool = False
+    command_priority: int = 10
+    query_timeout_seconds: float = 10.0
+    notification_enabled: bool = False
+    notify_target_groups: str = ""
+    notify_target_users: str = ""
+    notify_bot_id: str = ""
+    group_whitelist_enabled: bool = False
+    group_whitelist_groups: str = ""
+    poll_interval_seconds: int = 5
+    startup_silent: bool = True
+    data_dir: str = ""
+
+    @field_validator(
+        "server_host",
+        "serverquery_username",
+        "serverquery_password",
+        "notify_target_groups",
+        "notify_target_users",
+        "notify_bot_id",
+        "group_whitelist_groups",
+        "data_dir",
+        mode="before",
+    )
+    @classmethod
+    def strip_text(cls, value: object) -> str:
+        return str(value).strip()
+
+    @field_validator("command_priority", "poll_interval_seconds")
+    @classmethod
+    def validate_positive_int(cls, value: int) -> int:
+        return max(1, value)
+
+    @field_validator("query_timeout_seconds")
+    @classmethod
+    def validate_timeout(cls, value: float) -> float:
+        return max(1.0, value)
+
+    def parse_targets(self, raw: str) -> list[str]:
+        normalized = raw.replace("\r", "\n").replace(";", "\n").replace(",", "\n")
+        targets = [item.strip() for item in normalized.split("\n")]
+        return [item for item in targets if item]
+
+    def is_group_allowed(self, group_id: str | int | None) -> bool:
+        if group_id is None or not self.group_whitelist_enabled:
+            return True
+        return str(group_id) in set(self.parse_targets(self.group_whitelist_groups))
+
+    def get_effective_notify_groups(self) -> list[str]:
+        notify_groups = self.parse_targets(self.notify_target_groups)
+        if not self.group_whitelist_enabled:
+            return notify_groups
+        whitelist = set(self.parse_targets(self.group_whitelist_groups))
+        return [group_id for group_id in notify_groups if group_id in whitelist]
+
+
+class Config(BaseModel):
+    ts3_tracker: Ts3TrackerSettings = Field(default_factory=Ts3TrackerSettings)

nonebot_plugin_ts3_tracker/models.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(slots=True)
+class Ts3OnlineUser:
+    nickname: str
+    channel_id: str
+    channel_name: str
+    client_id: str
+    database_id: str
+    unique_id: str
+    client_ip: str
+    connected_duration_seconds: int
+    away: bool
+
+
+@dataclass(slots=True)
+class Ts3ServerStatus:
+    server_name: str
+    server_host: str
+    server_port: int
+    online_count: int
+    channels: list[tuple[str, str]]
+    users: list[Ts3OnlineUser]

nonebot_plugin_ts3_tracker/query.py

@@ -0,0 +1,275 @@
+from __future__ import annotations
+
+import asyncio
+import contextlib
+from collections.abc import Sequence
+
+from nonebot import logger
+
+from .models import Ts3OnlineUser, Ts3ServerStatus
+
+
+class Ts3QueryError(Exception):
+    """Raised when a ServerQuery request fails."""
+
+
+ESCAPE_MAP = {
+    "\\": "\\\\",
+    "/": "\\/",
+    " ": "\\s",
+    "|": "\\p",
+    "\a": "\\a",
+    "\b": "\\b",
+    "\f": "\\f",
+    "\n": "\\n",
+    "\r": "\\r",
+    "\t": "\\t",
+    "\v": "\\v",
+}
+
+UNESCAPE_MAP = {
+    "\\\\": "\\",
+    "\\/": "/",
+    "\\s": " ",
+    "\\p": "|",
+    "\\a": "\a",
+    "\\b": "\b",
+    "\\f": "\f",
+    "\\n": "\n",
+    "\\r": "\r",
+    "\\t": "\t",
+    "\\v": "\v",
+}
+
+
+class Ts3QueryClient:
+    def __init__(
+        self,
+        host: str,
+        server_port: int,
+        username: str,
+        password: str,
+        query_port: int = 10011,
+        timeout: float = 10.0,
+    ) -> None:
+        self.host = host
+        self.server_port = server_port
+        self.query_port = query_port
+        self.username = username
+        self.password = password
+        self.timeout = timeout
+
+    async def fetch_status(self) -> Ts3ServerStatus:
+        try:
+            return await asyncio.wait_for(self._fetch_status_inner(), timeout=self.timeout)
+        except asyncio.TimeoutError as exc:
+            raise Ts3QueryError(f"TS3 查询超时（{self.timeout:.0f} 秒）") from exc
+
+    async def _fetch_status_inner(self) -> Ts3ServerStatus:
+        try:
+            reader, writer = await asyncio.open_connection(self.host, self.query_port)
+        except Exception as exc:  # pragma: no cover - network dependent
+            raise Ts3QueryError(
+                f"无法连接到 ServerQuery：{self.host}:{self.query_port} ({exc})"
+            ) from exc
+
+        try:
+            await self._consume_welcome(reader)
+            await self._execute(
+                reader,
+                writer,
+                f"login {self._escape(self.username)} {self._escape(self.password)}",
+                "login",
+            )
+            await self._execute(reader, writer, f"use port={self.server_port}", "use")
+            serverinfo_records = await self._execute(
+                reader, writer, "serverinfo", "serverinfo"
+            )
+            channel_records = await self._execute(
+                reader, writer, "channellist", "channellist"
+            )
+            client_records = await self._execute(
+                reader,
+                writer,
+                "clientlist -uid -away -ip -times",
+                "clientlist",
+            )
+            await self._write_line(writer, "quit")
+        finally:
+            writer.close()
+            with contextlib.suppress(Exception):
+                await writer.wait_closed()
+
+        serverinfo = serverinfo_records[0] if serverinfo_records else {}
+        channels = {
+            channel.get("cid", ""): channel.get("channel_name", "")
+            for channel in channel_records
+        }
+        channel_order = [
+            (channel.get("cid", ""), channel.get("channel_name", ""))
+            for channel in channel_records
+            if channel.get("cid", "")
+        ]
+
+        users: list[Ts3OnlineUser] = []
+        for client in client_records:
+            if client.get("client_type") == "1":
+                continue
+
+            users.append(
+                Ts3OnlineUser(
+                    nickname=client.get("client_nickname", ""),
+                    channel_id=client.get("cid", ""),
+                    channel_name=channels.get(client.get("cid", ""), ""),
+                    client_id=client.get("clid", ""),
+                    database_id=client.get("client_database_id", ""),
+                    unique_id=client.get("client_unique_identifier", ""),
+                    client_ip=client.get("connection_client_ip", ""),
+                    connected_duration_seconds=max(
+                        0,
+                        self._safe_int(client.get("connection_connected_time"), 0) // 1000,
+                    ),
+                    away=client.get("client_away", "0") == "1",
+                )
+            )
+
+        users.sort(key=lambda item: item.nickname.casefold())
+        server_port = self._safe_int(
+            serverinfo.get("virtualserver_port"), self.server_port
+        )
+
+        return Ts3ServerStatus(
+            server_name=serverinfo.get("virtualserver_name", ""),
+            server_host=self.host,
+            server_port=server_port,
+            online_count=len(users),
+            channels=channel_order,
+            users=users,
+        )
+
+    async def _execute(
+        self,
+        reader: asyncio.StreamReader,
+        writer: asyncio.StreamWriter,
+        command: str,
+        action: str,
+    ) -> list[dict[str, str]]:
+        await self._write_line(writer, command)
+        lines = await self._read_response(reader)
+        return self._parse_response(lines, action)
+
+    async def _write_line(self, writer: asyncio.StreamWriter, line: str) -> None:
+        writer.write(f"{line}\n".encode("utf-8"))
+        await writer.drain()
+
+    async def _consume_welcome(self, reader: asyncio.StreamReader) -> None:
+        while True:
+            raw_line = await reader.readline()
+            if not raw_line:
+                logger.warning("TS3 ServerQuery welcome banner ended unexpectedly")
+                return
+
+            line = raw_line.decode("utf-8", errors="replace").strip("\r\n")
+            if not line:
+                continue
+            if line.startswith("error "):
+                return
+            if line == "TS3":
+                continue
+            if "TeamSpeak 3 ServerQuery interface" in line:
+                return
+
+            logger.debug("TS3 ServerQuery welcome line: {}", line)
+
+    async def _read_response(self, reader: asyncio.StreamReader) -> list[str]:
+        lines: list[str] = []
+        while True:
+            try:
+                raw_line = await reader.readline()
+            except Exception as exc:
+                raise Ts3QueryError(f"ServerQuery 读取响应失败：{exc}") from exc
+
+            if not raw_line:
+                if lines:
+                    return lines
+                raise Ts3QueryError("ServerQuery 连接已关闭")
+
+            line = raw_line.decode("utf-8", errors="replace").strip("\r\n")
+            if not line:
+                continue
+
+            lines.append(line)
+            if line.startswith("error "):
+                return lines
+
+    def _parse_response(
+        self, lines: Sequence[str], action: str
+    ) -> list[dict[str, str]]:
+        if not lines:
+            return []
+
+        error_line = lines[-1]
+        if not error_line.startswith("error "):
+            raise Ts3QueryError(f"{action} 失败：响应格式异常，缺少 error 行")
+
+        error_info = self._parse_record(error_line.removeprefix("error "))
+        try:
+            error_id = int(error_info.get("id", "-1"))
+        except (TypeError, ValueError) as exc:
+            raise Ts3QueryError(
+                f"{action} 失败：响应格式异常，error id 无法解析"
+            ) from exc
+
+        if error_id != 0:
+            error_msg = error_info.get("msg", "unknown")
+            raise Ts3QueryError(f"{action} 失败：{error_msg} (id={error_id})")
+
+        if len(lines) == 1:
+            return []
+
+        data = "\n".join(lines[:-1]).strip()
+        if not data:
+            return []
+
+        records: list[dict[str, str]] = []
+        for raw_record in data.split("|"):
+            record = raw_record.strip()
+            if record:
+                records.append(self._parse_record(record))
+        return records
+
+    def _parse_record(self, payload: str) -> dict[str, str]:
+        record: dict[str, str] = {}
+        for token in payload.split(" "):
+            if not token:
+                continue
+            if "=" not in token:
+                record[token] = ""
+                continue
+            key, value = token.split("=", 1)
+            record[key] = self._unescape(value)
+        return record
+
+    def _escape(self, value: str) -> str:
+        return "".join(ESCAPE_MAP.get(char, char) for char in value)
+
+    def _unescape(self, value: str) -> str:
+        chars: list[str] = []
+        index = 0
+        while index < len(value):
+            if value[index] != "\\" or index + 1 >= len(value):
+                chars.append(value[index])
+                index += 1
+                continue
+
+            escaped = value[index : index + 2]
+            chars.append(UNESCAPE_MAP.get(escaped, escaped[1]))
+            index += 2
+
+        return "".join(chars)
+
+    def _safe_int(self, value: object, default: int) -> int:
+        try:
+            return int(value)
+        except (TypeError, ValueError):
+            return default

nonebot_plugin_ts3_tracker/runtime.py

@@ -0,0 +1,336 @@
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+
+import nonebot
+from nonebot import logger, require
+from nonebot.adapters.onebot.v11 import Bot
+
+require("nonebot_plugin_localstore")
+import nonebot_plugin_localstore as store
+
+from .config import Ts3TrackerSettings
+from .models import Ts3OnlineUser, Ts3ServerStatus
+from .query import Ts3QueryError
+from .service import Ts3TrackerService
+from .storage import SnapshotStore, TrackedClientSnapshot
+
+MessageSender = Callable[[str, str, str], Awaitable[bool]]
+NowFactory = Callable[[], datetime]
+
+
+@dataclass(slots=True)
+class NotificationDiff:
+    joined: list[TrackedClientSnapshot]
+    left: list[TrackedClientSnapshot]
+
+
+class Ts3TrackerRuntime:
+    def __init__(
+        self,
+        settings: Ts3TrackerSettings,
+        service: Ts3TrackerService,
+        *,
+        store_backend: SnapshotStore | None = None,
+        message_sender: MessageSender | None = None,
+        now_factory: NowFactory | None = None,
+    ) -> None:
+        self.settings = settings
+        self.service = service
+        self._store = store_backend or SnapshotStore(self._build_snapshot_file())
+        self._message_sender = message_sender or self._send_message
+        self._now_factory = now_factory or datetime.now
+        self._snapshot: dict[str, TrackedClientSnapshot] = {}
+        self._snapshot_lock = asyncio.Lock()
+        self._stop_event = asyncio.Event()
+        self._poll_task: asyncio.Task[None] | None = None
+        self.service._duration_provider = self.get_online_duration_seconds
+
+    async def startup(self) -> None:
+        self._stop_event.clear()
+        try:
+            self._snapshot = self._store.load()
+        except Exception as exc:
+            logger.error("failed to load ts3 snapshot store: {}", exc)
+            self._snapshot = {}
+
+        if not self.settings.notification_enabled:
+            logger.info("TS3 通知轮询已关闭。")
+            return
+
+        logger.info(
+            "TS3 通知轮询已启动，轮询间隔 {} 秒，通知群：{}，通知私聊：{}，群白名单模式：{}。",
+            self.settings.poll_interval_seconds,
+            ",".join(self.settings.get_effective_notify_groups()) or "-",
+            self.settings.notify_target_users or "-",
+            "开启" if self.settings.group_whitelist_enabled else "关闭",
+        )
+        await self.sync_once(notify=not self.settings.startup_silent)
+        self._ensure_poll_task()
+
+    async def shutdown(self) -> None:
+        self._stop_event.set()
+        if self._poll_task is not None:
+            self._poll_task.cancel()
+            try:
+                await self._poll_task
+            except asyncio.CancelledError:
+                pass
+            self._poll_task = None
+
+    async def sync_once(self, *, notify: bool) -> NotificationDiff:
+        missing_fields = self.service.get_missing_required_fields()
+        if missing_fields:
+            logger.warning(
+                "TS3 通知轮询跳过，配置不完整：{}",
+                "、".join(missing_fields),
+            )
+            return NotificationDiff(joined=[], left=[])
+
+        try:
+            status = await self.service.fetch_status()
+        except Ts3QueryError as exc:
+            logger.warning("TS3 轮询失败：{}", exc)
+            return NotificationDiff(joined=[], left=[])
+        except Exception as exc:  # pragma: no cover
+            logger.exception("TS3 轮询发生未预期错误：{}", exc)
+            return NotificationDiff(joined=[], left=[])
+
+        current = self._build_snapshot(status)
+        async with self._snapshot_lock:
+            diff = self._calculate_diff(self._snapshot, current)
+            self._snapshot = current
+            try:
+                self._store.save(self._snapshot)
+            except Exception as exc:
+                logger.error("保存 TS3 快照失败：{}", exc)
+
+        if notify:
+            await self._dispatch_notifications(status, diff)
+        elif diff.joined or diff.left:
+            logger.info(
+                "TS3 首次同步完成，不发送通知。进入：{}，离开：{}。",
+                "、".join(item.nickname for item in diff.joined) or "无",
+                "、".join(item.nickname for item in diff.left) or "无",
+            )
+
+        return diff
+
+    def _ensure_poll_task(self) -> None:
+        if self._poll_task is not None and not self._poll_task.done():
+            return
+        self._poll_task = asyncio.create_task(self._poll_loop())
+
+    async def _poll_loop(self) -> None:
+        while not self._stop_event.is_set():
+            try:
+                await self.sync_once(notify=True)
+            except asyncio.CancelledError:
+                raise
+            except Exception as exc:  # pragma: no cover
+                logger.error("TS3 轮询循环异常：{}", exc)
+
+            try:
+                await asyncio.wait_for(
+                    self._stop_event.wait(),
+                    timeout=self.settings.poll_interval_seconds,
+                )
+            except asyncio.TimeoutError:
+                continue
+
+    def _build_snapshot(
+        self, status: Ts3ServerStatus
+    ) -> dict[str, TrackedClientSnapshot]:
+        snapshots: dict[str, TrackedClientSnapshot] = {}
+        now_text = self._format_now()
+        for user in status.users:
+            key = self._user_key(user)
+            previous = self._snapshot.get(key)
+            snapshots[key] = TrackedClientSnapshot(
+                nickname=user.nickname,
+                unique_id=user.unique_id,
+                channel_id=user.channel_id,
+                channel_name=user.channel_name,
+                connected_duration_seconds=user.connected_duration_seconds,
+                away=user.away,
+                first_seen_at=(
+                    previous.first_seen_at if previous and previous.first_seen_at else now_text
+                ),
+            )
+        return snapshots
+
+    def _calculate_diff(
+        self,
+        previous: dict[str, TrackedClientSnapshot],
+        current: dict[str, TrackedClientSnapshot],
+    ) -> NotificationDiff:
+        joined = [current[key] for key in current.keys() - previous.keys()]
+        left = [previous[key] for key in previous.keys() - current.keys()]
+        joined.sort(key=lambda item: item.nickname.casefold())
+        left.sort(key=lambda item: item.nickname.casefold())
+        return NotificationDiff(joined=joined, left=left)
+
+    async def _dispatch_notifications(
+        self, status: Ts3ServerStatus, diff: NotificationDiff
+    ) -> None:
+        messages: list[str] = []
+        if diff.joined:
+            logger.info(
+                "{} 进入了服务器。",
+                "、".join(item.nickname for item in diff.joined),
+            )
+            messages.append(self._format_join_message(status, diff.joined))
+        if diff.left:
+            logger.info(
+                "{} 退出了服务器。",
+                "、".join(item.nickname for item in diff.left),
+            )
+            messages.append(self._format_leave_message(status, diff.left))
+        if not messages:
+            return
+
+        targets = [
+            ("group", target)
+            for target in self.settings.get_effective_notify_groups()
+        ]
+        targets.extend(
+            ("private", target)
+            for target in self.settings.parse_targets(self.settings.notify_target_users)
+        )
+        if not targets:
+            logger.warning("检测到 TS3 变化，但没有可用的通知目标。")
+            return
+
+        for message in messages:
+            for target_type, target in targets:
+                ok = await self._message_sender(target_type, target, message)
+                if not ok:
+                    logger.warning(
+                        "发送 TS3 通知失败，目标类型：{}，目标：{}。",
+                        target_type,
+                        target,
+                    )
+
+    def _format_join_message(
+        self, status: Ts3ServerStatus, snapshots: list[TrackedClientSnapshot]
+    ) -> str:
+        lines = [
+            "让我看看是谁还没上号 👀",
+        ]
+        for snapshot in snapshots:
+            lines.append(f"🧾 昵称：{snapshot.nickname}")
+            lines.append(f"🟢 上线时间：{snapshot.first_seen_at or self._format_now()}")
+            lines.append(f"📣 {snapshot.nickname} 进入了 TS 服务器")
+        lines.append(f"👥 当前在线人数：{status.online_count}")
+        lines.append(f"📜 在线列表：{self._format_online_list(status)}")
+        return "\n".join(lines)
+
+    def _format_leave_message(
+        self, status: Ts3ServerStatus, snapshots: list[TrackedClientSnapshot]
+    ) -> str:
+        lines = [
+            "📤 用户下线通知",
+        ]
+        for snapshot in snapshots:
+            duration_text = self._format_online_duration(snapshot)
+            lines.append(f"🧾 昵称：{snapshot.nickname}")
+            lines.append(f"🟢 上线时间：{snapshot.first_seen_at or self._format_now()}")
+            lines.append(f"🔴 下线时间：{self._format_now()}")
+            lines.append(f"⏱️ 在线时长：{duration_text}")
+        lines.append(f"👥 当前在线人数：{status.online_count}")
+        lines.append(f"📜 在线列表：{self._format_online_list(status)}")
+        return "\n".join(lines)
+
+    async def _send_message(self, target_type: str, target: str, message: str) -> bool:
+        bot = self._select_bot()
+        if bot is None:
+            logger.warning("没有可用的 OneBot V11 机器人，无法发送 TS3 主动通知。")
+            return False
+
+        try:
+            normalized_target = int(target) if target.isdigit() else target
+            if target_type == "group":
+                await bot.send_group_msg(group_id=normalized_target, message=message)
+            else:
+                await bot.send_private_msg(user_id=normalized_target, message=message)
+            return True
+        except Exception as exc:
+            logger.error("发送 TS3 主动{}消息失败：{}", target_type, exc)
+            return False
+
+    def _select_bot(self) -> Bot | None:
+        bots = nonebot.get_bots()
+        if self.settings.notify_bot_id:
+            bot = bots.get(self.settings.notify_bot_id)
+            if isinstance(bot, Bot):
+                return bot
+        for bot in bots.values():
+            if isinstance(bot, Bot):
+                return bot
+        return None
+
+    def _build_snapshot_file(self) -> Path:
+        if self.settings.data_dir:
+            return Path(self.settings.data_dir) / "snapshot.json"
+        return store.get_plugin_data_file("snapshot.json")
+
+    def _user_key(self, user: Ts3OnlineUser) -> str:
+        if user.unique_id:
+            return f"uid:{user.unique_id}"
+        if user.database_id:
+            return f"db:{user.database_id}"
+        if user.client_id:
+            return f"clid:{user.client_id}"
+        return f"name:{user.nickname}"
+
+    def _format_now(self) -> str:
+        return self._now_factory().strftime("%Y-%m-%d %H:%M:%S")
+
+    def _format_duration(self, seconds: int) -> str:
+        total = max(0, seconds)
+        hours, remainder = divmod(total, 3600)
+        minutes, secs = divmod(remainder, 60)
+        if hours:
+            return f"{hours}小时{minutes}分{secs}秒"
+        if minutes:
+            return f"{minutes}分{secs}秒"
+        return f"{secs}秒"
+
+    def _format_online_duration(self, snapshot: TrackedClientSnapshot) -> str:
+        if snapshot.first_seen_at:
+            try:
+                started_at = datetime.strptime(snapshot.first_seen_at, "%Y-%m-%d %H:%M:%S")
+            except ValueError:
+                started_at = None
+            else:
+                seconds = int((self._now_factory() - started_at).total_seconds())
+                return self._format_duration(seconds)
+        return self._format_duration(snapshot.connected_duration_seconds)
+
+    def _format_online_list(self, status: Ts3ServerStatus) -> str:
+        if not status.users:
+            return "暂无在线用户"
+        return ", ".join(user.nickname for user in status.users)
+
+    def get_online_duration_seconds(self, user: Ts3OnlineUser) -> int | None:
+        key = self._user_key(user)
+        snapshot = self._snapshot.get(key)
+        if snapshot is not None:
+            if snapshot.first_seen_at:
+                try:
+                    started_at = datetime.strptime(
+                        snapshot.first_seen_at, "%Y-%m-%d %H:%M:%S"
+                    )
+                except ValueError:
+                    pass
+                else:
+                    return max(0, int((self._now_factory() - started_at).total_seconds()))
+            if snapshot.connected_duration_seconds > 0:
+                return snapshot.connected_duration_seconds
+        if user.connected_duration_seconds > 0:
+            return user.connected_duration_seconds
+        return None

nonebot_plugin_ts3_tracker/service.py

@@ -0,0 +1,145 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from datetime import datetime
+
+from nonebot import logger
+
+from .config import Ts3TrackerSettings
+from .models import Ts3OnlineUser, Ts3ServerStatus
+from .query import Ts3QueryClient, Ts3QueryError
+
+
+QueryClientFactory = Callable[[], Ts3QueryClient]
+DurationProvider = Callable[[Ts3OnlineUser], int | None]
+
+
+class Ts3TrackerService:
+    def __init__(
+        self,
+        settings: Ts3TrackerSettings,
+        client_factory: QueryClientFactory | None = None,
+        duration_provider: DurationProvider | None = None,
+    ) -> None:
+        self.settings = settings
+        self._client_factory = client_factory
+        self._duration_provider = duration_provider
+
+    async def build_server_message(self) -> str:
+        missing_fields = self.get_missing_required_fields()
+        if missing_fields:
+            return "TS3 配置不完整，请先填写：" + "、".join(missing_fields)
+
+        try:
+            status = await self.fetch_status()
+        except Ts3QueryError as exc:
+            logger.warning("TS3 query failed: {}", exc)
+            return f"TS3 查询失败：{exc}"
+        except Exception as exc:  # pragma: no cover - defensive guard
+            logger.exception("Unexpected TS3 query error: {}", exc)
+            return "TS3 查询失败：发生了未预期错误，请查看 NoneBot 日志。"
+
+        return self.format_server_status(status)
+
+    async def fetch_status(self) -> Ts3ServerStatus:
+        return await self._build_client().fetch_status()
+
+    def get_missing_required_fields(self) -> list[str]:
+        missing: list[str] = []
+        if not self.settings.server_host:
+            missing.append("服务器地址")
+        if self.settings.server_port <= 0:
+            missing.append("服务器端口")
+        if not self.settings.serverquery_username:
+            missing.append("ServerQuery 账号")
+        if not self.settings.serverquery_password:
+            missing.append("ServerQuery 密码")
+        return missing
+
+    def format_server_status(self, status: Ts3ServerStatus) -> str:
+        lines = [
+            f"服务器地址：{status.server_host}:{status.server_port}",
+            f"服务器端口：{status.server_port}",
+            f"服务器名称：{status.server_name or '-'}",
+            "服务器频道：",
+        ]
+
+        for channel_name, users in self.group_users_by_channel(status):
+            display_name = channel_name or "未命名频道"
+            if users:
+                lines.append(f"{display_name}: {', '.join(users)}")
+            else:
+                lines.append(display_name)
+
+        return "\n".join(lines)
+
+    def group_users_by_channel(
+        self, status: Ts3ServerStatus
+    ) -> list[tuple[str, list[str]]]:
+        grouped: dict[str, dict[str, object]] = {}
+        for channel_id, channel_name in status.channels:
+            grouped.setdefault(channel_id, {"name": channel_name, "users": []})
+
+        for user in status.users:
+            channel_id = user.channel_id or "__unknown__"
+            channel_entry = grouped.setdefault(
+                channel_id,
+                {"name": user.channel_name or "未命名频道", "users": []},
+            )
+            users = channel_entry["users"]
+            assert isinstance(users, list)
+            users.append(self._format_user_display(user))
+
+        ordered_groups: list[tuple[str, list[str]]] = []
+        for channel_id, _ in status.channels:
+            channel_entry = grouped.pop(channel_id, None)
+            if channel_entry is None:
+                continue
+            ordered_groups.append(
+                (str(channel_entry["name"]), list(channel_entry["users"]))
+            )
+
+        for channel_entry in grouped.values():
+            ordered_groups.append(
+                (str(channel_entry["name"]), list(channel_entry["users"]))
+            )
+
+        return ordered_groups
+
+    def _build_client(self) -> Ts3QueryClient:
+        if self._client_factory is not None:
+            return self._client_factory()
+
+        return Ts3QueryClient(
+            host=self.settings.server_host,
+            server_port=self.settings.server_port,
+            query_port=self.settings.serverquery_port,
+            username=self.settings.serverquery_username,
+            password=self.settings.serverquery_password,
+            timeout=self.settings.query_timeout_seconds,
+        )
+
+    def _format_user_display(self, user: Ts3OnlineUser) -> str:
+        duration = self._get_user_duration_seconds(user)
+        if duration is None:
+            return user.nickname
+        return f"{user.nickname}({self._format_duration(duration)})"
+
+    def _get_user_duration_seconds(self, user: Ts3OnlineUser) -> int | None:
+        if self._duration_provider is not None:
+            duration = self._duration_provider(user)
+            if duration is not None:
+                return max(0, duration)
+        if user.connected_duration_seconds > 0:
+            return user.connected_duration_seconds
+        return None
+
+    def _format_duration(self, seconds: int) -> str:
+        total = max(0, seconds)
+        hours, remainder = divmod(total, 3600)
+        minutes, secs = divmod(remainder, 60)
+        if hours:
+            return f"{hours}小时{minutes}分{secs}秒"
+        if minutes:
+            return f"{minutes}分{secs}秒"
+        return f"{secs}秒"

nonebot_plugin_ts3_tracker/storage.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+
+@dataclass(slots=True)
+class TrackedClientSnapshot:
+    nickname: str
+    unique_id: str
+    channel_id: str
+    channel_name: str
+    connected_duration_seconds: int
+    away: bool
+    first_seen_at: str = ""
+
+
+class SnapshotStore:
+    def __init__(self, data_file: Path) -> None:
+        self._data_file = data_file
+
+    def load(self) -> dict[str, TrackedClientSnapshot]:
+        if not self._data_file.exists():
+            return {}
+
+        raw = json.loads(self._data_file.read_text(encoding="utf-8"))
+        if not isinstance(raw, dict):
+            raise ValueError("snapshot file root node must be an object")
+
+        snapshots: dict[str, TrackedClientSnapshot] = {}
+        for key, value in raw.items():
+            if not isinstance(key, str) or not isinstance(value, dict):
+                continue
+            snapshots[key] = TrackedClientSnapshot(**value)
+        return snapshots
+
+    def save(self, snapshots: dict[str, TrackedClientSnapshot]) -> None:
+        self._data_file.parent.mkdir(parents=True, exist_ok=True)
+        payload = {
+            key: asdict(snapshot)
+            for key, snapshot in sorted(snapshots.items(), key=lambda item: item[0])
+        }
+        self._data_file.write_text(
+            json.dumps(payload, ensure_ascii=False, indent=2, sort_keys=True),
+            encoding="utf-8",
+        )

nonebot_plugin_ts3_tracker-1.0.0.dist-info/METADATA

@@ -0,0 +1,235 @@
+Metadata-Version: 2.4
+Name: nonebot-plugin-ts3-tracker
+Version: 1.0.0
+Summary: TeamSpeak 3 query and join/leave notification plugin for NoneBot2
+Keywords: nonebot,nonebot2,ts3,teamspeak3,serverquery,onebot
+Author: neri
+License-Expression: MIT
+Requires-Dist: nonebot2>=2.4.4,<3.0.0
+Requires-Dist: nonebot-adapter-onebot>=2.4.0,<3.0.0
+Requires-Dist: nonebot-plugin-localstore>=0.7.4,<1.0.0
+Requires-Dist: pydantic>=2.0.0,<3.0.0
+Requires-Python: >=3.10, <4.0
+Project-URL: Homepage, https://github.com/moeneri/nonebot-plugin-ts3-tracker
+Project-URL: Repository, https://github.com/moeneri/nonebot-plugin-ts3-tracker
+Description-Content-Type: text/markdown
+
+# nonebot-plugin-ts3-tracker
+
+基于 NoneBot2 的 TeamSpeak 3 查询与进服/退服通知插件。
+
+本插件提供以下查询命令：
+
+- `上号`
+- `ts`
+- `tsinfo`
+
+并补充了适合长期运行的能力：
+
+- TS3 进服通知
+- TS3 退服通知
+- 5 秒轮询监控
+- 在线快照持久化
+- 重启后静默同步，避免历史误报
+- 频道内玩家在线时长显示
+- 群聊 / 私聊主动推送
+- 群白名单模式
+- 中文日志输出
+
+## 安装
+
+1. 安装插件：
+   `nb plugin install nonebot-plugin-ts3-tracker`
+2. 确保已安装本插件依赖的 `nonebot-plugin-localstore`
+3. 在机器人项目中加载插件 `nonebot_plugin_ts3_tracker`
+4. 配置环境变量
+
+## 基础配置
+
+插件使用以下环境变量：
+
+```env
+TS3_TRACKER__SERVER_HOST=127.0.0.1
+TS3_TRACKER__SERVER_PORT=9987
+TS3_TRACKER__SERVERQUERY_PORT=10011
+TS3_TRACKER__SERVERQUERY_USERNAME=your-serverquery-username
+TS3_TRACKER__SERVERQUERY_PASSWORD=your-password
+TS3_TRACKER__DEBUG=false
+```
+
+## 配置
+
+```env
+HOST=127.0.0.1
+PORT=8080
+
+TS3_TRACKER__SERVER_HOST=127.0.0.1
+TS3_TRACKER__SERVER_PORT=9987
+TS3_TRACKER__SERVERQUERY_PORT=10011
+TS3_TRACKER__SERVERQUERY_USERNAME=your-serverquery-username
+TS3_TRACKER__SERVERQUERY_PASSWORD=your-password
+TS3_TRACKER__DEBUG=false
+TS3_TRACKER__COMMAND_PRIORITY=10
+TS3_TRACKER__QUERY_TIMEOUT_SECONDS=10
+
+TS3_TRACKER__NOTIFICATION_ENABLED=true
+TS3_TRACKER__NOTIFY_TARGET_GROUPS=123456789
+TS3_TRACKER__NOTIFY_TARGET_USERS=
+TS3_TRACKER__NOTIFY_BOT_ID=
+
+TS3_TRACKER__GROUP_WHITELIST_ENABLED=false
+TS3_TRACKER__GROUP_WHITELIST_GROUPS=
+
+TS3_TRACKER__POLL_INTERVAL_SECONDS=5
+TS3_TRACKER__STARTUP_SILENT=true
+TS3_TRACKER__DATA_DIR=data/ts3_tracker
+```
+
+配置说明：
+
+- `TS3_TRACKER__SERVER_HOST`：TS3 服务器地址
+- `TS3_TRACKER__SERVER_PORT`：TS3 语音端口，通常为 `9987`
+- `TS3_TRACKER__SERVERQUERY_PORT`：TS3 ServerQuery 端口，通常为 `10011`
+- `TS3_TRACKER__SERVERQUERY_USERNAME`：ServerQuery 用户名
+- `TS3_TRACKER__SERVERQUERY_PASSWORD`：ServerQuery 密码
+- `TS3_TRACKER__DEBUG`：是否输出调试日志
+- `TS3_TRACKER__COMMAND_PRIORITY`：命令优先级
+- `TS3_TRACKER__QUERY_TIMEOUT_SECONDS`：单次查询超时秒数
+- `TS3_TRACKER__NOTIFICATION_ENABLED`：是否启用进服/退服通知
+- `TS3_TRACKER__NOTIFY_TARGET_GROUPS`：接收通知的群号，支持逗号、分号、换行分隔
+- `TS3_TRACKER__NOTIFY_TARGET_USERS`：接收通知的私聊 QQ，支持逗号、分号、换行分隔
+- `TS3_TRACKER__NOTIFY_BOT_ID`：指定发送主动通知的 OneBot v11 Bot ID
+- `TS3_TRACKER__GROUP_WHITELIST_ENABLED`：是否开启群白名单模式
+- `TS3_TRACKER__GROUP_WHITELIST_GROUPS`：允许使用群命令查询，且允许接收群通知的白名单群号
+- `TS3_TRACKER__POLL_INTERVAL_SECONDS`：轮询间隔，默认 `5`
+- `TS3_TRACKER__STARTUP_SILENT`：启动时只同步快照，不立刻发送历史在线通知
+- `TS3_TRACKER__DATA_DIR`：自定义快照持久化目录；不填写时使用 `nonebot-plugin-localstore` 的插件数据目录
+
+## 群白名单模式
+
+默认情况下：
+
+- 所有群聊都可以使用 `上号`、`ts`、`tsinfo`
+- 所有私聊都可以使用查询命令
+- 通知只会发给 `TS3_TRACKER__NOTIFY_TARGET_GROUPS` 和 `TS3_TRACKER__NOTIFY_TARGET_USERS`
+
+当开启白名单模式后：
+
+```env
+TS3_TRACKER__GROUP_WHITELIST_ENABLED=true
+TS3_TRACKER__GROUP_WHITELIST_GROUPS=123456789
+```
+
+效果如下：
+
+- 只有白名单群可以使用群聊查询命令
+- 私聊仍然可以查询
+- 群通知只会发到白名单内，且同时存在于 `TS3_TRACKER__NOTIFY_TARGET_GROUPS` 的群
+
+## 命令
+
+群聊或私聊发送以下任一命令：
+
+```text
+上号
+ts
+tsinfo
+```
+
+## 查询返回示例
+
+```text
+服务器地址：127.0.0.1:9987
+服务器端口：9987
+服务器名称：迷你世界高手大会
+服务器频道：
+APEX: neri(20秒)
+原神
+守望先锋-归西
+穿越火线
+永雏塔菲
+高能英雄
+三国杀
+迷你世界
+王者荣耀
+三角洲行动
+```
+
+## 通知示例
+
+进服通知：
+
+```text
+让我看看是谁还没上号 👀
+🧾 昵称：neri
+🟢 上线时间：2026-03-16 00:33:19
+📣 neri 进入了 TS 服务器
+👥 当前在线人数：3
+📜 在线列表：neri, koishi
+```
+
+退服通知：
+
+```text
+📤 用户下线通知
+🧾 昵称：neri
+🟢 上线时间：2026-03-16 00:32:51
+🔴 下线时间：2026-03-16 01:31:37
+⏱️ 在线时长：58分46秒
+👥 当前在线人数：2
+📜 在线列表：KirA, Cirno
+```
+
+## 日志示例
+
+```text
+群号 123456789 查询了服务器信息。
+neri 进入了服务器。
+neri 退出了服务器。
+```
+
+## 数据持久化
+
+插件当前不是通过数据库持久化。
+
+它使用本地 JSON 快照文件记录在线状态。
+
+默认情况下，文件通过 `nonebot-plugin-localstore` 保存到插件专属数据目录。
+
+如果你手动设置了 `TS3_TRACKER__DATA_DIR`，则会改为保存到你指定目录下的：
+
+```text
+<TS3_TRACKER__DATA_DIR>/snapshot.json
+```
+
+快照中主要保存：
+
+- 用户唯一标识
+- 所在频道
+- 首次上线时间
+- 已连接时长
+- 离开检测所需的对比状态
+
+## 验证
+
+运行单元测试：
+
+```bash
+pytest
+```
+
+实时验证 TS3 查询：
+
+```bash
+python scripts/verify_live.py
+```
+
+## NoneBot2 规范确认
+
+已按本地 `nonebot2-master` 文档核对以下要求：
+
+- 使用 `PluginMetadata` 声明插件元信息
+- 明确 `config=Config`
+- 明确 `supported_adapters={"nonebot.adapters.onebot.v11"}`
+- 使用标准 `pyproject.toml` 打包结构
+- 根目录包含 `README.md`、`LICENSE`、测试目录与验证脚本

nonebot_plugin_ts3_tracker-1.0.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+nonebot_plugin_ts3_tracker/__init__.py,sha256=ygX0v3X6RO_9Wr7LkDvmmDE9D3JM4LOZPfVKrX9jUK8,2615
+nonebot_plugin_ts3_tracker/config.py,sha256=QKR5XR2pQMs2o4Qh9jCApMHUKi0Jo_KvSv22EUDPKPw,2347
+nonebot_plugin_ts3_tracker/models.py,sha256=6PoEZEQ55TAhq282rBR9YzhPKSkgzug5eWDmtBF2ERs,505
+nonebot_plugin_ts3_tracker/query.py,sha256=-k20ATg1PRgKuI1NbfjELiQMOCZHINKOP3xDySA754M,8791
+nonebot_plugin_ts3_tracker/runtime.py,sha256=lS66-GYEf11is6qQh7qLRckUqsErZYGPpyxczRj8KM0,13100
+nonebot_plugin_ts3_tracker/service.py,sha256=axWCdt1b3igvmkXq1LlszIub8wXZF6PEk3kZrWNL2zI,5419
+nonebot_plugin_ts3_tracker/storage.py,sha256=6tSz4K21vhB8HR_xhh6tl7-M_lLcemrnwQiFwMdgfb0,1461
+nonebot_plugin_ts3_tracker-1.0.0.dist-info/WHEEL,sha256=iHtWm8nRfs0VRdCYVXocAWFW8ppjHL-uTJkAdZJKOBM,80
+nonebot_plugin_ts3_tracker-1.0.0.dist-info/METADATA,sha256=8SCXjcffkdTpI4C32cpR4dh_GHdyZS4GfZqPLlFs_LY,6188
+nonebot_plugin_ts3_tracker-1.0.0.dist-info/RECORD,,

nonebot_plugin_ts3_tracker-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.9.30
+Root-Is-Purelib: true
+Tag: py3-none-any