@topmindspace/tms-skills 0.3.6 → 0.4.1

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

@@ -95,9 +95,18 @@ def kp(k, v) -> str:
     return f'<li><strong>{k}。</strong>{v}</li>' if k else f'<li>{v}</li>'
 
 
-def open_sec(i: int, ptype: str, extra: str = '') -> str:
+def sec_anchor(i: int, sec: dict) -> str:
+    """页锚点 id：模型 anchor 优先，否则 s{i}（agenda 链接与 open_sec 同源，禁各写一份）。"""
+    a = str((sec or {}).get('anchor') or '').strip()
+    if re.fullmatch(r'[A-Za-z][A-Za-z0-9_-]*', a):
+        return a
+    return f's{i}'
+
+
+def open_sec(i: int, ptype: str, extra: str = '', sec: dict = None) -> str:
     skel = PAGE_TO_PRESET.get(ptype, 'P4')
-    return (f'<section class="band" id="s{i}" data-skel="{skel}" '
+    sid = sec_anchor(i, sec)
+    return (f'<section class="band" id="{sid}" data-skel="{skel}" '
             f'data-page-type="{ptype}"{extra}>')
 
 
@@ -118,10 +127,17 @@ def sowhat(sec: dict) -> str:
 
 
 def footnote(sec: dict) -> str:
+    # footnote 与 note 共用来源行（与 build_pptx 注释带同口径：两者都不丢）
     t = sec.get('footnote')
-    if not t:
+    n = sec.get('note')
+    parts = []
+    if t:
+        parts.append(cite(t))
+    if n and n != t:
+        parts.append(f'注：{cite(n)}')
+    if not parts:
         return ''
-    return f'    <div class="footnote">{cite(t)}</div>\n'
+    return f'    <div class="footnote">{" ".join(parts)}</div>\n'
 
 
 def flags_block(sec: dict) -> str:
@@ -134,55 +150,49 @@ def flags_block(sec: dict) -> str:
 
 
 def wrap(i: int, ptype: str, body: str, sec: dict, extra: str = '') -> str:
-    return (f'{open_sec(i, ptype, extra)}\n  <div class="wrap">\n'
+    return (f'{open_sec(i, ptype, extra, sec)}\n  <div class="wrap">\n'
             f'{shead(sec)}\n{body}{sowhat(sec)}{footnote(sec)}{flags_block(sec)}'
             f'  </div>\n</section>')
 
 
-# ── 语义图标库（高频取码 · 与 references/icons.md 同源；PPTX 侧由 accent 方块路标对应）──
-_SVG_OPEN = ('<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" '
-             'stroke-linecap="round" stroke-linejoin="round">')
-ICONS: dict[str, str] = {
-    '增长': _SVG_OPEN + '<path d="M22 7l-8.5 8.5-5-5L2 17"/><path d="M16 7h6v6"/></svg>',
-    '下降': _SVG_OPEN + '<path d="M22 17l-8.5-8.5-5 5L2 7"/><path d="M16 17h6v-6"/></svg>',
-    '数据': _SVG_OPEN + '<ellipse cx="12" cy="5" rx="9" ry="3"/><path d="M3 5v14c0 1.66 4.03 3 9 3s9-1.34 9-3V5"/><path d="M3 12c0 1.66 4.03 3 9 3s9-1.34 9-3"/></svg>',
-    '图表': _SVG_OPEN + '<path d="M3 3v18h18"/><rect x="7" y="12" width="3" height="6" rx="1"/><rect x="12" y="8" width="3" height="10" rx="1"/><rect x="17" y="4" width="3" height="14" rx="1"/></svg>',
-    '趋势': _SVG_OPEN + '<path d="M3 3v18h18"/><path d="M7 14l4-4 3 3 5-6"/><path d="M15 7h4v4"/></svg>',
-    '占比': _SVG_OPEN + '<path d="M21.2 15.9A10 10 0 1 1 8 2.8"/><path d="M22 12A10 10 0 0 0 12 2v10z"/></svg>',
-    '表格': _SVG_OPEN + '<rect x="3" y="3" width="18" height="18" rx="2"/><path d="M3 9h18M3 15h18M9 3v18M15 3v18"/></svg>',
-    '效率': _SVG_OPEN + '<path d="M12 15l3.5-5.5"/><path d="M20.2 15a8.5 8.5 0 1 0-16.4 0"/></svg>',
-    '成果': _SVG_OPEN + '<circle cx="12" cy="8" r="6"/><path d="M15.5 13 17 22l-5-3-5 3 1.5-9"/></svg>',
-    '安全': _SVG_OPEN + '<path d="M12 22s8-4 8-10V5l-8-3-8 3v7c0 6 8 10 8 10z"/><path d="M9 12l2 2 4-4"/></svg>',
-    '权限': _SVG_OPEN + '<rect x="3" y="11" width="18" height="10" rx="2"/><path d="M7 11V7a5 5 0 0 1 10 0v4"/></svg>',
-    '检查': _SVG_OPEN + '<circle cx="12" cy="12" r="10"/><path d="M8 12.5l2.5 2.5L16 9.5"/></svg>',
-    '风险': _SVG_OPEN + '<path d="M10.3 3.9 1.8 18a2 2 0 0 0 1.7 3h17a2 2 0 0 0 1.7-3L13.7 3.9a2 2 0 0 0-3.4 0z"/><path d="M12 9v4M12 17h.01"/></svg>',
-    '团队': _SVG_OPEN + '<path d="M17 21v-2a4 4 0 0 0-4-4H5a4 4 0 0 0-4 4v2"/><circle cx="9" cy="7" r="4"/><path d="M23 21v-2a4 4 0 0 0-3-3.87"/><path d="M16 3.13a4 4 0 0 1 0 7.75"/></svg>',
-    '流程': _SVG_OPEN + '<circle cx="18" cy="18" r="3"/><circle cx="6" cy="6" r="3"/><path d="M6 21V9a9 9 0 0 0 9 9"/></svg>',
-    '计划': _SVG_OPEN + '<rect x="3" y="4" width="18" height="18" rx="2"/><path d="M16 2v4M8 2v4M3 10h18"/></svg>',
-    '智能': _SVG_OPEN + '<rect x="4" y="4" width="16" height="16" rx="2"/><path d="M9 9h6v6H9zM9 1v3M15 1v3M9 20v3M15 20v3M1 9h3M1 15h3M20 9h3M20 15h3"/></svg>',
-    '洞察': _SVG_OPEN + '<circle cx="11" cy="11" r="8"/><path d="M21 21l-4.35-4.35"/></svg>',
-    '工具': _SVG_OPEN + '<path d="M14.7 6.3a1 1 0 0 0 0 1.4l1.6 1.6a1 1 0 0 0 1.4 0l3.77-3.77a6 6 0 0 1-7.94 7.94l-6.91 6.91a2.12 2.12 0 0 1-3-3l6.91-6.91a6 6 0 0 1 7.94-7.94l-3.76 3.76z"/></svg>',
-    '清单': _SVG_OPEN + '<path d="M8 6h13M8 12h13M8 18h13M3 6h.01M3 12h.01M3 18h.01"/></svg>',
-}
+# ── 语义图标库（单源：assets/icons/ + index.json；与 icon_lib.js / PPTX 真导出同源）──
+_ICON_DIR = Path(__file__).resolve().parent.parent / 'assets' / 'icons'
+_ICON_INDEX: dict = {}
+try:
+    _ICON_INDEX = json.loads((_ICON_DIR / 'index.json').read_text(encoding='utf-8'))
+except OSError:
+    _ICON_INDEX = {}
+
+
+def _load_icons() -> 'dict[str, str]':
+    out: dict[str, str] = {}
+    for name in (_ICON_INDEX.get('icons') or {}):
+        try:
+            out[name] = (_ICON_DIR / f'{name}.svg').read_text(encoding='utf-8').strip()
+        except OSError:
+            continue
+    return out
+
+
+ICONS: dict[str, str] = _load_icons()
 _ICONS_ORDER = list(ICONS.keys())
+_ICON_DEFAULTS = [n for n in (_ICON_INDEX.get('defaults') or []) if n in ICONS] or _ICONS_ORDER
 
 
 def pick_icon(title: str = '', idx: int = 0) -> str:
-    """按标题语义挑图标；未命中则按序轮换（保持同屏同家族、不堆砌）。"""
-    t = str(title or '')
-    for key, svg in ICONS.items():
-        if key in t:
-            return svg
-    return ICONS[_ICONS_ORDER[idx % len(_ICONS_ORDER)]]
+    """按标题语义挑图标 SVG；未命中则在默认表内轮换（选不出用默认，不盲目轮换全量）。"""
+    return ICONS[pick_icon_name(title, idx)]
 
 
 def pick_icon_name(title: str = '', idx: int = 0) -> str:
-    """图标名（与 icon_lib.js / PPTX 真导出同名）。"""
+    """图标名（与 icon_lib.js / PPTX 真导出同名；关键词来自 index.json）。"""
     t = str(title or '')
-    for key in ICONS:
-        if key in t:
+    meta = _ICON_INDEX.get('icons') or {}
+    for key in _ICONS_ORDER:
+        kws = (meta.get(key) or {}).get('keywords') or [key]
+        if any(kw and kw in t for kw in kws):
             return key
-    return _ICONS_ORDER[idx % len(_ICONS_ORDER)]
+    return _ICON_DEFAULTS[idx % len(_ICON_DEFAULTS)]
 
 
 def card_head(title: str, idx: int = 0, icon_name: str | None = None) -> str:
@@ -253,16 +263,23 @@ def r_metrics(i, sec):
 
 
 def r_kpi(i, sec):
+    # 大数指标页：hero 大数字 + 支撑指标行（metrics，可选）+ 要点；三者缺一不丢其余
     hero = sec.get('hero') or []
     val = hero[0] if hero else ''
     lab = hero[1] if len(hero) > 1 else ''
     delta = hero[2] if len(hero) > 2 else ''
+    left = ''
+    if val or lab:
+        left = (
+            '      <div class="stack gap-3"><div class="t-metric" style="color:var(--accent)">'
+            f'{esc(val)}</div>'
+            f'<div class="t-h3">{esc(lab)}</div>'
+            + (f'<div class="t-sm" style="color:var(--accent);font-weight:600">{esc(delta)}</div>' if delta else '')
+            + '</div>\n')
+    mets = metrics_row(sec.get('metrics')) if sec.get('metrics') else ''
     body = (
         '    <div class="grid g-hero rv a-c">\n'
-        f'      <div class="stack gap-3"><div class="t-metric" style="color:var(--accent)">{esc(val)}</div>'
-        f'<div class="t-h3">{esc(lab)}</div>'
-        + (f'<div class="t-sm" style="color:var(--accent);font-weight:600">{esc(delta)}</div>' if delta else '')
-        + '</div>\n'
+        + left + mets
         + '      <div class="grid g-2">\n'
         + pts_list(sec.get('points') or [['支撑', '一句话。']])
         + '\n      </div>\n    </div>\n')
@@ -339,14 +356,20 @@ def r_exhibit(i, sec):
 
 def r_twocol(i, sec):
     paras = sec.get('paragraphs') or []
+    variant = sec.get('variant') or ''
     cols = []
-    for p in paras:
+    for pi, p in enumerate(paras):
         if isinstance(p, (list, tuple)) and len(p) >= 2:
             cols.append(f'      <p class="t-body"><strong>{esc(p[0])}。</strong>{cite(p[1])}</p>')
         else:
             cols.append(f'      <p class="t-body">{cite(p)}</p>')
+    # 变体 2-col-feature：首栏为特性栏（复用 .card 语义：加粗标题 + accent 左线）
+    extra = ''
+    if variant == '2-col-feature' and cols:
+        cols[0] = cols[0].replace('class="t-body"', 'class="t-body col--feature"', 1)
+        extra = ' data-variant="2-col-feature"'
     body = '    <div class="cols-2 rv">\n' + '\n'.join(cols) + '\n    </div>\n'
-    return wrap(i, 'twocol', body, sec)
+    return wrap(i, 'twocol', body, sec, extra)
 
 
 def r_threecol(i, sec):
@@ -365,11 +388,16 @@ def r_threecol(i, sec):
 
 def r_cards(i, sec):
     cards = sec.get('cards') or []
+    variant = sec.get('variant') or ''
     n = int(sec.get('columns') or min(3, max(1, len(cards))))
     cls = {1: 'g-2', 2: 'g-2', 3: 'g-3', 4: 'g-4'}.get(n, 'g-3')
     # 纯卡片栅格强制等高（g-2--equal / g-3--equal），与 CSS / layout-grammar「同行卡片 stretch」一致
     if cls in ('g-2', 'g-3', 'g-4'):
         cls = cls + '--equal'
+    extra = ''
+    if variant == 'bento-grid':
+        # 变体 bento-grid：首卡跨 2 列（.card--lead），复用 .card 组件
+        cls, extra = 'g-bento', ' data-variant="bento-grid"'
     blocks = []
     for ci, cd in enumerate(cards):
         if isinstance(cd, dict):
@@ -380,11 +408,12 @@ def r_cards(i, sec):
             title, points, icon_name = cd[0], [['', cd[1]]], None
         else:
             title, points, icon_name = (cd or ''), [], None
+        lead_cls = ' card--lead' if (variant == 'bento-grid' and ci == 0) else ''
         blocks.append(
-            f'      <div class="card">{card_head(str(title), ci, icon_name)}\n'
+            f'      <div class="card{lead_cls}">{card_head(str(title), ci, icon_name)}\n'
             f'        {pts_list(points)}</div>')
     body = f'    <div class="grid {cls} rv">\n' + '\n'.join(blocks) + '\n    </div>\n'
-    return wrap(i, 'cards', body, sec)
+    return wrap(i, 'cards', body, sec, extra)
 
 
 def r_split(i, sec):
@@ -519,6 +548,9 @@ def r_image(i, sec):
         else:
             grid_cls = f'media-grid media-grid--{min(4, max(2, n))}'
         media = f'    <div class="{grid_cls} rv">\n' + '\n'.join(cells) + '\n    </div>\n'
+        # 组 caption（图编号）：多图版式同样渲染，与 PPTX img.caption 同口径（此前仅单图分支渲染）
+        if cap:
+            media += f'    <p class="media__src">{cite(cap)}</p>\n'
     else:
         src = im.get('src') or ''
         ph = bool(im.get('placeholder')) or not src
@@ -589,23 +621,32 @@ def r_lane(i, sec):
 
 def r_timeline(i, sec):
     items = []
+    variant = sec.get('variant') or ''
     for ph in (sec.get('phases') or []):
         if isinstance(ph, (list, tuple)):
             lab, name, desc = (list(ph) + ['', '', ''])[:3]
             state = ph[3] if len(ph) > 3 else ''
+            icon_name = ph[4] if len(ph) > 4 else ''
         else:
             lab, name, desc, state = ph.get('label', ''), ph.get('name', ''), ph.get('d', ''), ph.get('s', '')
+            icon_name = ph.get('icon', '')
         cls = 'tl__i'
         if state == 'done':
             cls += ' tl__i--done'
         elif state == 'now':
             cls += ' tl__i--now'
+        # 变体 timeline：节点图标（icon:<name>，无图标回落圆点）
+        dot = '<div class="tl__d"></div>'
+        if variant == 'timeline' and icon_name and icon_name in ICONS:
+            dot = (f'<div class="tl__ico" data-icon="{esc(icon_name)}">'
+                   f'{ICONS[icon_name]}</div>')
         items.append(
-            f'        <div class="{cls}"><div class="tl__d"></div>'
+            f'        <div class="{cls}">{dot}'
             f'<div class="tl__l">{esc(lab)}</div><div class="tl__t">{esc(name)}</div>'
             f'<p class="t-body">{cite(desc)}</p></div>')
     body = '    <div class="fig rv"><div class="tl">\n' + '\n'.join(items) + '\n    </div></div>\n'
-    return wrap(i, 'timeline', body, sec)
+    extra = ' data-variant="timeline"' if variant == 'timeline' else ''
+    return wrap(i, 'timeline', body, sec, extra)
 
 
 def r_steps(i, sec):
@@ -675,18 +716,34 @@ def r_pyramid(i, sec):
 
 
 def r_halftable(i, sec):
-    """半表半图：g-half 左表右图（校验 TYPE_FEATURE.halftable）。"""
+    """半表半图：g-half 左表右图（校验 TYPE_FEATURE.halftable）。
+    research 模式带 exhibitNo 时：右图按 Exhibit 规范加编号徽标与来源行，表侧不丢
+    （此前 research 统一走 r_exhibit 会静默丢弃 table——内容覆盖率门禁捕获）。"""
     tbl = sec.get('table') or {}
     ch = sec.get('chart') or {}
     head = tbl.get('head') or []
     rows = tbl.get('rows') or []
     th = ''.join(f'<th>{esc(h)}</th>' for h in head)
     trs = ''.join('<tr>' + ''.join(f'<td>{cite(c)}</td>' for c in row) + '</tr>' for row in rows)
+    no = sec.get('exhibitNo')
+    if no:
+        fig = (
+            '      <div class="fig"><div class="exhibit rv">\n'
+            f'        <div class="exhibit__hd"><span class="exhibit__no">Exhibit {esc(no)}</span>'
+            f'<span class="exhibit__t">{esc(sec.get("title") or "")}</span></div>\n'
+            f'{chart_svg(ch, i)}'
+            f'        <div class="exhibit__src">{cite(sec.get("footnote") or "来源：待补")}</div>\n'
+            '      </div></div>\n')
+        sec = dict(sec)
+        sec.pop('footnote', None)  # 已进来源行，避免 wrap 再渲染一次
+    else:
+        fig = (
+            f'      <div class="fig"><div class="fig__cap">{esc(ch.get("cap") or "互证图")}</div>\n'
+            f'{chart_svg(ch, i)}      </div>\n')
     body = (
         '    <div class="grid g-half g-2 rv a-start">\n'
         f'      <div class="tbl-wrap"><table><thead><tr>{th}</tr></thead><tbody>{trs}</tbody></table></div>\n'
-        f'      <div class="fig"><div class="fig__cap">{esc(ch.get("cap") or "互证图")}</div>\n'
-        f'{chart_svg(ch, i)}      </div>\n'
+        f'{fig}'
         '    </div>\n')
     return wrap(i, 'halftable', body, sec)
 
@@ -800,8 +857,10 @@ def render_body(model: dict) -> str:
             title = ag[1] if isinstance(ag, (list, tuple)) and len(ag) > 1 else ''
             desc = ag[2] if isinstance(ag, (list, tuple)) and len(ag) > 2 else ''
             href_i = chapter_first.get(str(num).zfill(2)) or chapter_first.get(str(num)) or gi
+            # 锚点与 open_sec 同源：该页有 anchor 则链到命名锚点
+            href_id = sec_anchor(href_i, secs[href_i - 1] if 0 < href_i <= len(secs) else {})
             lis.append(
-                f'      <li class="agenda__i"><a class="agenda__a" href="#s{href_i}">'
+                f'      <li class="agenda__i"><a class="agenda__a" href="#{href_id}">'
                 f'<span class="agenda__n">{esc(num)}</span>'
                 f'<span><span class="agenda__t">{esc(title)}</span>'
                 f'<div class="agenda__d">{esc(desc)}</div></span></a></li>')
@@ -822,7 +881,9 @@ def render_body(model: dict) -> str:
             sec = dict(sec)
             sec['exhibitNo'] = ex_n
         fn = RENDERERS.get(t, r_points)
-        if is_research_exhibit:
+        if is_research_exhibit and t != 'halftable':
+            # halftable 在 research 下仍走 r_halftable（表+图），仅借 exhibitNo 加 Exhibit 徽标；
+            # 统一走 r_exhibit 会静默丢弃 table（内容覆盖率门禁捕获，0.2.0 修）。
             fn = r_exhibit
         try:
             parts.append(fn(i, sec))

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

@@ -113,7 +113,7 @@ CHART_CYCLE = CHART_CORE  # 轮换默认序列（骨架示范「图要选对」
 _SCAFFOLD = (LC.get('charts') or {}).get('scaffold') or {}
 if not _SCAFFOLD.get('viewBoxHeight') or not _SCAFFOLD.get('infoTypes'):
     # 启动自检：单源缺键时立刻失败，防「静默退回默认值 180」的窗口期
-    print('错误: layout-constants.json 缺 charts.scaffold.viewBoxHeight/infoTypes'
+    print('错误：layout-constants.json 缺 charts.scaffold.viewBoxHeight/infoTypes'
           '（骨架尺寸单源不完整；补单源后先跑 sync_runtime.py）', file=sys.stderr)
     sys.exit(2)
 CHART_VIEWBOX = dict(_SCAFFOLD.get('viewBoxHeight') or {})

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

@@ -301,10 +301,10 @@ def inject(path: Path, pat: re.Pattern, repl: str, label: str) -> bool:
     try:
         src = path.read_text(encoding='utf-8')
     except OSError as e:
-        print(f'错误: 无法读取 {path.name}: {e}')
+        print(f'错误： 无法读取 {path.name}: {e}')
         return False
     if not pat.search(src):
-        print(f'错误: {path.name} 缺少 {label} 标记块')
+        print(f'错误： {path.name} 缺少 {label} 标记块')
         return False
     path.write_text(pat.sub(lambda m: repl, src, count=1), encoding='utf-8')
     return True
@@ -312,32 +312,32 @@ def inject(path: Path, pat: re.Pattern, repl: str, label: str) -> bool:
 
 def main() -> int:
     if not LC.exists():
-        print(f'错误: 找不到 {LC}')
+        print(f'错误： 找不到 {LC}')
         return 2
     try:
         lc = json.loads(LC.read_text(encoding='utf-8'))
     except UnicodeDecodeError as e:
-        print(f'错误: {LC.name} 不是合法 UTF-8: {e}')
+        print(f'错误： {LC.name} 不是合法 UTF-8: {e}')
         return 2
     except json.JSONDecodeError as e:
-        print(f'错误: {LC.name} 不是合法 JSON: {e}')
+        print(f'错误： {LC.name} 不是合法 JSON: {e}')
         return 2
     except OSError as e:
-        print(f'错误: 无法读取 {LC}: {e}')
+        print(f'错误： 无法读取 {LC}: {e}')
         return 2
     if not MS.exists():
-        print(f'错误: 找不到 {MS}（DSL schema 单源）')
+        print(f'错误： 找不到 {MS}（DSL schema 单源）')
         return 2
     try:
         ms = json.loads(MS.read_text(encoding='utf-8'))
     except UnicodeDecodeError as e:
-        print(f'错误: {MS.name} 不是合法 UTF-8: {e}')
+        print(f'错误： {MS.name} 不是合法 UTF-8: {e}')
         return 2
     except json.JSONDecodeError as e:
-        print(f'错误: {MS.name} 不是合法 JSON: {e}')
+        print(f'错误： {MS.name} 不是合法 JSON: {e}')
         return 2
     except OSError as e:
-        print(f'错误: 无法读取 {MS}: {e}')
+        print(f'错误： 无法读取 {MS}: {e}')
         return 2
     ok = True
 
@@ -345,13 +345,13 @@ def main() -> int:
     try:
         src = PE.read_text(encoding='utf-8')
     except OSError as e:
-        print(f'错误: 无法读取 {PE}: {e}')
+        print(f'错误： 无法读取 {PE}: {e}')
         return 1
     if not CONST_PAT.search(src):
-        print('错误: assets/pptx-export.js 缺少 __TOPPPT_CONSTANTS__ 标记块')
+        print('错误： assets/pptx-export.js 缺少 __TOPPPT_CONSTANTS__ 标记块')
         return 1
     if not SCHEMA_PAT.search(src):
-        print('错误: assets/pptx-export.js 缺少 __TOPPPT_SCHEMA__ 标记块')
+        print('错误： assets/pptx-export.js 缺少 __TOPPPT_SCHEMA__ 标记块')
         return 1
     block = build_const_block(lc)
     PE.write_text(CONST_PAT.sub(lambda m: block, src), encoding='utf-8')
@@ -370,7 +370,7 @@ def main() -> int:
 
     # ② 公共片段源
     if not ENGINE.exists() or not UI.exists():
-        print(f'错误: 缺少公共片段 {ENGINE} / {UI}')
+        print(f'错误： 缺少公共片段 {ENGINE} / {UI}')
         return 1
     engine_css = ENGINE.read_text(encoding='utf-8').rstrip('\n')
     ui_js = UI.read_text(encoding='utf-8').rstrip('\n')

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

@@ -138,6 +138,7 @@ SLIDE_RE = re.compile(r"ppt/slides/slide(\d+)\.xml$")
 _PROBE_SKIP_KEYS = {
     "colors", "color", "icon", "href", "id", "type", "exhibitNo", "max", "unit",
     "hint", "src", "alt", "fit", "layout", "placeholder", "ratio", "dataTable",
+    "variant",  # 版式变体注册值（bento-grid/timeline/2-col-feature）不渲染为文本
 }
 
 

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

@@ -4,6 +4,7 @@
 TopPPT HTML· HTML 报告质量校验（交付闭环）
 用法:
     python validate_report.py <报告.html> [--strict] [--layout-qa] [--json]
+    python validate_report.py --help
 
 输出每项 PASS/FAIL，结尾给汇总与结论；任一 FAIL 时退出码为 1（--strict 时 WARN 也计失败）。
 --json 以 JSON 输出全部检查结果（供脚本/流水线读取）。
@@ -30,6 +31,8 @@ import re
 import json
 import base64
 import hashlib
+import html as _html
+import unicodedata
 from typing import Optional
 from html.parser import HTMLParser
 from pathlib import Path
@@ -370,6 +373,155 @@ def _check_bands(txt, chk, mode="presentation"):
         f"{bad_grids} 处未对齐" if bad_grids else "", level="WARN")
 
 
+def _icon_pack_names():
+    """图标包合法名集合（assets/icons/index.json）；读不到时返回 None（跳过存在性检查）。"""
+    try:
+        idx = json.loads((Path(__file__).resolve().parent.parent / 'assets' / 'icons'
+                          / 'index.json').read_text(encoding='utf-8'))
+        return set((idx.get('icons') or {}).keys())
+    except OSError:
+        return None
+
+
+def _check_icon_refs(txt, chk):
+    """图标引用存在性：data-icon / icon: 标记引用了包外图标 → WARN（不 FAIL）。"""
+    names = _icon_pack_names()
+    if names is None:
+        return
+    # 只扫渲染正文：去掉 script/style/注释与嵌入模型 JSON，避免代码与文档示例误报
+    body = re.sub(r'<script[\s\S]*?</script>', '', txt, flags=re.I)
+    body = re.sub(r'<style[\s\S]*?</style>', '', body, flags=re.I)
+    body = re.sub(r'<!--[\s\S]*?-->', '', body)
+    body = re.sub(r'window\.REPORT_MODEL\s*=\s*\{[\s\S]*?\n\};', '', body)
+    refs = set(re.findall(r'data-icon="([^"]+)"', body))
+    refs |= set(re.findall(r'icon:([\u4e00-\u9fa5A-Za-z0-9_-]+)', body))
+    # 排除 hydrate 占位与 CSS 类名噪声：只看真实引用上下文
+    bad = sorted(r for r in refs if r not in names and not r.startswith('{{'))
+    chk("图标引用存在（assets/icons 包内）", not bad,
+        f"未知图标: {', '.join(bad[:6])}{'…' if len(bad) > 6 else ''}（{len(bad)} 个）" if bad else "",
+        level="WARN")
+
+
+# ── 内容覆盖率（0.2.0）：版式不得以丢文字为代价美化 ──
+# 口径：REPORT_MODEL 可见文本串（去重、归一化）有多少字符能在渲染后 HTML 可见文本中找到；
+# <95% → WARN（只报告，不 FAIL；长串按 8 字窗口部分计分，避免数字重排/截断误杀）。
+_COV_SKIP_KEYS = {
+    # 元字段（不渲染为正文）
+    "style", "theme", "mode", "type", "variant", "icon", "color", "colors",
+    "src", "href", "id", "layout", "datatable", "dataTable", "font", "fontface",
+    "exhibitno", "exhibitNo", "columns", "max", "min", "unit", "ratio", "fit",
+    "align", "width", "height", "placeholder", "alt", "target", "rel", "dir",
+    "lang", "charset", "defer", "async", "media",
+    "hint",  # 搭建期给智能体的指令（如 image.hint），不是读者正文
+}
+_COV_URL_RE = re.compile(r'^(https?://|www\.|data:|#)', re.I)
+_COV_COLOR_RE = re.compile(r'^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$')
+# 纯小写 ASCII 标识符（无空格/CJK/大写）：渲染器语义 flag（如 "focus"），不是正文
+_COV_FLAG_RE = re.compile(r'^[a-z][a-z0-9_-]*$')
+# 信息图页型（r_info 故意留"按 infographics 规格绘制"占位、PPTX 走形状通道）：
+# 其 chart 数据子树不计入覆盖率（数据在模型与 PPTX 中完整，仅 HTML 待定制信息图）
+_COV_INFO_TYPES = {'sankey', 'treemap', 'boxplot', 'network', 'marimekko', 'streamgraph'}
+_COV_INFO_DATA_KEYS = {'chart', 'labels', 'values', 'groups', 'nodes', 'links', 'edges', 'data',
+                       'series', 'dataset', 'cols', 'rows', 'cells'}
+_COV_MIN_RATIO = 0.95  # 覆盖率下限（layout-constants qualityGates.contentCoverage 可覆写）
+
+
+def _norm_cov(s: str) -> str:
+    s = unicodedata.normalize('NFKC', s)
+    s = re.sub(r'(?<=\d),(?=\d)', '', s)  # 千分位 1,000 → 1000（中文逗号保留）
+    s = re.sub(r'\s+', '', s)
+    # 标点不计入：内容在、标点异（： vs 无、（） vs 无）不算丢失；比的是信息不是排印
+    s = ''.join(c for c in s if not unicodedata.category(c).startswith('P'))
+    return s
+
+
+def _model_cov_strings(model) -> list:
+    """从 REPORT_MODEL 递归抽取候选正文串（去重、保序）。"""
+    out, seen = [], set()
+
+    def walk(node, skip_sub=False):
+        if isinstance(node, dict):
+            # 信息图页型：chart 数据子树是故意占位（r_info），不计入
+            info_data = isinstance(node.get('type'), str) and node.get('type').lower() in _COV_INFO_TYPES
+            for k, v in node.items():
+                kl = str(k).lower()
+                if kl in _COV_SKIP_KEYS or str(k).startswith('data-'):
+                    continue
+                if info_data and kl in _COV_INFO_DATA_KEYS:
+                    continue
+                walk(v)
+        elif isinstance(node, (list, tuple)):
+            for v in node:
+                walk(v)
+        elif isinstance(node, str):
+            t = node.strip()
+            if len(t) < 4 or _COV_URL_RE.match(t) or _COV_COLOR_RE.match(t):
+                return
+            if _COV_FLAG_RE.match(t):
+                return  # 渲染器语义 flag（如 focus），非正文
+            if t not in seen:
+                seen.add(t)
+                out.append(t)
+
+    walk(model)
+    return out
+
+
+def _visible_cov_text(txt: str) -> str:
+    """渲染后可见文本：剔 script（含 REPORT_MODEL JSON 本体）/style/注释/标签后归一化。"""
+    t = re.sub(r'<script[\s\S]*?</script>', '', txt, flags=re.I)
+    t = re.sub(r'<style[\s\S]*?</style>', '', t, flags=re.I)
+    t = re.sub(r'<!--[\s\S]*?-->', '', t)
+    t = re.sub(r'<[^>]+>', '', t)
+    return _norm_cov(_html.unescape(t))
+
+
+def _cov_credit(cand: str, rendered: str) -> float:
+    """候选串的字符计分：整串命中按全长；否则按 8 字窗口命中率折算。"""
+    n = _norm_cov(cand)
+    if not n:
+        return 0.0
+    if n in rendered:
+        return float(len(n))
+    if len(n) <= 12:
+        return 0.0
+    win, hits, total = 8, 0, 0
+    for i in range(0, len(n), win):
+        total += 1
+        if n[i:i + win] in rendered:
+            hits += 1
+    return len(n) * hits / total if total else 0.0
+
+
+def _check_content_coverage(txt, chk, model) -> None:
+    """模型文本 → 渲染文本覆盖率（只 WARN）。"""
+    if not isinstance(model, dict):
+        return
+    try:
+        min_ratio = float((load_constants().get("qualityGates") or {}).get("contentCoverage")
+                          or _COV_MIN_RATIO)
+    except Exception:
+        min_ratio = _COV_MIN_RATIO
+    cands = _model_cov_strings(model)
+    if not cands:
+        return
+    rendered = _visible_cov_text(txt)
+    total = sum(len(_norm_cov(c)) for c in cands)
+    if not total:
+        return
+    miss = []
+    got = 0.0
+    for c in cands:
+        cr = _cov_credit(c, rendered)
+        got += cr
+        if cr < len(_norm_cov(c)) * 0.5:
+            miss.append(c[:24])
+    ratio = got / total
+    chk(f"内容覆盖率（模型文本→渲染文本 ≥{min_ratio:.0%}）", ratio >= min_ratio,
+        f"覆盖率 {ratio:.1%}（{len(cands)} 串），疑似丢失: {'；'.join(miss[:3])}" if ratio < min_ratio else "",
+        level="WARN")
+
+
 def _check_icons(txt, chk):
     """图标使用：长报告不应全文无图标；含 ≥2 张卡的内容页应有 .card__ico（WARN）。"""
     if len(_bands(txt)) < 6:
@@ -1630,6 +1782,9 @@ def main():
     if len(sys.argv) < 2:
         print(__doc__)
         return 2
+    if sys.argv[1] in ('-h', '--help'):
+        print(__doc__)
+        return 0
     path = Path(sys.argv[1])
     strict = '--strict' in sys.argv
     as_json = '--json' in sys.argv
@@ -1797,8 +1952,10 @@ def main():
     _check_mode_layouts(txt, chk, mode)
     if mode != 'architecture':
         _check_icons(txt, chk)
+        _check_icon_refs(txt, chk)
     _check_pptx_export(txt, chk)
     model = _check_model_consistency(txt, chk, mode, style)
+    _check_content_coverage(txt, chk, model)
     _check_type_features(txt, chk, model)
     _check_exhibits(txt, chk, mode)
     _check_research_extras(txt, chk, mode)

package/topmind-cover/README.en.md

@@ -4,15 +4,15 @@
 
 A reusable skill for generating cover art for X long-form posts and WeChat articles. Goal: **striking, eye-catching, theme-focused**.
 
-- Version: **v0.1.0** (same tag as `@topmindspace/tms-skills@0.3.6`)
+- Version: **v0.2.0** (same tag as `@topmindspace/tms-skills@0.4.1`)
 
 ## Style gallery
 
 <p align="center">
-  <img src="https://github.com/topmindspace/tms-skills/raw/main/topmind-cover/assets/examples/overview.png" alt="topmind-cover · 8 cover-style overview" width="960" />
+  <img src="https://github.com/topmindspace/tms-skills/raw/main/topmind-cover/assets/examples/overview.png" alt="topmind-cover · 11 cover-style overview" width="960" />
 </p>
 
-8 styles (viral dry-goods / giant-type manifesto / brand launch / tutorial steps / fun IP / news flash / minimalist / editorial magazine): use cases, palette stories, abstract design principles, and Chinese+English prompt recipes in [`references/cover-styles.md`](./references/cover-styles.md); full-size per-style shots in [`assets/examples/`](./assets/examples/).
+11 styles (clean white / background blur / paper collage / news flash / giant-type manifesto / tutorial steps / minimalist / editorial magazine / viral dry-goods / brand launch / fun IP, light-first ordering): use cases, palette stories, abstract design principles, and Chinese+English prompt recipes in [`references/cover-styles.md`](./references/cover-styles.md); full-size per-style shots in [`assets/examples/`](./assets/examples/).
 
 ## Install
 
@@ -22,7 +22,7 @@ npx @topmindspace/tms-skills install topmind-cover
 
 ## Usage
 
-0. **Pick a style**: choose 1 of 8 styles from `references/cover-styles.md` by topic → check the example image to confirm the visual language.
+0. **Pick a style**: choose 1 of 11 styles from `references/cover-styles.md` by topic (light-first) → check the example image to confirm the visual language.
 1. **Refine the title**: lock the title copy first (usually ≤ 10 chars) using that style's title rules; rewrite until it lands — no drawing yet.
 2. **Composition brief**: one-sentence brief (theme / audience / mood / visual metaphor / palette direction) before composing the prompt.
 3. Input: article title + 3 theme keywords + platform (x / wechat / both, default both).