argo-search 2.9.7 → 2.9.8

package/scripts/search_attribution.py

@@ -44,15 +44,112 @@ def top_engine_latency(engine_latency: dict[str, Any] | None,
 
 
 def usage_log_attribution(engine_latency: dict[str, Any] | None,
-                          top_n: int = DEFAULT_TOP_N) -> dict[str, Any]:
-    """usage_log query 流的归因字段（当前只有引擎耗时 Top-N）。
+                          top_n: int = DEFAULT_TOP_N,
+                          engine_outcomes: Iterable[dict[str, Any]] | None = None
+                          ) -> dict[str, Any]:
+    """usage_log query 流的归因字段（慢源 Top-N + 失败类别）。
 
     返回 dict 以便调用方 **展开进日志记录**，未来新增归因维度（如
     「等待预算被谁耗掉」「缓存未命中的原因分布」）时只扩这里，
     主管线那一行 `**usage_log_attribution(...)` 不动——归因是会长大的，
     写入点不该跟着长（主管线有模块大小门禁，见模块 docstring）。
+
+    失败类别只记「哪类」不记条数：errors 已经记了条数，两者互补。
+    """
+    out: dict[str, Any] = {
+        "engine_latency_top": top_engine_latency(engine_latency, top_n),
+    }
+    kinds = failure_kinds(engine_outcomes)
+    if kinds:
+        out["failure_kinds"] = kinds
+    return out
+
+
+# 合成引擎名（只存在于基准/混沌测试的 fake combo）。它们出现在 engines_used
+# 里就说明这一跑不是真实检索；写进生产 usage_log 会污染慢源排行与总量统计
+# （2026-10-21 实测 "hedge bench" 32 条，dead_primary/fast_backup 进了慢源榜）。
+_SYNTHETIC_ENGINES: frozenset[str] = frozenset({
+    "dead_primary", "dead_backup", "fast_backup", "slow_backup",
+    "slow_primary", "quick_primary", "fast_primary",
+})
+
+
+def is_synthetic_run(engines: Iterable[str] | None) -> bool:
+    """这组引擎是否来自基准/测试的合成组合（有一个即判合成）。"""
+    return any(str(e) in _SYNTHETIC_ENGINES for e in (engines or []))
+
+
+# 「源被跳过/没资格调用」的状态：空结果时要把它们与「查询没有召回」分开。
+# 只收持续性状态（配额/缺 env/鉴权），不含 timeout/error——后者是本次
+# 真的失败了，原表述已够用。
+SKIPPED_SOURCE_STATUSES: frozenset[str] = frozenset({
+    "skipped-quota-exhausted", "skipped-missing-env",
+    "quota-exhausted", "auth-failed",
+})
+
+
+def skipped_sources(engine_outcomes: Iterable[dict[str, Any]] | None,
+                    limit: int = 4) -> list[str]:
+    """空结果时被跳过/鉴权失败的引擎名（去重、保序、限量）。"""
+    out: list[str] = []
+    seen: set[str] = set()
+    for o in (engine_outcomes or []):
+        if not isinstance(o, dict):
+            continue
+        if str(o.get("status") or "") not in SKIPPED_SOURCE_STATUSES:
+            continue
+        name = str(o.get("engine") or "?")
+        if name not in seen:
+            seen.add(name)
+            out.append(name)
+        if len(out) >= max(0, int(limit)):
+            break
+    return out
+
+
+def zero_result_recovery_note(recovery: Any,
+                              engine_outcomes: Iterable[dict[str, Any]] | None
+                              ) -> str | None:
+    """恢复链触发但没救回来时的局限声明；不需要声明时返回 None。
+
+    「没有召回」与「源被跳过/鉴权失败」处置完全不同：前者改写查询，
+    后者看 failures 或补凭证。此前一律写成 no recall，实测 bocha 配额
+    耗尽（403 not enough money）被报成「查询无召回」，调用方白跑一轮。
     """
-    return {"engine_latency_top": top_engine_latency(engine_latency, top_n)}
+    if not isinstance(recovery, dict) or not recovery.get("triggered") \
+            or recovery.get("recovered"):
+        return None
+    note = recovery.get("note") or "no note"
+    skipped = skipped_sources(engine_outcomes)
+    if skipped:
+        return (
+            "recovery triggered but no usable strategy ("
+            f"{note}); empty results came from skipped/failed sources "
+            f"({', '.join(skipped)}) — see failures; this is not necessarily "
+            "a no-recall query"
+        )
+    return (
+        "recovery triggered but no usable strategy ("
+        f"{note}); empty results likely mean the query had no recall — "
+        "try rephrasing"
+    )
+
+
+def failure_kinds(engine_outcomes: Iterable[dict[str, Any]] | None,
+                  limit: int = 6) -> list[str]:
+    """本次调用的失败类别（去重、稳定排序），写进 usage_log 供长期归因。
+
+    errors 只记「几条」，回答不了「哪类失败在反复出现」；类别来自
+    output_transparency.build_failures（与 agent 档 failures 同一口径），
+    不在日志侧另写一份分类。
+    """
+    try:
+        from output_transparency import build_failures
+    except ImportError:  # pragma: no cover - 单文件分发时的降级
+        return []
+    rows = build_failures({"engine_outcomes": list(engine_outcomes or [])},
+                          limit=limit)
+    return sorted({str(r.get("category") or "unknown") for r in rows})
 
 
 def aggregate_slow_engines(rows: Iterable[dict[str, Any]],

package/scripts/search_cli.py

@@ -328,6 +328,27 @@ def _format_engine_summary(summary: dict[str, Any]) -> str:
     return "\n".join(lines)
 
 
+def _merge_verify_timing(timing: dict[str, Any], verify_ms: float) -> None:
+    """把 verify 的墙钟并回 timing 的三个总数，保持互相自洽。
+
+    why：verify 发生在主搜索快照之后。此前只并回 stages_ms/process_ms，
+    elapsed_ms 仍是主搜索的数（实测 1173 vs 10967），调用方最先读的总账
+    比它的分项之和还小 8 倍。三个数必须一起走，否则「这次为什么慢」会被
+    带偏到主搜索上。
+    """
+    total = float(timing.get("stages_ms") or 0) + verify_ms
+    timing.setdefault("stages", []).append({
+        "stage": "verify",
+        "ms": round(verify_ms, 1),
+        "pct": round(verify_ms * 100.0 / total, 1) if total > 0 else 0.0,
+    })
+    timing["stages_ms"] = round(total, 1)
+    timing["process_ms"] = round(
+        float(timing.get("process_ms") or 0) + verify_ms, 1)
+    timing["elapsed_ms"] = round(
+        max(float(timing.get("elapsed_ms") or 0), total), 1)
+
+
 def main():
     # 入口第一件事：钉住 stdout/stderr 编码（实现唯一，见 cli_io）。
     # 放在这里而不是 import 期：本模块被 search.py 与 bin/argo 两条路调用，
@@ -579,19 +600,11 @@ def main():
     # （process_ms 定格处）之后，净增 280–1160ms 完全不进任何账——实测
     # wall 776–1746ms vs process_ms 494–701ms，「这次为什么慢」归因指错
     # 方向。快照后移做不到（verify 是装配后的可选后处理），补一个 stage
-    # 并把耗时并回 stages_ms / process_ms，两个总数保持自洽。
+    # 并把耗时并回三个总数（stages_ms / process_ms / elapsed_ms），
+    # 三者保持自洽（2026-10-22 补 elapsed_ms）。
     if _timing is not None and "timing" in results and args.verify:
         _verify_ms = (time.perf_counter() - _t_verify0) * 1000.0
-        _t = results["timing"]
-        _total = float(_t.get("stages_ms") or 0) + _verify_ms
-        _t.setdefault("stages", []).append({
-            "stage": "verify",
-            "ms": round(_verify_ms, 1),
-            "pct": round(_verify_ms * 100.0 / _total, 1) if _total > 0 else 0.0,
-        })
-        _t["stages_ms"] = round(_total, 1)
-        _t["process_ms"] = round(
-            float(_t.get("process_ms") or 0) + _verify_ms, 1)
+        _merge_verify_timing(results["timing"], _verify_ms)
 
     if args.json_output:
         public = {k: v for k, v in results.items() if not k.startswith("_")}

package/scripts/search_entry.py

@@ -28,7 +28,7 @@ engine_dispatch。
 from __future__ import annotations
 
 import time
-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, Callable, Optional
 
 from engine_dispatch import run_dispatch
@@ -361,6 +361,11 @@ def dispatch(req: _SearchRequest, run: _SearchRun, hooks: _SearchHooks) -> _Sear
     engine_latency = _dispatch.engine_latency
     wasted_ms = _dispatch.wasted_ms
     useful_ms = _dispatch.useful_ms
+    dispatch_tail = {
+        "first_sufficient_ms": _dispatch.first_sufficient_ms,
+        "tail_wait_ms": _dispatch.tail_wait_ms,
+        "abandoned_engine_ms": _dispatch.abandoned_engine_ms,
+    }
     early_stopped = _dispatch.early_stopped
     budget_used_ms = _dispatch.budget_used_ms
     budget_total_ms = _dispatch.budget_total_ms
@@ -378,6 +383,7 @@ def dispatch(req: _SearchRequest, run: _SearchRun, hooks: _SearchHooks) -> _Sear
         engine_latency=engine_latency,
         wasted_ms=wasted_ms,
         useful_ms=useful_ms,
+        dispatch_tail=dispatch_tail,
         early_stopped=early_stopped,
         budget_used_ms=budget_used_ms,
         budget_total_ms=budget_total_ms,

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