@topmindspace/tms-skills 0.1.0

package/top-ppt-html/scripts/lib_layout_regions.js

@@ -0,0 +1,412 @@
+/**
+ * TopPPT HTML · 页型布局区域 IR（双通道几何收敛起点）
+ *
+ * 从 layout-constants.json + layout_slots.json 派生「语义槽位 → 英寸矩形」。
+ * B 通道（build_pptx.js）直接 require；A 通道消费同一 LC 常量（数字同源），
+ * 本模块是把「槽位语义」从散落坐标收拢成可测接口的第一步。
+ *
+ * 纪律：改几何只改 layout-constants.json；改槽位只改 layout_slots.json。
+ * 新增页型先扩 layout_slots.json，再在此补 regionOf 分支，最后写双引擎。
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.join(__dirname, '..');
+const LC = JSON.parse(fs.readFileSync(path.join(__dirname, 'layout-constants.json'), 'utf8'));
+// 布局 IR：优先 layout-constants.layoutSlots（v9 单源合并）；否则回落 layout_slots.json
+let SLOTS = LC.layoutSlots;
+if (!SLOTS || !SLOTS.pageTypes) {
+  SLOTS = JSON.parse(fs.readFileSync(path.join(__dirname, 'layout_slots.json'), 'utf8'));
+}
+
+const INFO_TYPES = {
+  sankey: 1, treemap: 1, boxplot: 1, network: 1, marimekko: 1, streamgraph: 1,
+};
+
+function pageBox() {
+  const p = LC.page;
+  return { pw: p.pw, ph: p.ph, mx: p.mx, cw: p.pw - 2 * p.mx };
+}
+
+/** 内容区垂直范围（含注释层预留） */
+function contentBand(opts) {
+  const L = LC.pageTypes.layout;
+  const C = LC.pageTypes.common;
+  const withNote = !!(opts && opts.withNote);
+  const top = (opts && opts.top != null) ? opts.top : C.bodyY;
+  const bottom = withNote ? L.contentBottomWithNote : L.contentBottom;
+  return { top, bottom, h: Math.max(0, bottom - top) };
+}
+
+/**
+ * 语义槽位 → {x,y,w,h}（英寸）
+ * 未识别页型/槽位时返回 null（调用方回落自身逻辑，不中断）。
+ */
+function regionOf(pageType, slotId, opts) {
+  const type = String(pageType || 'points');
+  const slot = String(slotId || '');
+  const { mx, cw } = pageBox();
+  const C = LC.pageTypes.common;
+  const L = LC.pageTypes.layout;
+  const PT = LC.pageTypes[type] || {};
+
+  // ── chrome：页头 ──
+  if (slot === 'head' || slot === 'chrome') {
+    return {
+      x: mx, y: C.headEyebrowY, w: cw,
+      h: Math.max(0.4, (C.headRuleY || 1.95) - C.headEyebrowY),
+      titleY: C.headTitleY, ruleY: C.headRuleY, leadY: C.leadY, bodyY: C.bodyY,
+    };
+  }
+
+  // ── annotation：so-what / 来源 / note ──
+  if (slot === 'annotation' || slot === 'soWhat') {
+    const y = (LC.pageTypes.exhibit && LC.pageTypes.exhibit.soWhatY != null)
+      ? LC.pageTypes.exhibit.soWhatY : 6.05;
+    return { x: mx, y, w: cw, h: 0.62 };
+  }
+  if (slot === 'footnote') {
+    const y = (LC.pageTypes.exhibit && LC.pageTypes.exhibit.footnoteY != null)
+      ? LC.pageTypes.exhibit.footnoteY
+      : ((LC.pageTypes.note && LC.pageTypes.note.y) || 6.55);
+    return { x: mx, y, w: cw - 1.2, h: (LC.pageTypes.note && LC.pageTypes.note.h) || 0.32 };
+  }
+
+  // ── 页型主从区域 ──
+  if (type === 'points') {
+    const band = contentBand(opts);
+    if (slot === 'primary' || slot === 'list') {
+      return { x: mx, y: PT.listY || band.top, w: cw, h: Math.max(0.8, band.bottom - (PT.listY || band.top)) };
+    }
+    if (slot === 'metrics') {
+      return { x: mx, y: PT.metricY || 4.7, w: cw, h: Math.max(0.6, L.contentBottom - (PT.metricY || 4.7)) };
+    }
+  }
+
+  if (type === 'metrics') {
+    if (slot === 'primary') {
+      return {
+        x: mx, y: PT.bandY || 3.1, w: cw, h: PT.cardH || 2.3,
+        valY: PT.valY, valH: PT.valH, capY: PT.capY, capH: PT.capH,
+        gap: PT.gap, maxW: PT.maxW,
+      };
+    }
+  }
+
+  if (type === 'table') {
+    if (slot === 'primary') {
+      const y = PT.y || L.contentTop;
+      return {
+        x: mx, y, w: cw,
+        h: Math.max(1, ((opts && opts.bottom) || L.contentBottom) - y),
+        rowH: PT.rowH, rowHMin: PT.rowHMin, headRowH: PT.headRowH,
+      };
+    }
+  }
+
+  if (type === 'bar') {
+    if (slot === 'primary') {
+      const y = PT.chartY || 2.95;
+      const bottom = (opts && opts.bottom != null) ? opts.bottom
+        : ((opts && opts.withNote) ? L.contentBottomWithNote : L.contentBottom);
+      return { x: mx + (PT.chartX || 0), y, w: cw - (PT.chartW || 0), h: Math.max(1.2, bottom - y) };
+    }
+    if (slot === 'hbar') {
+      const y0 = PT.hbarY0 || 2.6;
+      const y1 = (opts && opts.bottom != null) ? opts.bottom : (PT.hbarY1 || 6.25);
+      return { x: mx, y: y0, w: cw, h: Math.max(1.2, y1 - y0) };
+    }
+  }
+
+  if (type === 'donut') {
+    if (slot === 'primary') {
+      const y = PT.chartY || 2.95;
+      const bottom = (opts && opts.bottom != null) ? opts.bottom : L.contentBottom;
+      return { x: mx, y, w: cw, h: Math.max(1.2, bottom - y) };
+    }
+  }
+
+  if (type === 'exhibit') {
+    if (slot === 'primary') {
+      const y = PT.chartY || 2.95;
+      const h = Math.max(1.2, (L.contentBottomWithNote - y));
+      return { x: mx, y, w: cw, h, badgeY: PT.badgeY };
+    }
+    if (slot === 'secondary') {
+      return { x: mx, y: PT.badgeY || L.contentTop, w: cw * 0.32, h: 0.4 };
+    }
+  }
+
+  if (type === 'points') {
+    const band = contentBand(opts);
+    if (slot === 'primary' || slot === 'list') {
+      return {
+        x: mx, y: PT.listY || band.top, w: cw,
+        h: Math.max(0.8, (opts && opts.bottom != null ? opts.bottom : band.bottom) - (PT.listY || band.top)),
+        rowH: PT.rowH, rowHMin: PT.rowHMin, markSize: PT.markSize,
+      };
+    }
+    if (slot === 'metrics') {
+      return {
+        x: mx, y: PT.metricY || 4.7, w: cw,
+        h: Math.max(0.6, L.contentBottom - (PT.metricY || 4.7)),
+        metricW: PT.metricW, metricValH: PT.metricValH, metricCapY: PT.metricCapY,
+      };
+    }
+  }
+
+  if (type === 'split') {
+    const SP = PT;
+    const top = SP.chartY || L.contentTop;
+    const bottom = (opts && opts.bottom != null) ? opts.bottom : L.contentBottom;
+    if (slot === 'left') {
+      return {
+        x: mx, y: top, w: cw * (SP.leftW || 0.55),
+        h: Math.max(1.2, bottom - top),
+        tableY: SP.tableY, tableRowH: SP.tableRowH, rowH: SP.rowH, capY: SP.capY,
+      };
+    }
+    if (slot === 'right') {
+      const rx = mx + cw * (SP.rightX != null ? SP.rightX : 0.585);
+      return {
+        x: rx, y: top, w: cw * (SP.rightW || 0.415),
+        h: Math.max(1.2, bottom - top),
+        tableY: SP.tableY, tableRowH: SP.tableRowH, rowH: SP.rowH, capY: SP.capY,
+      };
+    }
+  }
+
+  if (type === 'twocol') {
+    const gap = PT.colGap || 0.5;
+    const colW = (cw - gap) / 2;
+    const top = (opts && opts.top != null) ? opts.top : L.contentTop;
+    const bottom = (opts && opts.bottom != null) ? opts.bottom : L.contentBottom;
+    if (slot === 'primary' || slot === 'left') {
+      return { x: mx, y: top, w: colW, h: Math.max(1, bottom - top), gap, colW };
+    }
+    if (slot === 'secondary' || slot === 'right') {
+      return { x: mx + colW + gap, y: top, w: colW, h: Math.max(1, bottom - top), gap, colW };
+    }
+  }
+
+  if (type === 'diagram' || type === 'lane') {
+    if (slot === 'primary') {
+      const arch = LC.pageTypes.arch || {};
+      const y = (opts && opts.mode === 'architecture' && arch.fullStartY != null)
+        ? arch.fullStartY
+        : (PT.bodyStartY || 2.9);
+      const b = (opts && opts.mode === 'architecture' && arch.fullEndY != null)
+        ? arch.fullEndY
+        : ((opts && opts.bottom != null) ? opts.bottom : L.contentBottom);
+      return {
+        x: mx, y, w: cw, h: Math.max(1.2, b - y),
+        layerBarW: PT.layerBarW, layerGap: PT.layerGap, maxLayerH: PT.maxLayerH,
+        laneH: arch.laneH, laneHeadW: arch.laneHeadW, laneGap: arch.laneGap,
+        stepGap: arch.stepGap, stepMaxW: arch.stepMaxW,
+      };
+    }
+  }
+
+  // ── 剩余高频页型 ──
+  if (type === 'kpi') {
+    if (slot === 'primary' || slot === 'hero') {
+      return {
+        x: mx, y: PT.heroY || 2.9, w: cw * (PT.heroW || 0.52), h: PT.heroH || 1.6,
+        dividerX: PT.dividerX, metricY0: PT.metricY0, metricRowH: PT.metricRowH,
+      };
+    }
+    if (slot === 'metrics') {
+      const dx = PT.dividerX != null ? PT.dividerX : 0.56;
+      return {
+        x: mx + cw * dx + 0.35, y: PT.metricY0 || 2.95,
+        w: cw * (1 - dx) - 0.5, h: Math.max(0.6, L.contentBottom - (PT.metricY0 || 2.95)),
+      };
+    }
+  }
+
+  if (type === 'comparison') {
+    const gap = PT.panelGap || 0.4;
+    const panelW = (cw - gap) / 2;
+    const y = PT.panelY || 2.55;
+    const h = PT.panelH || 3.4;
+    if (slot === 'primary' || slot === 'left') {
+      return { x: mx, y, w: panelW, h, titleH: PT.titleH, rowH: PT.rowH };
+    }
+    if (slot === 'right' || slot === 'secondary') {
+      return { x: mx + panelW + gap, y, w: panelW, h, titleH: PT.titleH, rowH: PT.rowH };
+    }
+  }
+
+  if (type === 'quote') {
+    if (slot === 'primary') {
+      return {
+        x: mx + 1.05, y: PT.textY || 2.7, w: cw - 2.1, h: PT.textH || 2.3,
+        markY: PT.markY, authorY: PT.authorY, contextY: PT.contextY,
+      };
+    }
+  }
+
+  if (type === 'heatmap') {
+    if (slot === 'primary') {
+      const y = PT.y || 2.6;
+      const bottom = (opts && opts.bottom != null) ? opts.bottom : L.contentBottom;
+      return {
+        x: mx, y, w: cw, h: Math.max(1, bottom - y),
+        labelW: PT.labelW, headH: PT.headH, cellH: PT.cellH, cellGap: PT.cellGap,
+      };
+    }
+  }
+
+  if (type === 'bullet') {
+    if (slot === 'primary') {
+      const y = PT.y || 2.6;
+      const bottom = (opts && opts.bottom != null) ? opts.bottom : L.contentBottom;
+      return {
+        x: mx, y, w: cw, h: Math.max(1, bottom - y),
+        rowH: PT.rowH, labelW: PT.labelW, valW: PT.valW, barH: PT.barH,
+      };
+    }
+  }
+
+  if (type === 'pyramid') {
+    if (slot === 'primary') {
+      const y = PT.y || 2.35;
+      const bottom = (opts && opts.bottom != null) ? opts.bottom : L.contentBottom;
+      return {
+        x: mx, y, w: cw, h: Math.max(1, bottom - y),
+        rowH: PT.rowH, gap: PT.gap, minW: PT.minW, labelW: PT.labelW,
+      };
+    }
+  }
+
+  if (type === 'steps') {
+    if (slot === 'primary') {
+      const y = PT.y || 3.05;
+      return {
+        x: mx, y, w: cw, h: PT.barH || 1.35,
+        gap: PT.gap, arrowW: PT.arrowW, numH: PT.numH, titleH: PT.titleH,
+        pad: PT.pad, maxPerRow: PT.maxPerRow,
+      };
+    }
+  }
+
+  if (type === 'cards') {
+    if (slot === 'primary') {
+      const y = PT.startY || 3.0;
+      const bottom = (opts && opts.bottom != null) ? opts.bottom : L.contentBottom;
+      return { x: mx, y, w: cw, h: Math.max(1, bottom - y), gap: PT.gap, maxH: PT.maxH, titleH: PT.titleH };
+    }
+  }
+
+  if (type === 'timeline') {
+    if (slot === 'primary') {
+      return {
+        x: mx, y: PT.labelY || 2.95, w: cw,
+        h: Math.max(1, L.contentBottom - (PT.labelY || 2.95)),
+        axisY: PT.axisY, dotY: PT.dotY, dotR: PT.dotR, nameY: PT.nameY,
+        descY: PT.descY, descH: PT.descH,
+      };
+    }
+  }
+
+  if (type === 'image') {
+    if (slot === 'primary') {
+      const y = Math.max(PT.y || 2.3, (opts && opts.top) || 0);
+      const bottom = (opts && opts.bottom != null) ? opts.bottom : L.contentBottom;
+      const capH = (opts && opts.caption) ? 0.32 : 0;
+      return {
+        x: mx, y, w: cw, h: Math.max(1.2, Math.min(PT.h || 4.2, bottom - y - capH)),
+        halfW: PT.halfW, halfGap: PT.halfGap, capY: PT.capY, capH: PT.capH || 0.3,
+        radius: PT.radius, gridGap: PT.gridGap, gridCols: PT.gridCols,
+      };
+    }
+  }
+
+  if (type === 'halftable') {
+    if (slot === 'primary' || slot === 'left') {
+      const r = LC.pageTypes.research || {};
+      const top = (opts && opts.top != null) ? opts.top : L.contentTop;
+      const bottom = (opts && opts.bottom != null) ? opts.bottom : L.contentBottom;
+      return { x: mx, y: top, w: cw * (r.halfTableW || 0.52), h: Math.max(1, bottom - top) };
+    }
+    if (slot === 'secondary' || slot === 'right') {
+      const r = LC.pageTypes.research || {};
+      const top = (opts && opts.top != null) ? opts.top : L.contentTop;
+      const bottom = (opts && opts.bottom != null) ? opts.bottom : L.contentBottom;
+      return {
+        x: mx + cw * (r.halfChartX || 0.57), y: top,
+        w: cw * (r.halfChartW || 0.43), h: Math.max(1, bottom - top),
+      };
+    }
+  }
+
+  if (type === 'matrix') {
+    if (slot === 'primary') {
+      const r = LC.pageTypes.research || {};
+      const y = r.matrixY || 2.3;
+      const bottom = (opts && opts.bottom != null) ? opts.bottom : L.contentBottom;
+      return {
+        x: mx, y, w: cw, h: Math.max(1, bottom - y),
+        labelW: r.matrixLabelW, cellH: r.matrixCellH,
+      };
+    }
+  }
+
+  if (type === 'threecol') {
+    const r = LC.pageTypes.research || {};
+    const gap = r.col3Gap || 0.38;
+    const colW = (cw - 2 * gap) / 3;
+    const top = (opts && opts.top != null) ? opts.top : L.contentTop;
+    const bottom = (opts && opts.bottom != null) ? opts.bottom : L.contentBottom;
+    if (slot === 'primary' || slot === 'left') {
+      return { x: mx, y: top, w: colW, h: Math.max(1, bottom - top), gap, colW, cols: 3 };
+    }
+    if (slot === 'middle') {
+      return { x: mx + colW + gap, y: top, w: colW, h: Math.max(1, bottom - top), gap, colW, cols: 3 };
+    }
+    if (slot === 'right' || slot === 'secondary') {
+      return { x: mx + 2 * (colW + gap), y: top, w: colW, h: Math.max(1, bottom - top), gap, colW, cols: 3 };
+    }
+  }
+
+  // 信息图页型：内容区主图
+  if (INFO_TYPES[type] && (slot === 'primary')) {
+    const y = PT.y || L.contentTop;
+    const h = PT.h || 4.1;
+    const bottom = (opts && opts.bottom != null) ? opts.bottom : L.contentBottom;
+    return { x: mx, y, w: cw, h: Math.max(1.2, Math.min(h, bottom - y)) };
+  }
+
+  // 默认：内容区全宽
+  if (slot === 'primary' || slot === 'secondary' || slot === 'left' || slot === 'right') {
+    const band = contentBand(opts);
+    return { x: mx, y: band.top, w: cw, h: band.h };
+  }
+  return null;
+}
+
+/** 槽位是否在 layout_slots.json 中声明为 required */
+function slotRequired(pageType, slotId) {
+  const def = (SLOTS.pageTypes || {})[pageType];
+  if (!def) return false;
+  const s = (def.slots || []).find(x => x.id === slotId);
+  return !!(s && s.required);
+}
+
+/** 列出页型已声明槽位 id */
+function slotIds(pageType) {
+  const def = (SLOTS.pageTypes || {})[pageType];
+  return (def && def.slots) ? def.slots.map(s => s.id) : [];
+}
+
+module.exports = {
+  LC,
+  SLOTS,
+  pageBox,
+  contentBand,
+  regionOf,
+  slotRequired,
+  slotIds,
+};

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

@@ -0,0 +1,178 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""TopPPT HTML · HTML 页高与容器裁切真值测量（可选 · 需 playwright）
+
+静态估算（validate_report 页高溢出）是交付前硬门禁的保守近似，但它看不到
+真实布局：「表格被半幅容器横向裁掉一列」这类缺陷在 strict 全绿时照样发生。
+本脚本用无头浏览器量真实布局高度与容器裁切，供深度交付 / 排版争议时对照。
+
+用法:
+    python scripts/measure_height.py report.html
+    python scripts/measure_height.py report.html --json
+    python scripts/measure_height.py report.html --width 1920 --height 1080
+
+缺 playwright / chromium 时打印指引并 exit 0（不阻断交付链）。
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+try:
+    sys.stdout.reconfigure(encoding='utf-8', errors='replace')
+except Exception:
+    pass
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description='HTML 页高真值测量（Playwright）')
+    ap.add_argument('html', help='报告 HTML 路径')
+    ap.add_argument('--width', type=int, default=1920)
+    ap.add_argument('--height', type=int, default=1080)
+    ap.add_argument('--json', action='store_true')
+    ap.add_argument('--tolerance-px', type=int, default=8,
+                    help='band 高度相对视口的容差（超过则记 overflow）')
+    args = ap.parse_args()
+
+    html = Path(args.html)
+    if not html.exists():
+        print(f'错误：HTML 不存在 {html}')
+        return 2
+
+    try:
+        from playwright.sync_api import sync_playwright
+    except ImportError:
+        # 托管 Python 可能未装 playwright；回落到本机已装 playwright 的解释器（不阻断）
+        import shutil
+        import subprocess
+        candidates = []
+        for name in ('python', 'python3', 'py'):
+            exe = shutil.which(name)
+            if exe:
+                candidates.append(exe)
+        # 常见用户安装路径不写死绝对盘符/用户名；仅用 PATH / py launcher
+        for extra in (
+            r'py',
+        ):
+            if Path(extra).exists() or shutil.which(extra):
+                candidates.append(extra)
+        alt = None
+        for exe in candidates:
+            try:
+                probe = subprocess.run(
+                    [exe, '-c', 'import playwright; print(1)'],
+                    capture_output=True, text=True, timeout=8)
+                if probe.returncode == 0 and '1' in (probe.stdout or ''):
+                    alt = exe
+                    break
+            except Exception:
+                continue
+        if not alt:
+            print('跳过：未安装 playwright（pip install playwright && playwright install chromium）')
+            print('静态估算仍由 validate_report.py --strict 把关。')
+            return 0
+        # 用有 playwright 的解释器重跑本脚本（避免在无 playwright 的解释器里空转）
+        import subprocess as sp
+        cmd = [alt, str(Path(__file__).resolve()), str(html),
+               '--width', str(args.width), '--height', str(args.height),
+               '--tolerance-px', str(args.tolerance_px)]
+        if args.json:
+            cmd.append('--json')
+        raise SystemExit(sp.call(cmd))
+
+    url = html.resolve().as_uri()
+    results = []
+    with sync_playwright() as p:
+        try:
+            browser = p.chromium.launch(headless=True)
+        except Exception as e:
+            print(f'跳过：无法启动 chromium（{e}）。请执行 playwright install chromium。')
+            return 0
+        page = browser.new_page(viewport={'width': args.width, 'height': args.height})
+        page.goto(url, wait_until='load', timeout=60000)
+        # 关掉工具栏对页高的影响：尽量贴近演示全屏内容区
+        page.evaluate("""() => {
+          const bar = document.querySelector('.bar');
+          if (bar) bar.style.display = 'none';
+          document.documentElement.style.setProperty('--bar-h', '0px');
+        }""")
+        page.wait_for_timeout(200)
+        bands = page.evaluate("""(tol) => {
+          const vh = window.innerHeight;
+          const nodes = [...document.querySelectorAll('section.band')];
+          return nodes.map((el, i) => {
+            const r = el.getBoundingClientRect();
+            const h = Math.round(el.offsetHeight);
+            const flow = el.classList.contains('band--flow');
+            const id = el.id || ('band-' + (i + 1));
+            return {
+              index: i + 1,
+              id,
+              height: h,
+              viewport: vh,
+              overflow: !flow && h > vh + tol,
+              flow,
+              title: (el.querySelector('.shead__title, h1, h2')?.textContent || '').trim().slice(0, 40),
+            };
+          });
+        }""", args.tolerance_px)
+        # 容器级裁切真值：静态估算只看页高，看不到「表格/卡片被归属容器横向或纵向裁掉」——
+        # 裁切比压缩更糟（数据直接不可见），且 strict 全绿时依然可能发生。
+        clipped = page.evaluate("""() => {
+          const sel = '.card,.panel,.metric,.sowhat,.exhibit,.kpi,.note,.tbl-wrap,td,th';
+          const out = [];
+          document.querySelectorAll(sel).forEach(el => {
+            if (getComputedStyle(el).overflow === 'visible') return;
+            const dw = el.scrollWidth - el.clientWidth;
+            const dh = el.scrollHeight - el.clientHeight;
+            if (dw > 3 || dh > 3) {
+              const band = el.closest('section.band');
+              out.push({
+                container: (el.className || el.tagName).toString().slice(0, 30),
+                page: band ? ([...document.querySelectorAll('section.band')].indexOf(band) + 1) : 0,
+                overflowX: dw > 3 ? dw : 0,
+                overflowY: dh > 3 ? dh : 0,
+                text: (el.textContent || '').trim().slice(0, 24),
+              });
+            }
+          });
+          return out;
+        }""")
+        browser.close()
+
+    over = [b for b in bands if b['overflow']]
+    payload = {
+        'file': str(html),
+        'viewport': f'{args.width}x{args.height}',
+        'bands': len(bands),
+        'overflow_count': len(over),
+        'overflow': over,
+        'clipped_count': len(clipped),
+        'clipped': clipped,
+        'details': bands,
+    }
+    if args.json:
+        print(json.dumps(payload, ensure_ascii=False, indent=2))
+    else:
+        print(f'页高真值测量 · {html.name} @ {args.width}×{args.height}')
+        print(f'  band 数 {len(bands)} · 超一屏 {len(over)} · 容器裁切 {len(clipped)}')
+        for b in bands:
+            mark = '✗' if b['overflow'] else ('·' if b['flow'] else '✓')
+            print(f'  {mark} 第{b["index"]}页 {b["id"]:16} {b["height"]:4}px  {b["title"]}')
+        if clipped:
+            print('  ── 容器级裁切（内容越过归属容器，铁律 11）──')
+            for c in clipped[:8]:
+                axis = f'横向 {c["overflowX"]}px' if c['overflowX'] else f'纵向 {c["overflowY"]}px'
+                print(f'  ✗ 第{c["page"]}页 {c["container"]} {axis}  「{c["text"]}」')
+            print('  处理：换组合版式/减列/缩表 → 调容器宽度 → 拆页；不要靠容器滚动条遮掩')
+        if over:
+            print('  处理：列表化/精炼 → 压缩间距 → 多列 → 拆页；长结构页加 band--flow')
+        if not over and not clipped:
+            print('  结论：全部固定页高 band 未超视口，且无容器级裁切')
+    return 0 if not over and not clipped else 1
+
+
+if __name__ == '__main__':
+    sys.exit(main())