argo-search 2.9.7 → 2.9.9

package/scripts/search_output.py

@@ -8,10 +8,23 @@
 
 from __future__ import annotations
 
-from dataclasses import dataclass
-
 from search_rank import filter_results_by_domains
+from search_types import slot_record as dataclass
 from typing import Any
+from output_transparency import (  # noqa: F401
+    _AGGREGATOR_HOSTS,
+    _FAILURE_META,
+    _FAILURE_NON_ERROR,
+    _NON_ERROR_OUTCOME,
+    _SEVERITY,
+    _UNCERTAINTY_HIGH,
+    _UNCERTAINTY_LOW,
+    _UNCERTAINTY_MEDIUM,
+    _hostname,
+    build_failures,
+    build_uncertainty,
+    decorate_compact_payload,
+)
 
 
 # 本模块的 6 处日志都写在 **except 处理器**里，且分散在 shape_response 的
@@ -72,6 +85,39 @@ _AGENT_RESULT_FIELDS = (
 )
 
 
+def _slim_verify(v: Any) -> dict[str, Any] | None:
+    """verify 块的 agent 精简版：保留「核验后改了什么」，丢掉逐条细节。
+
+    why：`--fields agent` 此前把整个 verify 块剥掉，而这是**唯一**能说明
+    「花几秒核验换来了什么」的字段。保留 revision_summary 与每条 delta，
+    体积约 0.2–0.8 KB；pre/post 绝对分与 title 已在 results[] 可查，不重复。
+    """
+    if not isinstance(v, dict):
+        return None
+    out: dict[str, Any] = {}
+    for key in ("revision_summary", "pending", "skipped_cached", "semantic"):
+        if v.get(key) is not None:
+            out[key] = v[key]
+    rows = []
+    for r in v.get("verified") or []:
+        if not isinstance(r, dict):
+            continue
+        rows.append({k: r[k] for k in
+                     ("url", "delta", "post_absorption", "fetch_method")
+                     if r.get(k) is not None})
+    if rows:
+        out["verified"] = rows
+    return out or None
+
+
+def _slim_reorder(r: Any) -> dict[str, Any] | None:
+    """证据回写排序的 agent 精简版：只留结论（是否重排、动了几处）。"""
+    if not isinstance(r, dict):
+        return None
+    out = {k: r[k] for k in ("reordered", "moved") if r.get(k) is not None}
+    return out or None
+
+
 def _strip_for_agent(payload: dict[str, Any]) -> dict[str, Any]:
     """--fields agent：输出只留答案内容（P2-2，2026-09-13）。
 
@@ -93,9 +139,33 @@ def _strip_for_agent(payload: dict[str, Any]) -> dict[str, Any]:
         # 阶段耗时：默认就带（--no-timing 才没有）。剥掉会让使用者看不到
         # 「这次慢在哪」，也拿不到自己动手优化所需的依据。
         "timing",
+        # 综合可信度：一个 level 就能决定「直接引用」还是「先核验」。
+        # 剥掉它等于让 agent 自己交叉比对来源数/同站/聚合站/引擎失败——
+        # 而那正是它最容易漏掉的一步。
+        "meta",
+        # 结构化失败清单：类别 + 是否可重试 + 建议动作（≤6 条短字段）。
+        # 只有 errors 的整行文本时，agent 知道「坏了」但不知道「该重试、
+        # 换源还是去配 key」；这两件事的处置完全不同。
+        "failures",
+        # 信任级别：网页文本一律是不可信外部数据，随答案一起到达，
+        # 避免调用方把摘要里的指令当任务执行（输出层声明，非提示词）。
+        "content_trust",
+        # 核验产出：verify/evidence_reorder 是**花了墙钟换来的**，且是
+        # 「该不该引用这批结果」的直接依据。此前被整块剥掉，调用方付了
+        # 几秒核验却只看到 verified_count 一个数（2026-10-22 实测）。
+        # 值由下方 _slim_verify/_slim_reorder 压缩，不整块照搬。
+        "verify", "evidence_reorder",
     )
     out: dict[str, Any] = {k: payload[k] for k in keep_top
                            if payload.get(k) is not None}
+    for _key, _slim in (("verify", _slim_verify),
+                        ("evidence_reorder", _slim_reorder)):
+        if payload.get(_key) is not None:
+            _value = _slim(payload[_key])
+            if _value is not None:
+                out[_key] = _value
+            else:
+                out.pop(_key, None)
     slim_results = []
     for r in payload.get("results") or []:
         if not isinstance(r, dict):
@@ -219,7 +289,8 @@ def format_timing(t: dict[str, Any]) -> str:
             f"  引擎并发        墙钟 {d.get('wall_ms')} ms / 引擎合计 "
             f"{d.get('engine_sum_ms')} ms → 并发效率 "
             f"{d.get('parallel_efficiency')}（跑了 {d.get('engines_run')} 个，"
-            f"早停={d.get('early_stopped')}，浪费 {d.get('wasted_ms')} ms）")
+            f"早停={d.get('early_stopped')}，尾等待 {d.get('tail_wait_ms')} ms，"
+            f"弃置 {d.get('abandoned_engine_ms')} ms）")
     if "overhead_ms" in t:
         lines.append(
             f"  固定开销        {t['overhead_ms']} ms"
@@ -331,18 +402,6 @@ def format_text_output(results: dict[str, Any]) -> str:
     return "\n".join(lines)
 
 
-# 不算失败的 outcome 状态：这些情况「引擎跑了、没问题」，不该出现在 errors[]
-# cancelled = 早停收工时被主动弃置（结果已够，引擎没失败也没超窗）
-_NON_ERROR_OUTCOME = frozenset({
-    "ok", "ok-cached", "partial", "no-results", "no-results-cached",
-    "cancelled",
-    # 配额耗尽的跳过是**持续状态**，不是本次查询的失败：标记默认持续到周期
-    # 边界（一天），若每个查询都把它塞进 errors，调用方会看到一条持续一天的
-    # 「错误」并误判本次检索降级。状态本身在 --list-engines 可见。
-    "skipped-quota-exhausted",
-})
-
-
 def _collect_errors(raw_results: dict[str, list[dict[str, Any]]],
                     engine_outcomes: list[dict[str, Any]] | None = None
                     ) -> list[str]:
@@ -379,6 +438,7 @@ def _collect_errors(raw_results: dict[str, list[dict[str, Any]]],
         _add(f"{o.get('engine')}: {detail}")
     return errors
 
+
 @dataclass(frozen=True)
 class _ShapeContext:
     """输出成形的全部选项（请求侧只读 + 一个本地检索钩子）。"""
@@ -603,4 +663,28 @@ def shape_response(ctx: _ShapeContext, result: dict[str, Any]) -> dict[str, Any]
             # 待核验 0 条」这类自相矛盾的口径。
             _el["suggested"] = _sug
             _el["pending_count"] = len(_sug)
+    # 综合可信度：读的 results 必须与最终输出同源，所以放在收口（与 count
+    # 重算同处）——域过滤与本地命中并入都发生在这之前。只读不写结果，
+    # 失败时静默跳过（增强失败不得让一次搜索失败）。
+    try:
+        result["meta"] = {"uncertainty": build_uncertainty(result)}
+    except Exception as e:
+        _log(f"可信度评估跳过: {type(e).__name__}")
+    # 结构化失败清单：与 meta 同一收口，读的 outcome 与漏斗/可信度同源。
+    # 失败时静默跳过（增强失败不得让一次搜索失败）。
+    try:
+        failures = build_failures(result)
+        if failures:
+            result["failures"] = failures
+    except Exception as e:
+        _log(f"失败清单跳过: {type(e).__name__}")
+    # 信任级别与边界清洗：所有入口（full/agent/MCP）共用同一个收口，
+    # 避免 CLI/agent 档带 content_trust 却未剥离网页自带的 </untrusted-web-content>。
+    try:
+        from content_boundary import (CONTENT_TRUST_UNTRUSTED,
+                                      sanitize_results_boundary)
+        sanitize_results_boundary(result.get("results"))
+        result["content_trust"] = CONTENT_TRUST_UNTRUSTED
+    except Exception:
+        pass
     return result

package/scripts/search_pipeline.py

@@ -30,7 +30,7 @@ http_client / engines_base / engine_dispatch。
 
 from __future__ import annotations
 
-from dataclasses import dataclass, field, replace
+from search_types import slot_record as dataclass, slot_field as field, slot_replace as replace
 from typing import Any
 
 # 模块级曾有一行 `import logging`，而本模块 7 处 `logging.getLogger(...)`
@@ -56,8 +56,9 @@ from variant_recall import augment_with_variants
 from phrase_filter import apply_phrase_filter, extract_phrases
 from except_sets import OPT_IMPORT, SHAPE_BENIGN
 from postprocess_signals import apply_tfidf_polish, detect_number_conflict
-from search_attribution import usage_log_attribution
+from search_attribution import usage_log_attribution, is_synthetic_run
 from search_output import _collect_errors, _slow_query_ttl, build_funnel
+from serp_kill_log import clean_engine_lists
 from search_rank import (
     _LANG_SCRIPT,
     _RERANK_DEGRADED_STATUSES,
@@ -153,7 +154,11 @@ class _SearchRun:
     engine_latency: dict[str, float] = field(default_factory=dict)
     wasted_ms: int = 0
     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
@@ -236,16 +241,8 @@ def postprocess(req: _SearchRequest, run: _SearchRun, hooks: Any) -> _SearchRun:
     merged = run.merged
 
     # 融合输入派生（原先在 execute_search 里，属于加工的第一步）
-    valid_lists = [
-        res for res in raw_results.values()
-        if res and any(isinstance(r, dict) and "error" not in r for r in res)
-    ]
-    # 去掉 error-only 列表中的 error 条目
-    clean_lists = []
-    for res in valid_lists:
-        clean = [r for r in res if isinstance(r, dict) and "error" not in r]
-        if clean:
-            clean_lists.append(clean)
+    # 去 error 与 SERP 守卫同源：缓存命中的结果也要过同一道门（issue #18）。
+    clean_lists = clean_engine_lists(raw_results, query)
 
     # 查询主语言：噪声门与语言能力加权共用同一个判定（唯一来源，
     # 避免两处各自算导致行为漂移）。
@@ -387,8 +384,8 @@ def postprocess(req: _SearchRequest, run: _SearchRun, hooks: Any) -> _SearchRun:
     _funnel_deduped = len(merged)
     if merged:
         try:
-            from serp_guard import is_serp_or_jump_url as _is_serp  # 轻依赖，锁见 test_hotpath_import_lint.py
-            merged = [r for r in merged if not _is_serp(r.get("url", ""))]
+            from serp_guard import is_unusable_url as _is_unusable  # SERP + 内容农场，标定见 test_content_farm_guard.py
+            merged = [r for r in merged if not _is_unusable(r.get("url", ""), r.get("title", ""), r.get("snippet", ""))]
         except ImportError:
             pass  # serp_guard 不可用时跳过（本地五维 rerank 已对 SERP 降权）
 
@@ -515,176 +512,33 @@ def postprocess(req: _SearchRequest, run: _SearchRun, hooks: Any) -> _SearchRun:
     except OPT_IMPORT + SHAPE_BENIGN:  # 守卫不可用不设卡（fail-open）
         _echo_triggered = False
     if not merged or _echo_triggered:
-        # ── 恢复链 L0：early-stop 误判时补跑被跳过的同域引擎 ──
-        # （同域优先于 L3 换跨域引擎；实现在 recovery_l0）。死线 = 用户
-        # 声明的整体超时扣掉 dispatch 已耗墙钟——补跑不得把总时长推出
-        # 用户预算（语义见 recovery_l0 模块 docstring 的死线约束）。
-        try:
-            import time as _time
-            from recovery_l0 import maybe_retry_skipped
-            try:
-                _l0_deadline = _time.monotonic() + max(
-                    0.0, float(req.timeout or 0)
-                    - float(run.budget_used_ms or 0) / 1000.0)
-            except (TypeError, ValueError):
-                _l0_deadline = None
-            _l0_merged, _l0_info = maybe_retry_skipped(
-                run.early_stopped, engines_combo, raw_results,
-                available_engines, query, _run_one, _ingest,
-                max_results, _emit_usage, deadline=_l0_deadline)
-        except SHAPE_BENIGN:
-            _l0_merged, _l0_info = [], None
-        if _l0_merged and _l0_info:
-            recovery_info = _l0_info
-            merged = _l0_merged
-    if not merged or _echo_triggered:
-        try:
-            from recovery import run_recovery
-            tried = list(raw_results.keys()) or list(engines)
-            fallback_engines = decision.get("engines_fallback") or []
-            # 域路由零结果：恢复链放行 L3 换引擎。复杂度门此前把简单查询
-            # 压到 L2——L3 被禁 + 全域零结果 = 域命中查询无解（实测
-            # macro_data「中国GDP」零结果、恢复链空转）。engines_fallback
-            # 里是路由的定向保底声明（域未试成员优先），代价可控。
-            rec_level = _max_rec_level
-            if _echo_triggered:
-                # 退化是「引擎选错了」而非「查询写得不好」：L1 放宽 / L2 换词
-                # 都救不了「上游把整句当单词查」，必须换引擎（L3）。
-                rec_level = "L3"
-            elif fallback_engines and decision.get("domain") not in (
-                    None, "", "general", "general_search") \
-                    and (rec_level is None or rec_level < "L3"):
-                rec_level = "L3"
-            try:
-                enabled_set = set(available_engines())
-            except Exception:
-                enabled_set = None
-
-            def _recovery_executor(rq: str, rengines: list[str]) -> list[dict[str, Any]]:
-                """恢复执行器：对冲竞速跑候选引擎，取首个非空。跳过缓存避免污染。
-
-                并行形态（2026-09-29）：原为严格串行——域查询零结果时 recovery
-                段占 process_ms 的 79–86%（实测中位 906ms；「黄金价格」2019ms、
-                「比特币行情」1989ms），是体感「有时特别慢」的直接原因。改为
-                「起步间隔 = grace 的有界并发」（bounded_run.run_bounded 的
-                stagger 语义，与 dispatch 串行路径同一套对冲哲学，见
-                engine_dispatch._run_engines_bounded）：首引擎先跑，grace 内
-                交付仍只付一次调用，超时才补发下一匹；任一引擎交付非空即收工。
-                grace 复用 hooks.primary_grace_s（标定依据见 search._PRIMARY_GRACE_S），
-                不新增开关面。总等待上限 = grace×(n-1) + timeout + 1s ≤ 串行版
-                n×timeout，最坏情况也不慢于改造前。消融：把 primary_grace 调到
-                大于引擎超时上限即完全退回严格串行（与 ARGO_SERIAL_STAGGER_S
-                同思路）。daemon 线程不 join，卡住的 HTTP 读拖不垮止损。
-                """
-                def _fire(eng: str) -> list[dict[str, Any]]:
-                    _dk = {k: v for k in ("domain", "sub_domain") if (v := getattr(req, "engine_" + k, None))}
-                    # 记下真正发出的调用：恢复段走的不是 dispatch，若不单独记账，
-                    # 漏斗会算出「routed 2 → called 2 → returned 5」这种自相矛盾的
-                    # 账（实测「python 怎么读csv」），而这正是最需要被看见的路径。
-                    _recovery_engines.add(eng)
-                    try:
-                        # 恢复路径同样携带时间窗，避免恢复时丢弃用户约束；
-                        # --no-cache 也要透传：本函数的契约是「跳过缓存避免污染」，
-                        # 不透传会让恢复段既读到用户明确拒绝的旧缓存，又把自己的
-                        # 临时查询写进缓存（dispatch 那条路径是透传的，两处不一致）。
-                        res = engine_search(rq, eng, n=max_results,
-                                            timeout=timeout, depth=depth, mode=mode,
-                                            since=since_iso, until=until_iso,
-                                            skip_cache=skip_cache, **_dk)
-                    except Exception as e:
-                        import sys
-                        sys.stderr.write(
-                            f"[recovery] 恢复链异常（{type(e).__name__}）: {e}\n")
-                        res = []
-                    goods = [r for r in (res or [])
-                             if isinstance(r, dict) and "error" not in r]
-                    # 恢复段同样进配额账：它真的打了引擎（engine_search），
-                    # 而 quota_batch.add 的全仓唯一常规入口在 dispatch 的
-                    # _run_one 里——恢复链不走那条路，不在这里补一行，
-                    # 这批消耗就落在本地账本之外（见下方 flush 处注释）。
-                    # add 是 list.append（GIL 下原子），对冲线程并发调用安全。
-                    quota_batch.add(eng, bool(goods))
-                    if goods:
-                        for r in goods:
-                            r.setdefault("_engine", eng)
-                            r.setdefault("_recovered", True)
-                        # 回声不算「恢复成功」（判据与理由见
-                        # postprocess_signals.drop_echo_items）：不拦则 L1 放宽
-                        # 查询后收工，L3 换引擎永不执行。
-                        try:
-                            from postprocess_signals import drop_echo_items as _drop_echo
-                            goods = _drop_echo(goods, rq)
-                        except OPT_IMPORT + SHAPE_BENIGN:
-                            pass
-                    return goods
-
-                if len(rengines) <= 1:
-                    return _fire(rengines[0]) if rengines else []
-                grace = max(0.0, float(hooks.primary_grace_s or 0.0))
-                wait_s = grace * (len(rengines) - 1) \
-                    + max(1.0, float(timeout)) + 1.0
-
-                def _enough(finished: list[tuple[str, Any]]) -> bool:
-                    # 任一引擎交付非空即收工：不再起排队中的引擎（省调用），
-                    # 已在跑的归 unfinished（daemon，结果丢弃但配额已如实记）。
-                    return any(isinstance(v, list) and v for _i, v in finished)
-
-                finished, _unfinished = run_bounded(
-                    rengines, _fire, wait_s, max_workers=3,
-                    enough=_enough, stagger_s=grace)
-                # finished 按完成先后排列：首个非空即「最快非空」。与串行版
-                # 「首个非空」的差别只在来源引擎——恢复候选都过 run_recovery
-                # 的 query-signal 门，质量由它把关。
-                for _item, value in finished:
-                    if isinstance(value, list) and value:
-                        return value
-                return []
-
-            rec_results, rec_result = run_recovery(
-                query, tried, _recovery_executor,
-                engines_fallback=fallback_engines, enabled=enabled_set, mode=mode,
-                max_level=rec_level)
-            recovery_info = rec_result.to_dict()
-            # P2-6：恢复使用日志——query 截断脱敏，只记概览不记明细
-            if _emit_usage is not None:
-                try:
-                    _emit_usage("recovery", {
-                        "query": (query[:60] if query else query),
-                        "triggered": recovery_info.get("triggered"),
-                        "recovered": recovery_info.get("recovered"),
-                        "level_used": recovery_info.get("level_used"),
-                        "strategy_used": recovery_info.get("strategy_used"),
-                        "steps_tried": len(recovery_info.get("steps_tried") or []),
-                        "final_query": (recovery_info.get("final_query") or "")[:60],
-                        "note": recovery_info.get("note", ""),
-                    })
-                except SHAPE_BENIGN:  # 使用日志记录失败不影响恢复结果本身
-                    pass
-            if rec_results:
-                # 恢复结果复检壳口径：主链的壳过滤跑在恢复链之前，恢复产出
-                # 是唯一可能把壳带回最终输出的入口（唯一出口在
-                # serp_guard.drop_shell_urls，L0/L3/充分性三处共用）。
-                try:
-                    from recovery_l0 import finalize_l3_results
-                    merged = finalize_l3_results(rec_results, max_results)
-                except ImportError:
-                    merged = deduplicate_by_url(rec_results)[:max_results]
-                # 恢复引擎按引擎分组记回 raw_results：engines_used 此前不含
-                # 救援引擎（provenance 断链，实测恢复成功后 engines_used 仍
-                # 只列原 combo），自适应学习也看不到恢复成功信号。
-                _rec_by_eng: dict[str, list] = {}
-                for r in merged:
-                    eng = r.get("_engine") or r.get("source") or ""
-                    if eng:
-                        r.setdefault("consensus_engines", [eng])
-                        _rec_by_eng.setdefault(eng, []).append(r)
-                for _eng, _lst in _rec_by_eng.items():
-                    raw_results.setdefault(_eng, _lst)
-        except ImportError:
-            pass  # recovery 模块不可用
-        except Exception as e:
-            _log(
-                f"错误恢复跳过: {type(e).__name__}")
+        from recovery_runner import run_pipeline_recovery
+        _dk = {k: v for k in ("domain", "sub_domain") if (v := getattr(req, "engine_" + k, None))}
+        merged, _rec_info = run_pipeline_recovery(
+            query=query,
+            merged=merged,
+            raw_results=raw_results,
+            decision=decision,
+            engines=engines,
+            available_engines_fn=available_engines,
+            max_results=max_results,
+            max_rec_level=_max_rec_level,
+            echo_triggered=_echo_triggered,
+            primary_grace_s=float(hooks.primary_grace_s or 0.0),
+            timeout=timeout,
+            depth=depth,
+            mode=mode,
+            since_iso=since_iso,
+            until_iso=until_iso,
+            skip_cache=skip_cache,
+            quota_batch=quota_batch,
+            engine_search_fn=engine_search,
+            emit_usage_fn=_emit_usage,
+            recovery_engines_set=_recovery_engines,
+            engine_domain_extra=_dk,
+        )
+        if _rec_info:
+            recovery_info = _rec_info
 
     # 配额记账落盘：整批一次写入文件（同一次搜索的 N 个引擎合并为一次写）。
     # 位置是契约：必须在**最后一个 quota add 点**之后。D6 补搜走后，
@@ -886,6 +740,7 @@ def finalize(req: _SearchRequest, run: _SearchRun, hooks: Any) -> dict[str, Any]
     funnel = run.funnel
     result_payload = run.result_payload
     wasted_ms, useful_ms = run.wasted_ms, run.useful_ms
+    dispatch_tail = run.dispatch_tail
     early_stopped = run.early_stopped
     budget_used_ms, budget_total_ms = run.budget_used_ms, run.budget_total_ms
     elapsed = run.elapsed
@@ -920,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)}
@@ -945,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:
@@ -979,15 +849,15 @@ def finalize(req: _SearchRequest, run: _SearchRun, hooks: Any) -> dict[str, Any]
     # 字符（与 recovery 流同一脱敏纪律）；记录失败静默，绝不拖累主路径。
     # 取自 req 而非局部别名：_emit_usage 是 postprocess 的局部变量，
     # 本函数（finalize）不在其作用域内，直接引用会 NameError。
-    if req.emit_usage_log is not None:
+    if req.emit_usage_log is not None and not is_synthetic_run(raw_results):
         try:
-            # 引擎级耗时归因（2026-10-15 起）：写在 search_attribution，本处只接线。
+            # 归因走 search_attribution；合成引擎（基准/混沌）整条不入日志。
             req.emit_usage_log("query", {
                 "query": (query[:60] if query else query),
                 "count": len(merged),
                 "elapsed_ms": round(elapsed),
                 "engines_used": list(raw_results.keys())[:8],
-                **usage_log_attribution(engine_latency),
+                **usage_log_attribution(engine_latency, engine_outcomes=engine_outcomes),
                 "errors": len(_collect_errors(raw_results, engine_outcomes)),
                 "recovered": bool(recovery_info.get("recovered")) if recovery_info else False,
                 "early_stopped": bool(early_stopped),
@@ -1054,19 +924,16 @@ def finalize(req: _SearchRequest, run: _SearchRun, hooks: Any) -> dict[str, Any]
         out["timing"] = timing.summary()
         out["timing"]["elapsed_ms"] = elapsed
         out["timing"]["dispatch"] = {
-            # 用 dispatch 自己那口单调钟量出来的墙钟（budget_used_ms），不用外层
-            # 这笔 time.time() 差值：useful/wasted 都是单调钟算的，混用两种钟会
-            # 对不上账。注意 2026-10-10 记账改版起 useful + wasted 与 wall 没有
-            # 恒等式关系，别再按恒等式读仪表（口径真源：engine_dispatch 记账注释）。
+            # 墙钟/尾等待/弃置的口径真源见 dispatch_result.py；useful + wasted 与
+            # wall 没有恒等式（2026-10-10 起），不要再按恒等式读仪表。
             "wall_ms": budget_used_ms,
             "engines_run": len(engine_latency),
             "engine_sum_ms": eng_sum,
             "parallel_efficiency": (round(eng_sum / budget_used_ms, 2)
                                     if budget_used_ms else None),
-            # useful = 最后一个贡献结果引擎的完成时刻；wasted = 被编排主动弃置
-            # 的引擎已花墙钟之和。与 wall 无恒等式（真源：engine_dispatch 记账注释）。
             "useful_ms": useful_ms,
             "wasted_ms": wasted_ms,
+            **dispatch_tail,
             "early_stopped": early_stopped,
         }
         if budget_total_ms is not None:

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/search_types.py

@@ -1,20 +1,118 @@
 #!/usr/bin/env python3
-"""search_types.py — 统一类型系统（已废弃，勿接入）
+"""search_types.py — 统一类型系统（轻量记录 + 零依赖 dataclass 替代）。
 
-早期设计声明的统一 schema 层，从未被任何模块 import（grep 全仓库无引用）：
-  - 引擎输出直接透传 dict，运行时防御在 engines_base/safe_search 与
-    search.py 的 execute_search 里完成
-  - 保留本文件仅避免旧版外部脚本 import 断裂；新代码禁止使用
+`slot_record` / `slot_field` / `slot_replace` 是为热路径准备的
+`@dataclass` / `field` / `replace` 零依赖替代：`dataclasses` 的导入链是
+`dataclasses → inspect → tokenize → dis`（实测 ~8ms），而 `SearchResult`
+这类记录在每次搜索都要构造，导入成本全落在固定开销上。
+
+兼容面：挂 `__dataclass_fields__`，标准库的 `dataclasses.replace` /
+`is_dataclass` / `fields` 对实例照常工作（`_field_type` 惰性解析）。
+
+仍不建议新代码接入本模块的 `SearchResult`（引擎输出直接透传 dict，运行时
+防御在 engines_base/safe_search 里）；这里的价值在**替代实现本身**。
 """
 from __future__ import annotations
 
+import sys
 from enum import Enum
-
-from dataclasses import dataclass, field, asdict
 from typing import Any
 
 
-@dataclass
+class _FieldMeta:
+    """`__dataclass_fields__` 的兼容描述子。
+
+    `dataclasses.replace` 只读 `.init`；`dataclasses.fields` 会按
+    `_field_type is dataclasses._FIELD` 过滤，所以 `_field_type` 做成**惰性
+    属性**：dataclasses 已被 import 时（也就是有人真去调 `fields()` 时）
+    返回真哨兵，没 import 时返回 None。热路径因此仍然零导入——`_FIELD`
+    只在 dataclasses 已经进场后才去取它。
+    """
+
+    __slots__ = ("name", "init")
+
+    def __init__(self, name: str) -> None:
+        self.name = name
+        self.init = True
+
+    @property
+    def _field_type(self) -> Any:
+        dc = sys.modules.get("dataclasses")
+        return getattr(dc, "_FIELD", None) if dc is not None else None
+
+
+class _SlotField:
+    __slots__ = ("factory",)
+
+    def __init__(self, default_factory: Any) -> None:
+        self.factory = default_factory
+
+
+def slot_field(*, default_factory: Any) -> Any:
+    """零依赖 field(default_factory=...) 替代。"""
+    return _SlotField(default_factory)
+
+
+def _class_annotations(cls: Any) -> dict:
+    """读类的注解，兼容 PEP 649 惰性注解。
+
+    `cls.__dict__["__annotations__"]` 在 3.14 的惰性注解下**可能根本不存在**
+    （注解由 `__annotate__` 描述子按需计算，不进类字典）——此时取到的是
+    `{}`，类会静默变成「零字段」，实例化时报一个与真因毫不相干的
+    TypeError。必须走 `getattr` 触发描述子。
+    """
+    return getattr(cls, "__annotations__", None) or {}
+
+
+def slot_record(_cls: Any = None, *, frozen: bool = False) -> Any:
+    """零依赖 @dataclass 替代（省去 import dataclasses→inspect→tokenize→dis ~8ms）。
+
+    挂上 `__dataclass_fields__` 兼容描述子，标准库 `dataclasses.replace` /
+    `dataclasses.is_dataclass` / `dataclasses.fields` 对实例照常工作，但热
+    路径自身零导入（`_field_type` 惰性解析，只在 dataclasses 已进场时取哨兵）。
+    """
+    def _wrap(cls: Any) -> Any:
+        ann = list(_class_annotations(cls).keys())
+        defaults = {k: cls.__dict__[k] for k in ann if k in cls.__dict__}
+
+        def __init__(self: Any, *args: Any, **kwargs: Any) -> None:
+            if len(args) > len(ann):
+                raise TypeError(f"{cls.__name__}.__init__() takes {len(ann)} positional arguments but {len(args)} were given")
+            for i, val in enumerate(args):
+                object.__setattr__(self, ann[i], val)
+            for k in ann[len(args):]:
+                if k in kwargs:
+                    val = kwargs.pop(k)
+                elif k in defaults:
+                    d = defaults[k]
+                    val = d.factory() if isinstance(d, _SlotField) else d
+                else:
+                    raise TypeError(f"{cls.__name__}.__init__() missing required argument: {k!r}")
+                object.__setattr__(self, k, val)
+            if kwargs:
+                bad = next(iter(kwargs))
+                raise TypeError(f"{cls.__name__}.__init__() got an unexpected keyword argument {bad!r}")
+
+        cls._slot_fields = tuple(ann)
+        cls.__dataclass_fields__ = {k: _FieldMeta(k) for k in ann}
+        cls.__init__ = __init__
+        if frozen:
+            def __setattr__(self: Any, name: str, value: Any) -> None:
+                raise AttributeError(f"cannot assign to field {name!r}")
+            cls.__setattr__ = __setattr__
+        return cls
+
+    return _wrap if _cls is None else _wrap(_cls)
+
+
+def slot_replace(obj: Any, **changes: Any) -> Any:
+    """零依赖 replace(obj, **changes) 替代。"""
+    kw = {k: getattr(obj, k) for k in obj._slot_fields}
+    kw.update(changes)
+    return type(obj)(**kw)
+
+
+@slot_record
 class SearchResult:
     """统一的搜索结果数据类。"""
     title: str
@@ -22,7 +120,7 @@ class SearchResult:
     snippet: str = ""
     score: float = 0.5
     source: str = ""
-    metadata: dict = field(default_factory=dict)
+    metadata: dict = slot_field(default_factory=dict)
     social_meta: dict | None = None
 
     def to_dict(self) -> dict[str, Any]: