@huicai/cli 2026.814.0 → 2026.1019.0

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

@@ -0,0 +1,1182 @@
+# PPT 版式体检（对任意 .pptx 都能跑，不限于本技能生成的）。
+#
+# 解决的真问题：幻灯片是"盲写"的——python-pptx 把文字塞进一个固定大小的框，
+# 塞不塞得下没人知道；图片给了 width 又给 height 就被悄悄拉成长脸；
+# 两个框坐标算错就直接压在一起。这些在保存那一刻全都不报错，
+# 等人打开 PPT 才看见，而那时模型早就说"已完成"了。
+#
+# 本模块把这些做成确定性检查：逐页遍历形状 → 还原几何与文字度量 →
+# 判溢出/重叠/变形/越界/字号/对比度/表格/内容密度/跨页一致性，
+# 每条都带页码、元素名与具体数字（估算高 4.62" vs 可用高 3.90"），
+# 而不是一句"排版有问题"。
+#
+# 用法：
+#   python pptx_check.py 汇报.pptx                # 人读报告
+#   python pptx_check.py 汇报.pptx --json         # 机读
+#   python pptx_check.py 汇报.pptx --fix          # 自动修可安全修的，另存 -已修复.pptx
+#   python pptx_check.py 汇报.pptx --fix --inplace
+# 或在 run_python 里：from pptx_check import inspect, report, fix
+
+import json
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+from pptx import Presentation                                    # noqa: E402
+from pptx.enum.shapes import MSO_SHAPE_TYPE                       # 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
+
+# ── 阈值（集中在这里，便于按场合调紧调松）────────────────────────────────────
+SAFE_MARGIN = 0.22        # 安全边距（英寸）：内容离页边小于它就算贴边
+OVERLAP_MIN = 0.06        # 重叠面积占比低于它视为误差，不报
+DISTORT_WARN = 0.02       # 图片宽高比偏差 >2% 提醒
+DISTORT_ERR = 0.06        # >6% 判为明显变形
+MIN_DPI = 96              # 图片渲染分辨率下限（低于此贴出来是糊的）
+FONT_ERR = 10.0           # 字号下限（磅）：低于此投影上根本看不清
+FONT_WARN = 14.0
+CONTRAST_ERR = 3.0
+CONTRAST_WARN = 4.5
+MAX_BULLETS = 6
+MAX_BULLET_CHARS = 25
+MAX_SLIDE_CHARS = 220
+MAX_TITLE_CHARS = 24
+TITLE_JITTER = 0.06       # 各页标题基线抖动上限（英寸）
+
+LEVEL_ORDER = {'error': 0, 'warn': 1, 'info': 2}
+LEVEL_CN = {'error': '必修', 'warn': '建议', 'info': '提示'}
+
+CODE_CN = {
+    'overflow_v': '文字溢出',
+    'overflow_h': '横向超宽',
+    'out_of_slide': '超出页面',
+    'off_grid': '贴边过近',
+    'overlap': '元素重叠',
+    'image_distort': '图片变形',
+    'image_blurry': '图片发虚',
+    'table_overflow': '表格超界',
+    'tiny_shape': '元素过小',
+    'font_too_small': '字号过小',
+    'no_ea_font': '中文字体未设',
+    'font_zoo': '字体过杂',
+    'low_contrast': '对比度不足',
+    'autofit_shrunk': '被迫缩字',
+    'bullet_overload': '要点过多',
+    'bullet_too_long': '要点过长',
+    'title_too_long': '标题过长',
+    'text_wall': '文字过密',
+    'empty_slide': '空白页',
+    'dup_title': '标题重复',
+    'title_jitter': '标题错位',
+    'palette_zoo': '配色过杂',
+    'size_odd': '页面比例',
+}
+FIXABLE = {'image_distort', 'out_of_slide', 'off_grid', 'overflow_v', 'table_overflow'}
+
+
+class Finding(dict):
+    def __init__(self, page, code, level, detail, hint='', where='', rect=None, fixable=None):
+        super().__init__(
+            page=page, code=code, level=level, name=CODE_CN.get(code, code),
+            detail=detail, hint=hint, where=where,
+            fixable=(code in FIXABLE) if fixable is None else bool(fixable),
+            rect=None if rect is None else [round(rect.x, 2), round(rect.y, 2), round(rect.w, 2), round(rect.h, 2)],
+        )
+
+
+# ── 几何还原 ────────────────────────────────────────────────────────────────
+def _in(v):
+    return None if v is None else v / L.EMU_IN
+
+
+def _rect_of(sh, inherit=None):
+    """形状矩形（英寸）。占位符缺尺寸时回退到版式里同 idx 的占位符。"""
+    x, y, w, h = sh.left, sh.top, sh.width, sh.height
+    if None in (x, y, w, h) and inherit is not None:
+        x = x if x is not None else inherit.left
+        y = y if y is not None else inherit.top
+        w = w if w is not None else inherit.width
+        h = h if h is not None else inherit.height
+    if None in (x, y, w, h):
+        return None
+    return L.Rect(_in(x), _in(y), _in(w), _in(h))
+
+
+def _rot_aabb(r, deg):
+    """旋转后的外接矩形（重叠判定用；0/180 度原样返回）。"""
+    d = float(deg or 0) % 360
+    if d < 0.01 or abs(d - 180) < 0.01:
+        return r
+    import math
+    a = math.radians(d)
+    cx, cy = r.x + r.w / 2, r.y + r.h / 2
+    hw = (abs(r.w * math.cos(a)) + abs(r.h * math.sin(a))) / 2
+    hh = (abs(r.w * math.sin(a)) + abs(r.h * math.cos(a))) / 2
+    return L.Rect(cx - hw, cy - hh, hw * 2, hh * 2)
+
+
+def _group_xf(grp):
+    """组合的子坐标变换（chOff/chExt → off/ext）。取不到返回恒等。"""
+    try:
+        xfrm = grp._element.find(qn('p:grpSpPr')).find(qn('a:xfrm'))
+        off, ext = xfrm.find(qn('a:off')), xfrm.find(qn('a:ext'))
+        ch_off, ch_ext = xfrm.find(qn('a:chOff')), xfrm.find(qn('a:chExt'))
+        ox, oy = int(off.get('x')), int(off.get('y'))
+        cx, cy = int(ext.get('cx')), int(ext.get('cy'))
+        gx, gy = int(ch_off.get('x')), int(ch_off.get('y'))
+        gw, gh = int(ch_ext.get('cx')), int(ch_ext.get('cy'))
+        sx = cx / gw if gw else 1.0
+        sy = cy / gh if gh else 1.0
+        return (ox / L.EMU_IN, oy / L.EMU_IN, gx / L.EMU_IN, gy / L.EMU_IN, sx, sy)
+    except Exception:
+        return None
+
+
+def _layout_ph(slide, sh):
+    """占位符在版式里的对应形状（继承尺寸用）。"""
+    try:
+        if not sh.is_placeholder:
+            return None
+        idx = sh.placeholder_format.idx
+        for p in slide.slide_layout.placeholders:
+            if p.placeholder_format.idx == idx:
+                return p
+    except Exception:
+        pass
+    return None
+
+
+def walk(slide):
+    """展开一页的所有形状（组合按变换递归展开），按 z 序返回 [(shape, Rect, z)]。"""
+    out = []
+
+    def rec(container, xf, depth):
+        for sh in container.shapes:
+            if sh.shape_type == MSO_SHAPE_TYPE.GROUP:
+                sub = _group_xf(sh)
+                out.append((sh, _apply(_rect_of(sh), xf), len(out), True))
+                if sub and depth < 4:
+                    rec(sh, _compose(xf, sub), depth + 1)
+                continue
+            r = _rect_of(sh, _layout_ph(slide, sh))
+            if r is None:
+                continue
+            out.append((sh, _apply(r, xf), len(out), False))
+
+    def _apply(r, xf):
+        if r is None or xf is None:
+            return r
+        ox, oy, gx, gy, sx, sy = xf
+        return L.Rect(ox + (r.x - gx) * sx, oy + (r.y - gy) * sy, r.w * sx, r.h * sy)
+
+    def _compose(outer, inner):
+        if outer is None:
+            return inner
+        ox, oy, gx, gy, sx, sy = outer
+        ix, iy, igx, igy, isx, isy = inner
+        nx = ox + (ix - gx) * sx
+        ny = oy + (iy - gy) * sy
+        return (nx, ny, igx, igy, isx * sx, isy * sy)
+
+    rec(slide, None, 0)
+    return [(sh, r, z) for sh, r, z, is_grp in out if r is not None and not is_grp]
+
+
+# ── 文字度量还原 ────────────────────────────────────────────────────────────
+def _run_size(run, para, sh):
+    if run.font.size is not None:
+        return run.font.size.pt
+    try:
+        if para.font.size is not None:
+            return para.font.size.pt
+    except Exception:
+        pass
+    # 占位符按类型给经验默认；普通文本框 PowerPoint 默认 18pt
+    try:
+        if sh.is_placeholder and sh.placeholder_format.idx == 0:
+            return 44.0
+    except Exception:
+        pass
+    return 18.0
+
+
+def _bodypr(tf):
+    try:
+        return tf._txBody.find(qn('a:bodyPr'))
+    except Exception:
+        return None
+
+
+def _insets(tf):
+    """文本框内边距（磅）：左右、上下。"""
+    bp = _bodypr(tf)
+    lr, tb = L.INSET_LR, L.INSET_TB
+    if bp is not None:
+        try:
+            li = bp.get('lIns')
+            ri = bp.get('rIns')
+            ti = bp.get('tIns')
+            bi = bp.get('bIns')
+            lv = int(li) / L.EMU_PT if li is not None else L.INSET_LR
+            rv = int(ri) / L.EMU_PT if ri is not None else L.INSET_LR
+            tv = int(ti) / L.EMU_PT if ti is not None else L.INSET_TB
+            bv = int(bi) / L.EMU_PT if bi is not None else L.INSET_TB
+            lr, tb = (lv + rv) / 2, (tv + bv) / 2
+        except Exception:
+            pass
+    return lr, tb
+
+
+def _autofit(tf):
+    """PowerPoint 自动缩放：返回 (字号比例, 行距压缩)。none/spAutoFit 返回 (1,0)。"""
+    bp = _bodypr(tf)
+    if bp is None:
+        return 1.0, 0.0
+    na = bp.find(qn('a:normAutofit'))
+    if na is None:
+        return 1.0, 0.0
+    fs = na.get('fontScale')
+    lr = na.get('lnSpcReduction')
+    return (int(fs) / 100000.0 if fs else 1.0), (int(lr) / 100000.0 if lr else 0.0)
+
+
+def _word_wrap(tf):
+    bp = _bodypr(tf)
+    if bp is not None and bp.get('wrap') == 'none':
+        return False
+    return True
+
+
+def _para_indent(p):
+    """段落左缩进（磅）：优先读 pPr@marL（建版侧写入的挂起缩进），否则按层级估算。"""
+    try:
+        pPr = p._p.find(qn('a:pPr'))
+        if pPr is not None and pPr.get('marL') is not None:
+            return int(pPr.get('marL')) / L.EMU_PT
+    except Exception:
+        pass
+    return (p.level or 0) * 0.28 * L.PT_IN
+
+
+def para_lines(sh, rect, tf=None):
+    """还原一个文本框的排版：返回 (总高磅, 最大行宽磅, 可用宽磅, 可用高磅, 段落明细)。"""
+    tf = tf or sh.text_frame
+    lr, tb = _insets(tf)
+    scale, ln_red = _autofit(tf)
+    avail_w = rect.w * L.PT_IN - 2 * lr
+    avail_h = rect.h * L.PT_IN - 2 * tb
+    total = 0.0
+    max_w = 0.0
+    detail = []
+    for p in tf.paragraphs:
+        segs = []
+        for r in p.runs:
+            if r.text:
+                segs.append((r.text, _run_size(r, p, sh) * scale, bool(r.font.bold)))
+        if not segs:
+            # 空段落也占一行高
+            sz = 18.0
+            try:
+                if p.font.size is not None:
+                    sz = p.font.size.pt
+            except Exception:
+                pass
+            total += sz * scale * L.LINE_H
+            detail.append(dict(text='', lines=1, size=sz))
+            continue
+        indent = _para_indent(p)
+        w = max(10.0, avail_w - indent)
+        lines = L.wrap_segments(segs, w) if _word_wrap(tf) else [(''.join(s[0] for s in segs), max(s[1] for s in segs))]
+        ls = 1.0
+        try:
+            if p.line_spacing is not None:
+                ls = float(p.line_spacing) if isinstance(p.line_spacing, (int, float)) else p.line_spacing.pt / max(1.0, max(s[1] for s in segs)) / L.LINE_H
+        except Exception:
+            ls = 1.0
+        ls = max(0.5, ls * (1 - ln_red))
+        h = L.text_height(lines, ls)
+        try:
+            if p.space_before is not None:
+                h += p.space_before.pt
+            if p.space_after is not None:
+                h += p.space_after.pt
+        except Exception:
+            pass
+        total += h
+        for txt, sz in lines:
+            max_w = max(max_w, L.measure(txt, sz) + indent)
+        detail.append(dict(text=''.join(s[0] for s in segs), lines=len(lines),
+                           size=max(s[1] for s in segs)))
+    return total, max_w, avail_w, avail_h, detail
+
+
+def ink_box(sh, rect):
+    """文字实际占据的区域（不是文本框本身）。
+
+    重叠判定必须用它：真实 PPT 里大量文本框远大于文字本身，
+    按框判会把"两个空框挨着"报成重叠，一屏假阳性之后没人再看报告。
+    """
+    try:
+        tf = sh.text_frame
+    except Exception:
+        return rect
+    if not (sh.has_text_frame and tf.text.strip()):
+        return rect
+    total, max_w, avail_w, avail_h, _ = para_lines(sh, rect, tf)
+    lr, tb = _insets(tf)
+    w = min(rect.w, (min(max_w, avail_w) + 2 * lr) / L.PT_IN)
+    h = min(rect.h, (total + 2 * tb) / L.PT_IN)
+    # 水平锚点
+    al = None
+    for p in tf.paragraphs:
+        if p.alignment is not None:
+            al = p.alignment
+            break
+    if al == PP_ALIGN.CENTER:
+        x = rect.x + (rect.w - w) / 2
+    elif al == PP_ALIGN.RIGHT:
+        x = rect.right - w
+    else:
+        x = rect.x
+    # 垂直锚点
+    anc = None
+    try:
+        anc = tf.vertical_anchor
+    except Exception:
+        pass
+    if anc == MSO_ANCHOR.MIDDLE:
+        y = rect.y + (rect.h - h) / 2
+    elif anc == MSO_ANCHOR.BOTTOM:
+        y = rect.bottom - h
+    else:
+        y = rect.y
+    return L.Rect(x, y, max(w, 0.02), max(h, 0.02))
+
+
+# ── 颜色还原 ────────────────────────────────────────────────────────────────
+def _theme_map(prs):
+    """主题配色 clrScheme → {'dk1':'000000', 'accent1':'4472C4', ...}"""
+    out = {}
+    try:
+        for part in prs.part.package.iter_parts():
+            if 'theme' not in str(part.partname):
+                continue
+            root = part._element if hasattr(part, '_element') else None
+            if root is None:
+                from lxml import etree
+                root = etree.fromstring(part.blob)
+            scheme = root.find('.//' + qn('a:clrScheme'))
+            if scheme is None:
+                continue
+            for child in scheme:
+                key = child.tag.split('}')[-1]
+                srgb = child.find(qn('a:srgbClr'))
+                if srgb is not None:
+                    out[key] = srgb.get('val')
+                    continue
+                sysc = child.find(qn('a:sysClr'))
+                if sysc is not None:
+                    out[key] = sysc.get('lastClr') or ('000000' if 'Text' in (sysc.get('val') or '') else 'FFFFFF')
+            break
+    except Exception:
+        pass
+    return out
+
+
+_THEME_ALIAS = {
+    'TEXT_1': 'dk1', 'BACKGROUND_1': 'lt1', 'TEXT_2': 'dk2', 'BACKGROUND_2': 'lt2',
+    'DARK_1': 'dk1', 'LIGHT_1': 'lt1', 'DARK_2': 'dk2', 'LIGHT_2': 'lt2',
+    'ACCENT_1': 'accent1', 'ACCENT_2': 'accent2', 'ACCENT_3': 'accent3',
+    'ACCENT_4': 'accent4', 'ACCENT_5': 'accent5', 'ACCENT_6': 'accent6',
+}
+
+
+def _color_hex(color, theme):
+    """ColorFormat → 'RRGGBB'；解析不出返回 None（宁可跳过检查也不猜）。"""
+    if color is None:
+        return None
+    try:
+        if color.type is None:
+            return None
+        if str(color.type).startswith('RGB') or color.type == 1:
+            return str(color.rgb)
+    except Exception:
+        return None
+    try:
+        name = str(color.theme_color).split('.')[-1].split(' ')[0]
+        base = theme.get(_THEME_ALIAS.get(name, ''), None)
+        if not base:
+            return None
+        try:
+            b = color.brightness
+        except Exception:
+            b = 0
+        rgb = L.hex_rgb(base)
+        if rgb and b:
+            if b > 0:
+                rgb = tuple(int(c + (255 - c) * b) for c in rgb)
+            else:
+                rgb = tuple(int(c * (1 + b)) for c in rgb)
+            return '%02X%02X%02X' % rgb
+        return base
+    except Exception:
+        return None
+
+
+def _fill_hex(sh, theme):
+    """形状填充色（纯色/渐变首停靠色）；无填充返回 None。"""
+    try:
+        f = sh.fill
+        t = str(f.type)
+        if 'SOLID' in t or f.type == 1:
+            return _color_hex(f.fore_color, theme)
+        if 'GRADIENT' in t:
+            try:
+                return _color_hex(f.gradient_stops[0].color, theme)
+            except Exception:
+                return None
+    except Exception:
+        pass
+    return None
+
+
+# ── 主检查 ──────────────────────────────────────────────────────────────────
+def inspect(path, strict=False):
+    """体检一份 pptx，返回 {ok, path, slides, size, findings, stats}。"""
+    prs = Presentation(path)
+    sw, sh_in = _in(prs.slide_width), _in(prs.slide_height)
+    page = L.Rect(0, 0, sw, sh_in)
+    theme = _theme_map(prs)
+    findings = []
+    titles = []
+    title_tops = []
+    fonts = set()
+    fills = set()
+    stats = dict(shapes=0, texts=0, pictures=0, tables=0, charts=0, chars=0)
+
+    for pno, slide in enumerate(prs.slides, 1):
+        items = walk(slide)
+        stats['shapes'] += len(items)
+        boxes = []          # (shape, rect, ink, kind, z)
+        slide_chars = 0
+        bullet_count = 0
+        slide_title = ''
+
+        for sh, rect, z in items:
+            kind = 'shape'
+            if sh.shape_type == MSO_SHAPE_TYPE.PICTURE:
+                kind = 'pic'
+                stats['pictures'] += 1
+            elif getattr(sh, 'has_table', False):
+                kind = 'table'
+                stats['tables'] += 1
+            elif getattr(sh, 'has_chart', False):
+                kind = 'chart'
+                stats['charts'] += 1
+            elif sh.has_text_frame and sh.text_frame.text.strip():
+                kind = 'text'
+                stats['texts'] += 1
+
+            label = _label(sh, kind)
+            arect = _rot_aabb(rect, getattr(sh, 'rotation', 0))
+
+            # ① 越界 / 贴边
+            if arect.w > 0.02 and arect.h > 0.02:
+                out_l = max(0.0, page.x - arect.x)
+                out_t = max(0.0, page.y - arect.y)
+                out_r = max(0.0, arect.right - page.right)
+                out_b = max(0.0, arect.bottom - page.bottom)
+                worst = max(out_l, out_t, out_r, out_b)
+                full_bleed = kind not in ('text', 'table') and arect.w >= sw * 0.98 and arect.h >= sh_in * 0.98
+                if worst > 0.02 and not full_bleed:
+                    findings.append(Finding(
+                        pno, 'out_of_slide', 'error' if worst > 0.12 or kind in ('text', 'table') else 'warn',
+                        f'{label} 超出页面 {worst:.2f}"（'
+                        + '、'.join(x for x in [
+                            f'左溢 {out_l:.2f}"' if out_l > 0.02 else '',
+                            f'上溢 {out_t:.2f}"' if out_t > 0.02 else '',
+                            f'右溢 {out_r:.2f}"' if out_r > 0.02 else '',
+                            f'下溢 {out_b:.2f}"' if out_b > 0.02 else '',
+                        ] if x) + '）',
+                        '把元素移回页内，或等比缩小', label, rect))
+                elif worst <= 0.02 and kind in ('text', 'pic', 'table', 'chart'):
+                    near = min(arect.x - page.x, arect.y - page.y, page.right - arect.right, page.bottom - arect.bottom)
+                    if near < SAFE_MARGIN and arect.w < sw * 0.98:
+                        findings.append(Finding(
+                            pno, 'off_grid', 'warn',
+                            f'{label} 距页边仅 {max(0.0, near):.2f}"（安全边距 {SAFE_MARGIN}"）',
+                            '往内收，四边留白一致才显整齐', label, rect))
+                # 细长条是分隔线/色带（设计件），只有两边都小才是误建的碎片
+                if (arect.w < 0.08 and arect.h < 0.08) or (kind in ('text', 'pic', 'table', 'chart')
+                                                           and (arect.w < 0.12 or arect.h < 0.1)):
+                    findings.append(Finding(pno, 'tiny_shape', 'warn',
+                                            f'{label} 尺寸仅 {arect.w:.2f}"×{arect.h:.2f}"，几乎不可见',
+                                            '删掉或给足尺寸', label, rect, fixable=False))
+
+            # ② 图片变形 / 发虚
+            if kind == 'pic':
+                findings.extend(_check_picture(pno, sh, rect, label))
+
+            # ③ 文字度量
+            ink = rect
+            if kind == 'text':
+                ink = ink_box(sh, rect)
+                findings.extend(_check_text(pno, sh, rect, ink, label, theme, boxes, page, strict))
+                txt = sh.text_frame.text
+                slide_chars += len(txt.replace('\n', ''))
+                stats['chars'] += len(txt.replace('\n', ''))
+                bullet_count += _bullet_paras(sh, rect, sh_in)
+                for p in sh.text_frame.paragraphs:
+                    for r in p.runs:
+                        if r.font.name:
+                            fonts.add(r.font.name)
+                if not slide_title and _is_title(sh, rect, page):
+                    slide_title = txt.strip().split('\n')[0]
+                    # 满版底色的页（封面/章节页/结尾页）本来就是另一种构图，
+                    # 把它们的标题拉进"各页标题该对齐"的比对里只会误报
+                    if not _full_bleed_page(items, page):
+                        title_tops.append((pno, round(rect.y, 3)))
+
+            # ④ 表格
+            if kind == 'table':
+                findings.extend(_check_table(pno, sh, rect, page, label))
+
+            f = _fill_hex(sh, theme)
+            if f:
+                fills.add(f)
+            boxes.append((sh, rect, ink, kind, z, label))
+
+        # ⑤ 重叠（页内两两比对，用 ink 而非框）
+        findings.extend(_check_overlap(pno, boxes))
+
+        # ⑥ 内容密度
+        content = [b for b in boxes if b[3] in ('text', 'pic', 'table', 'chart')]
+        if not content:
+            findings.append(Finding(pno, 'empty_slide', 'warn', '整页没有任何正文/图/表', '补内容或删页'))
+        if bullet_count > MAX_BULLETS + 1:
+            findings.append(Finding(pno, 'bullet_overload', 'warn',
+                                    f'本页 {bullet_count} 个段落/要点（建议 ≤{MAX_BULLETS}）',
+                                    '一页一个观点，多的拆页或进备注'))
+        if slide_chars > MAX_SLIDE_CHARS:
+            findings.append(Finding(pno, 'text_wall', 'warn',
+                                    f'本页正文 {slide_chars} 字（建议 ≤{MAX_SLIDE_CHARS}）',
+                                    'PPT 不是文档：留结论进正文，论证进备注'))
+        if slide_title:
+            titles.append((pno, slide_title))
+            if len(slide_title) > MAX_TITLE_CHARS:
+                findings.append(Finding(pno, 'title_too_long', 'warn',
+                                        f'标题 {len(slide_title)} 字：{slide_title[:30]}…',
+                                        f'压到 {MAX_TITLE_CHARS} 字内，长的挪到副标题'))
+
+    # ⑦ 跨页一致性
+    findings.extend(_check_consistency(titles, title_tops, fonts, fills, sw, sh_in))
+
+    order = sorted(findings, key=lambda f: (LEVEL_ORDER.get(f['level'], 3), f['page']))
+    return dict(
+        ok=not any(f['level'] == 'error' for f in order),
+        path=os.path.abspath(path),
+        slides=len(prs.slides),
+        size=f'{sw:.2f}"×{sh_in:.2f}"',
+        ratio=_ratio(sw, sh_in),
+        findings=order,
+        stats=stats,
+        counts={k: sum(1 for f in order if f['level'] == k) for k in ('error', 'warn', 'info')},
+    )
+
+
+def _ratio(w, h):
+    r = w / h if h else 0
+    for name, v in (('16:9', 16 / 9), ('4:3', 4 / 3), ('16:10', 16 / 10), ('A4横', 297 / 210)):
+        if abs(r - v) < 0.02:
+            return name
+    return f'{r:.2f}:1'
+
+
+def _label(sh, kind):
+    n = (sh.name or '').strip()
+    base = {'pic': '图片', 'table': '表格', 'chart': '图表', 'text': '文本', 'shape': '形状'}[kind]
+    if kind == 'text':
+        t = sh.text_frame.text.strip().split('\n')[0][:12]
+        return f'「{t}」' if t else base
+    return f'{base}({n[:16]})' if n and not n.startswith(('TextBox', 'Rectangle')) else base
+
+
+def _is_title(sh, rect, page):
+    try:
+        if sh.is_placeholder and sh.placeholder_format.idx == 0:
+            return True
+    except Exception:
+        pass
+    if rect.y > page.h * 0.22:
+        return False
+    for p in sh.text_frame.paragraphs:
+        for r in p.runs:
+            if r.font.size and r.font.size.pt >= 24:
+                return True
+    return False
+
+
+def _full_bleed_page(items, page):
+    """整页铺底的构图（封面/章节/结尾）。"""
+    for sh, r, _z in items:
+        if r.w >= page.w * 0.95 and r.h >= page.h * 0.95 and sh.shape_type != MSO_SHAPE_TYPE.PICTURE:
+            try:
+                if sh.fill.type is not None and 'BACKGROUND' not in str(sh.fill.type):
+                    return True
+            except Exception:
+                continue
+    return False
+
+
+def _check_picture(pno, sh, rect, label):
+    out = []
+    try:
+        img = sh.image
+        nw, nh = img.size
+    except Exception:
+        return out
+    # 裁剪后的有效原始比例
+    cl = getattr(sh, 'crop_left', 0) or 0
+    cr = getattr(sh, 'crop_right', 0) or 0
+    ct = getattr(sh, 'crop_top', 0) or 0
+    cb = getattr(sh, 'crop_bottom', 0) or 0
+    ew = nw * max(0.01, 1 - cl - cr)
+    eh = nh * max(0.01, 1 - ct - cb)
+    if ew <= 0 or eh <= 0 or rect.w <= 0 or rect.h <= 0:
+        return out
+    nat = ew / eh
+    cur = rect.w / rect.h
+    dev = abs(cur / nat - 1)
+    if dev > DISTORT_WARN:
+        want_h = rect.w / nat
+        out.append(Finding(
+            pno, 'image_distort', 'error' if dev > DISTORT_ERR else 'warn',
+            f'{label} 被{"拉宽" if cur > nat else "压扁"} {dev * 100:.0f}%'
+            f'（当前 {cur:.2f}:1，原图 {nat:.2f}:1）',
+            f'保持原比例：宽 {rect.w:.2f}" 时高应为 {want_h:.2f}"（或只给 width/height 之一）',
+            label, rect))
+    dpi_x = ew / rect.w if rect.w else 999
+    dpi_y = eh / rect.h if rect.h else 999
+    dpi = min(dpi_x, dpi_y)
+    if dpi < MIN_DPI:
+        out.append(Finding(pno, 'image_blurry', 'warn',
+                           f'{label} 渲染分辨率仅 {dpi:.0f} dpi（原图 {int(ew)}×{int(eh)}px，占 {rect.w:.2f}"×{rect.h:.2f}"）',
+                           '换高分辨率原图，或缩小显示尺寸', label, rect))
+    return out
+
+
+def _check_text(pno, sh, rect, ink, label, theme, prior, page, strict):
+    out = []
+    tf = sh.text_frame
+    total, max_w, avail_w, avail_h, detail = para_lines(sh, rect, tf)
+    scale, _ = _autofit(tf)
+
+    # 纵向溢出。两种结局要分开判：
+    #   · 普通框 → 文字被切掉（下半截看不见）；
+    #   · spAutoFit 框（python-pptx add_textbox 的默认！）→ 框自己长高，
+    #     不切字但会一路顶下去，超过页底就是纸面外，比切字更难发现。
+    if avail_h > 0 and total > avail_h * L.TOL:
+        over = total / avail_h - 1
+        auto_grow = False
+        try:
+            auto_grow = tf.auto_size == MSO_AUTO_SIZE.SHAPE_TO_FIT_TEXT
+        except Exception:
+            pass
+        need_h = (total + 2 * _insets(tf)[1]) / L.PT_IN
+        grown_bottom = rect.y + need_h
+        if auto_grow:
+            spill = grown_bottom - page.bottom
+            lvl = 'error' if spill > 0.02 else 'warn'
+            why = (f'；框是「随文字增高」，会一路长到 y={grown_bottom:.2f}"，'
+                   f'{"顶出页底 %.2f\"（这部分永远看不到）" % spill if spill > 0.02 else "把下方元素挤开"}')
+        else:
+            lvl = 'error' if over >= 0.12 else 'warn'
+            why = '；超出部分会被直接切掉'
+        out.append(Finding(
+            pno, 'overflow_v', lvl,
+            f'{label} 文字装不下：估算需 {need_h:.2f}"，框高仅 {rect.h:.2f}"（超 {over * 100:.0f}%，共 {sum(d["lines"] for d in detail)} 行）' + why,
+            '减少内容 / 拆页 / 调小字号 / 加高文本框（pptx_check --fix 可自动缩字或加高）', label, rect))
+    if scale < 0.92:
+        out.append(Finding(pno, 'autofit_shrunk', 'warn',
+                           f'{label} 被 PowerPoint 自动缩到原字号的 {scale * 100:.0f}%（说明内容本来就塞不下）',
+                           '内容拆页，别靠自动缩字硬塞', label, rect))
+    # 横向超宽（关了自动换行时）
+    if not _word_wrap(tf) and max_w > avail_w * L.TOL:
+        out.append(Finding(pno, 'overflow_h', 'error',
+                           f'{label} 关闭了自动换行且单行宽 {max_w / L.PT_IN:.2f}" > 可用 {avail_w / L.PT_IN:.2f}"',
+                           '打开 word_wrap 或加宽文本框', label, rect))
+
+    # 字号 / 东亚字体 / 对比度
+    bg = _bg_under(ink, prior) or 'FFFFFF'
+    seen_small = False
+    for p in tf.paragraphs:
+        for r in p.runs:
+            if not r.text.strip():
+                continue
+            size = _run_size(r, p, sh) * scale
+            if size < FONT_ERR and not seen_small:
+                seen_small = True
+                out.append(Finding(pno, 'font_too_small', 'error',
+                                   f'{label} 出现 {size:.0f}pt 文字（投影/远看不清）',
+                                   f'正文不低于 {FONT_WARN:.0f}pt，注释不低于 12pt', label, rect))
+            elif size < FONT_WARN and not seen_small and strict:
+                seen_small = True
+                out.append(Finding(pno, 'font_too_small', 'warn',
+                                   f'{label} 出现 {size:.0f}pt 文字', f'建议 ≥{FONT_WARN:.0f}pt', label, rect))
+            if _has_cjk(r.text) and r.font.name and not _has_ea(r):
+                out.append(Finding(pno, 'no_ea_font', 'warn',
+                                   f'{label} 中文未设东亚字体（只设了 {r.font.name}）',
+                                   '同时设 <a:ea typeface>，否则中文回退到别的字体、实际行宽与预期不符', label, rect))
+            fg = _color_hex(r.font.color, theme)
+            c = L.contrast(L.hex_rgb(fg), L.hex_rgb(bg)) if fg else None
+            if c is not None:
+                lim = CONTRAST_ERR if size >= 24 else CONTRAST_WARN
+                if c < lim:
+                    out.append(Finding(pno, 'low_contrast', 'error' if c < CONTRAST_ERR else 'warn',
+                                       f'{label} 文字 #{fg} 压在 #{bg} 上，对比度仅 {c:.1f}:1（需 ≥{lim}）',
+                                       f'改用 #{L.readable_on(bg)} 一类的可读色', label, rect))
+                    break
+        else:
+            continue
+        break
+
+    # 要点过长
+    for d in detail:
+        t = d['text'].strip().lstrip('•·-—　 ')
+        if len(t) > MAX_BULLET_CHARS and d['size'] < 28:
+            out.append(Finding(pno, 'bullet_too_long', 'warn',
+                               f'要点 {len(t)} 字：{t[:24]}…',
+                               f'一条要点压到 {MAX_BULLET_CHARS} 字内，展开的话进备注', label, rect))
+            break
+    return out
+
+
+def _bullet_paras(sh, rect, page_h):
+    """这个文本框算几条要点。
+
+    只认"真正的要点列表"：同一个框里 ≥2 段有内容的正文。页码、页脚、KPI 卡片标签
+    都是单段短文本，把它们数进来会让"本页 15 个要点"这种告警天天误报，
+    而一个天天误报的检查等于没有检查。
+    """
+    if rect.y > page_h - 0.62:                      # 页脚带
+        return 0
+    paras = [p for p in sh.text_frame.paragraphs if p.text.strip()]
+    if len(paras) < 2:
+        return 0
+    sizes = [r.font.size.pt for p in paras for r in p.runs if r.font.size]
+    if sizes and max(sizes) < 12:                   # 注释/脚注一类的小字块
+        return 0
+    return len(paras)
+
+
+def _has_cjk(s):
+    return any(0x2E80 <= ord(c) <= 0x9FFF or 0xF900 <= ord(c) <= 0xFAFF for c in s)
+
+
+def _has_ea(run):
+    try:
+        rPr = run._r.find(qn('a:rPr'))
+        return rPr is not None and rPr.find(qn('a:ea')) is not None
+    except Exception:
+        return False
+
+
+def _bg_under(ink, prior):
+    """ink 底下最靠上的一块纯色填充（z 序更小者在下）；找不到返回 None。"""
+    best = None
+    for sh, rect, _ink, kind, z, _label in prior:
+        if kind == 'pic':
+            continue
+        if rect.contains(ink, 0.02) or rect.overlap_ratio(ink) > 0.6:
+            f = _fill_hex(sh, {})
+            if f:
+                best = f
+    return best
+
+
+def _check_table(pno, sh, rect, page, label):
+    out = []
+    try:
+        tbl = sh.table
+    except Exception:
+        return out
+    cols = [c.width / L.EMU_IN for c in tbl.columns]
+    heights = _table_need(tbl, cols)                       # 与 _fix_table 同一把尺
+    need_h = sum(max(h, (row.height / L.EMU_IN) if row.height else 0) for h, row in zip(heights, tbl.rows))
+    for ri, row in enumerate(tbl.rows):
+        for ci, cell in enumerate(row.cells):
+            if ci >= len(cols) or not cell.text.strip():
+                continue
+            sizes = [r.font.size.pt for p in cell.text_frame.paragraphs for r in p.runs if r.font.size]
+            size = max(sizes) if sizes else 14.0
+            ml = cell.margin_left / L.EMU_PT if cell.margin_left is not None else 7.2
+            mr = cell.margin_right / L.EMU_PT if cell.margin_right is not None else 7.2
+            w = max(10.0, cols[ci] * L.PT_IN - ml - mr)
+            lines = L.wrap_segments([(cell.text, size, False)], w)
+            if len(lines) > 2 and size >= 12:
+                out.append(Finding(pno, 'table_overflow', 'warn',
+                                   f'{label} 第{ri + 1}行第{ci + 1}列「{cell.text[:14]}」要折 {len(lines)} 行',
+                                   '加宽该列、缩短文案或减小表格字号', label, rect, fixable=False))
+    if rect.y + need_h > page.bottom + 0.02:
+        out.append(Finding(pno, 'table_overflow', 'error',
+                           f'{label} 实际需高 {need_h:.2f}"，从 y={rect.y:.2f}" 起会顶出页面（页高 {page.h:.2f}"）',
+                           f'行数减到 {max(2, int((page.bottom - rect.y) / max(0.28, need_h / max(1, len(tbl.rows)))))} 行以内，或分两页', label, rect))
+    if len(tbl.rows) > 12:
+        out.append(Finding(pno, 'table_overflow', 'warn',
+                           f'{label} 共 {len(tbl.rows)} 行，投影上看不清',
+                           '摘要上页、明细另附 xlsx 并在页脚注明', label, rect, fixable=False))
+    return out
+
+
+# 装饰性形状：无文字的纯色块（卡片底/色条），与其它元素重叠是设计而非缺陷
+def _is_decor(kind, sh):
+    if kind != 'shape':
+        return False
+    try:
+        return not (sh.has_text_frame and sh.text_frame.text.strip())
+    except Exception:
+        return True
+
+
+def _check_overlap(pno, boxes):
+    out = []
+    n = len(boxes)
+    for i in range(n):
+        sh_a, rect_a, ink_a, kind_a, z_a, lab_a = boxes[i]
+        if kind_a not in ('text', 'pic', 'table', 'chart'):
+            continue
+        for j in range(i + 1, n):
+            sh_b, rect_b, ink_b, kind_b, z_b, lab_b = boxes[j]
+            if kind_b not in ('text', 'pic', 'table', 'chart'):
+                continue
+            a = _rot_aabb(ink_a, getattr(sh_a, 'rotation', 0))
+            b = _rot_aabb(ink_b, getattr(sh_b, 'rotation', 0))
+            ratio = a.overlap_ratio(b)
+            if ratio <= OVERLAP_MIN:
+                continue
+            # 文字压在图/图表上：只有当上层是图（把字盖住）才算问题；字在图上是常见设计
+            if {kind_a, kind_b} == {'text', 'pic'} or {kind_a, kind_b} == {'text', 'chart'}:
+                txt_i = (kind_a == 'text')
+                z_txt, z_img = (z_a, z_b) if txt_i else (z_b, z_a)
+                lab_txt, lab_img = (lab_a, lab_b) if txt_i else (lab_b, lab_a)
+                if z_img > z_txt and ratio > 0.12:
+                    out.append(Finding(pno, 'overlap', 'error',
+                                       f'{lab_img} 盖住了 {lab_txt}（压住 {ratio * 100:.0f}%，图在文字上层）',
+                                       '把图移开或置于底层', lab_txt, a.intersect(b)))
+                continue
+            lvl = 'error' if ratio > 0.12 else 'warn'
+            out.append(Finding(pno, 'overlap', lvl,
+                               f'{lab_a} 与 {lab_b} 重叠 {ratio * 100:.0f}%'
+                               f'（相交区 {a.intersect(b).w:.2f}"×{a.intersect(b).h:.2f}"）',
+                               '错开位置或缩小其一；同一行的多块内容用等分栅格排', f'{lab_a}/{lab_b}',
+                               a.intersect(b)))
+    return out
+
+
+def _check_consistency(titles, title_tops, fonts, fills, sw, sh_in):
+    out = []
+    if len(title_tops) >= 3:
+        ys = [y for _, y in title_tops]
+        lo, hi = min(ys), max(ys)
+        if hi - lo > TITLE_JITTER:
+            worst = max(title_tops, key=lambda t: abs(t[1] - sorted(ys)[len(ys) // 2]))
+            out.append(Finding(worst[0], 'title_jitter', 'warn',
+                               f'各页标题上边距在 {lo:.2f}"~{hi:.2f}" 之间跳动（第 {worst[0]} 页 {worst[1]:.2f}"）',
+                               '所有内容页标题用同一 y 坐标，翻页时标题不该乱动'))
+    if len(fonts) > 3:
+        out.append(Finding(0, 'font_zoo', 'warn', f'全篇用了 {len(fonts)} 种字体：{"、".join(sorted(fonts)[:6])}',
+                           '一套 PPT 两种字体足够（标题一种、正文一种）'))
+    if len(fills) > 10:
+        out.append(Finding(0, 'palette_zoo', 'info', f'全篇出现 {len(fills)} 种填充色',
+                           '收敛到一套主题色（主色/强调/浅底/中性）'))
+    seen = {}
+    for pno, t in titles:
+        seen.setdefault(t, []).append(pno)
+    for t, pages in seen.items():
+        if len(pages) > 1 and len(t) > 2:
+            out.append(Finding(pages[1], 'dup_title', 'info',
+                               f'第 {"、".join(map(str, pages))} 页标题都是「{t[:16]}」',
+                               '续页标题加「（续）」，或换成各页真正的结论'))
+    r = sw / sh_in if sh_in else 0
+    if abs(r - 16 / 9) > 0.02:
+        out.append(Finding(0, 'size_odd', 'info', f'页面比例 {_ratio(sw, sh_in)}（{sw:.2f}"×{sh_in:.2f}"）',
+                           '现在的投影/电视几乎都是 16:9；4:3 会两侧留黑边'))
+    return out
+
+
+# ── 报告 ────────────────────────────────────────────────────────────────────
+def report(res, max_per_code=4, max_lines=60):
+    """把体检结果写成给人/给模型看的紧凑报告。"""
+    c = res['counts']
+    head = (f'【版式体检】{os.path.basename(res["path"])} · {res["slides"]} 页 · {res["ratio"]} '
+            f'· 必修 {c["error"]} / 建议 {c["warn"]} / 提示 {c["info"]}')
+    if not res['findings']:
+        return head + '\n✓ 未发现溢出、重叠、变形、越界等版式问题。'
+    lines = [head]
+    shown = 0
+    for lvl in ('error', 'warn', 'info'):
+        group = [f for f in res['findings'] if f['level'] == lvl]
+        if not group:
+            continue
+        lines.append(f'\n{LEVEL_CN[lvl]}（{len(group)}）')
+        per = {}
+        for f in group:
+            per.setdefault(f['code'], []).append(f)
+        for code, fs in per.items():
+            for f in fs[:max_per_code]:
+                loc = f'p{f["page"]}' if f['page'] else '全篇'
+                lines.append(f'  {loc} {f["name"]}  {f["detail"]}')
+                if f['hint']:
+                    lines.append(f'        → {f["hint"]}')
+                shown += 1
+                if shown >= max_lines:
+                    break
+            if len(fs) > max_per_code:
+                rest = fs[max_per_code:]
+                lines.append(f'        （同类还有 {len(rest)} 处：{"、".join("p" + str(x["page"]) for x in rest[:12])}）')
+            if shown >= max_lines:
+                lines.append('  …（更多问题已省略，修完上面这些再跑一次）')
+                break
+        if shown >= max_lines:
+            break
+    fixable = sorted({f['code'] for f in res['findings'] if f.get('fixable')})
+    if fixable:
+        lines.append(f'\n可自动修复：{"、".join(CODE_CN[x] for x in fixable)} '
+                     f'→ fix("{os.path.basename(res["path"])}")；其余需改内容/版式后重新生成。')
+    return '\n'.join(lines)
+
+
+# ── 自动修复 ────────────────────────────────────────────────────────────────
+def fix(path, out=None, inplace=False, font_floor=14.0):
+    """自动修可安全修的问题（默认另存，绝不覆盖原件）。
+
+    只做**确定性且不改内容**的修复：
+      · 图片变形 → 按原图比例等比重排（在原框内居中）
+      · 超出页面 / 贴边 → 移回页内，过大的等比缩小
+      · 文字溢出 → 先在 [font_floor, 原字号] 内逐级缩字；仍不够则在页内向下加高；
+                   还不够则打开「自动缩排」兜底，并如实报出"建议拆页"
+    绝不删除任何元素、绝不改文案——那是人的决定。
+    """
+    prs = Presentation(path)
+    sw, sh_in = _in(prs.slide_width), _in(prs.slide_height)
+    page = L.Rect(0, 0, sw, sh_in)
+    changes = []
+    still = []
+
+    for pno, slide in enumerate(prs.slides, 1):
+        items = walk(slide)
+        for sh, rect, z in items:
+            # 图片变形
+            if sh.shape_type == MSO_SHAPE_TYPE.PICTURE:
+                try:
+                    nw, nh = sh.image.size
+                    cl = (sh.crop_left or 0) + (sh.crop_right or 0)
+                    ct = (sh.crop_top or 0) + (sh.crop_bottom or 0)
+                    nat = (nw * max(0.01, 1 - cl)) / (nh * max(0.01, 1 - ct))
+                    cur = rect.w / rect.h if rect.h else nat
+                    if abs(cur / nat - 1) > DISTORT_WARN:
+                        box = L.contain_fit(nat, 1.0, rect)
+                        sh.left, sh.top = Emu(int(box.x * L.EMU_IN)), Emu(int(box.y * L.EMU_IN))
+                        sh.width, sh.height = Emu(int(box.w * L.EMU_IN)), Emu(int(box.h * L.EMU_IN))
+                        changes.append(f'p{pno} 图片恢复原比例 {nat:.2f}:1（{rect.w:.2f}×{rect.h:.2f} → {box.w:.2f}×{box.h:.2f}"）')
+                        rect = box
+                except Exception:
+                    pass
+
+            # 越界：先等比缩到页内，再平移回来
+            r = L.Rect(rect.x, rect.y, rect.w, rect.h)
+            full_bleed = r.w >= sw * 0.98 and r.h >= sh_in * 0.98
+            if not full_bleed and (r.x < -0.02 or r.y < -0.02 or r.right > page.right + 0.02 or r.bottom > page.bottom + 0.02):
+                m = SAFE_MARGIN
+                inner = L.Rect(m, m, sw - 2 * m, sh_in - 2 * m)
+                s = min(1.0, inner.w / r.w if r.w else 1, inner.h / r.h if r.h else 1)
+                nw_, nh_ = r.w * s, r.h * s
+                nx = min(max(r.x, m), max(m, sw - m - nw_))
+                ny = min(max(r.y, m), max(m, sh_in - m - nh_))
+                sh.left, sh.top = Emu(int(nx * L.EMU_IN)), Emu(int(ny * L.EMU_IN))
+                if s < 1.0:
+                    sh.width, sh.height = Emu(int(nw_ * L.EMU_IN)), Emu(int(nh_ * L.EMU_IN))
+                changes.append(f'p{pno} {_label(sh, _kind_of(sh))} 移回页内'
+                               + (f'并缩到 {s * 100:.0f}%' if s < 1 else ''))
+                rect = L.Rect(nx, ny, nw_, nh_)
+
+            # 表格顶出页面：缩字 + 收边距 + 回写行高
+            if getattr(sh, 'has_table', False):
+                r3 = _fix_table(pno, sh, rect, page, changes)
+                if r3:
+                    still.append(r3)
+                continue
+
+            # 文字溢出：缩字 → 加高 → 自动缩排
+            if sh.has_text_frame and sh.text_frame.text.strip():
+                r2 = _fix_overflow(pno, sh, rect, page, font_floor, changes)
+                if r2:
+                    still.append(r2)
+
+    dst = path if inplace else (out or _sibling(path, '-已修复'))
+    prs.save(dst)
+    return dict(saved=dst, changed=changes, unresolved=still)
+
+
+def _fix_overflow(pno, sh, rect, page, floor, changes):
+    tf = sh.text_frame
+    total, max_w, avail_w, avail_h, _ = para_lines(sh, rect, tf)
+    if avail_h <= 0 or total <= avail_h * L.TOL:
+        return None
+    sizes = [(p, r, _run_size(r, p, sh)) for p in tf.paragraphs for r in p.runs if r.text.strip()]
+    if not sizes:
+        return None
+    base = max(s for _, _, s in sizes)
+    # ① 逐级缩字（等比缩所有 run，保持字号层级）
+    k = 1.0
+    while k > 0.55:
+        k -= 0.05
+        if base * k < floor:
+            break
+        for p, r, s0 in sizes:
+            r.font.size = Pt(round(s0 * k, 1))
+        total, _, _, avail_h, _ = para_lines(sh, rect, tf)
+        if total <= avail_h:
+            changes.append(f'p{pno} {_label(sh, "text")} 字号缩到 {k * 100:.0f}%（{base:.0f}→{base * k:.0f}pt）以消除溢出')
+            return None
+    for p, r, s0 in sizes:                      # 缩不动就还原，改走加高
+        r.font.size = Pt(s0)
+    # ② 页内向下加高
+    total, _, _, avail_h, _ = para_lines(sh, rect, tf)
+    need = total / L.PT_IN + 2 * L.INSET_TB / L.PT_IN
+    room = page.bottom - SAFE_MARGIN - rect.y
+    if need <= room:
+        sh.height = Emu(int(need * L.EMU_IN))
+        changes.append(f'p{pno} {_label(sh, "text")} 文本框加高到 {need:.2f}"（原 {rect.h:.2f}"）')
+        return None
+    # ③ 兜底：打开自动缩排，并如实报出该拆页
+    try:
+        tf.word_wrap = True
+        tf.auto_size = MSO_AUTO_SIZE.TEXT_TO_FIT_SHAPE
+        changes.append(f'p{pno} {_label(sh, "text")} 已打开「自动缩排」兜底')
+    except Exception:
+        pass
+    return (f'p{pno} {_label(sh, "text")} 内容确实太多（需 {need:.2f}"，页内最多 {room:.2f}"）：'
+            '已开自动缩排避免溢出，但正确做法是拆成两页或把细节挪进备注')
+
+
+def _kind_of(sh):
+    if sh.shape_type == MSO_SHAPE_TYPE.PICTURE:
+        return 'pic'
+    if getattr(sh, 'has_table', False):
+        return 'table'
+    if getattr(sh, 'has_chart', False):
+        return 'chart'
+    try:
+        if sh.has_text_frame and sh.text_frame.text.strip():
+            return 'text'
+    except Exception:
+        pass
+    return 'shape'
+
+
+def _table_need(tbl, cols):
+    """按单元格实际折行算出每行需要的高度（英寸）。"""
+    heights = []
+    for row in tbl.rows:
+        need = 0.22
+        for ci, cell in enumerate(row.cells):
+            if ci >= len(cols) or not cell.text.strip():
+                continue
+            sizes = [r.font.size.pt for p in cell.text_frame.paragraphs for r in p.runs if r.font.size]
+            size = max(sizes) if sizes else 14.0
+            ml = cell.margin_left / L.EMU_PT if cell.margin_left is not None else 7.2
+            mr = cell.margin_right / L.EMU_PT if cell.margin_right is not None else 7.2
+            mt = cell.margin_top / L.EMU_PT if cell.margin_top is not None else 3.6
+            mb = cell.margin_bottom / L.EMU_PT if cell.margin_bottom is not None else 3.6
+            w = max(10.0, cols[ci] * L.PT_IN - ml - mr)
+            h = (L.text_height(L.wrap_segments([(cell.text, size, False)], w)) + mt + mb) / L.PT_IN
+            need = max(need, h)
+        heights.append(need)
+    return heights
+
+
+def _fix_table(pno, sh, rect, page, changes):
+    """表格顶出页面：先缩字、再收紧单元格上下边距，最后把算出的行高写回。"""
+    try:
+        tbl = sh.table
+    except Exception:
+        return None
+    cols = [c.width / L.EMU_IN for c in tbl.columns]
+    avail = page.bottom - SAFE_MARGIN - rect.y
+    need = sum(_table_need(tbl, cols))
+    if need <= avail:
+        return None
+    runs = [r for row in tbl.rows for cell in row.cells
+            for p in cell.text_frame.paragraphs for r in p.runs if r.text.strip()]
+    base = max((r.font.size.pt for r in runs if r.font.size), default=14.0)
+    orig = [(r, r.font.size.pt if r.font.size else 14.0) for r in runs]
+    k = 1.0
+    while k > 0.6 and need > avail:
+        k -= 0.05
+        if base * k < 10.0:
+            break
+        for r, s0 in orig:
+            r.font.size = Pt(round(s0 * k, 1))
+        need = sum(_table_need(tbl, cols))
+    if need > avail:                                  # 再收紧上下内边距
+        for row in tbl.rows:
+            for cell in row.cells:
+                cell.margin_top = Pt(1.5)
+                cell.margin_bottom = Pt(1.5)
+        need = sum(_table_need(tbl, cols))
+    hs = _table_need(tbl, cols)
+    if need <= avail:
+        for row, h in zip(tbl.rows, hs):
+            row.height = Emu(int(h * L.EMU_IN))
+        changes.append(f'p{pno} 表格缩到 {k * 100:.0f}% 字号并回写行高，总高 {need:.2f}" 装进可用 {avail:.2f}"')
+        return None
+    for r, s0 in orig:                                # 缩不动就还原，如实报该分页
+        r.font.size = Pt(s0)
+    per = need / max(1, len(tbl.rows))
+    return (f'p{pno} 表格 {len(tbl.rows)} 行需 {need:.2f}"，页内只有 {avail:.2f}"：'
+            f'缩到 10pt 仍装不下，请拆成每页 ≤{max(2, int(avail / per))} 行，或只上摘要、明细另附 xlsx')
+
+
+def _sibling(path, suffix):
+    root, ext = os.path.splitext(path)
+    return root + suffix + ext
+
+
+# ── CLI ─────────────────────────────────────────────────────────────────────
+def main(argv):
+    if not argv or argv[0] in ('-h', '--help'):
+        print(__doc__ or '用法：python pptx_check.py <文件.pptx> [--json] [--fix] [--inplace] [--strict]')
+        return 2
+    path = argv[0]
+    as_json = '--json' in argv
+    do_fix = '--fix' in argv
+    strict = '--strict' in argv
+    if not os.path.exists(path):
+        print(f'文件不存在：{path}')
+        return 1
+    res = inspect(path, strict=strict)
+    if do_fix:
+        fr = fix(path, inplace='--inplace' in argv)
+        res2 = inspect(fr['saved'], strict=strict)
+        if as_json:
+            print(json.dumps(dict(before=res, fixed=fr, after=res2), ensure_ascii=False, indent=1))
+        else:
+            print(report(res))
+            print('\n【自动修复】已改 %d 处 → %s' % (len(fr['changed']), fr['saved']))
+            for c in fr['changed'][:20]:
+                print('  ·', c)
+            for u in fr['unresolved'][:10]:
+                print('  ⚠', u)
+            print('\n' + report(res2))
+        return 0
+    print(json.dumps(res, ensure_ascii=False, indent=1) if as_json else report(res))
+    return 0 if res['ok'] else 1
+
+
+if __name__ == '__main__':
+    sys.exit(main(sys.argv[1:]))