argo-search 1.0.1 → 2.9.8

package/scripts/network_aware.py

@@ -0,0 +1,152 @@
+#!/usr/bin/env python3
+"""
+network_aware.py — 网络环境感知（v2.7 新增）
+
+利用 adaptive 引擎表现数据 + 运行时实测，推断当前网络环境并给出
+自适应策略建议。核心洞察：
+  - adaptive.get_score 已经综合了 success × latency × cost，
+    是天然的「网络传感器」（慢网 → 延迟高 → 分数低）
+  - 不同网络环境应使用不同策略：慢网放大超时预算、快网收紧、
+    受限网优先本地引擎
+
+纯 stdlib，无外部依赖。任何失败都返回中性建议，不阻断搜索。
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any
+
+# 引擎延迟采样窗口（秒）
+_LATENCY_WINDOW = 24 * 3600
+
+# 网络环境判定阈值（平均延迟，毫秒）
+_FAST_THRESHOLD_MS = 800.0     # 平均 < 0.8s → 快网
+_SLOW_THRESHOLD_MS = 3000.0    # 平均 > 3s → 慢网
+
+# 超时缩放范围
+_TIMEOUT_SCALE_MIN = 0.8
+_TIMEOUT_SCALE_MAX = 1.8
+
+_cache: dict[str, Any] = {}
+
+
+def _avg_latency(learner: Any, engines: list[str]) -> float | None:
+    """从 adaptive 数据估计引擎平均延迟（无数据返回 None）。"""
+    latencies: list[float] = []
+    for e in engines:
+        try:
+            # 用 score 反推延迟不可靠；直接查 adaptive 的 per-engine 平均延迟
+            score = learner.get_score(e)
+            # score 已含 latency_factor，但需原始延迟 → 查 db
+            lat = _latency_from_db(e)
+            if lat is not None:
+                latencies.append(lat)
+        except Exception:
+            continue
+    if not latencies:
+        return None
+    return sum(latencies) / len(latencies)
+
+
+def _latency_from_db(engine: str) -> float | None:
+    """直接查 adaptive.db 的 AVG(latency_ms)（绕过 score 的合成因子）。"""
+    try:
+        from adaptive import DB_PATH, WINDOW_DAYS
+        import sqlite3
+        cutoff = time.time() - WINDOW_DAYS * 86400
+        conn = sqlite3.connect(str(DB_PATH), timeout=2)
+        try:
+            row = conn.execute(
+                "SELECT AVG(latency_ms) FROM engine_perf "
+                "WHERE engine = ? AND created_at > ?",
+                (engine, cutoff),
+            ).fetchone()
+            lat = row[0] if row and row[0] is not None else None
+            return float(lat) if lat else None
+        finally:
+            conn.close()
+    except Exception:
+        return None
+
+
+def network_profile(engines: list[str]) -> dict[str, Any]:
+    """推断当前网络环境，返回策略建议。
+
+    Returns:
+        {
+          "network": "fast" | "normal" | "slow" | "unknown",
+          "avg_latency_ms": float | None,
+          "timeout_scale": float,      # 超时缩放（0.8 ~ 1.8）
+          "prefer_local": bool,        # 受限网偏好本地引擎
+        }
+    """
+    now = time.time()
+    cached = _cache.get("profile")
+    if cached and now - cached["_ts"] < 60:  # 60s 缓存
+        return cached["data"]
+
+    profile: dict[str, Any] = {
+        "network": "unknown",
+        "avg_latency_ms": None,
+        "timeout_scale": 1.0,
+        "prefer_local": False,
+    }
+    try:
+        from adaptive import get_learner
+        learner = get_learner()
+        avg = _avg_latency(learner, engines or [])
+        if avg is None:
+            # 无数据：用健康探针的延迟
+            avg = _probe_latency(engines)
+        if avg is not None:
+            profile["avg_latency_ms"] = round(avg, 1)
+            if avg < _FAST_THRESHOLD_MS:
+                profile["network"] = "fast"
+                profile["timeout_scale"] = _TIMEOUT_SCALE_MIN
+            elif avg > _SLOW_THRESHOLD_MS:
+                profile["network"] = "slow"
+                profile["timeout_scale"] = _TIMEOUT_SCALE_MAX
+                profile["prefer_local"] = True
+            else:
+                profile["network"] = "normal"
+                profile["timeout_scale"] = 1.0
+    except Exception:
+        pass
+
+    _cache["profile"] = {"_ts": now, "data": profile}
+    return profile
+
+
+def _probe_latency(engines: list[str]) -> float | None:
+    """无 adaptive 数据时，用 health_probe 的 last_latency_ms 估计。"""
+    try:
+        from health_probe import get_engine_status
+        lats = []
+        for e in engines:
+            st = get_engine_status(e)
+            lat = st.get("last_latency_ms")
+            if isinstance(lat, (int, float)) and lat > 0:
+                lats.append(float(lat))
+        if lats:
+            return sum(lats) / len(lats)
+    except Exception:
+        pass
+    return None
+
+
+def adjusted_timeout(base_timeout: int, engines: list[str]) -> int:
+    """按网络环境调整超时预算。
+
+    慢网放大（最多 1.8×，避免误杀慢网下正常的引擎），
+    快网收紧（0.8×，更快响应），正常网不变。
+    """
+    profile = network_profile(engines)
+    scale = profile.get("timeout_scale", 1.0)
+    return max(1, int(base_timeout * scale))
+
+
+def should_prefer_local(engines: list[str]) -> bool:
+    """受限网偏好本地引擎（零成本、少外部依赖）。"""
+    profile = network_profile(engines)
+    return bool(profile.get("prefer_local"))

package/scripts/output_transparency.py

@@ -0,0 +1,200 @@
+#!/usr/bin/env python3
+"""output_transparency.py — 搜索输出的可信度评估、结构化失败清单与精简档透明修饰。
+
+从 search_output.py 拆出（2026-10-21）：
+  1. 单一职责：search_output 管「结果成形与人读格式」，本模块管「可信度/失败分类/
+     不可信边界」三件透明化信号；拆开后 search_output 保持在 ~650 行，远离千行硬限。
+  2. 口径合一：`_FAILURE_NON_ERROR` 与 `_NON_ERROR_OUTCOME` 同源派生，不再维护
+     两份独立 frozenset。
+"""
+
+from __future__ import annotations
+
+import sys
+from typing import Any
+
+# 本次调用不算失败的基础状态（引擎正常交付、无结果、或被早停主动取消）
+_FAILURE_NON_ERROR: frozenset[str] = frozenset({
+    "ok", "ok-cached", "partial", "no-results", "no-results-cached", "cancelled",
+})
+
+# errors[] 与 uncertainty 排除的 outcome 状态：在基础非错误集之上再排除
+# skipped-quota-exhausted（持续一天的配额跳过状态，不作为单次检索错误刷屏）
+_NON_ERROR_OUTCOME: frozenset[str] = _FAILURE_NON_ERROR | {"skipped-quota-exhausted"}
+
+# 二手/聚合平台（转载与洗稿高发地）。**刻意不复用 evidence 的词表**：
+# evidence 属热路径禁入名单（tests/test_hotpath_import_lint.py 的 HEAVY_TOP，
+# 它会拖进 content_signals/stylometry/burstiness 约 9ms），而本函数在每次
+# 搜索的收口处无条件执行。两处词表需同步——改这里时看 evidence.
+# _SECONDARY_PLATFORM_PATTERNS。
+_AGGREGATOR_HOSTS: frozenset[str] = frozenset({
+    "baijiahao.baidu.com",   # 百家号（自媒体洗稿重灾区）
+    "toutiao.com",           # 头条号（聚合+洗稿）
+    "k.sina.com.cn",         # 新浪博客/聚合
+    "guba.eastmoney.com",    # 股吧（UGC 讨论，非事实来源）
+})
+
+# 可信度等级（与 dsh-free-search 的 meta.uncertainty 同形）
+_UNCERTAINTY_HIGH = "high"
+_UNCERTAINTY_MEDIUM = "medium"
+_UNCERTAINTY_LOW = "low"
+# 严重度序：用于「多信号取最差」——等级只能降不升。
+_SEVERITY = {_UNCERTAINTY_HIGH: 0, _UNCERTAINTY_MEDIUM: 1, _UNCERTAINTY_LOW: 2}
+
+
+def _hostname(url: Any) -> str:
+    """URL → 归一化主机名（小写、去 www.）；解析失败返回空串。"""
+    try:
+        from urllib.parse import urlparse
+        host = urlparse(str(url or "")).hostname or ""
+    except Exception:
+        return ""
+    return host.lower().removeprefix("www.")
+
+
+# 失败类别 → (归一类别, 可执行建议, 是否可重试)。类别名与 dsh-free-search
+# 的 failureClass 对齐（quota/auth/bot-wall/transient/rate-limit/unknown），
+# 但归类依据是 argo 自己的 outcome.status（retry_policy.classify_error_status
+# 的唯一真源），不另写一套错误词表。
+_FAILURE_META: dict[str, tuple[str, str, bool]] = {
+    "timeout": ("transient", "超时；可重试或换源", True),
+    "quota-exhausted": ("quota", "配额耗尽；换源或等窗口重置", False),
+    "rate-limited": ("rate-limit", "被限流；稍后重试或换源", True),
+    "blocked": ("bot-wall", "被反爬拦截；稍后重试或换源", True),
+    "auth-failed": ("auth", "检查 API Key 是否有效、是否有该接口权限", False),
+    "error": ("unknown", "源端错误；可重试或换源", True),
+    "skipped-missing-env": ("missing-key", "未配置密钥；配置后即可参与", False),
+    "skipped-quota-exhausted": ("quota", "配额耗尽，本轮跳过", False),
+    "skipped-circuit-open": ("cooldown", "熔断冷却中，稍后自动恢复", True),
+    "skipped-budget": ("budget", "本轮预算不足，未执行", True),
+}
+
+
+def build_failures(result: dict[str, Any], limit: int = 6) -> list[dict[str, Any]]:
+    """把引擎 outcome 压成 Agent 可行动的结构化失败清单。
+
+    与 errors 的分工：errors 是给人看的整行文本（兼容旧契约），本字段是
+    给模型/宿主判断「要不要重试、换哪个源、是不是缺 key」的分类结果。
+    只收录没交出结果的 outcome；ok/no-results 不算失败（后者是「查了没有」，
+    不是「没查成」），与 uncertainty 的降级判据同源。
+    """
+    out: list[dict[str, Any]] = []
+    seen: set[tuple[str, str]] = set()
+    for o in (result.get("engine_outcomes") or []):
+        if not isinstance(o, dict):
+            continue
+        engine = str(o.get("engine") or "")
+        status = str(o.get("status") or "")
+        if not engine or status in _FAILURE_NON_ERROR:
+            continue
+        key = (engine, status)
+        if key in seen:
+            continue
+        seen.add(key)
+        category, action, retryable = _FAILURE_META.get(
+            status, ("unknown", "源端异常；可重试或换源", True))
+        item: dict[str, Any] = {
+            "engine": engine,
+            "status": status,
+            "category": category,
+            "retryable": retryable,
+            "action": action,
+        }
+        # skipped-* 是「持续状态」而不是本次尝试失败：配额窗口/熔断冷却在
+        # 周期边界前不会因重试改变。标出来，避免 Agent 立刻重试同一个源。
+        if status.startswith("skipped-"):
+            item["persistent"] = True
+        detail = str(o.get("detail") or "").strip()
+        if detail:
+            item["detail"] = detail[:160]
+        out.append(item)
+        if len(out) >= max(1, limit):
+            break
+    return out
+
+
+def decorate_compact_payload(out: dict[str, Any],
+                             result: dict[str, Any]) -> None:
+    """精简响应（MCP/Agent 档）的收尾修饰：边界清洗 + 三件透明信息 + sources 投影。"""
+    try:
+        from content_boundary import (CONTENT_TRUST_UNTRUSTED,
+                                      sanitize_results_boundary)
+        sanitize_results_boundary(out.get("results"))
+        out["content_trust"] = CONTENT_TRUST_UNTRUSTED
+    except Exception:
+        pass
+    failures = result.get("failures")
+    if isinstance(failures, list) and failures:
+        out["failures"] = failures[:6]
+    meta = result.get("meta")
+    if isinstance(meta, dict) and meta.get("uncertainty"):
+        out["meta"] = {"uncertainty": meta["uncertainty"]}
+    sources = result.get("sources")
+    if sources:
+        out["sources"] = [
+            {
+                "ref": s.get("ref"),
+                "title": s.get("title"),
+                "url": s.get("url"),
+                "engine": s.get("engine") or s.get("source"),
+            }
+            for s in sources
+            if isinstance(s, dict) and s.get("url")
+        ][:20]
+
+
+def build_uncertainty(result: dict[str, Any]) -> dict[str, Any]:
+    """一次调用的综合可信度：`{"level": ..., "notes": [...]}`。
+
+    与 `limitations` 的分工：limitations 是**逐条**的局限声明（早停、降级、
+    缓存复用、站点过滤），本字段是**整体**等级——消费者拿到一个 level 就能
+    决定「直接引用」还是「先核验」，不必自己交叉比对五六个字段。
+    """
+    notes: list[str] = []
+    results = [r for r in (result.get("results") or []) if isinstance(r, dict)]
+
+    if not results:
+        return {"level": _UNCERTAINTY_LOW, "notes": ["没有返回结果"]}
+
+    level = _UNCERTAINTY_HIGH
+
+    def _worse(candidate: str) -> None:
+        nonlocal level
+        if _SEVERITY[candidate] > _SEVERITY[level]:
+            level = candidate
+
+    if len(results) == 1:
+        _worse(_UNCERTAINTY_LOW)
+        notes.append("只有 1 个来源，无法交叉验证")
+    elif len(results) == 2:
+        _worse(_UNCERTAINTY_MEDIUM)
+        notes.append("只有 2 个来源")
+
+    hosts = {_hostname(r.get("url")) for r in results}
+    hosts.discard("")
+    if 0 < len(hosts) == 1:
+        _worse(_UNCERTAINTY_MEDIUM)
+        notes.append("所有结果来自同一站点")
+
+    # 尊重 search_output._AGGREGATOR_HOSTS 的猴子补丁（test_output_uncertainty 门禁锁）
+    so_mod = sys.modules.get("search_output")
+    agg_hosts = getattr(so_mod, "_AGGREGATOR_HOSTS", _AGGREGATOR_HOSTS)
+    aggregators = sorted(h for h in hosts if h in agg_hosts
+                         or any(h.endswith("." + a) for a in agg_hosts))
+    if aggregators:
+        _worse(_UNCERTAINTY_MEDIUM)
+        notes.append(f"含聚合站内容（{'/'.join(aggregators)}），建议二次核对")
+
+    if result.get("time_filter_warning"):
+        _worse(_UNCERTAINTY_MEDIUM)
+        notes.append("时间窗未实际过滤，结果可能不在请求的时间范围内")
+
+    outcomes = [o for o in (result.get("engine_outcomes") or [])
+                if isinstance(o, dict)]
+    failed = [o for o in outcomes
+              if str(o.get("status") or "") not in _NON_ERROR_OUTCOME]
+    if failed:
+        _worse(_UNCERTAINTY_LOW)
+        notes.append(f"{len(failed)} 个引擎未交出结果，覆盖可能比计划的窄")
+
+    return {"level": level, "notes": notes}

package/scripts/paid_policy.py

@@ -0,0 +1,98 @@
+#!/usr/bin/env python3
+"""paid_policy.py — 付费搜索的自动对冲位（2026-10-21，方案一）。
+
+只解决一件事：在**已证明有优势的域**里，把付费引擎放到 combo 第二位当对冲，
+而不是让它进通用候选池（那会被 TF-IDF/兜底带到任意查询并扣费）。
+
+策略：
+  - `ARGO_PAID_SEARCH=off` → 完全关闭；缺省 `auto`。
+  - 该域在 `PAID_DOMAIN_HEDGES` 里，且引擎 key 就绪、月度预算未用完
+    → 返回该引擎；预算用完/无 key → 回落 `tinyfish`（免费、带日期），
+    再不行返回空，由原 combo 继续。
+  - `fast`/`budget` 模式不参与（与 quota 的成本纪律一致）。
+
+当前只开两个域：`english_tech`、`intl_news_flash`。依据 2026-10-21 多引擎
+实测：DeepSeek 在英文技术/英文新闻上 p50 515ms、日期覆盖 23/39，明显优于
+anysearch/Exa/Tavily；中文宽泛新闻与金融原文反而更差，故不纳入。
+"""
+
+from __future__ import annotations
+
+import os
+
+__all__ = ["PAID_DOMAIN_HEDGES", "hedge_for", "insert_hedge"]
+
+PAID_DOMAIN_HEDGES: dict[str, str] = {
+    "english_tech": "deepseek_search",
+    "intl_news_flash": "deepseek_search",
+}
+
+_FREE_FALLBACK = "tinyfish"
+
+
+def _enabled() -> bool:
+    try:
+        from engine_env import get_env
+        raw = get_env("ARGO_PAID_SEARCH", "auto")
+    except Exception:
+        raw = os.environ.get("ARGO_PAID_SEARCH", "auto")
+    return raw.strip().lower() not in ("off", "0", "false", "no")
+
+
+def _key_ready(engine: str) -> bool:
+    try:
+        from engine_env import missing_env_for
+        return not missing_env_for(engine)
+    except Exception:
+        return False
+
+
+def _budget_ok(engine: str) -> bool:
+    try:
+        from quota import get_quota_manager
+        return not get_quota_manager().is_hard_down(engine)
+    except Exception:
+        # 预算层读失败时 fail-closed：宁可不自动花钱
+        return False
+
+
+def _healthy_and_enabled(engine: str, enabled: set[str] | None) -> bool:
+    if enabled is not None and engine not in enabled:
+        return False
+    try:
+        from route_combo import _breaker_blocked
+        if _breaker_blocked(engine):
+            return False
+    except Exception:
+        pass
+    return True
+
+
+def hedge_for(domain: str, mode: str = "auto",
+              enabled: set[str] | None = None) -> list[str]:
+    """返回该域应插入的付费/回落引擎（0 或 1 个）。永不抛异常。"""
+    if not _enabled() or mode in ("fast", "budget"):
+        return []
+    engine = PAID_DOMAIN_HEDGES.get(str(domain or ""))
+    if not engine:
+        return []
+    try:
+        if (_healthy_and_enabled(engine, enabled)
+                and _key_ready(engine) and _budget_ok(engine)):
+            return [engine]
+        # 付费位不可用：TinyFish 是免费且带发布日期的回落位
+        if (_healthy_and_enabled(_FREE_FALLBACK, enabled)
+                and _key_ready(_FREE_FALLBACK) and _budget_ok(_FREE_FALLBACK)):
+            return [_FREE_FALLBACK]
+    except Exception:
+        return []
+    return []
+
+
+def insert_hedge(combo: list[str], domain: str, mode: str = "auto",
+                 enabled: set[str] | None = None) -> list[str]:
+    """把付费/回落引擎插到 combo 第二位（原地改并返回，便于链式调用）。"""
+    for engine in reversed(hedge_for(domain, mode, enabled=enabled)):
+        if engine not in combo:
+            combo.insert(min(1, len(combo)), engine)
+    return combo