@topmindspace/tms-skills 0.1.0

package/top-ppt-html/scripts/prepare_images.py

@@ -0,0 +1,341 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""TopPPT HTML · 用户图片素材准备
+
+把用户提供的图片处理成**可直接放进报告**的素材：
+  ① 读尺寸/格式/体积（纯标准库解析 PNG/JPEG/GIF/WebP/SVG 头部，无需第三方依赖）；
+  ② 按 imageSpec.recommendedSizePx 检查是否够大（不足会提示，避免放大糊）；
+  ③ 需要时缩放/压缩（检测到 Pillow 才启用，缺失自动跳过并给出建议）；
+  ④ 生成两种落地形态：**data: 内联**（单文件零外链，随报告走）或 **相对路径**（体积大时推荐）；
+  ⑤ 直接产出可粘贴的 HTML 片段与 REPORT_MODEL 的 image 对象片段。
+
+用法:
+    python scripts/prepare_images.py <图片|目录> [更多图片…]
+        [--layout full|half|bleed|grid|compare|wall]   默认 full
+        [--out <目录>]        输出目录（默认当前目录下的 report-assets/）
+        [--mode inline|path]  inline=base64 内联（默认，受体积上限约束）；path=复制到 out 并用相对路径
+        [--max-bytes N]       单图内联上限（默认取 layout-constants.json imageSpec.maxInlineBytes）
+        [--json]              只打印机器可读 JSON
+        [--no-resize]         禁用缩放（即使 Pillow 可用）
+
+产出（写到 --out 目录）:
+    images-snippets.html   HTML 图片片段（.media 族，含占位示例）
+    images-model.json      REPORT_MODEL 的 image 对象片段（可直接并入 sections[]）
+
+依赖：仅标准库；可选 Pillow（有则缩放/压缩，无则原样内联并提示）。
+"""
+from __future__ import annotations
+
+import argparse
+import base64
+import json
+import re
+import shutil
+import sys
+from pathlib import Path
+
+try:
+    sys.stdout.reconfigure(encoding='utf-8', errors='replace')
+    sys.stderr.reconfigure(encoding='utf-8', errors='replace')
+except Exception:
+    pass
+
+ROOT = Path(__file__).resolve().parent.parent
+LC_PATH = Path(__file__).resolve().parent / 'layout-constants.json'
+IMAGE_EXT = {'.png', '.jpg', '.jpeg', '.webp', '.gif', '.svg'}
+MIME = {'.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg',
+        '.webp': 'image/webp', '.gif': 'image/gif', '.svg': 'image/svg+xml'}
+
+
+def load_image_spec() -> dict:
+    try:
+        lc = json.loads(LC_PATH.read_text(encoding='utf-8'))
+        spec = lc.get('imageSpec') or {}
+        return spec if isinstance(spec, dict) else {}
+    except (OSError, json.JSONDecodeError):
+        return {}
+
+
+SPEC = load_image_spec()
+
+
+def ratio_num(spec: str) -> float:
+    """'3:1' → 3.0；非法返回 0。"""
+    m = re.match(r'\s*(\d+(?:\.\d+)?)\s*[:/×x]\s*(\d+(?:\.\d+)?)', str(spec or ''))
+    if not m:
+        return 0.0
+    a, b = float(m.group(1)), float(m.group(2))
+    return a / b if a > 0 and b > 0 else 0.0
+
+
+def target_width(layout: str) -> int:
+    """imageSpec.recommendedSizePx 形如 '2000×1125' → 2000。"""
+    raw = str((SPEC.get('recommendedSizePx') or {}).get(layout) or '2000×1125')
+    m = re.match(r'\s*(\d+)', raw)
+    return int(m.group(1)) if m else 2000
+
+
+def read_size(path: Path) -> tuple[int, int] | None:
+    """纯标准库读位图尺寸（PNG/JPEG/GIF/WebP）；SVG 走文本解析。"""
+    try:
+        data = path.read_bytes()[:65536]
+    except OSError:
+        return None
+    if len(data) < 16:
+        return None
+    # PNG
+    if data[:8] == b'\x89PNG\r\n\x1a\n':
+        return int.from_bytes(data[16:20], 'big'), int.from_bytes(data[20:24], 'big')
+    # GIF
+    if data[:6] in (b'GIF87a', b'GIF89a'):
+        return int.from_bytes(data[6:8], 'little'), int.from_bytes(data[8:10], 'little')
+    # JPEG：扫描 SOF 段
+    if data[:2] == b'\xff\xd8':
+        i = 2
+        while i + 9 < len(data):
+            if data[i] != 0xFF:
+                i += 1
+                continue
+            marker = data[i + 1]
+            if marker in (0xD8, 0x01) or 0xD0 <= marker <= 0xD7:
+                i += 2
+                continue
+            if marker == 0xD9:
+                break
+            seg_len = int.from_bytes(data[i + 2:i + 4], 'big')
+            if 0xC0 <= marker <= 0xCF and marker not in (0xC4, 0xC8, 0xCC):
+                h = int.from_bytes(data[i + 5:i + 7], 'big')
+                w = int.from_bytes(data[i + 7:i + 9], 'big')
+                return w, h
+            i += 2 + max(2, seg_len)
+        return None
+    # WebP
+    if data[:4] == b'RIFF' and data[8:12] == b'WEBP':
+        chunk = data[12:16]
+        if chunk == b'VP8X' and len(data) >= 30:
+            w = int.from_bytes(data[24:27], 'little') + 1
+            h = int.from_bytes(data[27:30], 'little') + 1
+            return w, h
+        if chunk == b'VP8 ' and len(data) >= 30:
+            w = int.from_bytes(data[26:28], 'little') & 0x3FFF
+            h = int.from_bytes(data[28:30], 'little') & 0x3FFF
+            return w, h
+        if chunk == b'VP8L' and len(data) >= 25:
+            bits = int.from_bytes(data[21:25], 'little')
+            return (bits & 0x3FFF) + 1, ((bits >> 14) & 0x3FFF) + 1
+    return None
+
+
+def read_svg_size(path: Path) -> tuple[int, int] | None:
+    try:
+        head = path.read_text(encoding='utf-8', errors='replace')[:2048]
+    except OSError:
+        return None
+    w = re.search(r'width\s*=\s*["\']?\s*(\d+(?:\.\d+)?)', head)
+    h = re.search(r'height\s*=\s*["\']?\s*(\d+(?:\.\d+)?)', head)
+    if w and h:
+        return int(float(w.group(1))), int(float(h.group(1)))
+    vb = re.search(r'viewBox\s*=\s*["\']([\d.\-\s,]+)["\']', head)
+    if vb:
+        nums = re.split(r'[\s,]+', vb.group(1).strip())
+        if len(nums) == 4:
+            return int(float(nums[2])), int(float(nums[3]))
+    return None
+
+
+def ratio_label(w: int, h: int) -> str:
+    if not w or not h:
+        return '未知'
+    from math import gcd
+    g = gcd(w, h) or 1
+    a, b = w // g, h // g
+    if a > 40 or b > 40:
+        return f'{w / h:.2f}:1'
+    return f'{a}:{b}'
+
+
+def try_resize(src: Path, dst: Path, want_w: int) -> bool:
+    """有 Pillow 时缩放/压缩；无则返回 False（调用方回落原图）。"""
+    try:
+        from PIL import Image  # type: ignore
+    except Exception:
+        return False
+    try:
+        with Image.open(src) as im:
+            im.load()
+            w, h = im.size
+            if w > want_w:
+                im = im.resize((want_w, max(1, round(h * want_w / w))), Image.LANCZOS)
+            if dst.suffix.lower() in ('.jpg', '.jpeg'):
+                if im.mode in ('RGBA', 'P', 'LA'):
+                    bg = Image.new('RGB', im.size, (255, 255, 255))
+                    bg.paste(im.convert('RGBA'), mask=im.convert('RGBA').split()[-1])
+                    im = bg
+                else:
+                    im = im.convert('RGB')
+                im.save(dst, 'JPEG', quality=82, optimize=True, progressive=True)
+            else:
+                im.save(dst, optimize=True)
+        return True
+    except Exception:
+        return False
+
+
+def collect_inputs(args_paths: list[str]) -> list[Path]:
+    out: list[Path] = []
+    for raw in args_paths:
+        p = Path(raw)
+        if p.is_dir():
+            out.extend(sorted(q for q in p.rglob('*') if q.suffix.lower() in IMAGE_EXT))
+        elif p.is_file():
+            out.append(p)
+        else:
+            print(f'[跳过] 不存在: {raw}')
+    seen, uniq = set(), []
+    for p in out:
+        if p.resolve() not in seen:
+            seen.add(p.resolve())
+            uniq.append(p)
+    return uniq
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description='TopPPT HTML 用户图片素材准备')
+    ap.add_argument('paths', nargs='+', help='图片文件或目录（可多个）')
+    ap.add_argument('--layout', default='full', choices=list(SPEC.get('layouts') or
+                    ['full', 'half', 'bleed', 'grid', 'compare', 'wall']))
+    ap.add_argument('--out', default=None, help='输出目录（默认 ./report-assets）')
+    ap.add_argument('--mode', default='inline', choices=['inline', 'path'])
+    ap.add_argument('--max-bytes', type=int, default=int(SPEC.get('maxInlineBytes') or 1572864))
+    ap.add_argument('--json', action='store_true')
+    ap.add_argument('--no-resize', action='store_true')
+    args = ap.parse_args()
+
+    files = collect_inputs(args.paths)
+    if not files:
+        print('没有可处理的图片（支持 ' + '/'.join(sorted(e.lstrip(".") for e in IMAGE_EXT)) + '）。')
+        return 2
+
+    out_dir = Path(args.out) if args.out else Path.cwd() / 'report-assets'
+    out_dir.mkdir(parents=True, exist_ok=True)
+    assets_dir = out_dir / 'assets'
+    want_w = target_width(args.layout)
+    max_total = int(SPEC.get('maxTotalInlineBytes') or 8388608)
+
+    rows, html_bits, model_items, notes = [], [], [], []
+    total_inline = 0
+    for src in files:
+        ext = src.suffix.lower()
+        size = read_svg_size(src) if ext == '.svg' else read_size(src)
+        w, h = size if size else (0, 0)
+        work = src
+        resized = False
+        if not args.no_resize and w > want_w and ext != '.svg':
+            cand = out_dir / (src.stem + f'-{want_w}' + ('.jpg' if ext in ('.jpg', '.jpeg') else ext))
+            if try_resize(src, cand, want_w):
+                work, resized = cand, True
+                size = read_size(cand)
+                w, h = size if size else (w, h)
+        nbytes = work.stat().st_size
+        if not resized and w and w < want_w * 0.75:
+            notes.append(f'{src.name}: 宽 {w}px < 建议 {want_w}px（放大易糊；请换更高分辨率原图或改小版式）')
+        want_ratio = ratio_num((SPEC.get('ratioDefault') or {}).get(args.layout) or '')
+        fit_cls = ''
+        if w and h and want_ratio:
+            got = w / h
+            if abs(got - want_ratio) / want_ratio > 0.25:
+                fit_cls = ' media--contain'   # 比例差得多 → HTML 也用 contain，与模型 fit 保持一致
+                notes.append(f'{src.name}: 实际比例 {got:.2f}:1 与 {args.layout} 版式锁定比例 '
+                             f'{want_ratio:.2f}:1 相差较大 → 已按 fit:"contain" 输出（完整显示留白）；'
+                             f'若希望裁切填满请换更贴合比例的版式/素材')
+        if ext == '.svg':
+            notes.append(f'{src.name}: SVG 为矢量（好）；注意外链字体/图片需内联，否则破坏零外链铁律')
+
+        use_path = args.mode == 'path' or nbytes > args.max_bytes
+        if use_path:
+            assets_dir.mkdir(parents=True, exist_ok=True)
+            dst = assets_dir / work.name
+            if work.resolve() != dst.resolve():
+                shutil.copy2(work, dst)
+            url = f'assets/{dst.name}'
+            form = '相对路径'
+        else:
+            b64 = base64.b64encode(work.read_bytes()).decode('ascii')
+            url = f'data:{MIME.get(ext, "image/png")};base64,{b64}'
+            form = 'data: 内联'
+            total_inline += len(url)
+        if nbytes > args.max_bytes and args.mode != 'path':
+            notes.append(f'{src.name}: {nbytes // 1024}KB > 内联上限 {args.max_bytes // 1024}KB → 已改用相对路径')
+
+        rows.append({'file': src.name, 'w': w, 'h': h, 'ratio': ratio_label(w, h),
+                     'kb': nbytes // 1024, 'form': form, 'url': url,
+                     'targetW': want_w, 'resized': resized})
+        lock_cls = (SPEC.get('ratioCssClass') or {}).get(args.layout) or f'media--r{ratio_class(w, h)}'
+        html_bits.append(
+            f'<figure class="media {lock_cls}{fit_cls} rv">\n'
+            f'  <img src="{url if len(url) < 400 else url[:60] + "…（见 images-snippets.html 全文）"}" '
+            f'alt="{src.stem}">\n'
+            f'  <figcaption class="media__cap--below">图：{src.stem}（{w}×{h} · {ratio_label(w, h)}）</figcaption>\n'
+            f'</figure>')
+        model_items.append({'src': url, 'alt': src.stem, 'caption': f'图：{src.stem}'})
+
+    if total_inline > max_total:
+        notes.append(f'内联总量 {total_inline // 1024}KB > 上限 {max_total // 1024}KB：'
+                     '建议部分图片改用 --mode path（相对路径）')
+
+    layout = args.layout
+    if len(model_items) > 1 and layout not in (SPEC.get('multiLayouts') or ['grid', 'compare', 'wall']):
+        notes.append(f'共 {len(model_items)} 张图但 layout={layout}（单图版式）→ 多图请用 grid/compare/wall')
+    want_ratio = ratio_num((SPEC.get('ratioDefault') or {}).get(layout) or '')
+    fit = SPEC.get('fitDefault') or 'cover'
+    if want_ratio and any(r['w'] and r['h'] and abs(r['w'] / r['h'] - want_ratio) / want_ratio > 0.25
+                          for r in rows):
+        fit = 'contain'   # 比例差得多时默认完整显示，避免 cover 切掉关键内容
+    image_model = {'layout': layout, 'fit': fit,
+                   'caption': f'图：{model_items[0]["alt"]}' if model_items else ''}
+    if len(model_items) == 1:
+        image_model['src'] = model_items[0]['src']
+        image_model['alt'] = model_items[0]['alt']
+    else:
+        image_model['items'] = model_items
+
+    (out_dir / 'images-snippets.html').write_text('\n\n'.join(html_bits), encoding='utf-8')
+    (out_dir / 'images-model.json').write_text(
+        json.dumps(image_model, ensure_ascii=False, indent=2), encoding='utf-8')
+
+    if args.json:
+        print(json.dumps({'layout': layout, 'out': str(out_dir), 'images': rows, 'notes': notes},
+                         ensure_ascii=False, indent=2))
+        return 0
+
+    print(f'图片素材准备 · layout={layout} · 建议宽 {want_w}px · 共 {len(rows)} 张')
+    print(f'{"文件":<28}{"尺寸":<14}{"比例":<10}{"体积":<10}形态')
+    for r in rows:
+        dim = f'{r["w"]}×{r["h"]}' if r['w'] else '未知'
+        print(f'{r["file"][:26]:<28}{dim:<14}{r["ratio"]:<10}{str(r["kb"]) + "KB":<10}{r["form"]}'
+              + ('（已缩放）' if r['resized'] else ''))
+    if notes:
+        print('\n提示:')
+        for n in notes:
+            print('  · ' + n)
+    print(f'\n已写出:\n  {out_dir / "images-snippets.html"}  （HTML .media 片段，粘进对应 section.band）')
+    print(f'  {out_dir / "images-model.json"}      （REPORT_MODEL 的 image 对象，并入 sections[]）')
+    if args.mode == 'inline':
+        print('  说明: 内联形态保持「单文件零外链」；体积大时改用 --mode path 并把 assets/ 目录随报告一起交付。')
+    print('  占位: 暂无图时先在模型写 image.placeholder=true（正文用 .media--ph），交付前替换 src 即可。')
+    return 0
+
+
+def ratio_class(w: int, h: int) -> str:
+    """把实际比例归一到 .media--r* 锁定类（16-9 / 4-3 / 3-2 / 1-1 / 21-9）。"""
+    if not w or not h:
+        return '16-9'
+    r = w / h
+    for name, val in (('21-9', 21 / 9), ('16-9', 16 / 9), ('3-2', 1.5), ('4-3', 4 / 3), ('1-1', 1.0)):
+        if abs(r - val) / val <= 0.06:
+            return name
+    return '16-9' if r > 1.4 else ('1-1' if r > 0.9 else '4-3')
+
+
+if __name__ == '__main__':
+    sys.exit(main())

package/top-ppt-html/scripts/probe_image_export.py

@@ -0,0 +1,188 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""TopPPT HTML · 素材图片导出探针（维护工具，不进示例矩阵）
+
+为什么单列探针：示例矩阵刻意保持「零图片全原生」基线（`pictures=0`），真实素材图片
+（用户提供的位图）不在示例里长期携带。但图片路径必须被回归覆盖，否则「相对路径解析 /
+pictures 声明式放行 / half·grid 版式几何 / 裁切策略」这类改动会静默退化。
+
+本探针用 assets/ 下已有的主题总览图当素材，构造一个最小模型：
+  · image.layout="half" + fit="contain"（左图右注，完整显示不裁切）
+  · image.layout="grid" + fit="cover"（四图网格，裁切填满）
+然后跑 build_pptx.js → validate_pptx.py --strict --model，断言 0/0 且 pictures == 声明数。
+
+用法:
+    python scripts/probe_image_export.py            # 用内置素材
+    python scripts/probe_image_export.py <图片路径>  # 用指定素材（相对模型目录）
+
+环境：需要 Node + pptxgenjs（自动探测 TOP_PPT_NODE_PATH / NODE_PATH / 常见托管目录）。
+"""
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+try:
+    sys.stdout.reconfigure(encoding='utf-8', errors='replace')
+    sys.stderr.reconfigure(encoding='utf-8', errors='replace')
+except Exception:
+    pass
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from env_probe import find_node, find_node_modules, node_env  # noqa: E402
+
+ROOT = Path(__file__).resolve().parent.parent
+OUT = ROOT / 'dist' / 'probe'
+PY = sys.executable
+
+
+def main() -> int:
+    node, node_path = find_node(), find_node_modules()
+    if not node or not node_path:
+        print('SKIP：未找到 Node / pptxgenjs（本探针为维护工具，可跳过）。')
+        return 0
+
+    assets = ROOT / 'assets'
+    picks = [Path(a) for a in sys.argv[1:]]
+    if not picks:
+        picks = [assets / 'theme-overview.png',
+                 assets / 'theme-overview-presentation.png',
+                 assets / 'theme-overview-research.png',
+                 assets / 'theme-overview-architecture.png']
+    missing = [str(p) for p in picks if not p.exists()]
+    if missing:
+        print(f'错误：素材缺失 {missing}')
+        return 2
+
+    OUT.mkdir(parents=True, exist_ok=True)
+    model_path = OUT / 'image-probe.model.json'
+    pptx_path = OUT / 'image-probe.pptx'
+    # 相对路径以「模型目录」为锚（与 build_pptx.js 的 resolveImagePath 同规则）
+    rel = [os.path.relpath(p, OUT).replace('\\', '/') for p in picks]
+    grid = (rel * 4)[:4]
+
+    model = {
+        "mode": "presentation", "style": "business-blue", "theme": "light",
+        "title": "素材图片导出探针：双通道落地与门禁",
+        "subtitle": "half / grid 版式 · cover / contain 裁切 · 声明式放行",
+        "meta": "维护工具 · 不进示例矩阵",
+        "agenda": [["01", "图版", "半幅与网格"], ["02", "门禁", "声明式放行"]],
+        "sections": [
+            {"type": "image", "eyebrow": "01 · 图版",
+             "title": "半幅图加右栏注解：左图右注的图文互证版式",
+             "lead": "左侧锁定 4:3 素材图，右侧逐条给出读图要点。",
+             "image": {"src": rel[0], "layout": "half", "fit": "contain",
+                       "caption": "图 1：主题总览（contain 完整显示，不裁切）"},
+             "points": [["版式", "左图右注，图宽占版心 56%，右侧逐条注解"],
+                        ["裁切", "contain 完整显示不裁切；cover 裁切填满不留白"],
+                        ["比例", "half 版式锁定 4:3，与 PPTX 几何同源"],
+                        ["占位", "无图时同一几何出原生配图占位，交付前替换 src"]]},
+            {"type": "image", "eyebrow": "01 · 图版",
+             "title": "四图网格：同一套护栏下的四类业务现场互证",
+             "lead": "四张等比例素材并排，图下小图注标明来源场景。",
+             "image": {"layout": "grid", "fit": "cover",
+                       "caption": "图 2–5：四类业务现场（建议 900×675px · 4:3）",
+                       "items": [{"src": grid[0], "caption": "演示模式总览：封面与要点页节奏"},
+                                 {"src": grid[1], "caption": "汇报模式：大数字与图表页对照"},
+                                 {"src": grid[2], "caption": "研究模式：密排证据与 Exhibit 编号"},
+                                 {"src": grid[3], "caption": "架构模式：全幅分层与泳道图"}]}},
+            {"type": "image", "eyebrow": "02 · 门禁",
+             "title": "配图占位：无素材时锁版式，交付前替换 src",
+             "lead": "placeholder 出原生圆角框，pictures 不增。",
+             "image": {"placeholder": True, "layout": "full",
+                       "caption": "占位：建议 2400×800px · 3:1"},
+             "note": "占位不算图片，不触发 PICTURES_* 门禁"},
+        ],
+        "closing": {"title": "探针结束：图片路径与门禁已被覆盖",
+                    "points": [["路径", "相对模型目录解析，跨目录调用不失效"],
+                               ["门禁", "pictures 数不得超过声明数"],
+                               ["回落", "图片不可读时回落原生占位框，不留空洞"]]},
+    }
+    model_path.write_text(json.dumps(model, ensure_ascii=False, indent=2), encoding='utf-8')
+    # 真实位图声明数（half 1 + grid 4）；占位不计入 pictures
+    declared = 1 + len(model['sections'][1]['image']['items'])
+
+    # 第二段：用户素材路径缺失 → build 不中断 + strict 报 IMAGE_SRC_MISSING + pictures 不虚增
+    miss_model = dict(model)
+    miss_model['sections'] = list(model['sections']) + [{
+        "type": "image", "eyebrow": "02 · 门禁",
+        "title": "相对路径缺失时回落占位，不留空洞",
+        "lead": "IMAGE_SRC_MISSING 应回落原生占位框。",
+        "image": {"src": "missing-user-photo.jpg", "layout": "half", "fit": "cover",
+                  "caption": "用户素材（路径应以模型目录为锚）"},
+        "note": "文件缺失回落占位，交付前修正路径",
+    }]
+    miss_model_path = OUT / 'image-probe-missing.model.json'
+    miss_pptx_path = OUT / 'image-probe-missing.pptx'
+    miss_model_path.write_text(json.dumps(miss_model, ensure_ascii=False, indent=2), encoding='utf-8')
+
+    env = node_env(node_path)
+    r = subprocess.run([node, str(ROOT / 'scripts' / 'build_pptx.js'), str(pptx_path),
+                        '--model=' + str(model_path)],
+                       capture_output=True, text=True, encoding='utf-8', env=env)
+    if r.returncode != 0 or not pptx_path.exists():
+        print('[FAIL] build_pptx 失败')
+        print((r.stderr or r.stdout or '')[-900:])
+        return 1
+    print(f'[OK] build_pptx 生成 {pptx_path.name}（声明图片 {declared} 张）')
+
+    r = subprocess.run([PY, str(ROOT / 'scripts' / 'validate_pptx.py'), str(pptx_path),
+                        '--strict', '--model=' + str(model_path)],
+                       capture_output=True, text=True, encoding='utf-8')
+    report = {}
+    try:
+        report = json.loads(r.stdout or '{}')
+    except json.JSONDecodeError:
+        print('[FAIL] 无法解析 validate_pptx 报告')
+        print((r.stdout or '')[-900:])
+        return 1
+    pics = int((report.get('summary') or {}).get('pictures', 0))
+    errors = report.get('errors') or []
+    warnings = report.get('warnings') or []
+    print(f'[{"OK" if r.returncode == 0 else "FAIL"}] strict: '
+          f'{len(errors)} errors / {len(warnings)} warnings · pictures={pics}/{declared}')
+    for e in errors[:6]:
+        print('   E', e.get('code'), str(e.get('message'))[:140])
+    for w in warnings[:6]:
+        print('   W', w.get('code'), str(w.get('message'))[:140])
+    if r.returncode != 0:
+        return 1
+    if pics != declared:
+        print(f'[FAIL] pictures={pics} != 声明数 {declared}（声明式放行门禁失效）')
+        return 1
+
+    # ── 缺失路径探针：build 成功 + strict 抓 IMAGE_SRC_MISSING + pictures 不虚增 ──
+    r = subprocess.run([node, str(ROOT / 'scripts' / 'build_pptx.js'), str(miss_pptx_path),
+                        '--model=' + str(miss_model_path)],
+                       capture_output=True, text=True, encoding='utf-8', env=env)
+    if r.returncode != 0 or not miss_pptx_path.exists():
+        print('[FAIL] 缺失路径模型 build_pptx 应成功回落占位，却中断了')
+        print((r.stderr or r.stdout or '')[-600:])
+        return 1
+    print('[OK] 缺失路径 build 成功（已回落占位框，未中断交付）')
+    r = subprocess.run([PY, str(ROOT / 'scripts' / 'validate_pptx.py'), str(miss_pptx_path),
+                        '--strict', '--model=' + str(miss_model_path)],
+                       capture_output=True, text=True, encoding='utf-8')
+    try:
+        mreport = json.loads(r.stdout or '{}')
+    except json.JSONDecodeError:
+        print('[FAIL] 缺失路径 validate 报告不可解析')
+        return 1
+    mcodes = {(e or {}).get('code') for e in (mreport.get('errors') or [])}
+    mpics = int((mreport.get('summary') or {}).get('pictures', 0))
+    if 'IMAGE_SRC_MISSING' not in mcodes:
+        print(f'[FAIL] 缺失路径应报 IMAGE_SRC_MISSING，实际 errors={mcodes}')
+        return 1
+    if mpics != declared:
+        print(f'[FAIL] 缺失路径 pictures={mpics} != 有效声明 {declared}（缺失 src 不应计入图片数）')
+        return 1
+    print(f'[OK] 缺失路径 strict 抓到 IMAGE_SRC_MISSING · pictures={mpics}/{declared}')
+    print('图片导出探针通过：真实素材按声明数落地、占位不增图、缺失路径回落且被门禁拦下。')
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main())