@topmindspace/tms-skills 0.1.0

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

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+/* TopPPT HTML · 主题参考图生成器（维护工具，非交付依赖、非交付硬门禁）
+ *
+ * 用法：
+ *   npm install playwright            # 或在任意位置安装 playwright 后设置 NODE_PATH
+ *   npx playwright install chromium   # 首次需要下载浏览器
+ *   node scripts/capture_theme_overview.js [--channel=msedge|chrome|chromium] [--scale=1.25]
+ *
+ * --scale = deviceScaleFactor（默认 1.25）。参考图只用于"让用户看见风格与主题"，
+ * 1.25 在 1480px 视口下已足够清晰，同时把单张 PNG 控制在 ~1MB 内（便于在 IDE 里快速打开）。
+ *
+ * 浏览器通道自动探测：优先命令行 --channel=，其次环境变量 TOP_PPT_BROWSER_CHANNEL，
+ * 最后回落到 Playwright 自带的 chromium（无本机浏览器依赖）。
+ *
+ * 产物（assets/，覆盖旧图）：
+ *   theme-overview.png                      —— 默认（演示 Tab）整体参考图
+ *   theme-overview-presentation.png         —— 演示模式 Tab
+ *   theme-overview-research.png             —— 研究模式 Tab（咨询密排形态）
+ *   theme-overview-architecture.png         —— 架构模式 Tab（图为王形态）
+ *
+ * 每次截图前断言当前 Tab 文案，防止 Tab 切换未生效导致产出雷同图。 */
+const path = require('path');
+let chromium;
+try {
+  ({ chromium } = require('playwright'));
+} catch (e) {
+  console.error('未找到 playwright。请先安装：npm install playwright && npx playwright install chromium');
+  console.error('（本脚本仅用于刷新 assets/theme-overview*.png 参考图，非技能交付依赖。）');
+  process.exit(2);
+}
+
+const TAB_TEXT = { presentation: '演示汇报', research: '研究报告', architecture: '信息架构图' };
+const channelArg = (process.argv.find((a) => a.startsWith('--channel=')) || '').split('=')[1];
+const scaleArg = parseFloat((process.argv.find((a) => a.startsWith('--scale=')) || '').split('=')[1]);
+const SCALE = Number.isFinite(scaleArg) && scaleArg > 0 ? scaleArg : 1.25;
+const CHANNEL = channelArg || process.env.TOP_PPT_BROWSER_CHANNEL
+  || process.env.TOP_PPT_BROWSER_CHANNEL || '';
+
+(async () => {
+  const gallery = 'file:///' + path.resolve(__dirname, '../assets/style-gallery.html').replace(/\\/g, '/');
+  const outDir = path.resolve(__dirname, '../assets');
+  /* channel 为空 → 用 Playwright 自带 chromium（不依赖本机已装浏览器） */
+  const browser = await chromium.launch(CHANNEL ? { channel: CHANNEL } : {});
+  const page = await browser.newPage({ viewport: { width: 1480, height: 1200 }, deviceScaleFactor: SCALE });
+  await page.goto(gallery);
+  await page.waitForSelector('.preset');
+
+  const modes = ['presentation', 'research', 'architecture'];
+  for (const m of modes) {
+    const idx = modes.indexOf(m);
+    await page.evaluate((i) => document.querySelectorAll('.mtab')[i].click(), idx);
+    await page.waitForTimeout(500);
+    const on = await page.evaluate(() =>
+      (document.querySelector('.mtab.on .mtab__t') || {}).textContent || '');
+    if (on !== TAB_TEXT[m]) {
+      throw new Error(`Tab 切换断言失败：期望「${TAB_TEXT[m]}」实际「${on}」（防止雷同图回归）`);
+    }
+    /* 卡片数必须等于单源风格数（PRESETS 由 sync_runtime.py 从 layout-constants.json 注入），
+     * 防止「扩了风格但画廊/参考图没跟上」的静默漂移（旧断言只查 n < 9，太弱）。 */
+    const n = await page.evaluate(() => document.querySelectorAll('.preset').length);
+    const expected = await page.evaluate(() =>
+      (typeof PRESETS === 'object' && PRESETS) ? Object.keys(PRESETS).length : 0);
+    if (expected && n !== expected) {
+      throw new Error(`画廊卡片数 ${n} ≠ 单源风格数 ${expected}（画廊与 layout-constants.json 漂移）`);
+    }
+    if (n < 9) throw new Error(`卡片数异常：${n}`);
+    await page.screenshot({ path: path.join(outDir, `theme-overview-${m}.png`), fullPage: true });
+    console.log(`captured: theme-overview-${m}.png  (tab=${on}, cards=${n})`);
+  }
+
+  /* 主图回到演示 Tab（默认态） */
+  await page.evaluate(() => document.querySelectorAll('.mtab')[0].click());
+  await page.waitForTimeout(500);
+  await page.screenshot({ path: path.join(outDir, 'theme-overview.png'), fullPage: true });
+  console.log('captured: theme-overview.png (default presentation tab)');
+  await browser.close();
+  console.log(`done: 4 张主题参考图已刷新（deviceScaleFactor=${SCALE}）`);
+})().catch((e) => { console.error(e); process.exit(1); });

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

@@ -0,0 +1,127 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""TopPPT HTML · HTML 检查公共库（单源：承载正则 / 图表通道 / 多样性下限 / 组合版式）
+
+消费方：validate_report.py · quality_gate.py · evals/run_evals.py
+禁止在消费方再手抄 CARRIERS / 多样性公式 / 组合版式判定。
+阈值仍读 layout-constants.json（charts.variety / charts.registry）。
+"""
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+_LC_PATH = ROOT / 'scripts' / 'layout-constants.json'
+
+# 承载类型正则（组合版式：一页是否含 ≥2 种承载）
+CARRIERS = [
+    r'<svg\b[^>]*data-chart=',
+    r'class="tbl-wrap',
+    r'class="card[\s"]',
+    r'class="metric[\s"]',
+    r'class="media[\s"]',
+    r'class="arch[\s"]',
+    r'class="lane[\s"]',
+    r'class="matrix[\s"]',
+    r'class="heat[\s"]',
+    r'class="bul[\s"]',
+    r'class="pyr[\s"]',
+    r'class="steps[\s"]',
+    r'class="exhibit[\s"]',
+    r'class="cols-2',
+    r'class="cols-3',
+]
+
+SKIP_BAND_IDS = ('agenda', 'cover', 'refs', 'appendix', 'next')
+
+
+def load_lc() -> dict:
+    return json.loads(_LC_PATH.read_text(encoding='utf-8'))
+
+
+def chart_registry(lc: dict | None = None) -> dict:
+    lc = lc or load_lc()
+    return {k: v for k, v in ((lc.get('charts') or {}).get('registry') or {}).items()
+            if isinstance(v, dict)}
+
+
+def chart_variety(lc: dict | None = None) -> dict:
+    lc = lc or load_lc()
+    return (lc.get('charts') or {}).get('variety') or {}
+
+
+def bands(html: str) -> list[str]:
+    return re.split(r'(?=<section class="band)', html)[1:]
+
+
+def content_bands(html: str, skip_ids: tuple[str, ...] = SKIP_BAND_IDS) -> list[str]:
+    out = []
+    for b in bands(html):
+        head = b[:240]
+        if any(f'id="{i}"' in head for i in skip_ids):
+            continue
+        out.append(b)
+    return out
+
+
+def chart_types_per_page(html: str) -> list[list[str]]:
+    return [re.findall(r'data-chart="([^"]+)"', b) for b in bands(html)]
+
+
+def distinct_chart_types(html: str) -> list[str]:
+    used = [t for ts in chart_types_per_page(html) for t in ts]
+    return sorted(set(used))
+
+
+def variety_floor(mode: str, n_chart_pages: int, variety: dict | None = None) -> int:
+    """类型数下限 = min(模式上限, max(1, ⌈图表页数 × ratio⌉))"""
+    v = variety if variety is not None else chart_variety()
+    floor = int((v.get('minTypes') or {}).get(mode, 4) or 4)
+    ratio = float(v.get('minTypesRatio') or 0.6)
+    return min(floor, max(1, int(-(-n_chart_pages * ratio // 1))))
+
+
+def adjacent_same_type(pages: list[list[str]]) -> list[str]:
+    """相邻图表页同型告警文案列表。"""
+    adj, prev, prev_i = [], None, 0
+    for i, ts in enumerate(pages):
+        if not ts:
+            continue
+        if prev and set(ts) & set(prev):
+            adj.append(f'第 {prev_i + 1}/{i + 1} 页同型 {sorted(set(ts) & set(prev))}')
+        prev, prev_i = ts, i
+    return adj
+
+
+def carrier_count(band: str) -> int:
+    return sum(1 for pat in CARRIERS if re.search(pat, band))
+
+
+def composite_pages(html: str) -> tuple[int, int]:
+    """返回 (含 ≥2 种承载的内容页数, 内容页总数)。"""
+    content = content_bands(html)
+    multi = sum(1 for b in content if carrier_count(b) >= 2)
+    return multi, len(content)
+
+
+def composite_required(mode: str, variety: dict | None = None) -> float:
+    """组合版式比例下限；非 compositeModes 返回 0。"""
+    v = variety if variety is not None else chart_variety()
+    if mode not in (v.get('compositeModes') or ['research']):
+        return 0.0
+    return float(v.get('compositeMinRatio') or 0)
+
+
+def chart_channel(chart_type: str, reg: dict | None = None) -> str:
+    reg = reg if reg is not None else chart_registry()
+    spec = reg.get(str(chart_type or 'bar').lower()) or {}
+    return str(spec.get('pptx') or 'native')
+
+
+def chart_datatable_mode(chart: dict, reg: dict | None = None) -> str:
+    reg = reg if reg is not None else chart_registry()
+    spec = reg.get(str(chart.get('type') or 'bar').lower()) or {}
+    mode = str(chart.get('dataTable') or spec.get('dataTable') or 'notes').lower()
+    return 'inline' if mode == 'appendix' else mode

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

@@ -0,0 +1,294 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""TopPPT HTML · 双通道交叉验证（可选依赖 python-pptx）：
+① A 通道（手写 OOXML）与 B 通道（pptxgenjs）产物均可被 python-pptx 严格解析
+② 两通道逐页文本集合一致（同一模型 → 同一内容；段落换行表示差异已归一）
+   归一化：B 通道带数据的图表为原生 chart part（可编辑数据）——图表类别标签并入
+   文本集合、纯数值 token（含百分数）两端过滤（A 通道形状版的数值标签 vs B 通道 chart 数据值）
+③ 文本溢出启发式：文本估算宽 vs shape 宽 × 可容行数
+④ B 通道原生图表数值 ↔ 模型数值（类别标签一致不代表数值一致；数值错乱只能这里拓）
+⑤ 字号比例尺同源：B 的字号必须是 A 字号集的子集（防 modeSize()/sz() 后处理漂移）
+用法：先 node scripts/gen_channel_a.js 生成 A 通道产物，再 python scripts/cross_verify.py
+改 pptx-export.js 序列化骨架后必跑（见 references/pptx-export.md 双裁判教训）。
+"""
+import json
+import re
+import sys
+from pathlib import Path
+
+sys.stdout.reconfigure(encoding='utf-8', errors='replace')
+# 依赖缺失不在导入期退出——本模块的核对函数会被 negative_tests.py 直接复用
+try:
+    from pptx import Presentation
+except ImportError:
+    Presentation = None
+
+ROOT = Path(__file__).resolve().parent.parent
+A_DIR = ROOT / 'dist' / 'regression-a'    # A 通道（页面直导引擎）
+B_DIR = ROOT / 'dist' / 'regression'      # B 通道（pptxgenjs）
+MODEL_DIR = ROOT / 'assets' / 'examples'
+
+# 文本度量单源（与 build_pptx.js / validate_pptx.py 同值）——三侧各自硬编码会让
+# 溢出判定在不同裁判间飘移，出现“一侧报溢出、一侧说没事”。
+try:
+    _TM = (json.loads((ROOT / 'scripts' / 'layout-constants.json').read_text(encoding='utf-8'))
+           .get('containers', {}).get('textMetrics', {}))
+except (OSError, json.JSONDecodeError):
+    _TM = {}
+LINE_FACTOR = float(_TM.get('lineFactor') or 1.45)
+EM_ASCII_RATIO = float(_TM.get('emAsciiRatio') or 0.52)
+
+# 形态变换类图表：模型里的负值在图上是「向下的正高度条」，按绝对值比对
+SIGNLESS_CHARTS = {'waterfall', 'gauge', 'funnel', 'bullet'}
+
+# 纯数值 token（含千分位/小数/百分号/常见单位后缀）——图表数据标签在 A 通道是
+# 文本（值+unit，如 "9pt"），B 通道进 chart part；比对前两端过滤。类别标签（如 "2026Q3"）
+# 不匹配此模式，仍参与一致性检查。
+NUMERIC_TOKEN = re.compile(
+    r'^[+-]?[\d.,]+\s*(?:%|‰|pt|pct|pp|TB|GB|MB|KB|k|w|万|亿|元|倍|个|人|天|家|次|项|年'
+    r'|条|笔|台|套|份|款|张|篇|页|件|例|场|轮|艘|辆|吨|米|秒|分|时|档|级)?$')
+
+
+def slide_texts(prs):
+    """每页文本集合（逐行拆分——A 通道段落 \\n 与 B 通道 breakLine \\n\\n 表示差异归一；
+    忽略空白、页码与纯数值 token；B 通道原生图表的类别标签并入集合）。"""
+    pages = []
+    for slide in prs.slides:
+        texts = []
+        for shape in slide.shapes:
+            if shape.has_text_frame:
+                for line in shape.text_frame.text.splitlines():
+                    t = line.strip()
+                    if t and not NUMERIC_TOKEN.match(t):
+                        texts.append(t)
+            elif shape.has_table:
+                for row in shape.table.rows:
+                    for cell in row.cells:
+                        for line in cell.text.splitlines():
+                            t = line.strip()
+                            if t and not NUMERIC_TOKEN.match(t):
+                                texts.append(t)
+            elif getattr(shape, 'has_chart', False):
+                # B 通道原生数据图表——类别标签（实质内容）并入；数据值已按纯数值过滤。
+                # 类别标签同样过 NUMERIC_TOKEN——A 通道文本统一过滤，两端语义对称
+                # （否则 gauge 的 '76%'、stack 的年份 '2023' 这类数值型类别会造成单边误报）。
+                try:
+                    cats = list(shape.chart.plots[0].categories)
+                    texts.extend(str(c).strip() for c in cats
+                                 if str(c).strip() and not NUMERIC_TOKEN.match(str(c).strip()))
+                except Exception:
+                    pass
+        pages.append(sorted(set(texts)))   # 集合语义去重（B 端 chart categories 与自绘图例可能重复）
+    return pages
+
+
+def _model_chart(sec):
+    """取章节页的图表对象（口径与 validate_pptx._section_chart 一致）。"""
+    st = sec.get('type') or ''
+    if st in {'bar', 'donut', 'exhibit', 'halftable'}:
+        c = sec.get('chart') or {}
+    elif st == 'split':
+        c = sec.get('right') or {}
+        if (c.get('type') or 'bar') == 'table':
+            return None
+    else:
+        return None
+    return c if isinstance(c, dict) and c.get('labels') and c.get('values') else None
+
+
+def _model_values(chart):
+    """模型声明的全部数值（单系列 values 或多系列 series[].values）。"""
+    out = []
+    if isinstance(chart.get('series'), list) and chart['series']:
+        for se in chart['series']:
+            out += [v for v in (se.get('values') or []) if isinstance(v, (int, float))]
+    else:
+        out += [v for v in (chart.get('values') or []) if isinstance(v, (int, float))]
+    return out
+
+
+def chart_data_verify(prs, model, name):
+    """B 通道原生 chart part 的数值必须覆盖模型声明值。
+
+    只做「模型值 ⊆ 图表值」的包含判定，不做严格相等——waterfall 的累计基座、
+    gauge 的补角这类派生系列是合法的额外数据，严格相等会制造假阳性。
+    形态变换类图表（waterfall 把 -3 画成高度 3 的悬浮条）按绝对值比对。
+    """
+    issues = []
+    secs = [s for s in (model.get('sections') or []) if isinstance(s, dict)]
+    first = 3 if model.get('agenda') else 2
+    slides = list(prs.slides)
+    for i, sec in enumerate(secs):
+        chart = _model_chart(sec)
+        if chart is None:
+            continue
+        idx = first + i - 1
+        if idx >= len(slides):
+            break
+        pool = []
+        for shape in slides[idx].shapes:
+            if not getattr(shape, 'has_chart', False):
+                continue
+            try:
+                for plot in shape.chart.plots:
+                    for se in plot.series:
+                        pool += [v for v in se.values if v is not None]
+            except Exception:
+                pass
+        if not pool:
+            continue          # 该页是形状还原通道，数值走数据表/备注，另有门禁
+        ctype = str(chart.get('type') or 'bar').lower()
+        signless = ctype in SIGNLESS_CHARTS
+        if signless:
+            pool = [abs(p) for p in pool]
+        missing = []
+        for v in _model_values(chart):
+            target = abs(v) if signless else v
+            if not any(abs(target - p) <= max(0.01, abs(target) * 0.001) for p in pool):
+                missing.append(v)
+        if missing:
+            issues.append(f'{name} 第{idx + 1}页 {ctype} 图表数值与模型不符，'
+                          f'缺 {missing[:5]}（图表实际含 {sorted(set(pool))[:6]}）')
+    return issues
+
+
+def font_sizes(prs):
+    """全文文本框出现过的字号集合（pt）。"""
+    out = set()
+    for slide in prs.slides:
+        for sh in slide.shapes:
+            if not sh.has_text_frame:
+                continue
+            for p in sh.text_frame.paragraphs:
+                for r in p.runs:
+                    if r.font.size and r.text.strip():
+                        out.add(round(r.font.size.pt, 2))
+    return out
+
+
+def overflow_estimate(prs, name):
+    """启发式：文本估算宽（CJK 字符按 1em、ASCII 按 emAsciiRatio）vs shape 宽 × 可容行数。"""
+    issues = []
+    for si, slide in enumerate(prs.slides, 1):
+        for shape in slide.shapes:
+            if not shape.has_text_frame or not shape.width or not shape.height:
+                continue
+            for para in shape.text_frame.paragraphs:
+                line = ''.join(r.text for r in para.runs)
+                if not line.strip():
+                    continue
+                sz = None
+                for r in para.runs:
+                    if r.font.size:
+                        sz = r.font.size.pt
+                        break
+                sz = sz or 12
+                emu_w = int(shape.width)
+                in_w = emu_w / 914400
+                # 每行可容字符宽（英寸）→ em 数
+                est_w = sum(1.0 if ord(c) > 0x2E80 else EM_ASCII_RATIO for c in line) * sz / 72
+                lines_avail = max(1, int(int(shape.height) / 914400 / (sz / 72 * LINE_FACTOR)))
+                if est_w > in_w * lines_avail * 1.18:   # 18% 容差
+                    issues.append(f'{name} 第{si}页 "{line[:14]}…" 估算{est_w:.1f}in > 容量{in_w*lines_avail:.1f}in')
+    return issues
+
+
+def main() -> int:
+    if Presentation is None:
+        print('python-pptx 未安装')
+        return 2
+    fails = []
+    a_files = sorted(A_DIR.glob('*.pptx'))
+    print(f'A 通道产物 {len(a_files)} 个 · B 通道产物 {len(sorted(B_DIR.glob("*.pptx")))} 个\n')
+    all_overflow = []
+
+    for ap in a_files:
+        bp = B_DIR / ap.name
+        name = ap.stem
+        # ① 可解析性
+        try:
+            prs_a = Presentation(str(ap))
+        except Exception as e:
+            fails.append(f'{name}: A 通道 python-pptx 解析失败 {e}')
+            continue
+        if not bp.exists():
+            fails.append(f'{name}: B 通道产物缺失')
+            continue
+        try:
+            prs_b = Presentation(str(bp))
+        except Exception as e:
+            fails.append(f'{name}: B 通道 python-pptx 解析失败 {e}')
+            continue
+        # ② 逐页文本一致性（v9：A/B 不必逐字全等——A 预览为形状近似；
+        #    要求「标题+主文本 ≥80% 交集覆盖」，杜绝截断/串页，又不因图表标签形态差误杀）
+        ta, tb = slide_texts(prs_a), slide_texts(prs_b)
+        if len(ta) != len(tb):
+            fails.append(f'{name}: 页数不一致 A={len(ta)} B={len(tb)}')
+            continue
+        min_cov = 0.80
+        try:
+            min_cov = float((json.loads((ROOT / 'scripts' / 'layout-constants.json')
+                                       .read_text(encoding='utf-8'))
+                             .get('qualityGates') or {}).get('roundtripMin') or 0.8)
+        except Exception:
+            pass
+        diff_pages = []
+        for i, (x, y) in enumerate(zip(ta, tb), 1):
+            sx, sy = set(x), set(y)
+            if not sx and not sy:
+                continue
+            inter = sx & sy
+            cov = len(inter) / max(1, max(len(sx), len(sy)))
+            if cov < min_cov:
+                diff_pages.append((i, cov, sorted(sx - sy)[:3], sorted(sy - sx)[:3]))
+        if diff_pages:
+            for i, cov, only_a, only_b in diff_pages[:3]:
+                fails.append(f'{name}: 第{i}页文本覆盖 {cov:.0%} <{min_cov:.0%} '
+                             f'A独有{only_a} B独有{only_b}')
+        # ③ 溢出启发式（对两通道都跑）
+        all_overflow += overflow_estimate(prs_a, name + '/A')
+        all_overflow += overflow_estimate(prs_b, name + '/B')
+        # ④ B 通道原生图表数值 ↔ 模型（A 通道是形状还原，不产 chart part）
+        chart_note = ''
+        mp = MODEL_DIR / f'{name}.model.json'
+        if mp.exists():
+            try:
+                model = json.loads(mp.read_text(encoding='utf-8'))
+            except json.JSONDecodeError as e:
+                fails.append(f'{name}: 模型不可解析 {e}')
+                model = None
+            if model:
+                data_issues = chart_data_verify(prs_b, model, name)
+                fails += data_issues
+                chart_note = ' 图表数值=' + ('PASS' if not data_issues else f'DIFF({len(data_issues)})')
+        status = 'PASS' if not diff_pages else f'LOWCOV p{[d[0] for d in diff_pages]}'
+        # ⑤ 字号比例尺同源：B 的字号必须都来自 A 同一张表。
+        #    反向不成立——A 把图表渲染成形状，标签字号会多出来（B 的在 chart part 内）。
+        fa, fb = font_sizes(prs_a), font_sizes(prs_b)
+        alien = sorted(fb - fa)
+        if alien:
+            fails.append(f'{name}: B 通道出现 A 没有的字号 {alien}'
+                         f'（两通道应同走 modeTypeScale；modeSize() 与 sz() 的钳制/取整须一致）')
+        sz_note = ' 字号比例尺=' + ('PASS' if not alien else 'DRIFT')
+        print(f'{name}: A可解析✓ B可解析✓ 页数={len(ta)} 逐页文本={status}{chart_note}{sz_note}')
+
+    print('\n── 溢出启发式（check-overflow · 18% 容差）──')
+    if all_overflow:
+        for i in all_overflow[:20]:
+            print('  [WARN]', i)
+    else:
+        print('  两通道全部通过（无文本超容 shape）')
+
+    print('\n' + '=' * 50)
+    if fails:
+        print('交叉验证失败:')
+        for f in fails:
+            print('  [FAIL]', f)
+        return 1
+    print('双通道交叉验证通过：python-pptx 第三方裁判确认 A/B 产物均可解析、'
+          '逐页文本一致、原生图表数值与模型一致')
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main())

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

@@ -0,0 +1,158 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""TopPPT HTML · 运行环境探测（公共模块 · 被 regression / probe_image_export 等复用）
+
+统一 Node / pptxgenjs / python-pptx 的探测口径，避免各脚本各写一份导致漂移。
+**不绑定任何机器的固定路径**：环境变量 > PATH > 常见托管目录（存在才用，不存在不影响）。
+
+解析优先级：
+    Node 可执行文件
+        TOP_PPT_NODE_EXE > NODE_EXE > NODE
+        > PATH 上的 node > 常见托管目录最新版
+    含 pptxgenjs 的 node_modules
+        TOP_PPT_NODE_PATH > NODE_PATH
+        > 仓库内 node_modules > 逐级父目录 node_modules > 常见托管目录 > 全局 npm root
+    python-pptx
+        子进程 `import pptx` 是否成功（可选第三方裁判；未装则调用方跳过）
+
+自检：
+    python scripts/env_probe.py
+"""
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+try:
+    sys.stdout.reconfigure(encoding='utf-8', errors='replace')
+except Exception:
+    pass
+
+ROOT = Path(__file__).resolve().parent.parent
+
+NODE_ENV_VARS = ('TOP_PPT_NODE_EXE', 'NODE_EXE', 'NODE')
+NODE_PATH_ENV_VARS = ('TOP_PPT_NODE_PATH', 'NODE_PATH')
+NODE_BASES = (
+    Path.home() / '.local' / 'share' / 'node',
+    Path.home() / 'AppData' / 'Local' / 'nvs',
+)
+MODULE_BASES = (
+    Path.home() / 'node_modules',
+)
+NODE_EXES = ('node.exe', 'bin/node', 'bin/node.exe')
+DEFAULT_PKG = 'pptxgenjs'
+
+
+# ── Node 可执行文件 ───────────────────────────────────────────────────────────
+
+def node_candidates() -> list[str]:
+    """按优先级返回候选 node 可执行文件（去重、保序）。"""
+    cands: list[str] = []
+    for var in NODE_ENV_VARS:
+        val = os.environ.get(var)
+        if val and Path(val).is_file():
+            cands.append(val)
+    found = shutil.which('node')
+    if found:
+        cands.append(found)
+    for base in NODE_BASES:
+        if not base.is_dir():
+            continue
+        try:
+            for ver in sorted((p for p in base.iterdir() if p.is_dir()), reverse=True):
+                for exe in NODE_EXES:
+                    p = ver / exe
+                    if p.is_file():
+                        cands.append(str(p))
+                        break
+        except OSError:
+            pass
+    seen, out = set(), []
+    for c in cands:
+        if c not in seen:
+            seen.add(c)
+            out.append(c)
+    return out
+
+
+def find_node() -> str | None:
+    for c in node_candidates():
+        if Path(c).is_file():
+            return c
+    return None
+
+
+# ── 含 pptxgenjs 的 node_modules ─────────────────────────────────────────────
+
+def node_modules_candidates() -> list[str]:
+    """按优先级返回可能含目标包的 node_modules 目录（去重、保序）。"""
+    cands: list[str] = []
+    for var in NODE_PATH_ENV_VARS:
+        val = os.environ.get(var)
+        if val:
+            cands.extend(p for p in val.split(os.pathsep) if p)
+    cands.append(str(ROOT / 'node_modules'))
+    cands.extend(str(p / 'node_modules') for p in list(ROOT.parents)[:3])  # monorepo 场景
+    cands.extend(str(b) for b in MODULE_BASES)
+    try:
+        npm_root = subprocess.run(['npm', 'root', '-g'], capture_output=True, text=True,
+                                  encoding='utf-8', timeout=30).stdout.strip()
+        if npm_root:
+            cands.append(npm_root)
+    except Exception:
+        pass
+    seen, out = set(), []
+    for c in cands:
+        if c and c not in seen:
+            seen.add(c)
+            out.append(c)
+    return out
+
+
+def find_node_modules(pkg: str = DEFAULT_PKG) -> str | None:
+    for c in node_modules_candidates():
+        if (Path(c) / pkg).is_dir():
+            return c
+    return None
+
+
+# ── 组合与提示 ───────────────────────────────────────────────────────────────
+
+def node_env(node_modules: str | None = None) -> dict[str, str]:
+    """返回可直接传给 subprocess 的环境（把 NODE_PATH 指到解析出的 node_modules）。"""
+    env = dict(os.environ)
+    if node_modules:
+        env['NODE_PATH'] = node_modules
+    return env
+
+
+def has_python_pptx(python_exe: str | None = None) -> bool:
+    exe = python_exe or sys.executable
+    try:
+        return subprocess.run([exe, '-c', 'import pptx'], capture_output=True).returncode == 0
+    except OSError:
+        return False
+
+
+NODE_HINT = ('未找到 Node 可执行文件（PPTX 精导与回归必需）。安装 Node 后重试，'
+             '或用环境变量 TOP_PPT_NODE_EXE 指定路径。')
+NODE_MODULES_HINT = ('未找到含 pptxgenjs 的 node_modules（PPTX 生成必需）。'
+                     '在技能目录执行 `npm install`（依 package.json），'
+                     '或用环境变量 TOP_PPT_NODE_PATH 指定 node_modules 路径。')
+
+
+def resolve(pkg: str = DEFAULT_PKG) -> tuple[str | None, str | None]:
+    """一次性返回 (node, node_modules)。"""
+    return find_node(), find_node_modules(pkg)
+
+
+if __name__ == '__main__':
+    node, mods = resolve()
+    print('环境探测（TopPPT HTML）')
+    print(f'  node         : {node or "未找到"}')
+    print(f'  node_modules : {mods or "未找到（缺 pptxgenjs）"}')
+    print(f'  python-pptx  : {"可用" if has_python_pptx() else "未安装（可选，交叉裁判会跳过）"}')
+    sys.exit(0 if (node and mods) else 1)