argo-search 1.0.1 → 2.9.8

package/scripts/search.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python3
 """
-search.py — Unified Search v2 CLI 主入口 & 执行编排
+search.py — Unified Search v2 CLI 主入口 & 执行调度
 
 职责：
   - 解析命令行参数
@@ -14,306 +14,569 @@ search.py — Unified Search v2 CLI 主入口 & 执行编排
 
 from __future__ import annotations
 
-import argparse
-import json
-import os
-import sys
 import time
-from concurrent.futures import ThreadPoolExecutor, as_completed
-from enum import Enum
-from typing import Any, Callable, Optional
+
+# 尽早取时点：**放在重导入之前**，整条 import 链才算得进「固定开销」。
+# （放在导入之后测出来的是 0——模块体跑完时导入早已结束。）
+# 解释器自身的启动（本机 ~15 ms）到这里仍然测不到；那部分只能由外部
+# `time` 命令给，所以不在这儿谎报成已测。
+_MODULE_T0 = time.perf_counter()
+
+
+from engine_env import env_flag  # noqa: E402
+import json  # noqa: E402
+import os  # noqa: E402
+import re  # noqa: E402
+import sys  # noqa: E402
+from typing import Any, Callable, Optional, TYPE_CHECKING  # noqa: E402
 
 SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
 sys.path.insert(0, SCRIPT_DIR)
 
-from cache import SearchCache
-from route import route_query
-from engines import search as engine_search, available_engines
-from config import get_execution_config, get_cost_factor
+# cache 的导入**推迟到真正要用时**（2026-09-27，方案 B3）。
+# cache.py 的 import 链（sqlite3 / shutil / tempfile / gzip / hashlib）实测
+# 16-25ms，而 import search 本身只要 ~30ms；它只在「真的要读/写缓存」时
+# 才需要——`--list-engines`、纯路由决策、plan_only 路径都用不上。
+#
+# SearchCache 仍是本模块的公开面（tests/test_search_timing.py 写
+# `S.SearchCache()`），故用显式的 `__getattr__` 转发保持可访问。
+# 踩过的坑：**不要**在模块内写裸名 `SearchCache()` 指望 __getattr__ 兜底——
+# PEP 562 只管 `search.SearchCache` 这种属性访问，模块内全局名查找直接
+# NameError（实测 33 条测试集体红）。所以构造点是**函数内局部 import**，
+# 公开面是**属性访问**，两条路各走各的。
+if TYPE_CHECKING:  # pragma: no cover - 仅类型检查期
+    from cache import SearchCache  # noqa: F401
+
+# 被移除的 `query_similarity` 是**从未被调用**的死导入（全仓无引用）。
+
+
+def __getattr__(name: str):
+    """按需转发 cache.SearchCache（模块级惰性属性，仅服务 `search.SearchCache`）。"""
+    if name == "SearchCache":
+        from cache import SearchCache
+        globals()["SearchCache"] = SearchCache
+        return SearchCache
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+from config import get_cost_factor, get_execution_config, get_engines  # noqa: E402
+
+# ── 排序/融合层（search_rank）与输出层（search_output）按职责拆出，这里同名转出，
+# 调用方与既有测试无需改。打桩点若落在这些符号上，必须打在**读取处**（实现模块）。
+# **别按「谁引用了它」裁剪这份清单**：测试用字符串引用模块属性（patch.object
+# (search, "_tokens")），AST 统计会漏——照它裁 24 个名字，全量测试红 83 条。
+from search_rank import (  # noqa: E402
+    _RERANK_DEGRADED_STATUSES,
+    _CJK_OR_WORD,
+    _ENGINE_FUSION_WEIGHTS,
+    _REL_FACTOR_TTL,
+    _RERANK_BREAKER_KEY,
+    _RERANK_POOL_FACTOR,
+    _RERANK_POOL_MIN,
+    _align_facts_safe,
+    _apply_consensus_and_sort,
+    _attach_selection_signals,
+    _bigrams,
+    _canonical_url,
+    _content_sig,
+    _content_similarity,
+    _distinct_data_rows,
+    _domain_matches,
+    _domain_score_floors,
+    _engine_weight,
+    _jaccard,
+    _lang_prefer_rerank,
+    _note_rerank_failure,
+    _rel_factor_cache,
+    _rerank_breaker,
+    _rerank_pool_limit,
+    _rrf_weighted_default,
+    _score_completeness,
+    _score_relevance,
+    _single_reliability,
+    _tokens,
+    _weight_cache,
+    deduplicate_by_url,
+    filter_results_by_domains,
+    invalidate_engine_weight_cache,
+    local_five_dim_rerank,
+    minhash_dedupe,
+    rerank_results,
+    rrf_merge,
+)
+from search_entry import _SearchHooks, dispatch, prepare  # noqa: E402
+from search_pipeline import (  # noqa: E402
+    _SearchRequest,
+    _SearchRun,
+    finalize,
+    postprocess,
+)
+from search_output import (  # noqa: E402
+    _ShapeContext,
+    shape_response,
+    _collect_errors,
+    FUNNEL_STAGES,
+    _AGENT_RESULT_FIELDS,
+    _slow_query_ttl,
+    _strip_for_agent,
+    build_funnel,
+    build_sources,
+    describe_funnel,
+    format_text_output,
+    format_timing,
+    funnel_collapse,
+)
+
+# import 链结束的时点。固定开销 = 导入 + argparse + 收尾；这里把导入那段
+# 单独报出来，因为它的可控性最好（延迟导入 / 拆模块就是冲它去的）。
+_IMPORTS_DONE = time.perf_counter()
+
+
+# ── engines 惰性代理 ──────────────────────────────────────────────────────────
+# engines 是 import 链里最重的一块：它连带 engines_builders 的 7 个模块与
+# urllib.request 的 http/ssl/email 链，实测占 `import search` 的 39%（交错
+# A/B 中位 47.5ms → 29.2ms，即 18.3ms）。而**缓存命中**这一跳对它零依赖——
+# 实测缓存命中时 engine_search 与 available_engines 调用次数都是 0，两者只在
+# 派发、清单与错误路径上用到。改成惰性代理后：日常热路径省下整棵子树，冷路径
+# 在首次派发时照常导入（总量不变，而冷路径本来就被网络耗时主导）。
+#
+# 必须是**模块级函数**而不是 import 内联：网络出口靠属性替换被顶替——
+# search_benchmark 直接 `search.engine_search = fake`，
+# tests/test_budget_observability 用 `patch("search.engine_search")`。属性被换掉
+# 后代理自然让位，测试与基准的既有语义逐位不变。
+
+def engine_search(*args, **kwargs):
+    """惰性包装 engines.search（见上方说明）。"""
+    from engines import search as _engine_search
+    return _engine_search(*args, **kwargs)
+
+
+def available_engines(*args, **kwargs):
+    """惰性包装 engines.available_engines（见上方说明）。"""
+    from engines import available_engines as _available_engines
+    return _available_engines(*args, **kwargs)
+
+
+# ── 时间辅助（时间窗归一化 / published_at 解析 / 后过滤 / 排序）──────────────
+#
+# 时间窗三层语义：
+#   1. 下推（since/until → 引擎）：入口统一归一化为绝对 ISO，引擎收到确定值
+#   2. 后过滤（结果层保底）：引擎不带时间窗能力时，按 published_at 剔除超窗
+#   3. 排序（--sort）：仅展示顺序，不影响召回
+#
+# 归一化规则：相对量（Nd/Nh/Nw）→ 绝对日期；绝对时间无时区按本地时区解释
+# （与 published_ts 一致）；非法输入保持原样下推、不参与后过滤，不阻断搜索。
+
+from time_utils import (  # noqa: E402
+    published_ts as _published_ts,
+    normalize_time_window as _normalize_time_window,
+    apply_time_window as _apply_time_window,
+    sort_results_by_time as _sort_results,
+    is_time_capable as _is_time_capable,
+)
+
+
+# ── 查询改写辅助 ────────────────────────────────────────────────────────────────
+# 实现在 query_signals（纯本地启发式，无网络、无编排状态），此处只做别名导入，
+# 保持既有调用点与测试的 `search._query_coverage_ok` 等名字不变。
+
+from query_signals import (  # noqa: E402
+    apply_query_rewrite as _apply_query_rewrite,
+    results_sufficient as _results_sufficient,
+    cumulative_sufficient as _cumulative_sufficient,
+    query_coverage_ok as _query_coverage_ok,
+)
+
+
+def _missing_env_for(eng: str) -> list[str]:
+    """返回引擎缺失的环境变量名列表；检测不可用时返回空（不阻断搜索）。
+
+    与路由层 env_ready(spec) 同计算方式：查当前注册表拿 spec，否则
+    声明里自定义 required_env 的引擎在此拦截不到（仅 KNOWN_ENV_ALIASES
+    成员能命中）。注册表值是 callable（spec 在闭包里）时退化为原名检测。
+    """
+    try:
+        from engine_env import missing_env_for as _missing
+        spec = None
+        try:
+            from engines import get_engine_spec
+            spec = get_engine_spec(eng)
+        except Exception:
+            spec = None
+        return _missing(eng, spec)
+    except Exception:
+        return []
 
 
-# ── 进度阶段 ──────────────────────────────────────────────────────────────────
+# 结局分类（状态码表 / 配额与拦截关键词 / classify_engine_outcome）已随编排段
+# 搬到 engine_dispatch；这里只导入仍需在 search 内部用到的两个名字：
+# classify_engine_outcome 供下面的 run_dispatch 注入，配额关键词供自适应
+# 学习跳过判定。
 
-class Stage(str, Enum):
-    START = "start"
-    CACHE_HIT = "cache_hit"
-    ROUTING = "routing"
-    SEARCHING = "searching"
-    MERGING = "merging"
-    DONE = "done"
+from engine_dispatch import (  # noqa: E402
+    classify_engine_outcome as _classify_engine_outcome,
+    run_dispatch,
+)
+from local_seek import _run_local_seek, _LOCAL_SEEK_TIMEOUT_S  # noqa: E402
 
 
-# ── RRF 融合 ───────────────────────────────────────────────────────────────────
+# 缓存命中路径的 include-local 宽限窗（秒）：主结果命中缓存时墙钟已极小
+# （~25ms），为本地命中等满 _LOCAL_SEEK_TIMEOUT_S 会把快路径拖成慢路径
+# （实测 cached 查询 111~138ms vs --no-local 55ms）。宽限覆盖 seek 的常规
+# 60~140ms；超窗的慢 seek 本次不并入——本地命中缺席总好过拖垮快路径。
+def _local_seek_grace_s() -> float:
+    """本地搜索宽限窗（秒），允许环境变量覆盖。"""
+    try:
+        raw = os.environ.get("ARGO_LOCAL_SEEK_GRACE_S")
+        if raw is not None and raw.strip() != "":
+            return max(0.0, float(raw))
+    except (TypeError, ValueError):
+        pass
+    return 0.25
 
-def rrf_merge(ranked_lists: list[list[dict[str, Any]]], k: int = 60) -> list[dict[str, Any]]:
-    """Reciprocal Rank Fusion 合并多引擎结果。"""
-    scores: dict[str, float] = {}
-    items: dict[str, dict[str, Any]] = {}
-
-    for results in ranked_lists:
-        for i, r in enumerate(results):
-            url = r.get("url", "") or f"__title__:{r.get('title', '')}"
-            scores[url] = scores.get(url, 0.0) + 1.0 / (k + i + 1)
-            if url not in items:
-                items[url] = dict(r)
-            else:
-                if r.get("score", 0) > items[url].get("score", 0):
-                    items[url].update(r)
-                sources = {items[url].get("source", ""), r.get("source", "")}
-                items[url]["source"] = "/".join(s for s in sources if s)
-
-    ranked = sorted(scores.items(), key=lambda x: -x[1])
-    return [items[url] for url, _ in ranked]
-
-
-def deduplicate_by_url(results: list[dict[str, Any]]) -> list[dict[str, Any]]:
-    """URL 去重。"""
-    seen: set[str] = set()
-    out = []
-    for r in results:
-        key = r.get("url", "") or f"title:{r.get('title', '')}"
-        if key not in seen:
-            seen.add(key)
-            out.append(r)
-    return out
 
+_LOCAL_SEEK_GRACE_S = _local_seek_grace_s()
 
-# ── Bocha Reranker ──────────────────────────────────────────────────────────────
+# include-local 的本地搜索 worker：单例下沉到 local_seek 模块，避免 search.py
+# 在 daemon.py 的 runpy.run_module("search", run_name="__main__") 下重跑顶层时
+# 把 _LOCAL_SEEK_EXECUTOR 覆写为 None、导致每次调用泄漏一个 ThreadPoolExecutor。
+def _get_local_seek_executor():
+    from local_seek import get_local_seek_executor
+    return get_local_seek_executor()
 
-def rerank_results(query: str, results: list[dict[str, Any]],
-                   top_n: int = 10, timeout: float = 5) -> list[dict[str, Any]]:
-    """使用博查语义排序模型对搜索结果二次精排。"""
-    if not results or len(results) <= 1:
-        return results
-
-    api_key = os.environ.get("BOCHA_API_KEY", "")
-    if not api_key:
-        return results
-
-    documents = []
-    for r in results:
-        doc_text = f"{r.get('title', '')} {r.get('snippet', '')}".strip()
-        documents.append(doc_text or "empty")
-
-    import urllib.request
-    payload = json.dumps({
-        "model": "gte-rerank", "query": query,
-        "documents": documents[:50],
-        "top_n": min(top_n, len(documents)),
-        "return_documents": False,
-    }).encode("utf-8")
-
-    req = urllib.request.Request(
-        "https://api.bocha.cn/v1/rerank", data=payload,
-        headers={"Content-Type": "application/json", "Authorization": f"Bearer {api_key}"},
-    )
+
+def _note_remote_quota_exhausted(engine: str, detail: str) -> None:
+    """远端明示配额耗尽（如 byted 10406）→ 标记到周期边界自动恢复。
+
+    标记后路由组合层全模式排除该引擎、备用源自然接管；恢复无需人工干预。
+    """
     try:
-        with urllib.request.urlopen(req, timeout=timeout) as resp:
-            data = json.loads(resp.read().decode("utf-8"))
-            rerank_results_list = data.get("data", {}).get("results", [])
-            if not rerank_results_list:
-                return results
-            scored = []
-            for rr in rerank_results_list:
-                idx = rr.get("index", -1)
-                score = rr.get("relevance_score", 0)
-                if 0 <= idx < len(results):
-                    item = dict(results[idx])
-                    orig_score = item.get("score", 0) or 0
-                    item["score"] = round(score * 0.7 + orig_score * 0.3, 4)
-                    scored.append(item)
-            if scored:
-                scored.sort(key=lambda x: x.get("score", 0), reverse=True)
-                return scored[:top_n]
-    except Exception:
+        from quota import get_quota_manager
+        get_quota_manager().mark_remote_exhausted(engine, reason=detail)
+    except Exception:  # 侧信道：标记失败不得影响搜索主流程（规则见 except_sets）
         pass
-    return results
 
 
-# ── 执行层 ─────────────────────────────────────────────────────────────────────
+# 进度阶段枚举住在 search_types（执行层与加工层都要发进度事件，见那里的注释）。
+from search_types import Stage  # noqa: E402
 
-def execute_search(query: str, decision: dict[str, Any], max_results: int,
-                   timeout: int, depth: str, cache: SearchCache, skip_cache: bool,
-                   mode: str = "auto",
-                   on_progress: Optional[Callable[[Stage, dict[str, Any]], None]] = None) -> dict[str, Any]:
-    """执行搜索：缓存 → 引擎 → 融合 → 精排 → 写缓存。"""
-    domain = decision.get("domain") or "general"
-    engine_label = decision.get("engine", "auto")
-    engines_combo = decision.get("engines_combo", decision.get("engines", [engine_label]))
-    engines = engines_combo
-    parallel = decision.get("parallel", False) and len(engines) > 1
-
-    if on_progress:
-        on_progress(Stage.START, {"query": query})
-
-    cache_engine_key = "+".join(sorted(engines)) if len(engines) > 1 else engines[0]
-
-    if on_progress:
-        on_progress(Stage.ROUTING, {"domain": domain, "engine": engine_label, "engines": engines})
-
-    # 缓存命中
-    if not skip_cache:
-        hit = cache.get(query, cache_engine_key, max_results, domain=domain)
-        if hit:
-            if on_progress:
-                on_progress(Stage.CACHE_HIT, {"cache_level": hit.get("_cache_level", "L?")})
-            tfidf_scores = decision.get("tfidf_scores", [])
-            if tfidf_scores and all(s.get("score", 0) == 0 for s in tfidf_scores):
-                tfidf_scores = []
-            return {
-                "query": query, "engine": engine_label, "engines": engines,
-                "engines_combo": engines_combo, "cached": True,
-                "cache_level": hit.get("_cache_level", "L?"),
-                "domain": domain, "elapsed_ms": 0,
-                "tfidf_scores": tfidf_scores,
-                "results": hit.get("results", []),
-                "count": len(hit.get("results", [])),
-                "mode": mode,
-            }
 
-    if on_progress:
-        on_progress(Stage.SEARCHING, {"engines": engines})
+# ── RRF 融合 ───────────────────────────────────────────────────────────────────
 
-    t0 = time.time()
-    raw_results: dict[str, list[dict[str, Any]]] = {}
+# URL 归一化的唯一来源在 url_canon：本仓曾有四份各自实现的「URL 归一」
+# （search / plan / candidate_envelope / research_dossier，追踪参数表与
+# 大小写规则各不相同），导致同一链接在融合层与 dossier 层归一成不同键。
+# 此处只做薄转发，规则改动一律进 url_canon。
+from url_canon import canonical_url as _canonical_url_impl  # noqa: E402
 
-    exec_cfg = get_execution_config()
-    retry_count = exec_cfg.get("retry_count", 0)
 
-    def _exec_engine(eng: str, retries: int = retry_count) -> list[dict[str, Any]]:
-        for attempt in range(retries + 1):
-            res = engine_search(query, eng, n=max_results, timeout=timeout, depth=depth, mode=mode)
-            if res and any("error" not in r for r in res):
-                return res
-        if depth != "balanced":
-            return engine_search(query, eng, n=max_results, timeout=timeout, depth="balanced", mode=mode)
-        return res if res else []
 
-    if parallel:
-        with ThreadPoolExecutor(max_workers=min(len(engines), 3)) as ex:
-            futures = {ex.submit(_exec_engine, eng): eng for eng in engines}
-            try:
-                for fut in as_completed(futures, timeout=timeout + 2):
-                    eng = futures[fut]
-                    try:
-                        raw_results[eng] = fut.result()
-                    except Exception as e:
-                        raw_results[eng] = [{"error": str(e), "source": eng}]
-            except TimeoutError:
-                for fut in futures:
-                    if not fut.done():
-                        fut.cancel()
-                        eng = futures[fut]
-                        raw_results[eng] = [{"error": "timeout", "source": eng}]
-            for fut in futures:
-                if not fut.done():
-                    fut.cancel()
-    else:
-        for eng in engines:
-            res = _exec_engine(eng)
-            raw_results[eng] = res
-            if res and any("error" not in r for r in res):
-                break
-
-    elapsed = int((time.time() - t0) * 1000)
-
-    # 融合
-    valid_lists = [res for res in raw_results.values()
-                   if res and not any("error" in r for r in res)]
-    if len(valid_lists) > 1:
-        merged = rrf_merge(valid_lists)[:max_results]
-    elif valid_lists:
-        merged = deduplicate_by_url(valid_lists[0])[:max_results]
-    else:
-        merged = []
 
-    # Reranker 精排
-    if merged and len(merged) > 1:
-        merged = rerank_results(query, merged, top_n=max_results)
+# 引擎融合权重（WG-RRF：按来源质量加权，权威源提权、社交/低质源降权）
 
-    # 按 score 排序
-    if merged:
-        merged.sort(key=lambda r: abs(r.get("score", 0) or 0), reverse=True)
-        merged = merged[:max_results]
 
-    # 内嵌可信度评分（快速版本：authority + freshness，不含 cross_validation）
-    if merged:
-        try:
-            from evidence import score_authority, score_freshness
-            for r in merged:
-                url = r.get("url", "")
-                source = r.get("source", "")
-                auth = score_authority(url, source)
-                fresh = score_freshness(r)
-                r["authority"] = auth["score"]
-                r["authority_tier"] = auth["tier"]
-                r["freshness"] = fresh["score"]
-        except Exception:
-            pass  # evidence 模块不可用时跳过
-
-    if on_progress:
-        on_progress(Stage.MERGING, {"count": len(merged)})
-
-    result_payload = {
-        "results": merged, "engines_used": list(raw_results.keys()), "domain": domain,
-    }
-
-    # 写缓存
-    if not skip_cache:
-        effective_ttl = None
-        if elapsed > 2000:
-            multiplier = min(2 ** (elapsed // 2000), 8)
-            base_ttl = cache.resolve_ttl(domain)
-            effective_ttl = base_ttl * multiplier
-        cache.set(query, cache_engine_key, max_results, result_payload,
-                  domain=domain, ttl=effective_ttl)
-
-    # 记录自适应学习数据
+# 动态可靠性因子（weakest-link，论文 arxiv 2508.01405）：熔断/高错误引擎降权，
+# 避免「弱检索路径」在融合时拖垮整体精度。带 30s TTL 缓存，避免热路径重复查询。
+
+# _engine_weight 的结果缓存：{(source, lang): (weight, expires_at)}。
+# 见 _engine_weight 文档串——rrf_merge 逐条调用而取值空间极小，缓存后 300 条
+# 结果由 0.54ms 降到常数级；TTL 与上面的可靠性窗口对齐，不额外冻结熔断状态。
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+# 精排池容量：放宽截断让 rerank 看到 max_results 的 3 倍（下限 15 条），
+# 最终输出再截断到 max_results。去重提前停与放宽截断共用这一个计算方式——
+# 此前它是散在截断点上的字面量，而「去重该停在哪」需要知道同一个数。
+
+
+
+
+
+
+
+
+# ── 多语言结果语言偏好软排序（P2-覆盖，2026-08 新增）────────────────────────
+# ja/ko 明确主语言查询：把含目标语言字符（假名/谚文）的结果前移，纯相反语言
+# 结果后移。**软排序不删除**（避免误删混合/技术结果），其余语言零开销返回。
+
+
+# ── Bocha Reranker ──────────────────────────────────────────────────────────────
+
+# 精排端点在熔断器里的键。用 `rerank:` 前缀与可路由引擎区分——它不是一个能
+# 出现在 combo 里的引擎，但**复用同一套熔断语义**（失败计数 → 冷却 → 半开探测
+# → 自动禁用后周期复探），这样就不必另造一套「端点退避」机制。
+
+
+
+
+
+
+
+
+
+# ── P0-003：本地五维 Rerank 保底 ──────────────────────────────────────────────
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+# ── 融合后段（execute_search 的可独立测试单元）────────────────────────────────
+
+
+
+
+
+
+
+# ── 执行层 ─────────────────────────────────────────────────────────────────────
+
+# fast 单发总墙钟预算（秒）。引擎级超时收紧（≥8s 源 cap 6s、half_open 2s）之外
+# 的整条路径保底：实测引擎 P95 跨度 1.5-8.5s，6s 预算覆盖绝大多数快引擎，
+# 只砍 github 类拖尾——「等待剩余时间」与「是否再起新引擎」都受它约束。
+_FAST_TOTAL_BUDGET_S = 6.0
+
+# auto/budget 的总墙钟预算（秒）。auto 是默认模式，此前**没有**预算
+# （deadline=inf），于是 race 窗口退化成 `_eff_timeout + 2`：timeout 默认 10s
+# → 单查询最坏 grace + 12s(race) = 14s。2026-09-15 实测 "claude 5 release
+# date" 冷查询 13.4s，期间无任何信号说明在等什么，用户体感就是「卡住了」。
+#
+# 取 10.0 = 用户明确的体感阈值，也 ≥ execution.default_timeout(8s)，不截断
+# 正常查询（实测中位 4s、p75 8s，绝大多数早已 early-stop 完成），只砍极端尾部。
+_AUTO_TOTAL_BUDGET_S = 10.0
+
+# deep 的总墙钟预算（秒）。此前 deep 不设预算——「研究场景宁可等待」；但
+# 2026-09-30 实测这句被一个慢源架空：mode=deep → budget_s=None → deadline=inf，
+# firecrawl（声明 timeout=20）单源拖尾 6.5s，dispatch 7338ms 全在等它，期间
+# 其他 8 个引擎早已交付。15.0 = 覆盖 deep 正常 p50（实测 ~7s）与 p90，只截
+# 20s 级的病态拖尾；已完成引擎的证据一条不丢（budget 只管「还等不等」）。
+# execution.deep_budget_s 可覆盖（0 = 恢复无界，回滚无侵入）。
+_DEEP_TOTAL_BUDGET_S = 15.0
+
+# 首选引擎的独占宽限窗（秒）：在这个时间内完成且合格就免掉 hedge、只付 1 次
+# 调用；窗口内没完成就补发下一个引擎并行赛跑。
+#
+# **两条路径共用同一个值**，因为它们是同一个语义：「我们最信任的那个引擎，
+# 在放弃它之前先给它多久」。串行垂直域（`parallel=False`）此前根本没有这道窗，
+# 一个死源要耗满自己的超时上限（5-8s）才轮到备选；对冲改造后它与 wave-1 用
+# 同一个数。两个名字、两个值会让「到底等多久」没有单一答案。
+#
+# 2026-10-11 起实际窗 = min(本值, 主引擎历史 P75)（只缩不放：快引擎收窄、
+# 慢引擎不动），见 engine_dispatch._adaptive_grace；`ARGO_ADAPTIVE_GRACE=0`
+# 关闭收窄，回到纯本值（消融对照 / A/B 基线臂）。
+#
+# 取值 0.8s（2026-09-17 实测，本机真实网络，8 条查询 ×5 次、逐条交替执行）：
+#
+#   - 主引擎在 0.8s 内交付时（网络正常时的大多数），两者完全一致——都是 1 次
+#     调用、墙钟无差别（合计 7388ms → 6085ms 那一轮里 7/8 条查询就是这种情况）。
+#   - 主引擎慢于 2.0s 时，旧值要多等 1.2s 才肯补发备选，这段直接进墙钟：
+#     实测慢网那一轮 8 条查询合计 20988ms → 13426ms（**−36%**），其中
+#     「2026年 AI Agent 进展」2856→1228ms、「量子计算 突破 2026」2846→1310ms。
+#   - 代价是中间地带（主引擎落在 0.8~2.0s）偶尔多发一次调用：实测 8 条查询
+#     合计调用 8→9 条（+12%），而备选源都是免密钥源。
+#
+# 关键判断：旧值 2.0s 恰好在最差的位置——主引擎（anysearch）实测均值 1.9s，
+# 落在窗前窗后都说不准，于是「省下一次调用」这个目的基本没兑现，却把上界
+# 1.2s 的等待稳定地写进了每一次慢查询。**用一个免费备用源的调用换掉 1.2s
+# 用户可见延迟，是一笔划算的交换。**
+_PRIMARY_GRACE_S = 0.8
+
+# 质量守卫拒绝早停后的有界宽限窗（秒）。对冲的备份引擎先回来、但结果被判不充分
+# （计数不足，或与查询零词面交集）时，主引擎还能再跑这么久，之后不再等它。
+# 实测「上海 地铁 线路图」：备份给出 10 条纽约共享单车结果（零词面交集，守卫
+# 正确地拒绝早停），主引擎 Nominatim 对这类查询本就答不了、1-3s 后返回 0 条，
+# 却把墙钟拖到 4.4s。只影响「还等多久」，不改变任何结果的取舍。
+# 0 关闭（回到「等到 race 窗口耗尽」的旧行为，供消融对照）。
+_STRAGGLER_GRACE_S = 1.5
+
+
+def _straggler_grace() -> float:
+    """宽限窗取值（ARGO_STRAGGLER_GRACE_S 覆盖，供消融对照）。"""
     try:
-        from adaptive import get_learner
-        learner = get_learner()
-        for eng, res in raw_results.items():
-            success = bool(res and any("error" not in r for r in res))
-            latency = elapsed / max(len(raw_results), 1)
-            cost = get_cost_factor(eng)
-            learner.record(eng, success=success, latency_ms=latency, cost=0.0 if cost >= 0.85 else 0.001)
-    except Exception:
+        raw = os.environ.get("ARGO_STRAGGLER_GRACE_S")
+        if raw is not None and raw.strip() != "":
+            return max(0.0, float(raw))
+    except (TypeError, ValueError):
+        pass
+    return _STRAGGLER_GRACE_S
+
+
+def _serial_stagger() -> float:
+    """串行路径的起步间隔：`ARGO_SERIAL_STAGGER_S` > `_PRIMARY_GRACE_S`。
+
+    值与 wave-1 的宽限窗同源（同一语义，见 `_PRIMARY_GRACE_S` 注释）：首个
+    引擎跑过这么久还没回来，就补发备选源并行跑，而不是等它耗满自己的超时上限。
+
+    单调语义：0 = 不节流（备选源与首引擎同时起跑，最激进）；值越大越接近严格
+    串行（取一个大于引擎超时上限的值即可完全退回改造前的行为）。
+
+    环境变量这一层是给消融对照用的（取大于超时上限的值 = 退回严格串行）；
+    与隔壁 `_STRAGGLER_GRACE_S` 同一种取法：常量默认 + 环境变量覆盖、**按值
+    传进 engine_dispatch**，不在调度模块里重新解析配置。三种取法（常量 /
+    config / env）混用会让「这个值到底是多少」没有单一答案，也容易让测试里
+    patch 的常量被 config 静默顶掉。
+    """
+    try:
+        raw = os.environ.get("ARGO_SERIAL_STAGGER_S")
+        if raw is not None and raw.strip() != "":
+            return max(0.0, float(raw))
+    except (TypeError, ValueError):
         pass
+    return _PRIMARY_GRACE_S
+
+
+def _deep_budget_s() -> float | None:
+    """deep 总墙钟预算：常量默认 + execution.deep_budget_s 覆盖。
+
+    0 / 负数 = 恢复无界（回滚无侵入的逃生门）；非法值回落常量。
+    与 fast/auto 同一种取法：常量默认、**按值传进 engine_dispatch**，
+    不在调度模块里重新解析配置（原因见 _serial_stagger 注释）。
+    """
+    try:
+        raw = float(get_execution_config().get("deep_budget_s", _DEEP_TOTAL_BUDGET_S))
+        return raw if raw > 0 else None
+    except (TypeError, ValueError):
+        return _DEEP_TOTAL_BUDGET_S
+
+
+# 单引擎墙钟硬预算（秒）：含该引擎的**全部**重试尝试，超预算即停、不再发起
+# 新尝试，由调度层切备选源。
+#
+# 为什么要这个上界（2026-09-10 实测）：重试会叠乘。anysearch 曾同时具备
+#   引擎级 retry_count=1（2 次）× HTTP 级 max_retries=1（2 次）× 8s
+#   = 最坏 32s（实测 31.3s）
+# 用户侧表现是「一个查询卡半分钟」，而这期间既没切备选源、也没有任何
+# 信号说明在等什么。逐处调小超时不是好解法——那会误杀慢网下正常的源；
+# 给**单引擎总墙钟**设上界才是根本的，且对未来新增的重试层同样生效。
+#
+# 取值 10s：用户明确的体感阈值（「10 秒以内也应该能够解决」），
+# 也 ≥ execution.default_timeout(8s)，保证单次正常尝试不被截断。
+_PER_ENGINE_BUDGET_S = 10.0
+
+
+# ── 阶段耗时（--explain-timing）─────────────────────────────────────────────
+# 实现在 stage_timing（纯数据结构），此处只做别名导入，保持既有调用点与
+# 测试的 `search.StageTiming` 名字不变。
+
+from stage_timing import (  # noqa: E402
+    StageTiming,
+    tick as _tick,
+    tock as _tock,
+)
+# 尾宽分层策略（纯函数，拆出理由见 straggler_policy 模块头）
+from straggler_policy import straggler_tail  # noqa: E402
+
+
+def execute_search(query: str, decision: dict[str, Any], max_results: int,
+                   timeout: int, depth: str, cache: SearchCache, skip_cache: bool,
+                   mode: str = "auto",
+                   since: str | None = None, until: str | None = None,
+                   sort: str = "relevance",
+                   on_progress: Optional[Callable[[Stage, dict[str, Any]], None]] = None,
+                   engine_domain: str | None = None,
+                   engine_sub_domain: str | None = None,
+                   timing: StageTiming | None = None) -> dict[str, Any]:
+    hooks = _SearchHooks(
+        engine_search=engine_search, available_engines=available_engines,
+        get_cost_factor=get_cost_factor,
+        get_engines=get_engines, get_execution_config=get_execution_config,
+        missing_env_for=_missing_env_for,
+        classify_outcome=_classify_engine_outcome,
+        note_quota_exhausted=_note_remote_quota_exhausted,
+        per_engine_budget_s=_PER_ENGINE_BUDGET_S,
+        fast_budget_s=_FAST_TOTAL_BUDGET_S,
+        auto_budget_s=_AUTO_TOTAL_BUDGET_S,
+        deep_budget_s=_deep_budget_s(),
+        primary_grace_s=_PRIMARY_GRACE_S,
+        straggler_grace_s=_straggler_grace(),
+        straggler_tail_fn=straggler_tail,
+        serial_stagger_s=_serial_stagger(),
+    )
+    prepared = prepare(query, decision, max_results, timeout, depth, cache,
+                       skip_cache, mode=mode, since=since, until=until,
+                       sort=sort, on_progress=on_progress, timing=timing,
+                       engine_domain=engine_domain,
+                       engine_sub_domain=engine_sub_domain,
+                       hooks=hooks)
+    if prepared.cached is not None:
+        return prepared.cached
+    run = dispatch(prepared.req, prepared.run, hooks)
+    run = postprocess(prepared.req, run, hooks)
+    return finalize(prepared.req, run, hooks)
+
+
+
+
 
-    if on_progress:
-        on_progress(Stage.DONE, {"count": len(merged), "elapsed_ms": elapsed})
 
-    tfidf_scores = decision.get("tfidf_scores", [])
-    if tfidf_scores and all(s.get("score", 0) == 0 for s in tfidf_scores):
-        tfidf_scores = []
 
-    return {
-        "query": query, "engine": engine_label, "engines": engines,
-        "engines_combo": engines_combo, "cached": False,
-        "domain": domain, "elapsed_ms": elapsed,
-        "tfidf_scores": tfidf_scores, "results": merged,
-        "count": len(merged), "engines_used": list(raw_results.keys()),
-        "errors": _collect_errors(raw_results), "mode": mode,
-    }
 
 
-def _collect_errors(raw_results: dict[str, list[dict[str, Any]]]) -> list[str]:
-    errors = []
-    for eng, res in raw_results.items():
-        for r in res:
-            if isinstance(r, dict) and "error" in r:
-                errors.append(f"{eng}: {r['error']}")
-    return errors
 
 
 # ── 统一入口 ──────────────────────────────────────────────────────────────────
 
+from local_seek import resolve_include_local as _resolve_include_local
+
+
 def super_search(query: str, engine: str = "auto", n: int = 5, explain: bool = False,
                  skip_cache: bool = False, timeout: int = 10,
                  depth: str = "fast", mode: str = "auto", local_first: bool = False,
-                 rewrite: bool = True, cache: Any = None) -> dict[str, Any]:
+                 rewrite: bool = True, cache: Any = None,
+                 on_progress: Optional[Callable[[Stage, dict[str, Any]], None]] = None,
+                 input_kind: str = "auto",
+                 plan_only: bool = False,
+                 force_search: bool = False,
+                 envelope: bool = True,
+                 context: str = "search",
+                 engines_boost: list[str] | None = None,
+                 since: str | None = None,
+                 until: str | None = None,
+                 sort: str = "relevance",
+                 include_local: bool | None = None,
+                 include_domains: list[str] | None = None,
+                 exclude_domains: list[str] | None = None,
+                 engine_domain: str | None = None,
+                 engine_sub_domain: str | None = None,
+                 timing: StageTiming | None = None) -> dict[str, Any]:
     """统一搜索便捷入口。
 
+    执行分层（不阻塞日常）：
+      - daily（默认 auto/fast）：直搜，不挂 plan，不要求用户确认
+      - professional（mode=deep 或 depth=deep）：直搜 + 附加 plan 元数据
+      - plan_only：仅离线计划（显式开关，不进热路径默认）
+      - known-url：工具分流 handoff（不是「请确认后再搜」）
+
     Args:
         query: 搜索查询词
         engine: 指定引擎（默认 auto）
@@ -325,184 +588,401 @@ def super_search(query: str, engine: str = "auto", n: int = 5, explain: bool = F
         mode: 预算模式
         local_first: 强制本地优先
         rewrite: 是否自动改写查询（默认 True）
+        on_progress: 可选进度回调 (stage, data)
+        input_kind: auto|keyword|url-seed|known-url
+        plan_only: 仅离线计划，不联网
+        force_search: 即使判定 known-url 也强制多引擎搜索
+        envelope: 附加 candidates/coverage/limitations
+        context: search | research
+        engines_boost: 垂直引擎前置列表（研究路径 boost，不锁死单引擎）
+        since/until: 发布时间时间窗（如 7d / 2026-08-01），下推到支持时间窗的引擎
+
+    注意：路由永远基于原始 query。改写词只用于引擎检索，避免
+    「Python → 追加 pip/库」之类改写污染 package_search 等域规则。
     """
-    cache = cache if cache is not None else SearchCache()
+    if cache is None:
+        from cache import SearchCache  # 局部 import；见模块头注释（不能用裸名）
+        cache = SearchCache()
+    original_query = query
+
+    # 查询操作符契约层（2026-10-17 query_operators）：指令从路由与检索两侧
+    # 剥掉（今天以前 site: 会把路由锁死进错误域且引擎拿到脏查询）。
+    try:
+        from query_operators import parse_query_operators
+        _op_clean, _operators = parse_query_operators(original_query)
+        if _op_clean and _op_clean != original_query:
+            original_query = _op_clean
+        decision_operators = _operators
+    except ImportError:
+        decision_operators = None
+
+    # 查询改写：仅影响检索串，不影响路由（在执行引擎前应用）
     rewrite_result = None
+    search_query = original_query
 
-    # 查询改写：追加领域关键词提升搜索质量
-    if rewrite:
-        try:
-            from query_rewriter import rewrite_query as do_rewrite
-            rewrite_result = do_rewrite(query)
-            if rewrite_result["rewritten"] and rewrite_result["confidence"] >= 0.7:
-                query = rewrite_result["rewritten"]
-        except Exception:
-            pass  # 改写失败不影响搜索
+    # ── 离线计划 / URL 分流（离线计划 / 输入分流）──
+    # 纪律：build_plan 无网络、不回调本函数 → 无 plan↔search 死循环
+    kind = "keyword"
+    tier = "daily"
+    plan_info: dict[str, Any] | None = None
+    try:
+        from plan import (
+            build_plan, classify_input_kind, execution_tier, should_attach_plan,
+        )
+        kind = classify_input_kind(query, input_kind)
+        tier = execution_tier(mode, depth, context)
+        if plan_only:
+            return build_plan(
+                query, mode=mode, depth=depth, max_results=n,
+                engine=engine if not local_first else "local_search",
+                input_kind=input_kind,
+                context=context,
+            )
+        if kind == "known-url" and not force_search:
+            plan_info = build_plan(
+                query, mode=mode, depth=depth, max_results=n,
+                engine=engine, input_kind="known-url", context=context,
+            )
+            # 不发起多引擎搜索；返回 handoff 形态，避免把读链接当热搜
+            out = {
+                "query": query,
+                "engine": None,
+                "engines": [],
+                "engines_combo": [],
+                "cached": False,
+                "domain": None,
+                "elapsed_ms": 0,
+                "results": [],
+                "count": 0,
+                "errors": [],
+                "engine_outcomes": [],
+                "wasted_engine_ms": 0,
+                "early_stopped": False,
+                "mode": mode,
+                "depth": depth,
+                "status": "handoff_required",
+                "input_kind": "known-url",
+                "execution_tier": tier,
+                "requires_confirmation": False,
+                "plan": plan_info,
+                "handoff": plan_info.get("handoff"),
+                "limitations": plan_info.get("limitations") or [],
+                "schema_version": "1.0",
+                "candidates": [],
+                "coverage": [],
+            }
+            return out
+    except ImportError:
+        kind = "keyword"
+        tier = "daily"
+    except Exception as e:
+        import logging
+        logging.getLogger("unified_search").debug(f"plan 分流跳过: {type(e).__name__}")
+
+    # 无词元查询短路：整条查询连一个字母/数字/汉字都没有（纯符号、纯标点、
+    # 纯 emoji），任何文本引擎都不可能召回——实测放行只会白烧引擎调用与
+    # 3 秒级时延（"!!!" 实测 dispatch 3.1 s 且 anysearch 超时、缓存里多一条
+    # 垃圾空结果）。只拦 auto 档：显式指定引擎或 local_first 是用户在点名
+    # 「就要拿这个串去搜」，计划分流的 plan_only 也已在上方返回，均不受影响。
+    if (engine == "auto" and not local_first
+            and not re.search(r"\w", original_query)):
+        out = {
+            "query": original_query,
+            "engine": "none", "engines": [], "engines_used": [],
+            "domain": "general", "count": 0, "mode": mode, "depth": depth,
+            "status": "completed", "fetch_required": False,
+            "evidence_loop": {"high_consequence_domain": None,
+                              "suggested": [], "verified_count": 0,
+                              "pending_count": 0},
+            "errors": [], "login_hint": {"needs_login": False, "reason": ""},
+            "funnel": {"routed": 0, "called": 0, "returned": 0,
+                       "deduped": 0, "filtered": 0, "kept": 0},
+            "limitations": ["query has no word tokens (letters/digits/CJK); "
+                            "no engine can recall it, network dispatch skipped"],
+            "results": [],
+            "schema_version": "1.0",
+            "input_kind": kind, "execution_tier": tier,
+        }
+        if timing is not None:
+            out["timing"] = timing.summary()
+        return out
 
+    # 查询改写：追加领域关键词提升搜索质量
+    # local_first 路径跳过改写：改写词面向 web 引擎召回设计，套到本地
+    # 聚合（search_v3 智能路由）上会稀释查询、收窄引擎选择、扩大失败面
+    #（实测改写词把「Python 异步编程」扩为 5 词长句后本地聚合返回空）。
+    # original_query 此时可能是操作符清洗后的 clean_query（见上方
+    # query_operators 解析）——不重新赋值回原值，否则 site: 等指令会重新
+    # 污染路由（2026-10-17 实测踩中：此处覆盖后 `DeepSeek site:github.com`
+    # 又锁回 code_search）。
+    rewrite_result = None
+    original_query = search_query if decision_operators else query
+    if rewrite and not local_first:
+        rewritten, rewrite_result = _apply_query_rewrite(original_query)
+        if rewrite_result and rewrite_result.get("rewritten"):
+            search_query = rewritten
+
+    # 时间窗：查询里的 after:/before: 兜底（CLI --since/--until 显式值优先）
+    if decision_operators:
+        since = since or (str(decision_operators["after"])
+                          if decision_operators.get("after") else since)
+        until = until or (str(decision_operators["before"])
+                          if decision_operators.get("before") else until)
+
+    # route 延迟导入：route.py 的 import 链（config → logging/shutil/dataclasses）
+    # 实测 31ms，而 --list-engines / --help / plan_only 路径对它零依赖。
+    # 搜索路径在首次调用时付一次（sys.modules 缓存后免费），非搜索路径省整条链。
+    from route import route_query_cached
+
+    _op_langs = (decision_operators or {}).get("langs") or None
     if local_first:
-        decision = route_query(query, engine_override="local_search", mode=mode)
+        _tk_route = _tick(timing)
+        decision = route_query_cached(
+            original_query, engine_override="local_search", mode=mode,
+            depth=depth, context=context, engines_boost=engines_boost,
+            lang_override=_op_langs,
+        )
+        _tock(timing, "route", _tk_route)
     else:
-        decision = route_query(query, engine_override=engine, mode=mode)
+        _tk_route = _tick(timing)
+        decision = route_query_cached(
+            original_query, engine_override=engine, mode=mode,
+            depth=depth, context=context, engines_boost=engines_boost,
+            lang_override=_op_langs,
+        )
+        _tock(timing, "route", _tk_route)
+    if decision_operators:
+        decision["operators"] = decision_operators
+    if context == "research":
+        # 研究子查询禁早停：第一个「有结果」的垂直目录（如 models_dev 的
+        # 模型规格页）不等于研究证据齐了，跑满 combo 再 RRF 融合。
+        # 复用 no_early_stop 通道，串行/并行两条执行路径均已消费该标志。
+        decision["no_early_stop"] = True
     if explain:
         combo = decision.get('engines_combo', decision.get('engines', []))
         print(
             f"[路由] {decision['reason']} → engine={decision['engine']} "
             f"combo={combo} domain={decision.get('domain')} "
-            f"tfidf={decision.get('tfidf_scores', [])} mode={mode}",
+            f"tfidf={decision.get('tfidf_scores', [])} mode={mode} kind={kind} tier={tier}",
             file=sys.stderr,
         )
-    result = execute_search(query=query, decision=decision, max_results=n,
-                          timeout=timeout, depth=depth, cache=cache,
-                          skip_cache=skip_cache, mode=mode)
-    if rewrite_result and rewrite_result["rewritten"]:
+        if decision_operators and decision_operators.get("dropped"):
+            _o = decision_operators
+            print(f"[操作符] 剥离 {_o['dropped']} 排除词 {_o['exclude_terms']} "
+                  f"语言 {_o['langs']} 时间窗 {_o['after']}~{_o['before']}",
+                  file=sys.stderr)
+        if search_query != original_query:
+            print(f"[改写] {original_query} → {search_query}", file=sys.stderr)
+    # L1 并行化：本地搜索与主搜索并行提交（仅显式开启时在宽根下提示）。
+    _local_seek_explicit = include_local is not None
+    include_local = _resolve_include_local(include_local, mode, query)
+    _local_seek_future = None
+    if include_local:
+        _local_seek_future = _get_local_seek_executor().submit(
+            _run_local_seek, query, n, warn=_local_seek_explicit)
+
+    result = execute_search(
+        query=search_query, decision=decision, max_results=n,
+        timeout=timeout, depth=depth, cache=cache,
+        skip_cache=skip_cache, mode=mode, on_progress=on_progress,
+        since=since, until=until, sort=sort, timing=timing,
+        engine_domain=engine_domain, engine_sub_domain=engine_sub_domain,
+    )
+
+    # include-local 等待预算（H1，2026-09-29）：deadline 跨两个等待点共享
+    #（此处的预等待 + 下方 shape_response 的合并等待），总预算不叠加。
+    # 主结果命中缓存时收窄到宽限窗（_local_seek_grace_s() 调用时取值：
+    # 模块级常量只在 import 时读 env，MCP 常驻进程里改 ARGO_LOCAL_SEEK_GRACE_S
+    # 不生效——与 _straggler_grace()/_serial_stagger() 同一原则）。
+    _local_wait_cached = isinstance(result, dict) and bool(result.get("cached"))
+    _local_deadline = time.monotonic() + (_local_seek_grace_s() if _local_wait_cached
+                                          else _LOCAL_SEEK_TIMEOUT_S)
+    # 主搜索完成后，本地搜索应已就绪；若未完成则等待剩余预算
+    if _local_seek_future is not None:
+        try:
+            _local_seek_future.result(timeout=max(_local_deadline - time.monotonic(), 0))
+        except Exception:
+            pass  # 本地搜索失败不影响主结果
+    # 对外仍报告用户原始 query
+    result["query"] = original_query
+    if since:
+        result["since"] = since
+    if until:
+        result["until"] = until
+    if sort and sort != "relevance":
+        result["sort"] = sort
+    if rewrite_result and rewrite_result.get("rewritten"):
         result["rewritten_query"] = {
             "original": rewrite_result["original"],
             "rewritten": rewrite_result["rewritten"],
             "confidence": rewrite_result["confidence"],
             "reason": rewrite_result["reason"],
         }
+    result["input_kind"] = kind
+    result["status"] = "completed"
+    result["execution_tier"] = tier
+    result["requires_confirmation"] = False  # 日常/专业热路径永不阻塞等确认
+    # query_original 仅当改写改变检索词时才携带原始词，供存档/MCP 回退。
+    # 此前条件 `original_query != query` 恒为 False（原查询词从未被重赋），
+    # 导致该字段永远未写出——任何依赖它的下游都拿不到「是否被改写」的信号。
+    if search_query != original_query:
+        result["query_original"] = original_query
+
+    # professional：附加离线 plan 元数据（不阻断、不二次搜索）
+    try:
+        from plan import build_plan, should_attach_plan
+        if should_attach_plan(mode, depth, context, plan_only=False):
+            result["plan"] = build_plan(
+                original_query, mode=mode, depth=depth, max_results=n,
+                engine=engine if not local_first else "local_search",
+                input_kind=kind if kind != "auto" else "auto",
+                context=context,
+            )
+    except (OSError, ValueError, TypeError, KeyError):
+        pass
+
+    # 结果局限声明：**质量信号，与归档开关无关**，两条路径共用同一计算方式。
+    # 此前只在 envelope 分支内计算，于是 --no-envelope（文档推荐给 agent 的
+    # 档位）整块拿不到它——agent 无从知晓拿到的是「相关发现而非正文」
+    # 「降级路由结果」「未预确认的 daily 档」（2026-09-15 输出契约审查）。
+    extra_lim: list[str] = []
+    if kind == "url-seed":
+        extra_lim.append(
+            "url-seed: seed URL was not fetched; results are related discovery only"
+        )
+    # 恢复链两种结局分开说（2026-10-10 方案甲）：「恢复成功换了引擎」与
+    # 「触发了但无可用策略」对消费者的含义完全不同。失败那一半再细分：
+    # 源被跳过/鉴权失败时不要写成「查询没有召回」（2026-10-22 修正），
+    # 具体判据与措辞在 search_attribution.zero_result_recovery_note。
+    _rec_info = result.get("recovery") or {}
+    from search_attribution import zero_result_recovery_note
+    _rec_note = zero_result_recovery_note(
+        _rec_info, result.get("engine_outcomes"))
+    if _rec_note is not None:
+        extra_lim.append(_rec_note)
+    elif result.get("recovery"):
+        extra_lim.append("recovery used; engine fallback may differ from primary route")
+    # 执行归因：把「为什么只有这么几条 / 为什么只跑了一个源」写进随答案一起
+    # 到达的局限声明。此前这类问题只能靠翻 engine_outcomes 与 early_stopped
+    # 反推，而局限声明本身就是给消费者看的「这批结果能用到什么程度」，
+    # 成因属于同一类信息（GLM 密集反馈：反馈要能追到具体原因）。
+    _fn = result.get("funnel")
+    if isinstance(_fn, dict):
+        _routed, _called = _fn.get("routed"), _fn.get("called")
+        if isinstance(_routed, int) and isinstance(_called, int) \
+                and _called < _routed:
+            # 有漏斗时由这里给带数字的版本；candidate_envelope.build_limitations
+            # 见到 funnel 就不再出泛化表述——同一件事只留一句。
+            extra_lim.append(
+                f"early_stopped: only {_called} of {_routed} routed engines "
+                "were queried; coverage may be narrower than the route implies"
+            )
+        if result.get("count") == 0:
+            _stage = funnel_collapse(_fn)
+            if _stage:
+                extra_lim.append(
+                    f"no results: pipeline emptied at '{_stage}' "
+                    f"[{describe_funnel(_fn)}]"
+                )
+    # 输出成形（七个阶段：档位局限 → envelope/局限 → 本地正文索引 → 证据门控
+    # → 域过滤 → 信源标准化 → 本地命中并入）住在 search_output.shape_response：
+    # 那是**响应契约**，与执行/调度无关。
+    # 显式点名的引擎里查无此名者：随结果一起报出来（判据见
+    # unknown_requested_engines）。局限声明走既有通道 extra_lim，错误行在
+    # 成形之后追加——errors 是执行层的账，这里只做「请求级事实」的补充，
+    # 不去改执行层的账（两份账混写会互相覆盖）。
+    # import 收进真会用到判定的分支：engine 为 auto（默认）时判据函数恒返
+    # []，而 import engines 会把整只引擎构建栈（连带 urllib/http/xml/email，
+    # 2026-10-01 实测 ~115ms）拖进每次搜索——含缓存命中。红绿锁：
+    # tests/test_hotpath_import_lint.py
+    _unknown_engines: list[str] = []
+    if not local_first and engine and engine != "auto":
+        from engines import unknown_requested_engines as _unknown_requested
+        _unknown_engines = _unknown_requested(engine)
+    if _unknown_engines:
+        extra_lim.append(
+            "unknown engine name(s) requested: "
+            + ", ".join(_unknown_engines)
+            + "; results may come only from the remaining engines")
+    # 包装 _run_local_seek：若 Future 已完成则直接返回结果，否则等待
+    # （共享上方的 _local_deadline：缓存命中路径的合并等待同样受宽限窗约束）
+    def _local_seek_wrapper(q, max_n, search_dir=None):
+        if _local_seek_future is not None:
+            try:
+                return _local_seek_future.result(
+                    timeout=max(_local_deadline - time.monotonic(), 0))
+            except Exception:
+                return []
+        return _run_local_seek(q, max_n, search_dir)
+
+    result = shape_response(_ShapeContext(
+        query=query, kind=kind, tier=tier, envelope=envelope, decision=decision,
+        extra_lim=extra_lim, cache=cache, include_domains=include_domains,
+        exclude_domains=exclude_domains, include_local=include_local, n=n,
+        run_local_seek=_local_seek_wrapper,
+    ), result)
+
+    # serp_guard 整页误杀外露（2026-10-10 方案甲）：_serp_guard_apply 返回 []
+    # 是「诚实空」，但对调用方等价于「没搜到」——误杀类缺陷（搜狗跳转壳
+    # 10-06、百家号 10-08）都在这里静默过。引擎执行完统一 drain 进 errors，
+    # 让误杀可见、可归因（ARGO_SERP_GUARD=0 可复核）；空账不产生任何输出。
+    try:
+        from serp_kill_log import drain_serp_guard_kills
+        for _kill in drain_serp_guard_kills():
+            result.setdefault("errors", []).append(
+                f"serp_guard: {_kill['engine']} 头部结果均未覆盖 20% 查询词，"
+                f"整页按答非所问丢弃（{_kill['results']} 条）——"
+                "如需复核可设 ARGO_SERP_GUARD=0 重跑")
+    except ImportError:
+        pass
+
+    for _name in _unknown_engines:
+        result.setdefault("errors", []).append(
+            f"{_name}: registry 查无此引擎（拼写错误，或该源未随本版发布）")
+
     return result
 
 
-# ── 输出格式化 ─────────────────────────────────────────────────────────────────
+# ── 信源标准化 ─────────────────────────────────────────────────────────────────
 
-def format_text_output(results: dict[str, Any]) -> str:
-    lines = []
-    count = results.get("count", 0)
-    elapsed = results.get("elapsed_ms", 0)
-    engine = results.get("engine", "?")
-    cached = results.get("cached", False)
-    cache_level = results.get("cache_level", "")
-    domain = results.get("domain", "")
-    mode = results.get("mode", "auto")
-
-    header = f"=== {count} results ({elapsed}ms via {engine})"
-    if cached:
-        header += f" [CACHE {cache_level}]"
-    elif domain:
-        header += f" [domain:{domain}]"
-    if mode != "auto":
-        header += f" [mode:{mode}]"
-    lines.append(header)
-
-    for err in results.get("errors", [])[:3]:
-        lines.append(f"  [ERROR] {err}")
-
-    for r in results.get("results", []):
-        score = r.get("score", 0)
-        title = r.get("title", "?")[:80]
-        url = r.get("url", "")
-        prefix = f"[{score:.2f}]" if score else "[?]"
-        lines.append(f"  {prefix} {title}")
-        if url:
-            lines.append(f"    {url}")
-        snippet = r.get("snippet", "")
-        if snippet:
-            lines.append(f"    {snippet[:120]}")
-
-    return "\n".join(lines)
-
-
-# ── CLI 主入口 ─────────────────────────────────────────────────────────────────
-
-def main():
-    parser = argparse.ArgumentParser(
-        description="Unified Search v2 — 统一搜索 CLI",
-        formatter_class=argparse.RawDescriptionHelpFormatter,
-        epilog="""
-示例：
-  python3 search.py "python async"
-  python3 search.py "英伟达财报" --explain --json
-  python3 search.py "基金推荐" --mode fast
-  python3 search.py "AAPL" --engine anysearch --domain finance --sub_domain finance.us_stock
-        """,
-    )
-    parser.add_argument("query", nargs="?")
-    parser.add_argument("--engine", "-e", default="auto")
-    parser.add_argument("--max-results", "-n", type=int, default=5)
-    parser.add_argument("--depth", "-d", default="fast",
-                        choices=["fast", "balanced", "deep"])
-    parser.add_argument("--no-cache", action="store_true")
-    parser.add_argument("--explain", action="store_true")
-    parser.add_argument("--json", action="store_true", dest="json_output")
-    parser.add_argument("--timeout", "-t", type=int, default=10)
-    parser.add_argument("--list-engines", action="store_true")
-    parser.add_argument("--mode", default="auto",
-                        choices=["fast", "auto", "deep", "budget"],
-                        help="预算模式: fast=免费优先, auto=成本感知, deep=质量优先, budget=配额控制")
-    parser.add_argument("--local-first", action="store_true",
-                        help="强制优先使用 local_search 零成本聚合引擎")
-    parser.add_argument("--domain", default="", help="AnySearch 垂直域")
-    parser.add_argument("--sub_domain", default="", help="AnySearch 子域")
-    parser.add_argument("--progress", action="store_true")
-
-    args = parser.parse_args()
-
-    if args.list_engines:
-        print(json.dumps(available_engines(), ensure_ascii=False, indent=2))
-        return
-
-    if not args.query:
-        parser.error("必须提供搜索关键词")
-
-    cache = SearchCache()
-    if args.local_first:
-        decision = route_query(args.query, engine_override="local_search", mode=args.mode)
-    else:
-        decision = route_query(args.query, engine_override=args.engine, mode=args.mode)
+# --fields agent：每条 result 保留的答案字段（P2-2）。
+# 媒体专属字段按需登记——非该媒体的结果此键为 None，_strip_for_agent 会自动
+# 丢弃，其他查询不付代价：image_* 来自图源，episode_count/duration_minutes
+# 来自 itunes 的播客结果。
 
-    # 查询改写
-    rewrite_result = None
-    try:
-        from query_rewriter import rewrite_query as do_rewrite
-        rewrite_result = do_rewrite(args.query)
-        if rewrite_result["rewritten"] and rewrite_result["confidence"] >= 0.7:
-            search_query = rewrite_result["rewritten"]
-        else:
-            search_query = args.query
-    except Exception:
-        search_query = args.query
 
-    if args.explain:
-        combo = decision.get('engines_combo', decision.get('engines', []))
-        print(
-            f"[路由] {decision['reason']} → engine={decision['engine']} "
-            f"combo={combo} domain={decision.get('domain')} "
-            f"tfidf={decision.get('tfidf_scores', [])} mode={args.mode}",
-            file=sys.stderr,
-        )
-        if rewrite_result and rewrite_result["rewritten"]:
-            print(
-                f"[改写] {rewrite_result['original']} → {rewrite_result['rewritten']} "
-                f"({rewrite_result['confidence']:.0%})",
-                file=sys.stderr,
-            )
 
-    on_progress = None
-    if args.progress:
-        def on_progress(stage: Stage, data: dict[str, Any]):
-            print(f"[progress] {stage.value} {data}", file=sys.stderr)
 
-    results = execute_search(
-        query=search_query, decision=decision, max_results=args.max_results,
-        timeout=args.timeout, depth=args.depth, cache=cache,
-        skip_cache=args.no_cache, mode=args.mode, on_progress=on_progress,
-    )
 
-    if rewrite_result and rewrite_result["rewritten"]:
-        results["rewritten_query"] = {
-            "original": rewrite_result["original"],
-            "rewritten": rewrite_result["rewritten"],
-            "confidence": rewrite_result["confidence"],
-            "reason": rewrite_result["reason"],
-        }
 
-    if args.json_output:
-        public = {k: v for k, v in results.items() if not k.startswith("_")}
-        print(json.dumps(public, ensure_ascii=False, indent=2))
-    else:
-        print(format_text_output(results))
+
+
+
+
+
+
+
+
+
+
+# ── 输出格式化 ─────────────────────────────────────────────────────────────────
 
 
 if __name__ == "__main__":
+    # 把本模块（此刻身份是 __main__）的 import 时点交给 search_cli。
+    #
+    # 为什么需要这一行：入口是 bin/argo → runpy.run_module("search",
+    # run_name="__main__")，本模块体以 __main__ 身份跑完整条 import 链，
+    # 置的 _MODULE_T0 / _IMPORTS_DONE 是真值（约 30 ms）。紧接着下面这行
+    # `from search_cli import main` 会让 search_cli 执行 `from search import
+    # _MODULE_T0` —— 那是**第二次**导入 search（真模块），此刻依赖全在
+    # sys.modules 里，差值 ≈ 0。于是 --explain-timing 的 import_ms 恒为 0.0，
+    # 而它这一栏恰恰是给「优化固定开销」用的，报 0 等于把人指向错的数字。
+    #
+    # runpy 不会把 __main__ 留在 sys.modules['__main__']（它会恢复原模块），
+    # 所以靠 __main__ 取不到；写进 search_cli 的模块属性是唯一稳定的交接点。
+    from search_cli import main  # 反向导入放这里：CLI 依赖本模块，模块级会成环
+    import search_cli as _cli_mod
+    _cli_mod._TRUE_IMPORT_T0 = _MODULE_T0
+    _cli_mod._TRUE_IMPORTS_DONE = _IMPORTS_DONE
     main()