nonebot-plugin-ba-gamekee 0.2.0__tar.gz

nonebot_plugin_ba_gamekee-0.2.0/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.3
+Name: nonebot-plugin-ba-gamekee
+Version: 0.2.0
+Summary: 蔚蓝档案 GameKee Wiki 攻略查询
+Author: Misty02600
+Author-email: Misty02600 <xiao02600@gmail.com>
+Requires-Dist: httpx>=0.27.0,<1.0.0
+Requires-Dist: nonebot-plugin-alconna>=0.60.0,<1.0.0
+Requires-Dist: nonebot-plugin-apscheduler>=0.5.0,<1.0.0
+Requires-Dist: nonebot-plugin-localstore>=0.7.4,<1.0.0
+Requires-Dist: nonebot-plugin-uninfo>=0.10.0,<1.0.0
+Requires-Dist: nonebot2>=2.4.2,<3.0.0
+Requires-Dist: playwright>=1.58.0,<2.0.0
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/Misty02600/nonebot-plugin-ba-gamekee
+Project-URL: Issues, https://github.com/Misty02600/nonebot-plugin-ba-gamekee/issues
+Project-URL: Repository, https://github.com/Misty02600/nonebot-plugin-ba-gamekee.git
+Description-Content-Type: text/markdown
+
+<div align="center">
+    <a href="https://v2.nonebot.dev/store">
+    <img src="https://github.com/Misty02600/nonebot-plugin-template/releases/download/assets/NoneBotPlugin.png" width="310" alt="logo"></a>
+
+## ✨ nonebot-plugin-ba-gamekee ✨
+[![LICENSE](https://img.shields.io/github/license/Misty02600/nonebot-plugin-ba-gamekee.svg)](./LICENSE)
+[![python](https://img.shields.io/badge/python-3.11+-blue.svg?logo=python&logoColor=white)](https://www.python.org)
+[![Adapters](https://img.shields.io/badge/Adapters-OneBot%20v11-blue)](#supported-adapters)
+<br/>
+
+[![uv](https://img.shields.io/badge/package%20manager-uv-black?logo=uv)](https://github.com/astral-sh/uv)
+[![ruff](https://img.shields.io/badge/code%20style-ruff-black?logo=ruff)](https://github.com/astral-sh/ruff)
+
+</div>
+
+## 📖 介绍
+
+`nonebot-plugin-ba-gamekee` 是面向 Blue Archive / 蔚蓝档案的 GameKee Wiki 攻略查询插件。
+
+当前已支持查询三服当前活动攻略与卡池评测入口，并会在后台同步 GameKee 首页入口缓存，减少实时请求压力。
+
+## 💿 安装
+
+<details open>
+<summary>使用 nb-cli 安装</summary>
+在 nonebot2 项目的根目录下打开命令行, 输入以下指令即可安装
+
+    nb plugin install nonebot-plugin-ba-gamekee --upgrade
+使用 **pypi** 源安装
+
+    nb plugin install nonebot-plugin-ba-gamekee --upgrade -i "https://pypi.org/simple"
+使用**清华源**安装
+
+    nb plugin install nonebot-plugin-ba-gamekee --upgrade -i "https://pypi.tuna.tsinghua.edu.cn/simple"
+
+
+</details>
+
+<details>
+<summary>使用包管理器安装</summary>
+在 nonebot2 项目的插件目录下, 打开命令行, 根据你使用的包管理器, 输入相应的安装命令
+
+<details open>
+<summary>uv</summary>
+
+    uv add nonebot-plugin-ba-gamekee
+安装仓库 main 分支
+
+    uv add git+https://github.com/Misty02600/nonebot-plugin-ba-gamekee@main
+</details>
+
+<details>
+<summary>pdm</summary>
+
+    pdm add nonebot-plugin-ba-gamekee
+安装仓库 main 分支
+
+    pdm add git+https://github.com/Misty02600/nonebot-plugin-ba-gamekee@main
+</details>
+<details>
+<summary>poetry</summary>
+
+    poetry add nonebot-plugin-ba-gamekee
+安装仓库 main 分支
+
+    poetry add git+https://github.com/Misty02600/nonebot-plugin-ba-gamekee@main
+</details>
+
+打开 nonebot2 项目根目录下的 `pyproject.toml` 文件, 在 `[tool.nonebot]` 部分追加写入
+
+    plugins = ["nonebot_plugin_ba_gamekee"]
+
+</details>
+
+<details>
+<summary>使用 nbr 安装(使用 uv 管理依赖可用)</summary>
+
+[nbr](https://github.com/fllesser/nbr) 是一个基于 uv 的 nb-cli，可以方便地管理 nonebot2
+
+    nbr plugin install nonebot-plugin-ba-gamekee
+使用 **pypi** 源安装
+
+    nbr plugin install nonebot-plugin-ba-gamekee -i "https://pypi.org/simple"
+使用**清华源**安装
+
+    nbr plugin install nonebot-plugin-ba-gamekee -i "https://pypi.tuna.tsinghua.edu.cn/simple"
+
+</details>
+
+
+## ⚙️ 配置
+
+插件使用 [nonebot_plugin_localstore](https://github.com/nonebot/plugin-localstore) 储存数据和缓存，并使用 apscheduler 定时刷新 GameKee 首页入口。
+
+可在 nonebot2 项目的 `.env` 文件中按需覆盖下表配置。
+
+| 配置项  | 必填  | 默认值 |   说明   |
+| :-----: | :---: | :----: | :------: |
+| `ba_gamekee_refresh_interval_minutes` |  否   | `10` | 后台刷新当前攻略入口缓存的间隔，单位为分钟 |
+
+## 🎉 使用
+### 指令表
+| 指令  | 权限  | 需要@ | 范围  |   说明   |
+| :---: | :---: | :---: | :---: | :------: |
+| `/ba活动 日服` | 群员 | 否 | 私聊/群聊 | 查询当前日服活动攻略 |
+| `/ba活动 国际服` | 群员 | 否 | 私聊/群聊 | 查询当前国际服活动攻略 |
+| `/ba活动 国服` | 群员 | 否 | 私聊/群聊 | 查询当前国服活动攻略 |
+| `/ba卡池 日服` | 群员 | 否 | 私聊/群聊 | 查询当前日服卡池评测 |
+| `/ba卡池 国际服` | 群员 | 否 | 私聊/群聊 | 查询当前国际服卡池评测 |
+| `/ba卡池 国服` | 群员 | 否 | 私聊/群聊 | 查询当前国服卡池评测 |
+
+`ba` 与子命令之间可以加空格，例如 `/ba 活动 国际服`、`/ba 卡池 国服`。子命令与服务器参数之间需要分隔。
+
+### 🎨 效果图
+如果有效果图的话

nonebot_plugin_ba_gamekee-0.2.0/README.md

@@ -0,0 +1,115 @@
+<div align="center">
+    <a href="https://v2.nonebot.dev/store">
+    <img src="https://github.com/Misty02600/nonebot-plugin-template/releases/download/assets/NoneBotPlugin.png" width="310" alt="logo"></a>
+
+## ✨ nonebot-plugin-ba-gamekee ✨
+[![LICENSE](https://img.shields.io/github/license/Misty02600/nonebot-plugin-ba-gamekee.svg)](./LICENSE)
+[![python](https://img.shields.io/badge/python-3.11+-blue.svg?logo=python&logoColor=white)](https://www.python.org)
+[![Adapters](https://img.shields.io/badge/Adapters-OneBot%20v11-blue)](#supported-adapters)
+<br/>
+
+[![uv](https://img.shields.io/badge/package%20manager-uv-black?logo=uv)](https://github.com/astral-sh/uv)
+[![ruff](https://img.shields.io/badge/code%20style-ruff-black?logo=ruff)](https://github.com/astral-sh/ruff)
+
+</div>
+
+## 📖 介绍
+
+`nonebot-plugin-ba-gamekee` 是面向 Blue Archive / 蔚蓝档案的 GameKee Wiki 攻略查询插件。
+
+当前已支持查询三服当前活动攻略与卡池评测入口，并会在后台同步 GameKee 首页入口缓存，减少实时请求压力。
+
+## 💿 安装
+
+<details open>
+<summary>使用 nb-cli 安装</summary>
+在 nonebot2 项目的根目录下打开命令行, 输入以下指令即可安装
+
+    nb plugin install nonebot-plugin-ba-gamekee --upgrade
+使用 **pypi** 源安装
+
+    nb plugin install nonebot-plugin-ba-gamekee --upgrade -i "https://pypi.org/simple"
+使用**清华源**安装
+
+    nb plugin install nonebot-plugin-ba-gamekee --upgrade -i "https://pypi.tuna.tsinghua.edu.cn/simple"
+
+
+</details>
+
+<details>
+<summary>使用包管理器安装</summary>
+在 nonebot2 项目的插件目录下, 打开命令行, 根据你使用的包管理器, 输入相应的安装命令
+
+<details open>
+<summary>uv</summary>
+
+    uv add nonebot-plugin-ba-gamekee
+安装仓库 main 分支
+
+    uv add git+https://github.com/Misty02600/nonebot-plugin-ba-gamekee@main
+</details>
+
+<details>
+<summary>pdm</summary>
+
+    pdm add nonebot-plugin-ba-gamekee
+安装仓库 main 分支
+
+    pdm add git+https://github.com/Misty02600/nonebot-plugin-ba-gamekee@main
+</details>
+<details>
+<summary>poetry</summary>
+
+    poetry add nonebot-plugin-ba-gamekee
+安装仓库 main 分支
+
+    poetry add git+https://github.com/Misty02600/nonebot-plugin-ba-gamekee@main
+</details>
+
+打开 nonebot2 项目根目录下的 `pyproject.toml` 文件, 在 `[tool.nonebot]` 部分追加写入
+
+    plugins = ["nonebot_plugin_ba_gamekee"]
+
+</details>
+
+<details>
+<summary>使用 nbr 安装(使用 uv 管理依赖可用)</summary>
+
+[nbr](https://github.com/fllesser/nbr) 是一个基于 uv 的 nb-cli，可以方便地管理 nonebot2
+
+    nbr plugin install nonebot-plugin-ba-gamekee
+使用 **pypi** 源安装
+
+    nbr plugin install nonebot-plugin-ba-gamekee -i "https://pypi.org/simple"
+使用**清华源**安装
+
+    nbr plugin install nonebot-plugin-ba-gamekee -i "https://pypi.tuna.tsinghua.edu.cn/simple"
+
+</details>
+
+
+## ⚙️ 配置
+
+插件使用 [nonebot_plugin_localstore](https://github.com/nonebot/plugin-localstore) 储存数据和缓存，并使用 apscheduler 定时刷新 GameKee 首页入口。
+
+可在 nonebot2 项目的 `.env` 文件中按需覆盖下表配置。
+
+| 配置项  | 必填  | 默认值 |   说明   |
+| :-----: | :---: | :----: | :------: |
+| `ba_gamekee_refresh_interval_minutes` |  否   | `10` | 后台刷新当前攻略入口缓存的间隔，单位为分钟 |
+
+## 🎉 使用
+### 指令表
+| 指令  | 权限  | 需要@ | 范围  |   说明   |
+| :---: | :---: | :---: | :---: | :------: |
+| `/ba活动 日服` | 群员 | 否 | 私聊/群聊 | 查询当前日服活动攻略 |
+| `/ba活动 国际服` | 群员 | 否 | 私聊/群聊 | 查询当前国际服活动攻略 |
+| `/ba活动 国服` | 群员 | 否 | 私聊/群聊 | 查询当前国服活动攻略 |
+| `/ba卡池 日服` | 群员 | 否 | 私聊/群聊 | 查询当前日服卡池评测 |
+| `/ba卡池 国际服` | 群员 | 否 | 私聊/群聊 | 查询当前国际服卡池评测 |
+| `/ba卡池 国服` | 群员 | 否 | 私聊/群聊 | 查询当前国服卡池评测 |
+
+`ba` 与子命令之间可以加空格，例如 `/ba 活动 国际服`、`/ba 卡池 国服`。子命令与服务器参数之间需要分隔。
+
+### 🎨 效果图
+如果有效果图的话

nonebot_plugin_ba_gamekee-0.2.0/pyproject.toml

@@ -0,0 +1,131 @@
+[project]
+name = "nonebot-plugin-ba-gamekee"
+version = "0.2.0"
+description = "蔚蓝档案 GameKee Wiki 攻略查询"
+readme = "README.md"
+requires-python = ">=3.11"
+authors = [{ name = "Misty02600", email = "xiao02600@gmail.com" }]
+dependencies = [
+  "httpx>=0.27.0,<1.0.0",
+  "nonebot-plugin-alconna>=0.60.0,<1.0.0",
+  "nonebot-plugin-apscheduler>=0.5.0,<1.0.0",
+  "nonebot-plugin-localstore>=0.7.4,<1.0.0",
+  "nonebot-plugin-uninfo>=0.10.0,<1.0.0",
+  "nonebot2>=2.4.2,<3.0.0",
+  "playwright>=1.58.0,<2.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/Misty02600/nonebot-plugin-ba-gamekee"
+Issues = "https://github.com/Misty02600/nonebot-plugin-ba-gamekee/issues"
+Repository = "https://github.com/Misty02600/nonebot-plugin-ba-gamekee.git"
+
+[dependency-groups]
+dev = [
+  "commitizen>=4.1.0",
+  "git-cliff>=2.11.0,<3.0.0",
+  "prek>=0.2.0",
+  { include-group = "test" },
+]
+test = [
+  "basedpyright>=1.16.0",
+  "ruff>=0.14.13,<1.0.0",
+  "nonebot-adapter-onebot>=2.4.6,<3.0.0",
+  "nonebot2[fastapi]>=2.4.4,<3.0.0",
+  "nonebug>=0.4.3,<1.0.0",
+  "pytest-asyncio>=1.3.0,<1.4.0",
+  "pytest-cov>=7.0.0",
+]
+
+[tool.nonebot.plugins]
+nonebot-plugin-ba-gamekee = ["nonebot_plugin_ba_gamekee"]
+
+[tool.nonebot.adapters]
+nonebot-adapter-onebot = [
+  { name = "OneBot V11", module_name = "nonebot.adapters.onebot.v11" },
+]
+
+[build-system]
+requires = ["uv_build>=0.10.0,<0.11.0"]
+build-backend = "uv_build"
+
+[tool.commitizen]
+name = "cz_conventional_commits"
+version = "0.1.0"
+version_provider = "uv"
+tag_format = "v$version"
+annotated_tag = true
+major_version_zero = true                   # 允许 0.x.x 版本号
+
+[tool.coverage.report]
+exclude_lines = [
+  "raise NotImplementedError",
+  "if TYPE_CHECKING:",
+  "@overload",
+  "except ImportError:",
+]
+
+[tool.pyright]
+include = ["src"]      # 默认仅检查源码目录；测试通过 pytest / ruff 保证质量
+pythonVersion = "3.11" # 目标 Python 版本（影响可用的类型特性）
+pythonPlatform = "All" # 目标平台：All | Linux | Windows | Darwin
+# typeCheckingMode 类型检查严格程度，可选值：
+#   - "off"：      关闭类型检查
+#   - "basic"：    基础检查（仅报告明确的类型错误）
+#   - "standard"： 标准检查（推荐，平衡严格性与实用性）
+#   - "strict"：   严格检查（要求完整的类型注解，适合新项目）
+#   - "all"：      最严格（启用所有检查，可能产生大量警告）
+typeCheckingMode = "standard"
+
+[tool.pytest.ini_options]
+addopts = [
+  "--import-mode=importlib", # 使用 importlib 导入模式（推荐，避免 sys.path 污染）
+  "--strict-markers",        # 严格标记模式（未注册的 marker 会报错）
+  "--tb=short",              # 简短的错误回溯（减少输出噪音）
+  "-ra",                     # 显示所有非通过测试的摘要（a=all except passed）
+]
+pythonpath = ["src", "tests"] # 添加到 Python 路径，确保模块可导入
+asyncio_mode = "auto" # 自动检测异步测试函数，无需手动标记 @pytest.mark.asyncio
+
+[tool.ruff]
+line-length = 88                 # 每行最大字符数（与 Black 保持一致）
+src = ["src", "tests"]           # 源代码目录（用于判断导入是本地模块还是第三方模块）
+extend-exclude = ["scripts"]     # 脚本目录不做 lint 检查
+
+[tool.ruff.format]
+line-ending = "lf" # 行尾符：lf（Unix）| crlf（Windows）| auto | native
+
+[tool.ruff.lint]
+# 启用的规则集，每个字母代码对应一组规则
+select = [
+  "F",     # Pyflakes：基础语法和逻辑错误检查
+  "W",     # pycodestyle warnings：PEP 8 风格警告
+  "E",     # pycodestyle errors：PEP 8 风格错误
+  "I",     # isort：导入语句排序
+  "B",     # flake8-bugbear：发现潜在 bug 和设计问题
+  "UP",    # pyupgrade：升级到新版 Python 语法
+  "ASYNC", # flake8-async：异步代码最佳实践
+  "C4",    # flake8-comprehensions：推导式优化建议
+  "T10",   # flake8-debugger：检测遗留的调试器语句（如 pdb）
+  "T20",   # flake8-print：检测 print 语句（生产代码应使用 logging）
+  "PYI",   # flake8-pyi：类型存根文件（.pyi）规范检查
+  "PT",    # flake8-pytest-style：pytest 代码风格检查
+  "Q",     # flake8-quotes：引号使用规范
+  "TID",   # flake8-tidy-imports：导入语句整理
+  "RUF",   # Ruff-specific：Ruff 特有的规则
+]
+# 忽略的规则（根据项目需求放宽）
+ignore = [
+  "E501",   # 行长度由 formatter 控制，lint 不重复检查
+  "E402",   # 允许模块导入不在文件顶部（某些情况下需要先执行代码）
+  "UP037",  # 允许使用引号包裹的类型注解（前向引用）
+  "RUF001", # 允许字符串中的中文等 Unicode 字符
+  "RUF002", # 允许文档字符串中的中文等 Unicode 字符
+  "RUF003", # 允许注释中的中文等 Unicode 字符
+  "W191",   # 允许使用制表符缩进
+  "TID252", # 允许使用相对导入
+  "B008",   # 允许在函数参数默认值中使用函数调用
+]
+
+[tool.ruff.lint.isort]
+extra-standard-library = ["typing_extensions"] # 将 typing_extensions 视为标准库

nonebot_plugin_ba_gamekee-0.2.0/src/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-0.2.0/src/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-0.2.0/src/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-0.2.0/src/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-0.2.0/src/nonebot_plugin_ba_gamekee/bot/handlers/__init__.py

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