argo-search 1.0.1 → 2.9.7

package/scripts/search_types.py

@@ -1,20 +1,15 @@
 #!/usr/bin/env python3
-"""
-search_types.py — 统一类型系统
-
-定义 SearchResult 数据类和 normalize_result 统一转换，
-将所有引擎的原始输出统一为结构化格式。
+"""search_types.py — 统一类型系统（已废弃，勿接入）
 
-字段规范：
-  - title: 结果标题（必填，截断到 200 字符）
-  - url: 结果链接（可选）
-  - snippet: 摘要/片段（截断到 300 字符）
-  - score: 相关性评分（默认 0.5）
-  - source: 引擎来源
-  - metadata: 元数据字典
+早期设计声明的统一 schema 层，从未被任何模块 import（grep 全仓库无引用）：
+  - 引擎输出直接透传 dict，运行时防御在 engines_base/safe_search 与
+    search.py 的 execute_search 里完成
+  - 保留本文件仅避免旧版外部脚本 import 断裂；新代码禁止使用
 """
 from __future__ import annotations
 
+from enum import Enum
+
 from dataclasses import dataclass, field, asdict
 from typing import Any
 
@@ -28,6 +23,7 @@ class SearchResult:
     score: float = 0.5
     source: str = ""
     metadata: dict = field(default_factory=dict)
+    social_meta: dict | None = None
 
     def to_dict(self) -> dict[str, Any]:
         """转为字典，省略空值/默认值字段。"""
@@ -42,6 +38,8 @@ class SearchResult:
             d["source"] = self.source
         if self.metadata:
             d["metadata"] = self.metadata
+        if self.social_meta:
+            d["social_meta"] = self.social_meta
         return d
 
 
@@ -69,4 +67,21 @@ def normalize_result(item: dict, engine: str, default_score: float = 0.5) -> Sea
         score=score,
         source=item.get("source", engine),
         metadata=item.get("metadata", {}),
+        social_meta=item.get("social_meta"),
     )
+
+
+class Stage(str, Enum):
+    """进度回调的阶段名（on_progress 契约）。
+
+    从 search.py 搬来这里：执行层与加工层（search_pipeline）都要发进度事件，
+    枚举放在任何一侧都会让另一侧反向依赖；search_types 是本仓共享类型的家。
+    """
+
+    START = "start"
+    CACHE_HIT = "cache_hit"
+    ROUTING = "routing"
+    SEARCHING = "searching"
+    MERGING = "merging"
+    DONE = "done"
+    ERROR = "error"

package/scripts/seek_locator.py

@@ -0,0 +1,68 @@
+#!/usr/bin/env python3
+"""seek_locator.py — local-seek 子技能的「安装感知」定位（唯一来源，不写死主机路径）。
+
+本地搜索（argo_local_search / --include-local）需要 local-seek/scripts/seek.py。
+local-seek 随 argo 打包在 sub-skills/ 下（安装感知：寻址锚点是本文件的真实安装位置），
+也可能作为独立 skill 装在别处。此模块把发现逻辑收紧到一处，供 search.py 与
+mcp_handlers.py 共用，消除两处各自硬编码 __file__ 相对路径与 ~/.agents/skills 等
+主机路径的重复（Fowler: Duplicated Code 反面却是各自为政、易漂移）。
+
+保持一致 SKILL.md 纪律「禁止在产品代码写死主机 skill 路径」：不再出现
+~/.agents/skills / ~/.claude/skills 这类字面量，改由环境变量承载自定义/遗留位置。
+
+查找顺序（命中即返回，全部未命中则返回打包位置，由调用方据此 fail 提示）：
+  1. ARGO_LOCAL_SEEK_PATH      显式指定 seek.py 的绝对/相对路径（任意自定义位置）
+  2. <ARGO_ROOT>/sub-skills/local-seek/scripts/seek.py
+                               —— 打包子技能，锚点为本模块的安装位置（symlink 会解析回来源）
+  3. ARGO_LOCAL_SEEK_ROOTS     os.pathsep 分隔的候选根目录，逐个检查
+                               <根>/local-seek/scripts/seek.py（承载遗留/独立装法）
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Iterator
+
+ARGO_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+_BUNDLED = os.path.join(ARGO_ROOT, "sub-skills", "local-seek", "scripts", "seek.py")
+
+
+def _candidates() -> Iterator[str]:
+    """按优先级产出候选 seek.py 路径（仅路径，未校验存在性）。
+
+    优先级：显式文件覆盖 > 显式候选根 > 打包位置（默认）。
+    显式配置（ARGO_LOCAL_SEEK_PATH / ARGO_LOCAL_SEEK_ROOTS）代表用户点名了
+    装在哪，理应先于总是存在的打包子技能；打包位置只作保底。
+    """
+    override = (os.environ.get("ARGO_LOCAL_SEEK_PATH") or "").strip()
+    if override:
+        yield os.path.realpath(os.path.expanduser(override))
+    roots = (os.environ.get("ARGO_LOCAL_SEEK_ROOTS") or "").strip()
+    if roots:
+        for root in roots.split(os.pathsep):
+            root = root.strip()
+            if not root:
+                continue
+            base = os.path.realpath(os.path.expanduser(root))
+            candidate = os.path.join(base, "local-seek", "scripts", "seek.py")
+            if os.path.isfile(candidate):
+                yield candidate
+    yield _BUNDLED
+
+
+def resolve_seek_py() -> str:
+    """返回 local-seek/scripts/seek.py 的绝对路径（命中即返回，未命中返回打包位置）。"""
+    for cand in _candidates():
+        if cand and os.path.isfile(cand):
+            return cand
+    return _BUNDLED
+
+
+def seek_py_exists() -> bool:
+    """本地搜索能力是否可用（seek.py 实际存在）。"""
+    return os.path.isfile(resolve_seek_py())
+
+
+if __name__ == "__main__":  # pragma: no cover
+    import sys
+    print(resolve_seek_py())

package/scripts/semantic_evidence.py

@@ -0,0 +1,215 @@
+#!/usr/bin/env python3
+"""semantic_evidence.py — 可选的语义证据层（classifier.dev，默认关闭）。
+
+## 为什么存在
+
+argo 的正文吸收分是**正则密度**（has_numbers / has_definition / …），它测的是
+「这段文本长得像不像证据块」，不测「它是否支持这条查询的主张」。2026-09-19 的
+实测（reports/classifier-dev-argo/A、B）：密度最高页判 neutral、密度最低页判
+supports 0.99，两者近乎反向；而假前提主张（查询预设「降息」、现实是「加息」）
+密度分在结构上无法表达，语义判定 5/5 判 contradicts（conf 0.95~1.00）。
+
+## 定位（与热路径解耦）
+
+- **只在显式核验链路调用**（`search --verify` / `research --verify`），不进搜索
+  热路径：热命中 78~82ms 且网络为零，一次分类调用 200~680ms，放进热路径是净损失
+- **默认关闭**：config.yaml `semantic_evidence.enabled: false`；显式开启用环境变量
+  `ARGO_SEMANTIC_EVIDENCE=1`（env 优先于 config）
+- **fail-open**：超时 / HTTP 错误 / 429 / 解析失败 / 条数不匹配 → 返回 None，
+  调用方行为与未开启时逐位一致（不加字段、不改排序、不改公式）
+- **只加并列字段**：`semantic_support` 挂在结果与 verified 条目上，可信度公式
+  （selection 0.40 / absorption 0.35 / freshness 0.15 / original 0.10）不动
+
+## 外部服务约束（2026-09-19 实测，见 reports/classifier-dev-argo/D）
+
+- 无密钥、HTTP 通道稳定（1000 条 1.83s、顺序严格保真）；CLI 与 MCP 通道当前不可用
+  （npm/PyPI 404、MCP tools/call 返回 not_found），因此只走 HTTP
+- 必须带真实 User-Agent（python urllib 默认 UA 被边缘 403）——复用 HttpClient 的
+  UA 轮换与 429 退避
+- 标签集必须显式含「none of these」：服务永远返回给定标签之一，不加会把无关文本
+  硬塞进某个标签
+- 同输入置信度有 ±0.08 漂移（标签稳定），所以只做 ≥0.7 的粗门控；实测 conf ≥0.7
+  时严格错误为 0（51 条 entailment 样本）
+- 限额按出口 IP：fast 3000 次/分钟、20000 次/天；空串输入会让整批 400，调用前过滤
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any, Optional
+
+logger = logging.getLogger("unified_search.semantic_evidence")
+
+DEFAULT_ENDPOINT = "https://classifier.dev"
+DEFAULT_TIMEOUT_S = 5.0
+# conf ≥ 0.7 才给结论：低于此值的判定不可信（B 实测 4 个严格错误全部 ≤0.67）
+SUPPORT_THRESHOLD = 0.7
+# 单条文本上限：核验链路取回的正文 ≤8000 字，再高无收益（A 实测 400→7798 字
+# 置信度反而从 0.73 升到 0.98，说明长文不劣化，但也没必要超发）
+MAX_TEXT_CHARS = 8000
+
+SUPPORT_LABELS = (
+    "supports the query",
+    "contradicts the query",
+    "neutral",
+    "none of these",
+)
+SOURCE_TYPE_LABELS = (
+    "primary data or official announcement",
+    "secondary reporting",
+    "analysis or opinion",
+    "social narrative",
+    "none of these",
+)
+
+
+def _config() -> dict[str, Any]:
+    """读 config.yaml 的 semantic_evidence 段（缺失时用内置默认）。"""
+    try:
+        from config import load_config
+        cfg = load_config().get("semantic_evidence")
+        return cfg if isinstance(cfg, dict) else {}
+    except Exception:  # pragma: no cover - 配置不可用按默认关处理
+        return {}
+
+
+def enabled() -> bool:
+    """开关判定：环境变量优先，其次 config.yaml；两者都缺省 → 关闭。
+
+    用 engine_env.get_env/env_flag 读（全仓唯一的布尔解析），所以
+    `ARGO_SEMANTIC_EVIDENCE=off`、写进 ~/.config/argo/env 的写法都生效。
+    """
+    try:
+        from engine_env import env_flag, get_env
+        if get_env("ARGO_SEMANTIC_EVIDENCE").strip():
+            return env_flag("ARGO_SEMANTIC_EVIDENCE", default=False)
+    except Exception:  # pragma: no cover - 环境层不可用时不冒险开启
+        return False
+    return bool(_config().get("enabled", False))
+
+
+def _endpoint() -> str:
+    return str(_config().get("endpoint") or DEFAULT_ENDPOINT).rstrip("/")
+
+
+def _timeout() -> float:
+    try:
+        return float(_config().get("timeout_s") or DEFAULT_TIMEOUT_S)
+    except (TypeError, ValueError):
+        return DEFAULT_TIMEOUT_S
+
+
+def classify(texts: list[str], labels: tuple[str, ...] | list[str], *,
+             instructions: str | None = None,
+             timeout: float | None = None,
+             tier: str | None = None) -> Optional[list[dict[str, Any]]]:
+    """一次批量分类（≤1000 条）。任何异常/非 200/条数不匹配 → None。
+
+    返回按输入顺序排列的 [{label, confidence, scores}]；调用方负责判定阈值。
+    空文本会被过滤后再发（空串会让整批 400），返回列表与输入等长、空缺位为 None。
+    """
+    if not texts or len(labels) < 2:
+        return None
+    keep = [(i, t) for i, t in enumerate(texts) if (t or "").strip()]
+    if not keep:
+        return None
+    body: dict[str, Any] = {
+        "labels": [str(x) for x in labels],
+        "inputs": [t[:MAX_TEXT_CHARS] for _i, t in keep],
+        "tier": tier or str(_config().get("tier") or "fast"),
+    }
+    if instructions:
+        body["instructions"] = instructions
+    try:
+        from http_client import HttpClient
+        resp = HttpClient(timeout=timeout or _timeout(), max_retries=1,
+                          jitter=False).post(_endpoint(), body)
+        if resp.get("status") != 200:
+            logger.debug(f"语义分类非 200: {resp.get('status')} {resp.get('error')}")
+            return None
+        data = json.loads(resp.get("text") or "{}")
+        results = data.get("results")
+        if not isinstance(results, list) or len(results) != len(keep):
+            logger.debug("语义分类返回条数与输入不匹配，按失败处理")
+            return None
+    except Exception as e:  # fail-open：语义层任何问题都不阻断核验
+        logger.debug(f"语义分类失败: {type(e).__name__}")
+        return None
+    out: list[Optional[dict[str, Any]]] = [None] * len(texts)
+    for (idx, _t), r in zip(keep, results):
+        if isinstance(r, dict):
+            out[idx] = r
+    return out  # type: ignore[return-value]
+
+
+def assess_support(query: str, items: list[dict[str, Any]]) -> Optional[dict[str, dict]]:
+    """对已抓取的正文批量判定「是否支持查询隐含的主张」。
+
+    items: [{"url": str, "title": str, "text": str}]
+    返回 {url: {label, confidence, supports, contradicts}}；未达阈值时
+    supports/contradicts 均为 False（原始 label 与 confidence 仍原样保留，
+    调用方可自行换阈值）。失败返回 None。
+    """
+    usable = [it for it in items if (it.get("text") or "").strip() and it.get("url")]
+    if not usable:
+        return None
+    texts = [f"{it.get('title') or ''}\n{(it.get('text') or '')[:MAX_TEXT_CHARS]}"
+             for it in usable]
+    instructions = (
+        f"Judge whether each passage supports the claim implied by this query: {query!r}. "
+        "Answer 'supports the query' when the passage backs the claim, "
+        "'contradicts the query' when it states the opposite or a conflicting figure, "
+        "'neutral' when it is on-topic but neither supports nor contradicts, "
+        "and 'none of these' when it is unrelated to the query."
+    )
+    results = classify(texts, SUPPORT_LABELS, instructions=instructions)
+    if results is None:
+        return None
+    out: dict[str, dict] = {}
+    for it, r in zip(usable, results):
+        if not r:
+            continue
+        label = str(r.get("label") or "")
+        conf = r.get("confidence")
+        conf_f = float(conf) if isinstance(conf, (int, float)) else 0.0
+        out[str(it["url"])] = {
+            "label": label,
+            "confidence": conf_f,
+            "supports": label == "supports the query" and conf_f >= SUPPORT_THRESHOLD,
+            "contradicts": label == "contradicts the query" and conf_f >= SUPPORT_THRESHOLD,
+        }
+    return out or None
+
+
+def assess_source_types(items: list[dict[str, Any]]) -> Optional[dict[str, dict]]:
+    """来源类型分级（研究取证链路用）：一手数据 / 二手报道 / 分析观点 / 社交叙事。
+
+    items: [{"url": str, "title": str, "text": str}]（text 可为摘要）
+    """
+    usable = [it for it in items if it.get("url") and
+              ((it.get("text") or "").strip() or (it.get("title") or "").strip())]
+    if not usable:
+        return None
+    texts = [f"{it.get('title') or ''}\n{(it.get('text') or '')[:MAX_TEXT_CHARS]}"
+             for it in usable]
+    instructions = (
+        "Classify each source by its nature: 'primary data or official announcement' "
+        "for original datasets, filings, official releases; 'secondary reporting' for "
+        "news coverage of someone else's work; 'analysis or opinion' for commentary; "
+        "'social narrative' for forum/social posts."
+    )
+    results = classify(texts, SOURCE_TYPE_LABELS, instructions=instructions)
+    if results is None:
+        return None
+    out: dict[str, dict] = {}
+    for it, r in zip(usable, results):
+        if not r:
+            continue
+        label = str(r.get("label") or "")
+        conf = r.get("confidence")
+        out[str(it["url"])] = {
+            "label": label,
+            "confidence": float(conf) if isinstance(conf, (int, float)) else 0.0,
+        }
+    return out or None

package/scripts/serp_guard.py

@@ -0,0 +1,228 @@
+#!/usr/bin/env python3
+"""serp_guard — HTML SERP 垃圾结果守卫（判定规则单点）。
+
+事故背景（dsh-free-search issue #38/#35 同款事故，argo 的 local_* 引擎同样
+暴露）：html 引擎解析的是无 API 的网页 SERP，上游偶发把缓存 SERP / 与查询
+完全无关的结果页当正常页返回，解析层照常抽出标题摘要，垃圾条目静默混进
+聚合，调用方把「答非所问」当成「网上没有」——失败伪装成功是红线，这类
+混入是它的隐形变体。
+
+裁决口径（全部量化，无模糊地带）：
+
+  1. query token：CJK 连续段取相邻二元组、拉丁/数字连续段取小写词。
+     token 少于 2 个时恒 False（无裁决权）——单 token 的巧合重叠率太高，
+     拦了误杀大于漏放。单字 CJK 查询（如「猫」）只有 0 个二元组，双字
+     CJK 查询（如「猫粮」）只有 1 个，都天然落在无裁决区。
+  2. results 只取前 5 条；每条取 title+snippet。URL 不参与：缓存/跳转
+     链接的 URL 常回显 query 参数（uddg=、q=），会正好把垃圾页放行，
+     标题+摘要才是「这页在答什么」的信号。
+  3. 前 5 条全部与 query token 零交集 → 整页判垃圾（True）。
+
+为什么调用方对判垃圾应整页丢弃而不是过滤后返回幸存者：前 5 条全无关说明
+这一页整体答非所问（缓存页/错路由），幸存的一两条是同一页的噪声，过滤
+返回等于给垃圾留门，宁缺勿假。调用方（engines_base）判垃圾后返回 [] 且
+不记 note_failure——结果无关不是引擎故障，不该进熔断归因。
+
+ARGO_SERP_GUARD=0 整体关闭守卫（逃生门：规则误杀时第一反应是关闸复现，
+而不是删代码）。
+
+不 import search_rank：本模块处在 engines_base 的冷启动热路径上，search_rank
+较重且有环风险；分词口径按其 _tokens/_bigrams 的语义在本模块最小复刻
+（CJK 二元组 + 小写拉丁词），不共享代码。
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+from typing import Any
+from urllib.parse import urlparse
+
+# CJK 连续段 / 小写拉丁数字词（findall 前文本已 lower()）
+_RUN_RE = re.compile(r"[\u4e00-\u9fff]+|[a-z0-9]+")
+_GUARD_WINDOW = 5      # 只看前 5 条：SERP 的「答非所问」看头部即可下结论
+_MIN_QUERY_TOKENS = 2  # query token 少于此数 → 无裁决权，恒不拦
+_SWITCH_ENV = "ARGO_SERP_GUARD"
+
+
+def guard_enabled() -> bool:
+    """逃生门：仅 ARGO_SERP_GUARD=0 关闭，其余取值（含未设置）均开启。"""
+    return os.environ.get(_SWITCH_ENV, "") != "0"
+
+
+def _extract_tokens(text: str) -> set[str]:
+    """提取 token：CJK 相邻二元组 + 小写拉丁/数字词（与 search_rank 同口径）。"""
+    tokens: set[str] = set()
+    for run in _RUN_RE.findall((text or "").lower()):
+        if "\u4e00" <= run[0] <= "\u9fff":
+            tokens.update(run[i:i + 2] for i in range(len(run) - 1))
+        else:
+            tokens.add(run)
+    return tokens
+
+
+def _result_text(item: object) -> str:
+    """单条结果的相关性文本 = title + snippet；非 dict 或字段缺失按空处理。"""
+    if not isinstance(item, dict):
+        return ""
+    return f"{item.get('title') or ''} {item.get('snippet') or ''}"
+
+
+def is_junk_serp(query: str, results: list[dict]) -> bool:
+    """判一页 SERP 结果是否整体答非所问（口径见模块 docstring）。
+
+    返回 True 表示整页判垃圾，调用方应丢弃全部条目；返回 False 表示不拦
+    （含 query 无裁决权、results 为空、守卫被关闭——三种都不拦）。
+    """
+    if not guard_enabled():
+        return False
+    q_tokens = _extract_tokens(query if isinstance(query, str) else "")
+    if len(q_tokens) < _MIN_QUERY_TOKENS:
+        return False
+    if not isinstance(results, list):
+        return False
+    head = [r for r in results[:_GUARD_WINDOW] if r is not None]
+    if not head:
+        return False
+    for item in head:
+        if _extract_tokens(_result_text(item)) & q_tokens:
+            return False
+    return True
+
+
+# ── SERP/跳转 URL 判定（自 evidence.py 迁入，2026-10-01）────────────────────
+# 迁入原因：这组判定是纯 URL 规则，但原宿主 evidence.py 会把 content_signals
+# 等证据质量栈一起拖进 import（实测 ~9 ms/进程），而它的调用方
+# （evidence_loop.gate_results、search_pipeline 的 SERP 过滤）在**每次搜索
+# 必经**的路径上——缓存命中也照付。本模块只依赖 os/re/json/urllib.parse，
+# 处在 engines_base 冷启动热路径上，轻量有既有纪律保证（见模块 docstring）。
+# evidence.py 保留同名转出，既有调用方（ab_eval_p0p1 等）不受影响。
+_BACKENDS_DIR = os.path.normpath(os.path.join(
+    os.path.dirname(os.path.abspath(__file__)), "..", "backends"))
+_CN_OVERRIDES: "dict[str, Any] | None" = None
+
+
+def _load_cn_source_types() -> dict[str, Any]:
+    global _CN_OVERRIDES
+    if _CN_OVERRIDES is not None:
+        return _CN_OVERRIDES
+    path = os.path.join(_BACKENDS_DIR, "source_types_cn.json")
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            _CN_OVERRIDES = json.load(f)
+    except Exception:
+        _CN_OVERRIDES = {}
+    return _CN_OVERRIDES
+
+
+def _normalize_domain(url: str) -> str:
+    if not url:
+        return ""
+    try:
+        host = urlparse(url).netloc.lower()
+    except Exception:
+        return ""
+    if "@" in host:
+        host = host.rsplit("@", 1)[1]
+    if ":" in host:
+        host = host.split(":", 1)[0]
+    if host.startswith("www."):
+        host = host[4:]
+    return host
+
+
+def _query_has_param(query: str, name: str) -> bool:
+    """query 参数名完整匹配：只在开头或 & 后出现才算。
+
+    子串匹配会把百度网盘分享的 ?pwd=x 连坐进 wd=（pwd 恰以 wd= 结尾，
+    实测误杀）——参数名只可能出现在 query 开头或 & 之后。
+    """
+    return query.startswith(name + "=") or ("&" + name + "=") in query
+
+
+def is_serp_or_jump_url(url: str) -> bool:
+    """是否为搜索引擎结果页 / 跳转壳（不可当信源正文）。"""
+    if not url:
+        return True
+    low = url.lower()
+    host = _normalize_domain(url)
+
+    # 白名单：百度子域（百家号、网盘等）不是 SERP，即使 path 为 /s 也不应误杀。
+    # 必须最先检查，否则 serp_url_patterns 中的 baidu.com/s? 会误匹配
+    # baijiahao.baidu.com/s?id= 百家号文章页。
+    _serp_whitelist = ("baijiahao.baidu.com", "pan.baidu.com", "tieba.baidu.com",
+                       "zhidao.baidu.com", "wenku.baidu.com")
+    host_bare = host[4:] if host.startswith("www.") else host
+    if host in _serp_whitelist or host_bare in _serp_whitelist:
+        return False
+
+    cfg = _load_cn_source_types()
+    for pat in cfg.get("serp_url_patterns") or []:
+        if pat.lower() in low:
+            return True
+    # 显式搜索/跳转模式
+    if re.search(r"(?:^|\.)baidu\.com/s\?", low):
+        return True
+    if "baidu.com/link" in low or "baidu.com/baidu.php" in low:
+        return True
+    if "sogou.com/link" in low:
+        return True
+    if "google.com/url?" in low or "google.com.hk/url?" in low:
+        return True
+    if re.search(r"(bing|google|google\.com\.hk)\.com/search\?", low):
+        return True
+    if "weixin.sogou.com/weixin" in low:
+        return True
+    try:
+        path = urlparse(url).path or ""
+        query = urlparse(url).query or ""
+    except Exception:
+        path, query = "", ""
+    # serp 域名只从 source_types_cn.json 的 serp_host_markers 读。此前这里
+    # 还并列写了一份字面量集合，两处各写一份正是漏网的成因：google.co.jp /
+    # yahoo.co.jp / duckduckgo.com 的结果页会被当成正文信源（authority 拿
+    # 到正常分、并进入最终输出），而 google.com 被拦——同一个概念两种判定。
+    #
+    # 判定用**后缀匹配**而非等值：同一搜索引擎的入口域名很多（yahoo.co.jp /
+    # search.yahoo.co.jp、duckduckgo.com / lite.duckduckgo.com、brave.com /
+    # search.brave.com），而 _normalize_domain 只去 www.，子域会原样保留。
+    # 等值比较下每上一个新入口就得往表里再补一条——那正是这份表原本在漏的。
+    serp_hosts = tuple(cfg.get("serp_host_markers") or ())
+    _hit = any(
+        host_bare == m or host == m
+        or host_bare.endswith("." + m) or host.endswith("." + m)
+        for m in serp_hosts
+    )
+    if _hit:
+        # path 只精确比较：此前 `path.startswith("/s")` 会把 pan.baidu.com/s/<id>
+        # 网盘分享正文链连坐误杀（实测；中文资源类查询的常见结果）。SERP 的
+        # path 恰为 /s，上方精确元组已覆盖，不需要前缀匹配。query 参数走
+        # _query_has_param 完整匹配（?pwd= 不再喂进 wd=）。
+        if path in ("", "/", "/s", "/web", "/search") \
+                or "link" in path or "search" in path \
+                or _query_has_param(query, "q") or _query_has_param(query, "wd"):
+            return True
+    return False
+
+
+def drop_shell_urls(results: list) -> list:
+    """过滤结果列表里的 SERP/跳转壳条目——壳判定的唯一过滤出口。
+
+    为什么必须是本模块的共用函数而不是各处内联：壳判定有多个消费点
+    （充分性判定 query_signals——壳不算「够数」；恢复链 L0——壳不算
+    「交付」，否则误判恢复成功；L3 恢复结果收口——主链的壳过滤跑在
+    恢复链之前，恢复产出是唯一可能把壳带回最终输出的入口）。判定规则
+    演进过多次（百度子域白名单、网盘 /s/<id> 误杀），每处内联一份就多
+    一处漏改点；2026-10-11 热榜壳链事故的根因之一正是充分性与漏斗
+    两处口径漂移。无 url 的结构化快照（行情/天气）不受影响。
+    """
+    kept = []
+    for r in results:
+        if not isinstance(r, dict):
+            continue
+        u = r.get("url")
+        if isinstance(u, str) and u and is_serp_or_jump_url(u):
+            continue
+        kept.append(r)
+    return kept

package/scripts/serp_kill_log.py

@@ -0,0 +1,51 @@
+#!/usr/bin/env python3
+"""serp_kill_log — serp_guard 整页误杀的运行内账本（2026-10-10 方案甲）。
+
+为什么单开一个模块：engines_base 是祖父文件、行数顶在登记上限，尺寸门的
+哲学是「要加东西先拆模块」。_serp_guard_apply 的判定逻辑随本账本一起搬来，
+engines_base 留薄委托保持原导入面不变。
+
+背景：_serp_guard_apply 对整页垃圾返回 [] 是「诚实空」（结果无关不进熔断
+归因、不伪装成成功），但对调用方等价于「引擎没搜到」——误杀类缺陷（搜狗
+跳转壳 10-06、百家号 10-08）都在这里静默发生过。击杀先入账本，search 层
+执行完 drain 进 errors：可见、可归因、可用 ARGO_SERP_GUARD=0 复核。
+"""
+from __future__ import annotations
+
+import threading
+from typing import Any
+
+# 判定规则与逃生门（ARGO_SERP_GUARD=0）在 serp_guard 单点；这里只登记
+# 哪些引擎接了守卫（解析上游 HTML 页最易被缓存 SERP 静默命中）。
+SERP_GUARD_ENGINES = frozenset({
+    "local_bing", "local_baidu", "local_sogou",
+})
+
+# 进程级 + 锁。并发搜索下 drain 可能拿到彼此的条目——条目只含引擎名与
+# 条数、无查询内容，跨运行误挂是无害的信息性噪音。
+_LOCK = threading.Lock()
+_KILLS: list[dict[str, Any]] = []
+
+
+def serp_guard_apply(engine_name: str, query: str,
+                     results: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """守卫接线：命中引擎且整页判垃圾 → 记账后返回 []（诚实空语义不变）。"""
+    if not results or engine_name not in SERP_GUARD_ENGINES:
+        return results
+    try:
+        from serp_guard import is_junk_serp
+    except ImportError:
+        return results  # fail-open：守卫自身故障不放大成搜索故障
+    if is_junk_serp(query, results):
+        with _LOCK:
+            _KILLS.append({"engine": engine_name, "results": len(results)})
+        return []
+    return results
+
+
+def drain_serp_guard_kills() -> list[dict[str, Any]]:
+    """取走并清空本进程累计的整页击杀记录（search 层专用）。"""
+    with _LOCK:
+        kills = list(_KILLS)
+        _KILLS.clear()
+        return kills