argo-search 2.9.8 → 2.9.9

package/scripts/recovery.py

@@ -47,8 +47,10 @@ _STOPWORDS_EN = {"the", "a", "an", "of", "for", "to", "please", "how", "what"}
 
 # 常见「过长尾修饰」：地点/时间/程度等，去掉后主体更聚焦
 _TAIL_MODIFIERS = re.compile(
-    r"(最新|最全|详细|完整|全面|2020|2021|2022|2023|2024|2025|2026|"
-    r"知乎|贴吧|论坛|大全|汇总|排行榜|一览)")
+    r"(?:\b\d{4}年?(?:度)?|\b\d{1,2}月|"
+    r"最新|最全|详细|完整|全面|2020|2021|2022|2023|2024|2025|2026|"
+    r"知乎|贴吧|论坛|大全|汇总|排行榜|一览|数据|报告|统计|分析|趋势)"
+)
 
 _QUOTE_CHARS = re.compile(r'["\'“”‘’「」『』]')
 _TOKEN_RE = re.compile(r"[\u4e00-\u9fff]|[a-zA-Z0-9]+")
@@ -119,9 +121,11 @@ def _load_synonyms() -> dict[str, Any]:
 # ── L1 放宽 ────────────────────────────────────────────────────────────────────
 
 def relax_query(query: str) -> str:
-    """L1：去引号 / 去停用词 / 去过长尾修饰。"""
+    """L1：去引号 / 去停用词 / 去过长尾修饰与孤立年份时间词。"""
     q = _QUOTE_CHARS.sub(" ", query)
     q = _TAIL_MODIFIERS.sub(" ", q)
+    # 清理孤立残留的年月单字
+    q = re.sub(r"(?<=\s)[年月](?=\s|$)|^([年月]\s+)", " ", q)
     # 去停用词（按 token）
     tokens = re.findall(r"[\u4e00-\u9fffA-Za-z0-9]+", q)
     kept = []

package/scripts/route_combo.py

@@ -502,6 +502,20 @@ def _get_engines_combo(domain: dict[str, Any], enabled: set[str], mode: str = "a
     # 学习器在此处首次解析（惰性，见模块顶部 _get_learner）：走到这里说明
     # 真的要装配 combo，这笔钱躲不掉；不进本函数的路径（缓存命中等）不付。
     _adaptive_learner = _get_learner()
+
+    # 场景分桶取分（2026-10-24）：优先用 (engine, domain, lang) 的桶分，
+    # 桶无样本时 adaptive.get_score 自动回退全局分。判据与旧口径一致，
+    # 只是多了一个维度——「引擎在 A 域强、B 域弱」现在可被路由区分。
+    _dom_name = str(domain.get("name") or "")
+    _q_lang = str((features or {}).get("primary_lang") or "")
+
+    def _score_of(e: str) -> float:
+        try:
+            return _adaptive_learner.get_score(e, _dom_name, _q_lang)
+        except TypeError:
+            # 旧版 adaptive（无 domain/lang 形参）回退全局分
+            return _adaptive_learner.get_score(e)
+
     combo = domain.get("engines_combo", [])
     primary = domain.get("primary", "anysearch")
     fallback = domain.get("fallback")
@@ -581,7 +595,7 @@ def _get_engines_combo(domain: dict[str, Any], enabled: set[str], mode: str = "a
     # 成员与 fallback，自动进入恢复链 L3 兜底。
     if primary and (
             _adaptive_learner is None
-            or _adaptive_learner.get_score(primary) >= _VERTICAL_FLOOR):
+            or _score_of(primary) >= _VERTICAL_FLOOR):
         protect.add(primary)
     # 仅 modal_card 整 combo 免 cost 裁剪（结构化路径不可被 anysearch 顶替）
     if domain_name == "modal_card":
@@ -608,14 +622,14 @@ def _get_engines_combo(domain: dict[str, Any], enabled: set[str], mode: str = "a
         # 自动回归 combo，且它仍是域 fallback（恢复链 L3 候选）。
         if domain_name in _VERTICAL_PROTECT:
             protect = {e for e in original
-                       if _adaptive_learner.get_score(e) >= _VERTICAL_FLOOR
+                       if _score_of(e) >= _VERTICAL_FLOOR
                        } | protect
         filtered = [
             e for e in filtered
             if e in protect
             or (e == primary
-                and _adaptive_learner.get_score(e) >= _VERTICAL_FLOOR)
-            or _adaptive_learner.get_score(e) >= 0.3
+                and _score_of(e) >= _VERTICAL_FLOOR)
+            or _score_of(e) >= 0.3
         ]
         if not filtered:
             filtered = original
@@ -662,7 +676,7 @@ def _get_engines_combo(domain: dict[str, Any], enabled: set[str], mode: str = "a
                     seen_fam.add(f)
                     members = [x for x in rest if _fam(x) == f]
                     if len(members) > 1:
-                        scored = [(x, _adaptive_learner.get_score(x)) for x in members]
+                        scored = [(x, _score_of(x)) for x in members]
                         top_score = max(s for _, s in scored)
                         laggards = [x for x, s in scored if top_score - s >= 0.15]
                         if laggards and len(laggards) < len(scored):

package/scripts/route_domains.py

@@ -70,10 +70,103 @@ _ZH_LANG_GATED_DOMAINS = frozenset({
 })
 
 
-# ── 域预编译（内容指纹缓存） ──────────────────────────────────────────────────
+# ── 域预编译（内容指纹缓存与锚点快筛） ──────────────────────────────────────────
 
 _compiled_domains: list[dict[str, Any]] | None = None
 _compiled_domains_id: tuple | None = None  # (name, patterns/exclude_if 内容指纹)
+_compiled_domains_ref: int | None = None
+_anchor_matcher: re.Pattern | None = None
+_anchor_to_domains: dict[str, list[int]] = {}
+_unconstrained_domains: set[int] = set()
+
+
+def _extract_anchors(src: Any) -> set[str] | None:
+    """从正则源码中提取一组必须包含其一的字面锚点词集合（全小写）。
+
+    若无法提取安全锚点（如含有纯通配、字符集类 []、通用转义字符类），返回 None。
+    """
+    if not isinstance(src, str) or not src:
+        return None
+    s = re.sub(r"^\(\?[a-zA-Z]+\)", "", src)
+    s = re.sub(r"\\b", "", s)
+    if s.startswith("(") and s.endswith(")"):
+        s = s[1:-1]
+    parts: list[str] = []
+    depth = 0
+    cur: list[str] = []
+    for ch in s:
+        if ch in ("(", "["):
+            depth += 1
+        elif ch in (")", "]"):
+            depth -= 1
+        if ch == "|" and depth == 0:
+            parts.append("".join(cur))
+            cur = []
+        else:
+            cur.append(ch)
+    if cur:
+        parts.append("".join(cur))
+
+    anchors: set[str] = set()
+    for part in parts:
+        # 正则字符类与元字符无法保证字面子串存在
+        if re.search(r"\[.*?\]", part) or re.search(r"\\[wWdDsS]", part):
+            return None
+        runs = re.findall(r"[\u4e00-\u9fff]{1,}|[a-zA-Z0-9_\-\.]{2,}", part)
+        if not runs:
+            return None
+        for r in runs:
+            anchors.add(r.lower())
+    return anchors if anchors else None
+
+
+def _init_anchor_index(compiled: list[dict[str, Any]]) -> None:
+    """初始化全局锚点自动机索引（方案一：Aho-Corasick 前置快速分桶）。"""
+    global _anchor_matcher, _anchor_to_domains, _unconstrained_domains
+    _anchor_to_domains = {}
+    _unconstrained_domains = set()
+    all_anchors: set[str] = set()
+
+    for idx, domain in enumerate(compiled):
+        entries = _pattern_entries(domain)
+        if not entries:
+            _unconstrained_domains.add(idx)
+            continue
+        dom_anchors: set[str] = set()
+        unconstrained = False
+        for p in entries:
+            match_src, _ = _split_pattern_entry(p)
+            anc = _extract_anchors(match_src)
+            if anc is None:
+                unconstrained = True
+                break
+            dom_anchors.update(anc)
+        if unconstrained or not dom_anchors:
+            _unconstrained_domains.add(idx)
+        else:
+            for term in dom_anchors:
+                _anchor_to_domains.setdefault(term, []).append(idx)
+                all_anchors.add(term)
+
+    if all_anchors:
+        sorted_terms = sorted(all_anchors, key=len, reverse=True)
+        escaped = [re.escape(t) for t in sorted_terms]
+        _anchor_matcher = re.compile("|".join(escaped), re.IGNORECASE)
+    else:
+        _anchor_matcher = None
+
+
+def _get_candidate_domain_indices(query: str) -> set[int] | None:
+    """通过锚点词快速扫描返回候选域索引集合；无索引时返回 None。"""
+    if _anchor_matcher is None:
+        return None
+    candidates = set(_unconstrained_domains)
+    for m in _anchor_matcher.finditer(query):
+        term = m.group(0).lower()
+        doms = _anchor_to_domains.get(term)
+        if doms:
+            candidates.update(doms)
+    return candidates
 
 
 def _ensure_domain_compiled(domain: dict[str, Any]) -> list[tuple[re.Pattern, re.Pattern | None]]:
@@ -134,18 +227,30 @@ def _split_pattern_entry(entry: Any) -> tuple[Any, Any]:
     return entry, None
 
 
-def _domain_fires(domain: dict[str, Any], query: str) -> bool:
-    """一个域是否成立：任一触发词命中，且它自己的否决词没命中。"""
+def _domain_fires_with_span(domain: dict[str, Any], query: str) -> tuple[bool, int, int]:
+    """一个域是否成立，并返回命中的 (是否成立, match_span_start, match_span_len)。"""
     for match_re, unless_re in _ensure_domain_compiled(domain):
         if unless_re is not None and unless_re.search(query):
             continue
-        if match_re.search(query):
-            return True
-    return False
+        m = match_re.search(query)
+        if m is not None:
+            start, end = m.span()
+            return True, start, end - start
+    return False, 0, 0
+
+
+def _domain_fires(domain: dict[str, Any], query: str) -> bool:
+    """一个域是否成立：任一触发词命中，且它自己的否决词没命中。"""
+    fires, _, _ = _domain_fires_with_span(domain, query)
+    return fires
 
 
 def _get_compiled_domains(domains: list[dict[str, Any]]) -> list[dict[str, Any]]:
-    global _compiled_domains, _compiled_domains_id
+    global _compiled_domains, _compiled_domains_id, _compiled_domains_ref
+    # 快速指针比对：当传入同一 domains 引用且已编译时 O(1) 返回，免除 97 域的 SHA1 开销
+    dom_ref = id(domains)
+    if _compiled_domains is not None and _compiled_domains_ref == dom_ref:
+        return _compiled_domains
     # 用内容指纹替代 id(domains)，避免 GC 后 id 复用导致缓存失效/错误。
     # 指纹含规则本体（只记长度会漏「改正则不改条数」的编辑），且必须覆盖
     # exclude_if / intent_required——它们和 patterns 一样会改变命中结果。
@@ -169,6 +274,8 @@ def _get_compiled_domains(domains: list[dict[str, Any]]) -> list[dict[str, Any]]
         for idx, domain in enumerate(domains)
     ]
     _compiled_domains_id = dom_fp
+    _compiled_domains_ref = dom_ref
+    _init_anchor_index(_compiled_domains)
     return _compiled_domains
 
 
@@ -311,20 +418,39 @@ def match_domains(query: str, domains: list[dict[str, Any]] | None = None,
         domains = get_domains()
     compiled = _get_compiled_domains(domains)
     hits: list[dict[str, Any]] = []
+    secondary_hits: list[tuple[dict[str, Any], float]] = []
     catch_all: dict[str, Any] | None = None
     non_zh = bool(primary_lang and primary_lang not in ("zh", "mixed", "other"))
-    for domain in compiled:
+    candidates = _get_candidate_domain_indices(query)
+    q_len = max(len(query), 1)
+
+    for idx, domain in enumerate(compiled):
         if not domain.get("patterns", []):
             catch_all = domain
             continue
         if non_zh and domain.get("name") in _ZH_LANG_GATED_DOMAINS:
             continue
-        if _domain_fires(domain, query):
-            hits.append(domain)
-        if len(hits) >= max_n:
-            break
+        if candidates is not None and idx not in candidates:
+            continue
+        fires, span_start, span_len = _domain_fires_with_span(domain, query)
+        if fires:
+            if not hits:
+                hits.append(domain)
+            else:
+                pos_ratio = span_start / q_len
+                # 方案二：跨度高（特异性强）优先提拔；同跨度下严格保持前序特化域顺位稳定
+                score = (span_len * 2.0) - (idx * 0.1) + (pos_ratio * 0.01)
+                secondary_hits.append((domain, score))
+            if len(hits) + len(secondary_hits) >= max_n:
+                break
+
+    if secondary_hits:
+        secondary_hits.sort(key=lambda x: x[1], reverse=True)
+        hits.extend(h[0] for h in secondary_hits)
+
     hits = _social_domain_first(hits)
     hits = _intent_gate(hits, query)
+    hits = hits[:max_n]
     return hits if hits else ([catch_all] if catch_all else [])
 
 

package/scripts/safe_conn.py

@@ -0,0 +1,52 @@
+#!/usr/bin/env python3
+"""safe_conn.py — 解析即锁定的 HTTP/HTTPS 连接类（DNS rebinding / TOCTOU 防护）
+
+独立成模块的理由：``http.client`` 会连带拉起 ``ssl``（实测 ≈14 ms）。
+``url_safety`` 被 ``robots_guard`` 等在**模块级**导入（见 robots_guard 的
+「轻导入」注释），若把 ``http.client`` 放在 ``url_safety`` 里，
+``test_robots_guard.test_module_import_stays_light`` 会红。连接类只在真正
+建连时经 ``net_proxy.open_connection`` 导入，不进轻导入路径。
+
+原理：``check_url()`` 在请求前解析一次 DNS，``http.client`` 在 ``connect()``
+时再解析一次——两次之间域名可改指内网（DNS rebinding）。本类在 ``connect()``
+里解析一次、过滤私网、把结果钉给本次 TCP 连接，窗口关闭；SNI/Host 仍用原域名。
+"""
+
+from __future__ import annotations
+
+import http.client
+
+from url_safety import pin_host
+
+
+class SafeHTTPConnection(http.client.HTTPConnection):
+    """解析即锁定的 HTTP 连接：TCP 只连校验过的公网 IP，Host 头仍用原域名。"""
+
+    def connect(self):
+        pinned = pin_host(self.host)
+        if pinned is None:
+            return super().connect()
+        host = self.host
+        self.host = pinned
+        try:
+            super().connect()
+        finally:
+            self.host = host
+
+
+class SafeHTTPSConnection(http.client.HTTPSConnection):
+    """解析即锁定的 HTTPS 连接：TCP 钉公网 IP，SNI/证书校验仍用原域名。"""
+
+    def connect(self):
+        pinned = pin_host(self.host)
+        if pinned is None:
+            return super().connect()
+        host = self.host
+        self.host = pinned
+        try:
+            http.client.HTTPConnection.connect(self)      # 仅 TCP
+        finally:
+            self.host = host
+        server_hostname = self._tunnel_host or host
+        self.sock = self._context.wrap_socket(
+            self.sock, server_hostname=server_hostname)

package/scripts/search_entry.py

@@ -392,4 +392,5 @@ def dispatch(req: _SearchRequest, run: _SearchRun, hooks: _SearchHooks) -> _Sear
         quota_batch=quota_batch,
         run_one=_run_one,
         ingest=_ingest,
+        stranded=_dispatch.stranded,
     )

package/scripts/search_pipeline.py

@@ -156,6 +156,9 @@ class _SearchRun:
     useful_ms: int = 0
     dispatch_tail: dict[str, int] = field(default_factory=dict)
     early_stopped: bool = False
+    # 早停弃置且仍存活的 (engine, holder, now_fn)：finalize 交给
+    # tail_completion 后台收割。纯数据字段，不改变任何既有阶段的行为。
+    stranded: tuple = ()
     budget_used_ms: int | None = None
     budget_total_ms: int | None = None
     elapsed: int = 0
@@ -772,7 +775,7 @@ def finalize(req: _SearchRequest, run: _SearchRun, hooks: Any) -> dict[str, Any]
     # 自适应学习（单事务批量写入 + cache_guard 统一状态态过滤）
     try:
         import contextlib
-        from adaptive import get_learner
+        from adaptive import get_learner, scenario_of
         learner = get_learner()
         _outcome_of = {o.get("engine"): o
                        for o in engine_outcomes if isinstance(o, dict)}
@@ -797,12 +800,27 @@ def finalize(req: _SearchRequest, run: _SearchRun, hooks: Any) -> dict[str, Any]
                         quality = None
                 learner.record(eng, success=success, latency_ms=latency,
                                cost=0.0 if cost >= 0.85 else 0.001, empty=empty,
-                               quality=quality)
+                               quality=quality, **scenario_of(decision))
     except ImportError:
         pass
     except Exception as e:
         _log(f"自适应学习记录跳过: {type(e).__name__}")
 
+    # 早停后台补全（2026-10-25）：弃置引擎的交付不再丢弃，宽限内完成的
+    # 记学习器真实成绩 + 合并写 L2 缓存（ARGO_TAIL_COMPLETE_S 控制，0=关）。
+    # 放在缓存写与学习记账之后：补全读的是刚写的主缓存条目；主响应已定，
+    # 这里的一切都是锦上添花，异常 fail-open。
+    if run.stranded:
+        try:
+            from tail_completion import hand_off
+            hand_off(run.stranded, query=query,
+                     cache_engine_key=cache_engine_key,
+                     max_results=max_results, domain=domain,
+                     mode=mode, depth=depth, decision=decision,
+                     skip_cache=skip_cache, cache_instance=cache)
+        except Exception as e:
+            _log(f"后台补全移交跳过: {type(e).__name__}")
+
     # 语言偏好：记录本轮查询语 + 输出观测快照（默认中英 + 系统 + 习惯）
     lang_pref_info: dict[str, Any] | None = None
     try:

package/scripts/search_rank.py

@@ -96,6 +96,12 @@ _ENGINE_FUSION_WEIGHTS: dict[str, float] = {
     "stackoverflow": 1.1, "imdb": 1.2, "thesportsdb": 1.2, "itunes": 1.2,
     "finviz": 1.2, "sina_quote": 1.2, "tencent_quote": 1.2, "eastmoney": 1.2,
     "fred": 1.3, "worldbank": 1.3, "nbs_stats": 1.3, "eurostat": 1.3, "fx_rate": 1.2, "frankfurter": 1.2,
+    # 2026-10-25 补表：学术聚合与官方一手数据此前表外=1.0 基线。实证缺口：
+    # 学术域查询常由 core 独家交付（当日实测组合里 arxiv/local_pubmed 零结果、
+    # 只 core 有货）却拿基线权重；官方 open data / 法律 / 标准系同理。
+    "core": 1.3, "openreview": 1.3, "zenodo": 1.2, "datacite": 1.2,
+    "sec_edgar": 1.3, "federal_register": 1.3, "eu_opendata": 1.3,
+    "egov_law": 1.3, "openstd": 1.3, "who_gho": 1.3, "usgs": 1.3, "nasa_cmr": 1.3,
     # 通用引擎（基线）
     "duckduckgo": 1.0, "local_bing": 1.0, "local_duckduckgo": 1.0,
     "local_google": 1.0, "anysearch": 1.05, "byted": 1.1, "bocha": 1.0,

package/scripts/serp_guard.py

@@ -334,3 +334,26 @@ def filter_content_farms(results: list) -> list:
         kept.append(r)
     return kept
 
+
+# ── 自适应放宽建议（2026-10-23 方案四）───────────────────────────────────
+
+_RELAX_TAIL_RE = re.compile(
+    r"(?:\b\d{4}年?(?:度)?|\b\d{1,2}月|"
+    r"最新|最全|详细|完整|全面|2020|2021|2022|2023|2024|2025|2026|"
+    r"知乎|贴吧|论坛|大全|汇总|排行榜|一览|数据|报告|统计|分析|趋势)"
+)
+
+
+def suggest_relaxed_query(query: str) -> str:
+    """针对 SERP 守卫击杀场景的自适应放宽查询（剥离过度约束的修饰与年份词）。"""
+    if not query or not isinstance(query, str):
+        return ""
+    q = _RELAX_TAIL_RE.sub(" ", query)
+    q = re.sub(r"(?<=\s)[年月](?=\s|$)|^([年月]\s+)", " ", q)
+    tokens = re.findall(r"[\u4e00-\u9fffA-Za-z0-9]+", q)
+    stopwords = {"的", "了", "呢", "吧", "请问", "怎么", "如何", "一下", "关于", "有关", "求", "谁知道",
+                 "the", "a", "an", "of", "for", "to", "how", "what"}
+    kept = [t for t in tokens if t.lower() not in stopwords]
+    relaxed = " ".join(kept).strip()
+    return relaxed or re.sub(r"\s+", " ", q).strip() or query
+

package/scripts/tail_completion.py

@@ -0,0 +1,212 @@
+"""tail_completion.py — 早停后台补全：慢源交付从「丢弃」变「补齐」。
+
+## 为什么（2026-10-25）
+
+七天窗口 1185 条真实查询里 74% 发生 early-stop。被放弃的交付不是低质货：
+离线回放（bench_tail_ab --quality）显示被放弃交付 81% 来自 anysearch，相关度
+代理比全库均线高 0.125；五条对照查询里四条「唯一有结果的就是慢源」（证据与
+口径见 docs/QUALITY_OF_SLOW_SOURCES.md）。早停省的是**用户等待**，不该连
+**交付**一起丢——那是在拿准确性换速度。缩尾宽已被实证否决，本模块是拍板的
+正确方向：慢源不拖住快源（早交付），但慢源的交付进缓存（后台补全）。
+
+## 做什么
+
+engine_dispatch 在早停弃置引擎时把 (engine, holder, now_fn) 交给本模块——
+主响应与既有记账逐位不变（cancelled outcome / abandoned_ms 照记）。本模块
+起一个 daemon 收割线程，在主流程返回后继续等被弃置的引擎，宽限内完成的：
+
+1. 学习器记真实成绩（success / latency / quality / 场景分桶标签）——此前
+   cancelled 被 cache_guard.should_record_adaptive 跳过，慢源的真实表现
+   从没进过学习器，场景分桶（engine×domain×lang）也少一笔真数据；
+2. 把交付合并写回 L2 combo 缓存（URL 去重、新条目追加、缺省 score 用词面
+   相关度）——同查询第二次免费拿到「快源+慢源」的全量覆盖。
+
+timeout 弃置不收：那是引擎确实超窗（甚至卡死），补全等于鼓励慢源；
+cancelled 是「编排收工决定，引擎没失败」——两者语义不同（见
+engine_dispatch._settle_pending 的注释）。
+
+## 进程语义
+
+收割线程是 daemon；CLI 进程退出前由 atexit 宽限等待（hand_off 首次调用时
+注册，无 stranded 的进程零成本、不注册）。MCP/daemon 常驻进程不退出，
+自然收割全部。宽限从**入队时刻**起算整批（job 级 deadline），不做逐引擎
+累加——实测被放弃交付从早停时刻起的剩余等待 p50 2306ms / p90 3883ms。
+
+## 开关
+
+ARGO_TAIL_COMPLETE_S：宽限秒数（默认 3.0；0=禁用整个机制，行为回到
+纯丢弃）。改动记得同步 references/usage.md 的开关总表（usage_doc_gates）。
+"""
+
+from __future__ import annotations
+
+import atexit
+import os
+import threading
+
+_LOCK = threading.Lock()
+_JOBS: list[dict] = []
+_WORKER: threading.Thread | None = None
+_ATEXIT_REGISTERED = False
+_STATS = {"salvaged": 0, "expired": 0, "recorded": 0}
+_POLL_INTERVAL_S = 0.05
+
+
+def grace_seconds() -> float:
+    """收割宽限（ARGO_TAIL_COMPLETE_S，默认 3.0；<=0 禁用）。"""
+    try:
+        return float(os.environ.get("ARGO_TAIL_COMPLETE_S", "3.0") or 3.0)
+    except ValueError:
+        return 3.0
+
+
+def hand_off(stranded, *, query, cache_engine_key, max_results,
+             domain, mode, depth, decision, skip_cache=False,
+             cache_instance=None) -> None:
+    """把早停弃置的引擎交给后台收割。
+
+    ``stranded`` 是 engine_dispatch 产出的 ``[(engine, holder, now_fn), ...]``：
+    holder["r"] 出现即完成（与 _ingest_holder 同判据），now_fn 用于算真实
+    latency（dispatch 可能跑在单调钟上，收割线程不能用墙钟去减）。
+    ``cache_instance`` 是本次请求的缓存实例（req.cache）：补全读写的必须是
+    同一实例（L1 内存态 + L2 落盘一致），模块级没有全局缓存可拿。
+    其余参数与 finalize 的 cache.set / learner.record 同源同口径。
+    任何异常 fail-open：补全失败只丢「锦上添花」，不影响主响应。
+    """
+    grace = grace_seconds()
+    if grace <= 0 or not stranded:
+        return
+    global _ATEXIT_REGISTERED
+    with _LOCK:
+        if not _ATEXIT_REGISTERED:
+            atexit.register(wait_for_completion)
+            _ATEXIT_REGISTERED = True
+        _JOBS.append({
+            "stranded": list(stranded),
+            "deadline": _now_wall() + grace,
+            "query": query, "cache_engine_key": cache_engine_key,
+            "max_results": max_results, "domain": domain,
+            "mode": mode, "depth": depth, "decision": decision or {},
+            "skip_cache": bool(skip_cache) or cache_instance is None,
+            "cache": cache_instance,
+        })
+        _start_worker_locked()
+
+
+def wait_for_completion(timeout_s: float | None = None) -> None:
+    """等收割线程收尾（atexit 出口 / 测试用）。宽限耗尽即返回，不无限等。"""
+    t = _WORKER
+    if t is not None and t.is_alive():
+        budget = timeout_s if timeout_s is not None else grace_seconds() + 0.5
+        t.join(timeout=budget)
+
+
+def stats() -> dict:
+    """收割计数（可观测口，供诊断；不改任何行为）。"""
+    with _LOCK:
+        return dict(_STATS)
+
+
+def _now_wall() -> float:
+    import time
+    return time.time()
+
+
+def _start_worker_locked() -> None:
+    global _WORKER
+    if _WORKER is not None and _WORKER.is_alive():
+        return
+    _WORKER = threading.Thread(target=_worker, daemon=True,
+                               name="argo-tail-completion")
+    _WORKER.start()
+
+
+def _worker() -> None:
+    """串行收割队列：宽限内完成的记学习器+合并缓存，超宽限标 expired。"""
+    import time
+    while True:
+        with _LOCK:
+            if not _JOBS:
+                return
+            job = _JOBS.pop(0)
+        for eng, holder, now_fn in job["stranded"]:
+            remaining = job["deadline"] - _now_wall()
+            while holder.get("r") is None and remaining > 0:
+                time.sleep(min(_POLL_INTERVAL_S, remaining))
+                remaining = job["deadline"] - _now_wall()
+            res = (holder.get("r") or (None,))[1] if holder.get("r") else None
+            if res is None:
+                with _LOCK:
+                    _STATS["expired"] += 1
+                continue
+            goods = [r for r in (res or [])
+                     if isinstance(r, dict) and "error" not in r]
+            with _LOCK:
+                _STATS["salvaged"] += 1
+            try:
+                _record_adaptive(eng, goods, holder, now_fn, job)
+            except Exception:
+                pass
+            if not job["skip_cache"]:
+                try:
+                    _merge_into_cache(eng, goods, job)
+                except Exception:
+                    pass
+
+
+def _record_adaptive(eng, goods, holder, now_fn, job) -> None:
+    """学习器记真实成绩（口径与 search_pipeline.finalize 对齐）。"""
+    from adaptive import get_learner, scenario_of
+    from query_signals import result_relevance
+    success = bool(goods)
+    try:
+        lat_ms = float((now_fn() - holder.get("t0", now_fn())) * 1000.0)
+    except Exception:
+        lat_ms = 0.0
+    quality = None
+    if success:
+        try:
+            quality = result_relevance(job["query"], goods)
+        except Exception:
+            quality = None
+    with _LOCK:
+        _STATS["recorded"] += 1
+    get_learner().record(eng, success=success, latency_ms=max(0.0, lat_ms),
+                         cost=0.001, empty=not success, quality=quality,
+                         **scenario_of(job["decision"]))
+
+
+def _merge_into_cache(eng, goods, job) -> None:
+    """交付合并写回 L2 combo 缓存：读现条目 → URL 去重追加 → 同 key 覆盖。
+
+    只在已有缓存条目时合并（本机制补的是「快源已写的那份」）；主缓存被守卫
+    拒写时这里不硬造。score 缺省用词面相关度，保证追加条目有可排序的分数。
+    """
+    from query_signals import result_relevance
+    cache = job["cache"]
+    cur = cache.get(job["query"], job["cache_engine_key"],
+                    job["max_results"], domain=job["domain"],
+                    mode=job["mode"], depth=job["depth"])
+    if not cur or not isinstance(cur.get("results"), list) or not goods:
+        return
+    existing = {r.get("url") for r in cur["results"]
+                if isinstance(r, dict)}
+    new: list[dict] = []
+    for r in goods:
+        if not isinstance(r, dict) or r.get("url") in existing:
+            continue
+        item = dict(r)
+        if "score" not in item:
+            try:
+                item["score"] = round(float(result_relevance(job["query"], [r])), 4)
+            except Exception:
+                item["score"] = 0.3
+        new.append(item)
+    if not new:
+        return
+    payload = dict(cur)
+    payload["results"] = list(cur["results"]) + new
+    payload["engines_used"] = sorted({*(cur.get("engines_used") or []), eng})
+    cache.set(job["query"], job["cache_engine_key"], job["max_results"],
+              payload, domain=job["domain"], mode=job["mode"],
+              depth=job["depth"])