argo-search 1.0.1 → 2.9.7

package/scripts/query_signals.py

@@ -0,0 +1,300 @@
+#!/usr/bin/env python3
+"""query_signals.py — 查询改写与「结果够不够」的判定。
+
+从 search.py 中外提。这里放的全是**本地启发式**判断，不发起网络请求、
+不依赖搜索编排状态，因此可以被搜索之外的层（评测、路由、批量任务）复用。
+
+两类信号：
+  - 查询改写（apply_query_rewrite）：把口语化查询换成更适合检索的形式
+  - 早停判定（results_sufficient / cumulative_sufficient / query_coverage_ok）：
+    结果是否已经够用、可以不再等慢源
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def apply_query_rewrite(query: str) -> tuple[str, dict | None]:
+    """统一查询改写逻辑，返回 (改写后的查询, 改写结果字典)。
+
+    改写失败时静默返回原查询，不影响搜索流程。
+    """
+    try:
+        from query_rewriter import rewrite_query as do_rewrite
+        result = do_rewrite(query)
+        if result["rewritten"] and result["confidence"] >= 0.7:
+            return result["rewritten"], result
+    except ImportError:
+        pass  # query_rewriter 模块不可用，使用原查询
+    except Exception as e:
+        import logging
+        logging.getLogger("unified_search").debug(f"查询改写跳过: {type(e).__name__}")
+    return query, None
+
+
+def results_sufficient(
+    results: list[dict[str, Any]],
+    mode: str = "auto",
+    min_results: int | None = None,
+    query: str = "",
+) -> bool:
+    return _sufficient_internal(results, mode, min_results, query)
+
+
+def cumulative_sufficient(raw_results: dict[str, list[dict[str, Any]]],
+                          mode: str = "auto",
+                          min_results: int | None = None,
+                          query: str = "") -> bool:
+    """跨引擎累计结果是否已够（wave-2 提前终止判定）。
+
+    与 results_sufficient 同阈值，但把 raw_results 里所有已完成的
+    引擎结果合并成一条列表再判，避免单一引擎不足时重复等待慢源。
+    壳链不算「够数」的口径在 _sufficient_internal 统一定义
+    （2026-10-11 热榜实测，判定与下游 serp_guard 过滤对齐）。
+    """
+    merged: list[dict[str, Any]] = []
+    for res in raw_results.values():
+        if not res:
+            continue
+        merged.extend(
+            r for r in res if isinstance(r, dict) and "error" not in r
+        )
+    return _sufficient_internal(merged, mode, min_results, query)
+
+
+def is_query_echo(results: list[dict[str, Any]], query: str) -> bool:
+    """这批结果是否是「查询词回声」——上游把整句当单词去查，返回查询中
+    **某一个词**的词典释义/同主题页。
+
+    2026-10-17 实锤：「keyboard switch lube service 2026」全批命中
+    "Online Virtual Keyboard"、「best mechanical keyboard for typing 2026」
+    全批命中 "BEST 的词典释义"——整批标题都在回声**同一个**查询词。
+
+    判据只看标题：snippet 里的功能词（for/the/and…）会把单条覆盖抬到 2，
+    判据即被击穿——实测 "Shop Best Buy for electronics" 仅因含 for 就
+    cov=2，而标题侧仍只有 best 一个词。标题是结果的核心，功能词出现率低。
+
+    只判整批、不判单条：长尾查询本就有弱命中，单条覆盖 1 词完全正常；
+    整批都只覆盖同一个词才是「上游降级」的信号。零网络成本（只读文本与
+    查询词元），可在早停（rerank 之前，rel 尚不存在）与输出层（恢复链）
+    复用——这与 cache_guard.is_degraded_results 的「整批退化」同构，区别是
+    那里读 rerank 的 relevance，这里读词面。
+    """
+    if not query or not query.strip() or not results:
+        return False
+    try:
+        from tfidf_router import tokenize
+    except ImportError:
+        return False  # 分词不可用不判（fail-open）
+    q_set = set(tokenize(query))
+    # 查询词 <4 不判：短查询的结果标题天然只命中一两个词，拦它即误伤（实测
+    # 「OpenAI MCP specification」的专利/论文结果只命中 specification 一个词，
+    # 却被判回声 → 恢复链误触发，白打两个引擎还把金标输出撑大）。
+    if len(q_set) < 4:
+        return False
+    # 至少 3 条结果才判：一两条短标题完全可能是正确答案（实测
+    # 「what is the capital of France」→ "Paris capital" 只命中 capital 一个词，
+    # 但那就是答案）。
+    if len(results) < 3:
+        return False
+    covered_terms: set[str] = set()
+    for r in results:
+        if isinstance(r, dict):
+            covered_terms |= (q_set & set(tokenize(r.get("title") or "")))
+    # 判据取「整批标题覆盖的**不同**查询词数恰好为 1」：
+    #   0 个 = 完全无关，归 covered 判据管（算进来会让离线 mock 误触发恢复链，
+    #         实测 test_funnel 的 called 从 2 涨到 4）；
+    #   1 个 = 整批都在回声同一个词（"Online Virtual Keyboard" 之类）；
+    #   ≥2 个 = 结果确实在回答查询的不同侧面，不是回声。
+    return len(covered_terms) == 1
+
+
+def query_coverage_ok(results: list[dict[str, Any]], query: str) -> bool:
+    """查询-结果词面覆盖守卫（fast/auto 早停质量门槛）。
+
+    2026-09-02 实测教训：fast 早停原只看计数+snippet，首引擎上游波动时
+    返回 5 条高计数但不相关结果（查询 Crawl4AI 却返回无关 MDN 页），
+    早停吞掉 wave-2，单引擎垃圾即成最终答案。本守卫只在极端场景（多数
+    结果与查询零词面交集）拒绝早停，让既有 wave-2/串行次引擎补跑——
+    只影响「是否停」，不丢弃任何结果，最坏代价是多跑一个引擎。
+
+    CJK 说明：中文查询分词为单字，覆盖判定在字符级——结果与查询零字符
+    交集同样会被拒早停（弱信号但非空）；同义词改写场景（如「电脑」vs
+    「计算机」）可能多跑一个引擎，属可接受代价：宁可多一次调用，不放走
+    单引擎垃圾。
+    """
+    if not query or not query.strip():
+        return True
+    try:
+        from tfidf_router import tokenize
+    except ImportError:
+        return True  # 分词不可用不设卡（fail-open）
+    q_set = set(tokenize(query))
+    if not q_set:
+        return True
+    # 同构垃圾检测：结构性包索引被域外查询误抢时，会把查询切词后逐词
+    # 返回单 token 包名（title≈1 词、URL=/project/<word>），词面覆盖因此
+    # 虚高（垃圾包名恰好是查询关键词）→ 覆盖守卫被骗过、垃圾即成最终
+    # 答案。多数结果标题 ≤1 token 且查询有 ≥3 token 时，视为索引噪声，
+    # 拒绝早停、放行串行次引擎补跑。
+    single_token_titles = sum(
+        1 for r in results if len(set(tokenize(r.get("title") or ""))) <= 1
+    )
+    if len(q_set) >= 3 and single_token_titles * 2 > len(results):
+        return False
+    if is_query_echo(results, query):
+        return False
+    covered = 0
+    for r in results:
+        text = f"{r.get('title') or ''} {r.get('snippet') or ''}"
+        if q_set & set(tokenize(text)):
+            covered += 1
+    return covered >= max(1, (len(results) + 1) // 2)
+
+
+def result_relevance(query: str, results: list[dict[str, Any]],
+                     top_k: int = 3) -> float | None:
+    """单个引擎这次结果的相关度代理 ∈ [0,1]；**拿不到信号时返回 None**。
+
+    用途：给 `adaptive` 学习器回写质量维度（见 adaptive.quality_factor），
+    让引擎排序不再只学「快慢/成败」而能学「好坏」。零网络成本——只读结果
+    文本与查询词元。
+
+    与 `query_coverage_ok` 的区别是本末颠倒：那个问「够不够好到可以停」
+    （二元判定，判据保守到宁可多跑一个引擎），这个问「有多好」
+    （连续量，用于跨引擎、跨时间比较）。两者共用词面覆盖的直觉，但口径必须
+    分开：早停判据要求高敏感度（漏放=放出垃圾），质量分要求可比较
+    （量纲稳定，否则引擎之间的分数不可比）。
+
+    取「前 top_k 条里每条对查询的覆盖率，再取均值」，而不是全量平均：
+    一条半相关文档不该替整个结果集背书，反之亦然。
+
+    返回 None 而非 0.0 是关键：0.0 在自适应评分里是「测过了、很差」，
+    None 才是「本次没测」。两者混同会让「无法判定」把引擎打落
+    （`adaptive.record` 负责把 None 落成不参与判定的 0.0）。
+    """
+    if not query or not query.strip():
+        return None
+    try:
+        from tfidf_router import tokenize
+    except ImportError:
+        return None  # 分词不可用 → 无信号（fail-open，不影响主路径）
+    q_set = set(tokenize(query))
+    if not q_set:
+        return None  # 查询无内容词元（纯符号）→ 无法判定
+    scored: list[float] = []
+    for r in results:
+        if not isinstance(r, dict) or "error" in r:
+            continue
+        text = f"{r.get('title') or ''} {r.get('snippet') or ''}"
+        d_set = set(tokenize(text))
+        if not d_set:
+            scored.append(0.0)  # 有结果却零词元：结构化源常见，计为不相关
+            continue
+        scored.append(len(q_set & d_set) / len(q_set))
+        if len(scored) >= top_k:
+            break
+    if not scored:
+        return None  # 无有效结果（全部 error / 空列表）→ 无信号
+    return sum(scored) / len(scored)
+
+
+def score_clarity_ok(results: list[dict[str, Any]]) -> bool:
+    """无标注 QPP 信号（2026-09-16）：结果分平坦且数量仅达下限时拒绝早停。
+
+    方法论：无 relevance judgments 的查询性能预测（QPP）——NQC/Clarity 一族
+    的共同直觉是「分数分布越尖锐（有明确赢家），查询表现越可预期；分布
+    平坦说明检索器对查询拿不准」。这里取最保守的判据：
+
+      - 只在**计数恰好等于下限**时参与判定（_sufficient_internal 传入
+        barely）：结果富余本身就是信心，不必再问分数分布；
+      - 至少 2 个数值 score 才参与（单条无从谈分布），否则 fail-open
+        （放行早停）——下限取 2 而非 3 是刻意的：fast 档计数下限就是 2，
+        取 3 会让 fast 档永远够不着信号；两条全等的占位分与三条同样可疑；
+      - 全体 score 完全相等（std=0，结构化源常见的占位分）视为最平坦。
+
+    「拒绝早停」的代价实打实是多跑一个引擎（成本语义见 engine_dispatch
+    wave-1 注释），所以阈值取最极端的平坦而非「偏平坦」；宁可多一次调用，
+    不放走「字段齐全、计数达标、分数无区分度」的单引擎垃圾（2026-09-02
+    实测教训的分数维度补丁，与词面覆盖守卫互补——那个管文本，这个管排序）。
+    """
+    scores: list[float] = []
+    for r in results:
+        try:
+            v = r.get("score")
+            if v is None:
+                continue
+            v = float(v)
+        except (TypeError, ValueError):
+            continue
+        scores.append(v)
+    if len(scores) < 2:
+        return True  # 信号不可用：fail-open
+    mean = sum(scores) / len(scores)
+    if mean <= 0:
+        return True
+    var = sum((s - mean) ** 2 for s in scores) / len(scores)
+    std = var ** 0.5
+    return (std / mean) > 0.02  # 变异系数 ≤2% 视为平坦（实测占位分全等=0）
+
+
+def _sufficient_internal(
+    results: list[dict[str, Any]],
+    mode: str,
+    min_results: int | None,
+    query: str = "",
+) -> bool:
+    """渐进检索 early-stop：结果是否已够用。
+
+    轻量启发式（不依赖网络/LLM）：
+      - 默认 auto：至少 3 条非错误 + 2 条有 snippet
+      - 默认 fast：至少 2 条 + 1 个 snippet
+      - min_results：域配置覆盖（答案型源 1 条快照即够用，计数语义不动）
+      - 通用路径叠加词面覆盖守卫（query_coverage_ok）：结果与查询几乎
+        无交集时不许早停
+      - 两条路径都叠加平坦分守卫（score_clarity_ok）：计数恰好压线且
+        分数无区分度时不许早停
+
+    壳链不算「够数」（2026-10-11 热榜实测）：early-stop 的两条调用
+    路径（wave-1 的 _wave1_stop → results_sufficient、wave-2 的
+    cumulative_sufficient）都在此判定，与下游 serp_guard 过滤共用
+    同一口径。此前壳链被算作有效结果——wave-1「先合格者赢」时
+    baidu_hot 交 10 条 baidu.com/s?wd= 壳即触发早停、同域真榜单
+    引擎（toutiao_hot）被 cancelled，壳随后被 serp_guard 整批过滤
+    清零、merged 归零触发 2.3s 恢复链。判定与过滤对齐后：壳从一
+    开始就不算「够」，早停只在交付真结果的引擎上触发。无 url 的
+    结构化快照（行情/天气）不受影响——壳判定只看 URL。
+    """
+    try:
+        from serp_guard import drop_shell_urls as _drop_shells
+    except ImportError:
+        _drop_shells = None  # 守卫不可用 → 壳不过滤（fail-open，与模块容错一致）
+    goods: list[dict[str, Any]] = [
+        r for r in results if isinstance(r, dict) and "error" not in r]
+    if _drop_shells is not None:
+        # 壳过滤唯一出口（serp_guard.drop_shell_urls）：与下游漏斗过滤、
+        # 恢复链 L0/L3 收口共用同一判定，口径不再各自内联漂移。
+        goods = _drop_shells(goods)
+    if not goods:
+        return False
+    with_snippet = sum(
+        1 for r in goods
+        if (r.get("snippet") or r.get("title") or "").strip()
+    )
+    if min_results is not None:
+        try:
+            need = max(1, int(min_results))
+        except (TypeError, ValueError):
+            need = 1
+        # 答案型 1 条要求有可展示正文；≥3 条时至少 2 条有 snippet
+        need_snip = 1 if need <= 2 else max(2, need - 1)
+        ok = len(goods) >= need and with_snippet >= min(need_snip, len(goods))
+        # 词面覆盖守卫不适用于答案型（1 条快照无「多数覆盖」可言），
+        # 平坦分守卫适用：占位分快照同样可能是垃圾
+        return ok and (len(goods) > need or score_clarity_ok(goods))
+    threshold = 2 if mode == "fast" else 3
+    ok = len(goods) >= threshold and with_snippet >= (1 if mode == "fast" else 2)
+    return (ok
+            and query_coverage_ok(goods, query)
+            and (len(goods) > threshold or score_clarity_ok(goods)))

package/scripts/query_templates.py

@@ -0,0 +1,167 @@
+#!/usr/bin/env python3
+"""query_templates.py — 查询模板注册表：加载、合并、展开（纯逻辑）。
+
+职责单一：把 YAML 注册表读成内存结构，按 id 取模板，把模板 + 追加词展开成
+最终查询串。**不碰 IO 输出面、不 spawn 子进程**——那些在 template_cli.py
+（分工同 citations.py / cite_cli.py）。
+
+两个注册表合并（这是「未知使用需求」的普适性所在）：
+  1. 随包注册表  references/query-templates.yaml（随 argo 升级更新，勿手改）
+  2. 用户注册表  $XDG_CONFIG_HOME/argo/query-templates.yaml（缺省 ~/.config/argo/）
+     或 ARGO_TEMPLATES_FILE 指定的路径
+用户表按 id 合并：新 id 追加，同名 id 覆盖随包条目；`disabled: true` 停用随包条目。
+于是新增一个领域只要加几行 YAML，零代码、零改仓。
+
+为什么注册表是数据而非代码：模板的本质是「命名查询模式」——一个纯数据问题。
+放 YAML 才能让用户零门槛扩展、让 git 管版本、让 --list 自动派生。
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from pathlib import Path
+from typing import Any
+
+SKILL_DIR = Path(__file__).resolve().parent.parent
+SHIPPED_PATH = SKILL_DIR / "references" / "query-templates.yaml"
+
+# command 白名单：模板只能转发到这些 argo 子命令。用户注册表可写，若不设白名单，
+# 一个被篡改/误写的注册表就能借 `argo template` 转发到任意命令——模板是数据，
+# 不该有执行任意命令的能力。
+COMMANDS = ("search", "x-search")
+DEFAULT_COMMAND = "search"
+
+_ID_RE = re.compile(r"^[a-z0-9][a-z0-9_]*$")
+
+
+class TemplateError(Exception):
+    """注册表缺失/损坏、id 未知、字段非法。"""
+
+
+def user_registry_path() -> Path | None:
+    """用户注册表路径（存在才返回）。优先级：ARGO_TEMPLATES_FILE > 平台配置根 > ~/.config。
+
+    与 engine_env._envfile_paths 同源思路（复用 _platform_config_root，避免
+    「Windows 取哪个目录」这类平台逻辑在本模块再写一份）。
+    """
+    explicit = os.environ.get("ARGO_TEMPLATES_FILE", "").strip()
+    if explicit:
+        return Path(os.path.expanduser(explicit))
+    cands: list[Path] = []
+    try:
+        from engine_env import _platform_config_root
+        root = _platform_config_root()
+        if root is not None:
+            cands.append(root / "argo" / "query-templates.yaml")
+    except Exception:
+        pass
+    cands.append(Path(os.path.expanduser("~/.config/argo/query-templates.yaml")))
+    for p in cands:
+        if p.exists():
+            return p
+    return None
+
+
+def _read_yaml(path: Path) -> dict[str, Any]:
+    from yaml_load import load as _yaml_load
+    try:
+        data = _yaml_load(path)
+    except FileNotFoundError:
+        raise TemplateError(f"注册表不存在: {path}")
+    except Exception as e:  # yaml.YAMLError 等
+        raise TemplateError(f"注册表解析失败 {path}: {e}")
+    if not isinstance(data, dict):
+        raise TemplateError(f"注册表顶层必须是映射: {path}")
+    return data
+
+
+def _normalize(entry: Any, tid: str, src: str) -> dict[str, Any]:
+    """校验并规范化单条模板。返回 None 之外的 dict。"""
+    if not isinstance(entry, dict):
+        raise TemplateError(f"{src}: 模板 {tid} 必须是映射")
+    if entry.get("disabled"):
+        return {"__disabled__": True}
+    query = entry.get("query")
+    if not isinstance(query, str) or not query.strip():
+        raise TemplateError(f"{src}: 模板 {tid} 缺非空 query")
+    command = entry.get("command") or DEFAULT_COMMAND
+    if command not in COMMANDS:
+        raise TemplateError(
+            f"{src}: 模板 {tid} 的 command「{command}」不在白名单 {COMMANDS}")
+    return {
+        "id": tid,
+        "description": str(entry.get("description") or "").strip(),
+        "category": str(entry.get("category") or "未分组").strip(),
+        "command": command,
+        "query": query.strip(),
+        "tags": [str(t) for t in (entry.get("tags") or []) if str(t).strip()],
+        "note": str(entry.get("note") or "").strip(),
+        "source": src,
+    }
+
+
+def _merge_into(registry: dict[str, dict], data: dict[str, Any], src: str) -> None:
+    templates = data.get("templates")
+    if templates is None:
+        return
+    if not isinstance(templates, dict):
+        raise TemplateError(f"{src}: templates 必须是映射")
+    for tid, entry in templates.items():
+        tid = str(tid)
+        if not _ID_RE.match(tid):
+            raise TemplateError(f"{src}: 模板 id 非法（须 [a-z0-9_]）: {tid!r}")
+        norm = _normalize(entry, tid, src)
+        if norm.get("__disabled__"):
+            registry.pop(tid, None)   # 用户表可用 disabled 停用随包模板
+            continue
+        registry[tid] = norm
+
+
+def load_templates(*, include_user: bool = True,
+                   shipped: Path | None = None,
+                   user: Path | None = None) -> dict[str, dict]:
+    """加载并合并注册表。返回 {id: 模板}；缺失随包表按空处理（不抛）。
+
+    include_user=False 或显式传 user=None 且不查环境，用于测试与「只看随包」场景。
+    """
+    registry: dict[str, dict] = {}
+    ship = shipped if shipped is not None else SHIPPED_PATH
+    if ship.exists():
+        _merge_into(registry, _read_yaml(ship), str(ship))
+    if include_user:
+        up = user if user is not None else user_registry_path()
+        if up is not None and up.exists() and up != ship:
+            _merge_into(registry, _read_yaml(up), str(up))
+    return registry
+
+
+def list_templates(registry: dict[str, dict]) -> list[dict]:
+    """按 (category, id) 排序的模板清单（--list 用）。"""
+    return sorted(registry.values(),
+                  key=lambda t: (t.get("category", ""), t.get("id", "")))
+
+
+def get_template(registry: dict[str, dict], tid: str) -> dict:
+    """按 id 取模板；未知 id 抛 TemplateError（带 did-you-mean 建议）。"""
+    t = registry.get(tid)
+    if t is not None:
+        return t
+    import difflib
+    near = difflib.get_close_matches(tid, list(registry), n=3, cutoff=0.4)
+    hint = f"（最接近: {', '.join(near)}）" if near else ""
+    raise TemplateError(f"未知模板「{tid}」{hint} —— 全部模板见 argo template --list")
+
+
+def expand(template: dict, adds: list[str] | None = None) -> str:
+    """模板 query + 追加词 → 最终查询串。
+
+    追加词以空格拼接（X 语法里空格即 AND）。空追加词/空白被丢弃，不产生
+    多余空格。这是模板「可组合」的实现：模板给基线，--add 给具体对象。
+    """
+    parts = [template.get("query", "")]
+    for a in adds or []:
+        a = str(a).strip()
+        if a:
+            parts.append(a)
+    return " ".join(p for p in parts if p)