@topmindspace/tms-skills 0.1.0 → 0.1.2

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

@@ -1,78 +1,79 @@
-#!/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); });
+#!/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-research.png             —— 研究模式 Tab（咨询密排形态）
+ *   theme-overview-architecture.png         —— 架构模式 Tab（图为王形态）
+ *
+ * 演示态与整体图内容相同，不再单独写 theme-overview-presentation.png。
+ * 每次截图前断言当前 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}`);
+    // presentation tab → theme-overview.png only (no duplicate *-presentation.png)
+    if (m === 'presentation') {
+      await page.screenshot({ path: path.join(outDir, 'theme-overview.png'), fullPage: true });
+      console.log(`captured: theme-overview.png  (tab=${on}, cards=${n}; presentation = overview)`);
+    } else {
+      await page.screenshot({ path: path.join(outDir, `theme-overview-${m}.png`), fullPage: true });
+      console.log(`captured: theme-overview-${m}.png  (tab=${on}, cards=${n})`);
+    }
+  }
+
+  await browser.close();
+  console.log(`done: 3 张主题参考图已刷新（deviceScaleFactor=${SCALE}）`);
+})().catch((e) => { console.error(e); process.exit(1); });

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

@@ -1,127 +1,166 @@
-#!/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
+#!/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 core_charts(lc: dict | None = None) -> list[str]:
+    lc = lc or load_lc()
+    ls = lc.get('layoutSystem') or {}
+    return list(ls.get('defaultCharts') or
+                ['bar', 'hbar', 'line', 'donut', 'progress', 'area', 'stack', 'dualline'])
+
+
+def advanced_charts(lc: dict | None = None) -> set[str]:
+    lc = lc or load_lc()
+    ls = lc.get('layoutSystem') or {}
+    return set(ls.get('advancedCharts') or [])
+
+
+def variety_core_preference(used: list[str], variety: dict | None = None,
+                            lc: dict | None = None) -> str | None:
+    """preferCoreFirst：advanced 已用但核图多样性不足 → WARN 文案。
+
+    advanced 仍计入 minTypes（不罚）；仅提示勿用冷门图凑下限。
+    """
+    v = variety if variety is not None else chart_variety(lc)
+    if not v.get('preferCoreFirst'):
+        return None
+    core = set(core_charts(lc))
+    adv = advanced_charts(lc)
+    distinct = set(used)
+    core_used = distinct & core
+    adv_used = distinct & adv if adv else (distinct - core)
+    if not adv_used:
+        return None
+    floor_hint = int(v.get('corePreferMin') or 3)
+    if len(core_used) >= min(floor_hint, len(core)):
+        return None
+    return (
+        f"核图仅 {sorted(core_used) or '∅'}（建议先 ≥{floor_hint} 种核图拉开多样性）；"
+        f"已用 advanced {sorted(adv_used)}——允许计入 minTypes，但勿为凑下限而选用；"
+        f"仅内容意图命中时用 advanced"
+    )
+
+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