♻️ refactor: 统一图片渲染架构并引入通用UI组件系统 (#2019)

* ♻️ refactor: 统一图片渲染架构并引入通用UI组件系统

🎨 **渲染服务重构**
- 统一图片渲染入口，引入主题系统支持
- 优化Jinja2环境管理，支持主题覆盖和插件命名空间
- 新增UI缓存机制和主题重载功能

✨ **通用UI组件系统**
- 新增 zhenxun.ui 模块，提供数据模型和构建器
- 引入BaseBuilder基类，支持链式调用
- 新增多种UI构建器：InfoCard, Markdown, Table, Chart, Layout等
- 新增通用组件：Divider, Badge, ProgressBar, UserInfoBlock

🔄 **插件迁移**
- 迁移9个内置插件至新渲染系统
- 移除各插件中分散的图片生成工具
- 优化数据处理和渲染逻辑

💥 **Breaking Changes**
- 移除旧的图片渲染接口和模板路径
- TEMPLATE_PATH 更名为 THEMES_PATH
- 插件需适配新的RendererService和zhenxun.ui模块

* ✅ test(check): 更新自检插件测试中的渲染服务模拟

* ♻️ refactor(renderer): 将缓存文件名哈希算法切换到 SHA256

* ♻️ refactor(shop): 移除商店HTML图片生成模块

* 🚨 auto fix by pre-commit hooks

---------

Co-authored-by: webjoin111 <455457521@qq.com>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

zhenxun/builtin_plugins/help/_data_source.py

@@ -1,13 +1,11 @@
-from pathlib import Path
-
 import nonebot
-from nonebot.plugin import PluginMetadata
-from nonebot_plugin_htmlrender import template_to_pic
 from nonebot_plugin_uninfo import Uninfo
 
-from zhenxun.configs.config import Config
-from zhenxun.configs.path_config import IMAGE_PATH, TEMPLATE_PATH
+from zhenxun.configs.config import BotConfig, Config
+from zhenxun.configs.path_config import IMAGE_PATH
 from zhenxun.configs.utils import PluginExtraData
+from zhenxun.models.bot_console import BotConsole
+from zhenxun.models.group_console import GroupConsole
 from zhenxun.models.level_user import LevelUser
 from zhenxun.models.plugin_info import PluginInfo
 from zhenxun.models.statistics import Statistics
@@ -15,60 +13,114 @@ from zhenxun.services import (
     LLMException,
     LLMMessage,
     generate,
+    renderer_service,
 )
 from zhenxun.services.log import logger
-from zhenxun.utils._image_template import Markdown
-from zhenxun.utils.enum import PluginType
-from zhenxun.utils.image_utils import BuildImage, ImageTemplate
-
-from ._config import (
-    GROUP_HELP_PATH,
-    SIMPLE_DETAIL_HELP_IMAGE,
-    SIMPLE_HELP_IMAGE,
-    base_config,
+from zhenxun.ui import (
+    InfoCardBuilder,
+    NotebookBuilder,
+    PluginMenuBuilder,
+    PluginMenuCategory,
 )
-from .html_help import build_html_image
-from .normal_help import build_normal_image
-from .zhenxun_help import build_zhenxun_image
+from zhenxun.utils.common_utils import format_usage_for_markdown
+from zhenxun.utils.enum import BlockType, PluginType
+from zhenxun.utils.platform import PlatformUtils
+from zhenxun.utils.pydantic_compat import model_dump
+
+from ._utils import classify_plugin
 
 random_bk_path = IMAGE_PATH / "background" / "help" / "simple_help"
-
 background = IMAGE_PATH / "background" / "0.png"
 
-
 driver = nonebot.get_driver()
 
 
+def _create_plugin_menu_item(
+    bot: BotConsole | None,
+    plugin: PluginInfo,
+    group: GroupConsole | None,
+    is_detail: bool,
+) -> dict:
+    """为插件菜单构造一个插件菜单项数据字典"""
+    status = True
+    has_superuser_help = False
+    nb_plugin = nonebot.get_plugin_by_module_name(plugin.module_path)
+    if nb_plugin and nb_plugin.metadata and nb_plugin.metadata.extra:
+        extra_data = PluginExtraData(**nb_plugin.metadata.extra)
+        if extra_data.superuser_help:
+            has_superuser_help = True
+
+    if not plugin.status:
+        if plugin.block_type == BlockType.ALL:
+            status = False
+        elif group and plugin.block_type == BlockType.GROUP:
+            status = False
+        elif not group and plugin.block_type == BlockType.PRIVATE:
+            status = False
+    elif group and f"{plugin.module}," in group.block_plugin:
+        status = False
+    elif bot and f"{plugin.module}," in bot.block_plugins:
+        status = False
+
+    commands = []
+    if is_detail and nb_plugin and nb_plugin.metadata and nb_plugin.metadata.extra:
+        extra_data = PluginExtraData(**nb_plugin.metadata.extra)
+        commands = [cmd.command for cmd in extra_data.commands]
+
+    return {
+        "id": str(plugin.id),
+        "name": plugin.name,
+        "status": status,
+        "has_superuser_help": has_superuser_help,
+        "commands": commands,
+    }
+
+
 async def create_help_img(
     session: Uninfo, group_id: str | None, is_detail: bool
-) -> Path:
-    """生成帮助图片
+) -> bytes:
+    """使用渲染服务生成帮助图片"""
+    classified_data = await classify_plugin(
+        session, group_id, is_detail, _create_plugin_menu_item
+    )
 
-    参数:
-        session: Uninfo
-        group_id: 群号
-    """
-    help_type = base_config.get("type", "").strip().lower()
+    sorted_categories = dict(
+        sorted(classified_data.items(), key=lambda x: len(x[1]), reverse=True)
+    )
+    categories_for_model = []
+    plugin_count = 0
+    active_count = 0
 
-    match help_type:
-        case "html":
-            result = BuildImage.open(
-                await build_html_image(session, group_id, is_detail)
-            )
-        case "zhenxun":
-            result = BuildImage.open(
-                await build_zhenxun_image(session, group_id, is_detail)
-            )
-        case _:
-            result = await build_normal_image(group_id, is_detail)
-    if group_id:
-        save_path = GROUP_HELP_PATH / f"{group_id}_{is_detail}.png"
-    elif is_detail:
-        save_path = SIMPLE_DETAIL_HELP_IMAGE
-    else:
-        save_path = SIMPLE_HELP_IMAGE
-    await result.save(save_path)
-    return save_path
+    if sorted_categories:
+        menu_key = next(iter(sorted_categories.keys()))
+        max_data = sorted_categories.pop(menu_key)
+        main_category_name = "主要功能" if menu_key in ["normal", "功能"] else menu_key
+        categories_for_model.append({"name": main_category_name, "items": max_data})
+        plugin_count += len(max_data)
+        active_count += sum(1 for item in max_data if item["status"])
+
+    for menu, value in sorted_categories.items():
+        category_name = "主要功能" if menu in ["normal", "功能"] else menu
+        categories_for_model.append({"name": category_name, "items": value})
+        plugin_count += len(value)
+        active_count += sum(1 for item in value if item["status"])
+
+    platform = PlatformUtils.get_platform(session)
+    bot_id = BotConfig.get_qbot_uid(session.self_id) or session.self_id
+    bot_avatar_url = PlatformUtils.get_user_avatar_url(bot_id, platform) or ""
+
+    builder = PluginMenuBuilder(
+        bot_name=BotConfig.self_nickname,
+        bot_avatar_url=bot_avatar_url,
+        is_detail=is_detail,
+    )
+
+    for category in categories_for_model:
+        builder.add_category(
+            PluginMenuCategory(name=category["name"], items=category["items"])
+        )
+
+    return await builder.build()
 
 
 async def get_user_allow_help(user_id: str) -> list[PluginType]:
@@ -92,36 +144,6 @@ async def get_user_allow_help(user_id: str) -> list[PluginType]:
     return type_list
 
 
-async def get_normal_help(
-    metadata: PluginMetadata, extra: PluginExtraData, is_superuser: bool
-) -> str | bytes:
-    """构建默认帮助详情
-
-    参数:
-        metadata: PluginMetadata
-        extra: PluginExtraData
-        is_superuser: 是否超级用户帮助
-
-    返回:
-        str | bytes: 返回信息
-    """
-    items = None
-    if is_superuser:
-        if usage := extra.superuser_help:
-            items = {
-                "简介": metadata.description,
-                "用法": usage,
-            }
-    else:
-        items = {
-            "简介": metadata.description,
-            "用法": metadata.usage,
-        }
-    if items:
-        return (await ImageTemplate.hl_page(metadata.name, items)).pic2bytes()
-    return "该功能没有帮助信息"
-
-
 def min_leading_spaces(str_list: list[str]) -> int:
     min_spaces = 9999
 
@@ -142,45 +164,6 @@ def split_text(text: str):
     return [s.replace(" ", " ") for s in split_text]
 
 
-async def get_zhenxun_help(
-    module: str, metadata: PluginMetadata, extra: PluginExtraData, is_superuser: bool
-) -> str | bytes:
-    """构建ZhenXun帮助详情
-
-    参数:
-        module: 模块名
-        metadata: PluginMetadata
-        extra: PluginExtraData
-        is_superuser: 是否超级用户帮助
-
-    返回:
-        str | bytes: 返回信息
-    """
-    call_count = await Statistics.filter(plugin_name=module).count()
-    usage = metadata.usage
-    if is_superuser:
-        if not extra.superuser_help:
-            return "该功能没有超级用户帮助信息"
-        usage = extra.superuser_help
-    return await template_to_pic(
-        template_path=str((TEMPLATE_PATH / "help_detail").absolute()),
-        template_name="main.html",
-        templates={
-            "title": metadata.name,
-            "author": extra.author,
-            "version": extra.version,
-            "call_count": call_count,
-            "descriptions": split_text(metadata.description),
-            "usages": split_text(usage),
-        },
-        pages={
-            "viewport": {"width": 824, "height": 590},
-            "base_url": f"file://{TEMPLATE_PATH}",
-        },
-        wait=2,
-    )
-
-
 async def get_plugin_help(user_id: str, name: str, is_superuser: bool) -> str | bytes:
     """获取功能的帮助信息
 
@@ -196,16 +179,42 @@ async def get_plugin_help(user_id: str, name: str, is_superuser: bool) -> str |
         plugin = await PluginInfo.get_or_none(
             name__iexact=name, load_status=True, plugin_type__in=type_list
         )
+
     if plugin:
         _plugin = nonebot.get_plugin_by_module_name(plugin.module_path)
         if _plugin and _plugin.metadata:
             extra_data = PluginExtraData(**_plugin.metadata.extra)
-            if Config.get_config("help", "detail_type") == "zhenxun":
-                return await get_zhenxun_help(
-                    plugin.module, _plugin.metadata, extra_data, is_superuser
-                )
-            else:
-                return await get_normal_help(_plugin.metadata, extra_data, is_superuser)
+
+            call_count = await Statistics.filter(plugin_name=plugin.module).count()
+            usage = _plugin.metadata.usage
+            if is_superuser:
+                if not extra_data.superuser_help:
+                    return "该功能没有超级用户帮助信息"
+                usage = extra_data.superuser_help
+
+            builder = InfoCardBuilder(title=_plugin.metadata.name)
+
+            builder.add_metadata_items(
+                [
+                    ("作者", extra_data.author or "未知"),
+                    ("版本", extra_data.version or "未知"),
+                    ("调用次数", call_count),
+                ]
+            )
+
+            processed_description = format_usage_for_markdown(
+                _plugin.metadata.description.strip()
+            )
+            processed_usage = format_usage_for_markdown(usage.strip())
+
+            builder.add_section("简介", [processed_description])
+            builder.add_section("使用方法", [processed_usage])
+
+            style_name = Config.get_config("help", "HELP_STYLE", "default")
+            render_dict = model_dump(builder._data)
+            render_dict["style_name"] = style_name
+
+            return await renderer_service.render("pages/builtin/help", data=render_dict)
         return "糟糕! 该功能没有帮助喔..."
     return "没有查找到这个功能噢..."
 
@@ -282,10 +291,12 @@ async def get_llm_help(question: str, user_id: str) -> str | bytes:
 
         reply_text = response.text if response else "抱歉，我暂时无法回答这个问题。"
         threshold = Config.get_config("help", "LLM_HELPER_REPLY_AS_IMAGE_THRESHOLD", 50)
+
         if len(reply_text) > threshold:
-            markdown = Markdown()
-            markdown.text(reply_text)
-            return await markdown.build()
+            builder = NotebookBuilder()
+            builder.text(reply_text)
+            return await builder.build()
+
         return reply_text
 
     except LLMException as e: