nonebot-plugin-ts3-tracker 1.0.0__tar.gz

nonebot_plugin_ts3_tracker-1.0.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,219 @@
+# 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/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-1.0.0/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-1.0.0/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]