argo-search 1.0.1 → 2.9.7

package/scripts/usage_log_clean.py

@@ -0,0 +1,113 @@
+#!/usr/bin/env python3
+"""usage_log_clean — 生产使用日志的夹具污染隔离（维护工具，隔离不删除）。
+
+背景（2026-10-10 侦察轮发现、10-11 实测定性）：本仓 benchmark/评测曾直写
+生产状态目录，query.jsonl 的 982 条真实记录混入 334 条夹具引擎条目
+（slow_primary / fast_garbage / g1 / fast_backup 等），P50/P90 与引擎频次
+统计全部失真。脚本侧已于 10-10 接 isolate_state_dir（防新增）；本工具清
+历史存量——夹具行原样移入 <stream>.jsonl.quarantine-<ts>，主文件只留
+真实条目，数据零丢失。
+
+引擎名真值来源：engines.available_engines()（与路由同源，253 个）。
+engines_used 出现任何表外名即判夹具。两处历史别名显式豁免（引擎改名前的
+旧条目，不是夹具）：openlibrary→open_library、bing→bing_rss。
+recovery.jsonl 无 engines_used 字段，2026-10-11 全文扫描零夹具命中，
+不在本工具处理范围。
+
+用法（建议 argo 空闲时跑；写回前会重读并把窗口内新追加的行接回 kept，
+不再静默丢失——但仍建议停掉 daemon/MCP 等持续写入方，避免夹具判定
+跨窗口不一致）：
+  python3 scripts/usage_log_clean.py            # 干跑：只报告不动文件
+  python3 scripts/usage_log_clean.py --apply    # 实际隔离
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import time
+from collections import Counter
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from engines import available_engines  # noqa: E402
+from usage_log import usage_log_dir  # noqa: E402
+import argo_paths  # noqa: E402
+
+# 引擎改名前的历史别名：表外但真实，豁免隔离（维护者注释留在账上）
+_ALIAS_KEEP = frozenset({"openlibrary", "bing"})
+
+_STREAM = "query"
+
+
+def _fixture_engines(used: list) -> list[str]:
+    """一条记录的表外引擎名（别名豁免后）。"""
+    return [e for e in used if e not in _ALIAS_KEEP and e not in _CANON]
+
+
+_CANON = frozenset(available_engines())
+
+
+def _clean(path: Path, apply: bool) -> dict:
+    lines = path.read_text(encoding="utf-8").splitlines() if path.exists() else []
+    kept: list[str] = []
+    quarantine: list[str] = []
+    bad_names: Counter = Counter()
+    for line in lines:
+        if not line.strip():
+            continue
+        try:
+            used = json.loads(line).get("engines_used") or []
+        except json.JSONDecodeError:
+            kept.append(line)  # 读不动的行不是隔离对象，原样保留
+            continue
+        bad = _fixture_engines(used)
+        if bad:
+            bad_names.update(bad)
+            quarantine.append(line)
+        else:
+            kept.append(line)
+    report = {
+        "stream": _STREAM,
+        "path": str(path),
+        "total": len(kept) + len(quarantine),
+        "kept": len(kept),
+        "quarantined": len(quarantine),
+        "fixture_engines": dict(bad_names.most_common()),
+        "applied": False,
+    }
+    if apply and quarantine:
+        # 写回前重读一次，把「快照读」与「原子写」之间并发追加的新行接在
+        # kept 之后——否则这段窗口里落进的真实查询会被静默吞掉（旧实现
+        # 整文件替换为读时的旧视图，docstring 的错误承诺正好相反）。
+        # 追加行夹在既有行之后，无法用「是否为快照行」区分，只能按行数增量
+        # 取尾部；夹具行本工具只报一次，多余不影响数据（它们仍会进下次账）。
+        try:
+            current = path.read_text(encoding="utf-8").splitlines()
+        except OSError:
+            current = lines
+        appended = current[len(lines):] if len(current) > len(lines) else []
+        kept = kept + [ln for ln in appended if ln.strip()]
+        stamp = time.strftime("%Y%m%d-%H%M%S")
+        q_path = path.with_name(f"{path.name}.quarantine-{stamp}")
+        argo_paths.atomic_write_text(q_path, "\n".join(quarantine) + "\n")
+        argo_paths.atomic_write_text(path, "\n".join(kept) + "\n")
+        report["applied"] = True
+        report["quarantine_path"] = str(q_path)
+        report["appended_kept"] = len(appended)
+    return report
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(description="使用日志夹具污染隔离（维护工具）")
+    ap.add_argument("--apply", action="store_true",
+                    help="实际执行隔离；默认干跑只报告")
+    args = ap.parse_args(argv)
+    path = usage_log_dir() / f"{_STREAM}.jsonl"
+    print(json.dumps(_clean(path, apply=args.apply), ensure_ascii=False))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/v2ex_nodes.py

@@ -0,0 +1,311 @@
+#!/usr/bin/env python3
+"""v2ex_nodes.py — V2EX 节点路由：把「全站热帖过滤」升级为「相关节点内检索」。
+
+## 问题（第一批的遗留）
+
+第一批把 V2EX 引擎从「抓 /search 页产出幻觉」改成「hot+latest 候选池 + 本地
+相关性过滤」。但候选池只有 10+10=20 条**全站热帖**，与查询无关，导致长尾
+查询必然落空（实测 MacBook/招聘 返回 0 条）。
+
+当时判定「官方 API 无搜索端点，只能这样」——**这个退让是错的**。
+
+## 重新定义
+
+官方 API 确实没有搜索，但有 `show.json?node_name=X&page=N`：**按节点取帖**。
+实测 V2EX 有 1376 个节点，其中 1246 个有内容，节点名 99% 是英文实体词
+（python/docker/iphone/paper…）。于是真实问题不是「如何搜索」，而是：
+
+    「如何把用户查询映射到节点空间」
+
+## 为什么是倒排而不是模糊匹配
+
+实测：节点名 99% 是英文实体词，且节点自带 title（中文标题）与 header
+（语义描述）。所以 `查询词元 ∩ 节点名` 就是**精确命中**——不需要算相似度、
+不需要 embedding。这消除了「准确 vs 通用」的假两难。
+
+## 三层递进（每层失败即降级，不阻断）
+
+  L1 精确倒排       查询词元 ∩ 节点名            conf=1.0  零 API
+  L2 同义/中英扩展   复用 argo query_synonyms_cn  conf=0.8  零 API
+  L3 header 语义保底 L1/L2 全空时在描述里找词     conf=0.5  零 API
+
+三层全空 = 该查询在 V2EX 确无对应资源，**诚实返回空**，由调用方降级到
+hot/latest 保底（而不是伪造结果）。
+
+## 成本
+
+节点表 1376 条 ≈ 200KB，变化极慢 → 本地缓存 24h。匹配阶段**零 API 调用**。
+取帖按 Top-K 节点并发，K=3 时占用配额 3/600 = 0.5%。
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import threading
+import time
+from pathlib import Path
+from typing import Any
+
+from cjk_tokens import cjk_term_grams
+
+# 节点表缓存
+_CACHE_TTL = 24 * 3600          # 24h：节点表变化极慢
+_CACHE_FILE = "v2ex_nodes_cache.json"
+
+# 单字/双字节点名不参与匹配：实测 "c"/"io"/"u"/"in" 等单字节点会造成噪声命中。
+# 这是**格式约束**（英文单字几乎必然误命中任意查询词元），不是质量判断。
+MIN_NODE_NAME_LEN = 3
+
+# 注意：这里曾尝试加「节点热度门槛」（topics >= N）过滤冷门节点，已废弃。
+# 实测数据否定了这类「节点固有属性」判据：
+#   · 节点主题数中位数仅 15，一半节点 <15 —— 热度不存在自然分界
+#   · u(大学)/in(分享邀请码)/pro(PRO) 都「名实相符」—— 一致性也不能区分
+# 根本原因：节点好坏不是固有属性，而是「节点 × 查询」的联合属性。
+# 同一个 paper 节点，查「论文」是好节点、查「数据库」是坏节点。
+# 正确做法是把判据后移到「结果」：路由只给候选，好坏由既有相关性过滤
+# （_term_hits）决定——命中冷门节点则池小、过滤后为空、诚实返回；
+# 命中热门节点则池大、过滤后命中。分工清晰，无需在路由层设阈值。
+
+# 默认取几个节点的帖子（并发）。3 个 = 30 条候选，配额占用 0.5%
+DEFAULT_TOP_K = 3
+
+# 节点表完整性下限：低于此数视为「上游半截响应/解析异常」，不写缓存。
+# V2EX 实际 1300+ 节点，测试 fixture 通常只有几条，用它区分真假数据。
+MIN_NODE_TABLE_SIZE = 100
+
+_lock = threading.Lock()
+_mem_cache: dict[str, Any] = {}
+
+
+def _cache_path() -> Path:
+    try:
+        import argo_paths
+        return argo_paths.state_path(_CACHE_FILE)
+    except Exception:
+        return Path.home() / ".cache" / "unified-search" / _CACHE_FILE
+
+
+def _load_cached_nodes() -> list[dict] | None:
+    """读本地节点表缓存；过期或损坏返回 None。"""
+    p = _cache_path()
+    try:
+        st = p.stat()
+    except OSError:
+        return None
+    if time.time() - st.st_mtime > _CACHE_TTL:
+        return None
+    try:
+        data = json.loads(p.read_text(encoding="utf-8"))
+        nodes = data.get("nodes") if isinstance(data, dict) else None
+        if isinstance(nodes, list) and nodes:
+            return nodes
+    except Exception:
+        pass
+    return None
+
+
+def _save_nodes(nodes: list[dict]) -> None:
+    """写节点表缓存。
+
+    防御：节点数低于完整性下限时不写。V2EX 实际有 1300+ 节点，若某次
+    只解析出极少数（上游半截响应 / 测试注入的 fixture / 解析逻辑变更），
+    写进缓存会把不完整数据固化 24h —— 实测曾因测试写入 1 个假节点，
+    导致后续所有真实查询路由失败（缓存里只有 python 一个节点）。
+    """
+    if len(nodes) < MIN_NODE_TABLE_SIZE:
+        return
+    p = _cache_path()
+    try:
+        # 原子写走唯一来源（唯一 tmp 名）——旧实现固定 `.tmp` 名，
+        # 并发进程互相搬走临时文件导致写失败。
+        import argo_paths as _paths
+        _paths.atomic_write_json(p, {"nodes": nodes}, indent=None)
+    except Exception:
+        pass  # 缓存是加速层，写失败不影响功能
+
+
+def fetch_all_nodes(fetcher=None, engine: str = "v2ex") -> list[dict]:
+    """取全节点表（带 24h 本地缓存 + 进程内缓存）。
+
+    fetcher(url) -> raw text，默认走 argo 统一 GET 出口。
+    只保留有内容的节点（topics>0）：空节点取不到帖子，参与匹配无意义。
+    engine：默认 fetcher 的归因归属（缺失会把失败记到伪引擎 "?" 名下）。
+    """
+    global _mem_cache
+    with _lock:
+        cached = _load_cached_nodes()
+        if cached:
+            return cached
+        if _mem_cache.get("nodes"):
+            return _mem_cache["nodes"]
+
+    if fetcher is None:
+        def fetcher(url):  # type: ignore
+            from engines_base import _http_get_raw
+            return _http_get_raw(url, {"Accept": "application/json"}, 10,
+                                 engine=engine)
+
+    try:
+        raw = fetcher("https://www.v2ex.com/api/nodes/all.json")
+        if not raw:
+            return []
+        data = json.loads(raw)
+    except Exception:
+        return []
+
+    if not isinstance(data, list):
+        return []
+    nodes = [
+        n for n in data
+        if isinstance(n, dict) and n.get("name")
+        and int(n.get("topics") or 0) > 0
+    ]
+    if nodes:
+        _save_nodes(nodes)
+    with _lock:
+        _mem_cache["nodes"] = nodes
+    return nodes
+
+
+def _eligible(n: dict) -> bool:
+    """节点是否可参与路由：仅要求名字长度达标。
+
+    这是**格式约束**而非质量判断：英文单字节点（c/io/u/in）几乎必然
+    误命中任意查询词元，属结构性噪声，故排除。
+    刻意不做热度/名实一致等「固有属性」筛选——见文件头部说明，
+    节点好坏是「节点 × 查询」的联合属性，路由层无法预判。
+    """
+    return len((n.get("name") or "")) >= MIN_NODE_NAME_LEN
+
+
+def _tokenize(query: str) -> set[str]:
+    """查询 → 拉丁词元集合（长度门槛见 MIN_NODE_NAME_LEN）。"""
+    toks = set(re.findall(r"[a-z0-9]+", (query or "").lower()))
+    return {t for t in toks if len(t) >= MIN_NODE_NAME_LEN}
+
+
+def _expand_synonyms(query: str) -> set[str]:
+    """复用 argo 已有的中英同义表做扩展（不新建维护面）。
+
+    表在 backends/query_synonyms_cn.json，含 synonyms(中→多语) 与
+    en_to_cn(英→中)。这里只取「中文意图 → 英文词面」方向，
+    用于把「论文」扩成 paper、「教程」扩成 guide。
+    """
+    out: set[str] = set()
+    q = (query or "").lower()
+    if not q:
+        return out
+    try:
+        p = Path(__file__).resolve().parent.parent / "backends" / "query_synonyms_cn.json"
+    except Exception:
+        return out
+    try:
+        data = json.loads(p.read_text(encoding="utf-8"))
+    except Exception:
+        return out
+    syn = data.get("synonyms") or {}
+    for cn, eqs in syn.items():
+        if cn and cn in q and isinstance(eqs, list):
+            for e in eqs:
+                out.update(re.findall(r"[a-z0-9]+", str(e).lower()))
+    return {t for t in out if len(t) >= MIN_NODE_NAME_LEN}
+
+
+def pick_nodes(query: str, *, top_k: int = DEFAULT_TOP_K,
+               nodes: list[dict] | None = None,
+               fetcher=None) -> dict[str, Any]:
+    """查询 → 节点列表（三层递进）。
+
+    返回 {"nodes": [name...], "confidence": float, "layer": str, "scores": {...}}
+    layer: exact / synonym / header / none
+    无命中时返回 nodes=[] + layer="none"，调用方据此降级到 hot/latest。
+    """
+    nodes = nodes if nodes is not None else fetch_all_nodes(fetcher=fetcher)
+    if not nodes:
+        return {"nodes": [], "confidence": 0.0, "layer": "none", "scores": {}}
+
+    q = (query or "").lower()
+    terms = _tokenize(q)
+
+    # ── L1 精确倒排：查询词元 ∩ 节点名 ────────────────────────────────
+    hits: dict[str, float] = {}
+    for n in nodes:
+        if not _eligible(n):
+            continue
+        name = (n.get("name") or "").lower()
+        if name in terms:
+            # 节点名被查询直接引用 = 最强信号；热度作次级权重避免大节点垄断
+            hits[name] = 10.0 + min(int(n.get("topics") or 0) / 100000, 1.0)
+    if hits:
+        ranked = sorted(hits.items(), key=lambda x: -x[1])
+        return {"nodes": [n for n, _ in ranked[:top_k]], "confidence": 1.0,
+                "layer": "exact", "scores": dict(ranked[:top_k])}
+
+    # ── L2 同义/中英扩展后倒排 ────────────────────────────────────────
+    expanded = terms | _expand_synonyms(q)
+    if expanded != terms:
+        for n in nodes:
+            if not _eligible(n):
+                continue
+            name = (n.get("name") or "").lower()
+            if name in expanded:
+                hits[name] = 8.0 + min(int(n.get("topics") or 0) / 100000, 1.0)
+        if hits:
+            ranked = sorted(hits.items(), key=lambda x: -x[1])
+            return {"nodes": [n for n, _ in ranked[:top_k]], "confidence": 0.8,
+                    "layer": "synonym", "scores": dict(ranked[:top_k])}
+
+    # ── L2b 中文标题反查 ──────────────────────────────────────────────
+    # 节点的 title/header 是中文（jobs=「酷工作」、rent=「租房」、
+    # shanghai=「上海」），可把中文查询意图反查到英文节点名。
+    # 实测：「工作」→jobs/career/remote 有效；「招聘」→ 无（词面差异，
+    # 此时诚实回落 L3/none，不硬凑）。
+    # 要求 CJK 词长 ≥2，避免单字（「上」「大」）噪声；长串按 2-gram 展开
+    # （cjk_tokens），否则「怎么找工作」整句当一个词，与「酷工作」永不交集。
+    cjk_terms = set(cjk_term_grams(q))
+    if cjk_terms:
+        for n in nodes:
+            if not _eligible(n):
+                continue
+            name = (n.get("name") or "").lower()
+            blob = f"{n.get('title') or ''} {n.get('header') or ''}"
+            hit = sum(1 for t in cjk_terms if t in blob)
+            if hit:
+                hits[name] = float(hit) * 2.0 + min(
+                    int(n.get("topics") or 0) / 100000, 1.0)
+        if hits:
+            ranked = sorted(hits.items(), key=lambda x: -x[1])
+            return {"nodes": [n for n, _ in ranked[:top_k]], "confidence": 0.7,
+                    "layer": "cn_title", "scores": dict(ranked[:top_k])}
+
+    # ── L3 header 语义保底（低置信）────────────────────────────────────
+    # 只在描述文本里找词；要求词长 ≥4 以免通用短词误命中
+    probe = {t for t in (terms | _expand_synonyms(q)) if len(t) >= 4}
+    if probe:
+        for n in nodes:
+            if not _eligible(n):
+                continue
+            header = (n.get("header") or "").lower()
+            title = (n.get("title") or "").lower()
+            blob = f"{header} {title}"
+            hit = sum(1 for t in probe if t in blob)
+            if hit:
+                name = (n.get("name") or "").lower()
+                hits[name] = float(hit) + min(int(n.get("topics") or 0) / 100000, 1.0)
+        if hits:
+            ranked = sorted(hits.items(), key=lambda x: -x[1])
+            return {"nodes": [n for n, _ in ranked[:top_k]], "confidence": 0.5,
+                    "layer": "header", "scores": dict(ranked[:top_k])}
+
+    return {"nodes": [], "confidence": 0.0, "layer": "none", "scores": {}}
+
+
+def clear_cache() -> None:
+    """清空内存与磁盘节点缓存（测试与强制刷新用）。"""
+    with _lock:
+        _mem_cache.clear()
+    try:
+        _cache_path().unlink(missing_ok=True)
+    except Exception:
+        pass

package/scripts/variant_recall.py

@@ -0,0 +1,188 @@
+#!/usr/bin/env python3
+"""variant_recall.py — multi-query 变体召回波（Step 1，argo 普适性改进）。
+
+问题：argo 主搜索路径只发**单个** retrieval_query，模糊/新颖 query 无法通过多路
+召回补漏——召回天花板 = 单串 × 引擎自身改写能力。query_enhance.retrieval_variants
+早已写好（归一化 + 拆型号 + 同义变体），却从没接到主路径（此前只在 research /
+个别付费引擎内部用）。本模块把它接进主路径。
+
+接法（最小且隔离）：主 query 召回不足时，用变体对 combo 内主引擎补充召回，结果
+作为**独立 ranked list** 并入 clean_lists，让 rrf_merge 按「多 query 共识」天然
+加权（同一 URL 被多变体命中 → RRF 分累加 → 排更前）。
+
+隔离设计（为何绕开 _run_one 直接用 engine_search）：
+  - 不走熔断/负缓存/per-engine 记账——变体 query 的失败不该污染主引擎健康，
+    也不该把「这个变体没结果」固化成主 query 的负缓存；
+  - skip_cache=True：变体结果不读不写缓存，避免缓存键维度膨胀；
+  - 失败安全：单条变体/单引擎异常整体吞掉，绝不影响主 query 结果。
+
+成本受控（多 query 时收敛引擎数是通行做法）：最轻量预算档 mode=fast|budget
+不触发；仅主 query 召回不足才补；最多 2 变体 × combo 前 2 引擎，超时收紧到 ≤6s。
+
+为何独立成模块：search_pipeline.py 受 1000 行门禁约束（见 test_module_size_gate），
+新增召回机制应拆出而非塞进融合管线。本模块**不** import search_pipeline（避免循环），
+以 duck typing 消费 req.retrieval_query / req.engines / req.max_results / req.eff_timeout
+/ req.since_iso / req.until_iso / req.mode / req.depth 等字段。
+"""
+from __future__ import annotations
+
+import re
+from typing import Any
+
+_VARIANT_MAX_QUERIES = 2
+_VARIANT_MAX_ENGINES = 2
+_VARIANT_TIMEOUT_CAP_S = 6.0
+# 波级总预算（秒）：per-call 超时盖不住 2×2 串行累计（最坏 4×6s=24s），而主调度
+# 的 auto 预算不含这段追加——必须自设总闸。超线即停，已拿到的部分照常并入。
+_WAVE_BUDGET_S = 8.0
+
+
+def should_variant_recall(req: Any, clean_lists: list, max_results: int) -> bool:
+    """是否触发 multi-query 变体召回波。
+
+    两条硬边界（抽成纯函数供回归门直接锁）：
+      - 最轻量预算档 mode=fast|budget 不触发——时延可预期优先；
+      - 仅主 query 召回不足（clean_lists 结果总数 < max_results）才补——结果
+        够就零成本不动，不够才用变体补召回。
+
+    刻意**不**按 depth=fast 拦截：默认调用是 mode=auto + depth=fast，而 auto 有
+    10s 总预算（远宽于 mode=fast 的 6s），足以容纳「召回不足才补」的少量变体
+    调用。若连默认路径都拦掉，multi-query 对普通用户永不生效，普适性提升落空。
+
+    运维 kill-switch：ARGO_MULTI_QUERY=0 一键回滚，也便于无侵入 A/B 对照。
+    """
+    try:
+        from engine_env import env_flag
+        if not env_flag("ARGO_MULTI_QUERY", default=True):
+            return False
+    except Exception:
+        pass  # env_flag 不可用时按默认开启，不阻断搜索
+    if req.mode in ("fast", "budget"):
+        return False
+    # 答案型域 route 会下发 early_stop_min_results（1-2 行快照即完整答案）：
+    # 完整性判据按它算，否则这类域每次搜索都白付变体调用。
+    need = max_results
+    dec = getattr(req, "decision", None)
+    if isinstance(dec, dict):
+        m = dec.get("early_stop_min_results")
+        if isinstance(m, int) and 0 < m <= max_results:
+            need = m
+    return sum(len(c) for c in clean_lists) < need
+
+
+def variant_recall_wave(req: Any, engine_search: Any) -> list[list[dict[str, Any]]]:
+    """主 query 召回不足时的 multi-query 补充波；返回要追加的 ranked lists。
+
+    返回空列表表示「无需补或无处补」，调用方直接沿用主 query 的 clean_lists。
+    单条变体/单引擎异常整体吞掉（失败安全），不向上抛。
+    """
+    try:
+        from query_enhance import retrieval_variants
+    except ImportError:
+        return []
+    base = req.retrieval_query
+    if not base:
+        return []
+    # 变体池 = retrieval_variants（归一化/拆型号/同义）+ structural_variants（错误裸
+    # token/复合词短语）；合并去重、去主串，取前 _VARIANT_MAX_QUERIES 个（成本受控）。
+    pool = (retrieval_variants(base, max_n=_VARIANT_MAX_QUERIES + 1)[1:]
+            + structural_variants(base))
+    seen: set[str] = set()
+    variants: list[str] = []
+    for v in pool:
+        k = v.strip().lower()
+        if v.strip() and v != base and k not in seen:
+            seen.add(k)
+            variants.append(v)
+    if not variants:
+        return []
+    engines = (req.engines[:_VARIANT_MAX_ENGINES] if len(req.engines) > _VARIANT_MAX_ENGINES
+               else list(req.engines))
+    if not engines:
+        return []
+    try:
+        timeout = min(float(req.eff_timeout or _VARIANT_TIMEOUT_CAP_S), _VARIANT_TIMEOUT_CAP_S)
+    except (TypeError, ValueError):
+        timeout = _VARIANT_TIMEOUT_CAP_S
+    import time as _time
+    deadline = _time.monotonic() + _WAVE_BUDGET_S
+    # CLI --domain / --sub_domain 的引擎入参照主路径（engine_dispatch 同口径）透传，
+    # 否则用户的域约束被变体旁路。
+    dom_kwargs: dict[str, str] = {}
+    _d = getattr(req, "engine_domain", None)
+    _sd = getattr(req, "engine_sub_domain", None)
+    if _d:
+        dom_kwargs["domain"] = _d
+    if _sd:
+        dom_kwargs["sub_domain"] = _sd
+    extra: list[list[dict[str, Any]]] = []
+    for v in variants[:_VARIANT_MAX_QUERIES]:
+        if _time.monotonic() > deadline:
+            break
+        for eng in engines:
+            if _time.monotonic() > deadline:
+                break
+            try:
+                res = engine_search(
+                    v, eng, n=req.max_results, timeout=timeout,
+                    depth=req.depth, mode=req.mode,
+                    since=req.since_iso, until=req.until_iso, skip_cache=True,
+                    **dom_kwargs,
+                )
+            except Exception:
+                continue  # 单条变体/单引擎失败不影响主结果
+            goods = [r for r in (res or []) if isinstance(r, dict) and "error" not in r]
+            for r in goods:
+                r.setdefault("_engine", eng)
+            if goods:
+                extra.append(goods)
+    return extra
+
+
+# 结构信号变体（无词典、纯形状识别）——补 retrieval_variants 覆盖不到的两类：
+#   1. 错误/异常裸 token：从 "Rust error[E0499]" 提取 "E0499"（解错页在 issue tracker）；
+#   2. 复合词短语：给连字符/snake_case 词加引号（"sqlite-vec"），迫使精确匹配。
+# 刻意窄匹配：错误码只认 E\d{3,5}/ERR_*/XxxError 形状，不碰 HTTPS/NGINX 等全大写普通词。
+_ERR_SHAPE = re.compile(r"\b(E\d{3,5}|ERR_[A-Z0-9_]+|[A-Z][A-Za-z]*Error)\b")
+_COMPOUND_SHAPE = re.compile(r"\b[A-Za-z][A-Za-z0-9]*[-_][A-Za-z0-9][A-Za-z0-9_-]*\b")
+
+
+def structural_variants(query: str, max_n: int = _VARIANT_MAX_QUERIES) -> list[str]:
+    """结构信号变体：错误裸 token + 复合词引号短语。无词典、零依赖、确定性。"""
+    if not query or not isinstance(query, str):
+        return []
+    out: list[str] = []
+    for m in _ERR_SHAPE.finditer(query):
+        tok = m.group(1)
+        if tok and tok.lower() != query.lower():
+            out.append(tok)
+    for m in _COMPOUND_SHAPE.finditer(query):
+        tok = m.group(0)
+        if ("-" in tok or "_" in tok) and f'"{tok}"' not in out:
+            out.append(f'"{tok}"')
+    seen: set[str] = set()
+    uniq: list[str] = []
+    for v in out:
+        k = v.lower()
+        if k not in seen:
+            seen.add(k)
+            uniq.append(v)
+    return uniq[:max_n]
+
+
+def augment_with_variants(req: Any, engine_search: Any, clean_lists: list,
+                          max_results: int) -> tuple[list, int]:
+    """按 gate 决定是否补变体召回；返回 (clean_lists, 变体补回条数)。
+
+    失败安全：任何异常都原样返回入参 clean_lists，绝不影响主 query 融合。
+    补回条数单列：变体条目不进漏斗 returned 口径，调用方拿它做观测补账。
+    """
+    if not should_variant_recall(req, clean_lists, max_results):
+        return clean_lists, 0
+    try:
+        extra = variant_recall_wave(req, engine_search)
+    except Exception:
+        return clean_lists, 0
+    if not extra:
+        return clean_lists, 0
+    return clean_lists + extra, sum(len(c) for c in extra)