argo-search 2.9.7 → 2.9.9

package/scripts/semantic_evidence.py

@@ -43,6 +43,31 @@ logger = logging.getLogger("unified_search.semantic_evidence")
 
 DEFAULT_ENDPOINT = "https://classifier.dev"
 DEFAULT_TIMEOUT_S = 5.0
+# 未声明 transport 时的默认通道。jev = TypeSafe System One（当前唯一可用）；
+# classifier.dev 的匿名路径 2026-10-22 起回 403 proxy_requires_payment。
+DEFAULT_TRANSPORT = "jev"
+
+# ── JEV / System One 通道（TypeSafe）──────────────────────────────────────
+# 官方 API：POST https://api.typesafe.ai/v1/systemone，Bearer 鉴权
+# （docs.typesafe.ai/api/system-one）。与 classifier.dev 的 /v1/classify 是
+# **两种形状**：那边一次发 N 条文本 + 一组标签；这边一次发一个 state + 若干
+# 具名问题，每题独立作答（文档原话：questions are evaluated in parallel and
+# in isolation）。所以接过来要做的是形状转换，不是换个 URL。
+DEFAULT_JEV_ENDPOINT = "https://api.typesafe.ai/v1/systemone"
+DEFAULT_JEV_MODEL = "jev-latest"
+# key 候选链：argo 推荐名在前；TYPESAFE_API_KEY 是官方 SDK 与 JEV 插件
+# （dsh-verbatim-compaction）用的名字，照文档配的人直接可用。
+JEV_KEY_ENV = ("ARGO_JEV_API_KEY", "TYPESAFE_API_KEY")
+# state 超过这个长度就带长上下文头。实测（2026-10-22 本机）：
+#   不带 TypeSafe-Danger-Zone-Long-Context：32K tokens 通过（32350）、
+#     40K 中文字（≈40K tokens）回 `max_tokens_exceeded`（400）
+#   带上：40K 字（40358 tokens）与 80K 字（80358 tokens）均通过
+# 24000 字是保守拐点（正常路径不带头也稳），不是实测上限。
+JEV_LONG_CONTEXT_CHARS = 24000
+# 并发上限。官方 cookbook（classifying_rag_passages）取 4，理由是端点限流；
+# 429/529 要求指数退避，所以不铺大。
+JEV_MAX_WORKERS = 4
+
 # conf ≥ 0.7 才给结论：低于此值的判定不可信（B 实测 4 个严格错误全部 ≤0.67）
 SUPPORT_THRESHOLD = 0.7
 # 单条文本上限：核验链路取回的正文 ≤8000 字，再高无收益（A 实测 400→7798 字
@@ -100,20 +125,167 @@ def _timeout() -> float:
         return DEFAULT_TIMEOUT_S
 
 
+def jev_api_key() -> str:
+    """JEV（TypeSafe）key：os.environ 优先，~/.config/argo/env 热读保底。"""
+    try:
+        from engine_env import get_env
+        return (get_env(list(JEV_KEY_ENV)) or "").strip()
+    except Exception:  # pragma: no cover - 环境层不可用时不冒险
+        import os
+        for _n in JEV_KEY_ENV:
+            _v = (os.environ.get(_n) or "").strip()
+            if _v:
+                return _v
+        return ""
+
+
+def _transport() -> str:
+    """通道选择：`jev`（TypeSafe System One）或 `classify`（classifier.dev）。
+
+    **纯配置驱动，不做「按键就绪自动选」**。初版按 jev_api_key() 是否就绪自动
+    选，结果是通道取决于本机 ~/.config/argo/env 里有没有那把 key——同一份代码
+    在开发机与 CI 上走不同分支，既有测试在开发机上会静默改道（实测：写进 key
+    后 test_semantic_evidence 的 5 条 HttpClient 桩里 1 条改走 JEV 路径而挂）。
+    机器状态不该改变代码路径。
+
+    未声明时的默认是 jev：classifier.dev 的匿名路径 2026-10-22 起回 403
+    proxy_requires_payment，JEV 是当前可用的那条。
+    """
+    declared = str(_config().get("transport") or "").strip().lower()
+    return declared if declared in ("jev", "classify") else DEFAULT_TRANSPORT
+
+
+def _jev_endpoint() -> str:
+    """JEV 端点：**独立于 classify 通道的 endpoint 字段**。
+
+    不共用是刻意的坑修：config.yaml 里 `endpoint` 长期写的是
+    https://classifier.dev，JEV 通道若读同一个字段，就会把 System One 的
+    请求体发到 classifier.dev，拿回「Invalid API key / Create a workspace
+    key at /app/keys」这种指向完全错误方向的 401（2026-10-22 实测踩中）。
+    每个通道自带端点，杜绝「换 transport 忘了换 endpoint」。
+    """
+    return str(_config().get("jev_endpoint") or DEFAULT_JEV_ENDPOINT).rstrip("/")
+
+
+def _jev_model() -> str:
+    return str(_config().get("jev_model") or _config().get("model")
+               or DEFAULT_JEV_MODEL)
+
+
+def _jev_post(path_state: Any, questions: dict[str, Any], *,
+              timeout: float) -> Optional[dict[str, Any]]:
+    """一次 System One 请求；失败返回 None（fail-open 的全部出口都在这里）。"""
+    key = jev_api_key()
+    if not key:
+        logger.debug("JEV key 未配置（%s），语义层跳过", " / ".join(JEV_KEY_ENV))
+        return None
+    body = {
+        "model": _jev_model(),
+        "state": path_state,
+        "questions": questions,
+    }
+    # Content-Type 必须显式给：HttpClient.post 会把 dict 做 json.dumps，
+    # 但**从不设 Content-Type**（头只来自浏览器 UA 模板 + extra_headers）。
+    # 缺它时 FastAPI 侧把 body 当字符串，回
+    #   422 {"loc":["body"],"msg":"Input should be a valid dictionary…"}
+    # ——报错指向「请求体不是对象」，而真因是少了一个头（2026-10-22 实测踩中）。
+    headers = {"Authorization": f"Bearer {key}",
+               "Content-Type": "application/json"}
+    # 长上下文要显式带头，否则 state 一过 32K tokens 就 400 max_tokens_exceeded
+    if len(json.dumps(path_state, ensure_ascii=False)) > JEV_LONG_CONTEXT_CHARS:
+        headers["TypeSafe-Danger-Zone-Long-Context"] = "true"
+    try:
+        from http_client import HttpClient
+        resp = HttpClient(timeout=timeout, max_retries=1, jitter=False).post(
+            _jev_endpoint(), body, extra_headers=headers)
+        if resp.get("status") != 200:
+            logger.debug("JEV 非 200: %s %s", resp.get("status"),
+                         str(resp.get("text") or resp.get("error") or "")[:200])
+            return None
+        return json.loads(resp.get("text") or "{}")
+    except Exception as e:  # fail-open：语义层任何问题都不阻断核验
+        logger.debug("JEV 请求失败: %s", type(e).__name__)
+        return None
+
+
+def _jev_choice(text: str, labels: tuple[str, ...] | list[str],
+                instructions: str | None, timeout: float
+                ) -> Optional[dict[str, Any]]:
+    """单条文本 → 一个 Choice 问题。
+
+    **每条一个请求**，不是「多段一个 state、每段一问」。理由在官方文档里：
+    jaggedness 那篇明写「state 里塞与决策无关的细节会降低准确率（context
+    rot）」，而判第 i 段时其余各段就是无关细节；cookbook 的
+    classifying_rag_passages 也是「One request per passage」。（我们试过 3 段
+    合一，结果全对，但样本太小，不拿它赌准确率。）
+    """
+    out = _jev_post(text, {
+        "cls": {
+            "type": "choice",
+            "instructions": instructions or "Classify the state into one of the criteria.",
+            # criteria 的**值**是描述：jaggedness 说 instructions 与 criteria
+            # 不一致时模型会困惑，所以两边用同一句话，不给它两个版本。
+            "criteria": {str(lab): str(lab) for lab in labels},
+        },
+    }, timeout=timeout)
+    if not isinstance(out, dict):
+        return None
+    ans = (out.get("answers") or {}).get("cls")
+    if not isinstance(ans, dict) or not ans.get("choice"):
+        if isinstance(ans, dict):
+            logger.debug("JEV 答案缺 choice: %s", str(ans)[:120])
+        return None
+    return {
+        "label": str(ans.get("choice")),
+        "confidence": ans.get("confidence"),
+        "scores": ans.get("probabilities"),
+    }
+
+
+def _classify_jev(texts: list[str], labels: tuple[str, ...] | list[str], *,
+                  instructions: str | None, keep: list[tuple[int, str]],
+                  timeout: float) -> Optional[list[dict[str, Any]]]:
+    """JEV 通道：每条文本一个请求，并发 4。
+
+    任一条失败就在该位留 None（与 classifier.dev 通道「整批失败即 None」
+    不同）：一次核验有几条正文，坏一条不该把其余判定的价值也丢掉。全部失败
+    时仍返回 None，调用方行为与未开启时一致。
+    """
+    from concurrent.futures import ThreadPoolExecutor
+    texts_kept = [t[:MAX_TEXT_CHARS] for _i, t in keep]
+    with ThreadPoolExecutor(max_workers=min(JEV_MAX_WORKERS, len(texts_kept))) as pool:
+        results = list(pool.map(
+            lambda t: _jev_choice(t, labels, instructions, timeout), texts_kept))
+    if not any(r for r in results):
+        return None
+    out: list[Optional[dict[str, Any]]] = [None] * len(texts)
+    for (idx, _t), r in zip(keep, results):
+        if isinstance(r, dict):
+            out[idx] = r
+    return out  # type: ignore[return-value]
+
+
 def classify(texts: list[str], labels: tuple[str, ...] | list[str], *,
              instructions: str | None = None,
              timeout: float | None = None,
              tier: str | None = None) -> Optional[list[dict[str, Any]]]:
-    """一次批量分类（≤1000 条）。任何异常/非 200/条数不匹配 → None。
+    """一次批量分类。任何异常/非 200/条数不匹配 → None。
 
     返回按输入顺序排列的 [{label, confidence, scores}]；调用方负责判定阈值。
     空文本会被过滤后再发（空串会让整批 400），返回列表与输入等长、空缺位为 None。
+
+    两个通道的实现分居 _classify_jev（TypeSafe，每条一请求）与下方内联的
+    classifier.dev 路径（一次发 N 条）；开关判定见 _transport。
     """
     if not texts or len(labels) < 2:
         return None
     keep = [(i, t) for i, t in enumerate(texts) if (t or "").strip()]
     if not keep:
         return None
+    to = timeout or _timeout()
+    if _transport() == "jev":
+        return _classify_jev(texts, labels, instructions=instructions,
+                             keep=keep, timeout=to)
     body: dict[str, Any] = {
         "labels": [str(x) for x in labels],
         "inputs": [t[:MAX_TEXT_CHARS] for _i, t in keep],
@@ -123,8 +295,12 @@ def classify(texts: list[str], labels: tuple[str, ...] | list[str], *,
         body["instructions"] = instructions
     try:
         from http_client import HttpClient
-        resp = HttpClient(timeout=timeout or _timeout(), max_retries=1,
-                          jitter=False).post(_endpoint(), body)
+        # Content-Type 同 JEV 通道：HttpClient.post 不设它，缺了会被服务端
+        # 当字符串解析。这条路径此前只在 403（匿名要付费 key）处止步，没走到
+        # body 校验，所以同一个坑没暴露——配了有效 workspace key 就会现形。
+        resp = HttpClient(timeout=to, max_retries=1, jitter=False).post(
+            _endpoint(), body,
+            extra_headers={"Content-Type": "application/json"})
         if resp.get("status") != 200:
             logger.debug(f"语义分类非 200: {resp.get('status')} {resp.get('error')}")
             return None

package/scripts/serp_guard.py

@@ -1,11 +1,12 @@
 #!/usr/bin/env python3
-"""serp_guard — HTML SERP 垃圾结果守卫（判定规则单点）。
+"""serp_guard — SERP / 模糊搜索结果的垃圾结果守卫（判定规则单点）。
 
 事故背景（dsh-free-search issue #38/#35 同款事故，argo 的 local_* 引擎同样
 暴露）：html 引擎解析的是无 API 的网页 SERP，上游偶发把缓存 SERP / 与查询
-完全无关的结果页当正常页返回，解析层照常抽出标题摘要，垃圾条目静默混进
-聚合，调用方把「答非所问」当成「网上没有」——失败伪装成功是红线，这类
-混入是它的隐形变体。
+完全无关的结果页当正常页返回；模糊搜索 API（people_daily 的 isFuzzy=True）
+匹配不到时则回整页默认 feed。两种形态都是「答非所问但看起来正常」，解析层
+照常抽出标题摘要，垃圾条目静默混进聚合，调用方把「答非所问」当成「网上
+没有」——失败伪装成功是红线，这类混入是它的隐形变体。
 
 裁决口径（全部量化，无模糊地带）：
 
@@ -16,7 +17,13 @@
   2. results 只取前 5 条；每条取 title+snippet。URL 不参与：缓存/跳转
      链接的 URL 常回显 query 参数（uddg=、q=），会正好把垃圾页放行，
      标题+摘要才是「这页在答什么」的信号。
-  3. 前 5 条全部与 query token 零交集 → 整页判垃圾（True）。
+  3. 前 5 条里没有任何一条覆盖 query token 的 20% → 整页判垃圾（True）。
+     只判「有没有一个词命中」不够：实测「2026年新能源汽车销量数据」经
+     local_bing 返回的五条全是 2026 年节假日/维基页面，只命中「2026」一个
+     数字 token，旧判据（有交集即放行）把整页垃圾放了过去，而核心词
+     「新能源汽车销量数据」全部缺席。覆盖率 1/9 远低于门槛。
+     中文查询在存在 CJK 二元组时**不把纯数字 token 计入分母**：年份是最
+     容易被无关页面顺带命中的词，不能拿它当相关性证据。
 
 为什么调用方对判垃圾应整页丢弃而不是过滤后返回幸存者：前 5 条全无关说明
 这一页整体答非所问（缓存页/错路由），幸存的一两条是同一页的噪声，过滤
@@ -43,6 +50,7 @@ from urllib.parse import urlparse
 _RUN_RE = re.compile(r"[\u4e00-\u9fff]+|[a-z0-9]+")
 _GUARD_WINDOW = 5      # 只看前 5 条：SERP 的「答非所问」看头部即可下结论
 _MIN_QUERY_TOKENS = 2  # query token 少于此数 → 无裁决权，恒不拦
+_MIN_COVERAGE = 0.2    # 单条结果至少要覆盖 20% 的 query token 才算「在答这题」
 _SWITCH_ENV = "ARGO_SERP_GUARD"
 
 
@@ -69,6 +77,20 @@ def _result_text(item: object) -> str:
     return f"{item.get('title') or ''} {item.get('snippet') or ''}"
 
 
+def _query_tokens(query: str) -> set[str]:
+    """query token；中文查询里纯数字不参与（年份不是相关性证据）。
+
+    有 CJK 二元组说明查询主体是中文短语，此时「2026」这类数字是最容易被
+    无关页面顺带命中的 token（节假日表、维基年表都带年份），留在分母里会
+    把覆盖率算高、把垃圾页放行。纯拉丁查询（如「2026 GDP」）没有这个问题，
+    数字是有信息的，照常保留。
+    """
+    tokens = _extract_tokens(query)
+    if any("\u4e00" <= ch <= "\u9fff" for tok in tokens for ch in tok):
+        tokens = {tok for tok in tokens if not tok.isdigit()}
+    return tokens
+
+
 def is_junk_serp(query: str, results: list[dict]) -> bool:
     """判一页 SERP 结果是否整体答非所问（口径见模块 docstring）。
 
@@ -77,7 +99,7 @@ def is_junk_serp(query: str, results: list[dict]) -> bool:
     """
     if not guard_enabled():
         return False
-    q_tokens = _extract_tokens(query if isinstance(query, str) else "")
+    q_tokens = _query_tokens(query if isinstance(query, str) else "")
     if len(q_tokens) < _MIN_QUERY_TOKENS:
         return False
     if not isinstance(results, list):
@@ -86,7 +108,8 @@ def is_junk_serp(query: str, results: list[dict]) -> bool:
     if not head:
         return False
     for item in head:
-        if _extract_tokens(_result_text(item)) & q_tokens:
+        hit = _extract_tokens(_result_text(item)) & q_tokens
+        if len(hit) / len(q_tokens) >= _MIN_COVERAGE:
             return False
     return True
 
@@ -226,3 +249,111 @@ def drop_shell_urls(results: list) -> list:
             continue
         kept.append(r)
     return kept
+
+
+# ── 内容农场与 AI 机翻垃圾站判定（2026-10-23）─────────────────────────────
+#
+# 依据 source_types_cn.json 的 content_farm_markers 与结构化特征模式，
+# 识别并拦截低质搬运镜像、机翻爬虫站及流水线批量 AI 假稿。
+
+_FARM_CONNECTORS = ("首先", "其次", "然后", "接下来", "最后", "综上所述")
+_FARM_AI_PHRASES = ("业内人士表示", "专家分析", "消费者认为", "看完这篇你就懂了",
+                    "看完你就懂了", "建议收藏", "综上所述")
+
+
+def is_content_farm(url: str = "", title: str = "", snippet: str = "") -> bool:
+    """判定某条目是否属于内容农场 / 机翻爬虫 / 批量流水线 AI 废话。
+
+    2026-10-23 接线前用 5 条正例 + 4 条边界标定，修正两处：
+      - 序数连接词单独出现**不判农场**：正常安装指南同样含「首先/其次/然后/
+        接下来/最后」（实测 5 个），旧判据 `hit_conn >= 4` 把它误杀了。现在
+        要求同时出现 ≥1 个 AI 套话（流水线稿的伴生特征）。
+      - 「自费 N 元实测」不再要求标题带「最新」：实测真实的虚假实测标题是
+        「自费5000元实测10款耳机」，不带「最新」，旧判据漏召。
+    """
+    if not guard_enabled():
+        return False
+    cfg = _load_cn_source_types()
+    host = _normalize_domain(url)
+    host_bare = host[4:] if host.startswith("www.") else host
+    farm_markers = tuple(cfg.get("content_farm_markers") or ())
+    if any(host_bare == m or host == m or host_bare.endswith("." + m) or host.endswith("." + m)
+           for m in farm_markers):
+        return True
+
+    low_url = (url or "").lower()
+    for pat in cfg.get("content_farm_url_patterns") or []:
+        if pat.lower() in low_url:
+            # 仅在非白名单顶级域下生效
+            if any(host.endswith(tld) for tld in (".top", ".xyz", ".site", ".cc", ".icu", ".work")):
+                return True
+
+    # 标题模式：虚假实测 / 利益诱饵 + 年份刷新
+    t = (title or "").strip()
+    if t:
+        if re.search(r"自费\s*\d+\s*元?实测", t):
+            return True
+        if re.search(r"\d{4}\s*最新推荐\s*\d+\s*款.*看完这篇你就懂了", t):
+            return True
+
+    # 摘要/正文模式：高度僵化的模板流水线
+    body = f"{t} {snippet or ''}".strip()
+    if body:
+        hit_conn = sum(1 for w in _FARM_CONNECTORS if w in body)
+        hit_ai = sum(1 for w in _FARM_AI_PHRASES if w in body)
+        if hit_conn >= 4 and hit_ai >= 1:
+            return True
+        if hit_ai >= 2 and hit_conn >= 1:
+            return True
+        if hit_ai >= 3:
+            return True
+
+    return False
+
+
+def is_unusable_url(url: str, title: str = "", snippet: str = "") -> bool:
+    """是否为不可作为信源引用的条目（SERP壳 或 确凿内容农场）。"""
+    if is_serp_or_jump_url(url):
+        return True
+    return is_content_farm(url, title, snippet)
+
+
+def filter_content_farms(results: list) -> list:
+    """过滤结果列表里的内容农场条目。"""
+    if not results or not guard_enabled():
+        return results or []
+    kept = []
+    for r in results:
+        if not isinstance(r, dict):
+            continue
+        u = r.get("url") or ""
+        t = r.get("title") or ""
+        s = r.get("snippet") or ""
+        if is_content_farm(u, t, s):
+            continue
+        kept.append(r)
+    return kept
+
+
+# ── 自适应放宽建议（2026-10-23 方案四）───────────────────────────────────
+
+_RELAX_TAIL_RE = re.compile(
+    r"(?:\b\d{4}年?(?:度)?|\b\d{1,2}月|"
+    r"最新|最全|详细|完整|全面|2020|2021|2022|2023|2024|2025|2026|"
+    r"知乎|贴吧|论坛|大全|汇总|排行榜|一览|数据|报告|统计|分析|趋势)"
+)
+
+
+def suggest_relaxed_query(query: str) -> str:
+    """针对 SERP 守卫击杀场景的自适应放宽查询（剥离过度约束的修饰与年份词）。"""
+    if not query or not isinstance(query, str):
+        return ""
+    q = _RELAX_TAIL_RE.sub(" ", query)
+    q = re.sub(r"(?<=\s)[年月](?=\s|$)|^([年月]\s+)", " ", q)
+    tokens = re.findall(r"[\u4e00-\u9fffA-Za-z0-9]+", q)
+    stopwords = {"的", "了", "呢", "吧", "请问", "怎么", "如何", "一下", "关于", "有关", "求", "谁知道",
+                 "the", "a", "an", "of", "for", "to", "how", "what"}
+    kept = [t for t in tokens if t.lower() not in stopwords]
+    relaxed = " ".join(kept).strip()
+    return relaxed or re.sub(r"\s+", " ", q).strip() or query
+

package/scripts/serp_kill_log.py

@@ -16,9 +16,11 @@ import threading
 from typing import Any
 
 # 判定规则与逃生门（ARGO_SERP_GUARD=0）在 serp_guard 单点；这里只登记
-# 哪些引擎接了守卫（解析上游 HTML 页最易被缓存 SERP 静默命中）。
+# 哪些引擎接了守卫（解析上游 HTML 页 / 模糊搜索接口最易被缓存 SERP 或
+# 默认 feed 静默命中）。people_daily 的 isFuzzy=True 在匹配不到时返回整页
+# 最新 feed（issue #18 复现 A），与 local_* 同属「答非所问但形态正常」。
 SERP_GUARD_ENGINES = frozenset({
-    "local_bing", "local_baidu", "local_sogou",
+    "local_bing", "local_baidu", "local_sogou", "people_daily",
 })
 
 # 进程级 + 锁。并发搜索下 drain 可能拿到彼此的条目——条目只含引擎名与
@@ -49,3 +51,24 @@ def drain_serp_guard_kills() -> list[dict[str, Any]]:
         kills = list(_KILLS)
         _KILLS.clear()
         return kills
+
+
+def clean_engine_lists(raw_results: dict[str, list[Any]],
+                       query: str) -> list[list[dict[str, Any]]]:
+    """raw_results{engine → results} → 去 error + SERP 守卫后的非空列表。
+
+    守卫必须同时覆盖缓存命中：per-engine 缓存走 engine_dispatch，不经过
+    engines.search，旧条目里的默认 feed/垃圾 SERP 会以 `ok-cached` 直接
+    返回（issue #18 的 14ms 复现）。融合前按引擎整页判定一次，缓存与网络
+    两条路径就收敛到同一口径；engines.search 里的守卫保留，因为它还要
+    阻止垃圾结果影响早停判定。
+    """
+    out: list[list[dict[str, Any]]] = []
+    for eng, res in (raw_results or {}).items():
+        goods = [r for r in (res or []) if isinstance(r, dict) and "error" not in r]
+        if not goods:
+            continue
+        goods = serp_guard_apply(eng, query, goods)
+        if goods:
+            out.append(goods)
+    return out

package/scripts/stats_cli.py

@@ -29,7 +29,19 @@ from search_attribution import aggregate_slow_engines  # noqa: E402
 def _query_summary(n: int) -> dict:
     rows = usage_log.tail("query", n)
     if not rows:
-        return {"samples": 0}
+        # 空日志（CI 全新 runner / 首次安装）也要给稳定的字段形状：夜间账本
+        # 直接读 avg_elapsed_ms，此前这里只回 {"samples": 0}，工作流每次
+        # 首次跑必炸 KeyError（issue #19）。指标用 None 而不是 0：0ms 会被
+        # 画成一条假曲线，None 才表示「没有样本」；调用方按 samples 判断。
+        return {
+            "samples": 0,
+            "result_rate": None,
+            "avg_elapsed_ms": None,
+            "recovered": 0,
+            "top_engines": [],
+            "slowest_engines": [],
+            "recent": [],
+        }
     counts = [r.get("count", 0) for r in rows]
     lat = [r.get("elapsed_ms") for r in rows if isinstance(r.get("elapsed_ms"), (int, float))]
     engines: Counter = Counter()