♻️ refactor(UI): 重构UI渲染服务为组件化分层架构 (#2025)

* ♻️ refactor(UI): 重构UI渲染服务为组件化分层架构

♻️ **架构重构**
- UI渲染服务重构为组件化分层架构
- 解耦主题管理、HTML生成、截图功能

✨ **新增功能**
- `zhenxun.ui` 统一入口，提供 `render`、`markdown`、`vstack` 等API
- `RenderableComponent` 基类和渲染协议抽象
- 新增主题管理器和截图引擎模块

⚙️ **配置优化**
- UI配置迁移至 `superuser/ui_manager.py`
- 新增"重载UI主题"管理指令

🔧 **性能改进**
- 优化渲染缓存，支持组件级透明缓存
- 所有UI组件适配新渲染流程

* 🚨 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/layout.py

@@ -1,7 +1,7 @@
-import base64
 from typing import Any
 from typing_extensions import Self
 
+from ...models.core.base import RenderableComponent
 from ...models.core.layout import LayoutData, LayoutItem
 from ..base import BaseBuilder
 
@@ -10,108 +10,100 @@ __all__ = ["LayoutBuilder"]
 
 class LayoutBuilder(BaseBuilder[LayoutData]):
     """
-    一个用于将多个图片（bytes）组合成单张图片的链式构建器。
-    采用混合模式，提供便捷的工厂方法和灵活的自定义模板能力。
+    一个用于将多个UI组件组合成单张图片的链式构建器。
+    它通过在单个渲染流程中动态包含子模板来实现高质量的输出。
     """
 
     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._template_name = "layouts/column"
         builder._options.update(options)
         return builder
 
     @classmethod
-    def grid(cls, **options: Any) -> Self:
-        """
-        工厂方法：创建一个网格布局的构建器。
-        :param options: 传递给模板的选项，如 columns, gap, padding 等。
-        """
+    def row(cls, **options: Any) -> Self:
         builder = cls()
-        builder._preset_template_name = "layouts/grid"
+        builder._template_name = "layouts/row"
         builder._options.update(options)
         return builder
 
     @classmethod
-    def vstack(cls, images: list[bytes], **options: Any) -> Self:
-        """
-        工厂方法：创建一个垂直堆叠布局的构建器，并直接添加图片。
+    def hstack(
+        cls, components: list["BaseBuilder | RenderableComponent"], **options: Any
+    ) -> Self:
+        builder = cls.row(**options)
+        for component in components:
+            builder.add_item(component)
+        return builder
 
-        参数:
-            images: 要垂直堆叠的图片字节流列表。
-            options: 传递给模板的选项，如 gap, padding, align_items 等。
-        """
+    @classmethod
+    def vstack(
+        cls, components: list["BaseBuilder | RenderableComponent"], **options: Any
+    ) -> Self:
         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)
+        for component in components:
+            builder.add_item(component)
         return builder
 
     def add_item(
-        self, image_bytes: bytes, metadata: dict[str, Any] | None = None
+        self,
+        component: "BaseBuilder | RenderableComponent",
+        metadata: dict[str, Any] | None = None,
     ) -> Self:
         """
-        向布局中添加一个图片项目。
-        :param image_bytes: 图片的原始字节数据。
-        :param metadata: (可选) 与此项目关联的元数据，可用于模板。
+        向布局中添加一个组件，支持多种组件类型的添加。
+
+        参数:
+            component: 一个 Builder 实例 (如 TableBuilder) 或一个 RenderableComponent
+                      数据模型。
+            metadata: (可选) 与此项目关联的元数据，可用于模板。
+
+        返回:
+            Self: 返回当前布局构建器实例，支持链式调用。
         """
-        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))
+        component_data = (
+            component.data if isinstance(component, BaseBuilder) else component
+        )
+        self._data.children.append(
+            LayoutItem(component=component_data, metadata=metadata)
+        )
         return self
 
     def add_option(self, key: str, value: Any) -> Self:
         """
         为布局添加一个自定义选项，该选项会传递给模板。
+
+        参数:
+            key: 选项的键名，用于在模板中引用。
+            value: 选项的值，可以是任意类型的数据。
+
+        返回:
+            Self: 返回当前布局构建器实例，支持链式调用。
         """
         self._options[key] = value
         return self
 
-    async def build(
-        self, use_cache: bool = False, template: str | None = None, **render_options
-    ) -> bytes:
+    def build(self) -> LayoutData:
         """
-        构建最终的布局图片。
-        :param use_cache: 是否使用缓存。
-        :param template: (可选) 强制使用指定的模板，覆盖工厂方法的预设。
-                         这是实现自定义布局的关键。
-        :param render_options: 传递给渲染引擎的额外选项。
-        """
-        final_template_name = template or self._preset_template_name
+        [修改] 构建并返回 LayoutData 模型实例。
+        此方法现在是同步的，并且不执行渲染。
 
-        if not final_template_name:
+        参数:
+            无
+
+        返回:
+            LayoutData: 配置好的布局数据模型。
+        """
+        if not self._template_name:
             raise ValueError(
-                "必须通过工厂方法 (如 LayoutBuilder.column()) 或在 build() "
-                "方法中提供一个模板名称。"
+                "必须通过工厂方法 (如 LayoutBuilder.column()) 初始化布局类型。"
             )
 
-        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)
+        self._data.layout_type = self._template_name.split("/")[-1]
+        return self._data

zhenxun/ui/builders/core/markdown.py

@@ -140,10 +140,12 @@ class MarkdownBuilder(BaseBuilder[MarkdownData]):
         self._append_element(RawHtmlElement(html="---"))
         return self
 
-    async def build(self, use_cache: bool = False, **render_options) -> bytes:
-        """构建Markdown图片"""
+    def build(self) -> MarkdownData:
+        """
+        构建并返回 MarkdownData 模型实例。
+        """
         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)
+        return super().build()

zhenxun/ui/builders/core/notebook.py

@@ -78,10 +78,25 @@ class NotebookBuilder(BaseBuilder[NotebookData]):
         self.add_component(Divider(**kwargs))
         return self
 
-    def add_component(self, component: RenderableComponent) -> "NotebookBuilder":
-        """向 Notebook 中添加一个可渲染的自定义组件。"""
+    def add_component(
+        self, component: "RenderableComponent | BaseBuilder"
+    ) -> "NotebookBuilder":
+        """
+        向 Notebook 中添加一个可渲染的自定义组件。
+
+        """
+        component_data = (
+            component.data if isinstance(component, BaseBuilder) else component
+        )
+
+        if not isinstance(component_data, RenderableComponent):
+            raise TypeError(
+                f"add_component 只能接受 RenderableComponent 或其 Builder，"
+                f"但收到了 {type(component)}"
+            )
+
         self._elements.append(
-            NotebookElement(type="component", component_data=component)
+            NotebookElement(type="component", component=component_data)
         )
         return self
 
@@ -97,11 +112,9 @@ class NotebookBuilder(BaseBuilder[NotebookData]):
             self.quote(quote)
         return self
 
-    async def build(
-        self, use_cache: bool = False, frameless: bool = False, **render_options
-    ) -> bytes:
-        """构建Notebook图片"""
+    def build(self) -> NotebookData:
+        """
+        构建并返回 NotebookData 模型实例。
+        """
         self._data.elements = self._elements
-        return await super().build(
-            use_cache=use_cache, frameless=frameless, **render_options
-        )
+        return super().build()