npm - @remixmate/cli - Versions diffs - 0.9.25 → 0.9.27 - Mend

@remixmate/cli 0.9.25 → 0.9.27

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (21) hide show

package/README.md +11 -4
package/README.zh-CN.md +8 -4
package/dist/handlers/gen-voice.d.ts +11 -1
package/dist/handlers/gen-voice.js +17 -1
package/dist/manifest.json +166 -10
package/package.json +3 -1
package/skills/gen-script/SKILL.md +1 -0
package/skills/gen-script/scripts/gen_script.py +52 -3
package/skills/gen-script/skill.json +5 -0
package/skills/gen-script/version.json +1 -1
package/skills/gen-voice/SKILL.md +5 -3
package/skills/gen-voice/skill.json +3 -8
package/skills/render-video/scripts/render_video.py +32 -0
package/skills/render-video/version.json +1 -1
package/skills/web-read/SKILL.md +146 -0
package/skills/web-read/skill.json +131 -0
package/skills/web-screenshot/scripts/_media_screenshot/__init__.py +2 -0
package/skills/web-screenshot/scripts/_media_screenshot/js/extract_article.js +373 -0
package/skills/web-screenshot/scripts/_media_screenshot/reader.py +245 -0
package/skills/web-screenshot/scripts/_media_screenshot/urlguard.py +90 -0
package/skills/web-screenshot/scripts/read_page.py +136 -0

package/skills/web-screenshot/scripts/_media_screenshot/js/extract_article.js ADDED Viewed

@@ -0,0 +1,373 @@
+// Extract a page's main readable content as an ordered list of typed blocks.
+// Injected via page.evaluate(js_loader.load("extract_article"), cfg).
+//
+// A compact Readability-style pass: strip chrome, score paragraph density to
+// pick the content container, then walk it in document order. It returns
+// structured blocks rather than a formatted string so that every output format
+// (markdown / plain text / json) is a pure function of one single extraction —
+// the alternative, formatting in the page and re-parsing in Python, loses the
+// block boundaries that make truncation land somewhere readable.
+//
+// Runs against the live DOM and mutates it (junk removal). That is safe here:
+// the page is headless and thrown away immediately after this call.
+(cfg) => {
+  const opts = cfg || {};
+  const wantLinks = !!opts.includeLinks;
+  const wantImages = !!opts.includeImages;
+  const inlineMarkdown = opts.inline === 'markdown';
+  const squash = (s) => (s || '').replace(/\s+/g, ' ').trim();
+  const rawLen = (el) => squash(el.textContent).length;
+  // ── metadata (read before junk removal strips the <head> siblings) ────────
+  const meta = (sel, attr) => {
+    const el = document.querySelector(sel);
+    if (!el) return '';
+    return squash(attr ? el.getAttribute(attr) : el.textContent);
+  };
+  const metadata = {
+    title:
+      meta('meta[property="og:title"]', 'content') ||
+      meta('meta[name="twitter:title"]', 'content') ||
+      squash(document.title) ||
+      meta('h1'),
+    byline:
+      meta('meta[name="author"]', 'content') ||
+      meta('meta[property="article:author"]', 'content') ||
+      meta('[rel="author"]'),
+    siteName: meta('meta[property="og:site_name"]', 'content'),
+    publishedTime:
+      meta('meta[property="article:published_time"]', 'content') ||
+      meta('time[datetime]', 'datetime'),
+    description:
+      meta('meta[name="description"]', 'content') ||
+      meta('meta[property="og:description"]', 'content'),
+    lang: squash(document.documentElement.getAttribute('lang') || ''),
+    url: location.href,
+  };
+  const bodyCharCount = rawLen(document.body);
+  // ── 1. strip boilerplate (structural only, see below) ────────────────────
+  const JUNK_TAGS = [
+    'script', 'style', 'noscript', 'template', 'svg', 'canvas', 'iframe',
+    'form', 'button', 'select', 'textarea', 'nav', 'aside', 'footer',
+    '[aria-hidden="true"]', '[hidden]', '[role="navigation"]', '[role="banner"]',
+    '[role="complementary"]', '[role="search"]', '[role="dialog"]',
+  ].join(',');
+  // Matched against class + id, on "words" delimited by -, _ or space.
+  const JUNK_WORDS =
+    /(^|[-_\s])(comments?|disqus|sidebar|side-?bar|related|recommend(ed|ations?)?|advert(isement)?|ads?|adsbygoogle|banner|breadcrumbs?|share|sharing|social|subscribe|newsletter|popup|modal|overlay|cookie|toolbar|pagination|pager|footer|masthead|menu|promo|sponsor|widget|skip-link|back-to-top)($|[-_\s])/i;
+  const isJunkClass = (el) => {
+    const tokens = `${el.className || ''} ${el.id || ''}`;
+    return typeof tokens === 'string' && JUNK_WORDS.test(tokens);
+  };
+  document.querySelectorAll(JUNK_TAGS).forEach((el) => {
+    try { el.remove(); } catch (e) { /* already detached */ }
+  });
+  // Class-based junk is NOT removed here — only scored down in step 2 and
+  // pruned inside the winner in step 3. Removing it up front looks tidier and
+  // is how this first went wrong: Tencent Cloud's whole page wrapper carries
+  // `show-ad`, the `ads?` rule matched it, and the extractor deleted the entire
+  // article before it had a chance to score anything. A class name is a hint
+  // about a subtree's role, never grounds for deleting an ancestor of the text
+  // we came for.
+  // ── 2. pick the content container ────────────────────────────────────────
+  const linkDensity = (el) => {
+    const total = rawLen(el);
+    if (!total) return 1;
+    let linked = 0;
+    el.querySelectorAll('a').forEach((a) => { linked += rawLen(a); });
+    return Math.min(1, linked / total);
+  };
+  const tagBonus = (el) => {
+    const tag = el.tagName;
+    if (isJunkClass(el)) return 0.2;
+    if (tag === 'ARTICLE' || tag === 'MAIN') return 1.5;
+    const tokens = `${el.className || ''} ${el.id || ''}`;
+    if (typeof tokens === 'string' &&
+        /(^|[-_\s])(article|post|content|entry|markdown-body|rich_media|story|body)($|[-_\s])/i.test(tokens)) {
+      return 1.25;
+    }
+    return 1;
+  };
+  let container = null;
+  let containerReason = '';
+  if (opts.selector) {
+    container = document.querySelector(opts.selector);
+    if (!container) {
+      return { error: 'selector-not-found', selector: opts.selector, metadata };
+    }
+    containerReason = `selector:${opts.selector}`;
+  } else {
+    // Readability's scoring:每个够长的段落给自己父/祖父/曾祖父记分（1/2、1/3 衰减），
+    // 所以赢家是"段落最密集的那层"，而不是 <body>——<body> 拿不到直接段落的分。
+    const scores = new Map();
+    const add = (el, amount) => {
+      if (!el || el.nodeType !== 1 || el === document.body ||
+          el === document.documentElement) return;
+      scores.set(el, (scores.get(el) || 0) + amount);
+    };
+    document.querySelectorAll('p, pre, blockquote, li, td, h2, h3').forEach((node) => {
+      const text = squash(node.textContent);
+      if (text.length < 25) return;
+      const commas = (text.match(/[,，、.。;；]/g) || []).length;
+      let s = 1 + Math.min(text.length / 100, 3) + Math.min(commas, 3);
+      // 列表项 / 单元格常常是导航或目录，给一半权重。
+      if (node.tagName === 'LI' || node.tagName === 'TD') s *= 0.5;
+      const p = node.parentElement;
+      const gp = p && p.parentElement;
+      const ggp = gp && gp.parentElement;
+      add(p, s);
+      add(gp, s / 2);
+      add(ggp, s / 3);
+    });
+    let bestScore = 0;
+    scores.forEach((s, el) => {
+      const adjusted = s * (1 - linkDensity(el)) * tagBonus(el);
+      if (adjusted > bestScore) { bestScore = adjusted; container = el; }
+    });
+    containerReason = container ? `scored:${bestScore.toFixed(1)}` : 'fallback:body';
+    // 赢家常常只是正文里**最密的那一层**，而不是正文本身：docs.python.org 上
+    // 打分赢家是 `section#text`（第 3.1.2 节），它上面还有三节同级内容。所以向上
+    // 合并兄弟小节，直到父层开始引入噪音（体量暴涨或链接占比变高）为止。
+    let guard = 0;
+    while (container && container.parentElement &&
+           container.parentElement !== document.body &&
+           container.parentElement !== document.documentElement &&
+           guard++ < 8) {
+      const parent = container.parentElement;
+      if (isJunkClass(parent)) break;
+      const tooSmall = rawLen(container) < 200;
+      const growth = rawLen(parent) / Math.max(rawLen(container), 1);
+      if (!tooSmall && (growth > 3 || linkDensity(parent) > 0.3)) break;
+      container = parent;
+      containerReason += '+up';
+    }
+    if (!container) container = document.body;
+  }
+  // ── 3. prune junk *inside* the winner, then walk it into blocks ──────────
+  // Safe by construction: a descendant can never be the container, and the
+  // 40% rule keeps a mislabelled wrapper (the `show-ad` case, one level down)
+  // from taking the article with it.
+  const containerChars = rawLen(container) || 1;
+  Array.prototype.slice.call(container.querySelectorAll('div,section,ul,ol,span,header,p,figure'))
+    .forEach((el) => {
+      if (!container.contains(el) || el === container) return;
+      if (!isJunkClass(el)) return;
+      if (rawLen(el) / containerChars > 0.4) return;
+      try { el.remove(); } catch (e) { /* already detached */ }
+    });
+  const describe = (el) => {
+    if (!el || !el.tagName) return '';
+    const id = el.id ? `#${el.id}` : '';
+    const cls = typeof el.className === 'string' && el.className.trim()
+      ? `.${el.className.trim().split(/\s+/).slice(0, 2).join('.')}`
+      : '';
+    return `${el.tagName.toLowerCase()}${id}${cls}`;
+  };
+  // Inline serializer — the only place that knows about markdown syntax.
+  const inline = (node) => {
+    let out = '';
+    node.childNodes.forEach((child) => {
+      if (child.nodeType === 3) { out += child.nodeValue; return; }
+      if (child.nodeType !== 1) return;
+      const tag = child.tagName;
+      if (tag === 'BR') { out += ' '; return; }
+      if (tag === 'IMG') {
+        if (wantImages) {
+          const alt = squash(child.getAttribute('alt'));
+          const src = child.currentSrc || child.src ||
+            child.getAttribute('data-src') || '';
+          if (src) out += `![${alt}](${src})`;
+        }
+        return;
+      }
+      const inner = inline(child);
+      if (!inner.trim()) return;
+      if (tag === 'A' && wantLinks) {
+        const href = child.href || child.getAttribute('href') || '';
+        out += href ? `[${inner}](${href})` : inner;
+        return;
+      }
+      if (!inlineMarkdown) { out += inner; return; }
+      if (tag === 'CODE' || tag === 'KBD' || tag === 'SAMP') out += `\`${inner}\``;
+      else if (tag === 'STRONG' || tag === 'B') out += `**${inner}**`;
+      else if (tag === 'EM' || tag === 'I') out += `*${inner}*`;
+      else if (tag === 'DEL' || tag === 'S') out += `~~${inner}~~`;
+      else out += inner;
+    });
+    return out;
+  };
+  const text = (node) => squash(inline(node));
+  const listItems = (el, depth) => {
+    const items = [];
+    Array.prototype.forEach.call(el.children, (li) => {
+      if (li.tagName !== 'LI') return;
+      // Nested lists are flattened with an indent prefix rather than nested
+      // structures — every consumer here renders to flat text anyway.
+      const nested = li.querySelector(':scope > ul, :scope > ol');
+      const own = squash(
+        Array.prototype.filter
+          .call(li.childNodes, (n) => n !== nested)
+          .map((n) => (n.nodeType === 1 ? inline(n) : n.nodeValue || ''))
+          .join(''),
+      );
+      if (own) items.push({ depth, text: own });
+      if (nested && depth < 3) items.push(...listItems(nested, depth + 1));
+    });
+    return items;
+  };
+  const EMIT = new Set([
+    'H1', 'H2', 'H3', 'H4', 'H5', 'H6', 'P', 'PRE', 'BLOCKQUOTE',
+    'UL', 'OL', 'TABLE', 'FIGURE', 'IMG', 'HR', 'DL',
+  ]);
+  const SKIP_DESCEND = new Set(['PRE', 'TABLE', 'UL', 'OL', 'FIGURE', 'DL']);
+  const blocks = [];
+  const push = (block) => {
+    if (!block) return;
+    const prev = blocks[blocks.length - 1];
+    // 同一段文字在页面里出现两次（懒加载占位 + 真身）时只留一份。
+    if (prev && prev.type === block.type && prev.text && prev.text === block.text) return;
+    blocks.push(block);
+  };
+  const emit = (el) => {
+    const tag = el.tagName;
+    if (/^H[1-6]$/.test(tag)) {
+      const t = text(el);
+      if (t) push({ type: 'heading', level: Number(tag[1]), text: t });
+      return;
+    }
+    if (tag === 'P') {
+      const t = text(el);
+      if (t) push({ type: 'paragraph', text: t });
+      return;
+    }
+    if (tag === 'PRE') {
+      const code = el.querySelector('code') || el;
+      const cls = `${el.className || ''} ${code.className || ''}`;
+      const m = typeof cls === 'string' ? cls.match(/(?:language|lang|highlight)[-_](\w+)/i) : null;
+      const body = (code.innerText || code.textContent || '').replace(/\s+$/, '');
+      if (body.trim()) push({ type: 'code', lang: m ? m[1].toLowerCase() : '', text: body });
+      return;
+    }
+    if (tag === 'BLOCKQUOTE') {
+      const t = text(el);
+      if (t) push({ type: 'quote', text: t });
+      return;
+    }
+    if (tag === 'UL' || tag === 'OL') {
+      const items = listItems(el, 0);
+      if (items.length) push({ type: 'list', ordered: tag === 'OL', items });
+      return;
+    }
+    if (tag === 'DL') {
+      const items = [];
+      Array.prototype.forEach.call(el.children, (child) => {
+        const t = text(child);
+        if (!t) return;
+        items.push({ depth: child.tagName === 'DD' ? 1 : 0, text: t });
+      });
+      if (items.length) push({ type: 'list', ordered: false, items });
+      return;
+    }
+    if (tag === 'TABLE') {
+      const rows = [];
+      el.querySelectorAll('tr').forEach((tr) => {
+        const cells = [];
+        tr.querySelectorAll('th,td').forEach((cell) => cells.push(text(cell)));
+        if (cells.some((c) => c)) rows.push(cells);
+      });
+      if (rows.length) push({ type: 'table', rows });
+      return;
+    }
+    if (tag === 'FIGURE') {
+      const img = el.querySelector('img');
+      const cap = el.querySelector('figcaption');
+      const caption = cap ? text(cap) : '';
+      if (wantImages && img) {
+        const src = img.currentSrc || img.src || img.getAttribute('data-src') || '';
+        if (src) push({ type: 'image', src, alt: squash(img.getAttribute('alt')), caption });
+        return;
+      }
+      if (caption) push({ type: 'paragraph', text: caption });
+      return;
+    }
+    if (tag === 'IMG') {
+      if (!wantImages) return;
+      const src = el.currentSrc || el.src || el.getAttribute('data-src') || '';
+      if (src) push({ type: 'image', src, alt: squash(el.getAttribute('alt')), caption: '' });
+      return;
+    }
+    if (tag === 'HR') push({ type: 'rule' });
+  };
+  // 直接挂在容器上、没有被 <p> 包起来的裸文本（老网页很常见）也要收；
+  // 用 buffer 在遇到下一个块级元素或本层结束时冲刷成一个段落。
+  const walk = (el, depth) => {
+    if (depth > 24) return;
+    let buffer = '';
+    const flush = () => {
+      const t = squash(buffer);
+      buffer = '';
+      if (t.length >= 2) push({ type: 'paragraph', text: t });
+    };
+    el.childNodes.forEach((child) => {
+      if (child.nodeType === 3) { buffer += child.nodeValue; return; }
+      if (child.nodeType !== 1) return;
+      const tag = child.tagName;
+      if (EMIT.has(tag)) {
+        flush();
+        emit(child);
+        return;
+      }
+      if (SKIP_DESCEND.has(tag)) return;
+      if (tag === 'BR') { buffer += ' '; return; }
+      // Inline-level element sitting between block siblings: keep its text in
+      // the running buffer instead of dropping it on the floor.
+      if (['A', 'SPAN', 'CODE', 'STRONG', 'B', 'EM', 'I', 'SMALL', 'LABEL', 'TIME',
+           'SUP', 'SUB', 'MARK', 'ABBR', 'CITE', 'Q', 'DEL', 'S', 'U'].includes(tag)) {
+        buffer += inline(child);
+        return;
+      }
+      flush();
+      walk(child, depth + 1);
+    });
+    flush();
+  };
+  walk(container, 0);
+  const charCount = blocks.reduce((n, b) => {
+    if (b.type === 'list') return n + b.items.reduce((m, i) => m + i.text.length, 0);
+    if (b.type === 'table') return n + b.rows.reduce((m, r) => m + r.join('').length, 0);
+    return n + (b.text || '').length;
+  }, 0);
+  return {
+    metadata,
+    blocks,
+    container: describe(container),
+    containerReason,
+    charCount,
+    bodyCharCount,
+  };
+}

package/skills/web-screenshot/scripts/_media_screenshot/reader.py ADDED Viewed

@@ -0,0 +1,245 @@
+"""Read operation: load a page and extract its main content as text.
+The DOM work lives in ``js/extract_article.js`` (one injected pass returning
+typed blocks); this module drives the browser, renders those blocks into the
+requested format, and enforces the character budget.
+Truncation is the part that matters for the caller: a 200k-character page
+pasted into a model's context is worse than useless. ``max_chars`` cuts on a
+block boundary and says so in-band, and ``--output`` keeps the full text on
+disk so nothing is actually lost.
+"""
+from __future__ import annotations
+import json
+from pathlib import Path
+from . import js_loader
+from .bootstrap import ensure_runtime
+from .browser import apply_pre_action_waits, build_context_options, launch_with_browser_install
+def extract(cfg: dict) -> dict:
+    """Load cfg['url'] and return the raw extraction dict from the page."""
+    ensure_runtime()
+    from playwright.sync_api import sync_playwright
+    js_cfg = {
+        "selector": cfg.get("selector") or "",
+        "includeLinks": bool(cfg.get("includeLinks")),
+        "includeImages": bool(cfg.get("includeImages")),
+        "inline": "markdown" if cfg.get("format", "markdown") == "markdown" else "plain",
+    }
+    with sync_playwright() as p:
+        browser = launch_with_browser_install(p, cfg.get("browser"))
+        try:
+            context = browser.new_context(**build_context_options(p, cfg, None))
+            if cfg.get("timeout"):
+                context.set_default_timeout(cfg["timeout"])
+            page = context.new_page()
+            try:
+                try:
+                    response = page.goto(cfg["url"], wait_until="domcontentloaded")
+                except Exception as e:
+                    # 一条模型能据以行动的错误，胜过 30 行 Playwright traceback。
+                    # 导航失败是这个 skill 最常见的失败形态（打不开 / 超时 / DNS），
+                    # 让它读起来像"这个网址打不开"，而不是像程序崩了。
+                    raise SystemExit(
+                        f"打开页面失败：{cfg['url']}\n"
+                        f"{type(e).__name__}: {str(e).splitlines()[0]}\n"
+                        "可能是网络不可达、站点屏蔽了无头浏览器，或加载超过了超时时间。"
+                        "可尝试加大 --timeout、换 --user-agent，或确认该 URL 在本机能打开。"
+                    )
+                status = response.status if response else None
+                if status is not None and status >= 400:
+                    # Keep going: many sites serve real content under a 403/404
+                    # (paywalls, soft 404s). The status rides along in the output
+                    # so the caller can tell "empty page" from "blocked".
+                    pass
+                apply_pre_action_waits(page, cfg)
+                # SPA 正文往往在 domcontentloaded 之后才注水。networkidle 等不到就
+                # 算了——静态页本来就不会再有请求，硬等只是白白花掉 20 秒。
+                try:
+                    page.wait_for_load_state("networkidle", timeout=cfg.get("networkIdleMs", 8000))
+                except Exception:
+                    pass
+                settle = cfg.get("settleMs")
+                if settle:
+                    page.wait_for_timeout(settle)
+                data = page.evaluate(js_loader.load("extract_article"), js_cfg)
+                data["status"] = status
+                data["finalUrl"] = page.url
+                return data
+            finally:
+                context.close()
+        finally:
+            browser.close()
+# ── rendering ────────────────────────────────────────────────────────────────
+def _render_blocks(blocks: list, fmt: str) -> list[str]:
+    """One string per block, ready to be joined with a blank line."""
+    md = fmt == "markdown"
+    out: list[str] = []
+    for block in blocks:
+        kind = block.get("type")
+        if kind == "heading":
+            level = int(block.get("level") or 2)
+            out.append(f"{'#' * min(level, 6)} {block['text']}" if md else block["text"].upper())
+        elif kind == "paragraph":
+            out.append(block["text"])
+        elif kind == "quote":
+            out.append(f"> {block['text']}" if md else f'"{block["text"]}"')
+        elif kind == "code":
+            body = block.get("text", "")
+            out.append(f"```{block.get('lang') or ''}\n{body}\n```" if md else body)
+        elif kind == "list":
+            ordered = bool(block.get("ordered"))
+            lines = []
+            counter = 1
+            for item in block.get("items") or []:
+                indent = "  " * int(item.get("depth") or 0)
+                if ordered and not item.get("depth"):
+                    lines.append(f"{indent}{counter}. {item['text']}")
+                    counter += 1
+                else:
+                    lines.append(f"{indent}- {item['text']}")
+            out.append("\n".join(lines))
+        elif kind == "table":
+            rows = block.get("rows") or []
+            if not rows:
+                continue
+            if md:
+                width = max(len(r) for r in rows)
+                padded = [r + [""] * (width - len(r)) for r in rows]
+                lines = ["| " + " | ".join(padded[0]) + " |",
+                         "| " + " | ".join(["---"] * width) + " |"]
+                lines += ["| " + " | ".join(r) + " |" for r in padded[1:]]
+                out.append("\n".join(lines))
+            else:
+                out.append("\n".join("\t".join(r) for r in rows))
+        elif kind == "image":
+            src = block.get("src") or ""
+            alt = block.get("alt") or ""
+            caption = block.get("caption") or ""
+            if md:
+                line = f"![{alt}]({src})"
+                out.append(f"{line}\n{caption}" if caption else line)
+            else:
+                out.append(f"[image: {alt or caption or src}]")
+        elif kind == "rule":
+            out.append("---" if md else "—")
+    return [s for s in out if s.strip()]
+def _header(data: dict, fmt: str) -> str:
+    meta = data.get("metadata") or {}
+    lines = []
+    title = meta.get("title")
+    if title:
+        lines.append(f"# {title}" if fmt == "markdown" else title)
+    trailer = []
+    if meta.get("siteName"):
+        trailer.append(meta["siteName"])
+    if meta.get("byline"):
+        trailer.append(meta["byline"])
+    if meta.get("publishedTime"):
+        trailer.append(meta["publishedTime"])
+    trailer.append(data.get("finalUrl") or meta.get("url") or "")
+    lines.append(" · ".join(t for t in trailer if t))
+    return "\n".join(lines)
+def render(data: dict, cfg: dict) -> tuple[str, str, bool]:
+    """Return (stdout_text, full_text, truncated).
+    ``full_text`` is always the complete document; ``stdout_text`` is what the
+    caller should print, i.e. the same thing cut to ``maxChars``.
+    """
+    fmt = cfg.get("format", "markdown")
+    blocks = list(data.get("blocks") or [])
+    # 标题已经在 header 里印过一次；正文第一个块又是同一句时，去掉重复的那个。
+    title = ((data.get("metadata") or {}).get("title") or "").strip()
+    if blocks and title and blocks[0].get("type") == "heading":
+        first = (blocks[0].get("text") or "").strip().rstrip("¶").strip()
+        if first and (first == title or title.startswith(first)):
+            blocks = blocks[1:]
+    body_parts = _render_blocks(blocks, fmt)
+    body = "\n\n".join(body_parts)
+    if fmt == "json":
+        payload = {
+            "url": data.get("finalUrl"),
+            "status": data.get("status"),
+            "metadata": data.get("metadata"),
+            "container": data.get("container"),
+            "charCount": data.get("charCount"),
+            "blocks": data.get("blocks"),
+        }
+        full = json.dumps(payload, ensure_ascii=False, indent=2)
+        # JSON 不做块级截断：切一半的 JSON 不是 JSON。超预算时只报告，
+        # 让调用方自己决定是改格式还是配 --output。
+        return full, full, False
+    full = f"{_header(data, fmt)}\n\n{body}".strip()
+    max_chars = int(cfg.get("maxChars") or 0)
+    if max_chars <= 0 or len(full) <= max_chars:
+        return full, full, False
+    # Cut on a block boundary so the tail is a whole paragraph, not half a word.
+    head = f"{_header(data, fmt)}\n\n"
+    kept: list[str] = []
+    used = len(head)
+    for part in body_parts:
+        if used + len(part) + 2 > max_chars:
+            break
+        kept.append(part)
+        used += len(part) + 2
+    if not kept:
+        # Single oversized block (one giant <pre>, say) — fall back to a hard cut.
+        kept = [body[: max(0, max_chars - len(head))]]
+    shown = (head + "\n\n".join(kept)).strip()
+    notice = (
+        f"\n\n---\n[truncated] 已显示 {len(shown)} / {len(full)} 字符。"
+        "需要全文时加大 --max-chars（0 = 不限），或用 --output 把全文写到文件再按需读取。"
+    )
+    return shown + notice, full, True
+def do_read(cfg: dict) -> dict:
+    """Extract, render, optionally persist. Returns a small result summary."""
+    data = extract(cfg)
+    if data.get("error") == "selector-not-found":
+        raise SystemExit(
+            f'selector "{data.get("selector")}" 在页面上未找到（{cfg["url"]}）。'
+            "请换一个选择器，或去掉 --selector 让正文自动识别。"
+        )
+    stdout_text, full_text, truncated = render(data, cfg)
+    out_path = None
+    if cfg.get("output"):
+        out_path = Path(cfg["output"]).resolve()
+        out_path.parent.mkdir(parents=True, exist_ok=True)
+        out_path.write_text(full_text, encoding="utf-8")
+    return {
+        "text": stdout_text,
+        "fullText": full_text,
+        "truncated": truncated,
+        "outputPath": str(out_path) if out_path else None,
+        "charCount": data.get("charCount") or 0,
+        "bodyCharCount": data.get("bodyCharCount") or 0,
+        "blockCount": len(data.get("blocks") or []),
+        "container": data.get("container"),
+        "containerReason": data.get("containerReason"),
+        "status": data.get("status"),
+        "finalUrl": data.get("finalUrl"),
+        "metadata": data.get("metadata") or {},
+    }