Undefined-bot 3.8.0__tar.gz → 3.8.1__tar.gz

{undefined_bot-3.8.0 → undefined_bot-3.8.1}/CHANGELOG.md

@@ -1,3 +1,15 @@
+## v3.8.1 可配置长图渲染与浏览器运行时回退
+
+本版本为 AI 渲染工具新增适合长内容发送的长图布局，可精确控制成图宽度与内边距；同时完善 Playwright 浏览器选择，在缺少内置浏览器时可使用已配置或系统安装的 Chrome / Chromium 完成渲染。
+
+- 扩展 `render.render_html` 与 `render.render_markdown`。新增 `layout=long`、`width` 和 `padding` 参数；长图默认宽度为 900 像素、内边距为 28 像素，并可通过 `[network]` 配置统一调整。默认布局保持原有行为，避免影响现有调用。
+- 优化长图版式与输出尺寸。长图模式移除页面外部留白和 Markdown 内容最大宽度限制，使正文填满指定画布；截图使用 CSS 像素缩放，最终图片宽度与请求的 `width` 一致，便于聊天平台直接预览和发送。
+- 完善渲染浏览器选择。新增 `render_browser_executable_path` 配置；Playwright 内置浏览器缺失时自动探测系统 Chrome / Chromium，显式配置路径无效或其他启动错误仍会直接报告，避免掩盖真实故障。
+- 收紧 HTML 渲染网络边界。BrowserContext 强制离线、禁用 Service Worker，并在上下文级终止全部网络请求，不再依赖可被 DNS 重绑定绕过的主机名预检；内联 CSS、脚本及 `data:` / `blob:` 资源仍可使用。LaTeX 同步收敛为本地 mathtext 渲染，复杂且不受支持的 TeX 不再等待外部 MathJax CDN。
+- 加固渲染缓存与配置集成。缓存键纳入截图缩放和样式参数，避免不同布局错误复用缓存；同步环境变量、热更新边界、配置模板、部署与使用文档，并补充长图参数、缓存隔离、浏览器回退和实际渲染回归测试。
+
+---
+
 ## v3.8.0 多协议 LLM SDK、推理回放与 WebUI 可用性
 
 本版本重构生成模型请求层，统一 OpenAI Chat Completions、OpenAI Responses 与 Anthropic Messages 的 SDK 调用和配置语义，补全多轮工具调用中的原生推理载体回放，并修复 WebUI 配置编辑器与多行日志查询的可用性问题。

{undefined_bot-3.8.0 → undefined_bot-3.8.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: Undefined-bot
-Version: 3.8.0
+Version: 3.8.1
 Summary: QQ bot platform with cognitive memory architecture and multi-agent Skills, via OneBot V11.
 Project-URL: Repository, https://github.com/69gg/Undefined
 Project-URL: Issues, https://github.com/69gg/Undefined/issues

{undefined_bot-3.8.0 → undefined_bot-3.8.1}/config.toml.example

@@ -1095,12 +1095,21 @@ request_retries = 0
 # zh: HTML/Markdown 图片渲染配置。
 # en: HTML/Markdown image rendering settings.
 [render]
-# zh: 是否让 crawl4ai、HTML/Markdown/LaTeX 渲染中的远程资源使用 [proxy] 代理地址。默认关闭。
-# en: Whether crawl4ai and remote resources in HTML/Markdown/LaTeX rendering use proxy addresses from [proxy]. Disabled by default.
+# zh: 是否让 crawl4ai 等网页抓取链路使用 [proxy] 代理地址。HTML/Markdown 浏览器渲染始终离线。默认关闭。
+# en: Whether crawl4ai and other web crawling paths use proxy addresses from [proxy]. HTML/Markdown browser rendering is always offline. Disabled by default.
 use_proxy = false
 # zh: 渲染浏览器最大同时开启数量。0 表示自动：Linux 默认 1，其它平台默认 2。
 # en: Max concurrent render browser pages. 0 = auto: Linux defaults to 1, other platforms default to 2.
 browser_max_concurrency = 0
+# zh: 可选的 Chrome/Chromium 可执行文件路径。留空时优先使用 Playwright 自带浏览器，缺失时再自动查找系统浏览器。
+# en: Optional Chrome/Chromium executable path. Empty prefers Playwright's bundled browser, then discovers an installed system browser if missing.
+browser_executable_path = ""
+# zh: render_html/render_markdown 的 long 布局未显式传 width 时使用的最终图片宽度（像素，320-2048）。
+# en: Final image width used by the long layout when width is omitted (pixels, 320-2048).
+long_image_default_width = 900
+# zh: long 布局未显式传 padding 时使用的内边距（像素，0-160）。
+# en: Content padding used by the long layout when padding is omitted (pixels, 0-160).
+long_image_default_padding = 28
 
 # zh: HTML 渲染结果缓存：基于 HTML 内容 hash 复用同一张图片，避免重复渲染。
 # en: HTML render result cache: reuse rendered images by content hash to skip re-rendering.

{undefined_bot-3.8.0 → undefined_bot-3.8.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "Undefined-bot"
-version = "3.8.0"
+version = "3.8.1"
 description = "QQ bot platform with cognitive memory architecture and multi-agent Skills, via OneBot V11."
 readme = "README.md"
 authors = [

{undefined_bot-3.8.0 → undefined_bot-3.8.1}/src/Undefined/__init__.py

@@ -24,7 +24,7 @@ if TYPE_CHECKING:
     from .skills.registry import BaseRegistry as BaseRegistry
     from .skills.tools import ToolRegistry as ToolRegistry
 
-__version__: str = "3.8.0"
+__version__: str = "3.8.1"
 
 # symbol -> (module_path, attribute_name)；首次访问时才 importlib 加载
 _LAZY_IMPORTS: dict[str, tuple[str, str]] = {

{undefined_bot-3.8.0 → undefined_bot-3.8.1}/src/Undefined/config/config_class.py

@@ -123,7 +123,10 @@ class Config:
     network_request_timeout: float
     network_request_retries: int
     render_browser_max_concurrency: int
+    render_browser_executable_path: str
     render_use_proxy: bool
+    render_long_image_default_width: int
+    render_long_image_default_padding: int
     api_xxapi_base_url: str
     api_xingzhige_base_url: str
     api_jkyai_base_url: str

{undefined_bot-3.8.0 → undefined_bot-3.8.1}/src/Undefined/config/env_registry.py

@@ -116,6 +116,9 @@ ENV_REGISTRY: Final[dict[tuple[str, ...], str]] = {
     ("naga", "use_proxy"): "NAGA_USE_PROXY",
     ("onebot", "token"): "ONEBOT_TOKEN",
     ("onebot", "ws_url"): "ONEBOT_WS_URL",
+    ("render", "browser_executable_path"): "RENDER_BROWSER_EXECUTABLE_PATH",
+    ("render", "long_image_default_padding"): "RENDER_LONG_IMAGE_DEFAULT_PADDING",
+    ("render", "long_image_default_width"): "RENDER_LONG_IMAGE_DEFAULT_WIDTH",
     ("render", "use_proxy"): "RENDER_USE_PROXY",
     ("search", "use_proxy"): "SEARCH_USE_PROXY",
     ("search", "firecrawl_search_enabled"): "FIRECRAWL_SEARCH_ENABLED",

{undefined_bot-3.8.0 → undefined_bot-3.8.1}/src/Undefined/config/hot_reload.py

@@ -32,6 +32,7 @@ _RESTART_REQUIRED_KEYS: set[str] = {
     "webui_port",
     "webui_password",
     "webui_autostart_bot",
+    "render_browser_executable_path",
     "api",
     "api.enabled",
     "api.host",
@@ -79,6 +80,8 @@ _RUNTIME_AI_MODEL_CONFIG_PREFIXES: tuple[str, ...] = (
     "tool_search_enabled",
     "tool_search_always_loaded",
     "tool_search_max_results",
+    "render_long_image_default_width",
+    "render_long_image_default_padding",
 )
 
 _AGENT_INTRO_KEYS: set[str] = {

{undefined_bot-3.8.0 → undefined_bot-3.8.1}/src/Undefined/config/load_sections/network.py

@@ -23,6 +23,10 @@ from ..search import normalize_search_priority
 
 logger = logging.getLogger(__name__)
 
+_LONG_IMAGE_MIN_WIDTH: int = 320
+_LONG_IMAGE_MAX_WIDTH: int = 2048
+_LONG_IMAGE_MAX_PADDING: int = 160
+
 
 def load_network(
     data: dict[str, Any], *, config_path: Optional[Path] = None
@@ -127,9 +131,46 @@ def load_network(
             0,
         ),
     )
+    render_browser_executable_path = _coerce_str(
+        _get_value(
+            data,
+            ("render", "browser_executable_path"),
+            "RENDER_BROWSER_EXECUTABLE_PATH",
+        ),
+        "",
+    )
     render_use_proxy = _coerce_bool(
         _get_value(data, ("render", "use_proxy"), "RENDER_USE_PROXY"), False
     )
+    render_long_image_default_width = min(
+        _LONG_IMAGE_MAX_WIDTH,
+        max(
+            _LONG_IMAGE_MIN_WIDTH,
+            _coerce_int(
+                _get_value(
+                    data,
+                    ("render", "long_image_default_width"),
+                    "RENDER_LONG_IMAGE_DEFAULT_WIDTH",
+                ),
+                900,
+            ),
+        ),
+    )
+    render_long_image_default_padding = min(
+        _LONG_IMAGE_MAX_PADDING,
+        max(
+            0,
+            _coerce_int(
+                _get_value(
+                    data,
+                    ("render", "long_image_default_padding"),
+                    "RENDER_LONG_IMAGE_DEFAULT_PADDING",
+                ),
+                28,
+            ),
+        ),
+        (render_long_image_default_width - 1) // 2,
+    )
 
     api_xxapi_base_url = _normalize_base_url(
         _coerce_str(
@@ -194,7 +235,10 @@ def load_network(
         "network_request_timeout": network_request_timeout,
         "network_request_retries": network_request_retries,
         "render_browser_max_concurrency": render_browser_max_concurrency,
+        "render_browser_executable_path": render_browser_executable_path,
         "render_use_proxy": render_use_proxy,
+        "render_long_image_default_width": render_long_image_default_width,
+        "render_long_image_default_padding": render_long_image_default_padding,
         "api_xxapi_base_url": api_xxapi_base_url,
         "api_xingzhige_base_url": api_xingzhige_base_url,
         "api_jkyai_base_url": api_jkyai_base_url,

{undefined_bot-3.8.0 → undefined_bot-3.8.1}/src/Undefined/render.py

@@ -5,13 +5,14 @@ import logging
 import sys
 from collections.abc import Awaitable, Callable
 from pathlib import Path
-from playwright.async_api import async_playwright, Browser, Page, Playwright
+from typing import Any, Literal, TypeVar
 
 import markdown
+from playwright.async_api import Browser, Page, Playwright, Route, async_playwright
 
-from typing import Any, TypeVar
 
 from Undefined.config import get_config
+from Undefined.utils.io import find_executable, is_file, resolve_path
 from Undefined.utils.render_cache import compute_render_cache_key, get_render_cache
 
 logger = logging.getLogger(__name__)
@@ -59,6 +60,13 @@ _render_active_count = 0
 
 # 默认并发限制：Linux 默认 1，其它平台默认 2
 _DEFAULT_MAX_CONCURRENT = 1 if sys.platform == "linux" else 2
+_SYSTEM_CHROMIUM_COMMANDS = (
+    "google-chrome-stable",
+    "google-chrome",
+    "chromium",
+    "chromium-browser",
+    "microsoft-edge-stable",
+)
 _RenderResult = TypeVar("_RenderResult")
 
 
@@ -89,6 +97,40 @@ def _resolve_render_browser_max_concurrency() -> int:
     return configured_limit
 
 
+async def _resolve_configured_browser_executable() -> str | None:
+    """读取显式配置的浏览器路径；配置错误时不静默回退。"""
+    try:
+        runtime_config = get_config(strict=False)
+    except Exception:
+        logger.debug("[渲染] 读取浏览器路径配置失败", exc_info=True)
+        return None
+
+    configured = str(
+        getattr(runtime_config, "render_browser_executable_path", "") or ""
+    ).strip()
+    if not configured:
+        return None
+
+    path = await resolve_path(configured)
+    if not await is_file(path):
+        raise FileNotFoundError(f"配置的渲染浏览器不存在: {path}")
+    return str(path)
+
+
+async def _find_system_browser_executable() -> str | None:
+    """在 Playwright 自带 Chromium 缺失时查找已安装的系统浏览器。"""
+    for command in _SYSTEM_CHROMIUM_COMMANDS:
+        executable = await find_executable(command)
+        if executable:
+            return executable
+    return None
+
+
+def _is_missing_playwright_browser(error: BaseException) -> bool:
+    text = str(error)
+    return "Executable doesn't exist" in text or "playwright install" in text
+
+
 async def _get_browser() -> Browser:
     """获取或创建浏览器实例（懒加载单例）"""
     global _playwright, _browser
@@ -100,9 +142,32 @@ async def _get_browser() -> Browser:
         if _browser is not None:
             return _browser
 
+        configured_executable = await _resolve_configured_browser_executable()
         playwright = await async_playwright().start()
         try:
-            browser = await playwright.chromium.launch(headless=True)
+            if configured_executable is not None:
+                browser = await playwright.chromium.launch(
+                    headless=True,
+                    executable_path=configured_executable,
+                )
+            else:
+                try:
+                    browser = await playwright.chromium.launch(headless=True)
+                except Exception as exc:
+                    system_executable = await _find_system_browser_executable()
+                    if (
+                        not _is_missing_playwright_browser(exc)
+                        or system_executable is None
+                    ):
+                        raise
+                    logger.warning(
+                        "[render] Playwright Chromium 未安装，回退到系统浏览器: %s",
+                        system_executable,
+                    )
+                    browser = await playwright.chromium.launch(
+                        headless=True,
+                        executable_path=system_executable,
+                    )
         except Exception:
             await playwright.stop()
             raise
@@ -206,6 +271,8 @@ async def render_html_to_image(
     *,
     viewport_width: int = 1280,
     screenshot_selector: str | None = None,
+    screenshot_scale: Literal["css", "device"] = "device",
+    screenshot_style: str | None = None,
     timeout_ms: int = 60000,
     proxy: str | None = None,
 ) -> None:
@@ -217,12 +284,19 @@ async def render_html_to_image(
         output_path: 输出图片路径 (例如 'result.png')
         viewport_width: 视口宽度（像素），默认 1280
         screenshot_selector: 仅截图匹配的元素，默认截整页
+        screenshot_scale: 输出像素尺度，device 按 DPR 输出，css 按 CSS 像素输出
+        screenshot_style: 仅在截图期间注入的 CSS 样式
         timeout_ms: 截图超时时间（毫秒），默认 60000
-        proxy: 可选浏览器代理地址
+        proxy: 保留用于调用兼容和缓存隔离；离线上下文不会发出网络请求
     """
     cache = await get_render_cache()
     cache_key = compute_render_cache_key(
-        html_content, viewport_width, screenshot_selector, proxy
+        html_content,
+        viewport_width,
+        screenshot_selector,
+        proxy,
+        screenshot_scale,
+        screenshot_style,
     )
 
     if await cache.copy_to(cache_key, output_path):
@@ -234,12 +308,16 @@ async def render_html_to_image(
         if screenshot_selector:
             await page.locator(screenshot_selector).first.screenshot(
                 path=output_path,
+                scale=screenshot_scale,
+                style=screenshot_style,
                 timeout=timeout_ms,
             )
         else:
             await page.screenshot(
                 path=output_path,
                 full_page=True,
+                scale=screenshot_scale,
+                style=screenshot_style,
                 timeout=timeout_ms,
             )
 
@@ -264,7 +342,11 @@ async def render_html_with_page(
     timeout_ms: int = 60000,
     proxy: str | None = None,
 ) -> _RenderResult:
-    """在共享浏览器实例中打开 HTML 页面并交给调用方渲染。"""
+    """在共享浏览器实例中打开 HTML 页面并交给调用方渲染。
+
+    ``proxy`` 在移出 ``context_kwargs`` 后仍刻意保留，以兼容现有调用；上层
+    ``render_html_to_image`` 继续用它隔离缓存键，离线浏览器上下文不会使用它。
+    """
     browser = await _get_browser()
     semaphore = await _get_semaphore()
 
@@ -276,11 +358,12 @@ async def render_html_with_page(
         try:
             context_kwargs: dict[str, Any] = {
                 "device_scale_factor": 2,
+                "offline": True,
+                "service_workers": "block",
                 "viewport": {"width": viewport_width, "height": 800},
             }
-            if proxy:
-                context_kwargs["proxy"] = {"server": proxy}
             context = await browser.new_context(**context_kwargs)
+            await context.route("**/*", _abort_render_network_request)
             page = await context.new_page()
             page.set_default_timeout(timeout_ms)
             await page.set_content(html_content)
@@ -291,3 +374,8 @@ async def render_html_with_page(
                     await context.close()
             finally:
                 _render_active_count = max(0, _render_active_count - 1)
+
+
+async def _abort_render_network_request(route: Route) -> None:
+    """终止渲染上下文中的所有网络请求，避免 DNS 重绑定绕过。"""
+    await route.abort()

{undefined_bot-3.8.0 → undefined_bot-3.8.1}/src/Undefined/skills/toolsets/README.md

@@ -135,9 +135,9 @@ async def execute(args: dict[str, Any], context: dict[str, Any]) -> str:
 
 ### Render（渲染）
 
-- `render.render_html`: 将 HTML 渲染为图片
+- `render.render_html`: 将 HTML 渲染为普通图片或指定宽度的单张长图
 - `render.render_latex`: 将 LaTeX 渲染为图片；常见公式本地渲染，复杂内容回退 MathJax + Playwright
-- `render.render_markdown`: 将 Markdown 渲染为图片
+- `render.render_markdown`: 将 Markdown 渲染为普通图片或指定宽度的单张长图
 
 ### Memes（表情包）
 

undefined_bot-3.8.1/src/Undefined/skills/toolsets/render/README.md

@@ -0,0 +1,14 @@
+# render 工具集
+
+渲染相关工具集合，工具名以 `render.*` 命名。
+
+主要能力：
+- HTML 渲染，支持内联 CSS、脚本和 `data:` / `blob:` 资源；浏览器上下文默认完全离线，不加载外部资源
+- Markdown 渲染
+- LaTeX 渲染
+- HTML/Markdown 可显式传 `layout=long`、`width`、`padding` 输出无两侧外部留白的单张长图
+
+`layout=default` 保持原有布局。`layout=long` 时，`width` 是最终图片像素宽度，高度按内容自动延伸；`padding=0` 可用于 HTML 全幅设计。
+
+目录结构：
+- 每个子目录对应一个工具（`config.json` + `handler.py`）

undefined_bot-3.8.1/src/Undefined/skills/toolsets/render/layout.py

@@ -0,0 +1,171 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Literal, Mapping
+
+RenderContentKind = Literal["html", "markdown"]
+RenderLayoutName = Literal["default", "long"]
+
+MIN_LONG_IMAGE_WIDTH = 320
+MAX_LONG_IMAGE_WIDTH = 2048
+MAX_LONG_IMAGE_PADDING = 160
+DEFAULT_LONG_IMAGE_WIDTH = 900
+DEFAULT_LONG_IMAGE_PADDING = 28
+
+
+@dataclass(frozen=True)
+class RenderLayoutOptions:
+    """已校验的渲染布局选项。"""
+
+    layout: RenderLayoutName
+    viewport_width: int | None = None
+    screenshot_scale: Literal["css", "device"] = "device"
+    screenshot_style: str | None = None
+
+    def render_kwargs(self) -> dict[str, Any]:
+        """仅为长图返回额外参数，保持默认调用完全兼容。"""
+        if self.layout == "default":
+            return {}
+        return {
+            "viewport_width": self.viewport_width,
+            "screenshot_scale": self.screenshot_scale,
+            "screenshot_style": self.screenshot_style,
+        }
+
+
+def _config_int(context: Mapping[str, Any], attribute: str, fallback: int) -> int:
+    runtime_config = context.get("runtime_config")
+    raw_value = getattr(runtime_config, attribute, fallback)
+    if isinstance(raw_value, bool):
+        return fallback
+    try:
+        return int(raw_value)
+    except (TypeError, ValueError):
+        return fallback
+
+
+def _parse_explicit_int(
+    value: Any,
+    *,
+    name: str,
+    minimum: int,
+    maximum: int,
+) -> tuple[int | None, str | None]:
+    if isinstance(value, bool) or not isinstance(value, int):
+        return None, f"{name} 必须是整数"
+    if value < minimum or value > maximum:
+        return None, f"{name} 必须在 {minimum}..{maximum} 之间"
+    return value, None
+
+
+def _long_layout_style(content_kind: RenderContentKind, padding: int) -> str:
+    shared = """
+html, body {
+  margin: 0 !important;
+  width: 100% !important;
+  min-width: 0 !important;
+  max-width: 100% !important;
+  overflow-x: hidden !important;
+}
+img, video, canvas, svg {
+  max-width: 100% !important;
+}
+"""
+    if content_kind == "markdown":
+        return (
+            shared
+            + f"""
+body {{
+  padding: 0 !important;
+}}
+.markdown-body {{
+  box-sizing: border-box !important;
+  width: 100% !important;
+  min-width: 0 !important;
+  max-width: none !important;
+  margin: 0 !important;
+  padding: {padding}px !important;
+  overflow-wrap: anywhere !important;
+}}
+.markdown-body pre {{
+  max-width: 100% !important;
+  white-space: pre-wrap !important;
+  overflow-wrap: anywhere !important;
+}}
+"""
+        )
+    return (
+        shared
+        + f"""
+body {{
+  box-sizing: border-box !important;
+  padding: {padding}px !important;
+}}
+"""
+    )
+
+
+def resolve_render_layout(
+    args: Mapping[str, Any],
+    context: Mapping[str, Any],
+    *,
+    content_kind: RenderContentKind,
+) -> tuple[RenderLayoutOptions | None, str | None]:
+    """解析并校验工具的 default/long 布局参数。"""
+    layout_raw = str(args.get("layout", "default") or "default").strip().lower()
+    if layout_raw not in {"default", "long"}:
+        return None, f"layout 无效：{layout_raw}。仅支持 default 或 long"
+
+    has_width = args.get("width") is not None
+    has_padding = args.get("padding") is not None
+    if layout_raw == "default":
+        if has_width or has_padding:
+            return None, "width 和 padding 仅支持在 layout=long 时使用"
+        return RenderLayoutOptions(layout="default"), None
+
+    if has_width:
+        width, error = _parse_explicit_int(
+            args.get("width"),
+            name="width",
+            minimum=MIN_LONG_IMAGE_WIDTH,
+            maximum=MAX_LONG_IMAGE_WIDTH,
+        )
+        if error is not None or width is None:
+            return None, error
+    else:
+        width = _config_int(
+            context,
+            "render_long_image_default_width",
+            DEFAULT_LONG_IMAGE_WIDTH,
+        )
+        width = min(MAX_LONG_IMAGE_WIDTH, max(MIN_LONG_IMAGE_WIDTH, width))
+
+    if has_padding:
+        padding, error = _parse_explicit_int(
+            args.get("padding"),
+            name="padding",
+            minimum=0,
+            maximum=MAX_LONG_IMAGE_PADDING,
+        )
+        if error is not None or padding is None:
+            return None, error
+    else:
+        padding = _config_int(
+            context,
+            "render_long_image_default_padding",
+            DEFAULT_LONG_IMAGE_PADDING,
+        )
+        padding = min(MAX_LONG_IMAGE_PADDING, max(0, padding))
+
+    if padding * 2 >= width:
+        return None, "padding 过大，必须满足 2 * padding < width"
+
+    return (
+        RenderLayoutOptions(
+            layout="long",
+            viewport_width=width,
+            screenshot_scale="css",
+            screenshot_style=_long_layout_style(content_kind, padding),
+        ),
+        None,
+    )

{undefined_bot-3.8.0 → undefined_bot-3.8.1}/src/Undefined/skills/toolsets/render/render_html/config.json

@@ -2,7 +2,7 @@
     "type": "function",
     "function": {
         "name": "render_html",
-        "description": "将 HTML 内容渲染为图片。默认返回可嵌入回复的图片 UID（embed），也可直接发送到指定目标（send）。支持完整的 HTML 文档，包括内联 CSS 和样式。",
+        "description": "将 HTML 内容渲染为图片。默认返回可嵌入回复的图片 UID（embed），也可直接发送到指定目标（send）。支持完整 HTML、内联 CSS、脚本和 data:/blob: 资源；浏览器上下文不加载外部资源。需要窄幅、高度随内容延伸且无两侧外部留白时，使用 layout=long。",
         "parameters": {
             "type": "object",
             "properties": {
@@ -10,6 +10,24 @@
                     "type": "string",
                     "description": "要渲染的 HTML 内容。必须是完整的 HTML 文档（包含 <!DOCTYPE html>、<html>、<head>、<body> 标签）。"
                 },
+                "layout": {
+                    "type": "string",
+                    "description": "版式：default 保持原始页面布局；long 输出单张长图，高度随内容自动延伸并去除 html/body 外边距",
+                    "enum": ["default", "long"],
+                    "default": "default"
+                },
+                "width": {
+                    "type": "integer",
+                    "description": "长图最终像素宽度，仅 layout=long 时可用；不传则使用 [render].long_image_default_width",
+                    "minimum": 320,
+                    "maximum": 2048
+                },
+                "padding": {
+                    "type": "integer",
+                    "description": "长图 body 内边距（像素），仅 layout=long 时可用；传 0 可做全幅设计，不传则使用 [render].long_image_default_padding",
+                    "minimum": 0,
+                    "maximum": 160
+                },
                 "delivery": {
                     "type": "string",
                     "description": "图片交付方式：embed 返回可插入回复的图片 UID；send 立即发送到目标",
@@ -28,4 +46,4 @@
             "required": ["html_content"]
         }
     }
-}
+}

{undefined_bot-3.8.0 → undefined_bot-3.8.1}/src/Undefined/skills/toolsets/render/render_html/handler.py

@@ -5,6 +5,7 @@ import logging
 import uuid
 
 from Undefined.attachments import scope_from_context
+from Undefined.skills.toolsets.render.layout import resolve_render_layout
 
 logger = logging.getLogger(__name__)
 
@@ -41,6 +42,14 @@ async def execute(args: Dict[str, Any], context: Dict[str, Any]) -> str:
     if delivery not in {"embed", "send"}:
         return f"delivery 无效：{delivery}。仅支持 embed 或 send"
 
+    layout_options, layout_error = resolve_render_layout(
+        args,
+        context,
+        content_kind="html",
+    )
+    if layout_error is not None or layout_options is None:
+        return layout_error or "渲染布局参数无效"
+
     if delivery == "send" and message_type and message_type not in ("group", "private"):
         return "消息类型必须是 group 或 private"
 
@@ -55,7 +64,11 @@ async def execute(args: Dict[str, Any], context: Dict[str, Any]) -> str:
         if not render_html_to_image:
             return "错误：渲染函数 (render_html_to_image) 未在上下文中提供，请检查 AIClient 配置。"
 
-        await render_html_to_image(html_content, str(filepath))
+        await render_html_to_image(
+            html_content,
+            str(filepath),
+            **layout_options.render_kwargs(),
+        )
 
         # 注册到附件系统
         attachment_registry = context.get("attachment_registry")

{undefined_bot-3.8.0 → undefined_bot-3.8.1}/src/Undefined/skills/toolsets/render/render_latex/config.json

@@ -2,13 +2,13 @@
     "type": "function",
     "function": {
         "name": "render_latex",
-        "description": "将 LaTeX 数学公式渲染为图片或 PDF 文档，使用 MathJax（不依赖系统 TeX 安装）。支持 LaTeX 数学子集（amsmath、equation、align、matrix 等），但不支持自定义 TeX 包。返回可嵌入回复的附件 UID。",
+        "description": "将常见 LaTeX 数学公式通过本地 matplotlib mathtext 渲染为图片或 PDF 文档，不依赖系统 TeX 或外部网络。复杂 TeX 环境和自定义宏可能不受支持。返回可嵌入回复的附件 UID。",
         "parameters": {
             "type": "object",
             "properties": {
                 "content": {
                     "type": "string",
-                    "description": "要渲染的 LaTeX 数学内容。支持 $...$（行内）、$$...$$（块级）、\\[...\\]、\\(...\\) 及标准数学环境（\\begin{align}、\\begin{equation}、\\begin{matrix} 等）。如果不包含分隔符，会自动用 \\[ ... \\] 包装。\\begin{document}...\\end{document} 外层包装会自动去掉。"
+                    "description": "要渲染的 LaTeX 数学内容。支持 mathtext 常见数学语法及 $...$、$$...$$、\\[...\\]、\\(...\\) 分隔符。如果不包含分隔符，会自动用 \\[ ... \\] 包装；\\begin{document}...\\end{document} 外层包装会自动去掉。复杂 TeX 环境和自定义宏可能不受支持。"
                 },
                 "output_format": {
                     "type": "string",