argo-search 1.0.1 → 2.9.7

package/scripts/jump_resolver.py

@@ -0,0 +1,235 @@
+"""jump_resolver — 不透明跳转壳解析（baidu/sogou/so /link 30x Location）。
+
+baidu/sogou 结果链接是 token 型跳转（与 DDG uddg 的可离线还原不同），聚合层
+P0（evidence.is_serp_or_jump_url）把这类 URL 整批滤掉——引擎不解析就永远
+0 条。本模块提供引擎级解析：单跳请求读 Location，失败返回空串由调用方丢弃
+（与 _unwrap_ddg_link 同哲学：不可核验的跳转壳不进结果）。
+
+两条落点形态（2026-10-06 实测补第二类）：
+  - 30x → 直接读 Location（baidu /link 之类）；
+  - 200 + 短页 → 页面里 window.location.replace("真实URL") 一类 JS 跳转。
+    搜狗对浏览器指纹客户端走这条（~234 字节小页）；对裸指纹/无会话客户端
+    302 弹回首页 Location: /，同源弹回一律不救回。
+
+第三类（2026-10-17 补）：Bing `ck/a?...&u=a1<base64url>` 把落点编码在参数里，
+**不需要任何网络请求**即可还原。此前 local_bing 的英文结果全被聚合层当
+搜索页滤掉（近 7 天 271 次调用、40.2% 空结果），而它本可零成本变成真链。
+"""
+
+from __future__ import annotations
+
+import base64
+import html as _html
+import re
+import urllib.parse
+import urllib.request
+from concurrent.futures import ThreadPoolExecutor
+
+JUMP_MARKERS = ("baidu.com/link", "baidu.com/baidu.php",
+                "sogou.com/link", "so.com/link",
+                "bing.com/ck/a")
+
+# 跳转页里的 JS/meta 落点（按优先级排列，先命中先赢）
+_JS_TARGET_RES = (
+    re.compile(r"window\.location\.replace\(\s*[\"']([^\"']+)[\"']\s*\)"),
+    re.compile(r"window\.location\.href\s*=\s*[\"']([^\"']+)[\"']"),
+    re.compile(r"location\.href\s*=\s*[\"']([^\"']+)[\"']"),
+    re.compile(r"location\.replace\(\s*[\"']([^\"']+)[\"']\s*\)"),
+    re.compile(r"""<meta[^>]+http-equiv=["']refresh["'][^>]+
+                content=["'][^"']*url=([^"';]+)""", re.IGNORECASE | re.VERBOSE),
+)
+
+# 200 响应只有落在这么短以内才当跳转页读：真实正文页不该进来白耗解析
+_MAX_REDIRECT_PAGE_BYTES = 8192
+
+# 批量解析的总量与并发上限：最坏墙钟 = ceil(cap/workers) × timeout
+_BATCH_CAP = 16
+_BATCH_WORKERS = 8
+
+
+def is_jump_url(u: str) -> bool:
+    return any(m in (u or "") for m in JUMP_MARKERS)
+
+
+# 可离线还原的落点参数：Bing 把目标 URL 放在 `u=a1<base64url>` 里。
+_BING_CK_HOSTS = ("bing.com", "www.bing.com", "cn.bing.com")
+
+
+def _unwrap_bing(url: str) -> str:
+    """Bing `ck/a` 跳转壳 → 真实 URL；不适用或解码失败返回空串。
+
+    `u` 的值是 `a1` + URL-safe base64（无 padding）。解码后必须是 http(s)
+    绝对地址，否则视为不可用（与 _is_usable_target 同哲学）。
+    """
+    try:
+        parsed = urllib.parse.urlsplit(url)
+        if parsed.netloc.lower() not in _BING_CK_HOSTS:
+            return ""
+        if not parsed.path.startswith("/ck/"):
+            return ""
+        raw = (urllib.parse.parse_qs(parsed.query).get("u") or [""])[0]
+        if not isinstance(raw, str) or not raw:
+            return ""
+        if raw.startswith("a1"):
+            raw = raw[2:]
+        padded = raw + "=" * (-len(raw) % 4)
+        target = base64.urlsafe_b64decode(padded.encode("ascii")).decode(
+            "utf-8", "replace").strip()
+        if not target.lower().startswith(("http://", "https://")):
+            return ""
+        # 同源弹回（目标又落回 bing 搜索页）不救回，避免把壳当答案。
+        if _is_usable_target(target, url):
+            return target
+        return ""
+    except Exception:
+        return ""
+
+
+def unwrap_offline_url(url: str) -> str:
+    """不需要网络的跳转壳还原；不适用/失败返回空串。
+
+    调用方可以在解析阶段无条件调用：非跳转 URL 直接返回空串，成本只有
+    `in` 判断。优先于任何 30x/Location 网络解析——Bing 的落点本来就写在
+    参数里，发请求纯属浪费。
+    """
+    u = url or ""
+    if not u:
+        return ""
+    if "bing.com/ck/" in u:
+        return _unwrap_bing(u)
+    return ""
+
+
+def _extract_js_target(body: str) -> str:
+    """从 JS/meta 跳转页提取落点；没有则空串。"""
+    for rx in _JS_TARGET_RES:
+        m = rx.search(body)
+        if m:
+            return _html.unescape(m.group(1).strip())
+    return ""
+
+
+def _is_usable_target(target: str, source_url: str) -> bool:
+    """落点基本可用性：非绝对 URL / 同源弹回（搜狗无会话时 Location: /，
+    经 urljoin 后是同 origin 的首页）不算可用落点。"""
+    if not target or not target.lower().startswith(("http://", "https://")):
+        return False
+    try:
+        src_origin = urllib.parse.urlsplit(source_url).netloc.lower()
+        tgt_origin = urllib.parse.urlsplit(target).netloc.lower()
+    except ValueError:
+        return False
+    return bool(tgt_origin) and tgt_origin != src_origin
+
+
+def _fetch_no_redirect(url: str, timeout: float,
+                       profiles: list[str]) -> tuple[int, dict[str, str], str]:
+    """请求且不跟随跳转，返回 (status, headers, body)。
+
+    curl_cffi 缺席时回落 urllib（只覆盖 302 场景，JS 页提取不了）。
+    网络层异常向上抛，由调用方统一 fail-open。
+    """
+    try:
+        from curl_cffi import requests as cr
+    except ImportError:
+        req = urllib.request.Request(url, headers={
+            "User-Agent": ("Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) "
+                           "AppleWebKit/537.36 (KHTML, like Gecko) "
+                           "Chrome/126.0.0.0 Safari/537.36"),
+        })
+        opener = urllib.request.build_opener(_NoRedirectHandler)
+        try:
+            with opener.open(req, timeout=timeout) as resp:
+                return resp.status, dict(resp.headers), ""
+        except urllib.error.HTTPError as e:
+            return e.code, dict(e.headers or {}), ""
+
+    proxies = None
+    try:
+        from net_proxy import resolve_proxy
+        purl = resolve_proxy(url)
+        if purl:
+            proxies = {"http": purl, "https": purl}
+    except Exception:
+        pass
+    last_err: Exception | None = None
+    for fp in profiles:
+        try:
+            resp = cr.get(url, timeout=timeout, allow_redirects=False,
+                          proxies=proxies, impersonate=fp)
+        except Exception as e:
+            last_err = e
+            continue
+        status = int(resp.status_code)
+        body = ""
+        if status == 200 and len(resp.content or b"") <= _MAX_REDIRECT_PAGE_BYTES:
+            body = resp.text or ""
+        return status, dict(resp.headers), body
+    if last_err is not None:
+        raise last_err
+    return 0, {}, ""
+
+
+class _NoRedirectHandler(urllib.request.HTTPRedirectHandler):
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        return None  # 拦下 3xx，把 Location 留给调用方
+
+
+def _resolve_core(url: str, timeout: float, profiles: list[str]) -> str:
+    """单条解析本体：30x 读 Location，200 短页提取 JS 落点；失败空串。"""
+    try:
+        status, headers, body = _fetch_no_redirect(url, timeout, profiles)
+    except Exception:
+        return ""
+    try:
+        if 300 <= status < 400:
+            target = urllib.parse.urljoin(url, (headers.get("Location") or "").strip())
+        elif status == 200 and body:
+            target = urllib.parse.urljoin(url, _extract_js_target(body))
+        else:
+            return ""
+    except Exception:
+        return ""
+    return target if _is_usable_target(target, url) else ""
+
+
+def resolve_jump_url(url: str, profiles: list[str] | None = None,
+                     timeout: float = 8.0) -> str:
+    """跳转壳 → 真实 URL（离线参数优先，其次单跳 Location / JS 落点）。
+
+    失败返回空串。离线可还原的壳不发网络请求。
+    """
+    offline = unwrap_offline_url(url)
+    if offline:
+        return offline
+    return _resolve_core(url, timeout, profiles or ["chrome131"])
+
+
+def resolve_jump_urls(urls: list[str], timeout: float = 2.5,
+                      profiles: list[str] | None = None,
+                      acceptable=None) -> dict[str, str]:
+    """批量并行解析，返回 {原URL: 落点URL}（只含解析成功的）。
+
+    `acceptable`：可选落点复核回调（主链传 serp_guard 判据——落点若仍是
+    搜索页/跳转页则不救回）；缺省只做同源弹回检查。超过 _BATCH_CAP 的
+    部分不解析（调用方按重要性排序给，前头的优先保住）；单条失败只丢
+    自己那条，不影响其余（fail-open）。
+    """
+    uniq = [u for u in dict.fromkeys(urls) if u][:_BATCH_CAP]
+    if not uniq:
+        return {}
+    profiles = profiles or ["chrome131"]
+    workers = max(1, min(_BATCH_WORKERS, len(uniq)))
+    with ThreadPoolExecutor(max_workers=workers,
+                            thread_name_prefix="jump-resolve") as ex:
+        targets = dict(zip(uniq, ex.map(lambda u: _resolve_core(u, timeout,
+                                                                profiles),
+                                        uniq)))
+    out: dict[str, str] = {}
+    for src, target in targets.items():
+        if not target:
+            continue
+        if acceptable is not None and not acceptable(target):
+            continue
+        out[src] = target
+    return out

package/scripts/lang_capability.py

@@ -0,0 +1,150 @@
+#!/usr/bin/env python3
+"""lang_capability.py — 语言能力画像：让路由按「引擎在某语言下真的行」来选。
+
+## 问题（C 阶段实测）
+
+18 语言 × 29 引擎矩阵（`scripts/lang_matrix_probe.py`）暴露两件事：
+
+1. **语言覆盖极不均衡**：西班牙语 12 个可用引擎，泰语只有 3 个；
+   日语只有 5 个——而 argo 明明有 Qiita / NDL / 萌娘百科等日文资源。
+2. **「可用」不等于「被用上」**：路由此前只看 `coverage` 字段（157 个引擎里
+   109 个根本没声明语言），于是「引擎在某语言下真的有内容」这个事实
+   完全没进入决策。
+
+## 机制
+
+把矩阵实测结果固化为**能力画像**（`data/lang_matrix/lang_capability.json`），
+路由据此对候选引擎打语言适配分。
+
+设计取舍——**建议而非硬过滤**：
+  · 硬过滤的风险：矩阵是单次实测，含网络抖动与查询抽样偏差；
+    一旦硬砍，某次抖动会让整门语言失去检索能力。
+  · 加权则两头兼顾：能力强的引擎优先，未知的保持原样（不惩罚），
+    实测为噪声的降权（不禁止）。
+  · 画像缺失/过期时**完全退化为原行为**——这是安全保底。
+
+## 数据来源与新鲜度
+
+画像由 `lang_matrix_probe.py` 生成。调用方不应假设它永远存在；
+`available()` 返回 False 时所有查询按原权重走。
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from pathlib import Path
+from typing import Any
+
+_PROFILE_PATH = Path(__file__).resolve().parent.parent / "data" / "lang_matrix" / "lang_capability.json"
+
+# 画像最大可接受年龄（秒）。超过则视为过期——语言能力会随上游改版变化，
+# 陈年数据不该继续影响路由。30 天是「够用且不至于陈旧」的折中。
+MAX_AGE_S = 30 * 24 * 3600
+
+# 评分权重
+BOOST_GOOD = 1.15      # 实测该语言下良好 → 提权
+PENALTY_NOISE = 0.85   # 实测该语言下噪声 → 降权
+NEUTRAL = 1.0          # 无数据 → 不动
+
+_cache: dict[str, Any] = {}
+
+
+def _load() -> dict[str, Any] | None:
+    """读能力画像（带进程内缓存）。缺失/损坏/过期返回 None。"""
+    if "profile" in _cache:
+        return _cache["profile"]
+    profile = None
+    try:
+        st = _PROFILE_PATH.stat()
+        if time.time() - st.st_mtime <= MAX_AGE_S:
+            data = json.loads(_PROFILE_PATH.read_text(encoding="utf-8"))
+            if isinstance(data, dict):
+                profile = data
+    except Exception:
+        profile = None
+    _cache["profile"] = profile
+    return profile
+
+
+def available() -> bool:
+    """画像是否可用。False 时调用方应完全按原行为处理。"""
+    return _load() is not None
+
+
+def engines_for_lang(lang: str) -> set[str]:
+    """该语言下实测良好的引擎集合（画像缺失时返回空集）。"""
+    p = _load()
+    if not p:
+        return set()
+    langs = p.get("lang_engines") or {}
+    # 语系级标签归一：detect_language 可能给 latin/cyrillic，
+    # 而画像按具体语种建（de/fr/ru…）。此时合并该语系全部成员。
+    members = _expand_lang(lang)
+    out: set[str] = set()
+    for m in members:
+        for e in (langs.get(m) or []):
+            out.add(e)
+    return out
+
+
+def noise_engines_for_lang(lang: str) -> set[str]:
+    """该语言下实测为噪声的引擎（用于降权）。"""
+    p = _load()
+    if not p:
+        return set()
+    per_lang = ((p.get("summary") or {}).get("per_lang")) or {}
+    members = _expand_lang(lang)
+    out: set[str] = set()
+    for m in members:
+        for e in (per_lang.get(m, {}).get("noise_engines") or []):
+            out.add(e)
+    return out
+
+
+_FAMILY = {
+    "latin": ("en", "de", "fr", "es", "pt", "it", "nl", "pl", "tr", "vi"),
+    "cyrillic": ("ru",),
+}
+
+
+def _expand_lang(lang: str) -> tuple[str, ...]:
+    """**仅当输入是语系标签**时展开为具体语种成员；具体语种原样返回。
+
+    为什么不对具体语种做同族扩展（实测教训）：
+      detect_language 对语言明确的查询返回具体标签（zh/ja/de/ru…），
+      只有判不出来时才返回语系标签（latin/cyrillic）。而**同语系的
+      语言能力并不通用**——实测 zh_wikipedia 擅长中文（zh/en/fr/es…）
+      却完全不胜任日语；ndl 擅长日语却不擅长中文。若把 ja 展开成
+      (zh, ja)，中文引擎的能力会被误算到日语头上。
+
+      故：具体语种 → 精确匹配；语系标签 → 展开（因为此时确实不知道
+      是哪种语言，只能取该语系并集作为参考）。
+    """
+    if not lang:
+        return ()
+    if lang in _FAMILY:
+        return _FAMILY[lang]
+    return (lang,)
+
+
+def score_adjust(engine: str, lang: str) -> float:
+    """返回该引擎在该语言下的权重系数（1.0 表示不调整）。
+
+    调用方把返回值乘到引擎原有评分上即可。画像缺失时恒为 1.0。
+    """
+    if not engine or not lang:
+        return NEUTRAL
+    p = _load()
+    if not p:
+        return NEUTRAL
+    if engine in engines_for_lang(lang):
+        return BOOST_GOOD
+    if engine in noise_engines_for_lang(lang):
+        return PENALTY_NOISE
+    return NEUTRAL
+
+
+def reload() -> None:
+    """清空缓存（测试与画像更新后调用）。"""
+    _cache.pop("profile", None)

package/scripts/lang_detect.py

@@ -0,0 +1,289 @@
+#!/usr/bin/env python3
+"""lang_detect.py — 查询语言检测（统一多语种判定）
+
+覆盖全球主要语系：中文/日文/韩文/拉丁语系（英法德西等）/西里尔（俄语等）/
+泰语/阿拉伯/希伯来/希腊/梵文天城体等。纯 stdlib、<1ms。
+
+关键决策：
+  - 汉字（CJK Unified）归 zh；但日文假名（\\u3040-\\u30ff）与韩文谚文
+    （\\uac00-\\ud7af）是强语言信号，优先于汉字判定 —— 「東京の天気」虽是
+    汉字+假名，应判 ja 而非 zh。
+  - english_ratio 改为「拉丁字母占比」而非「1 - chinese_ratio」，
+    修复日韩查询被误判为英文的老问题。
+  - script 与 primary_lang 同源（由 detect_language 映射），避免
+    「主语言 zh / script latin」这类混技术词查询上的矛盾。
+  - 引擎语言参数（setlang/hl/lang/uselang）表只在此维护一处，
+    engines_base / local-search/search_v3 共用。
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+_RE_HAN = re.compile(r"[\u4e00-\u9fff]")
+_RE_KANA = re.compile(r"[\u3040-\u30ff]")          # 平假名 + 片假名
+_RE_HANGUL = re.compile(r"[\uac00-\ud7af]")        # 谚文音节
+_RE_LATIN = re.compile(r"[A-Za-z]")
+_RE_CYRILLIC = re.compile(r"[\u0400-\u04ff]")      # 西里尔（俄/乌/保等）
+_RE_THAI = re.compile(r"[\u0e00-\u0e7f]")          # 泰文
+_RE_ARABIC = re.compile(r"[\u0600-\u06ff]")        # 阿拉伯
+_RE_HEBREW = re.compile(r"[\u0590-\u05ff]")        # 希伯来
+_RE_GREEK = re.compile(r"[\u0370-\u03ff]")         # 希腊
+_RE_DEVANAGARI = re.compile(r"[\u0900-\u097f]")    # 天城体（印地/梵）
+_RE_LATIN_EXT = re.compile(r"[\u00c0-\u024f]")     # 拉丁扩展（é ü ñ 等）
+
+LANG_LABELS = {
+    "zh": "中文",
+    "en": "英文",
+    "ja": "日文",
+    "ko": "韩文",
+    "latin": "拉丁语系",
+    "cyrillic": "西里尔语系",
+    "thai": "泰语",
+    "arabic": "阿拉伯语",
+    "hebrew": "希伯来语",
+    "greek": "希腊语",
+    "devanagari": "印地语系",
+    "mixed": "混合",
+    "other": "其他",
+}
+
+# primary_lang → 书写系统类别（与 detect_language 同源，杜绝双来源）
+_LANG_TO_SCRIPT: dict[str, str] = {
+    "zh": "cjk",
+    "ja": "kana",
+    "ko": "hangul",
+    "en": "latin",
+    "latin": "latin",
+    "cyrillic": "cyrillic",
+    "thai": "thai",
+    "arabic": "arabic",
+    "hebrew": "hebrew",
+    "greek": "greek",
+    "devanagari": "devanagari",
+    "mixed": "mixed",
+    "other": "other",
+}
+
+# 非拉丁主语言：路由/跨语言回退共用
+NON_LATIN_LANGS = frozenset({
+    "zh", "ja", "ko", "cyrillic", "thai", "arabic",
+    "hebrew", "greek", "devanagari",
+})
+
+# 引擎语言参数 → 各主语言取值（覆盖 config.yaml 静态值）
+# 缺语言键时 engine_lang_param 返回空串，调用方保留静态默认。
+ENGINE_LANG_PARAM_VALUES: dict[str, dict[str, str]] = {
+    "setlang": {  # Bing
+        "ja": "ja-JP", "ko": "ko-KR", "en": "en-US", "latin": "en-US",
+        "zh": "zh-Hans", "cyrillic": "ru-RU", "thai": "th-TH",
+        "arabic": "ar", "hebrew": "he", "greek": "el", "devanagari": "hi",
+        "mixed": "en-US", "other": "en-US",
+    },
+    "mkt": {  # Bing 市场码（比 setlang 更强制结果区域，修复 ja/ko 返回中文站问题）
+        "ja": "ja-JP", "ko": "ko-KR", "en": "en-US", "latin": "en-US",
+        "zh": "zh-CN", "cyrillic": "ru-RU", "thai": "th-TH",
+        "arabic": "ar-SA", "hebrew": "he-IL", "greek": "el-GR", "devanagari": "hi-IN",
+        "mixed": "en-US", "other": "en-US",
+    },
+    "hl": {  # Google
+        "ja": "ja", "ko": "ko", "en": "en", "latin": "en",
+        "zh": "zh-CN", "cyrillic": "ru", "thai": "th",
+        "arabic": "ar", "hebrew": "iw", "greek": "el", "devanagari": "hi",
+        "mixed": "en", "other": "en",
+    },
+    "lang": {  # Yandex
+        "ja": "ja", "ko": "ko", "en": "en", "latin": "en", "zh": "zh",
+        "cyrillic": "ru", "thai": "th",
+        "arabic": "ar", "hebrew": "he", "greek": "el", "devanagari": "hi",
+        "mixed": "en", "other": "en",
+    },
+    "uselang": {  # Wikipedia
+        "ja": "ja", "ko": "ko", "en": "en", "latin": "en", "zh": "zh",
+        "cyrillic": "ru", "thai": "th",
+        "arabic": "ar", "hebrew": "he", "greek": "el", "devanagari": "hi",
+        "mixed": "en", "other": "en",
+    },
+    "region": {  # ddgs -r region（{country}-{lang} 形态）
+        "ja": "jp-ja", "ko": "kr-ko", "en": "us-en", "latin": "us-en",
+        "zh": "cn-zh", "cyrillic": "ru-ru", "thai": "th-th",
+        "arabic": "sa-ar", "hebrew": "il-he", "greek": "gr-el", "devanagari": "in-hi",
+        "mixed": "us-en", "other": "us-en",
+    },
+}
+
+_LANG_PARAM_KEYS = frozenset(ENGINE_LANG_PARAM_VALUES.keys())
+
+# 纯汉字日文特征词：简体/繁体中文查询中均不出现（或极罕见）的日语词汇。
+# 用于区分「无假名日文查询」与「中文查询」，避免被 han/total 分支误判为 zh。
+_JA_KANJI_ONLY_SIGNALS = (
+    "非同期", "処理", "予報", "検索", "天気", "株式", "映画", "配信",
+    "報道", "速報", "転職", "面接", "給料", "応募", "卒業", "受験",
+    "大学院", "授業", "講義", "宿題", "就活", "新卒", "口座", "振込",
+    "残高", "通帳", "介護", "処方", "発熱", "予定", "営業", "退職",
+    "支払", "申告", "円高", "円安", "株価", "参議院", "衆議院", "住民票",
+    "印鑑", "免許", "交番", "弁護士", "捜査", "容疑者", "津波", "断水",
+    "変電", "給湯", "残業", "有給", "退院", "受診", "処方箋", "薬局",
+    "予約", "出張", "帰省", "新幹線", "改札", "切符", "乗車", "納期",
+    "発注", "受注", "出荷", "納品", "売上", "仕入", "原価", "在庫",
+    "領収書", "請求書", "見積",
+    # AI / 技术高频（实测缺口：查询「人工知能 最新 動向」曾因不在表中被判成 zh）
+    "人工知能", "機械学習", "深層学習", "情報処理", "開発環境", "実行",
+    "変数", "関数", "引数", "配列", "例外", "継承", "抽象", "再帰",
+)
+
+# 日文新字体中「既不同于简体、也不同于繁体」的独有字形。
+#
+# 判定依据（逐个核对字形三态）：
+#   観(ja) / 观(zh简) / 觀(zh繁)   → 仅日文用「観」
+#   経(ja) / 经(zh简) / 經(zh繁)   → 仅日文用「経」
+#   鉄(ja) / 铁(zh简) / 鐵(zh繁)   → 仅日文用「鉄」
+# 这类字形出现即**可以确定**是日文，不会误伤简体或繁体中文。
+#
+# 反面教训（为什么不用「動/報/學」这类字形）：它们是日文新字体，
+# 但**同时是繁体中文用字**（繁中亦作「動」「報」「學」），拿来判日文
+# 会把繁体中文误判成日文。故只用「三态互异」的严格子集。
+#
+# 已知局限（本函数无法覆盖）：纯粹由中日共用汉字组成的短查询，
+# 如「人工知能 最新 動向」——它不含任何日文独有字形，字符层面与中文
+# 无从区分，只能靠上面的词汇表命中（该例已通过补词解决）。若两者
+# 都不命中，会落到 zh 分支。这是一个**已知且有界的**限制，不做硬猜。
+_JA_SHINJITAI_ONLY = frozenset(
+    "亀亜伝価児円処剣剤単厳営団囲図圧塩壊売変奨実寛対専帯帰庁広弾徴応悪戦戸択拠挙挟摂斉斎桟検楽権歓歯気沢浄済渋滝犠獣産畳発糸経継続総縁縄縦繊聡聴臓芸荘薬蛍覚観証読譲賛転軽辺逓遅郷醸鉄鉱鋳関闘険雑顕駅騒験"
+)
+
+
+def _has_ja_only_kanji(text: str) -> bool:
+    """文本是否含「仅日文使用」的新字体字形（三态互异）。"""
+    return any(c in _JA_SHINJITAI_ONLY for c in text)
+
+
+def detect_language(query: str) -> str:
+    """返回主语言标签：zh / en / ja / ko / latin / cyrillic / thai / arabic /
+    hebrew / greek / devanagari / mixed / other。"""
+    if not query or not query.strip():
+        return "other"
+    total_chars = len([c for c in query if not c.isspace()])
+    if total_chars == 0:
+        return "other"
+    han = len(_RE_HAN.findall(query))
+    kana = len(_RE_KANA.findall(query))
+    hangul = len(_RE_HANGUL.findall(query))
+    latin = len(_RE_LATIN.findall(query))
+    latin_ext = len(_RE_LATIN_EXT.findall(query))
+    cyrillic = len(_RE_CYRILLIC.findall(query))
+    thai = len(_RE_THAI.findall(query))
+    arabic = len(_RE_ARABIC.findall(query))
+    hebrew = len(_RE_HEBREW.findall(query))
+    greek = len(_RE_GREEK.findall(query))
+    devanagari = len(_RE_DEVANAGARI.findall(query))
+
+    # 非拉丁书写系统强信号优先
+    if kana / total_chars >= 0.15:
+        return "ja"
+    if hangul / total_chars >= 0.15:
+        return "ko"
+    if kana and han and han / total_chars >= 0.3:
+        return "ja"  # 汉字 + 少量假名（如「東京の天気」）
+    if thai / total_chars >= 0.2:
+        return "thai"
+    if arabic / total_chars >= 0.2:
+        return "arabic"
+    if hebrew / total_chars >= 0.2:
+        return "hebrew"
+    if greek / total_chars >= 0.2:
+        return "greek"
+    if devanagari / total_chars >= 0.2:
+        return "devanagari"
+    if cyrillic / total_chars >= 0.2:
+        return "cyrillic"
+    # 纯汉字日文预检（两道，互为补充）：
+    #   ① 日文独有字形（三态互异，如 観/経/鉄）——出现即可确定是日文，
+    #      不会误伤简体或繁体中文，可靠性最高。
+    #   ② 日语特征词表——覆盖不含独有字形的常见日文表达。
+    #
+    # 已知且**有界**的残余局限：纯粹由中日共用汉字组成的短查询
+    # （如「人工知能 最新 動向」——「動」繁体中文亦用，不能作判据）
+    # 在字符层面与中文无从区分。此类查询若两道路径都不命中，会落到 zh。
+    # 不做硬猜：宁可保持现状（由调用方的语言覆盖/多语言回退保底），
+    # 也不引入会把简体中文误判成日文的正则。
+    if han and (_has_ja_only_kanji(query)
+                or any(w in query for w in _JA_KANJI_ONLY_SIGNALS)):
+        return "ja"
+    # 汉字为主判 zh
+    if han / total_chars >= 0.3:
+        return "zh"
+    # 拉丁字母（含扩展字符 é/ü/ñ 等）为主 → 拉丁语系
+    # 扩展字符占比 ≥ 0.08 时判 latin（café / español / français 等）
+    if (latin + latin_ext) / total_chars >= 0.5:
+        if latin_ext / total_chars >= 0.08:
+            return "latin"
+        return "en" if latin else "latin"
+    # 有汉字也有大量拉丁 → 中英混合；其余情况判混合
+    if han and latin:
+        return "mixed"
+    return "other"
+
+
+def detect_script(query: str) -> str:
+    """返回书写系统类别，与 detect_language 同源映射。
+
+    不再独立计分：避免「Python 异步编程」主语言 zh 却 script=latin 的矛盾。
+    供路由做 is_latin / 跨语言回退判断。
+    """
+    return _LANG_TO_SCRIPT.get(detect_language(query), "other")
+
+
+def is_non_latin_lang(lang: str) -> bool:
+    """主语言是否为非拉丁书写系统（需要跨语言回退/语言引擎补充）。"""
+    return lang in NON_LATIN_LANGS
+
+
+def engine_lang_param(param: str, query: str, preferred_lang: str = "") -> str:
+    """按查询主语言返回引擎语言参数取值；无法判定或无映射时返回空串。
+
+    调用方约定：`v = engine_lang_param(k, query) or v`，保留 config 静态默认。
+
+    preferred_lang：弱信号查询（mixed/other）时的回落语种，来自
+    lang_pref.effective_engine_lang（习惯/系统/中英基线）。强查询信号始终优先。
+    """
+    table = ENGINE_LANG_PARAM_VALUES.get(param)
+    if not table:
+        return ""
+    lang = detect_language(query)
+    # 弱信号才采用偏好语；zh/ja/ko/非拉丁/en/latin 以查询为准
+    if preferred_lang and lang in ("mixed", "other"):
+        if preferred_lang in table:
+            return table[preferred_lang]
+    return table.get(lang, "")
+
+
+def is_lang_param(key: str) -> bool:
+    """extra_params 键是否为可动态覆盖的语言参数。"""
+    return key in _LANG_PARAM_KEYS
+
+
+def language_features(query: str) -> dict[str, Any]:
+    """返回与 route.extract_features 兼容的语言特征字段。
+
+    新增 primary_lang / script / is_latin，并保留 chinese_ratio /
+    english_ratio 的既有语义（chinese_ratio 仍为汉字占比，english_ratio
+    为拉丁占比），兼容现有调用方（route / smart_router 的 is_chinese
+    判断不破坏）。
+    """
+    if not query:
+        query = ""
+    total = max(len(query), 1)
+    chinese = len(_RE_HAN.findall(query))
+    latin = len(_RE_LATIN.findall(query)) + len(_RE_LATIN_EXT.findall(query))
+    primary_lang = detect_language(query)
+    script = _LANG_TO_SCRIPT.get(primary_lang, "other")
+    return {
+        "primary_lang": primary_lang,
+        "script": script,
+        "is_latin": primary_lang in ("en", "latin"),
+        "chinese_ratio": round(chinese / total, 4),
+        "english_ratio": round(latin / total, 4),
+        "length": total,
+    }