♻️ 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/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