@topmindspace/tms-skills 0.1.0

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

@@ -0,0 +1,210 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+TopPPT HTML· 从 HTML 报告抽取 PPTX 内容模型
+用法:
+    python extract_model.py <报告.html> [输出.json]
+
+从报告的 window.REPORT_MODEL（JSON）抽取内容模型，供 build_pptx.js --model= 使用。
+保证 PPTX 与页面同源——模型即唯一事实源，不再两处维护。
+校验双端同源：页型字段与必填约束读 scripts/model-schema.json（与浏览器端 validateModel
+消费同一份 schema，经 sync_runtime.py 注入 assets/pptx-export.js，杜绝漂移）。
+含模型-正文一致性抽查（标题/agenda 条数/页数粗对齐），不一致打印警告（硬门禁在 validate_report.py）。
+"""
+import sys
+import re
+import json
+from pathlib import Path
+
+# Windows GBK 控制台兜底：强制 UTF-8 输出
+try:
+    sys.stdout.reconfigure(encoding='utf-8', errors='replace')
+    sys.stderr.reconfigure(encoding='utf-8', errors='replace')
+except Exception:
+    pass
+
+SCHEMA_PATH = Path(__file__).resolve().parent / 'model-schema.json'
+
+
+def load_schema():
+    """DSL schema 单源（model-schema.json）；与浏览器端 validateModel 同一份定义。"""
+    try:
+        return json.loads(SCHEMA_PATH.read_text(encoding='utf-8'))
+    except (OSError, json.JSONDecodeError) as e:
+        print(f"警告: 无法读取 schema 单源 {SCHEMA_PATH}: {e}")
+        return None
+
+
+def schema_get(obj, path):
+    cur = obj
+    for k in path.split('.'):
+        if cur is None or not isinstance(cur, dict):
+            return None
+        cur = cur.get(k)
+    return cur
+
+
+def schema_field_ok(sec, spec):
+    """spec = 'a.b:array' / 'a.b:str' / 'a.b'（真值检查）/ 'anyof:a|b:c'（任一满足）。"""
+    if spec.startswith('anyof:'):
+        return any(schema_field_ok(sec, alt) for alt in spec[len('anyof:'):].split('|') if alt)
+    m = re.match(r'^(.*?)(?::(array|str))?$', spec)
+    path, kind = m.group(1), m.group(2)
+    v = schema_get(sec, path)
+    if kind == 'array':
+        return isinstance(v, list) and len(v) > 0
+    if kind == 'str':
+        return isinstance(v, str) and bool(v.strip())
+    return bool(v)
+
+
+def validate_against_schema(model, schema):
+    """按 schema 单源校验模型；返回 (缺失列表, 警告列表)。与浏览器端 validateModel 同语义。"""
+    missing, warnings = [], []
+    if not schema:
+        return missing, warnings
+    ms = schema.get('model') or {}
+    for spec in ms.get('required', []):
+        if not schema_field_ok(model, spec):
+            missing.append(f"{spec}（顶层必填）")
+    mode = model.get('mode') or 'presentation'
+    ag = model.get('agenda') or []
+    ag_min = (ms.get('agendaMin') or {}).get(mode, 0)
+    if ag_min > 0 and len(ag) < ag_min:
+        missing.append(f"agenda（大纲 ≥{ag_min} 条）")
+    secs = model.get('sections') or []
+    if not isinstance(secs, list) or len(secs) < ms.get('sectionsMin', 1):
+        missing.append("sections（章节页 ≥1）")
+    page_types = schema.get('pageTypes') or {}
+    for i, sec in enumerate(secs if isinstance(secs, list) else []):
+        t = (sec.get('type') if isinstance(sec, dict) else None) or 'points'
+        defn = page_types.get(t)
+        if not defn:
+            missing.append(f"sections[{i}].type={t!r}（未知页型）")
+            continue
+        if not (isinstance(sec, dict) and sec.get('title')):
+            missing.append(f"sections[{i}].title（第 {i + 1} 章标题）")
+        for spec in defn.get('required', []):
+            if not schema_field_ok(sec, spec):
+                missing.append(f"sections[{i}].{spec}（{defn.get('label', t)}必填）")
+        if defn.get('modes') and mode not in defn['modes']:
+            warnings.append(f"sections[{i}] 页型 {t!r} 适用于 {'/'.join(defn['modes'])}，当前 mode={mode!r}")
+    if schema.get('modes') and model.get('mode') and model['mode'] not in schema['modes']:
+        warnings.append(f"mode={model['mode']!r} 未知，按 presentation 处理")
+    if secs and len(secs) < ms.get('sectionsRecommended', 3):
+        warnings.append(f"章节页仅 {len(secs)} 页，正式报告建议 ≥3")
+    if len(ag) > ms.get('agendaComfortMax', 16):
+        warnings.append(f"agenda {len(ag)} 条超出单页舒适上限，建议拆分")
+    return missing, warnings
+
+
+def main():
+    if len(sys.argv) < 2:
+        print(__doc__)
+        return 2
+    path = Path(sys.argv[1])
+    if not path.exists():
+        print(f"文件不存在: {path}")
+        return 2
+    txt = path.read_text(encoding='utf-8')
+
+    m = re.search(r'window\.REPORT_MODEL\s*=\s*(\{[\s\S]*?\})\s*;', txt)
+    if not m:
+        print("未找到 window.REPORT_MODEL —— 报告未内嵌内容模型。")
+        print("请按 references/pptx-export.md 在报告 <script> 中补齐模型后再抽取。")
+        return 1
+    raw = m.group(1)
+    try:
+        model = json.loads(raw)
+    except json.JSONDecodeError as e:
+        print(f"REPORT_MODEL 不是合法 JSON: {e}")
+        print("注意：模型必须是严格 JSON（双引号、无尾逗号、无注释）。")
+        return 1
+
+    # 模型字符串字段净化：禁止把 HTML 标签当纯文本写入（cite 只允许 [n]）。
+    # 泄漏标签会在 PPTX/预览里原样露出 <a class="cite"…>，属交付硬缺陷。
+    stripped = {'count': 0, 'samples': []}
+
+    def _scrub_assign(obj, path=''):
+        if isinstance(obj, dict):
+            for k in list(obj.keys()):
+                v = obj[k]
+                p = f'{path}.{k}' if path else k
+                if isinstance(v, str) and re.search(r'</?[a-zA-Z][^>]*>', v):
+                    obj[k] = re.sub(r'\s+', ' ', re.sub(r'</?[a-zA-Z][^>]*>', '', v)).strip()
+                    stripped['count'] += 1
+                    if len(stripped['samples']) < 5:
+                        stripped['samples'].append(p)
+                else:
+                    _scrub_assign(v, p)
+        elif isinstance(obj, list):
+            for i, v in enumerate(obj):
+                p = f'{path}[{i}]'
+                if isinstance(v, str) and re.search(r'</?[a-zA-Z][^>]*>', v):
+                    obj[i] = re.sub(r'\s+', ' ', re.sub(r'</?[a-zA-Z][^>]*>', '', v)).strip()
+                    stripped['count'] += 1
+                    if len(stripped['samples']) < 5:
+                        stripped['samples'].append(p)
+                else:
+                    _scrub_assign(v, p)
+
+    _scrub_assign(model)
+    if stripped['count']:
+        print(f"[净化] 剥离 {stripped['count']} 处模型字段中的 HTML 标签: {stripped['samples']}")
+        print("  注意：引用在模型里写 [n] 纯文本；HTML 正文才用 <a class=\"cite\">。禁止把标签写进模型。")
+
+    # 风格/模式/主题兜底：模型未写时取页面 data-style / data-mode / data-theme
+    if not model.get('style'):
+        sm = re.search(r'<html[^>]*data-style="([^"]+)"', txt)
+        if sm:
+            model['style'] = sm.group(1)
+    if not model.get('mode'):
+        mm = re.search(r'<html[^>]*data-mode="([^"]+)"', txt)
+        if mm:
+            model['mode'] = mm.group(1)
+    if not model.get('theme'):
+        tm = re.search(r'<html[^>]*data-theme="([^"]+)"', txt)
+        if tm:
+            model['theme'] = tm.group(1)
+
+    # schema 单源校验（与浏览器端 validateModel 同一份 model-schema.json）
+    schema = load_schema()
+    missing, schema_warn = validate_against_schema(model, schema)
+    if missing:
+        print(f"模型缺字段 {len(missing)} 项（导出的 PPTX 相应页面会为空或跳过）：")
+        for msg in missing:
+            print(f"  - {msg}")
+    for msg in schema_warn:
+        print(f"[schema 警告] {msg}")
+
+    # 模型-正文一致性抽查（标题 / agenda 条数 / 页数粗对齐）
+    issues = []
+    plain = re.sub(r'<[^>]+>', ' ', txt)
+    secs = model.get('sections') or []
+    miss_titles = [str(s.get('title'))[:14] for s in secs
+                   if s.get('title') and str(s.get('title')) not in plain]
+    if miss_titles:
+        issues.append(f"{len(miss_titles)} 个章节标题未在正文出现: {miss_titles[:3]}")
+    n_ag = len(model.get('agenda') or [])
+    n_html_ag = txt.count('class="agenda__a"')
+    if n_ag and n_html_ag and n_ag != n_html_ag:
+        issues.append(f"agenda 条数不一致: model={n_ag} 正文={n_html_ag}")
+    n_bands = len(re.findall(r'<section class="band', txt))
+    if secs and not (len(secs) + 3 <= n_bands <= len(secs) + 7):
+        issues.append(f"页数粗不匹配: 正文 {n_bands} 页 vs 模型 {len(secs)}+3~7")
+    for msg in issues:
+        print(f"[一致性警告] {msg}")
+
+    out = Path(sys.argv[2]) if len(sys.argv) > 2 else path.with_suffix('.model.json')
+    out.write_text(json.dumps(model, ensure_ascii=False, indent=2), encoding='utf-8')
+    n_sec = len(model.get('sections', []))
+    print(f"已抽取: {out}  (agenda {len(model.get('agenda', []))} 条 · sections {n_sec} 页 · style={model.get('style', 'business-blue')} · theme={model.get('theme', 'light')})")
+    if missing:
+        print("注意：模型不完整，正式交付前应回 AI 对话补全（页面预览模态含可复制提示词）。")
+    print("下一步：")
+    print(f'  NODE_PATH=<pptxgenjs 所在 node_modules> <node> scripts/build_pptx.js "报告.pptx" --model="{out}"')
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main())

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

@@ -0,0 +1,374 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""TopPPT HTML · L2 节级片段抽取器（减少整读 components.md / charts.md 的上下文成本）
+
+用法:
+    python scripts/extract_snippet.py --list
+    python scripts/extract_snippet.py --chart waterfall
+    python scripts/extract_snippet.py --page-type exhibit
+    python scripts/extract_snippet.py --file components.md --section 46
+    python scripts/extract_snippet.py --task research-evidence
+    python scripts/extract_snippet.py --task pptx-export
+
+设计:
+    智能体按「任务 → 只读相关节」取代码，而不是整文件读入 70KB+ 规范。
+    节边界用标题行识别；--task 走内置路由表（与 playbook.md §十 同源）。
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+try:
+    sys.stdout.reconfigure(encoding='utf-8', errors='replace')
+except Exception:
+    pass
+
+ROOT = Path(__file__).resolve().parent.parent
+REF = ROOT / 'references'
+LC = json.loads((ROOT / 'scripts' / 'layout-constants.json').read_text(encoding='utf-8'))
+# §编号 → 物理文件（components/charts 拆分后逻辑路由；单源 scripts/section-file-map.json）
+_SECTION_MAP_PATH = ROOT / 'scripts' / 'section-file-map.json'
+try:
+    SECTION_FILE_MAP = json.loads(_SECTION_MAP_PATH.read_text(encoding='utf-8'))
+except (OSError, json.JSONDecodeError):
+    SECTION_FILE_MAP = {}
+
+# 任务 → 建议只读的文件与节（与 references/playbook.md §十 保持一致）
+# 节号三种形态均可寻址：阿拉伯（46 / 46b / 8-1）、中文（三 / 一-b）、标题关键词（精导 / 速查）
+TASK_ROUTES = {
+    'research-evidence': {
+        'desc': 'research 证据页 / Exhibit / 密表',
+        'reads': [
+            ('components.md', ['36d', '46', '46c']),
+            ('playbook.md', ['三', '四']),
+        ],
+    },
+    'presentation-combo': {
+        'desc': '演示组合版式与卡片',
+        'reads': [
+            ('components.md', ['39', '40', '41', '42', '46', '46b', '46c']),
+            ('playbook.md', ['三', '四']),
+        ],
+    },
+    'architecture-diagram': {
+        'desc': '架构/泳道/分层',
+        'reads': [
+            ('components.md', ['37', '38', '38b']),
+            ('infographics.md', ['78', '79', '80']),
+            ('playbook.md', ['三', '七']),
+        ],
+    },
+    'chart-pick': {
+        'desc': '选图与取图表代码',
+        'reads': [
+            ('playbook.md', ['五']),
+            ('charts.md', ['16']),
+        ],
+    },
+    'content-rules': {
+        'desc': '密度/字数/去AI味/细节保全',
+        'reads': [
+            ('content-rules.md', ['四', '一']),
+            ('playbook.md', ['六']),
+        ],
+    },
+    'layout-grammar': {
+        'desc': '布局骨架 P1–P12 / 元素排版 / 组合与留白',
+        'reads': [
+            ('layout-grammar.md', ['〇', '二', '三', '四']),
+            ('playbook.md', ['〇']),
+        ],
+    },
+    'model-render': {
+        'desc': '模型驱动生成 / 单写路径',
+        'reads': [
+            ('pptx-export.md', ['内容模型']),
+            ('content-rules.md', ['二-b']),
+        ],
+    },
+    'pptx-export': {
+        'desc': 'PPTX 精导与页型字段',
+        'reads': [
+            ('pptx-export.md', ['精导', '内容模型']),
+            ('playbook.md', ['九']),
+        ],
+    },
+    'high-fidelity': {
+        'desc': '深度高保真/锚点/manifest',
+        'reads': [
+            ('high-fidelity.md', ['三', '四']),
+        ],
+    },
+    'image-layout': {
+        'desc': '素材图片六版式与配图占位',
+        'reads': [
+            ('components.md', ['11c']),
+            ('playbook.md', ['三']),
+        ],
+    },
+    'style-theme': {
+        'desc': '配色/亮暗/风格选型',
+        'reads': [
+            ('styles.md', ['快速选型', '新增']),
+            ('design-system.md', ['1a', '1b', '9']),
+        ],
+    },
+    'icons': {
+        'desc': '图标语义速查与使用准则',
+        'reads': [
+            ('icons.md', ['速查', '使用准则']),
+        ],
+    },
+}
+
+# 节号：阿拉伯（8 / 8b / 8-1）或中文（一 / 一-b / 一-续 / 十），须带 .、． 分隔或后随空白；
+# 无节号的二级标题也入节表（num=''，用标题关键词寻址——modes/icons/styles 等中文标题文件）
+_SEC_NUM = r'(?:\d+(?:[a-z]|-\d+)?|[一二三四五六七八九十]{1,3}(?:-[a-z0-9续]+)?)'
+HEADING_RE = re.compile(
+    r'^(#{2,4})[ \t]+(?:§)?(%s)[.、．]?[ \t]*(.*)$' % _SEC_NUM, re.M)
+HEADING_UNNUM_RE = re.compile(r'^(##)[ \t]+(.+)$', re.M)
+# 任意级别标题行（extract_chart 定位代码节边界用——### 代码节不能再被 ## 回退错层）
+_HEADING_ANY = re.compile(r'\n#{2,4}[ \t]')
+_CODE_FENCE = re.compile(r'```[\s\S]*?```')
+
+_TEXT_CACHE: dict[str, str] = {}
+
+
+def _read(path: Path) -> str:
+    """带缓存的读取（extract_section/_sections/extract_chart 共用，防同文件重复 IO）。"""
+    key = str(path)
+    if key not in _TEXT_CACHE:
+        _TEXT_CACHE[key] = path.read_text(encoding='utf-8')
+    return _TEXT_CACHE[key]
+
+
+def _fence_spans(text: str) -> list[tuple[int, int]]:
+    """代码围栏 ``` 区间（供 extract_chart 优先在代码内定位 data-chart）。"""
+    return [(m.start(), m.end()) for m in _CODE_FENCE.finditer(text)]
+
+
+def _sections(path: Path) -> list[tuple[str, str, int, int]]:
+    """返回 [(编号, 标题, start, end), ...]
+
+    编号节（## ~ ####）与无编号二级标题共同构成节边界；
+    无编号节 num=''，仅供 extract_section 的标题关键词兜底命中。
+    """
+    text = _read(path)
+    marks: list[tuple[str, str, int]] = []
+    num_starts: set[int] = set()
+    for m in HEADING_RE.finditer(text):
+        marks.append((m.group(2), m.group(3).strip(), m.start()))
+        num_starts.add(m.start())
+    for m in HEADING_UNNUM_RE.finditer(text):
+        if m.start() not in num_starts:  # 已被编号正则命中则跳过
+            marks.append(('', m.group(2).strip(), m.start()))
+    marks.sort(key=lambda t: t[2])
+    out = []
+    for i, (num, title, start) in enumerate(marks):
+        end = marks[i + 1][2] if i + 1 < len(marks) else len(text)
+        out.append((num, title, start, end))
+    return out
+
+
+def resolve_physical(filename: str, section: str | None = None) -> str:
+    """逻辑文件名 → 物理文件名（components/charts 拆分后路由）。"""
+    if not section:
+        return filename
+    mapping = SECTION_FILE_MAP.get(filename) or {}
+    return mapping.get(str(section), filename)
+
+
+def extract_section(filename: str, section: str, max_chars: int = 12000) -> str:
+    physical = resolve_physical(filename, section)
+    path = REF / physical
+    if not path.exists():
+        path = REF / filename
+    if not path.exists():
+        return f'错误：{path} 不存在'
+    secs = _sections(path)
+    # ① 精确节号优先；② 无精确命中才允许前缀（并提示，防敲错节号静默取错码）；③ 标题关键词兜底
+    hits = [s for s in secs if s[0] == section]
+    note = ''
+    if not hits:
+        prefix = [s for s in secs if s[0].startswith(section)]
+        if prefix:
+            hits = prefix[:1]
+            note = (f'\n/* 提示：§{section} 无精确节号，已按前缀命中 §{hits[0][0]} '
+                    f'（{hits[0][1][:24]}）；若非本意请用精确节号 */')
+    if not hits:
+        hits = [s for s in secs if section in s[1]]
+    if not hits:
+        seen: list[str] = []
+        for s in secs:
+            label = s[0] or (s[1][:10] + '…' if len(s[1]) > 10 else s[1])
+            if label not in seen:
+                seen.append(label)
+        sample = '、'.join(seen[:12])
+        return f'错误：{filename} 未找到 §{section}。可用节号/标题样例: {sample}'
+    num, title, start, end = hits[0]
+    body = _read(path)[start:end].rstrip()
+    if len(body) > max_chars:
+        body = body[:max_chars] + f'\n…（截断，全文见 references/{physical}）'
+    return f'/* references/{physical} §{num} {title} */\n\n{body}{note}'
+
+
+def verify_routes() -> list[str]:
+    """遍历 TASK_ROUTES，返回不可解析/空路由问题清单（audit_docs ⑥ 与 regression ⑦-b 共用同一实现）。"""
+    bad: list[str] = []
+    for task, r in TASK_ROUTES.items():
+        for fn, secs in r['reads']:
+            if not secs:
+                bad.append(f'{task}:{fn} 空路由')
+                continue
+            for sec in secs:
+                if extract_section(fn, sec, max_chars=200).startswith('错误'):
+                    bad.append(f'{task}:{fn} §{sec}')
+    return bad
+
+
+def extract_chart(chart_type: str, max_chars: int = 14000) -> str:
+    chart_type = (chart_type or '').strip().lower()
+    reg = ((LC.get('charts') or {}).get('registry') or {}).get(chart_type)
+    if not reg:
+        known = sorted((LC.get('charts') or {}).get('registry') or {})
+        return f'错误：未登记图表 {chart_type!r}。可用: {", ".join(known)}'
+    info_types = set(((LC.get('charts') or {}).get('scaffold') or {}).get('infoTypes') or {})
+    key = f'data-chart="{chart_type}"'
+    candidates = (
+        [REF / 'infographics-stats.md', REF / 'infographics-structure.md', REF / 'infographics.md']
+        if chart_type in info_types
+        else [REF / 'charts-basic.md', REF / 'charts-extended.md',
+              REF / 'charts-discipline.md', REF / 'charts.md']
+    )
+    path = next((p for p in candidates if p.exists() and key in _read(p)), None)
+    if path is None:
+        names = ', '.join(p.name for p in candidates if p.exists())
+        return f'错误：未找到 {key}（检索: {names}）'
+    text = _read(path)
+    # 优先取**代码围栏内**的 data-chart 出现位置——概述散文里的首个出现不是代码节
+    fences = _fence_spans(text)
+    idx = -1
+    pos = text.find(key)
+    while pos >= 0:
+        if any(a <= pos < b for a, b in fences):
+            idx = pos
+            break
+        pos = text.find(key, pos + 1)
+    if idx < 0:
+        idx = text.find(key)  # 无围栏命中时退回首现
+    # 回退到该代码块前最近的标题（任意级别——### 代码节不能被 ## 回退错层）
+    prev_head = None
+    for m in _HEADING_ANY.finditer(text, 0, idx + 1):
+        prev_head = m
+    head = prev_head.start() if prev_head else max(0, idx - 200)
+    # 前进到下一个任意级别标题或文件尾
+    nxt = _HEADING_ANY.search(text, idx)
+    end = nxt.start() if nxt else len(text)
+    body = text[head:end].rstrip()
+    if len(body) > max_chars:
+        body = body[:max_chars] + f'\n…（截断，全文见 {path.name}）'
+    meta = (f'/* chart={chart_type} · pptx={reg.get("pptx")} · '
+            f'dataTable={reg.get("dataTable")} · 来源 references/{path.name} */')
+    return f'{meta}\n\n{body}'
+
+
+def extract_page_type(page_type: str, max_chars: int = 10000) -> str:
+    ms = json.loads((ROOT / 'scripts' / 'model-schema.json').read_text(encoding='utf-8'))
+    pages = ms.get('pages') or ms.get('pageTypes') or ms
+    # schema 结构：可能是 {pages: {type: {...}}} 或顶层
+    entry = None
+    if isinstance(pages, dict) and page_type in pages:
+        entry = pages[page_type]
+    elif isinstance(ms.get('sections'), dict) and page_type in ms['sections']:
+        entry = ms['sections'][page_type]
+    # 兜底：递归找 type
+    if entry is None:
+        def find(obj):
+            if isinstance(obj, dict):
+                if obj.get('type') == page_type or page_type in obj and isinstance(obj[page_type], dict):
+                    return obj.get(page_type, obj)
+                for v in obj.values():
+                    r = find(v)
+                    if r is not None:
+                        return r
+            return None
+        entry = find(ms)
+    if entry is None:
+        return f'错误：model-schema.json 未找到页型 {page_type!r}'
+    # 选型表提示
+    hint = extract_section('components.md', '46', max_chars=4000)
+    schema_txt = json.dumps({page_type: entry}, ensure_ascii=False, indent=2)
+    return (f'/* pageType={page_type} · schema 字段（scripts/model-schema.json） */\n'
+            f'{schema_txt}\n\n'
+            f'/* 选型表摘要（components.md §46，完整表见原文） */\n'
+            f'{hint}')
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description='L2 节级片段抽取')
+    ap.add_argument('--list', action='store_true', help='列出任务路由与已登记图表')
+    ap.add_argument('--task', help='任务路由名（research-evidence / chart-pick / …）')
+    ap.add_argument('--chart', help='图表类型，从 charts.md / infographics.md 抽代码节')
+    ap.add_argument('--page-type', dest='page_type', help='页型名，输出 schema 字段 + 选型提示')
+    ap.add_argument('--file', help='references 下文件名，如 components.md')
+    ap.add_argument('--section', help='节编号，如 46 / 11c / 36d')
+    ap.add_argument('--max-chars', type=int, default=12000)
+    args = ap.parse_args()
+
+    if args.list:
+        print('任务路由：')
+        for name, r in TASK_ROUTES.items():
+            print(f'  {name:22} {r["desc"]}')
+            for fn, secs in r['reads']:
+                sec = ('§' + ' §'.join(secs)) if secs else '（全文按需）'
+                print(f'      · references/{fn} {sec}')
+        print('\n已登记图表：')
+        reg = (LC.get('charts') or {}).get('registry') or {}
+        for t, meta in sorted(reg.items()):
+            if t.startswith('$') or not isinstance(meta, dict):
+                continue
+            print(f'  {t:14} pptx={meta.get("pptx")} dataTable={meta.get("dataTable")}')
+        print('\n用法示例：')
+        print('  python scripts/extract_snippet.py --task research-evidence')
+        print('  python scripts/extract_snippet.py --chart waterfall')
+        print('  python scripts/extract_snippet.py --page-type exhibit')
+        print('  python scripts/extract_snippet.py --file components.md --section 46c')
+        return 0
+
+    if args.task:
+        r = TASK_ROUTES.get(args.task)
+        if not r:
+            print(f'错误：未知任务 {args.task!r}。用 --list 查看。')
+            return 2
+        print(f'# 任务：{args.task} — {r["desc"]}\n')
+        print('## 建议只读（读完即停，不预读下一份）\n')
+        for fn, secs in r['reads']:
+            sec = ('§' + '、'.join(secs)) if secs else '全文按需'
+            print(f'- references/{fn} — {sec}')
+        print('\n## 片段\n')
+        for fn, secs in r['reads']:
+            for sec in secs[:2]:  # 每文件最多抽 2 节，防上下文爆
+                print(extract_section(fn, sec, args.max_chars))
+                print('\n---\n')
+        return 0
+
+    if args.chart:
+        print(extract_chart(args.chart, args.max_chars))
+        return 0
+    if args.page_type:
+        print(extract_page_type(args.page_type, args.max_chars))
+        return 0
+    if args.file and args.section:
+        print(extract_section(args.file, args.section, args.max_chars))
+        return 0
+
+    ap.print_help()
+    return 2
+
+
+if __name__ == '__main__':
+    sys.exit(main())