@huicai/cli 2026.804.0 → 2026.1019.0

package/skills/pptx-author/scripts/pptx_deck.py

@@ -1,193 +1,784 @@
-# PPT 构建器（经 run_python 执行）。16:9 空白版式全手绘（不依赖模板文件），四套主题配色，
-# 八种版式：cover / agenda / section / bullets / kpi / image / table / end；notes 进演讲备注。
-# 直接执行本文件 = 自测：产出 pptx_deck_check.pptx 并重读校验。
-import base64
-
-from pptx import Presentation
-from pptx.dml.color import RGBColor
-from pptx.enum.text import PP_ALIGN
-from pptx.oxml.ns import qn
-from pptx.util import Emu, Inches, Pt
-
-THEMES = {
-    'navy': dict(primary='1F4E79', accent='2E75B6', light='DEEBF7', text='333333'),  # 深蓝商务（默认）
-    'tech': dict(primary='5B2D90', accent='9A66CC', light='EDE4F7', text='333333'),  # 科技紫
-    'mono': dict(primary='404040', accent='7F7F7F', light='F2F2F2', text='333333'),  # 极简灰
-    'warm': dict(primary='C55A11', accent='ED7D31', light='FBE5D6', text='3B3B3B'),  # 活力橙
-}
-FONT = '微软雅黑'  # 播放端渲染（mac 自动回退苹方），不嵌字体
-
-
-def _style(run, size=18, bold=False, color='333333', font=FONT):
-    f = run.font
-    f.name = font
-    f.size = Pt(size)
-    f.bold = bold
-    f.color.rgb = RGBColor.from_string(color)
-    # 中文字体需另设 <a:ea>（run.font.name 只设拉丁 <a:latin>）；用 lxml 直建，兼容各版本 python-pptx
-    from lxml import etree
-    rPr = run._r.get_or_add_rPr()
-    ea = rPr.find(qn('a:ea'))
-    if ea is None:
-        ea = etree.SubElement(rPr, qn('a:ea'))
-    ea.set('typeface', font)
+# PPT 建版器：**先量后画**的 16:9 演示文稿构建器（经 run_python 执行）。
+#
+# 与"直接调 python-pptx"的根本差别：那样是盲写——把文字塞进一个拍脑袋定的框，
+# 装不装得下没人知道，保存那一刻也不报错。本模块每放一段文字前先用 pptx_layout
+# 量一遍：量不下就先降字号（在下限内），还不下就自动拆页，绝不硬塞、绝不出框。
+# 图片一律等比 contain 进内容区（只给宽或只给高的写法根本不存在于这里，
+# 所以不可能被拉成长脸）。所有元素落在同一套栅格上，位置由栅格算，不手填坐标，
+# 因此天然不重叠——`save()` 之后还会自动跑一遍 pptx_check 体检兜底。
+#
+# 版式：cover/agenda/section/bullets/two_col/kpi/image/image_text/table/quote/
+#       compare/timeline/end，全部 16:9，六套主题配色。
+#
+# 直接执行 = 自测：产出 pptx_deck_check.pptx 并体检。
+
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+from pptx import Presentation                                    # noqa: E402
+from pptx.dml.color import RGBColor                              # noqa: E402
+from pptx.enum.shapes import MSO_SHAPE                           # noqa: E402
+from pptx.enum.text import MSO_ANCHOR, MSO_AUTO_SIZE, PP_ALIGN   # noqa: E402
+from pptx.oxml.ns import qn                                      # noqa: E402
+from pptx.util import Emu, Pt                                    # noqa: E402
+
+import pptx_layout as L                                          # noqa: E402
+from pptx_layout import Rect, THEMES                             # noqa: E402
+
+FONT = '微软雅黑'          # 播放端渲染（mac 自动回退苹方），不嵌字体
+FONT_NUM = 'Arial'         # 大数字用西文字体，字形更挺
+
+# 字号阶梯（磅）：标题/正文/小字。正文给区间，装不下就在区间内降，降到底才拆页。
+SZ_TITLE = 28
+SZ_BODY_MAX = 22
+SZ_BODY_MIN = 16
+SZ_CAPTION = 12
+SZ_FOOTER = 10
+SZ_MIN = 10        # 字号地板：再挤也不许低于它（投影上 10pt 以下等于没写），撞地板就改截断
+
+
+class Grid:
+    """页面栅格：所有版式都从这里取坐标，不手填数字——同源才谈得上对齐。"""
+
+    def __init__(self, w, h):
+        self.W, self.H = w, h
+        self.m = round(w * 0.056, 3)               # 左右外边距
+        self.title_y = round(h * 0.056, 3)
+        self.title_h = round(h * 0.104, 3)
+        self.rule_y = round(self.title_y + self.title_h + 0.04, 3)
+        self.top = round(self.rule_y + 0.16, 3)    # 内容区顶
+        self.footer_y = round(h - 0.52, 3)
+        self.bottom = round(h - 0.72, 3)           # 内容区底（给页脚留出）
+        self.gut = 0.34                            # 栏间距
+
+    @property
+    def content(self):
+        return Rect(self.m, self.top, self.W - 2 * self.m, self.bottom - self.top)
+
+    def cols(self, n, box=None):
+        """把一块区域等分成 n 栏（含栏间距）。"""
+        b = box or self.content
+        w = (b.w - self.gut * (n - 1)) / n
+        return [Rect(b.x + (w + self.gut) * i, b.y, w, b.h) for i in range(n)]
+
+    def rows(self, n, box=None, gap=0.24):
+        b = box or self.content
+        h = (b.h - gap * (n - 1)) / n
+        return [Rect(b.x, b.y + (h + gap) * i, b.w, h) for i in range(n)]
 
 
 class Deck:
-    def __init__(self, theme='navy'):
-        self.t = THEMES.get(theme, THEMES['navy'])
+    def __init__(self, theme='navy', size='16:9', footer='', page_numbers=True, font=FONT):
+        self.t = dict(THEMES.get(theme, THEMES['navy']))
+        self.theme_name = theme if theme in THEMES else 'navy'
+        self.font = font
         self.prs = Presentation()
-        self.prs.slide_width = Inches(13.333)
-        self.prs.slide_height = Inches(7.5)
+        w, h = (13.333, 7.5) if size != '4:3' else (10.0, 7.5)
+        self.prs.slide_width = Emu(int(w * L.EMU_IN))
+        self.prs.slide_height = Emu(int(h * L.EMU_IN))
+        self.g = Grid(w, h)
+        self.footer = footer or ''
+        self.page_numbers = page_numbers
+        self.warnings = []           # 建版过程中的降级记录（降字号/拆页），如实回报
+        self._occupied = []          # 当前页已占区域（防重叠自检）
+        self._outline = []           # [(页号, 版式, 标题)]
 
-    # ── 内部小件 ──────────────────────────────────────────────
-    def _slide(self, notes=None):
-        s = self.prs.slides.add_slide(self.prs.slide_layouts[6])  # 空白版式
+    # ── 底层小件 ────────────────────────────────────────────────────────────
+    def _slide(self, notes=None, chrome=True, kind='', title=''):
+        s = self.prs.slides.add_slide(self.prs.slide_layouts[6])   # 空白版式
+        if self.t['bg'].upper() != 'FFFFFF':                       # 深色主题：先铺满页底
+            self._rect_shape(s, Rect(0, 0, self.g.W, self.g.H), self.t['bg'])
         if notes:
-            s.notes_slide.notes_text_frame.text = notes
+            s.notes_slide.notes_text_frame.text = str(notes)
+        self._occupied = []
+        self._outline.append((len(self.prs.slides), kind, title))
+        s._wt_chrome = chrome
         return s
 
-    def _rect(self, s, x, y, w, h, color):
-        from pptx.enum.shapes import MSO_SHAPE
-        r = s.shapes.add_shape(MSO_SHAPE.RECTANGLE, x, y, w, h)
-        r.fill.solid()
-        r.fill.fore_color.rgb = RGBColor.from_string(color)
-        r.line.fill.background()
-        return r
+    def _claim(self, rect, what):
+        """占位登记 + 重叠自检（引擎自己算错也当场发现，而不是等用户打开 PPT）。"""
+        for r, w in self._occupied:
+            if r.contains(rect, 0.01) or rect.contains(r, 0.01):
+                continue                       # 卡片底 ⊃ 卡片内文字：套着是版式，不是撞车
+            if r.overlap_ratio(rect) > 0.02:
+                self.warnings.append(f'内部版式冲突：{what} 与 {w} 重叠（引擎缺陷，请报告）')
+                break
+        self._occupied.append((rect, what))
 
-    def _text(self, s, x, y, w, h, text, size=18, bold=False, color=None, align=PP_ALIGN.LEFT):
-        tb = s.shapes.add_textbox(x, y, w, h)
+    def _rect_shape(self, s, rect, color, line=None, radius=None):
+        shp = s.shapes.add_shape(
+            MSO_SHAPE.ROUNDED_RECTANGLE if radius else MSO_SHAPE.RECTANGLE,
+            Emu(int(rect.x * L.EMU_IN)), Emu(int(rect.y * L.EMU_IN)),
+            Emu(int(rect.w * L.EMU_IN)), Emu(int(rect.h * L.EMU_IN)))
+        if radius:
+            try:
+                shp.adjustments[0] = radius
+            except Exception:
+                pass
+        if color:
+            shp.fill.solid()
+            shp.fill.fore_color.rgb = RGBColor.from_string(color)
+        else:
+            shp.fill.background()
+        if line:
+            shp.line.color.rgb = RGBColor.from_string(line)
+            shp.line.width = Pt(1)
+        else:
+            shp.line.fill.background()
+        shp.shadow.inherit = False
+        return shp
+
+    def _textbox(self, s, rect):
+        """受控文本框：零内边距、开自动换行、关自动改尺寸。
+
+        这三项是 python-pptx 的默认坑：add_textbox 默认 wrap="none" + spAutoFit，
+        长文字会拉成一整行冲出版心，而框还会自己长高把下面的东西顶掉。
+        """
+        tb = s.shapes.add_textbox(Emu(int(rect.x * L.EMU_IN)), Emu(int(rect.y * L.EMU_IN)),
+                                  Emu(int(rect.w * L.EMU_IN)), Emu(int(rect.h * L.EMU_IN)))
         tf = tb.text_frame
         tf.word_wrap = True
-        p = tf.paragraphs[0]
-        p.alignment = align
-        _style(p.add_run(), size, bold, color or self.t['text'])
-        p.runs[0].text = text
-        return tf
-
-    def _title(self, s, text):
-        self._rect(s, 0, 0, self.prs.slide_width, Inches(0.12), self.t['accent'])
-        self._text(s, Inches(0.6), Inches(0.35), Inches(12), Inches(0.9), text, size=28, bold=True, color=self.t['primary'])
-
-    # ── 八种版式 ──────────────────────────────────────────────
-    def add_cover(self, title, subtitle='', notes=None):
-        s = self._slide(notes)
-        self._rect(s, 0, 0, self.prs.slide_width, self.prs.slide_height, self.t['primary'])
-        self._text(s, Inches(1), Inches(2.6), Inches(11.3), Inches(1.4), title, size=44, bold=True, color='FFFFFF', align=PP_ALIGN.CENTER)
+        tf.auto_size = MSO_AUTO_SIZE.NONE
+        tf.margin_left = tf.margin_right = tf.margin_top = tf.margin_bottom = Pt(0)
+        return tb, tf
+
+    def _fg(self, bg, prefer=(), min_ratio=4.5):
+        """在 bg 底色上挑一个对比度达标的前景色（配色可以随便改，可读性不由人肉保证）。"""
+        return L.pick_fg(bg, list(prefer) + [self.t['text'], self.t['on_primary']], min_ratio)
+
+    def _style(self, run, size, bold=False, color=None, font=None):
+        f = run.font
+        fam = font or self.font
+        f.name = fam
+        f.size = Pt(size)
+        f.bold = bold
+        f.color.rgb = RGBColor.from_string(color or self.t['text'])
+        # 中文必须另设 <a:ea>：run.font.name 只写 <a:latin>，不设 ea 的话中文会回退到
+        # 别的字体，实际行宽与我们量出来的对不上——溢出就是这么来的
+        rPr = run._r.get_or_add_rPr()
+        for tag in ('a:ea', 'a:cs'):
+            el = rPr.find(qn(tag))
+            if el is None:
+                from lxml import etree
+                el = etree.SubElement(rPr, qn(tag))
+            el.set('typeface', fam)
+
+    def _para(self, tf, first, text, size, bold=False, color=None, align=None,
+              space_after=0, indent=0.0, hang=0.0, font=None):
+        p = tf.paragraphs[0] if first else tf.add_paragraph()
+        if align is not None:
+            p.alignment = align
+        if space_after:
+            p.space_after = Pt(space_after)
+        if indent or hang:
+            pPr = p._p.get_or_add_pPr()
+            pPr.set('marL', str(int(indent * L.EMU_IN)))
+            if hang:
+                pPr.set('indent', str(int(-hang * L.EMU_IN)))
+            from lxml import etree
+            if pPr.find(qn('a:buNone')) is None:
+                etree.SubElement(pPr, qn('a:buNone'))
+        r = p.add_run()
+        r.text = str(text)
+        self._style(r, size, bold, color, font)
+        return p
+
+    def _fit_line(self, s, rect, text, size, color=None, align=None, bold=False,
+                  lo=None, font=None, anchor=None, what='标签'):
+        """把一段**标签文字**放进固定高度的框：先降字号，仍不够就按行数裁断加省略号。
+
+        固定高度 + 固定字号 = 盲写。标题、页脚、图注、时间轴的时间点这些看着"就一行"的地方，
+        换个稍长的文案就会溢出——压力测试里 51 条事故全出在这类框上。
+        """
+        raw = str(text if text is not None else '')
+        w = max(20.0, rect.w * L.PT_IN)
+        floor = max(SZ_MIN, lo or round(size * 0.6))
+        sz = L.fit_size(raw, w, rect.h * L.PT_IN, hi=max(size, floor), lo=floor, bold=bold)
+        maxn = max(1, int(rect.h * L.PT_IN / (sz * L.LINE_H)))
+        txt = L.clip(raw, sz, w, maxn, bold)
+        if txt != raw:
+            # 撞地板了：宁可截断也不把字缩到看不清。截断是可见的降级，必须如实报出来。
+            self.warnings.append(f'{what}「{raw[:18]}…」放不进 {rect.w:.1f}"×{rect.h:.1f}" 的位置，'
+                                 f'已按 {sz:.0f}pt 截断显示——请把这句话压短')
+        tb, tf = self._textbox(s, rect)
+        if anchor is not None:
+            tf.vertical_anchor = anchor
+        self._para(tf, True, txt, sz, bold, color, align, font=font)
+        self._claim(rect, what)
+        return tb, tf
+
+    def _fit_text(self, s, rect, items, hi=SZ_BODY_MAX, lo=SZ_BODY_MIN, gap=0.55,
+                  color=None, bold=False, align=None, bullet='•  ', indent=0.0):
+        """把 items 放进 rect：在 [lo,hi] 内选能装下的最大字号；装不下返回 None（调用方拆页）。
+
+        items: [str] 或 [(text, level)]。gap = 段间距占字号的比例。
+        """
+        norm = [(t, 0) if isinstance(t, str) else (str(t[0]), int(t[1])) for t in items]
+        got = self._best_size(rect, norm, hi, lo, gap, bullet, indent, bold)
+        if got is None:
+            return None
+        size, plan = got
+        self._emit(s, rect, plan, size, gap, color, bold, align, bullet, indent)
+        return size
+
+    def _best_size(self, rect, norm, hi=SZ_BODY_MAX, lo=SZ_BODY_MIN, gap=0.55,
+                   bullet='•  ', indent=0.0, bold=False):
+        """只量不画：能装下就回 (字号, 排版方案)，装不下回 None。"""
+        size = hi
+        while size >= lo:
+            total, plan = self._measure(norm, rect, size, gap, bullet, indent, bold)
+            if total <= rect.h:
+                return size, plan
+            size -= 1
+        return None
+
+    def _measure(self, norm, rect, size, gap, bullet, indent, bold):
+        total, plan = 0.0, []
+        for i, (text, lvl) in enumerate(norm):
+            sz = size if lvl == 0 else max(SZ_BODY_MIN - 2, size - 3)
+            pad = indent + lvl * 0.34
+            mark = (bullet if lvl == 0 else '–  ') if bullet else ''
+            bw = L.measure(mark, sz, False) / L.PT_IN
+            # 连项目符号一起量、压在 marL 之后的净宽里——体检侧就是这么读的（见
+            # pptx_check._para_indent）。两边差一个符号宽，就会出现"建版说装得下、
+            # 体检说溢出 2%"这种自相矛盾。宁可保守一格，也不要两套尺。
+            avail = (rect.w - pad - bw) * L.PT_IN * L.WRAP_SAFETY
+            lines = L.wrap_segments([(mark + text, sz, bold)], max(20.0, avail))
+            h = L.text_height(lines) / L.PT_IN
+            total += h + (gap * sz / L.PT_IN if i < len(norm) - 1 else 0)
+            plan.append((text, lvl, sz, pad, bw, h))
+        return total, plan
+
+    def _emit(self, s, rect, plan, size, gap, color, bold, align, bullet, indent):
+        tb, tf = self._textbox(s, rect)
+        tf.vertical_anchor = MSO_ANCHOR.TOP
+        for i, (text, lvl, sz, pad, bw, h) in enumerate(plan):
+            mark = (bullet if lvl == 0 else '–  ') if bullet else ''
+            self._para(tf, i == 0, mark + text, sz, bold,
+                       color or (self.t['text'] if lvl == 0 else self.t['muted']),
+                       align, space_after=(gap * sz if i < len(plan) - 1 else 0),
+                       indent=pad + bw, hang=bw)
+        self._claim(rect, '正文')
+        return tb
+
+    def _title(self, s, text, sub=''):
+        g = self.g
+        r = Rect(g.m, g.title_y, g.W - 2 * g.m, g.title_h)
+        sub_h = (SZ_CAPTION * L.LINE_H) / L.PT_IN if sub else 0     # 副标题也占高，不能只按主标题量
+        main = Rect(r.x, r.y, r.w, r.h - sub_h)
+        size = L.fit_size(text, main.w * L.PT_IN, main.h * L.PT_IN, hi=SZ_TITLE, lo=18, bold=True)
+        maxn = max(1, int(main.h * L.PT_IN / (size * L.LINE_H)))
+        tb, tf = self._textbox(s, r)
+        tf.vertical_anchor = MSO_ANCHOR.BOTTOM
+        self._para(tf, True, L.clip(text, size, main.w * L.PT_IN, maxn, True), size, True, self.t['head'])
+        if sub:
+            self._para(tf, False, L.clip(sub, SZ_CAPTION, r.w * L.PT_IN, 1), SZ_CAPTION, False, self.t['muted'])
+        self._claim(r, '标题')
+        self._rect_shape(s, Rect(g.m, g.rule_y, 0.9, 0.045), self.t['accent'])
+        self._rect_shape(s, Rect(g.m + 0.9, g.rule_y + 0.017, g.W - 2 * g.m - 0.9, 0.011), self.t['light'])
+        return r
+
+    def _chrome(self):
+        """页脚与页码（最后统一刷，页码才知道总页数）。"""
+        g = self.g
+        n = len(self.prs.slides)
+        for i, s in enumerate(self.prs.slides, 1):
+            if not getattr(s, '_wt_chrome', True):
+                continue
+            if self.footer:
+                self._fit_line(s, Rect(g.m, g.footer_y, g.W * 0.6, 0.28), self.footer,
+                               SZ_FOOTER, self.t['muted'], what='页脚')
+            if self.page_numbers:
+                self._fit_line(s, Rect(g.W - g.m - 1.2, g.footer_y, 1.2, 0.28), f'{i} / {n}',
+                               SZ_FOOTER, self.t['muted'], PP_ALIGN.RIGHT, what='页码')
+
+    # ── 版式 ────────────────────────────────────────────────────────────────
+    def add_cover(self, title, subtitle='', meta='', notes=None):
+        g = self.g
+        s = self._slide(notes, chrome=False, kind='封面', title=title)
+        self._rect_shape(s, Rect(0, 0, g.W, g.H), self.t['primary'])
+        self._rect_shape(s, Rect(0, g.H * 0.62, g.W, 0.06), self.t['accent'])
+        box = Rect(g.m + 0.4, g.H * 0.30, g.W - 2 * g.m - 0.8, g.H * 0.26)
+        self._fit_line(s, box, title, 44, self.t['on_primary'], bold=True, lo=26,
+                       anchor=MSO_ANCHOR.BOTTOM, what='封面标题')
+        dim = self._fg(self.t['primary'], [self.t['light'], self.t['on_primary']])
+        y = g.H * 0.66
         if subtitle:
-            self._text(s, Inches(1), Inches(4.2), Inches(11.3), Inches(0.8), subtitle, size=18, color='DDE7F3', align=PP_ALIGN.CENTER)
+            self._fit_line(s, Rect(box.x, y, box.w, 0.5), subtitle, 20, dim, what='封面副标题')
+            y += 0.56
+        if meta:
+            self._fit_line(s, Rect(box.x, y, box.w, 0.4), meta, 14, dim, what='封面署名')
         return s
 
     def add_agenda(self, items, title='目录', notes=None):
-        s = self._slide(notes)
+        s = self._slide(notes, kind='目录', title=title)
         self._title(s, title)
-        tb = s.shapes.add_textbox(Inches(1.2), Inches(1.7), Inches(10.5), Inches(5))
-        tf = tb.text_frame
-        tf.word_wrap = True
-        for i, it in enumerate(items):
-            p = tf.paragraphs[0] if i == 0 else tf.add_paragraph()
-            p.space_after = Pt(14)
-            _style(p.add_run(), 22, False, self.t['text'])
-            p.runs[0].text = f'{i + 1}　{it}'
+        g = self.g
+        n = len(items)
+        cols = 2 if n > 5 else 1
+        boxes = g.cols(cols)
+        per = (n + cols - 1) // cols
+        for ci in range(cols):
+            chunk = items[ci * per:(ci + 1) * per]
+            if not chunk:
+                continue
+            b = boxes[ci]
+            rows = g.rows(per, b, gap=0.12)
+            for i, it in enumerate(chunk):
+                idx = ci * per + i + 1
+                r = rows[i]
+                num_w = 0.62
+                self._rect_shape(s, Rect(r.x, r.y + (r.h - 0.42) / 2, 0.46, 0.42), self.t['light'])
+                tb, tf = self._textbox(s, Rect(r.x, r.y + (r.h - 0.42) / 2 + 0.06, 0.46, 0.32))
+                self._para(tf, True, f'{idx:02d}', 14, True, self.t['on_light'], PP_ALIGN.CENTER)
+                box = Rect(r.x + num_w, r.y, r.w - num_w, r.h)
+                self._fit_line(s, box, str(it), 20, self.t['text'], lo=14,
+                               anchor=MSO_ANCHOR.MIDDLE, what=f'目录项{idx}')
         return s
 
-    def add_section(self, title, notes=None):
-        s = self._slide(notes)
-        self._rect(s, 0, Inches(3.2), self.prs.slide_width, Inches(1.2), self.t['light'])
-        self._text(s, Inches(1), Inches(3.35), Inches(11.3), Inches(0.9), title, size=32, bold=True, color=self.t['primary'], align=PP_ALIGN.CENTER)
+    def add_section(self, title, no=None, subtitle='', notes=None):
+        g = self.g
+        s = self._slide(notes, chrome=False, kind='章节', title=title)
+        self._rect_shape(s, Rect(0, 0, g.W, g.H), self.t['light'])
+        self._rect_shape(s, Rect(0, g.H * 0.36, g.W, g.H * 0.28), self.t['primary'])
+        band = Rect(g.m, g.H * 0.36, g.W - 2 * g.m, g.H * 0.28)
+        if no is not None:
+            self._fit_line(s, Rect(band.x, band.y + 0.20, 2.4, 0.40), str(no), 16,
+                           self._fg(self.t['primary'], [self.t['accent'], self.t['on_primary']]),
+                           bold=True, what='章节编号')
+            box = Rect(band.x, band.y + 0.70, band.w, band.h - 0.92)
+        else:
+            box = Rect(band.x, band.y + 0.35, band.w, band.h - 0.70)
+        self._fit_line(s, box, title, 34, self.t['on_primary'], bold=True, lo=22, what='章节标题')
+        if subtitle:
+            self._fit_line(s, Rect(band.x, band.bottom + 0.3, band.w, 0.5), subtitle, 14,
+                           self._fg(self.t['light'], [self.t['muted'], self.t['on_light']]), what='章节副标题')
         return s
 
-    def add_bullets(self, title, bullets, notes=None):
-        s = self._slide(notes)
+    def add_bullets(self, title, bullets, notes=None, lead='', cont_mark='（续）'):
+        """要点页。装不下先降字号，降到下限仍不下则**自动拆页**（标题加「（续）」）。"""
+        items = _flat(bullets)
+        full = self.g.content
+        first_box = Rect(full.x, full.y + 0.74, full.w, full.h - 0.74) if lead else full
+        chunks = self._plan_pages(items, first_box, full)
+        if len(chunks) > 1:
+            self.warnings.append(
+                f'「{title}」{len(items)} 条要点一页放不下，已自动拆为 {len(chunks)} 页'
+                f'（每页 {"/".join(str(len(c)) for c in chunks)} 条）；'
+                '更好的做法是按论点重新归并，而不是按条数切')
+        made = []
+        for i, chunk in enumerate(chunks):
+            t = title if i == 0 else f'{title}{cont_mark}'
+            s = self._slide(notes if i == 0 else None, kind='要点', title=t)
+            self._title(s, t)
+            box = full
+            if lead and i == 0:
+                lb = Rect(box.x, box.y, box.w, 0.62)
+                self._rect_shape(s, Rect(box.x, box.y, 0.05, 0.5), self.t['accent'])
+                self._fit_line(s, Rect(lb.x + 0.18, lb.y, lb.w - 0.18, 0.5), lead, 16,
+                               self.t['head'], bold=True, what='导语')
+                box = first_box
+            if self._fit_text(s, box, chunk) is None:      # 单条都超高：放下并交给体检报出来
+                self._fit_text(s, box, chunk, lo=SZ_BODY_MIN - 4)
+            made.append(s)
+        return made[0] if len(made) == 1 else made
+
+    def _plan_pages(self, items, first_box, rest_box):
+        """拆页规划：先看几页装得下，再**等分**——不是把前面塞满、剩一条孤零零占一页。"""
+        norm = [(t, 0) if isinstance(t, str) else (str(t[0]), int(t[1])) for t in items]
+        if not norm:
+            return [[]]
+        if self._best_size(first_box, norm) is not None:
+            return [norm]
+        for pages in range(2, len(norm) + 1):
+            per = -(-len(norm) // pages)                   # 上取整，均分
+            chunks = [norm[i:i + per] for i in range(0, len(norm), per)]
+            boxes = [first_box] + [rest_box] * (len(chunks) - 1)
+            if all(self._best_size(b, c) is not None for b, c in zip(boxes, chunks)):
+                return chunks
+        return [[x] for x in norm]
+
+    def add_two_col(self, title, left, right, left_title='', right_title='', notes=None):
+        s = self._slide(notes, kind='两栏', title=title)
         self._title(s, title)
-        tb = s.shapes.add_textbox(Inches(0.9), Inches(1.6), Inches(11.5), Inches(5.3))
-        tf = tb.text_frame
-        tf.word_wrap = True
-        for i, b in enumerate(bullets):
-            p = tf.paragraphs[0] if i == 0 else tf.add_paragraph()
-            p.space_after = Pt(12)
-            _style(p.add_run(), 20, False, self.t['text'])
-            p.runs[0].text = '•  ' + str(b)
+        a, b = self.g.cols(2)
+        for box, head, items in ((a, left_title, left), (b, right_title, right)):
+            inner = box
+            if head:
+                self._rect_shape(s, Rect(box.x, box.y, box.w, 0.44), self.t['light'])
+                self._fit_line(s, Rect(box.x + 0.16, box.y + 0.09, box.w - 0.32, 0.3), head, 16,
+                               self.t['on_light'], bold=True, what=f'栏头{head[:6]}')
+                inner = Rect(box.x, box.y + 0.6, box.w, box.h - 0.6)
+            items = [x if isinstance(x, (list, tuple)) else (str(x), 0) for x in _flat(items)]
+            if self._fit_text(s, inner, items, hi=20, lo=14) is None:
+                self.warnings.append(f'「{title}」{head or ""}栏内容过多，已按下限字号放置，请精简')
+                self._fit_text(s, inner, items[:max(1, len(items) - 1)], hi=14, lo=12)
         return s
 
-    def add_kpi(self, title, kpis, notes=None):
-        """kpis: [(大数字, 说明)]，最多 4 个卡片。"""
-        s = self._slide(notes)
+    def add_kpi(self, title, kpis, notes=None, caption=''):
+        """大数字卡片页。kpis: [(数字, 说明)] 或 [(数字, 说明, 同比)]，1~6 个自动排布。"""
+        s = self._slide(notes, kind='KPI', title=title)
         self._title(s, title)
-        n = min(len(kpis), 4)
-        w = Inches(2.7)
-        gap = (self.prs.slide_width - n * w) / (n + 1)
-        for i, (num, label) in enumerate(kpis[:4]):
-            x = gap * (i + 1) + w * i
-            self._rect(s, x, Inches(2.4), w, Inches(2.2), self.t['light'])
-            self._text(s, x, Inches(2.7), w, Inches(1), str(num), size=36, bold=True, color=self.t['primary'], align=PP_ALIGN.CENTER)
-            self._text(s, x, Inches(3.8), w, Inches(0.6), str(label), size=14, color=self.t['text'], align=PP_ALIGN.CENTER)
+        ks = list(kpis)[:6]
+        n = len(ks)
+        box = self.g.content
+        if caption:
+            box = Rect(box.x, box.y, box.w, box.h - 0.5)
+        rows = 1 if n <= 3 else 2
+        per = (n + rows - 1) // rows
+        row_boxes = self.g.rows(rows, box, gap=0.3) if rows > 1 else [box]
+        card_h = min(2.3, row_boxes[0].h)
+        for ri in range(rows):
+            chunk = ks[ri * per:(ri + 1) * per]
+            if not chunk:
+                continue
+            rb = row_boxes[ri]
+            cells = self.g.cols(len(chunk), Rect(rb.x, rb.y + (rb.h - card_h) / 2, rb.w, card_h))
+            for cell, k in zip(cells, chunk):
+                num, label = str(k[0]), str(k[1])
+                delta = str(k[2]) if len(k) > 2 else ''
+                self._rect_shape(s, cell, self.t['light'])
+                self._rect_shape(s, Rect(cell.x, cell.y, cell.w, 0.06), self.t['accent'])
+                # 卡片内按比例分三层，层与层之间留真实间隙——写死偏移量迟早把两层叠在一起
+                iw, h = cell.w - 0.28, cell.h
+                nb = Rect(cell.x + 0.14, cell.y + h * 0.13, iw, h * 0.36)
+                self._fit_line(s, nb, num, 40, self.t['on_light'], PP_ALIGN.CENTER, bold=True, lo=18,
+                               font=FONT_NUM, anchor=MSO_ANCHOR.MIDDLE, what='大数字')
+                lb = Rect(cell.x + 0.14, cell.y + h * 0.53, iw, h * (0.20 if delta else 0.32))
+                self._fit_line(s, lb, label, 14,
+                               self._fg(self.t['light'], [self.t['text'], self.t['on_light']]),
+                               PP_ALIGN.CENTER, lo=10, what='卡片标签')
+                if delta:
+                    self._fit_line(s, Rect(cell.x + 0.14, cell.y + h * 0.76, iw, h * 0.16), delta, 11,
+                                   self._fg(self.t['light'], [self.t['accent'], self.t['on_light']]),
+                                   PP_ALIGN.CENTER, bold=True, what='同比')
+                self._claim(cell, f'卡片{label[:6]}')
+        if caption:
+            self._fit_line(s, Rect(box.x, self.g.bottom - 0.4, box.w, 0.36), caption,
+                           SZ_CAPTION, self.t['muted'], what='注解')
         return s
 
     def add_image(self, title, image_path, caption='', notes=None):
-        s = self._slide(notes)
+        """整幅图页。**永远等比 contain**——只给一边尺寸的写法在这里不存在，图不可能被拉变形。"""
+        s = self._slide(notes, kind='图', title=title)
         self._title(s, title)
-        pic = s.shapes.add_picture(image_path, Inches(1), Inches(1.6), height=Inches(4.6))
-        if pic.width > self.prs.slide_width - Inches(1):  # 超宽图改按宽度适配
-            s.shapes._spTree.remove(pic._element)
-            pic = s.shapes.add_picture(image_path, Inches(1), Inches(1.6), width=self.prs.slide_width - Inches(2))
-        pic.left = int((self.prs.slide_width - pic.width) / 2)
+        box = self.g.content
+        if caption:
+            box = Rect(box.x, box.y, box.w, box.h - 0.46)
+        self._place_image(s, image_path, box)
         if caption:
-            self._text(s, Inches(1), Inches(6.4), Inches(11.3), Inches(0.6), caption, size=14, color='777777', align=PP_ALIGN.CENTER)
+            self._fit_line(s, Rect(box.x, box.bottom + 0.12, box.w, 0.34), caption,
+                           SZ_CAPTION, self.t['muted'], PP_ALIGN.CENTER, what='图注')
         return s
 
-    def add_table(self, title, rows, notes=None):
-        s = self._slide(notes)
+    def add_image_text(self, title, image_path, bullets, side='left', caption='', notes=None):
+        """图文页：一半图一半要点（图仍等比 contain）。"""
+        s = self._slide(notes, kind='图文', title=title)
         self._title(s, title)
-        nr, nc = len(rows), len(rows[0])
-        tb = s.shapes.add_table(nr, nc, Inches(0.9), Inches(1.7), Inches(11.5), Inches(0.5) * nr).table
-        for i, row in enumerate(rows):
-            for j, val in enumerate(row):
-                cell = tb.cell(i, j)
-                cell.text = str(val)
+        a, b = self.g.cols(2)
+        img_box, txt_box = (a, b) if side == 'left' else (b, a)
+        if caption:
+            img_box = Rect(img_box.x, img_box.y, img_box.w, img_box.h - 0.42)
+        self._place_image(s, image_path, img_box)
+        if caption:
+            self._fit_line(s, Rect(img_box.x, img_box.bottom + 0.1, img_box.w, 0.32), caption,
+                           SZ_CAPTION, self.t['muted'], PP_ALIGN.CENTER, what='图注')
+        items = [x if isinstance(x, (list, tuple)) else (str(x), 0) for x in _flat(bullets)]
+        tb2 = Rect(txt_box.x, txt_box.y, txt_box.w, txt_box.h)
+        take = len(items)
+        while take > 0 and self._fit_text(s, tb2, items[:take], hi=20, lo=14) is None:
+            take -= 1
+        if take < len(items):
+            self.warnings.append(f'「{title}」右栏要点过多，只放下 {take} 条，其余请另开一页')
+        return s
+
+    def _place_image(self, s, path, box):
+        from PIL import Image
+        try:
+            with Image.open(path) as im:
+                nw, nh = im.size
+        except Exception:
+            nw, nh = 16, 9
+        fit = L.contain_fit(nw, nh, box)
+        pic = s.shapes.add_picture(path, Emu(int(fit.x * L.EMU_IN)), Emu(int(fit.y * L.EMU_IN)),
+                                   width=Emu(int(fit.w * L.EMU_IN)), height=Emu(int(fit.h * L.EMU_IN)))
+        dpi = min(nw / max(0.01, fit.w), nh / max(0.01, fit.h))
+        if dpi < 96:
+            self.warnings.append(f'{os.path.basename(str(path))} 原图 {nw}×{nh}px，铺到 {fit.w:.1f}"×{fit.h:.1f}" 仅 {dpi:.0f}dpi，贴出来会糊')
+        self._claim(fit, '图片')
+        return pic
+
+    def add_table(self, title, rows, notes=None, col_widths=None, note='', max_rows=None):
+        """表格页。列宽按内容自动分配，行高按折行实算；行数超出页面则**自动分页**。"""
+        rows = [[('' if c is None else str(c)) for c in r] for r in rows]
+        if not rows:
+            return self._slide(notes, kind='表', title=title)
+        header, body = rows[0], rows[1:]
+        box = self.g.content
+        if note:
+            box = Rect(box.x, box.y, box.w, box.h - 0.42)
+        widths = col_widths or _auto_widths(header, body, box.w)
+        fs_head, fs_body = 14, 13
+        rh = [_row_h(header, widths, fs_head, True)] + [_row_h(r, widths, fs_body, False) for r in body]
+        cap = max_rows or _max_rows(rh, box.h)
+        pages = [body[i:i + cap] for i in range(0, len(body), cap)] or [[]]
+        made = []
+        for pi, chunk in enumerate(pages):
+            t = title if pi == 0 else f'{title}（{pi + 1}/{len(pages)}）'
+            s = self._slide(notes if pi == 0 else None, kind='表', title=t)
+            self._title(s, t)
+            self._draw_table(s, box, header, chunk, widths, fs_head, fs_body)
+            if note:
+                self._fit_line(s, Rect(box.x, box.bottom + 0.1, box.w, 0.32), note,
+                               SZ_CAPTION, self.t['muted'], what='表注')
+            made.append(s)
+        if len(pages) > 1:
+            self.warnings.append(f'「{title}」共 {len(body)} 行，已自动分为 {len(pages)} 页（每页 ≤{cap} 行）')
+        return made[0] if len(made) == 1 else made
+
+    def _draw_table(self, s, box, header, body, widths, fs_head, fs_body):
+        nr, nc = len(body) + 1, len(header)
+        heights = [_row_h(header, widths, fs_head, True)] + [_row_h(r, widths, fs_body, False) for r in body]
+        total = sum(heights)
+        shp = s.shapes.add_table(nr, nc, Emu(int(box.x * L.EMU_IN)), Emu(int(box.y * L.EMU_IN)),
+                                 Emu(int(box.w * L.EMU_IN)), Emu(int(total * L.EMU_IN)))
+        tbl = shp.table
+        tbl.first_row = True
+        for j, w in enumerate(widths):
+            tbl.columns[j].width = Emu(int(w * L.EMU_IN))
+        for i, h in enumerate(heights):
+            tbl.rows[i].height = Emu(int(h * L.EMU_IN))
+        for i, row in enumerate([header] + body):
+            for j in range(nc):
+                cell = tbl.cell(i, j)
+                cell.text = row[j] if j < len(row) else ''
+                cell.margin_left = cell.margin_right = Pt(7)
+                cell.margin_top = cell.margin_bottom = Pt(3)
+                cell.vertical_anchor = MSO_ANCHOR.MIDDLE
                 p = cell.text_frame.paragraphs[0]
-                _style(p.runs[0] if p.runs else p.add_run(), 14, i == 0, 'FFFFFF' if i == 0 else self.t['text'])
-                if i == 0:
-                    cell.fill.solid()
-                    cell.fill.fore_color.rgb = RGBColor.from_string(self.t['primary'])
+                p.alignment = PP_ALIGN.LEFT if j == 0 else PP_ALIGN.RIGHT
+                r = p.runs[0] if p.runs else p.add_run()
+                band = self.t['primary'] if i == 0 else (self.t['bg'] if i % 2 else self.t['light'])
+                self._style(r, fs_head if i == 0 else fs_body, i == 0,
+                            self.t['on_primary'] if i == 0 else self._fg(band, [self.t['text'], self.t['on_light']]))
+                cell.fill.solid()
+                cell.fill.fore_color.rgb = RGBColor.from_string(band)
+        self._claim(Rect(box.x, box.y, box.w, total), '表格')
+        return tbl
+
+    def add_quote(self, text, author='', notes=None):
+        g = self.g
+        s = self._slide(notes, chrome=False, kind='引言', title=text[:16])
+        self._rect_shape(s, Rect(0, 0, g.W, g.H), self.t['light'])
+        box = Rect(g.m + 0.8, g.H * 0.26, g.W - 2 * g.m - 1.6, g.H * 0.36)
+        tb, tf = self._textbox(s, Rect(box.x - 0.55, box.y - 0.15, 0.6, 1.2))
+        self._para(tf, True, '“', 60, True, self._fg(self.t['light'], [self.t['accent'], self.t['on_light']], 3.0))
+        self._fit_line(s, box, text, 28, self.t['on_light'], lo=16,
+                       anchor=MSO_ANCHOR.MIDDLE, what='引言')
+        if author:
+            self._fit_line(s, Rect(box.x, box.bottom + 0.24, box.w, 0.4), '—— ' + author, 14,
+                           self._fg(self.t['light'], [self.t['muted'], self.t['on_light']]),
+                           PP_ALIGN.RIGHT, what='出处')
+        return s
+
+    def add_compare(self, title, left_title, left, right_title, right, notes=None):
+        """左右对照页（现状/目标、方案 A/B）。两栏底色不同，一眼看出这是对比。"""
+        s = self._slide(notes, kind='对照', title=title)
+        self._title(s, title)
+        a, b = self.g.cols(2)
+        for box, head, items, tone in ((a, left_title, left, self.t['muted']),
+                                       (b, right_title, right, self.t['primary'])):
+            self._rect_shape(s, box, self.t['light'])
+            self._rect_shape(s, Rect(box.x, box.y, box.w, 0.5), tone)
+            self._fit_line(s, Rect(box.x + 0.18, box.y + 0.11, box.w - 0.36, 0.32), head, 16,
+                           self._fg(tone, [self.t['on_primary'], 'FFFFFF']), bold=True, what=f'对照头{head[:6]}')
+            inner = Rect(box.x + 0.24, box.y + 0.72, box.w - 0.48, box.h - 0.96)
+            its = [x if isinstance(x, (list, tuple)) else (str(x), 0) for x in _flat(items)]
+            take = len(its)
+            while take > 0 and self._fit_text(s, inner, its[:take], hi=18, lo=13,
+                                              color=self._fg(self.t['light'], [self.t['text'], self.t['on_light']])) is None:
+                take -= 1
+            if take < len(its):
+                self.warnings.append(f'「{title}」{head} 栏只放下 {take} 条，请精简')
+            self._claim(box, f'对照栏{head}')
         return s
 
-    def add_end(self, text='谢谢', notes=None):
-        s = self._slide(notes)
-        self._rect(s, 0, 0, self.prs.slide_width, self.prs.slide_height, self.t['primary'])
-        self._text(s, Inches(1), Inches(3.1), Inches(11.3), Inches(1.2), text, size=40, bold=True, color='FFFFFF', align=PP_ALIGN.CENTER)
+    def add_timeline(self, title, items, notes=None):
+        """时间轴页。items: [(时间, 事项)]，最多 6 段。"""
+        s = self._slide(notes, kind='时间轴', title=title)
+        self._title(s, title)
+        its = list(items)[:6]
+        box = self.g.content
+        n = max(1, len(its))
+        y = box.y + box.h * 0.42
+        self._rect_shape(s, Rect(box.x, y, box.w, 0.035), self.t['light'])
+        cells = self.g.cols(n, box)
+        for i, (cell, it) in enumerate(zip(cells, its)):
+            when, what = (str(it[0]), str(it[1])) if isinstance(it, (list, tuple)) else ('', str(it))
+            cx = cell.x + cell.w / 2
+            self._rect_shape(s, Rect(cx - 0.09, y - 0.075, 0.18, 0.18), self.t['accent'])
+            self._fit_line(s, Rect(cell.x, y - 0.78, cell.w, 0.5), when, 16, self.t['head'],
+                           PP_ALIGN.CENTER, bold=True, anchor=MSO_ANCHOR.BOTTOM, what=f'时间{i + 1}')
+            wb = Rect(cell.x + 0.06, y + 0.3, cell.w - 0.12, box.bottom - y - 0.34)
+            self._fit_line(s, wb, what, 15, self.t['text'], PP_ALIGN.CENTER, lo=11, what=f'事项{i + 1}')
+        return s
+
+    def add_end(self, text='谢谢', subtitle='', notes=None):
+        g = self.g
+        s = self._slide(notes, chrome=False, kind='结尾', title=text)
+        self._rect_shape(s, Rect(0, 0, g.W, g.H), self.t['primary'])
+        box = Rect(g.m, g.H * 0.38, g.W - 2 * g.m, g.H * 0.2)
+        self._fit_line(s, box, text, 40, self.t['on_primary'], PP_ALIGN.CENTER, bold=True, lo=24,
+                       anchor=MSO_ANCHOR.MIDDLE, what='结尾语')
+        if subtitle:
+            self._fit_line(s, Rect(box.x, box.bottom + 0.16, box.w, 0.5), subtitle, 16,
+                           self._fg(self.t['primary'], [self.t['light'], self.t['on_primary']]),
+                           PP_ALIGN.CENTER, what='结尾副标题')
         return s
 
-    def save(self, path):
+    # ── 出片 ────────────────────────────────────────────────────────────────
+    def save(self, path, check=True, verbose=True):
+        """保存并**自动体检**（check=False 才跳过）。返回体检结果 dict。
+
+        自检不是可选项：生成完不查，等于把"没溢出/没重叠"这句话建立在祈祷上。
+        """
+        self._chrome()
         self.prs.save(path)
-        return path
+        if verbose and self.warnings:
+            print('【建版提示】')
+            for w in self.warnings:
+                print('  ·', w)
+        if not check:
+            return None
+        import pptx_check
+        res = pptx_check.inspect(path)
+        if verbose:
+            print(pptx_check.report(res))
+        return res
+
+    def outline(self):
+        """已建页面的大纲（页号 / 版式 / 标题），核对用。"""
+        return list(self._outline)
+
+
+# ── 工具函数 ────────────────────────────────────────────────────────────────
+def _flat(bullets):
+    """接受 ['a', ('b',1), {'text':'c','sub':['d']}] 三种写法，摊平成 [(text, level)]。"""
+    out = []
+    for b in bullets or []:
+        if isinstance(b, dict):
+            out.append((str(b.get('text', '')), int(b.get('level', 0))))
+            for sub in b.get('sub', []) or []:
+                out.append((str(sub), 1))
+        elif isinstance(b, (list, tuple)) and len(b) == 2 and isinstance(b[1], int):
+            out.append((str(b[0]), b[1]))
+        elif isinstance(b, (list, tuple)):
+            out.append((str(b[0]), 0))
+            for sub in list(b[1:]):
+                out.append((str(sub), 1))
+        else:
+            out.append((str(b), 0))
+    return out
 
 
-def verify(path):
-    """重读校验（验收步骤用）：打印页数与每页首个文本。"""
+def _auto_widths(header, body, total):
+    """按各列最长内容分配列宽（首列偏宽给标签，数值列收窄）。"""
+    nc = len(header)
+    need = []
+    for j in range(nc):
+        vals = [header[j]] + [r[j] for r in body if j < len(r)]
+        need.append(max(L.measure(str(v), 13) for v in vals) / L.PT_IN + 0.28)
+    s = sum(need) or 1
+    lo = total / nc * 0.55
+    w = [max(lo, min(total * 0.42, n / s * total)) for n in need]
+    k = total / sum(w)
+    return [x * k for x in w]
+
+
+def _row_h(row, widths, size, bold):
+    h = 0.0
+    for j, w in enumerate(widths):
+        txt = row[j] if j < len(row) else ''
+        lines = L.wrap_segments([(str(txt), size, bold)], max(20.0, w * L.PT_IN - 14))
+        h = max(h, L.text_height(lines) / L.PT_IN + 0.12)
+    return max(0.32, h)
+
+
+def _max_rows(rh, avail):
+    """表头 + 尽可能多的数据行（按最高的一行保守估）。"""
+    head = rh[0]
+    body = rh[1:] or [0.34]
+    per = max(body)
+    return max(2, int((avail - head) / per))
+
+
+def verify(path, detail=False):
+    """重开产物核对：打印页数与每页标题（对大纲用），并跑一遍版式体检。"""
+    import pptx_check
     prs = Presentation(path)
-    n = len(prs.slides)
-    print(f'[verify] 共 {n} 页')
+    print(f'[verify] 共 {len(prs.slides)} 页')
     for i, s in enumerate(prs.slides, 1):
         first = next((sh.text_frame.text.split('\n')[0] for sh in s.shapes
                       if sh.has_text_frame and sh.text_frame.text.strip()), '（无文本）')
         print(f'  p{i}: {first[:40]}')
-    return n
+    res = pptx_check.inspect(path)
+    print(pptx_check.report(res))
+    return res if detail else len(prs.slides)
+
+
+def _demo_png(path='pptx_deck_check.png', w=1280, h=720):
+    """自测用示意图（真实尺寸，免得占位小图必然触发"图片发虚"）。"""
+    from PIL import Image, ImageDraw
+    im = Image.new('RGB', (w, h), (245, 248, 251))
+    d = ImageDraw.Draw(im)
+    for i, v in enumerate([0.42, 0.68, 0.55, 0.81, 0.34]):
+        x = 120 + i * 210
+        d.rectangle([x, int(h * (1 - v)) - 60, x + 130, h - 90], fill=(46, 117, 182))
+    d.line([(90, h - 90), (w - 90, h - 90)], fill=(120, 130, 140), width=3)
+    im.save(path)
+    return path
 
 
 if __name__ == '__main__':
-    png = 'pptx_deck_check.png'  # 1x1 红点 png，占位自测（真实场景用 matplotlib 产图）
-    open(png, 'wb').write(base64.b64decode(
-        'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg=='))
-    d = Deck('navy')
-    d.add_cover('自测演示', 'pptx_deck.py 冒烟', notes='备注示例')
-    d.add_agenda(['概览', '数据', '结论'])
-    d.add_section('一、概览')
-    d.add_bullets('要点', ['要点甲', '要点乙', '要点丙'])
-    d.add_kpi('核心指标', [('3.6亿', '营收'), ('+18%', '同比'), ('32.5%', '毛利率')])
-    d.add_image('示意图', png, caption='占位图')
-    d.add_table('明细', [['地区', '销售额'], ['华东', '1200'], ['华南', '950']])
-    d.add_end()
-    p = d.save('pptx_deck_check.pptx')
-    verify(p)
-    print('OK', p)
+    png = _demo_png()
+    d = Deck('navy', footer='自测 · pptx_deck.py')
+    d.add_cover('2026 上半年经营分析', '数据一部', '2026-07-15', notes='备注示例')
+    d.add_agenda(['经营概览', '分区域表现', '问题与对策', '下半年计划', '资源需求', '风险提示'])
+    d.add_section('经营概览', no='PART 01', subtitle='数据截至 6 月 30 日')
+    d.add_kpi('核心指标', [('3.6亿', '营业收入', '同比 +18%'), ('32.5%', '毛利率', '环比 +1.2pct'),
+                           ('1.02亿', '经营性现金流', '同比 +9%'), ('87', 'NPS', '较去年 +5')])
+    d.add_bullets('增长来自哪里', [
+        '华东新签 12 家大客户，贡献增量 4200 万',
+        '订阅制收入占比 21% → 34%',
+        ('产品侧', '智能报表 3 月上线，续费率 92%', '数据服务包提价 8%，未见流失'),
+        '渠道伙伴翻倍，但单伙伴产出降 15%',
+        '西南仍未扭亏，卡在交付人力',
+    ], lead='结论：增长靠华东与订阅制，风险在渠道与西南', notes='这里展开讲渠道的账')
+    d.add_two_col('机会与风险', ['订阅制续费盘子稳定', '智能报表口碑好', '政企预算在恢复'],
+                  ['渠道单产下滑', '西南交付人力缺口 30%', '海外回款慢'],
+                  left_title='机会', right_title='风险')
+    d.add_compare('渠道策略调整', '现状（半年）', ['伙伴 48 家，单产 76 万', '无分层，资源平均撒', '培训 2 场'],
+                  '下半年', ['砍到 24 家精耕', 'A/B/C 三层差异化返点', '每月 1 场认证培训'])
+    d.add_image('区域销售分布', png, caption='华东领先，西南承压')
+    d.add_image_text('智能报表模块表现', png, ['上线 4 个月，MAU 1.2 万', '续费率 92%，高于均值 11pct',
+                                                '客户最常用的是自动周报'], caption='模块使用趋势')
+    d.add_table('分区域明细', [['地区', '销售额(万)', '同比', '毛利率', '回款天数'],
+                               ['华东', '12000', '+21%', '35.2%', '48'],
+                               ['华南', '9500', '+12%', '31.0%', '55'],
+                               ['华北', '7200', '+8%', '29.8%', '61'],
+                               ['西南', '3100', '-4%', '22.4%', '88'],
+                               ['海外', '4200', '+35%', '38.1%', '120']],
+                 note='口径：含税收入，与财务月结一致')
+    d.add_timeline('下半年节奏', [('7月', '渠道分层方案落地'), ('8月', '西南交付团队补齐'),
+                                  ('9月', '订阅 2.0 定价发布'), ('11月', '海外回款政策调整'),
+                                  ('12月', '年度复盘与预算')])
+    d.add_quote('增长不是把所有事都做一遍，是把对的事做到底。', '经营分析会')
+    d.add_end('谢谢，欢迎讨论', '数据一部 · 2026-07')
+    # 自动拆页演示：给 14 条要点，引擎会自己拆成「原标题 + （续）」两页
+    d.add_bullets('风险清单（演示自动拆页）', [f'风险项 {i + 1}：影响面与应对各一句' for i in range(14)])
+    res = d.save('pptx_deck_check.pptx')
+    print('\n大纲：')
+    for no, kind, title in d.outline():
+        print(f'  p{no} [{kind}] {title}')