dsh-courseware 0.1.0

package/engine/pptxgen/template.py

@@ -0,0 +1,834 @@
+"""模板解析：读取并固化 pptx 模板的版式、主题、字体、背景与装饰层。"""
+
+from __future__ import annotations
+
+import io
+import os
+from collections import Counter, defaultdict
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional, Tuple
+
+from pptx import Presentation
+from pptx.oxml.ns import qn
+from pptx.util import Emu
+
+from . import xmlutil as xu
+from .util import inch_from_emu, pt_from_emu, relative_luminance
+
+# --------------------------------------------------------------------------
+# 占位符类型 -> 语义名
+# --------------------------------------------------------------------------
+PH_TITLE = {"title", "ctrtitle"}
+PH_BODY = {"body", "obj", "subtitle", "content"}
+PH_OTHER = {"dt", "ftr", "sldnum", "pic", "chart", "tbl", "clipart", "media", "dgm"}
+
+
+@dataclass
+class PlaceholderInfo:
+    idx: Optional[int]
+    ph_type: str
+    name: str
+    left: int
+    top: int
+    width: int
+    height: int
+    font_size_pt: Optional[float] = None
+    font_name: Optional[str] = None
+    bold: Optional[bool] = None
+    color: Optional[str] = None
+    align: Optional[str] = None
+
+    @property
+    def box(self) -> Tuple[int, int, int, int]:
+        return self.left, self.top, self.width, self.height
+
+    @property
+    def is_title(self) -> bool:
+        return self.ph_type in PH_TITLE
+
+    @property
+    def is_body(self) -> bool:
+        return self.ph_type in PH_BODY
+
+    @property
+    def is_decoration(self) -> bool:
+        return self.ph_type in PH_OTHER
+
+
+@dataclass
+class ShapeInfo:
+    name: str
+    kind: str
+    left: Optional[int]
+    top: Optional[int]
+    width: Optional[int]
+    height: Optional[int]
+    is_placeholder: bool
+    text: str = ""
+
+
+@dataclass
+class ChromeItem:
+    """模板里反复出现的装饰/背景形状，会被克隆到新幻灯片。"""
+
+    element: object
+    src_slide: object
+    name: str
+    box: Tuple[Optional[int], Optional[int], Optional[int], Optional[int]]
+    occurrences: int
+    is_full_bleed: bool
+    fill_luminance: Optional[float] = None
+
+    def signature(self) -> tuple:
+        x, y, cx, cy = self.box
+        return (self.name, x, y, cx, cy)
+
+
+@dataclass
+class LayoutInfo:
+    index: int
+    name: str
+    master_index: int = 0
+    placeholders: List[PlaceholderInfo] = field(default_factory=list)
+    background: Optional[dict] = None
+    shape_count: int = 0
+    chrome: List[ChromeItem] = field(default_factory=list)
+
+    def find_title(self) -> Optional[PlaceholderInfo]:
+        for ph in self.placeholders:
+            if ph.is_title:
+                return ph
+        return None
+
+    def find_placeholder(self, idx: int) -> Optional[PlaceholderInfo]:
+        """按占位符 idx 查找（覆盖"标题/正文"之外的模板自定义槽位）。"""
+        for ph in self.placeholders:
+            if ph.idx == idx:
+                return ph
+        return None
+
+    def find_body(self) -> Optional[PlaceholderInfo]:
+        candidates = [ph for ph in self.placeholders if ph.is_body]
+        if not candidates:
+            return None
+        # 选面积最大的正文占位符
+        return max(candidates, key=lambda p: (p.width or 0) * (p.height or 0))
+
+
+@dataclass
+class TemplateInfo:
+    path: Optional[str]
+    width: int
+    height: int
+    theme_colors: Dict[str, str] = field(default_factory=dict)
+    theme_fonts: Dict[str, str] = field(default_factory=dict)
+    master_background: Optional[dict] = None
+    layouts: List[LayoutInfo] = field(default_factory=list)
+    layout_objects: List[object] = field(default_factory=list)   # 与 layouts 同序，供 add_slide 使用
+    masters: List[dict] = field(default_factory=list)
+    primary_master: int = 0
+    role_layout: Dict[str, int] = field(default_factory=dict)   # cover/content/end -> 全局版式下标
+    role_background: Dict[str, dict] = field(default_factory=dict)  # 封面/结束页自带的幻灯片级背景
+    global_chrome: List[ChromeItem] = field(default_factory=list)
+    slide_background: Optional[dict] = None
+    sample_slide_count: int = 0
+    _prs: object = None
+
+    # ---- 便捷访问 -------------------------------------------------------
+    @property
+    def aspect(self) -> float:
+        return (self.width or 1) / float(self.height or 1)
+
+    @property
+    def is_dark_background(self) -> bool:
+        bg = self.master_background or {}
+        if bg.get("kind") == "picture":
+            lum = bg.get("luminance")
+            return lum is not None and lum < 0.45
+        color = bg.get("color")
+        if color:
+            return relative_luminance(color) < 0.45
+        return False
+
+    def layout_by_index(self, idx: int) -> Optional[LayoutInfo]:
+        for lay in self.layouts:
+            if lay.index == idx:
+                return lay
+        return None
+
+    def accent_colors(self) -> List[str]:
+        out = []
+        for key in ("accent1", "accent2", "accent3", "accent4", "accent5", "accent6"):
+            c = self.theme_colors.get(key)
+            if c:
+                out.append(c)
+        return out or ["2F6FED", "E8590C", "2F9E44", "9C36B5", "0C8599", "C2255C"]
+
+    def primary_color(self) -> str:
+        acc = self.accent_colors()
+        return acc[0] if acc else "2F6FED"
+
+    def text_color(self) -> str:
+        for key in ("dk1", "tx1"):
+            c = self.theme_colors.get(key)
+            if c:
+                return c
+        return "1A1A1A"
+
+    def muted_color(self) -> str:
+        for key in ("dk2", "tx2"):
+            c = self.theme_colors.get(key)
+            if c:
+                return c
+        return "5A6472"
+
+    def cjk_font(self) -> str:
+        return (
+            self.theme_fonts.get("minor_ea")
+            or self.theme_fonts.get("major_ea")
+            or self.theme_fonts.get("minor_latin")
+            or "Microsoft YaHei"
+        )
+
+    def heading_font(self) -> str:
+        return (
+            self.theme_fonts.get("major_ea")
+            or self.theme_fonts.get("major_latin")
+            or self.cjk_font()
+        )
+
+
+# --------------------------------------------------------------------------
+# 解析入口
+# --------------------------------------------------------------------------
+def load_template(path: str, *, detect_chrome: bool = True) -> TemplateInfo:
+    prs = Presentation(path)
+    info = TemplateInfo(
+        path=os.path.abspath(path),
+        width=prs.slide_width,
+        height=prs.slide_height,
+        _prs=prs,
+    )
+    # 一个模板可能有多个母版（多套设计），python-pptx 只暴露第一个。
+    # 必须把所有母版的版式汇成一张全局表，否则会套错设计。
+    master_entries = _enumerate_masters(prs)
+    info.sample_slide_count = len(prs.slides)
+    used = _master_usage(prs, master_entries)
+    info.primary_master = max(used, key=lambda k: used[k]) if used else 0
+
+    info.masters = [
+        {
+            "index": i,
+            "name": e["name"],
+            "partname": str(e["part"].partname),
+            "layout_count": len(e["layout_objects"]),
+            "used_by_slides": used.get(i, 0),
+            "theme_colors": e["theme_colors"],
+            "theme_fonts": e["theme_fonts"],
+            "background": e["background"],
+        }
+        for i, e in enumerate(master_entries)
+    ]
+
+    global_index = 0
+    for mi, entry in enumerate(master_entries):
+        master = entry["master"]
+        master_fonts = entry["txstyles"]
+        master_ph = entry["ph_geometry"]
+        fallback_bg = entry["background"]
+        bg_from = f"master{mi + 1}(inherited)"
+        for layout in entry["layout_objects"]:
+            lay = _read_layout(layout, global_index, master, master_fonts, info, master_ph)
+            lay.master_index = mi
+            if lay.background is None and fallback_bg is not None:
+                lay.background = dict(fallback_bg)
+                lay.background["from"] = bg_from
+            info.layouts.append(lay)
+            info.layout_objects.append(layout)
+            global_index += 1
+
+    prim = master_entries[info.primary_master] if master_entries else None
+    if prim is not None:
+        info.theme_colors = prim["theme_colors"]
+        info.theme_fonts = prim["theme_fonts"]
+        info.master_background = prim["background"]
+
+    info.role_layout = _learn_role_layouts(prs, info)
+    info.role_background = _learn_role_backgrounds(prs)
+
+    if detect_chrome:
+        _detect_chrome(prs, info)
+    return info
+
+
+def _learn_role_layouts(prs: Presentation, info: TemplateInfo) -> Dict[str, int]:
+    """从样张学"哪一类页面用哪个版式"：封面取首页，内容取最高频，结束页取末页。"""
+    slides = list(prs.slides)
+    out: Dict[str, int] = {}
+    if not slides:
+        return out
+    first, last = slides[0], slides[-1]
+    cover = _layout_index_of(info, first)
+    if cover >= 0:
+        out["cover"] = cover
+    counts: Counter = Counter()
+    for s in slides[1:]:
+        idx = _layout_index_of(info, s)
+        if idx >= 0:
+            counts[idx] += 1
+    if counts:
+        out["content"] = counts.most_common(1)[0][0]
+    end = _layout_index_of(info, last)
+    if end >= 0 and len(list(last.shapes)) <= 4:
+        out["end"] = end
+    elif "cover" in out:
+        out["end"] = out["cover"]
+    return out
+
+
+def _learn_role_backgrounds(prs: Presentation) -> Dict[str, dict]:
+    """封面/结束页常有自己单独的幻灯片级背景，不跟随母版，要单独记住。"""
+    slides = list(prs.slides)
+    out: Dict[str, dict] = {}
+    if not slides:
+        return out
+    for role, slide in (("cover", slides[0]), ("end", slides[-1])):
+        bg = xu.get_bg(slide._element)
+        if bg is None:
+            continue
+        desc = xu.describe_bg(bg)
+        if not desc or desc.get("kind") in (None, "none"):
+            continue
+        out[role] = {"element": bg, "owner": slide, "kind": desc.get("kind")}
+    return out
+
+
+def _enumerate_masters(prs: Presentation) -> List[dict]:
+    """按 presentation 的 sldMasterIdLst 顺序收集全部母版及其版式。"""
+    part = prs.part
+    lst = part._element.find(qn("p:sldMasterIdLst"))
+    out: List[dict] = []
+    if lst is None:
+        return out
+    for smi in lst:
+        rId = smi.get(qn("r:id"))
+        if not rId:
+            continue
+        try:
+            mpart = part.related_part(rId)
+        except Exception:
+            continue
+        layout_objects = []
+        ll = mpart._element.find(qn("p:sldLayoutIdLst"))
+        if ll is not None:
+            for sli in ll:
+                lrid = sli.get(qn("r:id"))
+                if not lrid:
+                    continue
+                try:
+                    lpart = mpart.related_part(lrid)
+                    layout_objects.append(lpart.slide_layout)
+                except Exception:
+                    continue
+        master_obj = _SlideMasterFacade(mpart)
+        bg = xu.resolve_bg(master=master_obj)
+        if bg:
+            _annotate_luminance(prs, master_obj, bg)
+        out.append({
+            "master": master_obj,
+            "part": mpart,
+            "name": _master_name(mpart),
+            "layout_objects": layout_objects,
+            "theme_colors": _read_theme_colors_from(mpart),
+            "theme_fonts": _read_theme_fonts_from(mpart),
+            "txstyles": _read_master_txstyles(master_obj),
+            "ph_geometry": _master_placeholder_geometry(master_obj),
+            "background": bg,
+        })
+    return out
+
+
+class _SlideMasterFacade:
+    """让母版 part 有一个和 python-pptx SlideMaster 相同的 ._element 接口。"""
+
+    def __init__(self, part):
+        self.part = part
+        self._element = part._element
+
+    @property
+    def shapes(self):
+        from pptx.shapes.shapetree import MasterShapes
+
+        return MasterShapes(self._element.find(qn("p:cSld")).find(qn("p:spTree")), self)
+
+
+def _master_name(mpart) -> str:
+    cSld = mpart._element.find(qn("p:cSld"))
+    return (cSld.get("name") if cSld is not None else None) or str(mpart.partname).split("/")[-1]
+
+
+def _master_usage(prs: Presentation, entries: List[dict]) -> Dict[int, int]:
+    """统计示例幻灯片实际挂在哪个母版上。"""
+    part_of = {}
+    for i, e in enumerate(entries):
+        for lo in e["layout_objects"]:
+            part_of[str(lo.part.partname)] = i
+    counts: Dict[int, int] = {}
+    for slide in prs.slides:
+        try:
+            key = str(slide.slide_layout.part.partname)
+        except Exception:
+            continue
+        mi = part_of.get(key)
+        if mi is not None:
+            counts[mi] = counts.get(mi, 0) + 1
+    return counts
+
+
+def _theme_part_of(mpart):
+    try:
+        return mpart.part_related_by(
+            "http://schemas.openxmlformats.org/officeDocument/2006/relationships/theme"
+        )
+    except Exception:
+        return None
+
+
+def _read_theme_colors(prs: Presentation) -> Dict[str, str]:
+    return _read_theme_colors_from(prs.slide_master.part)
+
+
+def _read_theme_colors_from(mpart) -> Dict[str, str]:
+    colors: Dict[str, str] = {}
+    theme = _theme_part_of(mpart)
+    if theme is None:
+        return colors
+    root = theme._element if hasattr(theme, "_element") else None
+    if root is None:
+        try:
+            from lxml import etree
+
+            root = etree.fromstring(theme.blob)
+        except Exception:
+            return colors
+    clrScheme = root.find(f".//{qn('a:clrScheme')}")
+    if clrScheme is None:
+        return colors
+    for child in clrScheme:
+        key = child.tag.split("}")[-1]
+        color = xu._read_color(child)
+        if color:
+            colors[key] = color
+    # 常见别名
+    if "dk1" in colors and "tx1" not in colors:
+        colors["tx1"] = colors["dk1"]
+    if "lt1" in colors and "bg1" not in colors:
+        colors["bg1"] = colors["lt1"]
+    if "dk2" in colors:
+        colors.setdefault("tx2", colors["dk2"])
+    if "lt2" in colors:
+        colors.setdefault("bg2", colors["lt2"])
+    return colors
+
+
+def _read_theme_fonts(prs: Presentation) -> Dict[str, str]:
+    return _read_theme_fonts_from(prs.slide_master.part)
+
+
+def _read_theme_fonts_from(mpart) -> Dict[str, str]:
+    fonts: Dict[str, str] = {}
+    theme = _theme_part_of(mpart)
+    if theme is None:
+        return fonts
+    root = getattr(theme, "_element", None)
+    if root is None:
+        try:
+            from lxml import etree
+
+            root = etree.fromstring(theme.blob)
+        except Exception:
+            return fonts
+    scheme = root.find(f".//{qn('a:fontScheme')}")
+    if scheme is None:
+        return fonts
+    for which in ("major", "minor"):
+        node = scheme.find(qn(f"a:{which}Font"))
+        if node is None:
+            continue
+        for script, suffix in (("a:latin", "latin"), ("a:ea", "ea"), ("a:cs", "cs")):
+            el = node.find(qn(script))
+            if el is not None and el.get("typeface"):
+                fonts[f"{which}_{suffix}"] = el.get("typeface")
+    return fonts
+
+
+def _read_master_txstyles(master) -> Dict[str, dict]:
+    out: Dict[str, dict] = {}
+    txStyles = master._element.find(qn("p:txStyles"))
+    if txStyles is None:
+        return out
+    for name, key in (("p:titleStyle", "title"), ("p:bodyStyle", "body"), ("p:otherStyle", "other")):
+        node = txStyles.find(qn(name))
+        if node is None:
+            continue
+        lvl1 = node.find(qn("a:lvl1pPr"))
+        if lvl1 is None:
+            continue
+        out[key] = _read_defRPr(lvl1)
+    return out
+
+
+def _read_defRPr(pPr) -> dict:
+    res: dict = {}
+    if pPr is None:
+        return res
+    d = pPr.find(qn("a:defRPr"))
+    if d is not None:
+        sz = d.get("sz")
+        if sz:
+            res["size_pt"] = int(sz) / 100.0
+        b = d.get("b")
+        if b is not None:
+            res["bold"] = b in ("1", "true")
+        latin = d.find(qn("a:latin"))
+        if latin is not None and latin.get("typeface"):
+            res["font"] = latin.get("typeface")
+        ea = d.find(qn("a:ea"))
+        if ea is not None and ea.get("typeface"):
+            res.setdefault("font", ea.get("typeface"))
+        solid = d.find(qn("a:solidFill"))
+        color = xu._read_color(solid if solid is not None else d)
+        if color:
+            res["color"] = color
+    algn = pPr.get("algn")
+    if algn:
+        res["align"] = algn
+    return res
+
+
+def _master_placeholder_geometry(master) -> Dict[tuple, tuple]:
+    """母版上占位符的几何，(idx, type) 与 type 两种键，供版式继承。"""
+    out: Dict[tuple, tuple] = {}
+    for el in xu.iter_shape_elements(master.shapes._spTree):
+        if not xu.is_placeholder(el):
+            continue
+        idx = xu.placeholder_idx(el)
+        ptype = xu.placeholder_type(el) or "body"
+        x, y, cx, cy = xu.shape_off_ext(el)
+        if not (cx and cy):
+            continue
+        out[(idx, ptype)] = (x or 0, y or 0, cx, cy)
+        out.setdefault(("type", ptype), (x or 0, y or 0, cx, cy))
+    return out
+
+
+def _read_layout(layout, index: int, master, master_fonts, info: TemplateInfo,
+                 master_ph: Optional[Dict[tuple, tuple]] = None) -> LayoutInfo:
+    master_ph = master_ph or {}
+    lay = LayoutInfo(index=index, name=layout.name or f"版式{index + 1}")
+    bg = xu.resolve_bg(layout=layout, master=master)
+    if bg:
+        _annotate_luminance(info._prs, layout, bg)
+    lay.background = bg
+
+    spTree = layout.shapes._spTree
+    shape_count = 0
+    for el in xu.iter_shape_elements(spTree):
+        shape_count += 1
+        if not xu.is_placeholder(el):
+            continue
+        ph_type = xu.placeholder_type(el) or "body"
+        idx = xu.placeholder_idx(el)
+        x, y, cx, cy = xu.shape_off_ext(el)
+        if not (cx and cy):
+            # 版式常常不写几何，继承自母版同名占位符
+            fb = master_ph.get((idx, ph_type)) or master_ph.get(("type", ph_type))
+            if fb:
+                x, y, cx, cy = fb
+        ph = PlaceholderInfo(
+            idx=idx,
+            ph_type=ph_type,
+            name=xu.shape_name(el),
+            left=x or 0,
+            top=y or 0,
+            width=cx or 0,
+            height=cy or 0,
+        )
+        _apply_placeholder_fonts(ph, el, master_fonts, info)
+        lay.placeholders.append(ph)
+
+    # 忽略 idx/type 无效的
+    lay.placeholders = [
+        p for p in lay.placeholders if p.width and p.height
+    ] or lay.placeholders
+    lay.shape_count = shape_count
+    return lay
+
+
+def _apply_placeholder_fonts(ph: PlaceholderInfo, el, master_fonts, info: TemplateInfo) -> None:
+    txBody = el.find(qn("p:txBody"))
+    if txBody is not None:
+        lstStyle = txBody.find(qn("a:lstStyle"))
+        if lstStyle is not None:
+            lvl1 = lstStyle.find(qn("a:lvl1pPr"))
+            props = _read_defRPr(lvl1)
+            ph.font_size_pt = props.get("size_pt")
+            ph.font_name = props.get("font")
+            ph.bold = props.get("bold")
+            ph.color = props.get("color")
+            ph.align = props.get("align")
+        # 直接写在 run 上的属性优先级更高
+        r = txBody.find(f".//{qn('a:r')}")
+        if r is not None:
+            rPr = r.find(qn("a:rPr"))
+            if rPr is not None:
+                if rPr.get("sz"):
+                    ph.font_size_pt = int(rPr.get("sz")) / 100.0
+                if rPr.get("b") is not None:
+                    ph.bold = rPr.get("b") in ("1", "true")
+    if ph.font_size_pt is None or ph.font_name is None:
+        fallback = master_fonts.get("title" if ph.is_title else "body") or master_fonts.get("other") or {}
+        if ph.font_size_pt is None:
+            ph.font_size_pt = fallback.get("size_pt")
+        if ph.font_name is None:
+            ph.font_name = fallback.get("font")
+        if ph.bold is None:
+            ph.bold = fallback.get("bold")
+        if ph.color is None:
+            ph.color = fallback.get("color")
+    if ph.font_name is None:
+        ph.font_name = info.heading_font() if ph.is_title else info.cjk_font()
+
+
+def _annotate_luminance(prs, owner, bg: dict) -> None:
+    """背景是图片时，估算平均亮度，用来决定文字用深色还是浅色。"""
+    if bg.get("kind") != "picture" or not bg.get("rId"):
+        return
+    try:
+        part = owner.part.related_part(bg["rId"])
+        blob = part.blob
+    except Exception:
+        return
+    bg["blob"] = blob
+    try:
+        from PIL import Image
+
+        with Image.open(io.BytesIO(blob)) as im:
+            im = im.convert("L").resize((32, 32))
+            px = list(im.getdata())
+        bg["luminance"] = sum(px) / (255.0 * len(px))
+    except Exception:
+        bg["luminance"] = None
+
+
+# --------------------------------------------------------------------------
+# 装饰层（背景图 / 页眉页脚 / 角标）检测
+# --------------------------------------------------------------------------
+def _detect_chrome(prs: Presentation, info: TemplateInfo) -> None:
+    slides = list(prs.slides)
+    if not slides:
+        return
+
+    sig_count: Counter = Counter()
+    sig_repr: Dict[tuple, ChromeItem] = {}
+    per_layout_sigs: Dict[int, Dict[tuple, set]] = defaultdict(lambda: defaultdict(set))
+    layout_slide_count: Counter = Counter()
+
+    for si, slide in enumerate(slides):
+        lay_idx = _layout_index_of(info, slide)
+        layout_slide_count[lay_idx] += 1
+        spTree = slide.shapes._spTree
+        for el in xu.iter_shape_elements(spTree):
+            if xu.is_placeholder(el):
+                continue
+            name = xu.shape_name(el)
+            if name.startswith("__pptxgen"):
+                continue
+            box = xu.shape_off_ext(el)
+            full_bleed = xu.full_bleed_ratio(el, info.width, info.height) >= 0.9
+            key = (name, box[0], box[1], box[2], box[3])
+            sig_count[key] += 1
+            per_layout_sigs[lay_idx][key].add(si)
+            if key not in sig_repr:
+                sig_repr[key] = ChromeItem(
+                    element=el,
+                    src_slide=slide,
+                    name=name,
+                    box=box,
+                    occurrences=0,
+                    is_full_bleed=full_bleed,
+                    fill_luminance=(xu.solid_fill_luminance(el, info.theme_colors)
+                                    if full_bleed else None),
+                )
+
+    threshold = max(2, int(len(slides) * 0.6 + 0.5))
+    global_items: List[ChromeItem] = []
+    for key, cnt in sig_count.items():
+        item = sig_repr[key]
+        keep = cnt >= threshold
+        # 整页背景图：出现在 >=2 页，或模板本身就只有 1-2 页示例
+        if item.is_full_bleed and (cnt >= 2 or len(slides) <= 2):
+            keep = True
+        if keep:
+            item.occurrences = cnt
+            global_items.append(item)
+
+    # 面积大的先画（背景在下），小的在上
+    global_items.sort(key=lambda it: -((it.box[2] or 0) * (it.box[3] or 0)))
+    info.global_chrome = global_items
+
+    # 按版式细分：只用某个版式的幻灯片上重复出现的装饰
+    for lay in info.layouts:
+        slides_using = per_layout_sigs.get(lay.index)
+        n = layout_slide_count.get(lay.index, 0)
+        if not slides_using or n <= 0:
+            continue
+        items = []
+        for key, sids in slides_using.items():
+            item = sig_repr[key]
+            if item in global_items:
+                continue
+            if len(sids) >= max(1, int(n * 0.6 + 0.5)):
+                item.occurrences = len(sids)
+                items.append(item)
+        items.sort(key=lambda it: -((it.box[2] or 0) * (it.box[3] or 0)))
+        lay.chrome = items
+
+    # 幻灯片级背景覆盖：多数示例页都自己设了背景 -> 视为需要继承的设计
+    _detect_slide_background(prs, info)
+
+
+def _detect_slide_background(prs: Presentation, info: TemplateInfo) -> None:
+    slides = list(prs.slides)
+    if not slides:
+        return
+    counter: Counter = Counter()
+    first: Dict[str, tuple] = {}
+    for slide in slides:
+        bg = xu.get_bg(slide._element)
+        desc = xu.describe_bg(bg)
+        if not desc or desc.get("kind") in (None, "none"):
+            continue
+        key = _bg_key(slide, desc)
+        counter[key] += 1
+        first.setdefault(key, (bg, slide))
+    if not counter:
+        return
+    key, cnt = counter.most_common(1)[0]
+    if cnt >= max(1, int(len(slides) * 0.6 + 0.5)):
+        bg, slide = first[key]
+        info.slide_background = {
+            "element": bg,
+            "owner": slide,
+            "kind": xu.describe_bg(bg).get("kind"),
+            "count": cnt,
+        }
+
+
+def _bg_key(slide, desc: dict) -> str:
+    if desc.get("kind") == "picture" and desc.get("rId"):
+        try:
+            part = slide.part.related_part(desc["rId"])
+            return f"pic:{part.partname}"
+        except Exception:
+            return "pic:unknown"
+    return f"{desc.get('kind')}:{desc.get('color')}:{desc.get('theme_idx')}"
+
+
+def _layout_index_of(info: TemplateInfo, slide) -> int:
+    """返回幻灯片所用版式在全局版式表中的下标（跨多母版）。"""
+    try:
+        partname = str(slide.slide_layout.part.partname)
+    except Exception:
+        return -1
+    for i, lo in enumerate(info.layout_objects):
+        try:
+            if str(lo.part.partname) == partname:
+                return i
+        except Exception:
+            continue
+    return -1
+
+
+# --------------------------------------------------------------------------
+# 报告
+# --------------------------------------------------------------------------
+def describe(info: TemplateInfo, verbose: bool = False) -> str:
+    lines = []
+    lines.append(f"模板文件 : {info.path}")
+    lines.append(
+        f"画布尺寸 : {inch_from_emu(info.width):.2f} x {inch_from_emu(info.height):.2f} in "
+        f"({info.width} x {info.height} EMU, 比例 {info.aspect:.3f})"
+    )
+    lines.append(f"示例幻灯片: {info.sample_slide_count} 页")
+    if info.masters:
+        lines.append("")
+        lines.append(f"母版（共 {len(info.masters)} 个，主母版 = master{info.primary_master + 1}）")
+        for m in info.masters:
+            bg = m.get("background") or {}
+            mark = "  ← 主母版" if m["index"] == info.primary_master else ""
+            lines.append(
+                f"  master{m['index'] + 1}: 版式 {m['layout_count']} 个，"
+                f"被 {m['used_by_slides']} 页示例使用，背景={bg.get('kind', '无')}{mark}"
+            )
+        if len(info.masters) > 1:
+            lines.append("  注意：多母版模板里各套设计不同，工具会统一使用主母版的配色与字体。")
+    lines.append("")
+    lines.append("主题配色")
+    for k, v in info.theme_colors.items():
+        lines.append(f"  {k:<12} #{v}")
+    lines.append("")
+    lines.append("主题字体")
+    for k, v in info.theme_fonts.items():
+        lines.append(f"  {k:<12} {v}")
+    lines.append("")
+    lines.append("母版背景")
+    lines.append(f"  {_fmt_bg(info.master_background)}")
+    lines.append("")
+    lines.append("版式列表")
+    for lay in info.layouts:
+        title = lay.find_title()
+        body = lay.find_body()
+        lines.append(
+            f"  [{lay.index:>2}] {lay.name}"
+            f"  占位符={len(lay.placeholders)}"
+            f"  标题={'有' if title else '无'}"
+            f"  正文={'有' if body else '无'}"
+            f"  背景={_fmt_bg(lay.background, short=True)}"
+            f"  专属装饰={len(lay.chrome)}"
+        )
+        if verbose:
+            for ph in lay.placeholders:
+                color = f"颜色=#{ph.color}" if ph.color else "颜色=继承"
+                lines.append(
+                    f"        - idx={ph.idx} type={ph.ph_type} name={ph.name!r} "
+                    f"box=({inch_from_emu(ph.left):.2f},{inch_from_emu(ph.top):.2f},"
+                    f"{inch_from_emu(ph.width):.2f},{inch_from_emu(ph.height):.2f}) "
+                    f"字号={ph.font_size_pt} 字体={ph.font_name} {color}"
+                )
+    lines.append("")
+    lines.append(f"全局装饰层 (会复制到新页): {len(info.global_chrome)} 个")
+    for it in info.global_chrome:
+        w = inch_from_emu(it.box[2]) if it.box[2] else 0
+        h = inch_from_emu(it.box[3]) if it.box[3] else 0
+        kind = "整页背景" if it.is_full_bleed else "装饰"
+        lines.append(
+            f"  - {it.name!r} [{kind}] {w:.2f}x{h:.2f}in 出现 {it.occurrences} 次"
+        )
+    return "\n".join(lines)
+
+
+def _fmt_bg(bg: Optional[dict], short: bool = False) -> str:
+    if not bg:
+        return "无"
+    kind = bg.get("kind")
+    src = bg.get("from", "?")
+    if kind == "picture":
+        lum = bg.get("luminance")
+        lum_s = f" 亮度={lum:.2f}" if isinstance(lum, float) else ""
+        return f"图片(from={src}){'' if short else lum_s}"
+    if kind == "solid":
+        return f"纯色 #{bg.get('color')}(from={src})"
+    if kind == "ref":
+        return f"主题引用 idx={bg.get('theme_idx')} #{bg.get('color')}(from={src})"
+    return f"{kind}(from={src})"