docvortex 0.2.1__py3-none-any.whl

docvortex/analyzers/native/office/pptx/package_normalizer.py

@@ -0,0 +1,321 @@
+import posixpath
+import re
+from io import BytesIO
+from zipfile import BadZipFile, ZipFile, ZipInfo
+
+from loguru import logger
+from lxml import etree
+
+from ..opc import relationship_source_base_dir, write_zip_package
+
+LEGACY_PPT_MAGIC = b"\xd0\xcf\x11\xe0\xa1\xb1\x1a\xe1"
+
+WORDPROCESSINGML_NS = "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
+MARKUP_COMPATIBILITY_NS = "http://schemas.openxmlformats.org/markup-compatibility/2006"
+PRESENTATIONML_NS = "http://schemas.openxmlformats.org/presentationml/2006/main"
+PACKAGE_RELATIONSHIPS_NS = "http://schemas.openxmlformats.org/package/2006/relationships"
+
+CONTENT_PART_TAG = f"{{{PRESENTATIONML_NS}}}contentPart"
+RELATIONSHIP_TAG = f"{{{PACKAGE_RELATIONSHIPS_NS}}}Relationship"
+PPTX_SHAPE_TAGS = {
+    f"{{{PRESENTATIONML_NS}}}sp",
+    f"{{{PRESENTATIONML_NS}}}grpSp",
+    f"{{{PRESENTATIONML_NS}}}graphicFrame",
+    f"{{{PRESENTATIONML_NS}}}cxnSp",
+    f"{{{PRESENTATIONML_NS}}}pic",
+}
+
+ROOT_TAG_PATTERN = re.compile(rb"<(?![?!])(?:[A-Za-z_][\w.-]*:)?[A-Za-z_][\w.-]*(?=\s|/?>)")
+
+STRICT_OOXML_REPLACEMENTS = (
+    (
+        b"http://purl.oclc.org/ooxml/officeDocument/relationships/metadata/thumbnail",
+        b"http://schemas.openxmlformats.org/package/2006/relationships/metadata/thumbnail",
+    ),
+    (
+        b"http://purl.oclc.org/ooxml/officeDocument/relationships/customProperties",
+        b"http://schemas.openxmlformats.org/officeDocument/2006/relationships/custom-properties",
+    ),
+    (
+        b"http://purl.oclc.org/ooxml/officeDocument/relationships/extendedProperties",
+        b"http://schemas.openxmlformats.org/officeDocument/2006/relationships/extended-properties",
+    ),
+    (
+        b"http://purl.oclc.org/ooxml/officeDocument/relationships",
+        b"http://schemas.openxmlformats.org/officeDocument/2006/relationships",
+    ),
+    (
+        b"http://purl.oclc.org/ooxml/drawingml/main",
+        b"http://schemas.openxmlformats.org/drawingml/2006/main",
+    ),
+    (
+        b"http://purl.oclc.org/ooxml/drawingml/chart",
+        b"http://schemas.openxmlformats.org/drawingml/2006/chart",
+    ),
+    (
+        b"http://purl.oclc.org/ooxml/presentationml/main",
+        b"http://schemas.openxmlformats.org/presentationml/2006/main",
+    ),
+    (
+        b"http://purl.oclc.org/ooxml/officeDocument/math",
+        b"http://schemas.openxmlformats.org/officeDocument/2006/math",
+    ),
+    (
+        b"http://purl.oclc.org/ooxml/officeDocument/customProperties",
+        b"http://schemas.openxmlformats.org/officeDocument/2006/custom-properties",
+    ),
+    (
+        b"http://purl.oclc.org/ooxml/officeDocument/extendedProperties",
+        b"http://schemas.openxmlformats.org/officeDocument/2006/extended-properties",
+    ),
+    (
+        b"http://purl.oclc.org/ooxml/officeDocument/docPropsVTypes",
+        b"http://schemas.openxmlformats.org/officeDocument/2006/docPropsVTypes",
+    ),
+    (
+        b"http://purl.oclc.org/ooxml/officeDocument/oleObject",
+        b"http://schemas.openxmlformats.org/officeDocument/2006/oleObject",
+    ),
+)
+
+KNOWN_NAMESPACE_DECLARATIONS = {
+    b"w": f'xmlns:w="{WORDPROCESSINGML_NS}"'.encode("utf-8"),
+}
+
+
+def normalize_pptx_package(file_bytes: bytes) -> bytes:
+    """在进入 python-pptx 前修复常见包级兼容问题，避免修复逻辑散落到形状解析阶段。"""
+    if file_bytes.startswith(LEGACY_PPT_MAGIC):
+        raise ValueError("Legacy binary PPT files are not supported; convert the file to PPTX before parsing.")
+
+    try:
+        with ZipFile(BytesIO(file_bytes)) as source:
+            loaded_members: list[tuple[ZipInfo, bytes]] = []
+            rewritten_members: list[tuple[ZipInfo, bytes]] = []
+            skipped_members: set[str] = set()
+            changed = False
+
+            for info in source.infolist():
+                member_data = _read_member_best_effort(source, info)
+                if member_data is None:
+                    skipped_members.add(info.filename)
+                    changed = True
+                    continue
+                loaded_members.append((info, member_data))
+
+            for info, member_data in loaded_members:
+                normalized_data = _normalize_member_xml(
+                    info.filename,
+                    member_data,
+                    skipped_members,
+                )
+                if normalized_data != member_data:
+                    changed = True
+                rewritten_members.append((info, normalized_data))
+    except BadZipFile as exc:
+        raise ValueError("Invalid PPTX package: file is not a ZIP archive.") from exc
+
+    if not changed:
+        return file_bytes
+
+    return write_zip_package(rewritten_members)
+
+
+def _read_member_best_effort(source: ZipFile, info: ZipInfo) -> bytes | None:
+    """读取 ZIP 成员；损坏的媒体资源可跳过，关键 XML/关系文件仍保持失败。"""
+    try:
+        return source.read(info.filename)
+    except BadZipFile as exc:
+        if _is_skippable_corrupt_member(info.filename):
+            logger.warning(f"Skipping corrupt non-critical PPTX media member {info.filename}: {exc}")
+            return None
+        raise
+
+
+def _is_skippable_corrupt_member(filename: str) -> bool:
+    """判断损坏成员是否属于可降级丢弃的媒体资源。"""
+    return filename.startswith("ppt/media/")
+
+
+def _normalize_member_xml(
+    filename: str,
+    member_data: bytes,
+    skipped_members: set[str] | None = None,
+) -> bytes:
+    """仅对 XML/关系成员做文本级和结构级规范化，二进制资源保持原样。"""
+    if not (filename.endswith(".xml") or filename.endswith(".rels")):
+        return member_data
+
+    normalized = _translate_strict_ooxml_uris(member_data)
+    if filename.endswith(".rels"):
+        normalized = _remove_relationships_to_skipped_members(
+            filename,
+            normalized,
+            skipped_members or set(),
+        )
+    if filename.endswith(".xml"):
+        normalized = _add_missing_known_namespaces(normalized)
+        normalized = _replace_content_part_alternate_content_with_fallback(normalized)
+    return normalized
+
+
+def _remove_relationships_to_skipped_members(
+    rels_filename: str,
+    rels_xml: bytes,
+    skipped_members: set[str],
+) -> bytes:
+    """删除指向已跳过媒体成员的内部关系，避免归一化包保留悬空引用。"""
+    if not skipped_members:
+        return rels_xml
+
+    try:
+        parser = etree.XMLParser(resolve_entities=False, remove_blank_text=False)
+        root = etree.fromstring(rels_xml, parser)
+    except etree.XMLSyntaxError:
+        return rels_xml
+
+    removed_count = 0
+    for relationship in list(root):
+        if relationship.tag != RELATIONSHIP_TAG and etree.QName(relationship).localname != "Relationship":
+            continue
+        if relationship.get("TargetMode") == "External":
+            continue
+
+        target = relationship.get("Target")
+        if not target:
+            continue
+
+        resolved_target = _resolve_relationship_target(rels_filename, target)
+        if resolved_target in skipped_members:
+            root.remove(relationship)
+            removed_count += 1
+
+    if removed_count == 0:
+        return rels_xml
+
+    return etree.tostring(
+        root,
+        xml_declaration=rels_xml.lstrip().startswith(b"<?xml"),
+        encoding="UTF-8",
+        standalone=True,
+    )
+
+
+def _resolve_relationship_target(rels_filename: str, target: str) -> str:
+    """把关系文件中的 Target 解析成 ZIP 包内的规范成员路径。"""
+    target = target.replace("\\", "/")
+    if target.startswith("/"):
+        return target.lstrip("/")
+
+    base_dir = _relationship_source_base_dir(rels_filename)
+    if not base_dir:
+        return posixpath.normpath(target)
+    return posixpath.normpath(posixpath.join(base_dir, target))
+
+
+def _relationship_source_base_dir(rels_filename: str) -> str:
+    """根据 .rels 成员路径推导源 part 的基础目录。"""
+    shared_base_dir = relationship_source_base_dir(rels_filename)
+    if shared_base_dir is not None:
+        return shared_base_dir
+
+    marker = "/_rels/"
+    if marker not in rels_filename:
+        return posixpath.dirname(rels_filename)
+
+    prefix, rels_basename = rels_filename.rsplit(marker, 1)
+    if not rels_basename.endswith(".rels"):
+        return prefix
+
+    source_part_name = rels_basename[: -len(".rels")]
+    source_part_path = posixpath.normpath(posixpath.join(prefix, source_part_name))
+    return posixpath.dirname(source_part_path)
+
+
+def _translate_strict_ooxml_uris(xml_bytes: bytes) -> bytes:
+    """把 Strict OOXML URI 转为 python-pptx 能识别的 Transitional URI。"""
+    normalized = xml_bytes
+    for strict_uri, transitional_uri in STRICT_OOXML_REPLACEMENTS:
+        normalized = normalized.replace(strict_uri, transitional_uri)
+    return normalized
+
+
+def _add_missing_known_namespaces(xml_bytes: bytes) -> bytes:
+    """为实际使用但未声明的已知前缀补齐命名空间，修复轻微损坏的 XML。"""
+    declarations = []
+    for prefix, declaration in KNOWN_NAMESPACE_DECLARATIONS.items():
+        if prefix + b":" in xml_bytes and b"xmlns:" + prefix + b"=" not in xml_bytes:
+            declarations.append(declaration)
+
+    if not declarations:
+        return xml_bytes
+
+    root_match = ROOT_TAG_PATTERN.search(xml_bytes)
+    if root_match is None:
+        return xml_bytes
+
+    close_index = xml_bytes.find(b">", root_match.end())
+    if close_index < 0:
+        return xml_bytes
+
+    insert_at = close_index
+    if insert_at > 0 and xml_bytes[insert_at - 1 : insert_at] == b"/":
+        insert_at -= 1
+
+    namespace_attrs = b" " + b" ".join(declarations)
+    return xml_bytes[:insert_at] + namespace_attrs + xml_bytes[insert_at:]
+
+
+def _replace_content_part_alternate_content_with_fallback(xml_bytes: bytes) -> bytes:
+    """将 python-pptx 不支持的 p:contentPart 优先分支替换为可解析的 fallback 图形。"""
+    if b"AlternateContent" not in xml_bytes or b"contentPart" not in xml_bytes:
+        return xml_bytes
+
+    try:
+        parser = etree.XMLParser(resolve_entities=False, remove_blank_text=False)
+        root = etree.fromstring(xml_bytes, parser)
+    except etree.XMLSyntaxError:
+        return xml_bytes
+
+    replaced_count = 0
+    alternate_content_nodes = root.findall(f".//{{{MARKUP_COMPATIBILITY_NS}}}AlternateContent")
+    for alternate_content in alternate_content_nodes:
+        if _replace_single_alternate_content(alternate_content):
+            replaced_count += 1
+
+    if replaced_count == 0:
+        return xml_bytes
+
+    return etree.tostring(
+        root,
+        xml_declaration=xml_bytes.lstrip().startswith(b"<?xml"),
+        encoding="UTF-8",
+        standalone=True,
+    )
+
+
+def _replace_single_alternate_content(alternate_content: etree._Element) -> bool:
+    """替换单个 AlternateContent 节点，优先保留 fallback 中的可见图形。"""
+    choice = alternate_content.find(f"{{{MARKUP_COMPATIBILITY_NS}}}Choice")
+    fallback = alternate_content.find(f"{{{MARKUP_COMPATIBILITY_NS}}}Fallback")
+    if choice is None or fallback is None:
+        return False
+
+    if not any(child.tag == CONTENT_PART_TAG for child in choice):
+        return False
+
+    fallback_shapes = [child for child in list(fallback) if child.tag in PPTX_SHAPE_TAGS]
+    if not fallback_shapes:
+        return False
+
+    parent = alternate_content.getparent()
+    if parent is None:
+        return False
+
+    insert_index = parent.index(alternate_content)
+    parent.remove(alternate_content)
+    for fallback_shape in fallback_shapes:
+        fallback.remove(fallback_shape)
+        parent.insert(insert_index, fallback_shape)
+        insert_index += 1
+    return True

docvortex/analyzers/native/office/pptx/pptx_converter.py

@@ -0,0 +1,323 @@
+from io import BytesIO
+from typing import BinaryIO, Optional
+
+from loguru import logger
+from pptx import Presentation, presentation
+from pptx.enum.shapes import MSO_SHAPE_TYPE
+
+from ..equation.image import OfficeImageEquationDecoder
+from ..equation.ooxml import OoxmlEquationDecoder
+from ..streams import read_stream_bytes_from_start, rewind_stream
+from .package_normalizer import normalize_pptx_package
+from ..._shared.xycut import sort_entries
+from .....schema import BlockType
+
+# PPTX_XYCUT_BETA: Final = 0.7
+# PPTX 标题占位符角色仅用于单页内部归一化，返回 model_output 前必须清理。
+
+
+from .context import (
+    IGNORED_NOTES_PLACEHOLDER_TYPES as IGNORED_NOTES_PLACEHOLDER_TYPES,
+    MIN_PICTURE_DIMENSION_RATIO as MIN_PICTURE_DIMENSION_RATIO,
+    MIN_PICTURE_AREA_RATIO as MIN_PICTURE_AREA_RATIO,
+    BACKGROUND_PICTURE_TEXT_COVERAGE_RATIO as BACKGROUND_PICTURE_TEXT_COVERAGE_RATIO,
+    PPTX_XYCUT_BETA as PPTX_XYCUT_BETA,
+    PPTX_XYCUT_DENSITY_THRESHOLD as PPTX_XYCUT_DENSITY_THRESHOLD,
+    DRAWINGML_NS as DRAWINGML_NS,
+    RELATIONSHIP_NS as RELATIONSHIP_NS,
+    SVG_BLIP_NS as SVG_BLIP_NS,
+    A14_DRAWING_NS as A14_DRAWING_NS,
+    OMML_NS as OMML_NS,
+    _EFFECTIVE_FONT_SIZE_KEY as _EFFECTIVE_FONT_SIZE_KEY,
+    _EFFECTIVE_ALL_BOLD_KEY as _EFFECTIVE_ALL_BOLD_KEY,
+    _PPTX_TITLE_CANDIDATE_KEY as _PPTX_TITLE_CANDIDATE_KEY,
+    _PPTX_TITLE_ROLE_KEY as _PPTX_TITLE_ROLE_KEY,
+    _PPTX_TITLE_ROLE_CENTER as _PPTX_TITLE_ROLE_CENTER,
+    _PPTX_TITLE_ROLE_TITLE as _PPTX_TITLE_ROLE_TITLE,
+    _PPTX_TITLE_ROLE_SUBTITLE as _PPTX_TITLE_ROLE_SUBTITLE,
+    _PPTX_TITLE_PLACEHOLDER_ROLES as _PPTX_TITLE_PLACEHOLDER_ROLES,
+    _SlideTransform as _SlideTransform,
+    _FlattenedShape as _FlattenedShape,
+)
+from .resources import _PptxResources
+from .shapes import _PptxShapes
+from .text_styles import _PptxTextStyles
+from .lists import _PptxLists
+from .titles import _PptxTitles
+
+
+class PptxConverter(_PptxResources, _PptxShapes, _PptxTextStyles, _PptxLists, _PptxTitles):
+    """编排 PPTX 包读取、逐页遍历、重试及职责处理。"""
+
+    def __init__(self):
+        """配置固定命名空间并为当前转换创建独立状态。"""
+        self.namespaces = {
+            "a": "http://schemas.openxmlformats.org/drawingml/2006/main",
+            "c": "http://schemas.openxmlformats.org/drawingml/2006/chart",
+            "m": "http://schemas.openxmlformats.org/officeDocument/2006/math",
+            "p": "http://schemas.openxmlformats.org/presentationml/2006/main",
+        }
+        self._reset_state()
+
+    def convert(
+        self,
+        file_stream: BinaryIO,
+    ):
+        if rewind_stream(file_stream):
+            try:
+                self._convert_package_stream(file_stream)
+                return
+            except Exception as exc:
+                file_bytes = read_stream_bytes_from_start(file_stream)
+                self._retry_convert_package_bytes_after_normalization(file_bytes, exc)
+                return
+
+        file_bytes = file_stream.read()
+        try:
+            self._convert_package_bytes(file_bytes)
+        except Exception as exc:
+            self._retry_convert_package_bytes_after_normalization(file_bytes, exc)
+
+    def _reset_state(self) -> None:
+        """重置解析状态，确保失败重试时不会残留上一次半解析结果。"""
+        self.pages = []
+        self.cur_page = []
+        self.list_block_stack = []
+        self._shape_type_cache = {}
+        self.file_stream = None
+        self.pptx_obj = None
+        self._ooxml_equation_decoder = OoxmlEquationDecoder()
+        self._image_equation_decoder = OfficeImageEquationDecoder()
+        self._mtef_warned_shapes = set()
+
+    def _convert_package_bytes(self, file_bytes: bytes) -> None:
+        """用独立字节流解析 PPTX 包，便于原始包失败后用规范化包重试。"""
+        self._convert_package_stream(BytesIO(file_bytes))
+
+    def _convert_package_stream(self, file_stream: BinaryIO) -> None:
+        """直接使用可复位的 PPTX 流解析正常路径，避免提前复制完整包字节。"""
+        self._reset_state()
+        rewind_stream(file_stream)
+        self.file_stream = file_stream
+        self.pptx_obj = Presentation(self.file_stream)
+        self.pages.append(self.cur_page)
+        if self.pptx_obj:
+            self._walk_linear(self.pptx_obj)
+        if self.pages and self.pages[-1] == []:
+            self.pages.pop()
+
+    def _retry_convert_package_bytes_after_normalization(
+        self,
+        file_bytes: bytes,
+        exc: Exception,
+    ) -> None:
+        """首次解析失败后，仅在包规范化确实产生变化时使用规范化字节重试。"""
+        normalized_bytes = normalize_pptx_package(file_bytes)
+        if normalized_bytes == file_bytes:
+            raise exc
+        logger.warning(f"Retrying PPTX parsing after package normalization: {exc}")
+        self._convert_package_bytes(normalized_bytes)
+
+    def _walk_linear(self, pptx_obj: presentation.Presentation):
+        slide_width = int(pptx_obj.slide_width)
+        slide_height = int(pptx_obj.slide_height)
+        has_visible_content_slide = False
+
+        # 遍历每一张幻灯片
+        for _, slide in enumerate(pptx_obj.slides):
+            linear_shapes = self._flatten_slide_shapes(slide.shapes)
+            sortable_shape_entries = []
+            tail_blocks = []
+
+            # 遍历幻灯片中的每一个形状
+            for shape_index, shape_entry in enumerate(linear_shapes):
+                shape_blocks = self._collect_shape_blocks(
+                    shape_entry,
+                    linear_shapes,
+                    shape_index,
+                    slide_width,
+                    slide_height,
+                )
+                if not shape_blocks:
+                    continue
+
+                if shape_entry.bbox is None:
+                    tail_blocks.extend(shape_blocks)
+                    continue
+
+                sortable_shape_entries.append(
+                    {
+                        "bbox": shape_entry.bbox,
+                        "blocks": shape_blocks,
+                    }
+                )
+
+            sorted_shape_entries = sort_entries(
+                sortable_shape_entries,
+                beta=PPTX_XYCUT_BETA,
+                density_threshold=PPTX_XYCUT_DENSITY_THRESHOLD,
+            )
+            for entry in sorted_shape_entries:
+                self.cur_page.extend(entry["blocks"])
+            self.cur_page.extend(tail_blocks)
+
+            visible_slide_has_content = bool(self.cur_page)
+            self._handle_slide_notes(slide)
+            self._promote_slide_text_blocks_to_titles(self.cur_page)
+            self._finalize_slide_title_types(
+                self.cur_page,
+                is_first_visible_slide=visible_slide_has_content and not has_visible_content_slide,
+            )
+            self._cleanup_slide_text_block_metadata(self.cur_page)
+            if visible_slide_has_content:
+                has_visible_content_slide = True
+            self.cur_page = []
+            self.pages.append(self.cur_page)
+
+    def _handle_slide_notes(self, slide) -> None:
+        if not slide.has_notes_slide:
+            return
+
+        try:
+            notes_slide = slide.notes_slide
+        except Exception as e:
+            logger.warning(f"Warning: notes slide cannot be loaded: {e}")
+            return
+
+        def handle_notes_shape(shape) -> None:
+            shape_type = self._safe_shape_type(shape)
+            if shape_type == MSO_SHAPE_TYPE.GROUP:
+                for grouped_shape in shape.shapes:
+                    handle_notes_shape(grouped_shape)
+                return
+
+            if shape_type in {
+                MSO_SHAPE_TYPE.EMBEDDED_OLE_OBJECT,
+                MSO_SHAPE_TYPE.LINKED_OLE_OBJECT,
+            }:
+                if self._is_equation_ole_shape(shape):
+                    omml_equations = self._pptx_ole_shape_omml(shape)
+                    if omml_equations:
+                        self.cur_page.extend(
+                            {
+                                "type": BlockType.PAGE_FOOTNOTE,
+                                "content": [{"type": "equation_inline", "content": latex}],
+                            }
+                            for latex in omml_equations
+                        )
+                        return
+                    latex = self._decode_pptx_ole_equation(shape)
+                    if latex:
+                        self.cur_page.append(
+                            {
+                                "type": BlockType.PAGE_FOOTNOTE,
+                                "content": [{"type": "equation_inline", "content": latex}],
+                            }
+                        )
+                        return
+                    image_latex = self._decode_pptx_shape_image_equation(shape)
+                    if image_latex:
+                        self.cur_page.append(
+                            {
+                                "type": BlockType.PAGE_FOOTNOTE,
+                                "content": [{"type": "equation_inline", "content": image_latex}],
+                            }
+                        )
+                return
+
+            if shape_type == MSO_SHAPE_TYPE.PICTURE:
+                image_latex = self._decode_pptx_shape_image_equation(shape)
+                if image_latex:
+                    self.cur_page.append(
+                        {
+                            "type": BlockType.PAGE_FOOTNOTE,
+                            "content": [{"type": "equation_inline", "content": image_latex}],
+                        }
+                    )
+                    return
+
+            if self._should_skip_notes_shape(shape):
+                return
+
+            for paragraph in shape.text_frame.paragraphs:
+                note_text = self._normalize_text_block_content(self._build_paragraph_rich_text(paragraph, shape))
+                if not note_text:
+                    continue
+                self.cur_page.append(
+                    {
+                        "type": BlockType.PAGE_FOOTNOTE,
+                        "content": note_text,
+                    }
+                )
+
+        for shape in notes_slide.shapes:
+            handle_notes_shape(shape)
+
+    @staticmethod
+    def _should_skip_notes_shape(shape) -> bool:
+        if not PptxConverter._shape_has_raw_text(shape):
+            return True
+
+        if not getattr(shape, "is_placeholder", False):
+            return False
+
+        try:
+            return shape.placeholder_format.type in IGNORED_NOTES_PLACEHOLDER_TYPES
+        except Exception:
+            return False
+
+    def _handle_text_elements(self, shape):
+        self.list_block_stack = []
+        list_level_base: Optional[int] = None
+
+        # 遍历段落以构建文本
+        for paragraph in shape.text_frame.paragraphs:
+            list_info = self._get_paragraph_list_info(shape, paragraph)
+
+            if list_info["is_list"]:
+                rich_text = self._normalize_text_block_content(self._build_paragraph_rich_text(paragraph, shape))
+                if rich_text:
+                    if list_level_base is None:
+                        list_level_base = list_info["level"]
+                    self._append_list_item(
+                        self.list_block_stack,
+                        self._normalize_contiguous_list_level(
+                            list_info["level"],
+                            list_level_base,
+                        ),
+                        list_info["attribute"],
+                        rich_text,
+                        list_info.get("start"),
+                        list_info.get("start_is_explicit_restart", False),
+                    )
+                continue
+
+            # 段落不是列表项，关闭当前 shape 的列表上下文
+            self.list_block_stack.clear()
+            list_level_base = None
+
+            p_text = self._normalize_text_block_content(self._build_paragraph_rich_text(paragraph, shape))
+            if not p_text:
+                continue
+
+            style_profile = self._build_paragraph_style_profile(shape, paragraph)
+
+            block = {
+                "type": BlockType.TEXT,
+                "content": p_text,
+                _EFFECTIVE_FONT_SIZE_KEY: style_profile["font_size_pt"],
+                _EFFECTIVE_ALL_BOLD_KEY: style_profile["all_bold"],
+            }
+            if shape.is_placeholder:
+                placeholder_type = shape.placeholder_format.type
+                title_role = _PPTX_TITLE_PLACEHOLDER_ROLES.get(placeholder_type)
+                if title_role is not None:
+                    block[_PPTX_TITLE_CANDIDATE_KEY] = True
+                    block["level"] = 2
+                    block[_PPTX_TITLE_ROLE_KEY] = title_role
+
+            self.cur_page.append(block)
+
+        # shape 结束后清理列表上下文，避免跨 shape 污染
+        self.list_block_stack.clear()
+        return