docvortex 0.2.1__py3-none-any.whl

docvortex/foundation/image_payload.py

@@ -0,0 +1,280 @@
+from __future__ import annotations
+
+import base64
+import binascii
+from pathlib import Path, PureWindowsPath
+import re
+import xml.etree.ElementTree as ElementTree
+from typing import Final
+from urllib.parse import urlsplit
+
+INLINE_IMAGE_DATA_URI_RE = re.compile(r"data:image/([^;\"']+);base64,([^\"']+)", re.DOTALL)
+_SVG_NAMESPACE = "http://www.w3.org/2000/svg"
+_METAFILE_SVG_MARKER = "wmf-emf"
+_METAFILE_SVG_FALLBACK_ID = "metafile-render-raster-fallback"
+MAX_IMAGE_PAYLOAD_BYTES: Final = 64 * 1024 * 1024
+MAX_GENERATED_SVG_BYTES: Final = MAX_IMAGE_PAYLOAD_BYTES
+MAX_RASTER_IMAGE_BYTES: Final = MAX_IMAGE_PAYLOAD_BYTES
+MAX_IMAGE_DATA_URI_BYTES: Final = len("data:image/svg+xml;base64,") + ((MAX_IMAGE_PAYLOAD_BYTES + 2) // 3) * 4
+MAX_DECODED_RASTER_DIMENSION: Final = 8_192
+MAX_DECODED_RASTER_PIXELS: Final = 16_000_000
+_MAX_GENERATED_SVG_NODES = 100_000
+_SAFE_SVG_ATTRIBUTES: dict[str, set[str]] = {
+    "svg": {"width", "height", "viewBox", "data-metafile-render"},
+    "metadata": {"id", "data-mime"},
+    "defs": set(),
+    "clipPath": {"id"},
+    "path": {
+        "d",
+        "fill",
+        "fill-rule",
+        "fill-opacity",
+        "opacity",
+        "stroke",
+        "stroke-width",
+        "stroke-linecap",
+        "stroke-linejoin",
+        "stroke-miterlimit",
+        "stroke-opacity",
+        "stroke-dasharray",
+    },
+    "g": {"clip-path"},
+    "image": {"width", "height", "transform", "href"},
+    "text": {
+        "x",
+        "y",
+        "fill",
+        "opacity",
+        "font-family",
+        "font-size",
+        "font-weight",
+        "font-style",
+        "text-anchor",
+        "dominant-baseline",
+        "text-decoration",
+        "transform",
+    },
+    "rect": {"x", "y", "width", "height", "fill", "opacity"},
+}
+
+
+class _RejectingSvgTreeBuilder(ElementTree.TreeBuilder):
+    """构造拒绝任何 DTD 的 SVG XML 树。"""
+
+    def doctype(self, _name: str, _pubid: str | None, _system: str | None) -> None:
+        """在实体声明被处理前拒绝任意偏移和编码的 DOCTYPE。"""
+        raise ValueError("Generated SVG must not contain a DTD or entity declaration")
+
+
+def normalize_image_extension(fmt: str) -> str:
+    """规范化图片扩展名，保证同一图片格式生成稳定文件名。"""
+    normalized = fmt.lower().split("+", 1)[0]
+    return "jpg" if normalized in {"jpeg", "jpg"} else normalized
+
+
+def validate_decoded_raster_size(width: int, height: int) -> None:
+    """在 Pillow 解码像素前校验 raster 单边尺寸与总像素预算。"""
+    if (
+        width <= 0
+        or height <= 0
+        or width > MAX_DECODED_RASTER_DIMENSION
+        or height > MAX_DECODED_RASTER_DIMENSION
+        or width * height > MAX_DECODED_RASTER_PIXELS
+    ):
+        raise ValueError(
+            f"Decoded raster image exceeds limits: {width}x{height}; "
+            f"max_dimension={MAX_DECODED_RASTER_DIMENSION}, max_pixels={MAX_DECODED_RASTER_PIXELS}"
+        )
+
+
+def _parse_svg_root_strict(payload: bytes) -> ElementTree.Element:
+    """在固定字节预算内解析 SVG 根节点，并在实体展开前拒绝 DTD。"""
+    if len(payload) > MAX_GENERATED_SVG_BYTES:
+        raise ValueError("SVG image payload exceeds its byte limit")
+    try:
+        parser = ElementTree.XMLParser(target=_RejectingSvgTreeBuilder())
+        root = ElementTree.fromstring(payload, parser=parser)
+    except ElementTree.ParseError as exc:
+        raise ValueError("Invalid SVG image payload") from exc
+    if not isinstance(root.tag, str) or root.tag.rsplit("}", 1)[-1].lower() != "svg":
+        raise ValueError("Image signature does not match MIME subtype: svg+xml")
+    return root
+
+
+def parse_image_data_uri_strict(data_uri: str) -> tuple[bytes, str]:
+    """严格解析图片 data URI，并同时校验 MIME 与文件签名是否一致。"""
+    if len(data_uri) > MAX_IMAGE_DATA_URI_BYTES:
+        raise ValueError("Image data URI exceeds its byte limit")
+    match = re.fullmatch(r"data:image/([^;]+);base64,([A-Za-z0-9+/]*={0,2})", data_uri)
+    if match is None:
+        raise ValueError("Invalid image data URI")
+
+    mime_subtype = match.group(1).lower()
+    extension = normalize_image_extension(mime_subtype)
+    encoded_payload = match.group(2)
+    payload_limit = MAX_GENERATED_SVG_BYTES if extension == "svg" else MAX_RASTER_IMAGE_BYTES
+    max_encoded_bytes = ((payload_limit + 2) // 3) * 4
+    if len(encoded_payload) > max_encoded_bytes:
+        payload_kind = "SVG" if extension == "svg" else "Raster"
+        raise ValueError(f"{payload_kind} image payload exceeds its byte limit")
+    if extension == "svg":
+        if mime_subtype != "svg+xml":
+            raise ValueError(f"Unsupported image MIME subtype: {mime_subtype}")
+    try:
+        payload = base64.b64decode(encoded_payload, validate=True)
+    except (binascii.Error, ValueError) as exc:
+        raise ValueError("Invalid base64 image payload") from exc
+    if not payload:
+        raise ValueError("Image payload must not be empty")
+    if len(payload) > payload_limit:
+        payload_kind = "SVG" if extension == "svg" else "Raster"
+        raise ValueError(f"{payload_kind} image payload exceeds its byte limit")
+
+    if extension == "svg":
+        _parse_svg_root_strict(payload)
+        return payload, extension
+
+    signatures: dict[str, tuple[bytes, ...]] = {
+        "jpg": (b"\xff\xd8\xff",),
+        "png": (b"\x89PNG\r\n\x1a\n",),
+        "gif": (b"GIF87a", b"GIF89a"),
+        "webp": (b"RIFF",),
+        "bmp": (b"BM",),
+        "tiff": (b"II*\x00", b"MM\x00*"),
+    }
+    expected = signatures.get(extension)
+    if expected is None:
+        raise ValueError(f"Unsupported image MIME subtype: {mime_subtype}")
+    if not any(payload.startswith(signature) for signature in expected):
+        raise ValueError(f"Image signature does not match MIME subtype: {mime_subtype}")
+    if extension == "webp" and (len(payload) < 12 or payload[8:12] != b"WEBP"):
+        raise ValueError("Image signature does not match MIME subtype: webp")
+    return payload, extension
+
+
+def _decode_png_data_uri(value: str) -> bytes:
+    """严格解码生成 SVG 内嵌的 PNG data URI。"""
+    match = re.fullmatch(r"data:image/png;base64,([A-Za-z0-9+/]*={0,2})", value)
+    if match is None:
+        raise ValueError("Generated SVG image href must contain a PNG data URI")
+    try:
+        payload = base64.b64decode(match.group(1), validate=True)
+    except (binascii.Error, ValueError) as exc:
+        raise ValueError("Generated SVG contains invalid PNG base64") from exc
+    if not payload.startswith(b"\x89PNG\r\n\x1a\n"):
+        raise ValueError("Generated SVG fallback does not contain a PNG")
+    return payload
+
+
+def _validate_generated_svg_attribute(tag: str, name: str, value: str) -> None:
+    """校验生成 SVG 属性只使用静态数值、颜色、本地 clip 或 PNG。"""
+    if name not in _SAFE_SVG_ATTRIBUTES[tag] or "\x00" in value or name.lower().startswith("on"):
+        raise ValueError(f"Generated SVG contains an unsafe attribute: {tag}.{name}")
+    normalized = value.strip().casefold()
+    if "javascript:" in normalized or "data:text" in normalized or "url(" in normalized and name != "clip-path":
+        raise ValueError(f"Generated SVG contains an unsafe attribute value: {tag}.{name}")
+    if name == "href":
+        _decode_png_data_uri(value)
+    elif name == "clip-path" and re.fullmatch(r"url\(#metafile-render-clip-\d+\)", value) is None:
+        raise ValueError("Generated SVG clip-path must reference a local metafile-render clip")
+    elif name == "transform" and re.fullmatch(r"(?:matrix|rotate)\([0-9eE+.,\- ]+\)", value) is None:
+        raise ValueError("Generated SVG transform is outside the supported subset")
+    elif name == "d" and re.fullmatch(r"[MmLlCcZz0-9eE+.,\- ]*", value) is None:
+        raise ValueError("Generated SVG path data is outside the supported subset")
+
+
+def extract_generated_svg_fallback(payload: bytes) -> tuple[bytes, int, int]:
+    """验证 metafile-render 生成 SVG，并返回 PNG fallback 与逻辑像素尺寸。"""
+    if not isinstance(payload, bytes) or not payload:
+        raise ValueError("Generated SVG payload is empty or exceeds its byte limit")
+    root = _parse_svg_root_strict(payload)
+    if root.tag != f"{{{_SVG_NAMESPACE}}}svg" or root.get("data-metafile-render") != _METAFILE_SVG_MARKER:
+        raise ValueError("SVG is not marked as a metafile-render generated image")
+    try:
+        width = int(root.get("width", ""))
+        height = int(root.get("height", ""))
+    except ValueError as exc:
+        raise ValueError("Generated SVG dimensions must be integers") from exc
+    if width <= 0 or height <= 0 or width > 8192 or height > 8192 or root.get("viewBox") != f"0 0 {width} {height}":
+        raise ValueError("Generated SVG dimensions or viewBox are outside the supported bounds")
+
+    fallback: bytes | None = None
+    node_count = 0
+    for element in root.iter():
+        node_count += 1
+        if node_count > _MAX_GENERATED_SVG_NODES:
+            raise ValueError("Generated SVG exceeds its node limit")
+        if not isinstance(element.tag, str) or not element.tag.startswith(f"{{{_SVG_NAMESPACE}}}"):
+            raise ValueError("Generated SVG contains a foreign namespace")
+        tag = element.tag.rsplit("}", 1)[-1]
+        if tag not in _SAFE_SVG_ATTRIBUTES:
+            raise ValueError(f"Generated SVG contains an unsupported element: {tag}")
+        for attribute_name, attribute_value in element.attrib.items():
+            if "}" in attribute_name:
+                raise ValueError("Generated SVG contains a namespaced attribute")
+            _validate_generated_svg_attribute(tag, attribute_name, attribute_value)
+        if element.tail and element.tail.strip():
+            raise ValueError("Generated SVG contains unexpected tail text")
+        if tag == "metadata":
+            if (
+                element.get("id") != _METAFILE_SVG_FALLBACK_ID
+                or element.get("data-mime") != "image/png"
+                or fallback is not None
+            ):
+                raise ValueError("Generated SVG fallback metadata is invalid or duplicated")
+            encoded = (element.text or "").strip()
+            fallback = _decode_png_data_uri(f"data:image/png;base64,{encoded}")
+        elif tag != "text" and element.text and element.text.strip():
+            raise ValueError(f"Generated SVG element must not contain text: {tag}")
+    if fallback is None:
+        raise ValueError("Generated SVG does not contain a PNG fallback")
+    return fallback, width, height
+
+
+def validate_image_sidecar_path(image_path: str) -> str:
+    """校验图片 sidecar 路径只能是安全的相对子路径，并返回规范化 POSIX 路径。"""
+    if (
+        not image_path
+        or image_path == "."
+        or "\\" in image_path
+        or any(ord(char) < 0x20 or ord(char) == 0x7F for char in image_path)
+    ):
+        raise ValueError(f"Unsafe image sidecar path: {image_path}")
+    parsed = urlsplit(image_path)
+    if parsed.scheme or parsed.netloc:
+        raise ValueError(f"Unsafe image sidecar path: {image_path}")
+    posix_path = Path(image_path)
+    windows_path = PureWindowsPath(image_path)
+    if (
+        posix_path.is_absolute()
+        or windows_path.is_absolute()
+        or windows_path.drive
+        or windows_path.root
+        or ".." in posix_path.parts
+        or ".." in windows_path.parts
+    ):
+        raise ValueError(f"Unsafe image sidecar path: {image_path}")
+    return posix_path.as_posix()
+
+
+def validate_remote_image_url(image_url: str) -> str:
+    """校验远程图片只能使用无凭据的 HTTP(S) 绝对地址。"""
+    normalized = image_url.strip()
+    if (
+        not normalized
+        or any(ord(char) < 0x20 or ord(char) == 0x7F for char in normalized)
+        or any(char in normalized for char in ("<", ">", "\\"))
+        or normalized.startswith("//")
+    ):
+        raise ValueError(f"Unsafe remote image URL: {image_url}")
+    try:
+        parsed = urlsplit(normalized)
+        _ = parsed.port
+        hostname = parsed.hostname
+    except ValueError as exc:
+        raise ValueError(f"Unsafe remote image URL: {image_url}") from exc
+    if parsed.scheme.casefold() not in {"http", "https"} or not parsed.netloc or hostname is None:
+        raise ValueError(f"Unsafe remote image URL: {image_url}")
+    if parsed.username is not None or parsed.password is not None:
+        raise ValueError(f"Remote image URL must not contain credentials: {image_url}")
+    return normalized

docvortex/foundation/language.py

@@ -0,0 +1,92 @@
+import os
+import re
+import unicodedata
+
+DEFAULT_CODE_LANGUAGE = "txt"
+_INVALID_SURROGATES = re.compile("[\ud800-\udfff]")
+
+
+def _detect_language(text: str) -> object:
+    """首次检测时配置本地模型缓存并惰性加载语言识别器。"""
+    from fast_langdetect import detect_language
+
+    return detect_language(text, low_memory=True)
+
+
+def remove_invalid_surrogates(text: str) -> str:
+    """等价移除代理码点；常见合法 Unicode 文本无需逐字符 Python 扫描。"""
+    return _INVALID_SURROGATES.sub("", text)
+
+
+def detect_lang(text: str) -> str:
+    if len(text) == 0:
+        return ""
+
+    text = text.replace("\n", "")
+    text = remove_invalid_surrogates(text)
+
+    try:
+        lang_upper = _detect_language(text)
+    except Exception:
+        html_no_ctrl_chars = "".join([c for c in text if unicodedata.category(c)[0] not in ["C"]])
+        lang_upper = _detect_language(html_no_ctrl_chars)
+
+    try:
+        lang = lang_upper.lower()
+    except Exception:
+        lang = ""
+    return lang
+
+
+def _normalize_text_for_language_guess(code: str) -> str:
+    """移除孤立代理字符并还原合法代理对，供代码语言识别使用。"""
+    if not code:
+        return ""
+    normalized: list[str] = []
+    index = 0
+    while index < len(code):
+        current_char = code[index]
+        current_ord = ord(current_char)
+        if 0xD800 <= current_ord <= 0xDBFF:
+            if index + 1 < len(code):
+                next_char = code[index + 1]
+                next_ord = ord(next_char)
+                if 0xDC00 <= next_ord <= 0xDFFF:
+                    pair = current_char + next_char
+                    normalized.append(pair.encode("utf-16", "surrogatepass").decode("utf-16"))
+                    index += 2
+                    continue
+            index += 1
+            continue
+        if 0xDC00 <= current_ord <= 0xDFFF:
+            index += 1
+            continue
+        normalized.append(current_char)
+        index += 1
+    return "".join(normalized)
+
+
+def guess_code_language(code: str) -> str:
+    """使用 Magika 推断代码块语言，失败时返回纯文本类型。"""
+    normalized_code = _normalize_text_for_language_guess(code)
+    if not normalized_code:
+        return DEFAULT_CODE_LANGUAGE
+    try:
+        from magika import Magika
+
+        lang = Magika().identify_bytes(normalized_code.encode("utf-8", errors="replace")).prediction.output.label
+    except Exception:
+        return DEFAULT_CODE_LANGUAGE
+    return lang if lang != "unknown" else DEFAULT_CODE_LANGUAGE
+
+
+if __name__ == "__main__":
+    print(os.getenv("FTLANG_CACHE"))
+    print(detect_lang("This is a test."))
+    print(detect_lang("<html>This is a test</html>"))
+    print(detect_lang("这个是中文测试。"))
+    print(detect_lang("<html>这个是中文测试。</html>"))
+    print(detect_lang("〖\ud835\udc46\ud835〗这是个包含utf-16的中文测试"))
+
+
+__all__ = ["DEFAULT_CODE_LANGUAGE", "detect_lang", "guess_code_language", "remove_invalid_surrogates"]

docvortex/foundation/platform.py

@@ -0,0 +1,38 @@
+import platform
+
+from packaging import version
+
+
+def is_windows_environment() -> bool:
+    return platform.system() == "Windows"
+
+
+# Detect if the current environment is a Mac computer
+def is_mac_environment() -> bool:
+    return platform.system() == "Darwin"
+
+
+def is_linux_environment() -> bool:
+    return platform.system() == "Linux"
+
+
+# Detect if CPU is Apple Silicon architecture
+def is_apple_silicon_cpu() -> bool:
+    return platform.machine() in ["arm64", "aarch64"]
+
+
+# If Mac computer with Apple Silicon architecture, check if macOS version is 13.5 or above
+def is_mac_os_version_supported(min_version: str = "13.5") -> bool:
+    if not is_mac_environment() or not is_apple_silicon_cpu():
+        return False
+    mac_version = platform.mac_ver()[0]
+    if not mac_version:
+        return False
+    # print("Mac OS Version:", mac_version)
+    return version.parse(mac_version) >= version.parse(min_version)
+
+
+if __name__ == "__main__":
+    print("Is Mac Environment:", is_mac_environment())
+    print("Is Apple Silicon CPU:", is_apple_silicon_cpu())
+    print("Is Mac OS Version Supported (>=13.5):", is_mac_os_version_supported())

docvortex/foundation/text.py

@@ -0,0 +1,153 @@
+"""跨模型共享的文本字符规范化与换行连接规则。"""
+
+import re
+from collections.abc import Sequence
+
+# 中日韩文本的物理换行通常不需要插入额外空格，集中定义以供各后端和渲染器共享。
+CJK_LANGS = frozenset({"zh", "ja", "ko"})
+
+# PDF 文本抽取时，英文跨行断词可能被编码为多种 hyphen 字符。
+# 这里只用于判断“行末英文断词符”，不要扩展到 en/em dash 等普通破折号。
+LINE_END_HYPHEN_CHARS = "-\u00ad\u2010\u2011\u2043"
+LINE_END_HYPHEN_RE = re.compile(rf"[A-Za-z]+[{re.escape(LINE_END_HYPHEN_CHARS)}]\s*$")
+
+# URL 候选仅允许 RFC 3986 常见 ASCII 字符，避免把中文正文吞入链接。
+_URL_CANDIDATE_RE = re.compile(
+    r"(?<![A-Za-z0-9])(?:(?:https?|ftp)://|www\.)[A-Za-z0-9._~:/?#\[\]@!$&'()*+,;=%-]+",
+    re.ASCII | re.IGNORECASE,
+)
+# 下一行自身以完整 URL 开头时，必须保留边界，避免两条独立链接相连。
+_URL_AT_LINE_START_RE = re.compile(
+    r"(?:(?:https?|ftp)://|www\.)",
+    re.ASCII | re.IGNORECASE,
+)
+
+
+def is_hyphen_at_line_end(line: str) -> bool:
+    """判断文本行是否以英文单词的跨行断词符结尾。
+
+    只识别字母后紧跟行末 hyphen 的断词场景，不处理词内连字符或普通破折号。
+    """
+    return bool(LINE_END_HYPHEN_RE.search(line))
+
+
+def _url_spans_line_boundary(previous_content: str, next_content: str) -> bool:
+    """判断无空格候选中是否存在严格横跨当前物理行边界的 URL。"""
+    stripped_previous = previous_content.rstrip()
+    stripped_next = next_content.lstrip()
+    if not stripped_previous or not stripped_next:
+        return False
+    candidate = f"{stripped_previous}{stripped_next}"
+    boundary = len(stripped_previous)
+    return any(match.start() < boundary < match.end() for match in _URL_CANDIDATE_RE.finditer(candidate))
+
+
+def resolve_text_line_boundary(
+    previous_content: str,
+    *,
+    block_language: str,
+    next_content: str,
+) -> tuple[str, str]:
+    """返回处理后的上一行内容和本次物理行边界分隔符。
+
+    严格横跨边界的 URL 候选直接连接，但下一行自身为完整 URL 时保留空格。
+    其余 CJK 文本直接连接物理行，普通西文行插入一个空格。西文行末如果是
+    合法的 hyphen，则始终直接连接下一行，并仅在下一行以小写字母开头时删除
+    hyphen。
+    """
+    processed_content = previous_content.rstrip()
+    if not processed_content:
+        return "", ""
+    stripped_next = next_content.lstrip()
+    if _url_spans_line_boundary(processed_content, stripped_next):
+        if _URL_AT_LINE_START_RE.match(stripped_next):
+            return processed_content, " "
+        return processed_content, ""
+    if block_language in CJK_LANGS:
+        return processed_content, ""
+    if not is_hyphen_at_line_end(processed_content):
+        return processed_content, " "
+    if stripped_next and stripped_next[0].islower():
+        return processed_content[:-1], ""
+    return processed_content, ""
+
+
+def merge_text_line_contents(
+    line_contents: Sequence[str],
+    *,
+    block_language: str,
+) -> str:
+    """按累计文本上下文折叠物理行，支持跨越三行以上的 URL 连续拼接。"""
+
+    normalized_lines = [str(content) for content in line_contents if str(content)]
+    if not normalized_lines:
+        return ""
+    merged_content = normalized_lines[0]
+    for current_line in normalized_lines[1:]:
+        merged_content, separator = resolve_text_line_boundary(
+            merged_content,
+            block_language=block_language,
+            next_content=current_line,
+        )
+        merged_content = f"{merged_content}{separator}{current_line}"
+    return merged_content.strip()
+
+
+def full_to_half_exclude_marks(text: str) -> str:
+    """将全角英文字母和数字转换为半角形式，同时保留全角标点。"""
+    result = []
+    for char in text:
+        code = ord(char)
+        # Full-width letters and numbers (FF21-FF3A for A-Z, FF41-FF5A for a-z, FF10-FF19 for 0-9)
+        if (0xFF21 <= code <= 0xFF3A) or (0xFF41 <= code <= 0xFF5A) or (0xFF10 <= code <= 0xFF19):
+            result.append(chr(code - 0xFEE0))  # Shift to ASCII range
+        else:
+            result.append(char)
+    return "".join(result)
+
+
+def full_to_half(text: str) -> str:
+    """将全角 ASCII 字母、数字和标点统一转换为半角形式。"""
+    result = []
+    for char in text:
+        code = ord(char)
+        # Full-width letters, numbers and punctuation (FF01-FF5E)
+        if 0xFF01 <= code <= 0xFF5E:
+            result.append(chr(code - 0xFEE0))  # Shift to ASCII range
+        else:
+            result.append(char)
+    return "".join(result)
+
+
+def clean_isolated_formula(content: str) -> str:
+    """移除行间公式外层的反斜杠方括号并清理首尾空白。"""
+    latex = content[:]
+    if latex.startswith("\\["):
+        latex = latex[2:]
+    if latex.endswith("\\]"):
+        latex = latex[:-2]
+    return latex.strip()
+
+
+def normalize_formula_tag_content(tag_content: str) -> str:
+    """归一化公式编号文本，去掉全角字符和包裹括号后用于 \\tag{}。"""
+    tag_content = full_to_half(str(tag_content or "").strip())
+    if tag_content.startswith(("(", "﹙")):
+        tag_content = tag_content[1:].strip()
+    if tag_content.endswith((")", "﹚")):
+        tag_content = tag_content[:-1].strip()
+    return tag_content
+
+
+def normalize_formula_content_for_tag(formula_content: str) -> str:
+    """归一化待合并编号的公式正文，去掉模型可能携带的展示公式分隔符。"""
+    return clean_isolated_formula(str(formula_content or ""))
+
+
+def build_tagged_formula_content(formula_content: str, tag_content: str) -> str | None:
+    """将公式正文和编号文本合成为带 LaTeX tag 的纯公式内容。"""
+    formula_content = normalize_formula_content_for_tag(formula_content)
+    tag_content = normalize_formula_tag_content(tag_content)
+    if not formula_content or not tag_content:
+        return None
+    return f"{formula_content}\\tag{{{tag_content}}}"

docvortex/foundation/type_identity.py

@@ -0,0 +1,20 @@
+"""保持搬迁后类型的历史导入身份及可独立解析的注解。"""
+
+from __future__ import annotations
+
+from dataclasses import fields, is_dataclass
+from typing import get_type_hints
+
+
+def preserve_type_module(cls: type, module: str) -> None:
+    """先在定义模块解析注解，再保留旧 pickle 路径，避免依赖尚未导入的门面。"""
+    annotations = get_type_hints(cls)
+    cls.__annotations__ = annotations
+    if is_dataclass(cls):
+        for field in fields(cls):
+            if field.name in annotations:
+                field.type = annotations[field.name]
+    cls.__module__ = module
+
+
+__all__ = ["preserve_type_module"]

docvortex/foundation/xml_names.py

@@ -0,0 +1,20 @@
+"""安全归一化 XML namespace 与 legacy HTML 前缀标签名。"""
+
+from __future__ import annotations
+
+from lxml import etree  # type: ignore[reportMissingImports]
+
+
+def local_name(element: etree._Element) -> str:
+    """返回 Clark notation、普通或冒号前缀标签的小写本地名。"""
+    tag = element.tag
+    if not isinstance(tag, str):
+        return ""
+    if tag.startswith("{") and "}" in tag:
+        tag = tag.split("}", 1)[1]
+    elif ":" in tag:
+        tag = tag.rsplit(":", 1)[1]
+    return tag.casefold()
+
+
+__all__ = ["local_name"]

docvortex/options.py

@@ -0,0 +1,30 @@
+"""独立引擎的显式渲染选项，不读取环境或宿主配置。"""
+
+from pydantic import BaseModel, Field
+
+
+class LatexDelimiterConfig(BaseModel):
+    """单组 LaTeX 左右定界符配置。"""
+
+    left: str = Field(min_length=1)
+    right: str = Field(min_length=1)
+
+
+def _default_display_latex_delimiter() -> LatexDelimiterConfig:
+    """构造缺省行间公式定界符。"""
+    return LatexDelimiterConfig(left="$$", right="$$")
+
+
+def _default_inline_latex_delimiter() -> LatexDelimiterConfig:
+    """构造缺省行内公式定界符。"""
+    return LatexDelimiterConfig(left="$", right="$")
+
+
+class LatexDelimitersConfig(BaseModel):
+    """Markdown 行内与行间公式定界符配置。"""
+
+    display: LatexDelimiterConfig = Field(default_factory=_default_display_latex_delimiter)
+    inline: LatexDelimiterConfig = Field(default_factory=_default_inline_latex_delimiter)
+
+
+__all__ = ["LatexDelimiterConfig", "LatexDelimitersConfig"]

docvortex/postprocess/__init__.py

@@ -0,0 +1,3 @@
+"""将严格 ModelJson 转换并增强为 MiddleJson 的后处理层。"""
+
+__all__: list[str] = []