argo-search 1.0.1 → 2.9.8

package/scripts/engine_policy.py

@@ -0,0 +1,218 @@
+#!/usr/bin/env python3
+"""engine_policy.py — 引擎分层与 combo 预算（日常 vs 深度研究）
+
+单一策略层，避免 route/search/research 各自 if 分叉。
+
+tier（引擎 config 可覆写 engines.<id>.tier）：
+  daily_core      默认；意图命中即可跑
+  daily_support   同 daily，但优先被 budget 截断掉（靠 combo 后排）
+  research_only   仅 context=research / depth=deep / mode=deep
+
+combo 预算：
+  fast / budget / depth=fast → 最多 2
+  auto / balanced             → 最多 3
+  deep / research            → 不截断（全 combo + research_only）
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Iterable
+
+# 默认 research_only：长尾/慢/脆，日常窄域主源不要标这里
+DEFAULT_RESEARCH_ONLY: frozenset[str] = frozenset({
+    "wayback_cdx",
+    "archive_org",
+    "gutenberg",
+    "seeking_alpha",
+    "courtlistener",
+    "nasa_cmr",
+    "usgs",  # earth_science 双源时 daily 只留 usgs 需 domain 有别的 core；见 filter 保底
+    "rcsb_pdb",  # protein 以 uniprot 为主
+})
+
+# 明确 daily 答案源，永不标 research_only（防误配）
+FORCE_DAILY_CORE: frozenset[str] = frozenset({
+    "sina_quote", "tencent_quote", "em_flow", "eastmoney",
+    "fred", "worldbank", "fx_rate", "nbs_stats", "eurostat",
+    "pubchem", "rfc_editor", "gbif", "clinicaltrials",
+    "finviz", "anysearch", "byted", "octen",
+    "arxiv", "github", "wikipedia",
+    "zhihu", "zhihu_hot",
+})
+
+# 通用免费保底源（唯一来源）：route 保底 / 域内引擎全过滤 / recovery L3 共用。
+# 顺序 = 通用检索优先（anysearch），本地零成本引擎居中（供语言引擎展开），
+# 百科殿后（knowledge 族，最后保底）。route 侧本地优先时以 ["local_search"] 前缀
+# 再引用本清单；recovery 直接按本顺序遍历。预算截断由调用方完成。
+# 2026-09-07：duckduckgo 移出——本地使用日志 45% 错误率 + 实测 11.1s 0 条（本机网络
+# 限流），串行保底链里它是最大死重；uapi 顶入（免 key 聚合，历史 521 次 0% 错）。
+# 2026-09-12：firecrawl 顶入（免 key 云搜索，JS 渲染/PDF/学术垂直）——它的声明
+# 一直写着「免费池可路由（daily_support）」，但没有接进任何分发路径，属死源；
+# 排在通用检索源末位 + spec 的 tier=daily_support，日常 fast/auto 的 combo 预算
+# （2/3 个）够不到它，只在 deep/research 无截断时参战，共享免费层不被烧穿。
+GENERAL_FREE_FALLBACK: tuple[str, ...] = (
+    # 2026-10-21 A/B：octen 顶到第一位。交错对拍（ab_eval，4 对/查询、
+    # --no-cache）里 octen 对 anysearch 8:0 全胜：露营 天幕 p90 6313→835ms、
+    # asyncio p90 2769→963ms，结果数中位同为 8。生产日志同向：general_search
+    # 346 条查询里 324 条的最后一棒是 anysearch（p50 1932ms），octen 同域
+    # p50 776ms。anysearch 退到对冲位，能力面不变（仍在 combo 内）。
+    "octen", "anysearch", "local_bing", "uapi", "local_baidu", "firecrawl",
+    "parallel_free", "tavily_free", "keenable_free", "wikipedia",
+)
+
+
+def is_research_context(
+    *,
+    mode: str = "auto",
+    depth: str = "fast",
+    context: str = "search",
+) -> bool:
+    """是否允许 research_only 引擎与全量 combo。"""
+    if (context or "search") == "research":
+        return True
+    if (depth or "fast") == "deep":
+        return True
+    if (mode or "auto") == "deep":
+        return True
+    return False
+
+
+def combo_budget(
+    *,
+    mode: str = "auto",
+    depth: str = "fast",
+    context: str = "search",
+    extra: int = 0,
+) -> int | None:
+    """combo 最大引擎数；None = 不截断。
+
+    extra：垂直域的「新专源加成」。批次九的 11 个新源声明在 combo 后排
+    （位次 3~6），而日常预算只有 2~3 —— 截断后它们永不参与自动路由。
+    直接调大全局预算会拖慢所有查询，用 must_keep 顶位又会挤掉既有可用源
+    （实测会把 open_library/douban_movie/musicbrainz 挤出）。故只给
+    「确有新专源待接」的垂直域加固定额度，其余域预算不变。
+    """
+    if is_research_context(mode=mode, depth=depth, context=context):
+        return None
+    base = 2 if ((mode or "auto") in ("fast", "budget")
+                 or (depth or "fast") == "fast") else 3
+    return base + max(0, int(extra or 0))
+
+
+def get_engine_tier(engine_id: str, spec: dict[str, Any] | None = None) -> str:
+    """解析引擎 tier。"""
+    if engine_id in FORCE_DAILY_CORE:
+        return "daily_core"
+    if spec:
+        t = (spec.get("tier") or "").strip().lower()
+        if t in ("daily_core", "daily_support", "research_only"):
+            return t
+    if engine_id in DEFAULT_RESEARCH_ONLY:
+        return "research_only"
+    return "daily_core"
+
+
+def _tier_lookup() -> Callable[[str], str]:
+    try:
+        from config import get_engines, load_config
+        engines = get_engines(load_config())
+    except Exception:
+        engines = {}  # 配置加载失败：退回空引擎表，tier 查询退化为默认值
+
+    def _t(eid: str) -> str:
+        return get_engine_tier(eid, engines.get(eid) if isinstance(engines, dict) else None)
+
+    return _t
+
+
+def filter_combo_by_policy(
+    combo: list[str],
+    *,
+    mode: str = "auto",
+    depth: str = "fast",
+    context: str = "search",
+    tier_of: Callable[[str], str] | None = None,
+    budget_extra: int = 0,
+) -> list[str]:
+    """按 tier + budget 过滤 combo。
+
+    若 research_only 过滤后为空（域内全是研究源），保留原 combo 再截断预算，
+    避免「问蛋白质却一个引擎都没有」。
+
+    budget_extra：垂直域新专源加成，见 `combo_budget` 的 extra 说明。
+    """
+    if not combo:
+        return []
+    tier_of = tier_of or _tier_lookup()
+    allow_ro = is_research_context(mode=mode, depth=depth, context=context)
+
+    if allow_ro:
+        filtered = list(combo)
+    else:
+        kept = [e for e in combo if tier_of(e) != "research_only"]
+        filtered = kept if kept else list(combo)
+
+    budget = combo_budget(mode=mode, depth=depth, context=context,
+                          extra=budget_extra)
+    if budget is not None and len(filtered) > budget:
+        filtered = filtered[:budget]
+    return filtered
+
+
+def boost_into_combo(
+    combo: list[str],
+    boosts: Iterable[str] | None,
+    *,
+    enabled: set[str] | None = None,
+    max_total: int | None = None,
+) -> list[str]:
+    """将 boost 引擎插入 combo 前部（去重，可选 enabled 过滤）。
+
+    用于研究子查询：不锁死单引擎，而是抬高垂直源优先级后仍走 auto 融合。
+    """
+    base = list(combo or [])
+    if not boosts:
+        out = base
+    else:
+        head: list[str] = []
+        for e in boosts:
+            if not e or e == "auto":
+                continue
+            if enabled is not None and e not in enabled:
+                continue
+            if e not in head:
+                head.append(e)
+        tail = [e for e in base if e not in head]
+        out = head + tail
+    if max_total is not None and max_total > 0:
+        out = out[:max_total]
+    return out
+
+
+def research_engine_hints(
+    profile: dict[str, Any] | None,
+    sub_index: int,
+) -> list[str]:
+    """从选题 profile 生成子查询引擎 boost 列表。
+
+    子查询 0：vertical + priority 前 2（广度）
+    子查询 k>0：轮转 priority/vertical
+    """
+    if not profile:
+        return []
+    vertical = list(profile.get("vertical_engines") or [])
+    priority = list(profile.get("engines_priority") or [])
+    # 合并去重，vertical 优先
+    merged: list[str] = []
+    for e in vertical + priority:
+        if e and e not in merged:
+            merged.append(e)
+    if not merged:
+        return []
+    if sub_index <= 0:
+        return merged[:3]
+    # 轮转：每次取 2 个从 offset 起
+    n = len(merged)
+    start = (sub_index - 1) % n
+    picked = [merged[(start + i) % n] for i in range(min(2, n))]
+    return picked

package/scripts/engine_requires.py

@@ -0,0 +1,190 @@
+#!/usr/bin/env python3
+"""engine_requires.py — 引擎后端依赖声明的解析、检查与修复指引。
+
+背景（v2.4.2）：argo 的 CLI 引擎此前只校验 `cmd[-1]` 指向的脚本文件是否存在
+（见 config._validate_engine_paths）。这对「壳脚本」型引擎完全无效：例如
+xiaohongshu 引擎的 cmd 是 `python3 scripts/social_engines/xiaohongshu_engine.py`，
+脚本文件当然存在，于是状态显示 ready；但该脚本内部真正调用的 `xhs` 二进制
+依赖外部 CLI（xhs-cli），用户没装时它只是静默返回空列表——`--list-engines
+--detail` 仍报 ready，调用后白等到超时、拿到 0 条，且无从知道「缺什么、怎么装」。
+
+本模块引入声明式依赖：
+
+  engines:
+    xiaohongshu:
+      requires:
+        - bin: xhs                      # 必需的 PATH 可执行文件
+          fix: npm i -g xiaohongshu-cli  # 缺失时的修复指引
+          optional: false                # true 时缺失只降级不报 missing_dep
+        - bin: yt-dlp
+          min_version: "2024.01.01"      # 可选：最低版本（尽力检查）
+
+设计原则（与既有 required_env / engine_env.py 同构，属扩展而非外来物）：
+  - 只声明「后端工具」，不声明「密钥」（密钥仍归 required_env）
+  - 检查是只读的：`shutil.which` + 一次 `--version` 调用，绝不自动安装
+  - 缺失必须给出可执行 fix 指令，否则声明即无意义
+  - 检查结果可缓存（同进程内），避免 list-engines 对 168 引擎反复起子进程
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+import threading
+from typing import Any
+
+# 进程内缓存：{(bin, min_version): (ok, actual_version, reason)}
+_cache: dict[tuple[str, str | None], tuple[bool, str | None, str | None]] = {}
+_cache_lock = threading.Lock()
+
+# version 探测的候选参数（不同工具约定不同）
+_VERSION_ARGS = ("--version", "-version", "-V", "version")
+
+
+def _probe_version(bin_path: str, timeout: float = 3.0) -> str | None:
+    """尽力探测可执行文件的版本串；失败返回 None（不作为失败依据）。"""
+    for arg in _VERSION_ARGS:
+        try:
+            r = subprocess.run(
+                [bin_path, arg],
+                capture_output=True, text=True,
+                encoding="utf-8", errors="replace",  # Windows GBK 下防乱码/崩溃
+                timeout=timeout,
+            )
+            out = (r.stdout or "") + (r.stderr or "")
+            out = out.strip()
+            if out:
+                return out.splitlines()[0][:120]
+        except Exception:
+            continue
+    return None
+
+
+def _parse_version_numbers(text: str | None) -> tuple[int, ...]:
+    """从版本串里抽出数字段，用于比较。抽不到返回空元组。"""
+    if not text:
+        return ()
+    nums: list[int] = []
+    cur = ""
+    for ch in text:
+        if ch.isdigit():
+            cur += ch
+        else:
+            if cur:
+                nums.append(int(cur))
+                cur = ""
+    if cur:
+        nums.append(int(cur))
+    return tuple(nums[:4])
+
+
+def _version_ok(actual: str | None, minimum: str | None) -> bool:
+    """actual >= minimum？任一解析不出数字则视为通过（不误报缺失）。"""
+    if not minimum:
+        return True
+    a, b = _parse_version_numbers(actual), _parse_version_numbers(minimum)
+    if not a or not b:
+        return True
+    n = max(len(a), len(b))
+    a = a + (0,) * (n - len(a))
+    b = b + (0,) * (n - len(b))
+    return a >= b
+
+
+def check_requirement(req: dict[str, Any]) -> dict[str, Any]:
+    """检查单条依赖声明，返回结构化结果。
+
+    返回 {bin, ok, actual_version, required_version, reason, fix, optional}
+    """
+    bin_name = str(req.get("bin") or "").strip()
+    minimum = req.get("min_version")
+    optional = bool(req.get("optional", False))
+    fix = str(req.get("fix") or "").strip()
+    out = {
+        "bin": bin_name,
+        "ok": False,
+        "actual_version": None,
+        "required_version": minimum,
+        "reason": None,
+        "fix": fix,
+        "optional": optional,
+    }
+    if not bin_name:
+        out["reason"] = "invalid-requirement"
+        return out
+
+    key = (bin_name, minimum)
+    with _cache_lock:
+        cached = _cache.get(key)
+    if cached is not None:
+        ok, actual, reason = cached
+        out.update({"ok": ok, "actual_version": actual, "reason": reason})
+        return out
+
+    path = shutil.which(bin_name)
+    if not path:
+        ok, actual, reason = False, None, "bin-not-found"
+    else:
+        actual = _probe_version(path)
+        if _version_ok(actual, minimum):
+            ok, reason = True, None
+        else:
+            ok, reason = False, "version-too-old"
+    with _cache_lock:
+        _cache[key] = (ok, actual, reason)
+    out.update({"ok": ok, "actual_version": actual, "reason": reason})
+    return out
+
+
+def requirements_of(spec: dict[str, Any] | None) -> list[dict[str, Any]]:
+    """从 engine spec 取出 requires 声明（规范化成 list[dict]）。
+
+    容错：允许简写 `requires: [{bin: xhs}]`，也允许字符串简写
+    `requires: ["xhs"]`（等价 {bin: xhs}），便于手写 config。
+    """
+    spec = spec or {}
+    raw = spec.get("requires")
+    if not raw:
+        return []
+    if isinstance(raw, str):
+        raw = [raw]
+    if not isinstance(raw, list):
+        return []
+    out: list[dict[str, Any]] = []
+    for item in raw:
+        if isinstance(item, str) and item.strip():
+            out.append({"bin": item.strip()})
+        elif isinstance(item, dict) and item.get("bin"):
+            out.append(dict(item))
+    return out
+
+
+def requires_status(spec: dict[str, Any] | None) -> dict[str, Any]:
+    """引擎依赖总览：缺失的必需项 + 全部检查明细。
+
+    missing_deps 只含必需项（optional 缺失不算），保证状态机
+    `missing_dep` 只反映「真的跑不了」，不把可选增强算成故障。
+    """
+    reqs = requirements_of(spec)
+    if not reqs:
+        return {"requires": [], "missing_deps": [], "dep_ready": True,
+                "dep_fixes": []}
+    checked = [check_requirement(r) for r in reqs]
+    missing = [c for c in checked if not c["ok"] and not c["optional"]]
+    return {
+        "requires": checked,
+        "missing_deps": [{"bin": c["bin"], "reason": c["reason"],
+                          "fix": c["fix"]} for c in missing],
+        "dep_ready": not missing,
+        # 修复指引：缺失项自带 fix；未声明 fix 的给通用保底提示
+        "dep_fixes": [
+            c["fix"] or f"安装 {c['bin']} 并确保其在 PATH 上"
+            for c in missing
+        ],
+    }
+
+
+def clear_cache() -> None:
+    """清空探测缓存（测试与配置热更新用）。"""
+    with _cache_lock:
+        _cache.clear()