nonebot-plugin-ba-gamekee 0.2.0__py3-none-any.whl

nonebot_plugin_ba_gamekee/__init__.py

@@ -0,0 +1,57 @@
+from nonebot import get_driver, require
+from nonebot.plugin import PluginMetadata, inherit_supported_adapters
+
+require("nonebot_plugin_alconna")
+require("nonebot_plugin_uninfo")
+require("nonebot_plugin_localstore")
+require("nonebot_plugin_apscheduler")
+
+from nonebot_plugin_apscheduler import scheduler
+
+from . import bot as bot
+from .bot.dependencies import (
+    get_current_guide_cache,
+    get_current_guide_client,
+    refresh_current_guides,
+    startup_current_guides,
+)
+from .config import Config, plugin_config
+
+__plugin_meta__ = PluginMetadata(
+    name="BA GameKee",
+    description="蔚蓝档案 GameKee Wiki 攻略查询",
+    usage="/ba活动 国际服\n/ba卡池 国服",
+    type="application",  # application: 功能性插件 | library: 库插件
+    homepage="https://github.com/Misty02600/nonebot-plugin-ba-gamekee",
+    config=Config,
+    supported_adapters=inherit_supported_adapters("nonebot_plugin_alconna"),
+    extra={"author": "Misty02600 <xiao02600@gmail.com>"},
+)
+
+
+driver = get_driver()
+
+
+@driver.on_startup
+async def _sync_current_guides_on_startup() -> None:
+    await startup_current_guides(
+        client=get_current_guide_client(),
+        cache=get_current_guide_cache(),
+    )
+
+
+async def _refresh_current_guides_job() -> None:
+    await refresh_current_guides(
+        client=get_current_guide_client(),
+        cache=get_current_guide_cache(),
+        silent=True,
+    )
+
+
+scheduler.add_job(
+    _refresh_current_guides_job,
+    "interval",
+    minutes=plugin_config.ba_gamekee_refresh_interval_minutes,
+    id="ba_gamekee_refresh_current_guides",
+    replace_existing=True,
+)

nonebot_plugin_ba_gamekee/bot/__init__.py

@@ -0,0 +1,3 @@
+from .handlers.guides import ba_gamekee_matcher
+
+__all__ = ["ba_gamekee_matcher"]

nonebot_plugin_ba_gamekee/bot/article_delivery.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+from pathlib import Path
+
+from nonebot.adapters import Bot, Event
+from nonebot_plugin_alconna import CustomNode, UniMessage
+from nonebot_plugin_uninfo import get_interface
+
+DEFAULT_FORWARD_SENDER_NAME = "BA GameKee"
+
+
+async def send_article_pages(
+    *,
+    bot: Bot,
+    event: Event,
+    page_paths: Sequence[Path],
+) -> None:
+    """按平台能力发送文章分页图片。
+
+    Args:
+        bot: 当前响应 bot。
+        event: 当前事件。
+        page_paths: 已渲染完成的分页图片路径。
+    """
+    if not page_paths:
+        raise ValueError("article pages is empty")
+
+    if len(page_paths) == 1:
+        await UniMessage.image(path=page_paths[0], name=page_paths[0].name).send(
+            target=event,
+            bot=bot,
+            fallback=False,
+        )
+        return
+
+    await _send_forward_message(bot=bot, event=event, page_paths=page_paths)
+
+
+async def _send_forward_message(
+    *,
+    bot: Bot,
+    event: Event,
+    page_paths: Sequence[Path],
+) -> None:
+    sender_name = await _resolve_forward_sender_name(bot)
+    nodes = [
+        CustomNode(
+            uid=str(bot.self_id),
+            name=sender_name,
+            content=UniMessage.image(path=path, name=path.name),
+        )
+        for path in page_paths
+    ]
+    await UniMessage.reference(*nodes).send(target=event, bot=bot)
+
+
+async def _resolve_forward_sender_name(bot: Bot) -> str:
+    interface = get_interface(bot)
+    if interface is None:
+        return DEFAULT_FORWARD_SENDER_NAME
+
+    try:
+        user = await interface.get_user(str(bot.self_id))
+    except Exception:
+        return DEFAULT_FORWARD_SENDER_NAME
+
+    if user is None or not user.name:
+        return DEFAULT_FORWARD_SENDER_NAME
+    return user.name

nonebot_plugin_ba_gamekee/bot/dependencies.py

@@ -0,0 +1,134 @@
+from __future__ import annotations
+
+from nonebot import logger
+
+from ..core.models import GuideEntry
+from ..infra.article_renderer import ArticleRenderer
+from ..infra.current_guides_cache import CurrentGuideCache
+from ..infra.gamekee import GameKeeClient
+from ..infra.screenshot_cache import ScreenshotCache
+
+_current_guide_client = GameKeeClient()
+_current_guide_cache = CurrentGuideCache()
+_article_renderer = ArticleRenderer()
+_screenshot_cache = ScreenshotCache()
+_current_guide_entries: dict[str, GuideEntry] = {}
+
+
+def get_current_guide_client() -> GameKeeClient:
+    """获取共享的当前攻略入口数据源。
+
+    Returns:
+        GameKee 当前攻略入口客户端。
+    """
+    return _current_guide_client
+
+
+def get_current_guide_cache() -> CurrentGuideCache:
+    """获取共享的当前攻略入口缓存。
+
+    Returns:
+        当前攻略入口缓存实例。
+    """
+    return _current_guide_cache
+
+
+def get_current_guide_entries() -> dict[str, GuideEntry]:
+    """获取当前攻略入口内存快照。
+
+    Returns:
+        当前攻略入口内存快照。
+    """
+    return _current_guide_entries
+
+
+def get_article_renderer() -> ArticleRenderer:
+    """获取共享的文章渲染器。
+
+    Returns:
+        完整文章截图渲染器。
+    """
+    return _article_renderer
+
+
+def get_screenshot_cache() -> ScreenshotCache:
+    """获取共享的文章截图缓存。
+
+    Returns:
+        完整文章截图缓存实例。
+    """
+    return _screenshot_cache
+
+
+def load_current_guides_cache(*, cache: CurrentGuideCache) -> dict[str, GuideEntry]:
+    """从本地缓存加载最近一次成功同步的攻略入口快照。
+
+    Args:
+        cache: 当前攻略入口缓存。
+
+    Returns:
+        当前攻略入口内存快照。
+    """
+    global _current_guide_entries
+    _current_guide_entries = cache.load()
+    return _current_guide_entries
+
+
+async def refresh_current_guides(
+    *,
+    client: GameKeeClient,
+    cache: CurrentGuideCache,
+    silent: bool = False,
+) -> dict[str, GuideEntry]:
+    """从 GameKee 刷新内存中的攻略入口快照。
+
+    Args:
+        client: 当前攻略入口数据源。
+        cache: 当前攻略入口缓存。
+        silent: 为 `True` 时，刷新失败会保留旧缓存并记录 warning，
+            而不是继续抛出异常。
+
+    Returns:
+        当前攻略入口内存快照。
+    """
+    global _current_guide_entries
+    try:
+        entries = await client.fetch_current_guide_entries()
+        if not entries:
+            raise RuntimeError("GameKee 当前入口为空")
+        _current_guide_entries = entries
+        cache.save(_current_guide_entries)
+        logger.info(f"BA GameKee 当前入口已同步：{len(entries)} 条")
+    except Exception as e:
+        if silent:
+            logger.warning(f"同步 BA GameKee 当前入口失败，将使用旧缓存：{e}")
+            return _current_guide_entries
+        raise
+    return _current_guide_entries
+
+
+async def startup_current_guides(
+    *,
+    client: GameKeeClient,
+    cache: CurrentGuideCache,
+) -> None:
+    """启动时先加载本地缓存，再尝试静默刷新远端数据。
+
+    Args:
+        client: 当前攻略入口数据源。
+        cache: 当前攻略入口缓存。
+    """
+    load_current_guides_cache(cache=cache)
+    await refresh_current_guides(client=client, cache=cache, silent=True)
+
+
+__all__ = [
+    "get_article_renderer",
+    "get_current_guide_cache",
+    "get_current_guide_client",
+    "get_current_guide_entries",
+    "get_screenshot_cache",
+    "load_current_guides_cache",
+    "refresh_current_guides",
+    "startup_current_guides",
+]

nonebot_plugin_ba_gamekee/bot/handlers/__init__.py

@@ -0,0 +1,3 @@
+from .guides import ba_gamekee_matcher
+
+__all__ = ["ba_gamekee_matcher"]

nonebot_plugin_ba_gamekee/bot/handlers/guides.py

@@ -0,0 +1,173 @@
+from __future__ import annotations
+
+from arclet.alconna import Alconna, Args, Arparma, CommandMeta, Empty, Subcommand
+from nonebot import logger
+from nonebot.adapters import Bot, Event
+from nonebot_plugin_alconna import AlconnaMatches, Match, UniMessage, on_alconna
+
+from ...core.guide_kinds import GuideKindKey, guide_kind_by_key
+from ...core.servers import server_for, supported_server_names
+from ..article_delivery import send_article_pages
+from ..dependencies import (
+    get_article_renderer,
+    get_current_guide_client,
+    get_current_guide_entries,
+    get_screenshot_cache,
+)
+
+ba_gamekee_command = Alconna(
+    "ba",
+    Subcommand("活动", Args["server?", str]),
+    Subcommand("卡池", Args["server?", str]),
+    meta=CommandMeta(description="BA GameKee 查询", compact=True),
+)
+
+ba_gamekee_matcher = on_alconna(
+    ba_gamekee_command,
+    use_cmd_start=True,
+    block=True,
+    priority=10,
+)
+
+
+@ba_gamekee_matcher.handle()
+async def handle_guide_command(
+    bot: Bot,
+    event: Event,
+    result: Arparma = AlconnaMatches(),
+) -> None:
+    """处理 BA GameKee 当前攻略类子命令。"""
+    if result.query("活动", Empty) is not Empty:
+        await handle_activity(
+            bot=bot,
+            event=event,
+            server=_server_match(result, "活动"),
+        )
+        return
+
+    if result.query("卡池", Empty) is not Empty:
+        await handle_gacha_review(
+            bot=bot,
+            event=event,
+            server=_server_match(result, "卡池"),
+        )
+
+
+async def handle_activity(
+    bot: Bot,
+    event: Event,
+    server: Match[str | None],
+) -> None:
+    """处理 `ba 活动` 命令。
+
+    Args:
+        server: Alconna 解析出的服务器参数。
+    """
+    await _handle_current_guide(
+        bot=bot,
+        event=event,
+        server=server,
+        kind_key="activity",
+    )
+
+
+async def handle_gacha_review(
+    bot: Bot,
+    event: Event,
+    server: Match[str | None],
+) -> None:
+    """处理 `ba 卡池` 命令。
+
+    Args:
+        server: Alconna 解析出的服务器参数。
+    """
+    await _handle_current_guide(
+        bot=bot,
+        event=event,
+        server=server,
+        kind_key="gacha_review",
+    )
+
+
+def _server_match(result: Arparma, subcommand: str) -> Match[str | None]:
+    server = result.query(f"{subcommand}.args.server", Empty)
+    return Match(None, False) if server is Empty else Match(str(server), True)
+
+
+async def _handle_current_guide(
+    *,
+    bot: Bot,
+    event: Event,
+    server: Match[str | None],
+    kind_key: GuideKindKey,
+) -> None:
+    kind = guide_kind_by_key(kind_key)
+    if not server.available or server.result is None:
+        await UniMessage.text(
+            f"请提供服务器，例如：/ba{kind.command_name} 国际服\n"
+            f"支持：{supported_server_names()}"
+        ).finish()
+
+    current_server = server_for(server.result)
+    if current_server is None:
+        await UniMessage.text(
+            f"当前仅支持这些服务器：{supported_server_names()}"
+        ).finish()
+
+    entries = get_current_guide_entries()
+    if not entries:
+        await UniMessage.text("BA GameKee 当前入口尚未同步成功，请稍后再试。").finish()
+
+    entry_name = kind.entry_name_for(current_server)
+    entry = (
+        entries.get(entry_name)
+        if entry_name is not None
+        else next(
+            (
+                entry
+                for entry in entries.values()
+                if kind.matches_entry(entry, current_server)
+            ),
+            None,
+        )
+    )
+    if entry:
+        if entry.content_id is None:
+            await UniMessage.text("图片发送失败").finish()
+
+        screenshot_cache = get_screenshot_cache()
+        cached_pages = screenshot_cache.load(entry.content_id)
+        if cached_pages is None:
+            client = get_current_guide_client()
+            renderer = get_article_renderer()
+            try:
+                article = await client.fetch_article_detail(entry.content_id)
+                rendered = await renderer.render(article)
+                try:
+                    cached_pages = screenshot_cache.save(
+                        article=article,
+                        page_paths=rendered.page_paths,
+                    )
+                finally:
+                    rendered.cleanup()
+            except Exception:
+                logger.exception(f"渲染 BA GameKee {kind.display_name}失败")
+                await UniMessage.text("图片发送失败").finish()
+
+        assert cached_pages is not None
+        try:
+            await send_article_pages(
+                bot=bot,
+                event=event,
+                page_paths=cached_pages.page_paths,
+            )
+        except Exception:
+            logger.exception(f"发送 BA GameKee {kind.display_name}图片失败")
+            await UniMessage.text("图片发送失败").finish()
+        return
+
+    expected = entry_name or f"{current_server}{kind.display_name}"
+    await UniMessage.text(
+        f"当前未找到对应{kind.display_name}入口：{expected}\n"
+        "请稍后再试，或等待 BA GameKee 首页入口更新。"
+    ).finish()

nonebot_plugin_ba_gamekee/config.py

@@ -0,0 +1,13 @@
+from nonebot import get_plugin_config
+from pydantic import BaseModel, Field
+
+
+class Config(BaseModel):
+    ba_gamekee_refresh_interval_minutes: int = Field(
+        default=10,
+        ge=1,
+        description="后台刷新当前攻略入口缓存的间隔，单位为分钟。",
+    )
+
+
+plugin_config: Config = get_plugin_config(Config)

nonebot_plugin_ba_gamekee/core/__init__.py

@@ -0,0 +1,17 @@
+from .guide_kinds import (
+    GuideKind,
+    GuideKindKey,
+    guide_kind_by_key,
+)
+from .models import GuideEntry
+from .servers import ServerName, server_for, supported_server_names
+
+__all__ = [
+    "GuideEntry",
+    "GuideKind",
+    "GuideKindKey",
+    "ServerName",
+    "guide_kind_by_key",
+    "server_for",
+    "supported_server_names",
+]

nonebot_plugin_ba_gamekee/core/guide_kinds.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+from .models import GuideEntry
+from .servers import ServerName
+
+GuideKindKey = Literal["activity", "gacha_review", "raid", "grand_assault"]
+
+
+@dataclass(frozen=True, slots=True)
+class GuideKind:
+    key: GuideKindKey
+    display_name: str
+    command_name: str
+    entry_name_template: str | None = None
+    required_keywords: tuple[str, ...] = ()
+
+    def entry_name_for(self, server: ServerName) -> str | None:
+        """生成指定服务器对应的 GameKee 入口名。
+
+        Args:
+            server: 已归一化的服务器显示名。
+
+        Returns:
+            使用固定命名规则时返回精确入口名。
+            需要关键词匹配时返回 `None`。
+        """
+        if self.entry_name_template is None:
+            return None
+        return self.entry_name_template.format(server=server)
+
+    def matches_entry(self, entry: GuideEntry, server: ServerName) -> bool:
+        """判断缓存入口是否属于当前攻略类型。
+
+        Args:
+            entry: 已解析的 GameKee 入口。
+            server: 已归一化的服务器显示名。
+
+        Returns:
+            入口匹配指定服务器和攻略类型时返回 `True`。
+        """
+        entry_name = self.entry_name_for(server)
+        if entry_name is not None:
+            return entry.name == entry_name
+        return server in entry.name and all(
+            keyword in entry.name for keyword in self.required_keywords
+        )
+
+
+_GUIDE_KINDS: tuple[GuideKind, ...] = (
+    GuideKind(
+        key="activity",
+        display_name="活动攻略",
+        command_name="活动",
+        entry_name_template="{server}活动攻略",
+    ),
+    GuideKind(
+        key="gacha_review",
+        display_name="卡池评测",
+        command_name="卡池",
+        entry_name_template="{server}当期卡池评测",
+    ),
+    GuideKind(
+        key="raid",
+        display_name="总力战",
+        command_name="总力",
+        required_keywords=("总力战",),
+    ),
+    GuideKind(
+        key="grand_assault",
+        display_name="大决战",
+        command_name="大决战",
+        required_keywords=("大决战",),
+    ),
+)
+
+
+_GUIDE_KIND_BY_KEY = {kind.key: kind for kind in _GUIDE_KINDS}
+
+
+def guide_kind_by_key(key: GuideKindKey) -> GuideKind:
+    """根据稳定的内部 key 获取攻略类型描述。
+
+    Args:
+        key: 内部攻略类型 key。
+
+    Returns:
+        对应的攻略类型描述。
+    """
+    return _GUIDE_KIND_BY_KEY[key]

nonebot_plugin_ba_gamekee/core/models.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from typing import Any
+
+
+@dataclass(slots=True, frozen=True)
+class GuideEntry:
+    """可直接回复给用户的攻略入口。"""
+
+    name: str
+    url: str
+    content_id: int | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        """转换为缓存文件可序列化的字典。
+
+        Returns:
+            当前攻略入口的字典表示。
+        """
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "GuideEntry":
+        """从缓存文件中的字典恢复攻略入口。
+
+        Args:
+            data: 缓存文件中的单条攻略入口数据。
+
+        Returns:
+            当前攻略入口对象。
+        """
+        return cls(
+            name=str(data["name"]),
+            url=str(data["url"]),
+            content_id=_optional_int(data.get("content_id")),
+        )
+
+
+@dataclass(slots=True, frozen=True)
+class GuideArticleDetail:
+    """可用于完整渲染的 GameKee 文章详情。"""
+
+    content_id: int
+    title: str
+    url: str
+    content_json: str
+    updated_at: int | None = None
+    author: str | None = None
+    view_count: int | None = None
+    like_count: int | None = None
+
+
+def _optional_int(value: Any) -> int | None:
+    """尽量把可空字段转换为整数。"""
+    if value in (None, ""):
+        return None
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return None

nonebot_plugin_ba_gamekee/core/servers.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from typing import Literal
+
+ServerName = Literal["日服", "国际服", "国服"]
+
+
+# 用户命令只接受这些显示名；不维护别名和 GameKee 内部区服 id。
+_SERVER_NAMES: tuple[ServerName, ...] = (
+    "日服",
+    "国际服",
+    "国服",
+)
+
+
+def _normalize_server_name(raw_server: str) -> str:
+    """在服务器查找前归一化用户输入。
+
+    Args:
+        raw_server: 命令中解析出的原始服务器文本。
+
+    Returns:
+        去除空白并完成大小写折叠后的服务器名。
+    """
+    return "".join(raw_server.strip().split()).casefold()
+
+
+_SERVER_BY_NAME: dict[str, ServerName] = {
+    _normalize_server_name(server): server for server in _SERVER_NAMES
+}
+
+
+def server_for(raw_server: str) -> ServerName | None:
+    """按显示名解析受支持的服务器。
+
+    Args:
+        raw_server: 命令中解析出的原始服务器文本。
+
+    Returns:
+        匹配到的服务器描述；不支持时返回 `None`。
+    """
+    return _SERVER_BY_NAME.get(_normalize_server_name(raw_server))
+
+
+def supported_server_names() -> str:
+    """返回面向用户展示的服务器名称列表。"""
+    return "、".join(_SERVER_NAMES)

nonebot_plugin_ba_gamekee/infra/__init__.py

@@ -0,0 +1,3 @@
+from .gamekee import GameKeeClient, GameKeeError
+
+__all__ = ["GameKeeClient", "GameKeeError"]