webpage-parser 0.1.0__py3-none-any.whl

webpage_parser/htmlprep.py

@@ -0,0 +1,760 @@
+"""HTML 信号采集层：把原始 HTML 解析成各字段抽取器共用的信号集合。
+
+只做解析与归集，不做字段级仲裁。所有解析均容错，任何子步骤失败不抛出。
+"""
+import json
+import re
+
+from lxml import html as lxml_html
+
+try:
+    from .util import clean_text, loop_unescape
+except ImportError:  # 直接运行 extract.py 时 system/ 在 sys.path，无包上下文
+    from util import clean_text, loop_unescape
+
+ARTICLE_TYPES = {
+    "article", "newsarticle", "blogposting", "webpage", "report",
+    "qapage", "scholarlyarticle", "techarticle", "socialmediaposting",
+    "discussionforumposting", "liveblogposting", "analysisnewsarticle",
+    "reviewnewsarticle", "reportagenewsarticle", "opinionnewsarticle",
+}
+
+PUB_KEYS = {
+    "datepublished", "pubdate", "publishtime", "publish_time", "published_time",
+    "createtime", "create_time", "datecreate", "firstpublished", "issued",
+    "datecreated", "pub_time", "publishtime", "publishdate", "publish_date",
+    "releasedate", "release_time",
+}
+MOD_KEYS = {
+    "datemodified", "updatetime", "update_time", "dateupdate", "mtime",
+    "modified", "lastmodified", "last_modified", "lastupdated", "moddate",
+}
+
+def _cls_tokens(text):
+    """已弃用（被 region_token_hit 取代），保留仅防外部引用。"""
+    out = set()
+    for part in re.split(r"[^A-Za-z0-9]+", text or ""):
+        if not part:
+            continue
+        for tok in re.findall(r"[A-Z]+(?![a-z])|[A-Z][a-z0-9]*|[a-z0-9]+", part):
+            out.add(tok.lower())
+    return out
+
+
+# 状态标记类名（"has-sidebar"/"comment-open" 表示页面状态而非样板区块）
+_FLAG_PREFIX = {"has", "with", "no", "is", "fixed", "show", "hide", "use",
+                "js", "enable", "enabled", "contains"}
+_STATE_SUFFIX = {"open", "closed", "on", "off", "enabled", "active",
+                 "visible", "shown", "hidden", "expanded", "collapsed"}
+
+
+def region_token_hit(attr, tokens):
+    """判断 class/id 字符串是否语义上**就是** tokens 命名的区块（而非布局状态标记）。
+
+    逐 class 名判定：含 Tailwind 任意值（[/(/&）的名跳过；
+    token 前一段是 has/fixed/with… 或后一段是 open/on/active… 视为状态标记，不算命中。
+    例：'site-sidebar' 命中 sidebar；'has-sidebar'/'comment-open'/
+    'xs:[&.fixed-sidebar]:grid-cols-[...]' 不命中。
+    """
+    for name in (attr or "").lower().split():
+        if "[" in name or "(" in name or "&" in name:
+            continue
+        segs = [s for s in re.split(r"[^a-z0-9]+", name) if s]
+        for idx, seg in enumerate(segs):
+            if seg not in tokens:
+                continue
+            prev = segs[idx - 1] if idx > 0 else None
+            nxt = segs[idx + 1] if idx + 1 < len(segs) else None
+            if prev in _FLAG_PREFIX or nxt in _STATE_SUFFIX:
+                continue
+            return True
+    return False
+
+
+# 强 badZone：语义确定的样板区，对所有可见时间候选生效
+_STRONG_BAD_TOKENS = {
+    "comment", "comments", "reply", "replies", "respond", "discuss",
+    "discussion", "recommend", "recommended", "related", "footer",
+    "sidebar", "breadcrumb", "breadcrumbs", "copyright", "pager",
+    "pagination", "commentary",
+}
+# 弱 badZone：易误伤（module-nav / member-photo 这类复合 class），
+# 只对“无标签”的裸日期候选生效；带明确 发布时间/更新时间 标签的候选豁免
+# （调研07 §9.2：L5_visible_labeled 层不排除 badZone）
+_WEAK_BAD_TOKENS = {
+    "hot", "rank", "ranking", "trending", "share", "sharing", "advert",
+    "ads", "banner", "popup", "pop", "modal", "cookie", "subscribe",
+    "newsletter", "promo", "sponsor", "widget", "nav", "menu",
+}
+
+BADZONE_RE = re.compile(  # 保留导出兼容；新逻辑用 _in_badzone
+    r"comment|reply|respond|discuss|footer|recommend|related|sidebar|nav|menu|"
+    r"copyright|hot|rank|trending|breadcrumb|share|advert|banner|popup|modal|"
+    r"cookie|subscribe|newsletter|promo|sponsor|widget",
+    re.IGNORECASE,
+)
+
+DATE_LIKE_RE = re.compile(
+    r"(19|20)\d{2}[-/.\u5e74]\s*\d{1,2}[-/.\u6708]\s*\d{1,2}"
+    r"|\d{4}-\d{2}-\d{2}[Tt ]\d{2}:\d{2}"
+    r"|\d{1,2}/\d{1,2}/(?:19|20)\d{2}"
+    r"|\d{1,2}\s*(Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)"
+    r"|(Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)[a-z]*\s+\d{1,2}"
+    r"|\d+\s*\u4e2a?\s*(\u79d2|\u5206\u949f|\u5c0f\u65f6|\u5929|\u65e5|\u5468|\u661f\u671f)\u524d"
+    r"|\u6628\u5929|\u4eca\u5929|\u524d\u5929|\u521a\u521a"
+    r"|\d+\s*(seconds?|minutes?|hours?|days?|weeks?)\s+ago",
+    re.IGNORECASE,
+)
+
+HINT_PUB_RE = re.compile(
+    r"\u53d1\u5e03\u65f6\u95f4|\u53d1\u5e03\u4e8e|\u53d1\u8868\u4e8e|\u53d1\u8868\u65f6\u95f4|\u6765\u6e90.{0,4}\u65f6\u95f4|"
+    r"\u516c\u544a\u65e5\u671f|\u53d1\u5e03\u65e5\u671f|\u521b\u5efa\u65f6\u95f4|\u51fa\u7248\u65e5\u671f|"
+    r"published|posted|pubdate|release date|date published",
+    re.IGNORECASE,
+)
+HINT_MOD_RE = re.compile(
+    r"\u66f4\u65b0\u65f6\u95f4|\u66f4\u65b0\u4e8e|\u6700\u540e\u66f4\u65b0|\u4fee\u8ba2|\u7f16\u8f91\u4e8e|"
+    r"updated|modified|last[ -]?modified|edited",
+    re.IGNORECASE,
+)
+
+_SKIP_TAGS = {"script", "style", "noscript", "template", "svg", "iframe",
+              "canvas", "form", "button", "input", "select", "textarea"}
+_BLOCK_TAGS = {"p", "div", "span", "li", "td", "th", "time", "em", "strong",
+               "b", "i", "small", "label", "h1", "h2", "h3", "h4", "h5", "h6"}
+
+# 可见文本是相对时间的元素（其 title/datetime 属性常带同刻高精度绝对时间，
+# 如 gcores <span title="2026-08-28 04:51:19">31 分钟前</span>，验收反馈 case_02）
+_REL_TEXT_RE = re.compile(
+    r"(\u79d2|\u5206\u949f|\u5c0f\u65f6|\u5929|\u65e5|\u5468|\u661f\u671f)\s*\u524d\s*$"
+    r"|\bago\s*$"
+    r"|^(?:\u6628\u5929|\u4eca\u5929|\u524d\u5929|\u521a\u521a|\u4eca\u65e5|\u6628\u65e5)"
+    r"|^(?:yesterday|today)\b",
+    re.IGNORECASE,
+)
+
+
+def _user_panel(el):
+    """是否位于"当前用户面板"（SMF <div class="user"> 里的当前时刻显示）。
+
+    只认 class 恰为单词 'user' 或 id=='user' 的祖先：user-info/user-name 这类
+    byline 署名区不命中（它们的 <time> 是真实发布时间）。
+    """
+    n = 0
+    for anc in el.iterancestors():
+        if not isinstance(anc.tag, str) or anc.tag in ("body", "html"):
+            break
+        cls = (anc.get("class") or "").split()
+        aid = (anc.get("id") or "").strip().lower()
+        if cls == ["user"] or aid == "user":
+            return True
+        n += 1
+        if n >= 5:
+            break
+    return False
+
+
+class PageSignals:
+    def __init__(self, url="", host=""):
+        self.url = url
+        self.host = host
+        self.html = ""
+        self.tree = None
+        self.meta = {}               # key(lower, 保留空格) -> [value, ...]
+        self.jsonld_nodes = []       # 摊平后的节点 dict 列表
+        self.state_objs = []         # L1b 大 JSON 对象
+        self.time_elements = []      # (raw, strong_badzone, pos_ratio)
+        self.attr_times = []         # 元素属性里的时间 (raw, strong_badzone, pos_ratio)
+        self.comment_times = []      # CMS 注释里的原始时间串
+        self.itemprop_times = []     # microdata itemprop 时间 (raw, sem, strong_badzone)
+        self.visible_dates = []      # (txt, hint, labeled, strong_bz, weak_bz, pos_ratio)
+        self.author_nodes = []       # (txt, strong_bz, weak_bz, pos_ratio, tag)
+        self.visible_text_len = 0
+        self.title_tag = ""
+        self.h1_texts = []
+        self.forum = False
+        self.ok = False
+
+
+def _tolerant_json(text):
+    if not text:
+        return None
+    text = text.strip().strip(";")
+    if not text or text[0] not in "[{":
+        return None
+    # 小红书 __INITIAL_STATE__ 等内嵌 JS 字面量 undefined，替换后再试
+    variants = [text, re.sub(r",(\s*[}\]])", r"\1", text)]
+    if ":undefined" in text:
+        fixed = text.replace(":undefined", ":null")
+        variants += [fixed, re.sub(r",(\s*[}\]])", r"\1", fixed)]
+    for candidate in variants:
+        try:
+            return json.loads(candidate, strict=False)
+        except Exception:
+            continue
+    return None
+
+
+def _balance_extract(text, start):
+    """从 text[start]（应为 '{' 或 '['）做括号配平截取，返回子串或 None。"""
+    if start >= len(text) or text[start] not in "{[":
+        return None
+    open_ch = text[start]
+    close_ch = "}" if open_ch == "{" else "]"
+    depth = 0
+    in_str = False
+    esc = False
+    i = start
+    end = min(len(text), start + 2_000_000)
+    while i < end:
+        ch = text[i]
+        if in_str:
+            if esc:
+                esc = False
+            elif ch == "\\":
+                esc = True
+            elif ch == '"':
+                in_str = False
+        else:
+            if ch == '"':
+                in_str = True
+            elif ch == open_ch:
+                depth += 1
+            elif ch == close_ch:
+                depth -= 1
+                if depth == 0:
+                    return text[start:i + 1]
+        i += 1
+    return None
+
+
+def _flatten_jsonld(obj, out, depth=0):
+    if depth > 6:
+        return
+    if isinstance(obj, dict):
+        if "@graph" in obj:
+            _flatten_jsonld(obj["@graph"], out, depth + 1)
+        node = {k: v for k, v in obj.items() if k != "@graph"}
+        if node:
+            out.append(node)
+        for v in obj.values():
+            if isinstance(v, (dict, list)) and v is not obj.get("@graph"):
+                pass  # 嵌套实体保留在节点内，由取值方递归处理
+    elif isinstance(obj, list):
+        for item in obj:
+            _flatten_jsonld(item, out, depth + 1)
+
+
+def walk_json_keys(obj, prefix="", depth=0):
+    """递归遍历 JSON，产出 (dotted_lower_key, value)。供 L1b 时间/作者搜键用。"""
+    if depth > 8:
+        return
+    if isinstance(obj, dict):
+        for k, v in obj.items():
+            key = f"{prefix}.{k}".lower() if prefix else str(k).lower()
+            yield key, v
+            if isinstance(v, (dict, list)):
+                yield from walk_json_keys(v, key, depth + 1)
+    elif isinstance(obj, list):
+        for item in obj[:50]:
+            if isinstance(item, (dict, list)):
+                yield from walk_json_keys(item, prefix, depth + 1)
+
+
+def jsonld_regex_fallback(text):
+    """JSON 解析全失败时按键名正则直取（最后兜底，调研03 §2.4）。"""
+    node = {}
+    for key in ("datePublished", "dateModified", "headline"):
+        m = re.search(r'"' + key + r'"\s*:\s*"([^"{}]{4,64})"', text)
+        if m:
+            node[key] = m.group(1)
+    m = re.search(r'"author"\s*:\s*\{[^{}]{0,200}?"name"\s*:\s*"([^"{}]{1,80})"', text)
+    if m:
+        node["author"] = {"name": m.group(1)}
+    if node:
+        node["@type"] = "Article"
+    return node if node else None
+
+
+def _collect_jsonld(tree, signals):
+    for sc in tree.iter("script"):
+        t = (sc.get("type") or "").lower().strip()
+        if "ld+json" not in t:
+            continue
+        text = sc.text_content() or ""
+        if len(text) > 500_000:
+            text = text[:500_000]
+        obj = _tolerant_json(text)
+        if obj is None:
+            node = jsonld_regex_fallback(text)
+            if node:
+                signals.jsonld_nodes.append(node)
+            continue
+        _flatten_jsonld(obj, signals.jsonld_nodes)
+
+
+_STATE_HINT_RE = re.compile(
+    r"datePublished|publishTime|publish_time|pubDate|createTime|dateUpdate|"
+    r"updateTime|__NEXT_DATA__|__NUXT__|__INITIAL_STATE__|jsonData",
+    re.IGNORECASE,
+)
+
+
+def _collect_state_json(tree, signals):
+    """L1b：扫描 <script> 中的大 JSON 字面量（不硬编码变量名，调研03 §2.2）。"""
+    count = 0
+    for sc in tree.iter("script"):
+        if count >= 4:
+            break
+        t = (sc.get("type") or "").lower().strip()
+        if "ld+json" in t:
+            continue
+        text = sc.text_content() or ""
+        if len(text) < 100 or len(text) > 1_500_000:
+            continue
+        if not _STATE_HINT_RE.search(text):
+            continue
+        # 找变量赋值后的第一个 '{'，做括号配平
+        eq = text.find("=")
+        start = text.find("{", eq if eq >= 0 else 0)
+        if start < 0:
+            start = text.find("{")
+        sub = _balance_extract(text, start) if start >= 0 else None
+        obj = _tolerant_json(sub) if sub else None
+        if obj is None:
+            obj = _tolerant_json(text)
+        if obj is not None:
+            signals.state_objs.append(obj)
+            count += 1
+
+
+_FORUM_SOFT_TOKENS = {"comment", "comments", "reply", "replies", "discuss",
+                      "discussion"}
+
+
+def _in_badzone(el, forum=False):
+    """返回 (strong, weak)。标签/role 恒为强；class/id 按 token 分级。
+
+    - body/html 的类名是页面级布局声明（WP body class、Tailwind 布局容器），
+      不是局部样板区，跳过（样本实证：m-sidebar/comment-open/fixed-sidebar）；
+    - <article> 内部的 <header>/<footer> 是文章署名/元信息区（Nexstar、懂球帝
+      的 byline 都在 article>header 里），不算 badZone；
+    - forum=True（论坛/评论页型）时 comment/reply 楼层 token 降级为弱：
+      楼层即正文（V3 业务裁定：论坛保留讨论区）。
+    """
+    strong = False
+    weak = False
+    in_article = False
+    for anc in el.iterancestors():
+        if not isinstance(anc.tag, str):
+            continue
+        if anc.tag in ("body", "html"):
+            break
+        if anc.tag == "article":
+            in_article = True
+            continue
+        if anc.tag in ("nav", "header", "footer", "aside"):
+            anc_attr = (anc.get("class") or "") + " " + (anc.get("id") or "")
+            if in_article and anc.tag in ("header", "footer"):
+                continue
+            if anc.tag in ("header", "footer") and region_token_hit(
+                    anc_attr, {"article", "post", "entry"}):
+                continue
+            # 含 h1 的 header/footer 是文章头（署名/日期区），不是页头样板
+            # （验收反馈 case_01：vietnam.vn ant-layout-header 内含 h1+byline+日期）
+            if anc.tag in ("header", "footer"):
+                try:
+                    if any(clean_text(h.text_content()) for h in anc.iter("h1")):
+                        continue
+                except Exception:
+                    pass
+            strong = True
+            continue
+        attr = (anc.get("class") or "") + " " + (anc.get("id") or "")
+        strong_tokens = _STRONG_BAD_TOKENS
+        if forum:
+            strong_tokens = strong_tokens - _FORUM_SOFT_TOKENS
+            if region_token_hit(attr, _FORUM_SOFT_TOKENS):
+                weak = True
+        if region_token_hit(attr, strong_tokens):
+            strong = True
+        if region_token_hit(attr, _WEAK_BAD_TOKENS):
+            weak = True
+        role = anc.get("role") or ""
+        if role in ("navigation", "banner", "complementary", "search"):
+            strong = True
+    return strong, weak
+
+
+def _neighbor_label(el):
+    """取相邻结构里的短标签文本：前驱兄弟元素，或所在表格行首格。
+
+    覆盖 <td class="module-name">更新时间</td><td>2026-08-27…</td> 这类
+    标签与值分离的中文 CMS 表格标注（验收 case_00）。
+    """
+    try:
+        sib = el.getprevious()
+        while sib is not None:
+            t = clean_text(sib.text_content())
+            if t:
+                if len(t) <= 16:
+                    return t
+                return ""
+            sib = sib.getprevious()
+        if el.tag in ("td", "th"):
+            row = None
+            for anc in el.iterancestors():
+                if anc.tag == "tr":
+                    row = anc
+                    break
+            if row is not None:
+                for cell in row.iter("td", "th"):
+                    if cell is not el:
+                        t = clean_text(cell.text_content())
+                        if t and len(t) <= 16:
+                            return t
+                        return ""
+    except Exception:
+        return ""
+    return ""
+
+
+def _collect_comments(raw_html, signals):
+    """CMS 注释时间（enpproperty 等，毫秒冒号分隔，调研03 §3.5）。"""
+    for m in re.finditer(r"<!--(.{0,2000}?)-->", raw_html):
+        body = m.group(1)
+        dm = re.search(r"<date>([^<]{6,40})</date>", body)
+        if dm:
+            signals.comment_times.append(dm.group(1).strip())
+            continue
+        if re.search(r"publish|createdate|pubdate", body, re.IGNORECASE):
+            dm = re.search(r"((?:19|20)\d{2}[-/]\d{1,2}[-/]\d{1,2}[ T]?\d{0,2}:?\d{0,2}:?\d{0,2}:?\d{0,3})", body)
+            if dm:
+                signals.comment_times.append(dm.group(1).strip())
+
+
+_PUB_LABEL_NEAR_DATE_RE = re.compile(
+    r"(?:\u53d1\u5e03\u65f6\u95f4|\u53d1\u8868\u65f6\u95f4|\u53d1\u5e03\u65e5\u671f|\u53d1\u8868\u65e5\u671f|"
+    r"\u53d1\u5e03\u4e8e|\u53d1\u8868\u4e8e|\u51fa\u7248\u65e5\u671f|\u516c\u544a\u65e5\u671f|"
+    r"\u521b\u5efa\u65f6\u95f4|\u521b\u5efa\u65e5\u671f|\u520a\u767b\u65e5\u671f)"
+    r"\s*[\uff08(:\uff1a]?\s*(?=(?:19|20)\d{2})"
+)
+_MOD_LABEL_NEAR_DATE_RE = re.compile(
+    r"(?:\u66f4\u65b0\u65f6\u95f4|\u66f4\u65b0\u65e5\u671f|\u6700\u540e\u66f4\u65b0|\u6700\u8fd1\u66f4\u65b0|"
+    r"\u66f4\u65b0\u4e8e|\u4fee\u8ba2\u65f6\u95f4)"
+    r"\s*[\uff08(:\uff1a]?\s*(?=(?:19|20)\d{2})"
+)
+
+
+def _collect_time_elements(tree, signals):
+    body = tree.find("body") if tree.tag != "body" else tree
+    if body is None:
+        body = tree
+    total = 0
+    for el in body.iter():
+        if el.tag in _SKIP_TAGS:
+            continue
+        t = el.text or ""
+        total += len(t)
+    total = max(total, 1)
+    signals.visible_text_len = total
+
+    run = 0
+    seen_text = set()
+    for el in body.iter():
+        if el.tag in _SKIP_TAGS:
+            continue
+        t = el.text or ""
+        run += len(t)
+        pos = min(run / total, 1.0)
+        strong_bz = None
+        if el.tag == "time":
+            dt_attr = el.get("datetime") or ""
+            txt = clean_text(el.text_content())[:60]
+            raw = dt_attr.strip() or txt
+            if raw and DATE_LIKE_RE.search(raw):
+                strong_bz, _w = _in_badzone(el, getattr(signals, "forum", False))
+                signals.time_elements.append((raw, strong_bz, pos, _user_panel(el)))
+        for attr in ("data-time", "data-date", "data-ts", "data-timestamp",
+                     "data-pubtime", "data-publish-time", "data-createtime"):
+            v = el.get(attr)
+            if v and (DATE_LIKE_RE.search(v) or v.strip().isdigit()):
+                if strong_bz is None:
+                    strong_bz, _w = _in_badzone(el, getattr(signals, "forum", False))
+                signals.attr_times.append((v.strip(), strong_bz, pos))
+        # 可见文本日期扫描：只看短文本块
+        if el.tag in _BLOCK_TAGS:
+            txt = clean_text(el.text_content())
+            if not txt or len(txt) > 300 or len(txt) < 6:
+                continue
+            if txt in seen_text:
+                continue
+            if not DATE_LIKE_RE.search(txt):
+                continue
+            seen_text.add(txt)
+            # 复合标注：标签紧邻日期（"更新时间 2026-08-27（发布时间2026-08-27）"）
+            # 发布标签优先于更新标签（同一文本块内两者同时出现时）
+            hint = ""
+            labeled = False
+            if _PUB_LABEL_NEAR_DATE_RE.search(txt):
+                hint, labeled = "pub", True
+            elif _MOD_LABEL_NEAR_DATE_RE.search(txt):
+                hint, labeled = "mod", True
+            elif HINT_PUB_RE.search(txt):
+                hint = "pub"
+            elif HINT_MOD_RE.search(txt):
+                hint = "mod"
+            if not hint:
+                nb = _neighbor_label(el)
+                if nb:
+                    if HINT_PUB_RE.search(nb):
+                        hint, labeled = "pub", True
+                    elif HINT_MOD_RE.search(nb):
+                        hint, labeled = "mod", True
+            strong, weak = _in_badzone(el, getattr(signals, "forum", False))
+            # 相对时间节点的高精度属性（title/datetime 里的绝对时间，与相对文本同刻）
+            if _REL_TEXT_RE.search(txt):
+                for a in ("title", "datetime"):
+                    av = (el.get(a) or "").strip()
+                    if av and DATE_LIKE_RE.search(av):
+                        signals.attr_times.append((av, strong, pos))
+                        break
+            signals.visible_dates.append((txt, hint, labeled, strong, weak, pos))
+            if len(signals.visible_dates) >= 40:
+                break
+
+
+_AUTHOR_BYLINE_TOKENS = {"author", "byline", "writer"}
+_AUTHOR_TESTID_RE = re.compile(r"author|byline", re.IGNORECASE)
+
+
+def _collect_author_nodes(tree, signals):
+    """署名候选节点（调研03 §5.1 #3/#4）：itemprop/rel/data-testid/class-id 四路。
+
+    只取叶级命中（后代中无其他命中节点），文本截断 80 字符；
+    后续清洗与强拒绝在 author.py 完成。
+    """
+    body = tree.find("body") if tree.tag != "body" else tree
+    if body is None:
+        body = tree
+    hits = []
+    for el in body.iter():
+        if not isinstance(el.tag, str) or el.tag in _SKIP_TAGS:
+            continue
+        kind = None
+        testid = el.get("data-testid") or ""
+        if testid and _AUTHOR_TESTID_RE.search(testid):
+            kind = "testid"
+        elif (el.get("itemprop") or "").strip().lower() == "author":
+            kind = "itemprop"
+        elif el.tag == "a" and (el.get("rel") or "").strip().lower() == "author":
+            kind = "rel"
+        else:
+            attr = (el.get("class") or "") + " " + (el.get("id") or "")
+            if region_token_hit(attr, _AUTHOR_BYLINE_TOKENS):
+                kind = "cls"
+        if not kind:
+            continue
+        hits.append(el)
+    seen = set()
+    total = max(signals.visible_text_len, 1)
+    run = 0
+    hit_set = set(id(h) for h in hits)
+    for el in body.iter():
+        if not isinstance(el.tag, str) or el.tag in _SKIP_TAGS:
+            continue
+        run += len(el.text or "")
+        if id(el) not in hit_set:
+            continue
+        # 叶级判定：后代里还有命中节点则跳过父容器
+        leaf = True
+        for ch in el.iter():
+            if ch is not el and id(ch) in hit_set:
+                leaf = False
+                break
+        if not leaf:
+            continue
+        txt = ""
+        if (el.get("itemprop") or "").strip().lower() == "author":
+            nm = (el.get("content") or "").strip()
+            if not nm:
+                for sub in el.iter():
+                    if (sub.get("itemprop") or "").strip().lower() == "name":
+                        nm = clean_text(sub.text_content())
+                        break
+            txt = nm or clean_text(el.text_content())
+        else:
+            txt = clean_text(el.text_content())
+        if not txt or len(txt) > 80 or txt in seen:
+            continue
+        if txt.isascii() and len(txt) < 3:
+            continue
+        seen.add(txt)
+        strong, weak = _in_badzone(el, getattr(signals, "forum", False))
+        signals.author_nodes.append((txt, strong, weak, min(run / total, 1.0), el.tag))
+        if len(signals.author_nodes) >= 30:
+            break
+
+
+_AVATAR_ALT_BLOCK = frozenset({
+    "微信小程序", "微信", "新浪微博", "微博", "小程序", "公众号", "抖音", "快手",
+    "今日头条", "朋友圈", "qq", "qq空间", "app", "wechat", "weibo", "facebook",
+    "twitter", "x", "instagram", "linkedin", "whatsapp", "telegram", "email",
+    "mail", "分享", "收藏", "点赞", "评论", "打印", "字体", "字号",
+    "微信公众号", "话题追踪", "官方微博", "搜索", "专业版功能", "微博二维码",
+    "在线客服",
+})
+_AVATAR_ANCESTOR_RE = re.compile(
+    r"tool|share|popover|sns|avatar|recommand|recommend", re.IGNORECASE)
+_AVATAR_PUNCT = set("：，。！？!?.")
+
+
+def _collect_avatar_byline(tree, signals):
+    """头像署名：img[alt] 与同一容器内兄弟节点的文本完全一致 → 作者名
+    （验收 case_01：越南站 byline 只有头像 alt + 紧邻 span 名字，无 class 特征）。"""
+    body = tree.find("body") if tree.tag != "body" else tree
+    if body is None:
+        body = tree
+    found = []
+    for img in body.iter("img"):
+        alt = clean_text(img.get("alt") or "")
+        if not (2 <= len(alt) <= 40) or any(ch.isdigit() for ch in alt):
+            continue
+        if any(c in _AVATAR_PUNCT for c in alt):
+            continue
+        if alt.isascii() and " " not in alt and (len(alt) < 4 or alt.isupper()):
+            continue
+        if "扫码" in alt or "下载" in alt or alt.endswith("公众号"):
+            continue
+        if alt.lower() in _AVATAR_ALT_BLOCK:
+            continue
+        parent = img.getparent()
+        if parent is None:
+            continue
+        # 工具栏/分享条里的 icon+label 组合不是署名（回归 s1#16-19 微信小程序）
+        chrome = False
+        for anc in img.iterancestors():
+            if anc.tag == "button":
+                chrome = True
+                break
+            aattr = ((anc.get("class") or "") + " " + (anc.get("id") or ""))
+            if _AVATAR_ANCESTOR_RE.search(aattr):
+                chrome = True
+                break
+            if anc.tag in ("body",):
+                break
+        if chrome:
+            continue
+        containers = [parent]
+        gp = parent.getparent()
+        if gp is not None:
+            containers.append(gp)
+        match = None
+        for box in containers:
+            for i, sib in enumerate(box.iter("span", "a", "p", "strong", "b", "em", "label")):
+                if i >= 60:
+                    break
+                if clean_text(sib.text_content()) == alt:
+                    match = sib
+                    break
+            if match is not None:
+                break
+        if match is None:
+            continue
+        # 命中的是链接文本 → 导航/相关文章/产品网格，不是署名（回归 s1#58/86/179/199/290）
+        if match.tag == "a" or any(a.tag == "a" for a in match.iterancestors()):
+            continue
+        strong, weak = _in_badzone(match, getattr(signals, "forum", False))
+        found.append((alt, strong, weak, 0.0, "img_alt"))
+    # 一页命中过多 → 列表/网格页 alt 噪音，整批弃用（case_01 真值仅 1 个命中）
+    if 0 < len(found) <= 3:
+        signals.author_nodes.extend(found)
+
+
+def _collect_meta(tree, signals):
+    for el in tree.iter("meta"):
+        key = el.get("name") or el.get("property") or el.get("itemprop") or ""
+        key = key.strip().lower()  # 保留内部空格：weibo: article:create_at（调研05 坑）
+        if not key:
+            continue
+        val = el.get("content")
+        if val is None:
+            continue
+        val = clean_text(val)
+        if not val:
+            continue
+        signals.meta.setdefault(key, []).append(val)
+
+
+_ITEMPROP_PUB = {"datepublished", "datecreated", "pubdate", "publishdate"}
+_ITEMPROP_MOD = {"datemodified", "dateupdate"}
+
+
+def _collect_itemprop(tree, signals):
+    """Microdata 时间：<span itemprop="datePublished" content="...">（gamespress 等）。"""
+    for el in tree.iter():
+        if not isinstance(el.tag, str) or el.tag in _SKIP_TAGS:
+            continue
+        ip = (el.get("itemprop") or "").strip().lower()
+        if ip not in _ITEMPROP_PUB and ip not in _ITEMPROP_MOD:
+            continue
+        raw = (el.get("content") or el.get("datetime") or "").strip()
+        attr_based = bool(raw)
+        if not raw:
+            raw = clean_text(el.text_content())[:60]
+        if not raw or not DATE_LIKE_RE.search(raw):
+            continue
+        strong, _w = _in_badzone(el, getattr(signals, "forum", False))
+        if attr_based:
+            strong = False
+        sem = "pub" if ip in _ITEMPROP_PUB else "mod"
+        signals.itemprop_times.append((raw, sem, strong))
+        if len(signals.itemprop_times) >= 20:
+            break
+
+
+def _collect_titles(tree, signals):
+    for el in tree.iter("title"):
+        txt = clean_text(el.text_content())
+        if txt:
+            signals.title_tag = txt
+            break
+    for el in tree.iter("h1"):
+        txt = clean_text(el.text_content())
+        if txt:
+            signals.h1_texts.append(txt)
+        if len(signals.h1_texts) >= 3:
+            break
+
+
+def parse_page(raw_html, url="", host="", collect_state=True, forum=False):
+    """主入口：原始 HTML -> PageSignals。任何失败返回 ok=False 的空信号。"""
+    signals = PageSignals(url=url, host=host)
+    signals.html = raw_html or ""
+    signals.forum = bool(forum)
+    if not raw_html:
+        return signals
+    try:
+        _collect_comments(signals.html, signals)
+    except Exception:
+        pass
+    try:
+        doc = lxml_html.fromstring(raw_html)
+    except Exception:
+        try:
+            doc = lxml_html.fromstring(loop_unescape(raw_html))
+        except Exception:
+            return signals
+    signals.tree = doc
+    signals.ok = True
+    fns = [_collect_meta, _collect_titles, _collect_jsonld,
+           _collect_time_elements, _collect_itemprop, _collect_author_nodes,
+           _collect_avatar_byline]
+    if collect_state:
+        fns.insert(3, _collect_state_json)
+    for fn in fns:
+        try:
+            fn(doc, signals)
+        except Exception:
+            continue
+    return signals