dsh-courseware 0.1.0

package/engine/pptxgen/render.py

@@ -0,0 +1,1673 @@
+"""渲染引擎：把课件规格套用模板渲染成 pptx。"""
+
+from __future__ import annotations
+
+import os
+import re
+from typing import Dict, List, Optional, Sequence, Tuple
+
+from pptx.enum.shapes import MSO_SHAPE
+from pptx.enum.text import MSO_ANCHOR, MSO_AUTO_SIZE
+from pptx.oxml.ns import qn
+from pptx.util import Emu, Pt
+
+from . import xmlutil as xu
+from .layoutmap import build_map, resolve_layout_ref
+from .patterns import guess_pattern
+from .profile import StyleProfile, learn_profile
+from .shapes import (ALIGN_MAP, Para, add_line, add_picture_fit, add_shape,
+                     add_textbox, fit_paras, image_size, rounded_box,
+                     write_paras)
+from .template import LayoutInfo, PlaceholderInfo, TemplateInfo
+from .util import (EMU_PER_INCH, emu_from_inch, mix, parse_color, pt_from_emu,
+                   readable_on, relative_luminance, text_width_pt)
+
+# 基准字号（针对 16:9 / 13.333x7.5in 的画布），会按画布尺寸缩放
+BASE_FONTS = {
+    "cover_title": 40, "cover_sub": 18, "cover_meta": 13,
+    "title": 28, "subtitle": 14,
+    "toc_item": 17, "toc_num": 20,
+    "section_num": 60, "section_title": 32,
+    "goal": 17, "card_title": 16, "card_item": 14,
+    "bullet0": 17, "bullet1": 14,
+    "question": 16, "option": 14, "answer": 13,
+    "mind_center": 19, "mind_branch": 15, "mind_item": 12.5,
+    "page_num": 10,
+}
+
+BULLETS = ["●", "–", "·"]
+
+
+class RenderReport:
+    def __init__(self):
+        self.entries: List[tuple] = []      # (页型, 标题)
+        self.warnings: List[str] = []
+
+    @property
+    def slides(self) -> List[str]:
+        return [f"P{i:>2} [{t}] {title}" for i, (t, title) in enumerate(self.entries, 1)]
+
+    def add(self, stype: str, title: str) -> None:
+        self.entries.append((stype, title))
+
+    def ok(self) -> bool:
+        return not self.warnings
+
+    def text(self) -> str:
+        lines = [f"生成 {len(self.entries)} 页："]
+        lines.extend("  " + s for s in self.slides)
+        if self.warnings:
+            lines.append("")
+            lines.append(f"注意（{len(self.warnings)} 条）：")
+            for w in self.warnings:
+                lines.append(f"  ! {w}")
+        return "\n".join(lines)
+
+
+class Renderer:
+    def __init__(self, tpl: TemplateInfo, deck: dict, base_dir: Optional[str] = None):
+        self.tpl = tpl
+        self.deck = deck
+        self.base_dir = base_dir or deck.get("_dir") or os.getcwd()
+        self.prs = tpl._prs
+        self.W = tpl.width
+        self.H = tpl.height
+        self.scale = min(self.W / 12192000.0, self.H / 6858000.0) or 1.0
+        self.map = build_map(tpl, deck.get("layout_map"))
+        self.opts = deck["options"]
+        self.accents = tpl.accent_colors()
+        self.primary = tpl.primary_color()
+        self.report = RenderReport()
+        self.profile: Optional[StyleProfile] = None
+        self.use_chip = False
+        if str(self.opts.get("style_profile", "auto")).lower() not in ("off", "false", "none", "no", "0"):
+            try:
+                self.profile = learn_profile(tpl)
+            except Exception as exc:
+                self.warn(f"样式档案学习失败（已忽略）：{exc}")
+        self.use_chip = bool(self.profile and self.profile.has_chip_layout)
+        self.image_manifest = self._load_image_manifest()
+        self._answer_pool: List[dict] = []
+        self._page_no = 0
+        self._built_types: List[str] = []
+        self._last_practice_idx = -1
+
+    # ==================================================================
+    # 主流程
+    # ==================================================================
+    def render(self, out_path: str, *, keep_template_slides: bool = False) -> RenderReport:
+        if not keep_template_slides:
+            self._remove_all_slides()
+
+        slides = self.deck["slides"]
+        for i, spec in enumerate(slides):
+            self._render_one(spec, i, len(slides))
+
+        n_answers = 0
+        if self.opts["answer_mode"] == "end" and self._answer_pool:
+            n_answers = self._render_answer_slides()
+        if n_answers and self._last_practice_idx >= 0:
+            self._move_tail_slides_after(self._last_practice_idx, n_answers)
+
+        self._add_page_numbers()
+        os.makedirs(os.path.dirname(os.path.abspath(out_path)) or ".", exist_ok=True)
+        self.prs.save(out_path)
+        return self.report
+
+    def _move_tail_slides_after(self, anchor: int, count: int) -> None:
+        """把末尾的 count 页（参考答案）移动到 anchor 页之后。"""
+        sldIdLst = self.prs.slides._sldIdLst
+        ids = list(sldIdLst)
+        if count <= 0 or len(ids) < count:
+            return
+        moved = ids[len(ids) - count:]
+        for el in moved:
+            sldIdLst.remove(el)
+        remaining = list(sldIdLst)
+        pos = min(anchor + 1, len(remaining))
+        for offset, el in enumerate(moved):
+            remaining.insert(pos + offset, el)
+        for el in remaining:
+            sldIdLst.append(el)
+        # 报告顺序同步调整
+        if self.report.entries and count <= len(self.report.entries):
+            tail = self.report.entries[-count:]
+            rest = self.report.entries[:-count]
+            self.report.entries = rest[:pos] + tail + rest[pos:]
+        self._built_types[-count:] = []
+
+    def _render_one(self, spec: dict, index: int, total: int) -> None:
+        stype = spec["type"]
+        handler = getattr(self, f"_slide_{stype}", None)
+        if handler is None:
+            self.warn(f"未知页型 {stype!r}，已按知识点页处理")
+            handler = self._slide_content
+        slide, lay = self._new_slide(spec)
+        try:
+            handler(slide, lay, spec, index, total)
+        except Exception as exc:  # 单页失败不应中断整份课件
+            self.warn(f"第 {index + 1} 页（{stype}）渲染异常：{exc}")
+        self._prune_empty_placeholders(slide)
+        note = spec.get("note")
+        if note:
+            self._set_notes(slide, note)
+        self.report.add(stype, spec.get("title", ""))
+        self._built_types.append(stype)
+        if stype == "practice":
+            self._last_practice_idx = len(self._built_types) - 1
+
+    # ==================================================================
+    # 幻灯片创建 / 装饰层
+    # ==================================================================
+    def _new_slide(self, spec: dict):
+        idx = self.map.get(spec["type"], 0)
+        ref = spec.get("layout")
+        if ref is not None:
+            resolved = resolve_layout_ref(self.tpl, ref)
+            if resolved is None:
+                self.warn(f"找不到版式 {ref!r}，改用默认映射")
+            else:
+                idx = resolved
+        try:
+            layout = self.tpl.layout_objects[idx]
+        except (IndexError, AttributeError):
+            layout = self.prs.slide_layouts[idx]
+        slide = self.prs.slides.add_slide(layout)
+        lay = self.tpl.layout_by_index(idx)
+        self._apply_role_background(slide, spec)
+        self._apply_chrome(slide, lay, spec)
+        return slide, lay
+
+    def _load_image_manifest(self) -> dict:
+        """读取已生成配图的清单（渲染阶段不需要任何 API key）。"""
+        from .imagegen import normalize_dir, read_manifest
+
+        opts = (self.deck.get("options") or {}).get("images") or {}
+        cache_dir = normalize_dir(opts.get("cache_dir"), self.base_dir)
+        try:
+            return read_manifest(cache_dir)
+        except Exception:
+            return {}
+
+    def _apply_role_background(self, slide, spec: dict) -> None:
+        """封面/结束页如果自带幻灯片级背景，就照搬过来（母版背景会被它覆盖）。"""
+        role_bg = (self.tpl.role_background or {}).get(spec.get("type"))
+        if not role_bg:
+            return
+        try:
+            xu.clone_bg(role_bg["owner"], role_bg["element"], slide)
+        except Exception as exc:
+            self.warn(f"{spec.get('type')} 页背景复制失败：{exc}")
+
+    def _apply_chrome(self, slide, lay: Optional[LayoutInfo], spec: dict) -> None:
+        mode = spec.get("chrome")
+        if mode is None:
+            mode = self.opts.get("chrome", "auto")
+        if mode is False or str(mode).strip().lower() in ("off", "false", "none", "no", "0"):
+            return
+        new_els = []
+        items = list(self.tpl.global_chrome)
+        if lay is not None:
+            items += list(lay.chrome)
+        text_map = self.opts.get("chrome_text_map") or {}
+        for item in items:
+            try:
+                el = xu.clone_shape(item.src_slide, item.element, slide)
+                if text_map:
+                    self._remap_cloned_text(el, text_map)
+                new_els.append(el)
+            except Exception as exc:
+                self.warn(f"装饰形状 {item.name!r} 复制失败：{exc}")
+        if new_els:
+            spTree = slide.shapes._spTree
+            for el in reversed(new_els):
+                spTree.remove(el)
+                spTree.insert(2, el)
+
+        bgc = self.tpl.slide_background
+        if bgc is not None:
+            try:
+                xu.clone_bg(bgc["owner"], bgc["element"], slide)
+            except Exception as exc:
+                self.warn(f"背景复制失败：{exc}")
+
+    def _remap_cloned_text(self, el, text_map: Dict[str, str]) -> None:
+        """把克隆过来的装饰文本按映射整体替换（例如模板封面"立秋"→"立夏"）。"""
+        for t in el.iter(qn("a:t")):
+            if t.text and t.text in text_map:
+                t.text = text_map[t.text]
+
+    def _remove_all_slides(self) -> None:
+        sldIdLst = self.prs.slides._sldIdLst
+        for sldId in list(sldIdLst):
+            rId = sldId.get(qn("r:id"))
+            try:
+                self.prs.part.drop_rel(rId)
+            except Exception:
+                pass
+            sldIdLst.remove(sldId)
+
+    def _prune_empty_placeholders(self, slide) -> None:
+        for ph in list(slide.placeholders):
+            try:
+                phtype = ph.placeholder_format.type
+            except Exception:
+                continue
+            try:
+                has_text = bool(ph.text_frame.text.strip())
+            except Exception:
+                has_text = False
+            if not has_text:
+                el = ph._element
+                parent = el.getparent()
+                if parent is not None:
+                    parent.remove(el)
+
+    def _set_notes(self, slide, text: str) -> None:
+        try:
+            slide.notes_slide.notes_text_frame.text = str(text)
+        except Exception:
+            pass
+
+    # ==================================================================
+    # 几何 / 配色
+    # ==================================================================
+    def fz(self, key: str) -> float:
+        return BASE_FONTS.get(key, 16) * self.scale
+
+    def body_font(self) -> str:
+        """正文中文字体：优先用样张里实际用的字体。"""
+        if self.profile and self.profile.body_font:
+            return self.profile.body_font
+        return self.tpl.cjk_font()
+
+    def body_size(self, key: str = "bullet0") -> float:
+        """正文字号：以模板学到的正文为基准，收敛到"图文混排也放得下"的档位。
+
+        模板样张常是"一页没几条字"的大字号；一旦页面里有卡片、步骤、配图，
+        同字号会撑爆版面、逼着引擎逐页缩字，反而造成页与页字号忽大忽小。
+        这里统一压到同一档，让纯文字页和卡片页的字号保持一致。
+        """
+        base = float(self.profile.body_size_pt) if (self.profile and self.profile.body_size_pt) \
+            else self.fz(key)
+        return max(13.0, min(base * 0.72, 22.0))
+
+    # 正文族字号阶梯：全部相对正文基准等比推导，避免"28pt 正文"旁边出现"14pt 卡片"
+    _CONTENT_RATIO = {
+        "body": 1.0,          # 正文要点
+        "block_title": 1.08,  # 卡片标题 / 小标题（加粗，略大）
+        "item": 0.88,         # 卡片条目 / 步骤说明
+        "key": 1.35,          # 核心问题 / 结论（视觉锚点）
+        "lead": 0.75,         # 导语
+        "caption": 0.55,      # 图注 / 页码
+    }
+    _CONTENT_CLAMP = {
+        "body": (13.0, 22.0), "block_title": (14.0, 24.0), "item": (12.0, 20.0),
+        "key": (18.0, 30.0), "lead": (11.0, 17.0), "caption": (9.0, 13.0),
+    }
+
+    def csize(self, kind: str) -> float:
+        """正文族字号：相对正文基准等比缩放（模板换字号时整族一起走）。"""
+        base = self.body_size()
+        lo, hi = self._CONTENT_CLAMP.get(kind, (9.0, 30.0))
+        v = base * self._CONTENT_RATIO.get(kind, 1.0)
+        return max(lo, min(v, hi))
+
+    def body_line_spacing(self) -> float:
+        if self.profile and self.profile.body_line_spacing:
+            return float(self.profile.body_line_spacing)
+        return 1.30
+
+    def _is_dark(self, lay: Optional[LayoutInfo]) -> bool:
+        bg = (lay.background if lay else None) or self.tpl.master_background
+        if bg:
+            if bg.get("kind") == "picture":
+                lum = bg.get("luminance")
+                if lum is not None:
+                    return lum < 0.45
+            elif bg.get("color"):
+                return relative_luminance(bg["color"]) < 0.45
+        # 有的模板不用 <p:bg>，而是拿整页纯色形状当背景（画在样张或版式里）
+        for item in self.tpl.global_chrome:
+            if getattr(item, "is_full_bleed", False) and item.fill_luminance is not None:
+                return item.fill_luminance < 0.45
+        if lay is not None:
+            lum = self._layout_bg_luminance(lay)
+            if lum is not None:
+                return lum < 0.45
+        return False
+
+    def _layout_bg_luminance(self, lay: LayoutInfo) -> Optional[float]:
+        """版式里若画了一个覆盖整页的纯色形状，就把它当作实际底色。"""
+        try:
+            spTree = self.tpl.layout_objects[lay.index].shapes._spTree
+        except Exception:
+            return None
+        for el in xu.iter_shape_elements(spTree):
+            if xu.full_bleed_ratio(el, self.W, self.H) < 0.9:
+                continue
+            lum = xu.solid_fill_luminance(el, self.tpl.theme_colors)
+            if lum is not None:
+                return lum
+        return None
+
+    def _palette(self, lay: Optional[LayoutInfo]) -> dict:
+        if self._is_dark(lay):
+            return {
+                "text": "FFFFFF", "muted": "CFD8E3",
+                "card": "FFFFFF", "card_alpha": 0.14, "card_line": "FFFFFF",
+                "card_line_alpha": 0.30, "card_text": "FFFFFF",
+            }
+        return {
+            "text": self.tpl.text_color(), "muted": self.tpl.muted_color(),
+            "card": mix("FFFFFF", self.primary, 0.10), "card_alpha": 1.0,
+            "card_line": mix("FFFFFF", self.primary, 0.32), "card_line_alpha": 1.0,
+            "card_text": self.tpl.text_color(),
+        }
+
+    def _default_title_box(self) -> Tuple[int, int, int, int]:
+        return (int(self.W * 0.075), int(self.H * 0.075),
+                int(self.W * 0.85), int(self.H * 0.15))
+
+    def _default_body_box(self) -> Tuple[int, int, int, int]:
+        return (int(self.W * 0.075), int(self.H * 0.27),
+                int(self.W * 0.85), int(self.H * 0.62))
+
+    def _title_box(self, lay: Optional[LayoutInfo]) -> Tuple[int, int, int, int]:
+        ph = lay.find_title() if lay else None
+        if ph and ph.width and ph.height:
+            return ph.box
+        return self._default_title_box()
+
+    def _body_box(self, lay: Optional[LayoutInfo]) -> Tuple[int, int, int, int]:
+        ph = lay.find_body() if lay else None
+        if ph and ph.width and ph.height:
+            return ph.box
+        return self._default_body_box()
+
+    # ==================================================================
+    # 占位符 / 文本
+    # ==================================================================
+    def _ph_shape(self, slide, ph_info: PlaceholderInfo):
+        if ph_info.idx is not None:
+            for ph in slide.placeholders:
+                if ph.placeholder_format.idx == ph_info.idx:
+                    return ph
+        want_title = ph_info.is_title
+        for ph in slide.placeholders:
+            try:
+                is_title = ph.placeholder_format.type in (13, 1, 3)  # TITLE/SUBTITLE/CENTER_TITLE
+            except Exception:
+                is_title = False
+            if is_title == want_title:
+                return ph
+        return None
+
+    def _fill_ph(self, slide, ph_info: PlaceholderInfo, paras: List[Para],
+                 anchor: str = "top") -> bool:
+        shape = self._ph_shape(slide, ph_info)
+        if shape is None:
+            return False
+        self._clamp_placeholder(shape, ph_info)
+        tf = shape.text_frame
+        tf.word_wrap = True
+        tf.auto_size = MSO_AUTO_SIZE.NONE
+        try:
+            tf.vertical_anchor = {
+                "top": MSO_ANCHOR.TOP, "middle": MSO_ANCHOR.MIDDLE, "bottom": MSO_ANCHOR.BOTTOM,
+            }[anchor]
+        except Exception:
+            pass
+        w_pt = pt_from_emu(max(ph_info.width - emu_from_inch(0.1), emu_from_inch(1)))
+        h_pt = pt_from_emu(max(ph_info.height, emu_from_inch(0.3)))
+        fitted = fit_paras(paras, w_pt, h_pt, floor=self.opts["fit_shrink_floor"])
+        if paras and fitted and fitted[0].size < paras[0].size * 0.85:
+            self.warn(f"自动缩小字号以适配占位符：{paras[0].text[:24]!r}")
+        write_paras(tf, fitted, default_font=ph_info.font_name)
+        return True
+
+    def _clamp_placeholder(self, shape, ph_info: PlaceholderInfo) -> None:
+        """模板的占位符本身可能超出画布（尤其是改了画布比例的模板），把它拉回来。"""
+        try:
+            x, y, cx, cy = int(shape.left), int(shape.top), int(shape.width), int(shape.height)
+        except Exception:
+            return
+        m = max(int(self.W * 0.015), 9144)
+        nx, ny, ncx, ncy = x, y, cx, cy
+        if nx < m:
+            ncx -= (m - nx)
+            nx = m
+        if ny < m:
+            ncy -= (m - ny)
+            ny = m
+        if nx + ncx > self.W - m:
+            ncx = self.W - m - nx
+        if ny + ncy > self.H - m:
+            ncy = self.H - m - ny
+        ncx = max(ncx, int(self.W * 0.15))
+        ncy = max(ncy, int(self.H * 0.05))
+        if (nx, ny, ncx, ncy) == (x, y, cx, cy):
+            return
+        try:
+            shape.left, shape.top, shape.width, shape.height = nx, ny, ncx, ncy
+        except Exception:
+            return
+        self.warn(f"占位符超出画布，已自动调整：{ph_info.name!r}")
+        ph_info.left, ph_info.top, ph_info.width, ph_info.height = nx, ny, ncx, ncy
+
+    # ---- 从模板样张学到的页面骨架 ------------------------------------
+    def _header(self, slide, lay: Optional[LayoutInfo], spec: dict,
+                default_module: Optional[str] = None) -> Tuple[int, int, int, int]:
+        """画左上角模块标签 + 标题条；返回这一页的内容区。
+
+        学到样式档案时走 profile 的模块标签/标题条；没学到（模板主要依赖版式）时，
+        支持 deck 选项把标题与模块名重定向到版式里的指定占位符：
+          title_ph_idx  页面标题填进该 idx 的占位符（如窄标题条）
+          module_ph_idx 模块名填进该 idx 的占位符（如左上角小方框）
+        """
+        title = spec.get("title", "") or ""
+        if self.use_chip and self.profile:
+            module = spec.get("module") or default_module
+            if module:
+                self._module_label(slide, module)
+            if title:
+                self._title_chip(slide, title)
+            return self.profile.content_area()
+        module = spec.get("module") or default_module
+        t_idx = self.opts.get("title_ph_idx")
+        if t_idx is not None and lay is not None:
+            ph = lay.find_placeholder(int(t_idx))
+            if ph is not None:
+                self._put_title(slide, lay, title, ph=ph)
+            else:
+                self.warn(f"找不到标题占位符 idx={t_idx}，回退默认标题位")
+                self._put_title(slide, lay, title)
+        else:
+            self._put_title(slide, lay, title)
+        m_idx = self.opts.get("module_ph_idx")
+        if module and m_idx is not None and lay is not None:
+            ph = lay.find_placeholder(int(m_idx))
+            if ph is not None:
+                base = ph.font_size_pt or self.csize("block_title")
+                self._fill_ph(slide, ph,
+                              [Para(text=module, size=base, bold=True, color=None,
+                                    font=ph.font_name, align="center", bullet="")],
+                              anchor="middle")
+            else:
+                self.warn(f"找不到模块占位符 idx={m_idx}，模块标签未渲染")
+        return self._body_box(lay)
+
+    def _module_label(self, slide, module: str) -> None:
+        sk = self.profile.module_label
+        if sk is None:
+            return
+        st = sk.style
+        self._textbox(
+            slide, sk.box,
+            [Para(text=module, size=st.size_pt or self.csize("block_title"),
+                  bold=bool(st.bold), italic=bool(st.italic), color=st.color,
+                  font=st.font or self.tpl.heading_font(), align=st.align or "center",
+                  bullet="")],
+            anchor="middle", fit=False)
+
+    def _title_chip(self, slide, title: str):
+        sk = self.profile.title_chip
+        st = sk.style
+        size = st.size_pt or self.fz("title")
+        bold = bool(st.bold)
+        pad = emu_from_inch(0.13)
+        # 中文字体下英文空格/数字往往比估算更宽，留 18% 余量，保证标题条里不折行
+        SAFETY = 1.18
+        est_pt = text_width_pt(title, size, bold)
+        max_w = int(self.W * 0.74)
+        want = emu_from_inch(est_pt * SAFETY / 72.0) + 2 * pad
+        if want <= max_w:
+            w, use_size = max(int(want), sk.box[2]), size
+        else:
+            # 太长了：缩小字号让它在一行内放得下，而不是折行溢出标题条
+            w = max_w
+            avail_pt = pt_from_emu(w - 2 * pad) / SAFETY
+            use_size = max(12.0, size * avail_pt / max(est_pt, 1.0))
+        box = (sk.box[0], sk.box[1], w, sk.box[3])
+        shp = rounded_box(slide, box, fill=sk.fill or "FFFFFF", line=sk.line,
+                          line_width_pt=max(sk.line_width_pt, 1.0), radius=sk.radius)
+        tf = shp.text_frame
+        tf.word_wrap = False          # 标题条不折行
+        tf.auto_size = MSO_AUTO_SIZE.NONE
+        tf.vertical_anchor = MSO_ANCHOR.MIDDLE
+        tf.margin_left = pad
+        tf.margin_right = pad
+        tf.margin_top = 0
+        tf.margin_bottom = 0
+        paras = [Para(text=title, size=use_size, bold=bold, italic=bool(st.italic),
+                      color=st.color, font=st.font or self.tpl.cjk_font(),
+                      align=st.align or "left", bullet="")]
+        write_paras(tf, paras, default_font=st.font or self.tpl.cjk_font())
+        return shp
+
+    def _put_title(self, slide, lay: Optional[LayoutInfo], text: str, *,
+                   size_key: str = "title", color: Optional[str] = None,
+                   align: str = "left", anchor: str = "middle",
+                   ph: Optional[PlaceholderInfo] = None) -> None:
+        if not text:
+            return
+        if ph is None:
+            ph = lay.find_title() if lay else None
+        if ph is not None:
+            base = ph.font_size_pt or self.fz(size_key)
+            paras = [Para(text=text, size=base, bold=True,
+                          color=color, font=ph.font_name, align=align, bullet="")]
+            if self._fill_ph(slide, ph, paras, anchor=anchor):
+                return
+        pal = self._palette(lay)
+        box = self._default_title_box()
+        self._textbox(slide, box, [Para(text=text, size=self.fz(size_key), bold=True,
+                                        color=color or pal["text"],
+                                        font=self.tpl.heading_font(), align=align,
+                                        bullet="")], anchor=anchor)
+
+    def _textbox(self, slide, box, paras: Sequence[Para], *, anchor: str = "top",
+                 default_font: Optional[str] = None, fit: bool = True):
+        x, y, cx, cy = self._clamp_box(box)
+        tb = add_textbox(slide, (x, y, cx, cy), anchor=anchor)
+        use = [self._expand_highlight(p) for p in paras]
+        if fit and use:
+            w_pt = pt_from_emu(cx)
+            h_pt = pt_from_emu(cy)
+            use = fit_paras(use, w_pt, h_pt, floor=self.opts["fit_shrink_floor"])
+        write_paras(tb.text_frame, use, default_font=default_font or self.tpl.cjk_font())
+        return tb
+
+    def _clamp_box(self, box) -> Tuple[int, int, int, int]:
+        """把文本框限制在画布内，保证没有任何内容跑到幻灯片外面。"""
+        x, y, cx, cy = (int(v) for v in box)
+        m = max(int(self.H * 0.012), 9144)
+        cx = max(cx, int(self.W * 0.04))
+        cy = max(cy, int(self.H * 0.025))
+        x = max(min(x, self.W - m - cx), m)
+        y = max(min(y, self.H - m - cy), m)
+        cx = min(cx, self.W - m - x)
+        cy = min(cy, self.H - m - y)
+        return (x, y, max(cx, 1), max(cy, 1))
+
+    def _subtitle(self, slide, lay, box, text: str, *, size_key="subtitle",
+                  color: Optional[str] = None, align: str = "left", anchor: str = "top"):
+        if not text:
+            return None
+        pal = self._palette(lay)
+        return self._textbox(slide, box, [Para(text=text, size=self.fz(size_key),
+                                               color=color or pal["muted"],
+                                               font=self.tpl.cjk_font(), align=align,
+                                               bullet="")], anchor=anchor)
+
+    # ==================================================================
+    # 各页型
+    # ==================================================================
+    def _slide_cover(self, slide, lay, spec, index, total):
+        pal = self._palette(lay)
+        prof_box = self.profile.cover_title_box if self.profile else None
+        if prof_box:
+            tph = lay.find_title() if lay else None
+            size = (tph.font_size_pt if tph and tph.font_size_pt else None) or self.fz("cover_title")
+            self._textbox(slide, prof_box,
+                          [Para(text=spec.get("title", ""), size=size,
+                                bold=True, color=None,
+                                font=(tph.font_name if tph else None) or self.tpl.heading_font(),
+                                align="center", bullet="")], anchor="middle")
+            self._cover_meta(slide, lay, spec, pal, after=prof_box)
+            return
+        ph = lay.find_title() if lay else None
+        if ph is not None:
+            base = ph.font_size_pt or self.fz("cover_title")
+            self._fill_ph(slide, ph, [Para(
+                text=spec.get("title", ""), size=base, bold=True,
+                font=ph.font_name or self.tpl.heading_font(), bullet="",
+            )], anchor="middle")
+        else:
+            self._textbox(slide, (int(self.W * 0.1), int(self.H * 0.34), int(self.W * 0.8), int(self.H * 0.18)),
+                          [Para(text=spec.get("title", ""), size=self.fz("cover_title"), bold=True,
+                                color=pal["text"], font=self.tpl.heading_font(), align="left", bullet="")],
+                          anchor="middle")
+
+        sub = spec.get("subtitle", "")
+        # 副标题占位符
+        if lay:
+            sub_ph = next((p for p in lay.placeholders if p.ph_type == "subtitle"), None)
+            if sub_ph is not None and sub:
+                self._fill_ph(slide, sub_ph, [Para(
+                    text=sub, size=sub_ph.font_size_pt or self.fz("cover_sub"),
+                    color=sub_ph.color, font=sub_ph.font_name or self.tpl.cjk_font(),
+                    bullet="")], anchor="middle")
+                sub = ""
+
+        tx, ty, tw, th = self._title_box(lay)
+        self._cover_meta(slide, lay, spec, pal, after=(tx, ty, tw, th))
+
+    def _cover_meta(self, slide, lay, spec, pal, after) -> None:
+        tx, ty, tw, th = after
+        sub = spec.get("subtitle", "")
+        if sub:
+            self._textbox(slide, (tx, ty + th + int(self.H * 0.025), tw, int(self.H * 0.12)),
+                          [Para(text=sub, size=self.fz("cover_sub"), color=pal["muted"],
+                                font=self.tpl.cjk_font(), align="center" if self.profile else None,
+                                bullet="")])
+        meta = "　".join(x for x in [spec.get("teacher", ""), spec.get("school", ""),
+                                     spec.get("date", "")] if x)
+        if meta:
+            self._textbox(slide, (tx, int(self.H * 0.80), tw, int(self.H * 0.09)),
+                          [Para(text=meta, size=self.fz("cover_meta"), color=pal["muted"],
+                                font=self.tpl.cjk_font(), align="center" if self.profile else None,
+                                bullet="")])
+
+    def _slide_toc(self, slide, lay, spec, index, total):
+        pal = self._palette(lay)
+        items = [it for it in spec.get("items", []) if it.get("text")]
+        spec = {**spec, "title": spec.get("title") or "目 录"}
+        bx, by, bw, bh = self._header(slide, lay, spec, "目录")
+        if not items:
+            return
+        n = len(items)
+        two_col = n > 6 and self.W / float(self.H) > 1.4
+        per_col = (n + 1) // 2 if two_col else n
+        col_w = bw // 2 - int(self.W * 0.02) if two_col else bw
+        row_h = max(int(bh / max(per_col, 1)), emu_from_inch(0.42))
+        num_size = self.fz("toc_num")
+        item_size = self.fz("toc_item")
+
+        for i, it in enumerate(items):
+            col = i // per_col if two_col else 0
+            row = i % per_col if two_col else i
+            x = bx + col * (col_w + int(self.W * 0.04))
+            y = by + row * row_h
+            entry_h = int(row_h * 0.78)
+            accent = self.accents[i % len(self.accents)]
+            # 序号
+            self._textbox(slide, (x, y, int(col_w * 0.14), entry_h),
+                          [Para(text=f"{i + 1:02d}", size=num_size, bold=True, color=accent,
+                                font=self.tpl.heading_font(), align="left", bullet="")],
+                          anchor="middle", fit=False)
+            # 文本
+            self._textbox(slide, (x + int(col_w * 0.16), y, int(col_w * 0.82), entry_h),
+                          [Para(text=it["text"], size=item_size, color=pal["text"],
+                                font=self.tpl.cjk_font(), bullet="")],
+                          anchor="middle")
+            # 分隔线
+            if row < per_col - 1:
+                add_line(slide, x, y + row_h - int(emu_from_inch(0.02)),
+                         x + col_w, y + row_h - int(emu_from_inch(0.02)),
+                         color=pal["card_line"], width_pt=0.75)
+
+    def _slide_section(self, slide, lay, spec, index, total):
+        pal = self._palette(lay)
+        num = spec.get("index", "")
+        title = spec.get("title", "")
+        ph = lay.find_title() if lay else None
+        if ph is not None:
+            base = ph.font_size_pt or self.fz("section_title")
+            self._fill_ph(slide, ph, [Para(
+                text=title, size=base, bold=True, font=ph.font_name or self.tpl.heading_font(),
+                bullet="")], anchor="middle")
+            tx, ty, tw, th = ph.box
+        else:
+            tx, ty, tw, th = self._title_box(lay)
+            self._textbox(slide, (tx, ty, tw, th),
+                          [Para(text=title, size=self.fz("section_title"), bold=True,
+                                color=pal["text"], font=self.tpl.heading_font(), bullet="")],
+                          anchor="middle")
+
+        bottom = int(self.H * 0.90)
+        accent = self.accents[(int(num) - 1) % len(self.accents)] if str(num).isdigit() else self.primary
+        num_h = int(self.H * 0.18)
+        num_y = max(int(self.H * 0.05), ty - num_h - int(self.H * 0.015))
+        self._textbox(slide, (tx, num_y, tw, max(ty - num_y - int(self.H * 0.01), int(self.H * 0.08))),
+                      [Para(text=f"{num:02d}" if str(num).isdigit() else str(num),
+                            size=self.fz("section_num"), bold=True, color=accent,
+                            font=self.tpl.heading_font(), bullet="")], anchor="middle", fit=False)
+
+        cursor = ty + th + int(self.H * 0.02)
+        add_line(slide, tx, cursor, tx + int(tw * 0.28), cursor, color=accent, width_pt=3.5)
+        cursor += int(self.H * 0.025)
+
+        sub = spec.get("subtitle", "")
+        if sub and bottom - cursor > int(self.H * 0.09):
+            h = min(int(self.H * 0.1), bottom - cursor)
+            self._subtitle(slide, lay, (tx, cursor, tw, h), sub)
+            cursor += h + int(self.H * 0.015)
+
+        items = [it for it in spec.get("items", []) if it.get("text")]
+        if items and bottom - cursor > int(self.H * 0.1):
+            self._bullets(slide, lay, (tx, cursor, int(tw * 0.72), bottom - cursor), items,
+                          base_size=self.body_size() * 0.82)
+
+    def _slide_objectives(self, slide, lay, spec, index, total):
+        pal = self._palette(lay)
+        spec = {**spec, "title": spec.get("title") or "学习目标"}
+        bx, by, bw, bh = self._header(slide, lay, spec, "学习目标")
+        sub = spec.get("subtitle", "")
+        if sub:
+            self._textbox(slide, (bx, by, bw, int(self.H * 0.07)),
+                          [Para(text=sub, size=self.csize("lead"), color=pal["muted"],
+                                font=self.tpl.cjk_font(), bullet="")])
+            by += int(self.H * 0.085)
+            bh -= int(self.H * 0.085)
+        # 支持用 pattern 排目标页（例如把"知识/能力/素养"排成三张卡的本课导航页）
+        pattern = str(spec.get("pattern") or "").strip().lower()
+        if pattern and pattern != "auto" and (spec.get("cards") or spec.get("compare")
+                                              or spec.get("timeline")):
+            if self._render_pattern(slide, lay, (bx, by, bw, bh), spec, [], pattern):
+                return
+        goals = [g for g in spec.get("goals", []) if g.get("text")]
+        keys = [g for g in spec.get("key_points", []) if g.get("text")]
+        hards = [g for g in spec.get("hard_points", []) if g.get("text")]
+
+        has_cards = bool(keys or hards)
+        goals_h = int(bh * (0.52 if has_cards else 1.0))
+        if goals:
+            self._bullets(slide, lay, (bx, by, bw, goals_h), goals,
+                          base_size=self.body_size(), bullet_char="✓",
+                          bullet_color=self.accents[2 % len(self.accents)] if len(self.accents) > 2 else self.primary)
+
+        if has_cards:
+            top = by + goals_h + int(self.H * 0.03)
+            card_h = max(bh - goals_h - int(self.H * 0.03), int(self.H * 0.2))
+            n = 2 if (keys and hards) else 1
+            gap = int(bw * 0.03)
+            card_w = (bw - gap * (n - 1)) // n
+            specs = []
+            if keys:
+                specs.append(("重点", keys, self.accents[1 % len(self.accents)]))
+            if hards:
+                specs.append(("难点", hards, self.accents[5 % len(self.accents)]))
+            for i, (label, pts, color) in enumerate(specs):
+                x = bx + i * (card_w + gap)
+                self._card(slide, lay, (x, top, card_w, card_h), label, pts, color)
+
+    def _card(self, slide, lay, box, label, pts, color):
+        pal = self._palette(lay)
+        x, y, w, h = box
+        rounded_box(slide, box, fill=pal["card"], fill_alpha=pal["card_alpha"],
+                    line=color, line_width_pt=1.25, radius=0.06)
+        pad = int(w * 0.06)
+        head_h = int(h * 0.22)
+        self._textbox(slide, (x + pad, y + int(h * 0.05), w - 2 * pad, head_h),
+                      [Para(text=label, size=self.csize("block_title"), bold=True, color=color,
+                            font=self.tpl.heading_font(), bullet="")], anchor="middle", fit=False)
+        inner = (x + pad, y + int(h * 0.05) + head_h, w - 2 * pad, h - head_h - int(h * 0.1))
+        self._bullets(slide, lay, inner, pts, base_size=self.body_size() * 0.85,
+                      color=pal["card_text"], bullet_char="•", bullet_color=color)
+
+    def _slide_content(self, slide, lay, spec, index, total):
+        pal = self._palette(lay)
+        images = self._resolve_images(spec)
+        bullets = [b for b in spec.get("bullets", []) if b.get("text")]
+        bx, by, bw, bh = self._header(slide, lay, spec, "科学解释")
+        # 用了标题条就不再用版式的正文占位符（位置对不上）
+        ph = None if self.use_chip else (lay.find_body() if lay else None)
+        sub = spec.get("subtitle", "")
+        if sub:
+            self._textbox(slide, (bx, by, bw, int(self.H * 0.07)),
+                          [Para(text=sub, size=self.csize("lead"), color=pal["muted"],
+                                font=self.tpl.cjk_font(), bullet="")])
+            by += int(self.H * 0.085)
+            bh -= int(self.H * 0.085)
+
+        if sub and not images and not bullets:
+            return
+
+        # 版面骨架：显式 pattern 优先，否则按内容自动挑一个。
+        # 背景/配色/模块标签/标题条一律沿用模板，只重排正文区。
+        pattern = self._resolve_pattern(spec, bullets, images)
+        side_override = None
+        if pattern in ("image_left", "image_right"):
+            side_override = "left" if pattern == "image_left" else "right"
+            pattern = "bullets"
+        if pattern != "bullets":
+            if self._render_pattern(slide, lay, (bx, by, bw, bh), spec, images, pattern):
+                return
+
+        if not images:
+            # 有副标题时不能再往正文占位符里写，否则会和副标题重叠
+            if ph is not None and bullets and not sub:
+                base = ph.font_size_pt or self.fz("bullet0")
+                paras = self._bullets_to_paras(bullets, base, ph.font_name, bullet_char=None)
+                if self._fill_ph(slide, ph, paras, anchor="top"):
+                    return
+            if bullets:
+                self._bullets(slide, lay, (bx, by, bw, bh), bullets, base_size=self.body_size())
+            return
+
+        # 有配图：左文右图（可切换）
+        side = (side_override or spec.get("image_side") or "right").lower()
+        gap = int(bw * 0.04)
+        if side in ("top", "bottom") or len(images) > 1:
+            img_h = int(bh * (0.45 if side != "bottom" else 0.45))
+            txt_h = bh - img_h - int(self.H * 0.03)
+            if side == "bottom":
+                text_box = (bx, by, bw, txt_h)
+                img_box = (bx, by + txt_h + int(self.H * 0.03), bw, img_h)
+            else:
+                img_box = (bx, by, bw, img_h)
+                text_box = (bx, by + img_h + int(self.H * 0.03), bw, txt_h)
+            if bullets:
+                self._bullets(slide, lay, text_box, bullets, base_size=self.body_size())
+            self._images_row(slide, images, img_box)
+        else:
+            txt_w = int(bw * 0.54)
+            img_w = bw - txt_w - gap
+            if side == "left":
+                img_box = (bx, by, img_w, bh)
+                txt_box = (bx + img_w + gap, by, txt_w, bh)
+            else:
+                txt_box = (bx, by, txt_w, bh)
+                img_box = (bx + txt_w + gap, by, img_w, bh)
+            if bullets:
+                self._bullets(slide, lay, txt_box, bullets, base_size=self.body_size())
+            self._images_row(slide, images, img_box)
+        cap = spec.get("image_caption")
+        if cap:
+            self._textbox(slide, (img_box[0], img_box[1] + img_box[3], img_box[2], int(self.H * 0.06)),
+                          [Para(text=cap, size=self.csize("caption"), color=pal["muted"],
+                                font=self.tpl.cjk_font(), align="center", bullet="")])
+
+    # ==================================================================
+    # 版面骨架（pattern）—— 只重排正文区，模板骨架/配色/背景一律不动
+    # ==================================================================
+    def _resolve_pattern(self, spec: dict, bullets: Sequence[dict], images) -> str:
+        """显式 pattern 优先；没有就按内容形态自动挑一个（确定性，不用随机）。"""
+        return guess_pattern(spec, bullets)
+
+    # 这几类骨架只画"图形化主体"，不画 bullets——若规格里还写了要点，
+    # 缩小主体区域、在底部留一条要点带渲染，避免内容被静默丢弃。
+    _PATTERNS_WITH_FOOTER = ("compare", "cards", "levels", "timeline")
+
+    def _render_pattern(self, slide, lay, box, spec, images, pattern: str) -> bool:
+        fn = getattr(self, f"_pattern_{pattern}", None)
+        if fn is None:
+            self.warn(f"未知版面骨架 {pattern!r}，改用默认排版")
+            return False
+        try:
+            bullets = [b for b in (spec.get("bullets") or [])
+                       if isinstance(b, dict) and str(b.get("text") or "").strip()]
+            if pattern in self._PATTERNS_WITH_FOOTER and bullets:
+                bx, by, bw, bh = box
+                strip_h = max(min(int(bh * 0.22), emu_from_inch(1.4)), int(bh * 0.14))
+                main_box = (bx, by, bw, bh - strip_h)
+                if fn(slide, lay, main_box, spec, images):
+                    self._pattern_footer(slide, lay,
+                                         (bx, by + bh - strip_h, bw, strip_h), bullets)
+                    return True
+                return False
+            return bool(fn(slide, lay, box, spec, images))
+        except Exception as exc:                       # 任何异常都退回默认排版，不炸整份课件
+            self.warn(f"版面骨架 {pattern!r} 渲染失败（改用默认排版）：{exc}")
+            return False
+
+    def _pattern_footer(self, slide, lay, box, bullets) -> None:
+        """模式页底部的要点带：承接 compare/cards/levels/timeline 主区域放不下的要点。"""
+        pal = self._palette(lay)
+        paras = self._bullets_to_paras(bullets, self.csize("item"), self.tpl.cjk_font())
+        self._textbox(slide, box, paras, anchor="middle")
+
+    def _group_bullets(self, bullets: Sequence[dict]) -> List[dict]:
+        """按 level-0 把要点分组：[{title, items:[子项]}]。"""
+        groups: List[dict] = []
+        for b in bullets:
+            text = (b.get("text") or "").strip()
+            if not text:
+                continue
+            if int(b.get("level", 0) or 0) == 0:
+                groups.append({"title": text, "items": []})
+            elif groups:
+                groups[-1]["items"].append(text)
+            else:
+                groups.append({"title": "", "items": [text]})
+        return groups
+
+    def _steps_data(self, spec: dict) -> List[dict]:
+        src = [s for s in (spec.get("steps") or []) if s.get("text")]
+        if not src:
+            src = [b for b in spec.get("bullets", []) if b.get("text")]
+        return self._group_bullets(src)
+
+    def _cards_data(self, spec: dict) -> List[dict]:
+        cards = [c for c in (spec.get("cards") or []) if c.get("title") or c.get("items")]
+        if cards:
+            return cards
+        return self._group_bullets([b for b in spec.get("bullets", []) if b.get("text")])
+
+    def _accent(self, i: int) -> str:
+        return self.accents[i % len(self.accents)] if self.accents else self.primary
+
+    # ---- 文字润色：**关键词** 内嵌强调色 ---------------------------------
+    _HL_RE = re.compile(r"\*\*(.+?)\*\*")
+
+    def _keyword_color(self) -> str:
+        """关键词高亮色：优先用模板标题色（与讲义式润色风格一致），否则主色。"""
+        if self.profile and self.profile.title_chip and self.profile.title_chip.style.color:
+            return self.profile.title_chip.style.color
+        return self.primary
+
+    def _expand_highlight(self, p: Para) -> Para:
+        """把段落文本里的 ``**关键词**`` 变成"强调色 + 加粗"的 run，其余文字保持原色。"""
+        raw = str(p.text or "")
+        if "**" not in raw or p.runs:
+            return p
+        runs: List[dict] = []
+        pos = 0
+        for m in self._HL_RE.finditer(raw):
+            if m.start() > pos:
+                runs.append({"text": raw[pos:m.start()], "color": p.color})
+            runs.append({"text": m.group(1), "bold": True, "color": self._keyword_color()})
+            pos = m.end()
+        if pos < len(raw):
+            runs.append({"text": raw[pos:], "color": p.color})
+        if not runs:
+            return p
+        q = Para(**{**p.__dict__})
+        q.text = self._HL_RE.sub(r"\1", raw)     # 去掉标记，便于精确测量
+        q.runs = runs
+        return q
+
+    def _pattern_steps(self, slide, lay, box, spec, images) -> bool:
+        """编号步骤卡 + 向下箭头：适合"第 1 步 / 第 2 步"这类递进内容。"""
+        pal = self._palette(lay)
+        groups = self._steps_data(spec)
+        if len(groups) < 2:
+            return False
+        x, y, w, h = box
+        if images:
+            img_w = int(w * 0.34)
+            gap = int(w * 0.035)
+            ax, ay, aw, ah = x, y, w - img_w - gap, h
+        else:
+            img_w = gap = 0
+            ax, ay, aw, ah = box
+        n = len(groups)
+        row_gap = max(int(ah * 0.05), emu_from_inch(0.12))
+        each = (ah - row_gap * (n - 1)) // n
+        if each < emu_from_inch(0.5):
+            return False
+        strip = int(aw * 0.012)
+        for i, g in enumerate(groups):
+            gy = ay + i * (each + row_gap)
+            accent = self._accent(i)
+            rounded_box(slide, (ax, gy, aw, each), fill=pal["card"],
+                        fill_alpha=pal["card_alpha"], line=pal["card_line"], radius=0.1)
+            rounded_box(slide, (ax, gy + int(each * 0.1), strip, int(each * 0.8)),
+                        fill=accent, line=None, radius=0.5)
+            if i < n - 1:
+                add_shape(slide, MSO_SHAPE.DOWN_ARROW,
+                          (ax + aw // 2 - int(aw * 0.011), gy + each,
+                           int(aw * 0.022), row_gap),
+                          fill=self._accent(0), line=None)
+            paras = [Para(text=f"{i + 1}. {g['title']}", size=self.csize("block_title"),
+                          bold=True, color=accent, font=self.tpl.cjk_font(), bullet="")]
+            for it in g["items"][:3]:
+                paras.append(Para(text=it, size=self.csize("item"), color=pal["muted"],
+                                  font=self.tpl.cjk_font(), bullet="", space_before=2))
+            pad = int(aw * 0.045)
+            self._textbox(slide, (ax + pad + strip, gy, aw - 2 * pad - strip, each),
+                          paras, anchor="middle")
+        if images:
+            self._images_row(slide, images, (ax + aw + gap, y, img_w, h))
+        return True
+
+    def _pattern_flow(self, slide, lay, box, spec, images) -> bool:
+        """横向方框 + 箭头：适合 2–5 个环节的流程。"""
+        pal = self._palette(lay)
+        groups = self._steps_data(spec)
+        if not (2 <= len(groups) <= 5):
+            return False
+        x, y, w, h = box
+        n = len(groups)
+        if images:
+            flow_h = int(h * 0.5)
+            img_box = (x, y + flow_h + int(h * 0.06), w, h - flow_h - int(h * 0.06))
+            fy = y
+        else:
+            flow_h = int(h * 0.66)
+            fy = y + (h - flow_h) // 2
+            img_box = None
+        arrow_w = int(w * 0.05)
+        gap = int(w * 0.012)
+        bw_ = (w - arrow_w * (n - 1) - gap * 2 * (n - 1)) // n
+        if bw_ < emu_from_inch(0.95):
+            return False
+        for i, g in enumerate(groups):
+            bx_ = x + i * (bw_ + arrow_w + gap * 2)
+            accent = self._accent(i)
+            rounded_box(slide, (bx_, fy, bw_, flow_h), fill=pal["card"],
+                        fill_alpha=pal["card_alpha"], line=accent, line_width_pt=1.6, radius=0.12)
+            badge = min(int(flow_h * 0.28), int(bw_ * 0.24))
+            by_ = fy + int(flow_h * 0.1)
+            rounded_box(slide, (bx_ + (bw_ - badge) // 2, by_, badge, badge),
+                        fill=accent, line=None, radius=0.5)
+            self._textbox(slide, (bx_ + (bw_ - badge) // 2, by_, badge, badge),
+                          [Para(text=str(i + 1), size=max(self.csize("item") - 1, 10), bold=True,
+                                color=readable_on(accent), font=self.tpl.heading_font(),
+                                align="center", bullet="")], anchor="middle", fit=False)
+            paras = [Para(text=g["title"], size=self.csize("block_title"), bold=True, color=pal["text"],
+                          font=self.tpl.cjk_font(), align="center", bullet="")]
+            if g["items"]:
+                paras.append(Para(text=" ".join(g["items"][:2]), size=self.csize("item"),
+                                  color=pal["muted"], font=self.tpl.cjk_font(), align="center",
+                                  bullet="", space_before=2))
+            pad = int(bw_ * 0.07)
+            self._textbox(slide, (bx_ + pad, fy + int(flow_h * 0.34), bw_ - 2 * pad,
+                                  int(flow_h * 0.64)), paras)
+            if i < n - 1:
+                add_shape(slide, MSO_SHAPE.RIGHT_ARROW,
+                          (bx_ + bw_ + gap, fy + int(flow_h * 0.42), arrow_w, int(flow_h * 0.16)),
+                          fill=accent, line=None)
+        if img_box:
+            self._images_row(slide, images, img_box)
+        return True
+
+    def _pattern_compare(self, slide, lay, box, spec, images) -> bool:
+        """左右两栏对比 + 中间圆标：适合"A 与 B"的并列对照。"""
+        pal = self._palette(lay)
+        cmp = spec.get("compare") or {}
+        left = cmp.get("left") or {}
+        right = cmp.get("right") or {}
+        if not (left.get("title") or left.get("items") or right.get("title") or right.get("items")):
+            return False
+        x, y, w, h = box
+        if images:
+            card_h = int(h * 0.68)
+            img_box = (x, y + card_h + int(h * 0.05), w, h - card_h - int(h * 0.05))
+        else:
+            card_h = h
+            img_box = None
+        center = int(w * 0.1)
+        cw = (w - center) // 2
+        for idx, side_data in enumerate((left, right)):
+            col = self._accent(0 if idx == 0 else 4)
+            cx = x if idx == 0 else x + cw + center
+            rounded_box(slide, (cx, y, cw, card_h), fill=pal["card"], fill_alpha=pal["card_alpha"],
+                        line=col, line_width_pt=1.6, radius=0.08)
+            head_h = int(card_h * 0.24)
+            rounded_box(slide, (cx, y, cw, head_h), fill=col, line=None, radius=0.12)
+            self._textbox(slide, (cx, y, cw, head_h),
+                          [Para(text=side_data.get("title", ""), size=self.csize("block_title"),
+                                bold=True, color=readable_on(col), font=self.tpl.heading_font(),
+                                align="center", bullet="")], anchor="middle")
+            paras = [Para(text=it, size=self.csize("item"), color=pal["text"],
+                          font=self.tpl.cjk_font(), bullet="●", space_before=5)
+                     for it in side_data.get("items", [])]
+            if paras:
+                self._textbox(slide, (cx + int(cw * 0.07), y + head_h,
+                                      cw - int(cw * 0.14), card_h - head_h), paras, anchor="middle")
+        vs = str(cmp.get("vs") or "VS")
+        d = min(int(w * 0.08), max(int(card_h * 0.18), emu_from_inch(0.32)))
+        vx = x + cw + (center - d) // 2
+        vy = y + card_h // 2 - d // 2
+        rounded_box(slide, (vx, vy, d, d), fill=self.primary, line=None, radius=0.5)
+        self._textbox(slide, (vx, vy, d, d),
+                      [Para(text=vs, size=self.csize("item"), bold=True,
+                            color=readable_on(self.primary), font=self.tpl.heading_font(),
+                            align="center", bullet="")], anchor="middle", fit=False)
+        if img_box:
+            self._images_row(slide, images, img_box)
+        return True
+
+    def _pattern_cards(self, slide, lay, box, spec, images) -> bool:
+        """卡片网格：适合并列的 2–6 个要点（每条要点带小标题）。
+
+        deck options（可选，默认保持旧行为）：
+          cards_font_scale    卡片内文字相对正文基准的字号缩放（默认 1.0，<1 字更小）
+          cards_max_height_in 卡片最大高度（英寸，默认 None 不限制，单行/多行都生效）
+        """
+        pal = self._palette(lay)
+        cards = self._cards_data(spec)
+        if not (2 <= len(cards) <= 6):
+            return False
+        try:
+            font_scale = float(self.opts.get("cards_font_scale", 1.0))
+        except (TypeError, ValueError):
+            font_scale = 1.0
+        try:
+            max_h = emu_from_inch(float(self.opts.get("cards_max_height_in")))
+        except (TypeError, ValueError):
+            max_h = 0
+        x, y, w, h = box
+        if images:
+            area_w = int(w * 0.64)
+            img_box = (x + area_w + int(w * 0.03), y, w - area_w - int(w * 0.03), h)
+        else:
+            area_w, img_box = w, None
+        n = len(cards)
+        cols = n if n <= 3 else (2 if n == 4 else 3)
+        rows = (n + cols - 1) // cols
+        gap_x = int(area_w * 0.025)
+        gap_y = int(h * 0.045)
+        cw = (area_w - gap_x * (cols - 1)) // cols
+        ch = (h - gap_y * (rows - 1)) // rows
+        # 多行卡片限制单卡高度；单行卡片默认占满内容高度，
+        # 设置了 cards_max_height_in 时单行也限制，避免卡片被拉得过长
+        if rows > 1:
+            ch = min(ch, emu_from_inch(2.5))
+        if max_h > 0:
+            ch = min(ch, max_h)
+        grid_h = ch * rows + gap_y * (rows - 1)
+        y0 = y + max((h - grid_h) // 2, 0)
+        if cw < emu_from_inch(1.05) or ch < emu_from_inch(0.62):
+            return False
+        title_size = max(self.csize("block_title") * font_scale, 12.0)
+        item_size = max(self.csize("item") * font_scale, 11.0)
+        for i, c in enumerate(cards):
+            r, col_i = divmod(i, cols)
+            cx = x + col_i * (cw + gap_x)
+            cy = y0 + r * (ch + gap_y)
+            accent = self._accent(i)
+            rounded_box(slide, (cx, cy, cw, ch), fill=pal["card"], fill_alpha=pal["card_alpha"],
+                        line=pal["card_line"], radius=0.1)
+            rounded_box(slide, (cx, cy + int(ch * 0.08), int(cw * 0.02), int(ch * 0.84)),
+                        fill=accent, line=None, radius=0.5)
+            paras = [Para(text=c["title"], size=title_size, bold=True, color=accent,
+                          font=self.tpl.cjk_font(), bullet="")]
+            for it in c["items"][:2]:
+                paras.append(Para(text=it, size=item_size, color=pal["text"],
+                                  font=self.tpl.cjk_font(), bullet="", space_before=3))
+            pad = int(cw * 0.07)
+            self._textbox(slide, (cx + pad, cy, cw - pad - int(cw * 0.04), ch), paras, anchor="middle")
+        if img_box:
+            self._images_row(slide, images, img_box)
+        return True
+
+    def _pattern_timeline(self, slide, lay, box, spec, images) -> bool:
+        """横向时间轴：适合"先有 A、后有 B"的先后/因果关系。"""
+        pal = self._palette(lay)
+        items = [t for t in (spec.get("timeline") or []) if t.get("text") or t.get("time")]
+        if len(items) < 2:
+            return False
+        x, y, w, h = box
+        if images:
+            area_w = int(w * 0.64)
+            img_box = (x + area_w + int(w * 0.03), y, w - area_w - int(w * 0.03), h)
+        else:
+            area_w, img_box = w, None
+        n = len(items)
+        axis_y = y + h // 2
+        add_line(slide, x, axis_y, x + area_w, axis_y, color=pal["card_line"], width_pt=2.4)
+        seg = area_w // n
+        for i, t in enumerate(items):
+            accent = self._accent(i)
+            cxm = x + seg // 2 + i * seg
+            d = min(int(h * 0.09), emu_from_inch(0.34))
+            rounded_box(slide, (cxm - d // 2, axis_y - d // 2, d, d), fill=accent, line=None, radius=0.5)
+            above = (i % 2 == 0)
+            bh_ = int(h * 0.34)
+            by_ = (axis_y - d // 2 - bh_ - int(h * 0.03)) if above else (axis_y + d // 2 + int(h * 0.03))
+            tw = int(seg * 0.94)
+            paras = []
+            if t.get("time"):
+                paras.append(Para(text=t["time"], size=self.csize("item"), bold=True, color=accent,
+                                  font=self.tpl.heading_font(), align="center", bullet=""))
+            paras.append(Para(text=t["text"], size=self.csize("item"), color=pal["text"],
+                              font=self.tpl.cjk_font(), align="center", bullet="",
+                              space_before=2 if t.get("time") else 0))
+            self._textbox(slide, (cxm - tw // 2, by_, tw, bh_), paras, anchor="middle")
+        if img_box:
+            self._images_row(slide, images, img_box)
+        return True
+
+    def _pattern_levels(self, slide, lay, box, spec, images) -> bool:
+        """分级/强弱梯度：适合"绿 < 黄 < 深红""一级 < 二级 < 三级"这类递进等级。
+
+        用同一色相的深浅阶梯 + 逐级放大的条块表达"由弱到强"，
+        最上一级用语义色（若内容给了 color）或最强强调色收尾。
+        """
+        pal = self._palette(lay)
+        cards = self._cards_data(spec)
+        if not (2 <= len(cards) <= 4):
+            return False
+        x, y, w, h = box
+        if images:
+            area_w = int(w * 0.6)
+            img_box = (x + area_w + int(w * 0.03), y, w - area_w - int(w * 0.03), h)
+        else:
+            area_w, img_box = w, None
+        n = len(cards)
+        gap = int(h * 0.05)
+        each = (h - gap * (n - 1)) // n
+        if each < emu_from_inch(0.5):
+            return False
+        base = self._accent(0)
+        for i, c in enumerate(cards):
+            cy = y + i * (each + gap)
+            t = (i + 1) / n                      # 由弱到强的强度
+            # 语义色优先（例如雷达图三色），否则用模板强调色的深浅阶梯
+            color = parse_color(c.get("color")) or mix("FFFFFF", base, 0.35 + 0.65 * t * 0.8)
+            block_w = int(area_w * (0.34 + 0.66 * t))
+            rounded_box(slide, (x, cy, area_w, each), fill=pal["card"],
+                        fill_alpha=pal["card_alpha"], line=pal["card_line"], radius=0.08)
+            rounded_box(slide, (x, cy, block_w, each), fill=color, line=None, radius=0.08)
+            pad = int(area_w * 0.04)
+            label = "　".join([c["title"]] + list(c["items"][:2]))
+            self._textbox(slide, (x + pad, cy, area_w - 2 * pad, each),
+                          [Para(text=label, size=self.csize("block_title"), bold=True,
+                                color=readable_on(color), font=self.tpl.cjk_font(), bullet="")],
+                          anchor="middle")
+        if img_box:
+            self._images_row(slide, images, img_box)
+        return True
+
+    def _pattern_callout(self, slide, lay, box, spec, images) -> bool:
+        """重点框 + 要点：把第一句提炼成醒目的核心问题/结论。"""
+        pal = self._palette(lay)
+        bullets = [b for b in spec.get("bullets", []) if b.get("text")]
+        if len(bullets) < 2:
+            return False
+        x, y, w, h = box
+        if images:
+            area_w = int(w * 0.62)
+            img_box = (x + area_w + int(w * 0.03), y, w - area_w - int(w * 0.03), h)
+        else:
+            area_w, img_box = w, None
+        key = str(spec.get("key") or bullets[0].get("text") or "").strip()
+        rest = bullets[1:]
+        key_h = int(h * 0.42)
+        accent = self._accent(0)
+        # 底色用主题调色板（深色模板/浅色模板都成立），强调色只出现在描边和色条上
+        rounded_box(slide, (x, y, area_w, key_h), fill=pal["card"],
+                    fill_alpha=pal["card_alpha"], line=accent, line_width_pt=2.0, radius=0.1)
+        rounded_box(slide, (x, y + int(key_h * 0.12), int(area_w * 0.012), int(key_h * 0.76)),
+                    fill=accent, line=None, radius=0.5)
+        pad = int(area_w * 0.05)
+        # 核心问题/结论要成为视觉锚点：比正文更大
+        key_size = max(self.body_size() * 1.4, self.csize("block_title"))
+        self._textbox(slide, (x + pad, y, area_w - 2 * pad, key_h),
+                      [Para(text=key, size=key_size, bold=True, color=pal["text"],
+                            font=self.tpl.cjk_font(), bullet="")], anchor="middle")
+        if rest:
+            self._bullets(slide, lay, (x, y + key_h + int(h * 0.07), area_w,
+                                       h - key_h - int(h * 0.07)), rest, base_size=self.body_size())
+        if img_box:
+            self._images_row(slide, images, img_box)
+        return True
+
+    def _slide_example(self, slide, lay, spec, index, total):
+        pal = self._palette(lay)
+        spec = {**spec, "title": spec.get("title") or "例题讲解"}
+        bx, by, bw, bh = self._header(slide, lay, spec, "科学解释")
+        steps = [s for s in spec.get("steps", []) if s.get("text")]
+        bullets = [b for b in spec.get("bullets", []) if b.get("text")]
+        accent = self.accents[0]
+
+        if bullets:
+            qh = int(bh * 0.3)
+            rounded_box(slide, (bx, by, bw, qh), fill=pal["card"], fill_alpha=pal["card_alpha"],
+                        line=pal["card_line"], radius=0.06)
+            pad = int(bw * 0.035)
+            self._textbox(slide, (bx + pad, by + int(qh * 0.12), bw - 2 * pad, int(qh * 0.76)),
+                          self._bullets_to_paras(bullets, self.csize("block_title"), self.tpl.cjk_font(),
+                                                 bullet_char=None), anchor="middle")
+            by += qh + int(self.H * 0.03)
+            bh -= qh + int(self.H * 0.03)
+
+        if steps:
+            self._numbered_steps(slide, lay, (bx, by, bw, bh), steps, accent)
+
+    def _slide_practice(self, slide, lay, spec, index, total):
+        pal = self._palette(lay)
+        spec = {**spec, "title": spec.get("title") or "随堂练习"}
+        bx, by, bw, bh = self._header(slide, lay, spec, "科学问答")
+        note = [b for b in spec.get("bullets", []) if b.get("text")]
+        if note:
+            self._textbox(slide, (bx, by, bw, int(self.H * 0.06)),
+                          self._bullets_to_paras(note, self.fz("subtitle"), self.tpl.cjk_font(),
+                                                 bullet_char=None, color=pal["muted"]))
+            by += int(self.H * 0.08)
+            bh -= int(self.H * 0.08)
+
+        questions = [q for q in spec.get("questions", []) if q.get("q") or q.get("options")]
+        if not questions:
+            return
+        inline = self.opts["answer_mode"] == "inline"
+        if self.opts["answer_mode"] == "end":
+            self._answer_pool.append({"title": spec.get("title") or "随堂练习", "questions": questions})
+
+        n = len(questions)
+        gap = int(self.H * 0.022)
+        each = max((bh - gap * (n - 1)) // n, int(self.H * 0.1))
+        for i, q in enumerate(questions):
+            y = by + i * (each + gap)
+            self._question_block(slide, lay, (bx, y, bw, each), i + 1, q, inline)
+
+    def _slide_summary(self, slide, lay, spec, index, total):
+        pal = self._palette(lay)
+        spec = {**spec, "title": spec.get("title") or "课堂小结"}
+        bx, by, bw, bh = self._header(slide, lay, spec, "知识回顾")
+        mm = spec.get("mindmap") or {}
+        branches = [b for b in mm.get("branches", []) if b.get("title") or b.get("items")]
+        if branches and (len(branches) > 1 or branches[0].get("title")):
+            self._mindmap(slide, lay, (bx, by, bw, bh), mm.get("center") or spec.get("title", ""), branches)
+            return
+        points = [p for p in spec.get("points", []) if p.get("text")]
+        if points:
+            self._bullets(slide, lay, (bx, by, bw, bh), points, base_size=self.body_size(),
+                          bullet_char="✓",
+                          bullet_color=self.accents[2 % len(self.accents)] if len(self.accents) > 2 else self.primary)
+
+    def _slide_homework(self, slide, lay, spec, index, total):
+        pal = self._palette(lay)
+        spec = {**spec, "title": spec.get("title") or "课后作业"}
+        bx, by, bw, bh = self._header(slide, lay, spec, "课后任务")
+        items = [it for it in spec.get("items", []) if it.get("text")]
+        note = spec.get("note", "")
+        if note:
+            bh -= int(self.H * 0.12)
+        if items:
+            self._bullets(slide, lay, (bx, by, bw, bh), items, base_size=self.body_size(),
+                          bullet_char="▸", bullet_color=self.primary)
+        if note:
+            ny = by + bh + int(self.H * 0.02)
+            rounded_box(slide, (bx, ny, bw, int(self.H * 0.1)), fill=pal["card"],
+                        fill_alpha=pal["card_alpha"], line=pal["card_line"], radius=0.08)
+            pad = int(bw * 0.03)
+            self._textbox(slide, (bx + pad, ny, bw - 2 * pad, int(self.H * 0.1)),
+                          [Para(text=note, size=self.csize("item"), color=pal["muted"],
+                                font=self.tpl.cjk_font(), bullet="")], anchor="middle")
+
+    def _slide_end(self, slide, lay, spec, index, total):
+        pal = self._palette(lay)
+        title = spec.get("title") or "谢谢观看"
+        prof_box = self.profile.end_title_box if self.profile else None
+        if prof_box:
+            self._textbox(slide, prof_box,
+                          [Para(text=title, size=self.fz("cover_title"), bold=True,
+                                color=pal["text"], font=self.tpl.heading_font(),
+                                align="center", bullet="")], anchor="middle")
+            sub0 = spec.get("subtitle", "")
+            if sub0:
+                self._textbox(slide, (int(self.W * 0.15), prof_box[1] + prof_box[3] + int(self.H * 0.05),
+                                      int(self.W * 0.7), int(self.H * 0.1)),
+                              [Para(text=sub0, size=self.fz("cover_sub"), color=pal["muted"],
+                                    font=self.tpl.cjk_font(), align="center", bullet="")])
+            return
+        ph = lay.find_title() if lay else None
+        # 结束页需要"居中大气"，如果模板的标题占位符在页面顶部，就自己画居中的
+        use_ph = False
+        if ph is not None and ph.height:
+            center_ratio = (ph.top + ph.height / 2.0) / float(self.H or 1)
+            use_ph = 0.28 <= center_ratio <= 0.78
+        if use_ph:
+            base = ph.font_size_pt or self.fz("cover_title")
+            self._fill_ph(slide, ph, [Para(text=title, size=max(base, self.fz("cover_title")),
+                                           bold=True,
+                                           font=ph.font_name or self.tpl.heading_font(),
+                                           bullet="")], anchor="middle")
+        else:
+            self._textbox(slide, (int(self.W * 0.1), int(self.H * 0.34), int(self.W * 0.8), int(self.H * 0.18)),
+                          [Para(text=title, size=self.fz("cover_title"),
+                                bold=True, color=pal["text"], font=self.tpl.heading_font(),
+                                align="center", bullet="")], anchor="middle")
+        sub = spec.get("subtitle", "")
+        if sub:
+            self._textbox(slide, (int(self.W * 0.15), int(self.H * 0.58), int(self.W * 0.7), int(self.H * 0.1)),
+                          [Para(text=sub, size=self.fz("cover_sub"), color=pal["muted"],
+                                font=self.tpl.cjk_font(), align="center", bullet="")])
+
+    def _render_answer_slides(self) -> int:
+        made = 0
+        for pool in self._answer_pool:
+            questions = [q for q in pool["questions"] if q.get("answer") or q.get("analysis")]
+            if not questions:
+                continue
+            slide, lay = self._new_slide({"type": "practice", "chrome": None})
+            pal = self._palette(lay)
+            bx, by, bw, bh = self._header(
+                slide, lay, {"title": f"{pool['title']} · 参考答案", "module": "科学问答"}, "科学问答")
+            n = len(questions)
+            gap = int(self.H * 0.02)
+            each = max((bh - gap * (n - 1)) // n, int(self.H * 0.1))
+            for i, q in enumerate(questions):
+                y = by + i * (each + gap)
+                paras: List[Para] = [Para(text=f"{i + 1}. 答案：{q.get('answer', '')}",
+                                          size=self.csize("caption") + 1, bold=True,
+                                          color=self.accents[2 % len(self.accents)],
+                                          font=self.tpl.cjk_font(), bullet="")]
+                if q.get("analysis"):
+                    paras.append(Para(text=f"解析：{q['analysis']}", size=self.csize("caption"),
+                                      color=pal["text"], font=self.tpl.cjk_font(), bullet="",
+                                      space_before=2))
+                self._textbox(slide, (bx, y, bw, each), paras)
+            self._prune_empty_placeholders(slide)
+            self.report.add("answers", pool["title"])
+            self._built_types.append("answers")
+            made += 1
+        return made
+
+    # ==================================================================
+    # 组合绘制
+    # ==================================================================
+    def _bullets_to_paras(self, bullets: Sequence[dict], base_size: float,
+                          font: Optional[str], *, bullet_char: Optional[str] = None,
+                          color: Optional[str] = None, bullet_color: Optional[str] = None
+                          ) -> List[Para]:
+        paras: List[Para] = []
+        for b in bullets:
+            level = int(b.get("level", 0) or 0)
+            size = base_size if level == 0 else max(base_size * (0.86 ** level), 9.0)
+            char = None if bullet_char is None else (
+                bullet_char if level == 0 else BULLETS[min(level, len(BULLETS) - 1)])
+            paras.append(Para(
+                text=b["text"], size=size, level=level, bullet=char,
+                color=color, font=font, indent_in=0.0 if level == 0 else 0.28 * level,
+                space_before=6 if level == 0 else 2,
+                space_after=0,
+            ))
+        return paras
+
+    def _bullets(self, slide, lay, box, bullets, *, base_size, color=None,
+                 bullet_char="●", bullet_color=None):
+        pal = self._palette(lay)
+        paras = self._bullets_to_paras(
+            bullets, base_size, self.body_font(),
+            bullet_char=bullet_char, color=color or pal["text"],
+            bullet_color=bullet_color or self.primary)
+        return self._textbox(slide, box, paras)
+
+    def _numbered_steps(self, slide, lay, box, steps, accent):
+        pal = self._palette(lay)
+        x, y, w, h = box
+        n = len(steps)
+        gap = int(h * 0.05 / max(n, 1)) if n > 1 else 0
+        each = (h - gap * (n - 1)) // max(n, 1)
+        badge = min(int(each * 0.62), int(w * 0.055))
+        for i, s in enumerate(steps):
+            sy = y + i * (each + gap)
+            rounded_box(slide, (x, sy, badge, badge), fill=accent, line=None, radius=0.5)
+            self._textbox(slide, (x, sy, badge, badge),
+                          [Para(text=str(i + 1), size=max(self.csize("item"), 10), bold=True,
+                                color=readable_on(accent), font=self.tpl.heading_font(),
+                                align="center", bullet="")], anchor="middle", fit=False)
+            self._textbox(slide, (x + badge + int(w * 0.02), sy, w - badge - int(w * 0.02), each),
+                          [Para(text=s["text"], size=self.fz("bullet0"), color=pal["text"],
+                                font=self.tpl.cjk_font(), bullet="")], anchor="middle")
+
+    def _question_block(self, slide, lay, box, number, q, inline):
+        pal = self._palette(lay)
+        x, y, w, h = box
+        accent = self.accents[(number - 1) % len(self.accents)]
+        head_h = 0
+        paras: List[Para] = []
+        if q.get("q"):
+            paras.append(Para(text=f"{number}. {q['q']}", size=self.csize("block_title"), bold=True,
+                              color=pal["text"], font=self.tpl.cjk_font(), bullet=""))
+            from .shapes import measure_block
+
+            need_pt = measure_block(paras, pt_from_emu(w))
+            head_h = min(int(emu_from_inch(need_pt / 72.0)) + emu_from_inch(0.06), int(h * 0.6))
+            self._textbox(slide, (x, y, w, head_h), paras)
+        opts = q.get("options") or []
+        opt_y = y + head_h
+        opt_h = h - head_h
+        if inline and (q.get("answer") or q.get("analysis")):
+            ans_h = int(h * 0.3)
+            opt_h = max(h - head_h - ans_h, int(h * 0.3))
+            ans_paras = [Para(text=f"答案：{q.get('answer', '')}", size=self.csize("caption"), bold=True,
+                              color=accent, font=self.tpl.cjk_font(), bullet="")]
+            if q.get("analysis"):
+                ans_paras.append(Para(text=f"解析：{q['analysis']}", size=self.csize("caption"),
+                                      color=pal["muted"], font=self.tpl.cjk_font(), bullet="",
+                                      space_before=2))
+            self._textbox(slide, (x + int(w * 0.03), y + head_h + opt_h, w - int(w * 0.03), ans_h), ans_paras)
+        if not opts:
+            return
+        horizontal = self._options_fit_row(opts, w, self.csize("item"))
+        if horizontal:
+            n = len(opts)
+            gap = int(w * 0.02)
+            cw = (w - gap * (n - 1)) // n
+            # 横排时给选项一个紧凑的行高，并在这片区域里垂直居中
+            row_h = min(opt_h, max(int(self.H * 0.055), int(self.csize("item") * 2.2)))
+            cy = opt_y + (opt_h - row_h) // 2
+            for i, o in enumerate(opts):
+                self._option_chip(slide, lay, (x + i * (cw + gap), cy, cw, row_h), o, accent)
+        else:
+            gap = int(opt_h * 0.06)
+            each = (opt_h - gap * (len(opts) - 1)) // len(opts)
+            for i, o in enumerate(opts):
+                self._option_chip(slide, lay, (x + int(w * 0.03), opt_y + i * (each + gap),
+                                               w - int(w * 0.03), each), o, accent)
+
+    def _option_chip(self, slide, lay, box, text, accent):
+        pal = self._palette(lay)
+        label = text
+        is_answer = False
+        if text and text[0] in "ABCDEFGH" and len(text) > 1 and text[1] in ".、．)）:":
+            label = text[2:].strip()
+            is_answer = True
+        x, y, w, h = box
+        if is_answer:
+            dot = max(min(int(h * 0.7), int(w * 0.12)), int(self.csize("item") * 1.5))
+            # 徽标与文字在同一行上垂直居中对齐
+            dy = y + max((h - dot) // 2, 0)
+            rounded_box(slide, (x, dy, dot, dot), fill=pal["card"], fill_alpha=pal["card_alpha"],
+                        line=accent, line_width_pt=1.0, radius=0.5)
+            self._textbox(slide, (x, dy, dot, dot),
+                          [Para(text=text[0], size=self.csize("item") - 1, bold=True, color=accent,
+                                font=self.tpl.heading_font(), align="center", bullet="")],
+                          anchor="middle", fit=False)
+            tx = x + dot + int(w * 0.03)
+            tw = max(w - dot - int(w * 0.03), int(w * 0.2))
+        else:
+            tx, tw = x, w
+        self._textbox(slide, (tx, y, tw, h),
+                      [Para(text=label, size=self.csize("item"), color=pal["text"],
+                            font=self.tpl.cjk_font(), bullet="")], anchor="middle")
+
+    def _options_fit_row(self, opts, width, size) -> bool:
+        from .util import text_width_pt
+
+        total = sum(text_width_pt(o, size) for o in opts)
+        total += 20 * len(opts)
+        return total <= pt_from_emu(width) * 0.98
+
+    def _images_row(self, slide, images, box):
+        x, y, w, h = box
+        n = len(images)
+        if n == 0:
+            return
+        gap = int(w * 0.03) if n > 1 else 0
+        cw = (w - gap * (n - 1)) // n
+        for i, img in enumerate(images):
+            add_picture_fit(slide, img, (x + i * (cw + gap), y, cw, h), mode="contain")
+
+    def _mindmap(self, slide, lay, box, center, branches):
+        pal = self._palette(lay)
+        x, y, w, h = box
+        root_w = int(w * 0.26)
+        gap = int(w * 0.06)
+        br_x = x + root_w + gap
+        br_w = w - root_w - gap
+        n = len(branches)
+        row_gap = int(h * 0.04)
+        each = (h - row_gap * (n - 1)) // max(n, 1)
+
+        root_h = min(int(h * 0.36), max(int(self.H * 0.16), int(each * 1.2)))
+        root_y = y + (h - root_h) // 2
+        rounded_box(slide, (x, root_y, root_w, root_h), fill=self.primary, line=None, radius=0.1)
+        self._textbox(slide, (x + int(root_w * 0.07), root_y, int(root_w * 0.86), root_h),
+                      [Para(text=center, size=self.fz("mind_center"), bold=True,
+                            color=readable_on(self.primary), font=self.tpl.heading_font(),
+                            align="center", bullet="")], anchor="middle")
+
+        for i, br in enumerate(branches):
+            by = y + i * (each + row_gap)
+            accent = self.accents[i % len(self.accents)]
+            items = [it for it in br.get("items", []) if str(it).strip()]
+            head_h = min(int(each * (0.5 if items else 1.0)), int(each * 0.55)) if items else each
+            rounded_box(slide, (br_x, by, br_w, each), fill=pal["card"],
+                        fill_alpha=pal["card_alpha"], line=pal["card_line"], radius=0.08)
+            # 左侧色条
+            rounded_box(slide, (br_x, by, int(br_w * 0.012), each),
+                        fill=accent, line=None, radius=0.5)
+            pad = int(br_w * 0.035)
+            self._textbox(slide, (br_x + pad + int(br_w * 0.012), by, br_w - 2 * pad, head_h),
+                          [Para(text=br.get("title", ""), size=self.fz("mind_branch"), bold=True,
+                                color=accent, font=self.tpl.cjk_font(), bullet="")], anchor="middle")
+            if items:
+                self._textbox(slide, (br_x + pad + int(br_w * 0.012), by + head_h,
+                                      br_w - 2 * pad, each - head_h),
+                              [Para(text="　".join(str(t) for t in items),
+                                    size=self.fz("mind_item"), color=pal["text"],
+                                    font=self.tpl.cjk_font(), bullet="")], anchor="middle")
+            add_line(slide, x + root_w, root_y + root_h // 2,
+                     br_x, by + each // 2, color=pal["card_line"], width_pt=1.0)
+
+    # ==================================================================
+    # 图片 / 页码 / 杂项
+    # ==================================================================
+    def _resolve_images(self, spec: dict) -> List[str]:
+        paths = []
+        raw = []
+        if spec.get("images"):
+            raw = list(spec["images"]) if isinstance(spec["images"], (list, tuple)) else [spec["images"]]
+        elif spec.get("image"):
+            raw = [spec["image"]]
+        elif spec.get("image_prompt") and self.image_manifest:
+            hit = self.image_manifest.get(spec["image_prompt"].strip())
+            if hit:
+                raw = [hit]
+            else:
+                self.warn(f"配图还没生成（P 的 image_prompt 未命中缓存）：{spec['image_prompt'][:24]}…")
+        for p in raw:
+            if not p:
+                continue
+            cand = p if os.path.isabs(str(p)) else os.path.join(self.base_dir, str(p))
+            if not os.path.exists(cand) and self.tpl.path:
+                alt = os.path.join(os.path.dirname(self.tpl.path), str(p))
+                if os.path.exists(alt):
+                    cand = alt
+            if os.path.exists(cand):
+                paths.append(cand)
+            else:
+                self.warn(f"找不到图片：{p}")
+        return paths
+
+    def _add_page_numbers(self) -> None:
+        if not self.opts.get("page_numbers", True):
+            return
+        start = int(self.opts.get("page_number_start", 1) or 1)
+        for i, slide in enumerate(self.prs.slides):
+            num = i + start
+            if i == 0 and self.opts.get("skip_number_on_cover", True):
+                continue
+            pal = {"text": self.tpl.muted_color()}
+            box = (int(self.W * 0.86), int(self.H * 0.925), int(self.W * 0.09), int(self.H * 0.05))
+            try:
+                self._textbox(slide, box,
+                              [Para(text=str(num), size=self.csize("caption"), color=pal["text"],
+                                    font=self.tpl.cjk_font(), align="right", bullet="")],
+                              anchor="middle", fit=False)
+            except Exception:
+                pass
+
+    def warn(self, msg: str) -> None:
+        if msg not in self.report.warnings:
+            self.report.warnings.append(msg)
+
+
+EMU_PT = 12700