@topmindspace/tms-skills 0.1.0

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

@@ -0,0 +1,307 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""TopPPT HTML · 门禁反向验证（故障注入）
+
+校验器最容易退化成「只会说 OK 的摆设」。本脚本往合格产物里**注入已知缺陷**，
+断言对应门禁必须报错——门禁抓不到即视为失败。
+
+覆盖：
+  N1  Exhibit 框漏编号（旧实现只校验已编号者的连续性 → 静默通过）
+  N2  参考资料两位数编号错配（旧正则 `ref-\\d` 两侧同时落空 → 静默通过）
+  N3  参考资料编号跳号
+  N4  PPTX 演讲者备注被剔离（dataTable=notes 声称数据入备注，不核对就只是一句承诺）
+  N5  模型图表数值篡改（cross_verify 数值核对）
+  N6  行动标题判断词鉴别力（正则本身）
+  N7  PPTX 字号越出比例尺
+  N8  data-chart 未登记类型（登记表白名单）
+  N9  图表多样性塌陷（全篇压成同型 → 不同类型数 < 模式下限）
+  N10 图片外链（零外链铁律）
+  N11 待核实有标色无图例（.tbd 必须配 .tbd-legend/.flagbar）
+  N12 模型 theme 与 data-theme 矛盾
+  N13 模型 mode 与 data-mode 矛盾
+  N14 内部锚点断裂（链接目标 id 不存在）
+
+用法: python scripts/negative_tests.py
+"""
+from __future__ import annotations
+
+import json
+import re
+import subprocess
+import sys
+import zipfile
+from pathlib import Path
+
+try:
+    sys.stdout.reconfigure(encoding='utf-8', errors='replace')
+except Exception:
+    pass
+
+ROOT = Path(__file__).resolve().parent.parent
+OUT = ROOT / 'dist' / 'negtest'
+PY = sys.executable
+
+
+def run_validate(path: Path) -> tuple[int, str]:
+    r = subprocess.run([PY, str(ROOT / 'scripts' / 'validate_report.py'), str(path), '--strict'],
+                       capture_output=True, text=True, encoding='utf-8', errors='replace')
+    return r.returncode, (r.stdout or '') + (r.stderr or '')
+
+
+def expect_fail(name: str, path: Path, keyword: str) -> bool:
+    code, out = run_validate(path)
+    # --strict 下 WARN 同样计失败（退出码 1），故 [WARN] 行也算「门禁抓到」
+    hit = [ln for ln in out.splitlines()
+           if keyword in ln and ('[FAIL]' in ln or '[WARN]' in ln)]
+    ok = code != 0 and bool(hit)
+    print(f'  [{"OK" if ok else "FAIL"}] {name}')
+    if hit:
+        print(f'        抓到: {hit[0].strip()[:120]}')
+    elif not ok:
+        print(f'        门禁未触发（期望 FAIL 含「{keyword}」）')
+    return ok
+
+
+def main() -> int:
+    base = ROOT / 'assets' / 'examples' / '2026-09-09-research-mckinsey.html'
+    if not base.exists():
+        print(f'SKIP：基准示例缺失 {base}')
+        return 0
+    txt = base.read_text(encoding='utf-8')
+    OUT.mkdir(parents=True, exist_ok=True)
+
+    code, out = run_validate(base)
+    if code != 0:
+        print('[FAIL] 基准示例本身未通过 strict，反向验证失去意义')
+        return 1
+    print('基准示例 strict 通过，开始故障注入：')
+
+    cases: list[tuple[str, str, str]] = []
+
+    # N1 抹掉一个 Exhibit 编号（框仍在）
+    cases.append(('N1 Exhibit 框漏编号',
+                  txt.replace('class="exhibit__no"', 'class="exhibit__no--x"', 1),
+                  'Exhibit 框均已编号'))
+
+    # N2 参考资料改成两位数编号，与正文引用错配
+    cases.append(('N2 引用编号两位数错配',
+                  re.sub(r'id="ref-1"', 'id="ref-10"', txt, count=1),
+                  '双向对齐'))
+
+    # N3 编号跳号（两侧同时改，集合仍对齐，但 1..N 不连续）
+    t3 = txt.replace('ref-2"', 'ref-9"')
+    cases.append(('N3 参考资料编号跳号', t3, '编号连续'))
+
+    # N8 data-chart 用了登记表外的类型
+    cases.append(('N8 图表类型未登记',
+                  txt.replace('data-chart="hbar"', 'data-chart="hbarx"', 1),
+                  '登记表内'))
+
+    # N9 图表多样性塌陷（全部压成 bar → 不同类型数 1 < research 下限 6）
+    t9 = txt
+    for ct in ('hbar', 'donut', 'waterfall', 'sankey', 'treemap', 'boxplot',
+               'network', 'marimekko', 'streamgraph', 'gantt', 'rose', 'candlestick'):
+        t9 = t9.replace(f'data-chart="{ct}"', 'data-chart="bar"')
+    cases.append(('N9 图表多样性塌陷', t9, '图表多样性'))
+
+    # N10 外链图片（零外链铁律）
+    cases.append(('N10 图片外链',
+                  txt.replace('</body>',
+                              '<img src="https://example.com/x.png" alt="外链注入"></body>', 1),
+                  '图片源无外链'))
+
+    # N11 待核实有标色无图例（改名不得包含原串——校验是子串判断）
+    t11 = txt.replace('tbd-legend', 'tbd-leg').replace('flagbar', 'flag-bar')
+    cases.append(('N11 待核实无图例', t11, '待核实标注'))
+
+    # N12 模型 theme 与页面 data-theme 矛盾
+    cases.append(('N12 模型主题不一致',
+                  txt.replace('"theme": "light"', '"theme": "dark"', 1),
+                  'data-theme 一致'))
+
+    # N13 模型 mode 与页面 data-mode 矛盾
+    cases.append(('N13 模型模式不一致',
+                  txt.replace('"mode": "research"', '"mode": "presentation"', 1),
+                  'data-mode 一致'))
+
+    # N14 内部锚点断裂（链接目标 id 不存在）
+    cases.append(('N14 锚点断裂',
+                  txt.replace('href="#s1"', 'href="#s404"'),
+                  '锚点闭环'))
+
+    # N15 HTML 标签泄漏进可见文本（截图级：转义标签当字面量显示）
+    cases.append(('N15 标签泄漏',
+                  txt.replace('</p>',
+                              ' &lt;a class="cite" href="#ref-1"&gt;[1]&lt;/a&gt;。</p>', 1),
+                  'HTML_TAG_IN_TEXT'))
+
+    # N16 极偏 donut（0.5% vs 99.5% 应改 KPI，禁环图）
+    t16 = txt
+    if '"type": "donut"' in t16 or '"type":"donut"' in t16:
+        t16 = re.sub(
+            r'("type"\s*:\s*"donut"[\s\S]{0,200}?"values"\s*:\s*\[)[^\]]*(\])',
+            r'\g<1>0.5, 99.5\g<2>', t16, count=1)
+        cases.append(('N16 极偏 donut', t16, 'CHART_SKEW'))
+
+    # N17 模型字段夹带 HTML 标签（extract 净化 + validate 扫描 REPORT_MODEL）
+    t17 = re.sub(
+        r'("soWhat"\s*:\s*")',
+        r'\g<1><a class=\\"cite\\" href=\\"#ref-1\\">[1]</a> ',
+        txt, count=1)
+    if t17 == txt:
+        t17 = txt.replace(
+            '"footnote":',
+            '"footnote": "<strong>x</strong> ', 1)
+    cases.append(('N17 模型夹带标签', t17, 'HTML_TAG_IN_TEXT'))
+
+    ok = True
+    for name, content, keyword in cases:
+        if content == txt:
+            print(f'  [SKIP] {name}（基准示例无对应结构）')
+            continue
+        p = OUT / (name.split()[0] + '.html')
+        p.write_text(content, encoding='utf-8')
+        ok = expect_fail(name, p, keyword) and ok
+
+    ok = _pptx_notes_case() and ok
+    ok = _chart_data_case() and ok
+    ok = _title_pattern_case() and ok
+    ok = _font_scale_case() and ok
+
+    print('反向验证通过：注入的缺陷都被门禁抓住。' if ok
+          else '反向验证失败：存在抓不到的缺陷，门禁有假阴性。')
+    return 0 if ok else 1
+
+
+def _font_scale_case() -> bool:
+    """N7：往 PPTX 里塞一个比例尺外的字号 → FONT_SIZE_OFF_SCALE 必须报。"""
+    name = '2026-09-09-research-mckinsey'
+    src = ROOT / 'dist' / 'regression' / f'{name}.pptx'
+    model = ROOT / 'assets' / 'examples' / f'{name}.model.json'
+    if not src.exists() or not model.exists():
+        print('  [SKIP] N7 字号越出比例尺（需先跑 regression）')
+        return True
+    out = OUT / 'N7-off-scale.pptx'
+    patched = False
+    with zipfile.ZipFile(src) as zin, zipfile.ZipFile(out, 'w', zipfile.ZIP_DEFLATED) as zout:
+        for item in zin.infolist():
+            data = zin.read(item.filename)
+            if not patched and item.filename == 'ppt/slides/slide4.xml':
+                text = data.decode('utf-8')
+                new = re.sub(r'sz="\d+"', 'sz="1234"', text, count=1)  # 12.34pt：任何档位都没有
+                if new != text:
+                    data = new.encode('utf-8')
+                    patched = True
+            zout.writestr(item, data)
+    if not patched:
+        print('  [SKIP] N7 字号越出比例尺（未找到可改写的 sz 属性）')
+        return True
+    report = OUT / 'N7.json'
+    subprocess.run([PY, str(ROOT / 'scripts' / 'validate_pptx.py'), str(out),
+                    '--strict', '--model=' + str(model), '--json-out', str(report)],
+                   capture_output=True, text=True, encoding='utf-8', errors='replace')
+    try:
+        data = json.loads(report.read_text(encoding='utf-8'))
+    except (OSError, json.JSONDecodeError):
+        print('  [FAIL] N7 字号越出比例尺：校验报告不可解析')
+        return False
+    codes = {i.get('code') for i in (data.get('errors') or []) + (data.get('warnings') or [])}
+    ok = 'FONT_SIZE_OFF_SCALE' in codes
+    print(f'  [{"OK" if ok else "FAIL"}] N7 字号越出比例尺')
+    if not ok:
+        print(f'        门禁未触发（期望 FONT_SIZE_OFF_SCALE，实际 {sorted(codes)[:6]}）')
+    return ok
+
+
+def _title_pattern_case() -> bool:
+    """N6：主题词式长标题必须被判为「无判断信号」，结论句标题必须放行。"""
+    lc = json.loads((ROOT / 'scripts' / 'layout-constants.json').read_text(encoding='utf-8'))
+    pat = ((lc.get('contentQuality') or {}).get('researchTitle') or {}).get('judgmentPattern')
+    if not pat:
+        print('  [SKIP] N6 行动标题判断词（未配置 judgmentPattern）')
+        return True
+    topic = ['智能体平台的应用架构与技术选型说明', '关于数据治理需求的整体情况介绍',
+             '企业知识库建设的相关背景与范围', '平台能力地图与模块组成一览表',
+             '项目实施过程中的应急预案汇总', '面向未来的技术路线图规划说明']
+    claim = ['投入产出比在第 3 季度首次转正', '三成团队已把智能体纳入日常流程',
+             '数据质量是当前最大的落地瓶颈', '推理成本一年内下降 62%',
+             '从试点到规模化：关键卡在治理', '自建方案的总成本高于采购方案']
+    leaked = [t for t in topic if re.search(pat, t)]
+    hurt = [t for t in claim if not re.search(pat, t)]
+    ok = not leaked and not hurt
+    print(f'  [{"OK" if ok else "FAIL"}] N6 行动标题判断词鉴别力'
+          f'（漏放主题词 {len(leaked)}/{len(topic)} · 误伤结论句 {len(hurt)}/{len(claim)}）')
+    for t in (leaked + hurt)[:3]:
+        print(f'        {t}')
+    return ok
+
+
+def _chart_data_case() -> bool:
+    """N5：篡改模型里的图表数值 → cross_verify 的数值核对必须报不符。"""
+    name = '2026-09-09-research-mckinsey'
+    pptx = ROOT / 'dist' / 'regression' / f'{name}.pptx'
+    mp = ROOT / 'assets' / 'examples' / f'{name}.model.json'
+    if not pptx.exists() or not mp.exists():
+        print('  [SKIP] N5 图表数值篡改（需先跑 regression）')
+        return True
+    sys.path.insert(0, str(ROOT / 'scripts'))
+    try:
+        from pptx import Presentation           # noqa: PLC0415
+        import cross_verify as CV               # noqa: PLC0415
+    except ImportError:
+        print('  [SKIP] N5 图表数值篡改（python-pptx 未安装）')
+        return True
+    model = json.loads(mp.read_text(encoding='utf-8'))
+    touched = False
+    for sec in (model.get('sections') or []):
+        c = CV._model_chart(sec) if isinstance(sec, dict) else None
+        if c and isinstance(c.get('values'), list) and c['values']:
+            c['values'] = [(v + 777) if isinstance(v, (int, float)) else v for v in c['values']]
+            touched = True
+            break
+    if not touched:
+        print('  [SKIP] N5 图表数值篡改（基准模型无可改图表）')
+        return True
+    issues = CV.chart_data_verify(Presentation(str(pptx)), model, name)
+    ok = bool(issues)
+    print(f'  [{"OK" if ok else "FAIL"}] N5 模型图表数值被篡改')
+    if ok:
+        print(f'        抓到: {issues[0][:120]}')
+    else:
+        print('        门禁未触发（数值核对形同虚设）')
+    return ok
+
+
+def _pptx_notes_case() -> bool:
+    """N4：剥离演讲者备注 → dataTable=notes 的图表数据不可追溯，必须被 strict 抓住。"""
+    name = '2026-09-09-research-mckinsey'
+    src = ROOT / 'dist' / 'regression' / f'{name}.pptx'
+    model = ROOT / 'assets' / 'examples' / f'{name}.model.json'
+    if not src.exists() or not model.exists():
+        print('  [SKIP] N4 备注剥离（需先跑 regression 生成 PPTX）')
+        return True
+    stripped = OUT / 'N4-no-notes.pptx'
+    with zipfile.ZipFile(src) as zin, zipfile.ZipFile(stripped, 'w', zipfile.ZIP_DEFLATED) as zout:
+        for item in zin.infolist():
+            if item.filename.startswith('ppt/notesSlides/'):
+                continue
+            zout.writestr(item, zin.read(item.filename))
+    report = OUT / 'N4.json'
+    subprocess.run([PY, str(ROOT / 'scripts' / 'validate_pptx.py'), str(stripped),
+                    '--strict', '--model=' + str(model), '--json-out', str(report)],
+                   capture_output=True, text=True, encoding='utf-8', errors='replace')
+    try:
+        data = json.loads(report.read_text(encoding='utf-8'))
+    except (OSError, json.JSONDecodeError):
+        print('  [FAIL] N4 备注剥离：校验报告不可解析')
+        return False
+    codes = {i.get('code') for i in (data.get('errors') or []) + (data.get('warnings') or [])}
+    ok = 'MODEL_CHART_NOTES_MISSING' in codes
+    print(f'  [{"OK" if ok else "FAIL"}] N4 演讲者备注被剥离')
+    if not ok:
+        print(f'        门禁未触发（期望 MODEL_CHART_NOTES_MISSING，实际 {sorted(codes)[:6]}）')
+    return ok
+
+
+if __name__ == '__main__':
+    sys.exit(main())

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

@@ -0,0 +1,291 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""TopPPT HTML · 技能分发包打包器（发布前完整性校验 + 发布清单）
+
+用法:
+    python scripts/package_skill.py            # 校验 → 打包 → 写发布清单
+    python scripts/package_skill.py --check    # 只校验不打包（CI / 提交前自检）
+
+产物:
+    dist/top-ppt-html.zip            分发包（解压目录名 = 技能全名 top-ppt-html）
+    dist/top-ppt-html.manifest.json  发布清单（版本 / 条目 / 大小 / SHA-256），随包留档
+
+────────────────────────────────────────────────────────────────────────
+进包（= 技能运行与维护所需的最小完备集，缺一即校验失败）
+────────────────────────────────────────────────────────────────────────
+    SKILL.md                       技能入口（frontmatter + 触发边界 + 工作流 + 铁律）
+    README.md                      人类视角的简介 / 安装 / 开发 / 打包
+    package.json                   Node 依赖声明（pptxgenjs）与常用命令
+    assets/templates/              三份模式模板 + engine.css / ui.js（公共片段注入源）
+    assets/examples/               9 份示例 HTML + 9 份 REPORT_MODEL（复制起点 · 覆盖全部 9 风格）
+    assets/pptx-export.js          PPTX 预览运行时（注入源）
+    assets/style-gallery.html      风格 × 模式 × 亮暗主题交互画廊
+    assets/theme-overview*.png     4 张主题参考图（六项问询辅助）
+    references/*.md                15 篇规范（playbook.md = 唯一常读入口 L1；其余 L2 按需加载）
+    scripts/                         生成 / 校验 / 回归 / 维护工具（py + js + json 单源）
+    scripts/extract_snippet.py       L2 节级片段抽取（减少整读大规范）
+    scripts/layout_slots.json        页型布局 IR（高频页型语义槽位）
+
+────────────────────────────────────────────────────────────────────────
+不进包（构建产物 / 本地状态 / 缓存，与 .gitignore 口径一致）
+────────────────────────────────────────────────────────────────────────
+    dist/                          分发包与回归产物本身
+    report-assets/                 prepare_images.py 的产出（片段 / 模型对象）
+    render-compare/                render_compare.py 的渲染对照产物
+    node_modules/                  npm 依赖（安装期生成）
+    __pycache__/                   Python 缓存
+    IDE / 智能体本地状态目录                 IDE / 智能体本地状态（不入库、不分发）
+    scripts/_*                     下划线开头的临时脚本（用后即删）
+
+────────────────────────────────────────────────────────────────────────
+发布前校验（任一不过 → 退出码 1，不产出 zip）
+────────────────────────────────────────────────────────────────────────
+    · SKILL.md frontmatter 含 name / description；name 与分发包目录名一致；
+      description 为单行双引号字符串且 ≤ 1024 字符（平台截断阈值）
+    · 15 篇 references、3 份模式模板 + engine.css / ui.js、9 组示例、4 张参考图齐全
+    · 关键脚本齐全（单源注入 / 审计 / 示例重建 / 回归 / 双校验器 / 精导 / 打包）
+"""
+import fnmatch
+import hashlib
+import json
+import re
+import sys
+import zipfile
+from datetime import datetime, timezone
+from pathlib import Path
+
+try:
+    sys.stdout.reconfigure(encoding='utf-8', errors='replace')
+except Exception:
+    pass
+
+ROOT = Path(__file__).resolve().parent.parent
+NAME = 'top-ppt-html'                       # 技能全名 = 分发包顶层目录名 = SKILL.md name
+OUT = ROOT / 'dist' / f'{NAME}.zip'
+MANIFEST = ROOT / 'dist' / f'{NAME}.manifest.json'
+DESC_LIMIT = 1024
+# 版本唯一事实源 = layout-constants.json `version`（v8.3 起 frontmatter 不携带非标 version 键，
+# manifest 版本一律取 LC；frontmatter 若显式声明则以其为准——但不鼓励）
+try:
+    VERSION = str(json.loads(
+        (ROOT / 'scripts' / 'layout-constants.json').read_text(encoding='utf-8')).get('version') or '0.0')
+except (OSError, json.JSONDecodeError):
+    VERSION = '0.0'
+
+# 进包清单（显式枚举，缺一即失败）
+INCLUDE = [
+    'SKILL.md',
+    'README.md',
+    'package.json',
+    'assets/pptx-export.js',
+    'assets/style-gallery.html',
+    'assets/theme-overview.png',
+    'assets/theme-overview-presentation.png',
+    'assets/theme-overview-research.png',
+    'assets/theme-overview-architecture.png',
+    'assets/templates/*',
+    'assets/examples/*',
+    'references/*',
+    'scripts/*',
+    'evals/*',
+]
+
+# 出包规则（命中即跳过；与 .gitignore 口径一致）
+EXCLUDE = [
+    'scripts/_*',                 # 临时脚本
+    'scripts/__pycache__/*',
+    '**/__pycache__/*',
+    '**/node_modules/*',
+    '**/report-assets/*',
+    '**/render-compare/*',
+    '**/dist/*',
+    '**/.codebuddy/*',
+    '**/.h3caiwork/*',
+    '**/.playwright-mcp/*',
+    '**/.claude/*',
+    '**/.agents/*',
+    '**/.mimocode/*',
+    '**/OPTIMIZATION-PLAN.md',
+]
+
+# 必须齐全的关键文件（发布门禁）
+REQUIRED = [
+    'SKILL.md', 'README.md', 'package.json',
+    'assets/pptx-export.js', 'assets/style-gallery.html',
+    'assets/theme-overview.png', 'assets/theme-overview-presentation.png',
+    'assets/theme-overview-research.png', 'assets/theme-overview-architecture.png',
+    'assets/templates/presentation.html', 'assets/templates/research.html',
+    'assets/templates/architecture.html', 'assets/templates/engine.css',
+    'assets/templates/ui.js',
+    'references/playbook.md',
+    'references/modes.md', 'references/outline-design.md', 'references/design-system.md',
+    'references/styles.md', 'references/content-rules.md', 'references/components.md',
+    'references/charts.md',
+    'references/infographics.md', 'references/icons.md', 'references/pptx-export.md',
+    'references/high-fidelity.md', 'references/failure-modes.md',
+    'references/tech-design.md', 'references/industry-benchmark.md',
+    'scripts/env_probe.py', 'scripts/audit_docs.py', 'scripts/audit_skill.py',
+    'scripts/scaffold_report.py',
+    'scripts/sync_runtime.py', 'scripts/audit_styles.py', 'scripts/build_examples.py',
+    'scripts/regression.py', 'scripts/validate_report.py', 'scripts/validate_pptx.py',
+    'scripts/extract_model.py', 'scripts/build_pptx.js', 'scripts/gen_channel_a.js',
+    'scripts/cross_verify.py', 'scripts/prepare_images.py', 'scripts/probe_image_export.py',
+    'scripts/render_compare.py', 'scripts/capture_theme_overview.js', 'scripts/package_skill.py',
+    'scripts/layout-constants.json', 'scripts/model-schema.json', 'scripts/layout_slots.json',
+    'scripts/lib_layout_regions.js', 'scripts/extract_snippet.py', 'scripts/quality_gate.py',
+    'scripts/checks_html.py', 'scripts/section-file-map.json',
+    'scripts/measure_height.py', 'scripts/audit_css.py', 'scripts/negative_tests.py',
+    'references/components-atoms.md', 'references/layouts-research.md',
+    'references/layouts-architecture.md', 'references/layouts-combo.md',
+    'references/charts-basic.md', 'references/charts-extended.md', 'references/charts-discipline.md',
+    'references/design-system-engine.md',
+    'references/infographics-stats.md', 'references/infographics-structure.md',
+    'evals/prompts.csv', 'evals/run_evals.py', 'evals/rubric.schema.json',
+    'evals/trace.example.json',
+]
+
+# 必须达到最小数量的集合（名称含日期，故按数量校验）
+MIN_COUNTS = {
+    'assets/examples/*.html': 9,
+    'assets/examples/*.model.json': 9,
+    'references/*.md': 15,
+}
+
+
+def picked(rel: str) -> bool:
+    return any(rel == p or _match(rel, p) for p in EXCLUDE)
+
+
+def _match(rel: str, pat: str) -> bool:
+    if fnmatch.fnmatch(rel, pat):
+        return True
+    # '**/x/*' 需匹配任意深度
+    if pat.startswith('**/'):
+        tail = pat[3:]
+        return fnmatch.fnmatch(rel, tail) or fnmatch.fnmatch(rel, '*/' + tail)
+    return False
+
+
+def check_skill_md():
+    """frontmatter 门禁：name / description 必需，name 与包名一致，description ≤ 上限。"""
+    p = ROOT / 'SKILL.md'
+    if not p.exists():
+        return None, ['缺少 SKILL.md']
+    txt = p.read_text(encoding='utf-8')
+    if not txt.startswith('---'):
+        return None, ['SKILL.md 未以 YAML frontmatter（---）开头']
+    m = re.match(r'^---\s*\n(.*?)\n---\s*\n', txt, re.S)
+    if not m:
+        return None, ['SKILL.md frontmatter 未正确闭合']
+    fm = m.group(1)
+    errs = []
+    name_m = re.search(r'^name:\s*(\S+)\s*$', fm, re.M)
+    if not name_m:
+        errs.append('frontmatter 缺 name')
+    elif name_m.group(1) != NAME:
+        errs.append(f'frontmatter name={name_m.group(1)!r} 与分发包目录名 {NAME!r} 不一致')
+    desc_m = re.search(r'^description:\s*"(.*)"\s*$', fm, re.M)
+    if not desc_m:
+        errs.append('frontmatter 缺 description（须为单行双引号字符串）')
+        desc = ''
+    else:
+        desc = desc_m.group(1)
+        if len(desc) > DESC_LIMIT:
+            errs.append(f'description {len(desc)} 字符 > {DESC_LIMIT}')
+        if '<' in desc or '>' in desc:
+            errs.append('description 含尖括号（部分平台会拒载）')
+    ver_m = re.search(r'^version:\s*"?([\w.\-]+)"?\s*$', fm, re.M)
+    return {'name': NAME, 'description_len': len(desc),
+            'version': ver_m.group(1) if ver_m else VERSION}, errs
+
+
+def collect():
+    seen, files = set(), []
+    for pat in INCLUDE:
+        for h in sorted(ROOT.glob(pat)):
+            if not h.is_file():
+                continue
+            rel = h.relative_to(ROOT).as_posix()
+            if rel in seen or picked(rel):
+                continue
+            seen.add(rel)
+            files.append((rel, h))
+    return files
+
+
+def verify(files):
+    errs = []
+    have = {rel for rel, _ in files}
+    for rel in REQUIRED:
+        if rel not in have:
+            errs.append(f'缺必需文件: {rel}')
+    for pat, n in MIN_COUNTS.items():
+        got = len([r for r in have if _match(r, pat) or r == pat])
+        if got < n:
+            errs.append(f'{pat} 数量 {got} < {n}')
+    # 反向：不应出现的路径
+    for rel in have:
+        if rel.startswith('scripts/_') or '__pycache__' in rel or 'node_modules' in rel:
+            errs.append(f'不应进包: {rel}')
+    return errs
+
+
+def main():
+    check_only = '--check' in sys.argv[1:]
+
+    files = collect()
+    if not files:
+        print('错误：未收集到任何文件')
+        return 1
+    errs = verify(files)
+    meta, fm_errs = check_skill_md()
+    errs += fm_errs
+
+    print('── 发布前校验 ──')
+    print(f'  技能名 {NAME} · 版本 {meta.get("version") if meta else "?"} · '
+          f'description {meta.get("description_len") if meta else "?"} 字符')
+    print(f'  进包文件 {len(files)} 个')
+    if errs:
+        print('  校验失败：')
+        for e in errs:
+            print(f'    ✗ {e}')
+        return 1
+    print('  校验通过：必需文件齐全 · frontmatter 合规 · 无临时/缓存路径')
+
+    if check_only:
+        print('\n(--check 模式：仅校验，不打包)')
+        return 0
+
+    OUT.parent.mkdir(parents=True, exist_ok=True)
+    with zipfile.ZipFile(OUT, 'w', zipfile.ZIP_DEFLATED, compresslevel=9) as z:
+        for rel, h in files:
+            z.write(h, f'{NAME}/{rel}')
+
+    entries, total = [], 0
+    for rel, h in files:
+        raw = h.read_bytes()
+        total += len(raw)
+        entries.append({'path': rel, 'bytes': len(raw),
+                        'sha256': hashlib.sha256(raw).hexdigest()})
+    manifest = {
+        'skill': NAME,
+        'version': (meta or {}).get('version'),
+        'descriptionLength': (meta or {}).get('description_len'),
+        'builtAt': datetime.now(timezone.utc).strftime('%Y-%m-%dT%H:%M:%SZ'),
+        'zip': f'dist/{NAME}.zip',
+        'entries': len(entries),
+        'totalBytes': total,
+        'zipBytes': OUT.stat().st_size,
+        'files': entries,
+    }
+    MANIFEST.write_text(json.dumps(manifest, ensure_ascii=False, indent=2), encoding='utf-8')
+
+    print(f'\n── 打包完成 ──')
+    print(f'  {OUT}')
+    print(f'  条目 {len(entries)} 个 · 原始 {total/1024:.0f} KB · 压缩 {OUT.stat().st_size/1024:.0f} KB')
+    print(f'  {MANIFEST}（版本 / 条目 / SHA-256，随包留档）')
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main())