♻️ 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/ui/__init__.py

@@ -0,0 +1,40 @@
+from . import builders, models
+from .builders import (
+    InfoCardBuilder,
+    LayoutBuilder,
+    MarkdownBuilder,
+    NotebookBuilder,
+    PluginHelpPageBuilder,
+    PluginMenuBuilder,
+    TableBuilder,
+)
+from .models import (
+    HelpCategory,
+    HelpItem,
+    InfoCardData,
+    PluginHelpPageData,
+    PluginMenuCategory,
+    PluginMenuData,
+    PluginMenuItem,
+    RenderableComponent,
+)
+
+__all__ = [
+    "HelpCategory",
+    "HelpItem",
+    "InfoCardBuilder",
+    "InfoCardData",
+    "LayoutBuilder",
+    "MarkdownBuilder",
+    "NotebookBuilder",
+    "PluginHelpPageBuilder",
+    "PluginHelpPageData",
+    "PluginMenuBuilder",
+    "PluginMenuCategory",
+    "PluginMenuData",
+    "PluginMenuItem",
+    "RenderableComponent",
+    "TableBuilder",
+    "builders",
+    "models",
+]

zhenxun/ui/builders/__init__.py

@@ -0,0 +1,19 @@
+from . import widgets
+from .core.layout import LayoutBuilder
+from .core.markdown import MarkdownBuilder
+from .core.notebook import NotebookBuilder
+from .core.table import TableBuilder
+from .presets.help_page import PluginHelpPageBuilder
+from .presets.info_card import InfoCardBuilder
+from .presets.plugin_menu import PluginMenuBuilder
+
+__all__ = [
+    "InfoCardBuilder",
+    "LayoutBuilder",
+    "MarkdownBuilder",
+    "NotebookBuilder",
+    "PluginHelpPageBuilder",
+    "PluginMenuBuilder",
+    "TableBuilder",
+    "widgets",
+]

zhenxun/ui/builders/base.py

@@ -0,0 +1,41 @@
+from typing import Generic, TypeVar
+from typing_extensions import Self
+
+from pydantic import BaseModel
+
+from zhenxun.services import renderer_service
+
+T_DataModel = TypeVar("T_DataModel", bound=BaseModel)
+
+
+class BaseBuilder(Generic[T_DataModel]):
+    """所有UI构建器的基类，提供通用的样式化和构建逻辑。"""
+
+    def __init__(self, data_model: T_DataModel, template_name: str):
+        self._data: T_DataModel = data_model
+        self._style_name: str | None = None
+        self._template_name = template_name
+
+    def with_style(self, style_name: str) -> Self:
+        """
+        为组件应用一个特定的样式。
+        """
+        self._style_name = style_name
+        return self
+
+    async def build(self, use_cache: bool = False, **render_options) -> bytes:
+        """
+        通用的构建方法，将数据渲染为图片。
+        """
+        if self._style_name and hasattr(self._data, "style_name"):
+            setattr(self._data, "style_name", self._style_name)
+
+        data_to_render = self._data
+
+        return await renderer_service.render(
+            template_name=self._template_name,
+            data=data_to_render,
+            use_cache=use_cache,
+            style_name=self._style_name,
+            **render_options,
+        )

zhenxun/ui/builders/charts.py

@@ -0,0 +1,88 @@
+from typing import Any, Generic, Literal, TypeVar
+from typing_extensions import Self
+
+from ..models.charts import (
+    BarChartData,
+    BaseChartData,
+    LineChartData,
+    LineChartSeries,
+    PieChartData,
+    PieChartDataItem,
+)
+from .base import BaseBuilder
+
+T_ChartData = TypeVar("T_ChartData", bound=BaseChartData)
+
+
+class BaseChartBuilder(BaseBuilder[T_ChartData], Generic[T_ChartData]):
+    """所有图表构建器的基类"""
+
+    def set_title(self, title: str) -> Self:
+        self._data.title = title
+        return self
+
+
+class BarChartBuilder(BaseChartBuilder[BarChartData]):
+    """链式构建柱状图的辅助类 (支持横向和竖向)"""
+
+    def __init__(
+        self, title: str, direction: Literal["horizontal", "vertical"] = "horizontal"
+    ):
+        data_model = BarChartData(
+            title=title, direction=direction, category_data=[], data=[]
+        )
+        super().__init__(data_model, template_name="components/charts/bar_chart")
+
+    def add_data(self, category: str, value: float) -> Self:
+        """添加一个数据点"""
+        self._data.category_data.append(category)
+        self._data.data.append(value)
+        return self
+
+    def add_data_items(
+        self, items: list[tuple[str, int | float]] | list[dict[str, Any]]
+    ) -> Self:
+        for item in items:
+            if isinstance(item, tuple):
+                self.add_data(item[0], item[1])
+            elif isinstance(item, dict):
+                self.add_data(item.get("category", ""), item.get("value", 0))
+        return self
+
+    def set_background_image(self, background_image: str) -> Self:
+        """设置背景图片 (仅横向柱状图模板支持)"""
+        self._data.background_image = background_image
+        return self
+
+
+class PieChartBuilder(BaseChartBuilder[PieChartData]):
+    """链式构建饼图的辅助类"""
+
+    def __init__(self, title: str):
+        data_model = PieChartData(title=title, data=[])
+        super().__init__(data_model, template_name="components/charts/pie_chart")
+
+    def add_slice(self, name: str, value: float) -> Self:
+        """添加一个饼图扇区"""
+        self._data.data.append(PieChartDataItem(name=name, value=value))
+        return self
+
+
+class LineChartBuilder(BaseChartBuilder[LineChartData]):
+    """链式构建折线图的辅助类"""
+
+    def __init__(self, title: str):
+        data_model = LineChartData(title=title, category_data=[], series=[])
+        super().__init__(data_model, template_name="components/charts/line_chart")
+
+    def set_categories(self, categories: list[str]) -> Self:
+        """设置X轴的分类标签"""
+        self._data.category_data = categories
+        return self
+
+    def add_series(
+        self, name: str, data: list[int | float], smooth: bool = False
+    ) -> Self:
+        """添加一条折线"""
+        self._data.series.append(LineChartSeries(name=name, data=data, smooth=smooth))
+        return self

zhenxun/ui/builders/core/__init__.py

@@ -0,0 +1,16 @@
+"""
+核心构建器模块
+包含基础的UI构建器类
+"""
+
+from .layout import LayoutBuilder
+from .markdown import MarkdownBuilder
+from .notebook import NotebookBuilder
+from .table import TableBuilder
+
+__all__ = [
+    "LayoutBuilder",
+    "MarkdownBuilder",
+    "NotebookBuilder",
+    "TableBuilder",
+]

zhenxun/ui/builders/core/layout.py

@@ -0,0 +1,117 @@
+import base64
+from typing import Any
+from typing_extensions import Self
+
+from ...models.core.layout import LayoutData, LayoutItem
+from ..base import BaseBuilder
+
+__all__ = ["LayoutBuilder"]
+
+
+class LayoutBuilder(BaseBuilder[LayoutData]):
+    """
+    一个用于将多个图片（bytes）组合成单张图片的链式构建器。
+    采用混合模式，提供便捷的工厂方法和灵活的自定义模板能力。
+    """
+
+    def __init__(self):
+        super().__init__(LayoutData(), template_name="")
+        self._items: list[LayoutItem] = []
+        self._options: dict[str, Any] = {}
+        self._preset_template_name: str | None = None
+
+    @classmethod
+    def column(cls, **options: Any) -> Self:
+        """
+        工厂方法：创建一个垂直列布局的构建器。
+        :param options: 传递给模板的选项，如 gap, padding, align_items 等。
+        """
+        builder = cls()
+        builder._preset_template_name = "layouts/column"
+        builder._options.update(options)
+        return builder
+
+    @classmethod
+    def grid(cls, **options: Any) -> Self:
+        """
+        工厂方法：创建一个网格布局的构建器。
+        :param options: 传递给模板的选项，如 columns, gap, padding 等。
+        """
+        builder = cls()
+        builder._preset_template_name = "layouts/grid"
+        builder._options.update(options)
+        return builder
+
+    @classmethod
+    def vstack(cls, images: list[bytes], **options: Any) -> Self:
+        """
+        工厂方法：创建一个垂直堆叠布局的构建器，并直接添加图片。
+
+        参数:
+            images: 要垂直堆叠的图片字节流列表。
+            options: 传递给模板的选项，如 gap, padding, align_items 等。
+        """
+        builder = cls.column(**options)
+        for image_bytes in images:
+            builder.add_item(image_bytes)
+        return builder
+
+    @classmethod
+    def hstack(cls, images: list[bytes], **options: Any) -> Self:
+        """
+        工厂方法：创建一个水平堆叠布局的构建器，并直接添加图片。
+
+        参数:
+            images: 要水平堆叠的图片字节流列表。
+            options: 传递给模板的选项，如 gap, padding, align_items 等。
+        """
+        builder = cls()
+        builder._preset_template_name = "layouts/row"
+        builder._options.update(options)
+        for image_bytes in images:
+            builder.add_item(image_bytes)
+        return builder
+
+    def add_item(
+        self, image_bytes: bytes, metadata: dict[str, Any] | None = None
+    ) -> Self:
+        """
+        向布局中添加一个图片项目。
+        :param image_bytes: 图片的原始字节数据。
+        :param metadata: (可选) 与此项目关联的元数据，可用于模板。
+        """
+        b64_string = base64.b64encode(image_bytes).decode("utf-8")
+        src = f"data:image/png;base64,{b64_string}"
+        self._items.append(LayoutItem(src=src, metadata=metadata))
+        return self
+
+    def add_option(self, key: str, value: Any) -> Self:
+        """
+        为布局添加一个自定义选项，该选项会传递给模板。
+        """
+        self._options[key] = value
+        return self
+
+    async def build(
+        self, use_cache: bool = False, template: str | None = None, **render_options
+    ) -> bytes:
+        """
+        构建最终的布局图片。
+        :param use_cache: 是否使用缓存。
+        :param template: (可选) 强制使用指定的模板，覆盖工厂方法的预设。
+                         这是实现自定义布局的关键。
+        :param render_options: 传递给渲染引擎的额外选项。
+        """
+        final_template_name = template or self._preset_template_name
+
+        if not final_template_name:
+            raise ValueError(
+                "必须通过工厂方法 (如 LayoutBuilder.column()) 或在 build() "
+                "方法中提供一个模板名称。"
+            )
+
+        self._data.items = self._items
+        self._data.options = self._options
+        self._template_name = final_template_name
+
+        return await super().build(use_cache=use_cache, **render_options)

zhenxun/ui/builders/core/markdown.py

@@ -0,0 +1,149 @@
+from contextlib import AbstractContextManager
+from pathlib import Path
+from typing import Any
+
+from ...models.core.markdown import (
+    CodeElement,
+    HeadingElement,
+    ImageElement,
+    ListElement,
+    ListItemElement,
+    MarkdownData,
+    MarkdownElement,
+    QuoteElement,
+    RawHtmlElement,
+    TableElement,
+    TextElement,
+)
+from ..base import BaseBuilder
+
+__all__ = ["MarkdownBuilder"]
+
+
+class MarkdownBuilder(BaseBuilder[MarkdownData]):
+    """链式构建Markdown图片的辅助类，支持上下文管理和组合。"""
+
+    def __init__(self):
+        data_model = MarkdownData(markdown="", width=800, css_path=None)
+        super().__init__(data_model, template_name="components/core/markdown")
+        self._parts: list[MarkdownElement] = []
+        self._width: int = 800
+        self._css_path: str | None = None
+        self._context_stack: list[QuoteElement | ListElement | ListItemElement] = []
+
+    def _append_element(self, element: MarkdownElement):
+        """内部方法，根据上下文将元素添加到正确的位置。"""
+        if self._context_stack:
+            self._context_stack[-1].content.append(element)
+        else:
+            self._parts.append(element)
+        return self
+
+    def text(self, text: str) -> "MarkdownBuilder":
+        """添加Markdown文本"""
+        self._append_element(TextElement(text=text))
+        return self
+
+    def head(self, text: str, level: int = 1) -> "MarkdownBuilder":
+        """添加Markdown标题"""
+        self._append_element(HeadingElement(text=text, level=level))
+        return self
+
+    def image(self, content: str | Path, alt: str = "image") -> "MarkdownBuilder":
+        """添加Markdown图片"""
+        src = ""
+        if isinstance(content, Path):
+            src = content.absolute().as_uri()
+        elif content.startswith("base64://"):
+            src = f"data:image/png;base64,{content.split('base64://', 1)[-1]}"
+        else:
+            src = content
+        self._append_element(ImageElement(src=src, alt=alt))
+        return self
+
+    def code(self, code: str, language: str = "") -> "MarkdownBuilder":
+        """添加Markdown代码块"""
+        self._append_element(CodeElement(code=code, language=language))
+        return self
+
+    def table(
+        self,
+        headers: list[str],
+        rows: list[list[str]],
+        alignments: list[Any] | None = None,
+    ) -> "MarkdownBuilder":
+        """添加Markdown表格"""
+        self._append_element(
+            TableElement(headers=headers, rows=rows, alignments=alignments)
+        )
+        return self
+
+    def add_builder(self, builder: "MarkdownBuilder") -> "MarkdownBuilder":
+        """将另一个builder的内容组合进来。"""
+        if self._context_stack:
+            self._context_stack[-1].content.extend(builder._parts)
+        else:
+            self._parts.extend(builder._parts)
+        return self
+
+    def quote(self) -> AbstractContextManager["MarkdownBuilder"]:
+        """创建一个引用块上下文。"""
+        return self._context_for(QuoteElement())
+
+    def list(self, ordered: bool = False) -> AbstractContextManager["MarkdownBuilder"]:
+        """创建一个列表上下文。"""
+        return self._context_for(ListElement(ordered=ordered))
+
+    def list_item(self) -> AbstractContextManager["MarkdownBuilder"]:
+        """在列表上下文中创建一个列表项。"""
+        if not self._context_stack or not isinstance(
+            self._context_stack[-1], ListElement
+        ):
+            raise TypeError("list_item() 只能在 list() 上下文中使用。")
+        return self._context_for(ListItemElement())
+
+    class _ContextManager:
+        def __init__(
+            self,
+            builder: "MarkdownBuilder",
+            element: QuoteElement | ListElement | ListItemElement,
+        ):
+            self.builder = builder
+            self.element = element
+
+        def __enter__(self):
+            self.builder._context_stack.append(self.element)
+            return self.builder
+
+        def __exit__(self, exc_type, exc_val, exc_tb):
+            del exc_type, exc_val, exc_tb
+            self.builder._context_stack.pop()
+
+    def _context_for(
+        self, element: QuoteElement | ListElement | ListItemElement
+    ) -> AbstractContextManager["MarkdownBuilder"]:
+        self._append_element(element)
+        return self._ContextManager(self, element)
+
+    def set_width(self, width: int) -> "MarkdownBuilder":
+        """设置图片宽度"""
+        self._width = width
+        return self
+
+    def set_css_path(self, css_path: str) -> "MarkdownBuilder":
+        """设置CSS样式路径"""
+        self._css_path = css_path
+        return self
+
+    def add_divider(self) -> "MarkdownBuilder":
+        """添加一条标准的 Markdown 分割线。"""
+        self._append_element(RawHtmlElement(html="---"))
+        return self
+
+    async def build(self, use_cache: bool = False, **render_options) -> bytes:
+        """构建Markdown图片"""
+        final_markdown = "\n\n".join(part.to_markdown() for part in self._parts).strip()
+        self._data.markdown = final_markdown
+        self._data.width = self._width
+        self._data.css_path = self._css_path
+        return await super().build(use_cache=use_cache, **render_options)

zhenxun/ui/builders/core/notebook.py

@@ -0,0 +1,107 @@
+import builtins
+from pathlib import Path
+
+from ...models.core.base import RenderableComponent
+from ...models.core.notebook import NotebookData, NotebookElement
+from ..base import BaseBuilder
+
+__all__ = ["NotebookBuilder"]
+
+
+class NotebookBuilder(BaseBuilder[NotebookData]):
+    """
+    一个用于链式构建 Notebook 页面的辅助类。
+    """
+
+    def __init__(self, data: list[NotebookElement] | None = None):
+        elements = data if data is not None else []
+        data_model = NotebookData(elements=elements)
+        super().__init__(data_model, template_name="components/core/notebook")
+        self._elements = elements
+
+    def text(self, text: str) -> "NotebookBuilder":
+        """添加Notebook文本"""
+        self._elements.append(NotebookElement(type="paragraph", text=text))
+        return self
+
+    def head(self, text: str, level: int = 1) -> "NotebookBuilder":
+        """添加Notebook标题"""
+        if not 1 <= level <= 4:
+            raise ValueError("标题级别必须在1-4之间")
+        self._elements.append(NotebookElement(type="heading", text=text, level=level))
+        return self
+
+    def image(
+        self,
+        content: str,
+        caption: str | None = None,
+    ) -> "NotebookBuilder":
+        """添加Notebook图片"""
+        src = ""
+        if isinstance(content, Path):
+            src = content.absolute().as_uri()
+        elif content.startswith("base64"):
+            src = f"data:image/png;base64,{content.split('base64://', 1)[-1]}"
+        else:
+            src = content
+        self._elements.append(NotebookElement(type="image", src=src, caption=caption))
+        return self
+
+    def quote(self, text: str | list[str]) -> "NotebookBuilder":
+        """添加Notebook引用文本"""
+        if isinstance(text, str):
+            self._elements.append(NotebookElement(type="blockquote", text=text))
+        elif isinstance(text, list):
+            for t in text:
+                self._elements.append(NotebookElement(type="blockquote", text=t))
+        return self
+
+    def code(self, code: str, language: str = "python") -> "NotebookBuilder":
+        """添加Notebook代码块"""
+        self._elements.append(
+            NotebookElement(type="code", code=code, language=language)
+        )
+        return self
+
+    def list(self, items: list[str], ordered: bool = False) -> "NotebookBuilder":
+        """添加Notebook列表"""
+        self._elements.append(NotebookElement(type="list", data=items, ordered=ordered))
+        return self
+
+    def add_divider(self, **kwargs) -> "NotebookBuilder":
+        """
+        添加分隔线。
+        :param kwargs: Divider组件的可选参数, 如 margin, color, style, thickness。
+        """
+        from ...models.components import Divider
+
+        self.add_component(Divider(**kwargs))
+        return self
+
+    def add_component(self, component: RenderableComponent) -> "NotebookBuilder":
+        """向 Notebook 中添加一个可渲染的自定义组件。"""
+        self._elements.append(
+            NotebookElement(type="component", component_data=component)
+        )
+        return self
+
+    def add_texts(self, texts: builtins.list[str]) -> "NotebookBuilder":
+        """批量添加多个文本段落"""
+        for text in texts:
+            self.text(text)
+        return self
+
+    def add_quotes(self, quotes: builtins.list[str]) -> "NotebookBuilder":
+        """批量添加引用"""
+        for quote in quotes:
+            self.quote(quote)
+        return self
+
+    async def build(
+        self, use_cache: bool = False, frameless: bool = False, **render_options
+    ) -> bytes:
+        """构建Notebook图片"""
+        self._data.elements = self._elements
+        return await super().build(
+            use_cache=use_cache, frameless=frameless, **render_options
+        )

zhenxun/ui/builders/core/table.py

@@ -0,0 +1,27 @@
+from ...models.core.table import TableCell, TableData
+from ..base import BaseBuilder
+
+__all__ = ["TableBuilder"]
+
+
+class TableBuilder(BaseBuilder[TableData]):
+    """链式构建通用表格的辅助类"""
+
+    def __init__(self, title: str, tip: str | None = None):
+        data_model = TableData(title=title, tip=tip, headers=[], rows=[])
+        super().__init__(data_model, template_name="components/core/table")
+
+    def set_headers(self, headers: list[str]) -> "TableBuilder":
+        """设置表头"""
+        self._data.headers = headers
+        return self
+
+    def add_row(self, row: list[TableCell]) -> "TableBuilder":
+        """添加单行数据"""
+        self._data.rows.append(row)
+        return self
+
+    def add_rows(self, rows: list[list[TableCell]]) -> "TableBuilder":
+        """批量添加多行数据"""
+        self._data.rows.extend(rows)
+        return self

zhenxun/ui/builders/presets/__init__.py

@@ -0,0 +1,14 @@
+"""
+预设构建器模块
+包含预定义的UI组件构建器
+"""
+
+from .help_page import PluginHelpPageBuilder
+from .info_card import InfoCardBuilder
+from .plugin_menu import PluginMenuBuilder
+
+__all__ = [
+    "InfoCardBuilder",
+    "PluginHelpPageBuilder",
+    "PluginMenuBuilder",
+]

zhenxun/ui/builders/presets/help_page.py

@@ -0,0 +1,27 @@
+from ...models.presets.help_page import (
+    HelpCategory,
+    PluginHelpPageData,
+)
+from ..base import BaseBuilder
+
+
+class PluginHelpPageBuilder(BaseBuilder[PluginHelpPageData]):
+    """链式构建插件帮助页面的辅助类"""
+
+    def __init__(self, bot_nickname: str, page_title: str):
+        self._data = PluginHelpPageData(
+            bot_nickname=bot_nickname, page_title=page_title, categories=[]
+        )
+
+        super().__init__(self._data, template_name="pages/core/help_page")
+
+    def add_category(self, category: HelpCategory) -> "PluginHelpPageBuilder":
+        """添加一个帮助分类"""
+        self._data.categories.append(category)
+        return self
+
+    def add_categories(self, categories: list[HelpCategory]) -> "PluginHelpPageBuilder":
+        """批量添加帮助分类"""
+        for category in categories:
+            self.add_category(category)
+        return self

zhenxun/ui/builders/presets/info_card.py

@@ -0,0 +1,46 @@
+from typing import Any
+
+from ...models.presets.card import (
+    InfoCardData,
+    InfoCardMetadataItem,
+    InfoCardSection,
+)
+from ..base import BaseBuilder
+
+__all__ = ["InfoCardBuilder"]
+
+
+class InfoCardBuilder(BaseBuilder[InfoCardData]):
+    def __init__(self, title: str):
+        self._data = InfoCardData(title=title)
+
+        super().__init__(self._data, template_name="components/presets/info_card")
+
+    def add_metadata(self, label: str, value: str | int) -> "InfoCardBuilder":
+        self._data.metadata.append(InfoCardMetadataItem(label=label, value=value))
+        return self
+
+    def add_metadata_items(
+        self, items: list[tuple[str, Any]] | list[dict[str, Any]]
+    ) -> "InfoCardBuilder":
+        for item in items:
+            if isinstance(item, tuple):
+                self.add_metadata(item[0], item[1])
+            elif isinstance(item, dict):
+                self.add_metadata(item.get("label", ""), item.get("value", ""))
+        return self
+
+    def add_section(self, title: str, content: str | list[str]) -> "InfoCardBuilder":
+        content_list = [content] if isinstance(content, str) else content
+        self._data.sections.append(InfoCardSection(title=title, content=content_list))
+        return self
+
+    def add_sections(
+        self, sections: list[tuple[str, str | list[str]]] | list[dict[str, Any]]
+    ) -> "InfoCardBuilder":
+        for section in sections:
+            if isinstance(section, tuple):
+                self.add_section(section[0], section[1])
+            elif isinstance(section, dict):
+                self.add_section(section.get("title", ""), section.get("content", []))
+        return self

zhenxun/ui/builders/presets/plugin_menu.py

@@ -0,0 +1,36 @@
+from ...models.presets.plugin_menu import (
+    PluginMenuCategory,
+    PluginMenuData,
+)
+from ..base import BaseBuilder
+
+__all__ = ["PluginMenuBuilder"]
+
+
+class PluginMenuBuilder(BaseBuilder[PluginMenuData]):
+    """链式构建插件菜单的辅助类"""
+
+    def __init__(self, bot_name: str, bot_avatar_url: str, is_detail: bool = False):
+        self._data = PluginMenuData(
+            bot_name=bot_name,
+            bot_avatar_url=bot_avatar_url,
+            is_detail=is_detail,
+            plugin_count=0,
+            active_count=0,
+            categories=[],
+        )
+
+        super().__init__(self._data, template_name="pages/core/plugin_menu")
+
+    def add_category(self, category: PluginMenuCategory) -> "PluginMenuBuilder":
+        self._data.categories.append(category)
+        self._data.plugin_count += len(category.items)
+        self._data.active_count += sum(1 for item in category.items if item.status)
+        return self
+
+    def add_categories(
+        self, categories: list[PluginMenuCategory]
+    ) -> "PluginMenuBuilder":
+        for category in categories:
+            self.add_category(category)
+        return self

zhenxun/ui/builders/widgets/__init__.py

@@ -0,0 +1,14 @@
+"""
+小组件构建器模块
+包含各种UI小组件的构建器
+"""
+
+from .badge import BadgeBuilder
+from .progress_bar import ProgressBarBuilder
+from .user_info_block import UserInfoBlockBuilder
+
+__all__ = [
+    "BadgeBuilder",
+    "ProgressBarBuilder",
+    "UserInfoBlockBuilder",
+]

zhenxun/ui/builders/widgets/badge.py

@@ -0,0 +1,25 @@
+from typing import Literal
+
+from ...models.components.badge import Badge
+from ..base import BaseBuilder
+
+
+class BadgeBuilder(BaseBuilder[Badge]):
+    """链式构建徽章组件的辅助类"""
+
+    def __init__(
+        self,
+        text: str,
+        color_scheme: Literal[
+            "primary", "success", "warning", "error", "info"
+        ] = "info",
+    ):
+        data_model = Badge(text=text, color_scheme=color_scheme)
+        super().__init__(data_model, template_name="components/widgets/badge")
+
+    def set_color_scheme(
+        self, color_scheme: Literal["primary", "success", "warning", "error", "info"]
+    ) -> "BadgeBuilder":
+        """设置徽章的颜色方案。"""
+        self._data.color_scheme = color_scheme
+        return self

zhenxun/ui/builders/widgets/progress_bar.py

@@ -0,0 +1,42 @@
+from typing import Literal
+
+from ...models.components.progress_bar import ProgressBar
+from ..base import BaseBuilder
+
+
+class ProgressBarBuilder(BaseBuilder[ProgressBar]):
+    """链式构建进度条组件的辅助类"""
+
+    def __init__(
+        self,
+        progress: float,
+        label: str | None = None,
+        color_scheme: Literal[
+            "primary", "success", "warning", "error", "info"
+        ] = "primary",
+        animated: bool = False,
+    ):
+        data_model = ProgressBar(
+            progress=progress,
+            label=label,
+            color_scheme=color_scheme,
+            animated=animated,
+        )
+        super().__init__(data_model, template_name="components/widgets/progress_bar")
+
+    def set_label(self, label: str) -> "ProgressBarBuilder":
+        """设置进度条上显示的文本。"""
+        self._data.label = label
+        return self
+
+    def set_color_scheme(
+        self, color_scheme: Literal["primary", "success", "warning", "error", "info"]
+    ) -> "ProgressBarBuilder":
+        """设置进度条的颜色方案。"""
+        self._data.color_scheme = color_scheme
+        return self
+
+    def set_animated(self, animated: bool = True) -> "ProgressBarBuilder":
+        """设置进度条是否显示动画效果。"""
+        self._data.animated = animated
+        return self

zhenxun/ui/builders/widgets/user_info_block.py

@@ -0,0 +1,33 @@
+from ...models.components.user_info_block import UserInfoBlock
+from ..base import BaseBuilder
+
+
+class UserInfoBlockBuilder(BaseBuilder[UserInfoBlock]):
+    """链式构建用户信息块的辅助类"""
+
+    def __init__(
+        self,
+        name: str,
+        avatar_url: str,
+        subtitle: str | None = None,
+        tags: list[str] | None = None,
+    ):
+        data_model = UserInfoBlock(
+            name=name, avatar_url=avatar_url, subtitle=subtitle, tags=tags or []
+        )
+        super().__init__(data_model, template_name="components/widgets/user_info_block")
+
+    def set_subtitle(self, subtitle: str) -> "UserInfoBlockBuilder":
+        """设置副标题。"""
+        self._data.subtitle = subtitle
+        return self
+
+    def add_tag(self, tag: str) -> "UserInfoBlockBuilder":
+        """添加一个标签。"""
+        self._data.tags.append(tag)
+        return self
+
+    def add_tags(self, tags: list[str]) -> "UserInfoBlockBuilder":
+        """批量添加标签。"""
+        self._data.tags.extend(tags)
+        return self

zhenxun/ui/models/__init__.py

@@ -0,0 +1,84 @@
+from .charts import (
+    BarChartData,
+    BaseChartData,
+    LineChartData,
+    LineChartSeries,
+    PieChartData,
+    PieChartDataItem,
+)
+from .components.badge import Badge
+from .components.divider import Divider, Rectangle
+from .components.progress_bar import ProgressBar
+from .components.user_info_block import UserInfoBlock
+from .core.base import RenderableComponent
+from .core.layout import LayoutData, LayoutItem
+from .core.markdown import (
+    CodeElement,
+    HeadingElement,
+    ImageElement,
+    ListElement,
+    ListItemElement,
+    MarkdownData,
+    MarkdownElement,
+    QuoteElement,
+    RawHtmlElement,
+    TableElement,
+    TextElement,
+)
+from .core.notebook import NotebookData, NotebookElement
+from .core.table import (
+    BaseCell,
+    ImageCell,
+    StatusBadgeCell,
+    TableCell,
+    TableData,
+    TextCell,
+)
+from .presets.card import InfoCardData, InfoCardMetadataItem, InfoCardSection
+from .presets.help_page import HelpCategory, HelpItem, PluginHelpPageData
+from .presets.plugin_menu import PluginMenuCategory, PluginMenuData, PluginMenuItem
+
+__all__ = [
+    "Badge",
+    "BarChartData",
+    "BaseCell",
+    "BaseChartData",
+    "CodeElement",
+    "Divider",
+    "HeadingElement",
+    "HelpCategory",
+    "HelpItem",
+    "ImageCell",
+    "ImageElement",
+    "InfoCardData",
+    "InfoCardMetadataItem",
+    "InfoCardSection",
+    "LayoutData",
+    "LayoutItem",
+    "LineChartData",
+    "LineChartSeries",
+    "ListElement",
+    "ListItemElement",
+    "MarkdownData",
+    "MarkdownElement",
+    "NotebookData",
+    "NotebookElement",
+    "PieChartData",
+    "PieChartDataItem",
+    "PluginHelpPageData",
+    "PluginMenuCategory",
+    "PluginMenuData",
+    "PluginMenuItem",
+    "ProgressBar",
+    "QuoteElement",
+    "RawHtmlElement",
+    "Rectangle",
+    "RenderableComponent",
+    "StatusBadgeCell",
+    "TableCell",
+    "TableData",
+    "TableElement",
+    "TextCell",
+    "TextElement",
+    "UserInfoBlock",
+]

zhenxun/ui/models/charts.py

@@ -0,0 +1,43 @@
+from typing import Literal
+
+from pydantic import BaseModel
+
+
+class BaseChartData(BaseModel):
+    """所有图表数据模型的基类"""
+
+    style_name: str | None = None
+    title: str
+
+
+class BarChartData(BaseChartData):
+    """柱状图（支持横向和竖向）的数据模型"""
+
+    category_data: list[str]
+    data: list[int | float]
+    direction: Literal["horizontal", "vertical"] = "horizontal"
+    background_image: str | None = None
+
+
+class PieChartDataItem(BaseModel):
+    name: str
+    value: int | float
+
+
+class PieChartData(BaseChartData):
+    """饼图的数据模型"""
+
+    data: list[PieChartDataItem]
+
+
+class LineChartSeries(BaseModel):
+    name: str
+    data: list[int | float]
+    smooth: bool = False
+
+
+class LineChartData(BaseChartData):
+    """折线图的数据模型"""
+
+    category_data: list[str]
+    series: list[LineChartSeries]

zhenxun/ui/models/components/__init__.py

@@ -0,0 +1,17 @@
+"""
+组件模型模块
+包含各种UI组件的数据模型
+"""
+
+from .badge import Badge
+from .divider import Divider, Rectangle
+from .progress_bar import ProgressBar
+from .user_info_block import UserInfoBlock
+
+__all__ = [
+    "Badge",
+    "Divider",
+    "ProgressBar",
+    "Rectangle",
+    "UserInfoBlock",
+]

zhenxun/ui/models/components/badge.py

@@ -0,0 +1,22 @@
+from typing import Literal
+
+from pydantic import Field
+
+from ..core.base import RenderableComponent
+
+__all__ = ["Badge"]
+
+
+class Badge(RenderableComponent):
+    """一个简单的徽章组件，用于显示状态或标签。"""
+
+    component_type: Literal["badge"] = "badge"
+    text: str = Field(..., description="徽章上显示的文本")
+    color_scheme: Literal["primary", "success", "warning", "error", "info"] = Field(
+        default="info",
+        description="预设的颜色方案",
+    )
+
+    @property
+    def template_name(self) -> str:
+        return "components/widgets/badge/main.html"

zhenxun/ui/models/components/divider.py

@@ -0,0 +1,35 @@
+from typing import Literal
+
+from pydantic import Field
+
+from ..core.base import RenderableComponent
+
+__all__ = ["Divider", "Rectangle"]
+
+
+class Divider(RenderableComponent):
+    """一个简单的分割线组件。"""
+
+    component_type: Literal["divider"] = "divider"
+    margin: str = Field("2em 0", description="CSS margin属性，控制分割线上下的间距")
+    color: str = Field("#f7889c", description="分割线颜色")
+    style: Literal["solid", "dashed", "dotted"] = Field("solid", description="线条样式")
+    thickness: str = Field("1px", description="线条粗细")
+
+    @property
+    def template_name(self) -> str:
+        return "components/widgets/divider/main.html"
+
+
+class Rectangle(RenderableComponent):
+    """一个矩形背景块组件。"""
+
+    component_type: Literal["rectangle"] = "rectangle"
+    height: str = Field("50px", description="矩形的高度 (CSS value)")
+    background_color: str = Field("#fdf1f5", description="背景颜色")
+    border: str = Field("1px solid #fce4ec", description="CSS border属性")
+    border_radius: str = Field("8px", description="CSS border-radius属性")
+
+    @property
+    def template_name(self) -> str:
+        return "components/widgets/rectangle/main.html"

zhenxun/ui/models/components/progress_bar.py

@@ -0,0 +1,24 @@
+from typing import Literal
+
+from pydantic import Field
+
+from ..core.base import RenderableComponent
+
+__all__ = ["ProgressBar"]
+
+
+class ProgressBar(RenderableComponent):
+    """一个进度条组件。"""
+
+    component_type: Literal["progress_bar"] = "progress_bar"
+    progress: float = Field(..., ge=0, le=100, description="进度百分比 (0-100)")
+    label: str | None = Field(default=None, description="显示在进度条上的可选文本")
+    color_scheme: Literal["primary", "success", "warning", "error", "info"] = Field(
+        default="primary",
+        description="预设的颜色方案",
+    )
+    animated: bool = Field(default=False, description="是否显示动画效果")
+
+    @property
+    def template_name(self) -> str:
+        return "components/widgets/progress_bar/main.html"

zhenxun/ui/models/components/user_info_block.py

@@ -0,0 +1,23 @@
+from typing import Literal
+
+from pydantic import Field
+
+from ..core.base import RenderableComponent
+
+__all__ = ["UserInfoBlock"]
+
+
+class UserInfoBlock(RenderableComponent):
+    """一个带头像、名称和副标题的用户信息块组件。"""
+
+    component_type: Literal["user_info_block"] = "user_info_block"
+    avatar_url: str = Field(..., description="用户头像的URL")
+    name: str = Field(..., description="用户的名称")
+    subtitle: str | None = Field(
+        default=None, description="显示在名称下方的副标题 (如UID或角色)"
+    )
+    tags: list[str] = Field(default_factory=list, description="附加的标签列表")
+
+    @property
+    def template_name(self) -> str:
+        return "components/widgets/user_info_block/main.html"

zhenxun/ui/models/core/__init__.py

@@ -0,0 +1,47 @@
+"""
+核心模型模块
+包含基础的数据模型类
+"""
+
+from .base import RenderableComponent
+from .layout import LayoutData, LayoutItem
+from .markdown import (
+    CodeElement,
+    HeadingElement,
+    ImageElement,
+    ListElement,
+    ListItemElement,
+    MarkdownData,
+    MarkdownElement,
+    QuoteElement,
+    RawHtmlElement,
+    TableElement,
+    TextElement,
+)
+from .notebook import NotebookData, NotebookElement
+from .table import BaseCell, ImageCell, StatusBadgeCell, TableCell, TableData, TextCell
+
+__all__ = [
+    "BaseCell",
+    "CodeElement",
+    "HeadingElement",
+    "ImageCell",
+    "ImageElement",
+    "LayoutData",
+    "LayoutItem",
+    "ListElement",
+    "ListItemElement",
+    "MarkdownData",
+    "MarkdownElement",
+    "NotebookData",
+    "NotebookElement",
+    "QuoteElement",
+    "RawHtmlElement",
+    "RenderableComponent",
+    "StatusBadgeCell",
+    "TableCell",
+    "TableData",
+    "TableElement",
+    "TextCell",
+    "TextElement",
+]

zhenxun/ui/models/core/base.py

@@ -0,0 +1,20 @@
+"""
+核心基础模型定义
+用于存放 RenderableComponent 基类
+"""
+
+from abc import ABC, abstractmethod
+
+from pydantic import BaseModel
+
+__all__ = ["RenderableComponent"]
+
+
+class RenderableComponent(BaseModel, ABC):
+    """所有可渲染UI组件的抽象基类。"""
+
+    @property
+    @abstractmethod
+    def template_name(self) -> str:
+        """返回用于渲染此组件的Jinja2模板的路径。"""
+        pass

zhenxun/ui/models/core/layout.py

@@ -0,0 +1,24 @@
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+__all__ = ["LayoutData", "LayoutItem"]
+
+
+class LayoutItem(BaseModel):
+    """布局中的单个项目，通常是一张图片"""
+
+    src: str = Field(..., description="图片的Base64数据URI")
+    metadata: dict[str, Any] | None = Field(None, description="传递给模板的额外元数据")
+
+
+class LayoutData(BaseModel):
+    """布局构建器的数据模型"""
+
+    style_name: str | None = None
+    items: list[LayoutItem] = Field(
+        default_factory=list, description="要布局的项目列表"
+    )
+    options: dict[str, Any] = Field(
+        default_factory=dict, description="传递给模板的布局选项"
+    )

zhenxun/ui/models/core/markdown.py

@@ -0,0 +1,124 @@
+from abc import ABC, abstractmethod
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+__all__ = [
+    "CodeElement",
+    "HeadingElement",
+    "ImageElement",
+    "ListElement",
+    "ListItemElement",
+    "MarkdownData",
+    "MarkdownElement",
+    "QuoteElement",
+    "RawHtmlElement",
+    "TableElement",
+    "TextElement",
+]
+
+
+class MarkdownElement(BaseModel, ABC):
+    @abstractmethod
+    def to_markdown(self) -> str:
+        """Serializes the element to its Markdown string representation."""
+        pass
+
+
+class TextElement(MarkdownElement):
+    text: str
+
+    def to_markdown(self) -> str:
+        return self.text
+
+
+class HeadingElement(MarkdownElement):
+    text: str
+    level: int = Field(..., ge=1, le=6)
+
+    def to_markdown(self) -> str:
+        return f"{'#' * self.level} {self.text}"
+
+
+class ImageElement(MarkdownElement):
+    src: str
+    alt: str = "image"
+
+    def to_markdown(self) -> str:
+        return f"![{self.alt}]({self.src})"
+
+
+class CodeElement(MarkdownElement):
+    code: str
+    language: str = ""
+
+    def to_markdown(self) -> str:
+        return f"```{self.language}\n{self.code}\n```"
+
+
+class RawHtmlElement(MarkdownElement):
+    html: str
+
+    def to_markdown(self) -> str:
+        return self.html
+
+
+class TableElement(MarkdownElement):
+    headers: list[str]
+    rows: list[list[str]]
+    alignments: list[Literal["left", "center", "right"]] | None = None
+
+    def to_markdown(self) -> str:
+        header_row = "| " + " | ".join(self.headers) + " |"
+
+        if self.alignments:
+            align_map = {"left": ":---", "center": ":---:", "right": "---:"}
+            separator_row = (
+                "| "
+                + " | ".join([align_map.get(a, "---") for a in self.alignments])
+                + " |"
+            )
+        else:
+            separator_row = "| " + " | ".join(["---"] * len(self.headers)) + " |"
+
+        data_rows = "\n".join(
+            "| " + " | ".join(map(str, row)) + " |" for row in self.rows
+        )
+        return f"{header_row}\n{separator_row}\n{data_rows}"
+
+
+class ContainerElement(MarkdownElement):
+    content: list[MarkdownElement] = Field(default_factory=list)
+
+
+class QuoteElement(ContainerElement):
+    def to_markdown(self) -> str:
+        inner_md = "\n".join(part.to_markdown() for part in self.content)
+        return "\n".join([f"> {line}" for line in inner_md.split("\n")])
+
+
+class ListItemElement(ContainerElement):
+    def to_markdown(self) -> str:
+        return "\n".join(part.to_markdown() for part in self.content)
+
+
+class ListElement(ContainerElement):
+    ordered: bool = False
+
+    def to_markdown(self) -> str:
+        lines = []
+        for i, item in enumerate(self.content):
+            if isinstance(item, ListItemElement):
+                prefix = f"{i + 1}." if self.ordered else "*"
+                item_content = item.to_markdown()
+                lines.append(f"{prefix} {item_content}")
+        return "\n".join(lines)
+
+
+class MarkdownData(BaseModel):
+    """Markdown转图片的数据模型"""
+
+    style_name: str | None = None
+    markdown: str
+    width: int = 800
+    css_path: str | None = None

zhenxun/ui/models/core/notebook.py

@@ -0,0 +1,38 @@
+from typing import Literal
+
+from pydantic import BaseModel
+
+from .base import RenderableComponent
+
+__all__ = ["NotebookData", "NotebookElement"]
+
+
+class NotebookElement(BaseModel):
+    """一个 Notebook 页面中的单个元素"""
+
+    type: Literal[
+        "heading",
+        "paragraph",
+        "image",
+        "blockquote",
+        "code",
+        "list",
+        "divider",
+        "component",
+    ]
+    text: str | None = None
+    level: int | None = None
+    src: str | None = None
+    caption: str | None = None
+    code: str | None = None
+    language: str | None = None
+    data: list[str] | None = None
+    ordered: bool | None = None
+    component_data: RenderableComponent | None = None
+
+
+class NotebookData(BaseModel):
+    """Notebook转图片的数据模型"""
+
+    style_name: str | None = None
+    elements: list[NotebookElement]

zhenxun/ui/models/core/table.py

@@ -0,0 +1,59 @@
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+__all__ = [
+    "BaseCell",
+    "ImageCell",
+    "StatusBadgeCell",
+    "TableCell",
+    "TableData",
+    "TextCell",
+]
+
+
+class BaseCell(BaseModel):
+    """单元格基础模型"""
+
+    type: str
+
+
+class TextCell(BaseCell):
+    """文本单元格"""
+
+    type: Literal["text"] = "text"  # type: ignore
+    content: str
+    bold: bool = False
+    color: str | None = None
+
+
+class ImageCell(BaseCell):
+    """图片单元格"""
+
+    type: Literal["image"] = "image"  # type: ignore
+    src: str
+    width: int = 40
+    height: int = 40
+    shape: Literal["square", "circle"] = "square"
+    alt: str = "image"
+
+
+class StatusBadgeCell(BaseCell):
+    """状态徽章单元格"""
+
+    type: Literal["badge"] = "badge"  # type: ignore
+    text: str
+    status_type: Literal["ok", "error", "warning", "info"] = "info"
+
+
+TableCell = TextCell | ImageCell | StatusBadgeCell | str | int | float | None
+
+
+class TableData(BaseModel):
+    """通用表格的数据模型"""
+
+    style_name: str | None = None
+    title: str = Field(..., description="表格主标题")
+    tip: str | None = Field(None, description="表格下方的提示信息")
+    headers: list[str] = Field(default_factory=list, description="表头列表")
+    rows: list[list[TableCell]] = Field(default_factory=list, description="数据行列表")

zhenxun/ui/models/presets/__init__.py

@@ -0,0 +1,20 @@
+"""
+预设模型模块
+包含预定义的复合组件数据模型
+"""
+
+from .card import InfoCardData, InfoCardMetadataItem, InfoCardSection
+from .help_page import HelpCategory, HelpItem, PluginHelpPageData
+from .plugin_menu import PluginMenuCategory, PluginMenuData, PluginMenuItem
+
+__all__ = [
+    "HelpCategory",
+    "HelpItem",
+    "InfoCardData",
+    "InfoCardMetadataItem",
+    "InfoCardSection",
+    "PluginHelpPageData",
+    "PluginMenuCategory",
+    "PluginMenuData",
+    "PluginMenuItem",
+]

zhenxun/ui/models/presets/card.py

@@ -0,0 +1,37 @@
+from pydantic import BaseModel, Field
+
+from ..core.base import RenderableComponent
+
+__all__ = [
+    "InfoCardData",
+    "InfoCardMetadataItem",
+    "InfoCardSection",
+]
+
+
+class InfoCardMetadataItem(BaseModel):
+    """信息卡片元数据项"""
+
+    label: str
+    value: str | int
+
+
+class InfoCardSection(BaseModel):
+    """信息卡片内容区块"""
+
+    title: str
+    content: list[str] = Field(..., description="内容段落列表")
+
+
+class InfoCardData(RenderableComponent):
+    """通用信息卡片的数据模型"""
+
+    style_name: str | None = None
+    title: str = Field(..., description="卡片主标题")
+    metadata: list[InfoCardMetadataItem] = Field(default_factory=list)
+    sections: list[InfoCardSection] = Field(default_factory=list)
+
+    @property
+    def template_name(self) -> str:
+        """返回用于渲染此组件的Jinja2模板的路径。"""
+        return "components/presets/info_card/main.html"

zhenxun/ui/models/presets/help_page.py

@@ -0,0 +1,38 @@
+from pydantic import BaseModel
+
+from ..core.base import RenderableComponent
+
+__all__ = [
+    "HelpCategory",
+    "HelpItem",
+    "PluginHelpPageData",
+]
+
+
+class HelpItem(BaseModel):
+    """帮助菜单中的单个功能项"""
+
+    name: str
+    description: str
+    usage: str
+
+
+class HelpCategory(BaseModel):
+    """帮助菜单中的一个功能类别"""
+
+    title: str
+    icon_svg_path: str
+    items: list[HelpItem]
+
+
+class PluginHelpPageData(RenderableComponent):
+    """通用插件帮助页面的数据模型"""
+
+    style_name: str | None = None
+    bot_nickname: str
+    page_title: str
+    categories: list[HelpCategory]
+
+    @property
+    def template_name(self) -> str:
+        return "pages/core/help_page/main.html"

zhenxun/ui/models/presets/plugin_menu.py

@@ -0,0 +1,42 @@
+from pydantic import BaseModel, Field
+
+from ..core.base import RenderableComponent
+
+__all__ = [
+    "PluginMenuCategory",
+    "PluginMenuData",
+    "PluginMenuItem",
+]
+
+
+class PluginMenuItem(BaseModel):
+    """插件菜单中的单个插件项"""
+
+    id: str
+    name: str
+    status: bool
+    has_superuser_help: bool
+    commands: list[str] = Field(default_factory=list)
+
+
+class PluginMenuCategory(BaseModel):
+    """插件菜单中的一个分类"""
+
+    name: str
+    items: list[PluginMenuItem]
+
+
+class PluginMenuData(RenderableComponent):
+    """通用插件帮助菜单的数据模型"""
+
+    style_name: str | None = None
+    bot_name: str
+    bot_avatar_url: str
+    is_detail: bool
+    plugin_count: int
+    active_count: int
+    categories: list[PluginMenuCategory]
+
+    @property
+    def template_name(self) -> str:
+        return "pages/core/plugin_menu/main.html"