argo-search 1.0.1 → 2.9.7

package/scripts/cache_guard.py

@@ -0,0 +1,271 @@
+#!/usr/bin/env python3
+"""cache_guard.py — 公共缓存的写入守卫（登录态 + 上游退化）。
+
+从 cache.py 拆出（2026-09-27，方案 C1）。拆的理由是纪律性的：cache.py 已在
+tests/test_module_size_gate.py 的 GRANDFATHERED 里登记（1362 行上限），
+任何净增长都会被门禁拦下——而「写缓存前该不该写」这条判断不属于缓存的存储
+实现，属于「缓存的准入策略」，两者混在一起只会让 cache.py 继续变大。
+
+## 两条守卫
+
+**登录态守卫**（本体与异常类都在 cache.py）：登录态检索的结果不得进入
+公共缓存，避免一个账号的私有结果被所有人共享。
+
+**退化守卫**：上游抖动返回的残次品不得写入。
+实锤事故见 is_degraded_results 的 docstring——一次上游把整句当单词查、
+返回 8 条词典释义，相关性全为 0.1429，却照常缓存并从此固化。
+
+两个守卫的异常类**不在同一个模块**：cache.py 模块级 `from cache_guard
+import ...`，所以这里只能用函数级 import 去取 LoginCacheRejected，模块级
+会成环。统一入口是 attempt_cache_write，调用方不必自己认这两个类。
+
+## 为什么退化守卫在「写入」这一层而不是「返回」那一层
+
+退化结果**当场返回**是有价值的：它至少让调用方看到「这次没搜到」，
+且恢复路径是重打一次（无缓存命中，自然重新请求上游）。
+但它**不该被缓存**：一旦缓存，退化就从「一次抖动」变成「永久结果」——
+后续每次命中缓存都复现，且没有任何信号提示它曾经退化过。
+写入层拦截是唯一能切断这个固化的位置。
+
+## 调用方必须走 attempt_cache_write，不要裸调 cache.set
+
+「不写缓存」和「检索失败」是两件事。守卫抛出的异常如果穿透到调用主路径，
+代价是一次检索白跑——而且比白跑更糟，见 attempt_cache_write 的 docstring。
+"""
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from except_sets import OPT_IMPORT
+
+
+class DegradedCacheRejected(ValueError):
+    """退化结果（低相关/查询词回声）禁止写入公共 SearchCache。"""
+
+
+class FailedStateCacheRejected(ValueError):
+    """配置/状态类失败（缺密钥/熔断/鉴权/配额）且无有效结果：不写负缓存。
+
+    与退化守卫的分工：退化拦「搜到了但内容是垃圾」；本守卫拦「根本没搜成、
+    且换个人/等一会/改个配置就能好」。把后者缓存下来，等于把「argo 此刻
+    没配对」固化成「这个查询没有答案」——实测形态（2026-09-28）：
+    `--engine parallel` 缺 key → L2 落 {"results": [], "ttl": 45}，用户按
+    文档配好 PARALLEL_API_KEY 后同一查询仍 cached=true 并回放
+    「PARALLEL_API_KEY 未设置」，与 issue #12 报告人的体验逐字同构。
+    """
+
+
+# 配置/状态类失败的状态名（engine_dispatch.classify_engine_outcome 词汇表）。
+# 网络类失败（timeout/blocked/rate-limited/no-results）刻意不收——它们中
+# 确实混有「真的没有」，负缓存是既有设计（EMPTY_RESULT_TTL），等一会重试
+# 由 TTL 自然兜底。本类的共同点：**换环境就能好**，缓存它没有信息量。
+_STATE_FAIL_STATUSES = frozenset({
+    "skipped-missing-env", "skipped-circuit-open", "auth-failed",
+    "quota-exhausted", "skipped-quota-exhausted",
+})
+
+# 配额耗尽错误关键词（唯一来源）：classify_engine_outcome 的 quota-exhausted
+# 分类与自适应学习跳过逻辑共用。新增配额错误码（如新的 API 业务码）只改这里。
+_QUOTA_ERROR_KEYWORDS = ("quota", "10406", "insufficient balance",
+                         "insufficient funds", "not enough money",
+                         "余额不足", "额度不足", "配额耗尽")
+
+# builder 路径漏到 status="error" 的缺密钥形态：路由层 env 拦截覆盖不到
+# 自定义 required_env 的引擎（search.py:192-209 docstring 自认的缺口），
+# issue #12 的 parallel/seltz/you 就读裸名——状态层 env_ready=True、执行层
+# 取不到值。按 detail 文本兜底识别。
+_MISSING_ENV_DETAIL_KEYWORDS = (
+    "未设置", "api_key", "api key", "apikey", "环境变量",
+)
+
+
+def is_state_failure_outcome(outcome: Any) -> bool:
+    """单引擎结局是否「配置/状态类失败」（可修复，不该负缓存或记入学习器失败）。"""
+    if not isinstance(outcome, dict):
+        return False
+    status = str(outcome.get("status") or "")
+    if status in _STATE_FAIL_STATUSES:
+        return True
+    if status == "error":
+        detail = str(outcome.get("detail") or "").lower()
+        return any(k in detail for k in _MISSING_ENV_DETAIL_KEYWORDS)
+    return False
+
+
+def should_record_adaptive(outcome: dict[str, Any] | None,
+                           res: list[dict[str, Any]]) -> bool:
+    """单引擎结局是否应记入 adaptive 学习器（跳过早停弃置与配额/鉴权/缺密钥等状态类故障）。"""
+    st = str((outcome or {}).get("status") or "")
+    if st.startswith(("cancelled", "skipped-")) or is_state_failure_outcome(outcome):
+        return False
+    errors = [str(r.get("error", "")) for r in (res or ())
+              if isinstance(r, dict) and "error" in r]
+    if errors and all(
+        any(k in msg.lower() for k in (
+            *_QUOTA_ERROR_KEYWORDS, "unauthorized", "api key",
+            "forbidden", "401", "403",
+        ))
+        for msg in errors
+    ):
+        return False
+    return True
+
+
+def failed_state_reason(payload: object) -> str | None:
+    """载荷是否「整体没搜成且原因可修复」——是则返回理由（否则 None）。
+
+    判据：**没有任何有效结果**、且**至少一个**引擎结局是配置/状态类失败。
+    两条边界的理由：
+
+      - 有有效结果时不拦：个别引擎的配置失败不毒化整批（照常缓存）；
+      - 「至少一个」而不是「全部」：缓存命中会**原样回放 engine_outcomes**
+        并由 _collect_errors 重建 errors——混合场景里那条「未设置」会在
+        用户配好 key 后继续重放 45s，与单引擎形态同构。连带的代价只是
+        别的引擎少一份 45s 负缓存（重试一次超时引擎本就无妨）。
+
+    网络类失败单独出现时不拦（见 _STATE_FAIL_STATUSES 注释）。
+    """
+    if not isinstance(payload, dict):
+        return None
+    results = payload.get("results")
+    if isinstance(results, list) and any(
+            isinstance(r, dict) and "error" not in r for r in results):
+        return None
+    outcomes = payload.get("engine_outcomes")
+    if isinstance(outcomes, dict):
+        outcomes = [outcomes]  # 单引擎直写形态（CLI --engine 路径）
+    if not isinstance(outcomes, list) or not outcomes:
+        return None
+    failed = [o for o in outcomes if is_state_failure_outcome(o)]
+    if failed:
+        kinds = sorted({str(o.get("status") or "?") for o in failed
+                        if isinstance(o, dict)})
+        return (f"{len(failed)}/{len(outcomes)} 个引擎为配置/状态类失败"
+                f"（{'/'.join(kinds)}）且无有效结果，不写负缓存")
+    return None
+
+
+def assert_not_failed_state(payload: object, *, context: str) -> None:
+    """配置/状态类失败硬拒绝：宁可下次重打，也不把「没配对」固化成「没答案」。"""
+    reason = failed_state_reason(payload)
+    if reason:
+        raise FailedStateCacheRejected(f"{context}: {reason}")
+
+
+def cache_write_rejections() -> tuple[type[Exception], ...]:
+    """写入守卫会抛的全部异常类：退化 + 失败态（本模块）+ 登录态（cache.py）。
+
+    登录态那一个只能函数级取：cache.py 模块级 import 本模块，反向 import
+    会成环。取不到（cache 被换掉/裁掉）时只留本模块守卫——少认一种异常最多
+    让那一路退回旧行为，不该反过来让调用方炸掉。
+    """
+    try:
+        from cache import LoginCacheRejected
+    except OPT_IMPORT:
+        return (DegradedCacheRejected, FailedStateCacheRejected)
+    return (DegradedCacheRejected, FailedStateCacheRejected, LoginCacheRejected)
+
+
+def attempt_cache_write(write: Callable[[], Any], *,
+                        context: str = "cache") -> str | None:
+    """执行一次缓存写入；被写入守卫拒绝时返回异常类别名，而不是抛出。
+
+    守卫的职责是「不固化」，不是「不返回」——两者在调用主路径上必须分开：
+
+      - **combo 写入点**（search_pipeline.finalize）：异常穿透会取消整个
+        查询。2026-09-27 实锤——`Apple Inc 10-K annual report 2025` 的 5 条
+        结果里 4 条 relevance=0 触发退化守卫，CLI 直接 traceback 退出，
+        **已检索到的结果全部丢弃**（这批结果本身是有用的：第 1 条正是
+        Apple 的 CIK 归档页）。
+      - **per-engine 写入点**（engine_dispatch）：异常被 daemon 线程的兜底
+        except 接住，后果更隐蔽——那次**成功的**引擎调用被改写成
+        `status=error` 且结果清空，还按 kind=error 记账进熔断器，把一个
+        健康引擎推向 auto-disable。
+
+    返回值为 None 表示写入成功（或本就没有可写内容）；返回字符串表示被
+    拒绝，值即异常类别名（如 `"DegradedCacheRejected"`），供调用方写进
+    响应字段或日志。*context* 只用于日志措辞。
+    """
+    try:
+        write()
+    except cache_write_rejections() as exc:
+        import logging
+        logging.getLogger("unified_search").debug(
+            f"{context}: 缓存写入跳过（{type(exc).__name__}）: {exc}")
+        return type(exc).__name__
+    return None
+
+
+# 退化判据的阈值。与 rank_signals 的相关性算子配套：正常结果的 rel 普遍
+# ≥0.35，查询词回声（上游把整句当单词查、返回词典释义）稳定在 0.05-0.20。
+# 0.25 落在两者之间，且远高于噪声、又低于任何真实命中。
+DEGRADED_RELEVANCE_FLOOR = 0.25
+
+# 「多数条目低于地板」的比例门槛。不用 1.0：上游降级时通常仍混有 1-2 条
+# 正常结果（降级不是全有全无）。0.7 是「压倒性低分」与「正常长尾」的分界。
+DEGRADED_BATCH_RATIO = 0.7
+
+# 可判定条目数下限。低于此不判：样本太少时比例不可信，且宁可漏拦不误伤。
+DEGRADED_MIN_SCORED = 3
+
+# 恢复批降级写入的 TTL（秒）。恢复链成功产出的批次若整批低相关，不硬拒
+# （硬拒会把「难查询的恢复成果」挡在缓存外，重复查询每次重付 dispatch+恢复
+# 链全程——2026-10-17 实测同查询 21s 内 3 次恢复链），降级为 10 分钟短缓存：
+# 给重复查询留命中，又不长期固化低相关结果。
+RECOVERED_DEGRADED_TTL = 600
+
+
+def _entry_relevance(item: Any) -> float | None:
+    """取单条结果的相关性；取不到返回 None。
+
+    相关性通常不在顶层，而在 `rerank_dims` 里（本地五维 rerank 写入）。
+    顶层也看一眼是为了兼容未跑 rerank 的引擎直写路径。
+    踩过的坑：只读顶层会得到「全部取不到 → 一律不判」，守卫静默失效。
+    """
+    if not isinstance(item, dict):
+        return None
+    rel = item.get("relevance")
+    if not isinstance(rel, (int, float)) or isinstance(rel, bool):
+        dims = item.get("rerank_dims")
+        rel = dims.get("relevance") if isinstance(dims, dict) else None
+    if isinstance(rel, (int, float)) and not isinstance(rel, bool):
+        return float(rel)
+    return None
+
+
+def is_degraded_results(results: object) -> bool:
+    """这批结果是否是「上游退化」——不完整命中查询词的回声。
+
+    2026-09-27 实锤（`detecting LLM generated content farm SEO spam`）：
+    路由正确（anysearch + local_bing），但上游某一刻把整句当成单词去查，
+    返回 8 条「detecting 这个词的词典释义」。它们的 rerank_dims.relevance
+    全部是 **0.1429**（只命中查询里的 detecting 一词），却照常返回、照常
+    进入排序、照常写入缓存——于是这次上游抖动被**固化**下来，之后每次命中
+    缓存都复现同样的垃圾结果。funnel 看着完全正常（returned 10 → kept 8），
+    所以极难察觉。
+
+    这与「结果少」是两件事：`funnel` 只数数量，不看每条像不像答案。
+
+    判据刻意保守——**只拦整批退化**，不拦单条低分：
+      - 单条低相关完全正常（长尾查询本就有弱命中），拦它会误伤真结果；
+      - 整批都低于地板才是信号：要么上游确实降级了，要么这个查询真的没有
+        答案（此时缓存一份垃圾不如重打一次）。
+    """
+    if not isinstance(results, list) or not results:
+        return False
+    scored = [v for v in (_entry_relevance(it) for it in results) if v is not None]
+    if len(scored) < DEGRADED_MIN_SCORED:
+        # 拿不到足够的相关性数据就不判——不猜，也不用缺字段去拒绝正常写入。
+        return False
+    low = sum(1 for v in scored if v < DEGRADED_RELEVANCE_FLOOR)
+    return (low / len(scored)) >= DEGRADED_BATCH_RATIO
+
+
+def assert_not_degraded(results: object, *, context: str) -> None:
+    """退化结果硬拒绝：宁可下次重打，也不要把上游抖动固化进缓存。"""
+    if is_degraded_results(results):
+        raise DegradedCacheRejected(
+            f"{context}: 多数条目 relevance < {DEGRADED_RELEVANCE_FLOOR}，"
+            f"判定为上游退化，不写入公共 SearchCache"
+        )

package/scripts/cache_key_vdom.py

@@ -0,0 +1,56 @@
+"""cache_key_vdom — 缓存键里的「引擎级垂直域」维度。
+
+**为什么单独成文件**：`cache.py` 已到模块体积门禁上限（`tests/test_module_size_gate.py`
+登记 1375 行），而这层语义又必须与缓存键的其余维度待在一起。
+
+**为什么它必须在键里**：`--domain` / `--sub_domain` 改变的是**发给引擎的请求**，
+同 query 在不同垂直域下结果集不同。此前两个开关被 argparse 接下、写进 SKILL.md
+参数表，却没有任何一层读取——请求照发、结果照回，`domain` 从未到达引擎。
+接上之后若不进键，「不限域」的结果会被当成「限定金融域」的答案发回去：
+一个静默失效的开关会变成一个静默给错答案的开关。
+
+**两种 domain 同名不同义，刻意不合并**：
+
+- `domain`：**路由域**（general / stock / weather…），决定选哪些源；
+- `engine_domain` / `engine_sub_domain`：**引擎入参**，改变单个引擎的请求体。
+
+前者早就在键里；这里补的是后者。`short` 短键只用于拼 `raw`，不进 DB 列。
+"""
+from __future__ import annotations
+
+from typing import Any, Iterable
+
+# kwargs 名 → 键内短名。顺序固定，保证键的构造是确定性的。
+_VDOM_TAGS: tuple[tuple[str, str], ...] = (
+    ("engine_domain", "ed"),
+    ("engine_sub_domain", "esd"),
+)
+
+
+def cache_key_vdom(vdom: dict[str, Any] | None) -> list[tuple[str, str]]:
+    """把垂直域 kwargs 摊成 `[(短名, 值)]`，供缓存键拼装使用。
+
+    未知键一律忽略（而不是透传）：`_key` 的 `**vdom` 是开放签名，
+    拼键只认登记过的维度，避免调用方拼错名字时静默丢维度——那正是本模块
+    要消灭的那类 bug。空值 / 非字符串 / None 都被滤掉，保证「没给」
+    与「给了空串」在键上等价，不会凭空分裂出两份缓存。
+    """
+    if not vdom:
+        return []
+    out: list[tuple[str, str]] = []
+    for name, tag in _VDOM_TAGS:
+        val = vdom.get(name)
+        if isinstance(val, str) and val:
+            out.append((tag, val))
+    return out
+
+
+def has_vdom(vdom: dict[str, Any] | None) -> bool:
+    """是否指定了任意垂直域维度（供需要早退的调用方省一次拼键）。"""
+    return bool(cache_key_vdom(vdom))
+
+
+def vdom_of(iterable: Iterable[tuple[str, str]]) -> dict[str, str]:
+    """`cache_key_vdom` 的逆（按登记顺序还原成长名 → 值）。"""
+    rev = {tag: name for name, tag in _VDOM_TAGS}
+    return {rev[tag]: val for tag, val in iterable if tag in rev}

package/scripts/cache_similarity.py

@@ -0,0 +1,170 @@
+#!/usr/bin/env python3
+"""
+cache_similarity.py — 缓存侧的查询归一化与近重复判定（2026-10-16 从 cache.py 拆出）
+
+拆出原因：拆分前 cache.py 1382 行（祖父上限），是全仓仅次于源声明构建器的
+大文件，module size 门禁的既定结论是「按键 / 存储 / 命中策略三段拆，并把
+上限调低」。本模块承载三段里的「命中策略」判据层——**纯函数、零 IO、零
+sqlite 依赖**：
+
+  - normalize_query        缓存键归一化（空白/全半角/大小写）
+  - query_similarity       字符 n-gram minhash 近似 Jaccard（软命中的判据）
+  - split_qualifiers       限定符（site: / keywords:）与载荷拆分
+  - is_freshness_sensitive_query  时效敏感查询检测（TTL 帽的输入）
+
+为什么整段搬而不是只搬一半：这四件事共用同一套「查询字符串 → 可比签名」
+的变换，`find_similar` 的每一次软命中判定都要依序走完它们；留一半在
+cache.py 只会让「判据在哪」重新变成两处。搬走后 cache.py 只保留存储实现
+（L1/L2）与 SearchCache 门面。
+
+兼容约定（拆模块的两条老规矩，与 cache_guard / cache_key_vdom 一致）：
+  - cache.py 显式 re-export 本模块全部公开名，`from cache import
+    query_similarity` 等既有 import 点零改动；
+  - 测试 monkeypatch 的面仍在 cache.py（`cache.is_freshness_sensitive_query`），
+    调用方经模块全局名查找，patch 照常生效。
+"""
+
+from __future__ import annotations
+
+import functools
+import re
+
+__all__ = [
+    "normalize_query",
+    "query_similarity",
+    "split_qualifiers",
+    "is_freshness_sensitive_query",
+    "FRESHNESS_QUERY_RE",
+]
+
+
+@functools.lru_cache(maxsize=4096)
+def normalize_query(query: str) -> str:
+    """缓存键用查询归一化：折叠空白、全半角空格、两端 trim、小写英文字母。
+
+    不改变语义实体大小写敏感场景时仍用 lower；中文不受影响。
+    目标：同一问句不同空白/大小写命中同一 key。
+    """
+    if not query:
+        return ""
+    # 全角空格 → 半角；连续空白折叠
+    q = query.replace("\u3000", " ").strip()
+    q = re.sub(r"\s+", " ", q)
+    return q.casefold()
+
+
+# ── 近重复查询检测（minhash 字符 n-gram）────────────────────────────────────
+
+_NGRAM_N = 3
+# 置换数。**看起来偏低，但不要单独调它**——它与下游软命中阈值 0.7 是一套
+# 标定，动一个必须同时重标另一个，否则会把「检索上一年的缓存」放进来。
+#
+# 2026-09-19 实测记录（起因是「提到 32 更准」，结论是**保持 8 不改**）：
+# K=8 的估计确实有偏且方差大——四条中文对的真实 Jaccard 是
+# 0.275/0.444/0.500/0.375，K=8 估成 0.250/0.750/0.375/0.375（最大误差 0.306，
+# 双向发散）；换 32 后为 0.281/0.438/0.562/0.375，明显贴住真值。
+# 成本也不是障碍：`_signature` 带 lru_cache，比对是逐位比较（实测 0.41us/次，
+# 不随 K 变），提高 K 只增加一次性签名成本（K=8:0.171ms、K=32:0.832ms 每条
+# 查询，相对 1000–3000ms 的单次搜索可忽略）。
+#
+# 拦路石在**阈值**：0.7 正是照着 K=8 的偏高估计定的（下方 find_similar 的
+# docstring 写「单字差异约 0.75」，而真值只有 0.444）。把 K 提到 32 后，要维持
+# 原有软命中范围就得把阈值降到 ~0.35，而实测该阈值下
+#     苹果 2025 营收 ↔ 苹果 2024 营收 = 0.469 ≥ 0.35 → 命中
+# 即「今年的查询会命中去年的缓存」。这比「估计偏一点」严重得多——软命中的
+# 前提是结果集可互换，年份不同则不可互换。两侧一起保持原状。
+#
+# 要走这条路，正确顺序是先换能区分数字/年份的判据（词级或数字感知 shingle），
+# 再重标阈值；单独提 K 只是把偏差从「估计层」搬到「阈值层」。
+_MINHASH_PERM = 8  # 置换数（越多越准，越少越快；8 对查询级足够）
+
+
+def _ngrams(s: str, n: int = _NGRAM_N) -> set[str]:
+    """字符级 n-gram（中文按字，英文按字符，无需分词）。"""
+    s = re.sub(r"\s+", "", s)
+    return {s[i:i + n] for i in range(max(len(s) - n + 1, 1))}
+
+
+def _hash_token(t: str, seed: int) -> int:
+    """带种子的简单哈希（minhash 置换模拟）。"""
+    h = seed * 1315423911
+    for c in t:
+        h = (h ^ ord(c)) * 1099511628211 & 0xFFFFFFFFFFFFFFFF
+    return h
+
+
+@functools.lru_cache(maxsize=8192)
+def _signature(s: str) -> tuple[int, ...]:
+    """查询的 minhash 签名：每个置换下全部 n-gram 的最小哈希。
+
+    这是「查询 → 签名」的纯函数，按查询串记忆化。提出来的意义在于：
+    `query_similarity(q1, q2)` 会被拿去和缓存里**多条**候选比对，旧写法每次
+    都重算两边的签名——一次搜索实测 28,552 次 `_hash_token` 调用，绝大多数
+    是同一批 token 的重复置换。签名化后每条查询的签名全进程只算一次，
+    且比对本身从 O(K × |tokens|) 降到 O(K)（K=置换数=8）。
+    长驻进程（MCP server）里同一查询反复比对时收益为常数级。
+    """
+    grams = _ngrams(s)
+    if not grams:
+        return ()
+    return tuple(min(_hash_token(t, seed) for t in grams)
+                 for seed in range(_MINHASH_PERM))
+
+
+def query_similarity(q1: str, q2: str) -> float:
+    """两查询的字符 n-gram minhash 近似 Jaccard 相似度（0-1）。
+
+    中文「苹果 2025 营收」vs「苹果 2025 年营收」这类近重复查询
+    会得到高相似度（>0.7），用于语义缓存软命中。
+
+    实现 = 两个签名逐位置相等的比例（minhash 估计 Jaccard 的标准做法）。
+    """
+    a = _signature(q1)
+    b = _signature(q2)
+    if not a or not b:
+        return 0.0
+    hits = sum(1 for x, y in zip(a, b) if x == y)
+    return hits / _MINHASH_PERM
+
+
+# 结构化限定符（keywords:pi-package / site:zhihu.com / author:bcoe）。
+# 值里不含 `/` 是刻意的：URL 的 `https:` 因此不被当成限定符——fetch/evidence
+# 的 URL 近重复软命中（`.../x` 与 `.../x.md`，相似度 0.875）是既有的正确
+# 行为，不能被这次修复误伤。键以字母开头则排除 `10:30` 这类时间写法。
+_QUALIFIER_RE = re.compile(r"\b[A-Za-z][A-Za-z0-9_.-]*:[A-Za-z0-9_*.+-]+")
+
+
+def split_qualifiers(query: str) -> tuple[frozenset[str], str]:
+    """把查询拆成（限定符集合，载荷）。
+
+    限定符是**过滤器**而不是内容：两条查询的限定符集合不同，结果全集就不同，
+    再高的词面相似度也不构成可互换的理由。
+
+    为什么要拆：字符 n-gram 相似度会被长公共前缀主导。实测
+    `keywords:pi-package mcp` 与 `keywords:pi-package memory` 整串相似度
+    0.875（远超 0.7 阈值），而判别词只占几个字符——两条不同的检索需求被判成
+    近重复，软命中把 memory 的结果当成 mcp 的结果交了出去（2026-09-18 修复）。
+    拆开后比的是载荷（`mcp` vs `memory`，相似度 0.000），判据恢复有效。
+    """
+    text = query or ""
+    quals = frozenset(q.lower() for q in _QUALIFIER_RE.findall(text))
+    payload = re.sub(r"\s+", " ", _QUALIFIER_RE.sub(" ", text)).strip()
+    return quals, payload
+
+
+# 时效敏感查询正则：延迟编译（import 期编译正则对冷启动是纯税，见函数内判断）。
+FRESHNESS_QUERY_RE = None
+
+
+def is_freshness_sensitive_query(query: str) -> bool:
+    """检测查询是否时效敏感（今日/实时/盘中/快讯等）。"""
+    global FRESHNESS_QUERY_RE
+    if FRESHNESS_QUERY_RE is None:
+        FRESHNESS_QUERY_RE = re.compile(
+            r"(今日|今天|昨晚|昨夜|本周|本月|实时|即时|最新|刚刚|"
+            r"盘中|盘前|盘后|快讯|直播|热点新闻|头条|"
+            r"today|tonight|breaking|live\s*update|just\s*now|"
+            r"right\s*now|this\s*(morning|week|month))",
+            re.I,
+        )
+    return bool(FRESHNESS_QUERY_RE.search(query or ""))