argo-search 1.0.1 → 2.9.7

package/scripts/tfidf_router.py

@@ -25,6 +25,8 @@ from collections import Counter
 from pathlib import Path
 from typing import Optional
 
+import argo_paths as _paths
+
 # ── 路径 ──────────────────────────────────────────────────────────────────────
 
 SKILL_DIR = Path(__file__).parent.parent
@@ -33,18 +35,25 @@ DOMAIN_PROFILES_PATH = BACKENDS_DIR / "domain_profiles.json"
 
 # ── 分词 ──────────────────────────────────────────────────────────────────────
 
-_TOKEN_PATTERN = re.compile(r"[一-鿿]|[a-zA-Z0-9]+")
+_TOKEN_PATTERN = re.compile(r"[一-鿿\u3040-\u30ff\uac00-\ud7af]|[a-zA-Z0-9]+")
 
 
 def tokenize(text: str) -> list[str]:
-    """简单分词：中文单字 + 英文单词，统一小写。"""
+    """简单分词：中文/日文/韩文单字 + 英文单词，统一小写。
+
+    扩展 v2.8：并入假名（\\u3040-\\u30ff）与谚文（\\uac00-\\ud7af），否则韩/日
+    查询 tokenize 恒空、TF-IDF 语义路由对多语言整体失明。单字拉丁仍丢弃（词袋无关）。
+    """
     tokens = []
     for match in _TOKEN_PATTERN.finditer(text.lower()):
         token = match.group()
-        if len(token) == 1 and '一' <= token <= '鿿':
-            tokens.append(token)
-        elif len(token) > 1:
+        if len(token) > 1:
             tokens.append(token)
+        elif len(token) == 1:
+            ch = token[0]
+            if ('一' <= ch <= '鿿' or '\u3040' <= ch <= '\u30ff'
+                    or '\uac00' <= ch <= '\ud7af'):
+                tokens.append(ch)
     return tokens
 
 
@@ -100,43 +109,87 @@ def cosine_similarity(vec_a: dict[str, float], vec_b: dict[str, float]) -> float
     return dot / (norm_a * norm_b)
 
 
-# ── 配额感知 ──────────────────────────────────────────────────────────────────
+# ── 配额 / 成本（mtime 缓存，避免 route 每次为每个引擎读盘） ──────────────────
+
+_quota_state_cache: dict | None = None
+_quota_state_mtime: float = -1.0
+_cost_profiles_cache: dict | None = None
+_cost_profiles_mtime: float = -1.0
+
 
 def _load_quota_state() -> dict:
-    """加载配额状态文件。"""
-    quota_path = Path.home() / ".cache" / "unified-search" / "quota.json"
-    if not quota_path.exists():
+    """加载配额状态文件（mtime 缓存）。"""
+    global _quota_state_cache, _quota_state_mtime
+    quota_path = _paths.state_path("quota.json")
+    try:
+        mtime = quota_path.stat().st_mtime
+    except OSError:
         return {}
+    if _quota_state_cache is not None and mtime == _quota_state_mtime:
+        return _quota_state_cache
     try:
-        return json.loads(quota_path.read_text())
+        data = json.loads(quota_path.read_bytes())
     except (json.JSONDecodeError, OSError):
-        return {}
-
-
-def _quota_ratio(engine: str, quota_state: dict) -> float:
-    """计算配额剩余比例。返回 0.0-1.0，无记录时默认 1.0。"""
-    info = quota_state.get(engine)
-    if not info:
+        data = {}
+    _quota_state_cache = data if isinstance(data, dict) else {}
+    _quota_state_mtime = mtime
+    return _quota_state_cache
+
+
+def _quota_ratio(engine: str, quota_state: dict,
+                 profiles: dict | None = None) -> float:
+    """计算配额剩余比例。返回 0.0-1.0，无记录时默认 1.0。
+
+    limit 的唯一来源是 quota_profiles.json（声明文件）；配额状态文件里只有
+    用量计数。此前本函数只读 state["limit"]，而写入方（quota.record）恒填 0，
+    于是 limit<=0 走「无限配额」分支恒返回 1.0——配额感知惩罚（<0.2 砍到
+    2×qr、<0.5 乘 0.5+qr）从来没生效过。与 quota.get_remaining_ratio 的
+    profile.get("limit") 计算方式保持一致，缺省才回落到 state 里的值。
+    """
+    info = quota_state.get(engine) or {}
+    profile = (profiles if profiles is not None else _load_cost_profiles()).get(engine) or {}
+    limit = profile.get("limit")
+    if not isinstance(limit, (int, float)) or limit <= 0:
+        limit = info.get("limit")
+    if limit is None or limit <= 0:
+        # 无限配额 / 脏数据（limit=0）不当作耗尽
         return 1.0
-    limit = info.get("limit", 100)
-    used = info.get("used", 0)
-    return max(0, limit - used) / limit
+    used = info.get("used", 0) or 0
+    return max(0.0, float(limit - used) / float(limit))
 
 
-# ── 成本感知 ──────────────────────────────────────────────────────────────────
-
-def _cost_factor(engine: str) -> float:
-    """获取引擎成本因子：free=1.0, low=0.85, paid=0.6。"""
+def _load_cost_profiles() -> dict:
+    global _cost_profiles_cache, _cost_profiles_mtime
     tiers_path = BACKENDS_DIR / "quota_profiles.json"
-    if not tiers_path.exists():
-        return 1.0
     try:
-        profiles = json.loads(tiers_path.read_text())
+        mtime = tiers_path.stat().st_mtime
+    except OSError:
+        return {}
+    if _cost_profiles_cache is not None and mtime == _cost_profiles_mtime:
+        return _cost_profiles_cache
+    try:
+        data = json.loads(tiers_path.read_bytes())
     except (json.JSONDecodeError, OSError):
-        return 1.0
+        data = {}
+    _cost_profiles_cache = data if isinstance(data, dict) else {}
+    _cost_profiles_mtime = mtime
+    return _cost_profiles_cache
+
+
+def _cost_factor(engine: str, profiles: dict | None = None) -> float:
+    """获取引擎成本因子：free=1.0, low=0.85, paid=0.6。"""
+    if profiles is None:
+        profiles = _load_cost_profiles()
     profile = profiles.get(engine, {})
+    if not isinstance(profile, dict):
+        return 1.0
     tier = profile.get("cost_tier", "free")
-    return {"free": 1.0, "low": 0.85, "paid": 0.6}.get(tier, 1.0)
+    # 成本因子查 config 的唯一来源（此前本模块自带一张表，与 config 的值不一致）
+    try:
+        from config import _COST_FACTOR_BY_TIER
+        return _COST_FACTOR_BY_TIER.get(tier, 1.0)
+    except Exception:
+        return 1.0
 
 
 # ── 主路由引擎 ─────────────────────────────────────────────────────────────────
@@ -151,18 +204,34 @@ class SemanticRouter:
         self.boost_keywords: dict[str, dict[str, float]] = {}
         self.boost_combos: dict[str, dict[str, float]] = {}
         self._loaded = False
+        self._profiles_mtime: float = 0.0
 
     def _ensure_loaded(self) -> None:
-        """懒加载领域文档，只加载一次。"""
+        """懒加载领域文档；文件变化时自动重载。"""
         if self._loaded:
-            return
+            try:
+                mtime = DOMAIN_PROFILES_PATH.stat().st_mtime
+                if mtime == self._profiles_mtime:
+                    return
+            except OSError:
+                return
+            self._loaded = False
+            self.engine_names.clear()
+            self.engine_vectors.clear()
+            self.boost_keywords.clear()
+            self.boost_combos.clear()
         if not DOMAIN_PROFILES_PATH.exists():
             self._loaded = True
+            # mtime 一并复位：留着旧值的话，文件以原 mtime 还原（回收站恢复/
+            # 原子写回滚）时会被上面判成「未变化」，路由带着已清空的 vectors
+            # 永久空转——静默，无任何报错。
+            self._profiles_mtime = 0.0
             return
         try:
-            profiles = json.loads(DOMAIN_PROFILES_PATH.read_text())
+            profiles = json.loads(DOMAIN_PROFILES_PATH.read_bytes())
         except (json.JSONDecodeError, OSError):
             self._loaded = True
+            self._profiles_mtime = 0.0  # 同上：坏文件不占住旧 mtime
             return
 
         corpus = []
@@ -178,6 +247,7 @@ class SemanticRouter:
             self.vectorizer.fit(corpus)
             for i, name in enumerate(self.engine_names):
                 self.engine_vectors[name] = self.vectorizer.transform(corpus[i])
+        self._profiles_mtime = DOMAIN_PROFILES_PATH.stat().st_mtime
         self._loaded = True
 
     def route(self, query: str, top_k: int = 3,
@@ -194,6 +264,8 @@ class SemanticRouter:
         query_vec = self.vectorizer.transform(query)
         scores = []
         quota_state = _load_quota_state() if quota_aware else {}
+        cost_profiles = _load_cost_profiles()
+        q_lower = query.lower()  # 一次即可，避免每个引擎重复 lower
 
         for name in self.engine_names:
             sim = cosine_similarity(query_vec, self.engine_vectors[name])
@@ -203,7 +275,7 @@ class SemanticRouter:
             boost = 1.0
             hit_kws = []
             for kw, weight in self.boost_keywords.get(name, {}).items():
-                if kw.lower() in query.lower():
+                if kw.lower() in q_lower:
                     boost += weight - 1.0
                     hit_kws.append(kw)
             if hit_kws:
@@ -212,7 +284,7 @@ class SemanticRouter:
             # 组合关键词加成
             hit_combos = []
             for combo, bonus in self.boost_combos.get(name, {}).items():
-                if all(w.lower() in query.lower() for w in combo.split()):
+                if all(w.lower() in q_lower for w in combo.split()):
                     boost += bonus
                     hit_combos.append(combo)
             if hit_combos:
@@ -220,15 +292,15 @@ class SemanticRouter:
 
             final_score = sim * boost
 
-            # 成本感知
-            cf = _cost_factor(name)
+            # 成本感知（profiles 已缓存，不再每引擎读盘）
+            cf = _cost_factor(name, cost_profiles)
             if cf < 1.0:
                 final_score *= cf
                 parts.append(f"cost={cf}")
 
             # 配额感知惩罚
             if quota_aware and quota_state:
-                qr = _quota_ratio(name, quota_state)
+                qr = _quota_ratio(name, quota_state, cost_profiles)
                 if qr < 0.2:
                     final_score *= qr * 2
                     parts.append(f"配额紧张({qr:.0%})")

package/scripts/time_utils.py

@@ -0,0 +1,233 @@
+#!/usr/bin/env python3
+"""time_utils.py — 时间窗归一化与 published_at 解析的纯函数工具箱。
+
+从 search.py 中外提，解决 3351 行问题。本模块只含纯函数与编译好的正则，
+零重依赖（仅 datetime + re），可被路由/搜索/抓取/研究等层安全引用而不必
+担心循环导入或副作用。
+
+本模块是「时间语义」的唯一来源：
+  - published_at 解析 → published_ts
+  - 时间窗归一化 → parse_time_value / normalize_time_window
+  - 结果后过滤 → apply_time_window
+  - 排序 → sort_results_by_time
+  - 哪些引擎带时间能力 → TIME_CAPABLE_ENGINES / is_time_capable
+"""
+
+from __future__ import annotations
+
+import re
+from datetime import datetime, timedelta, timezone
+from typing import Any
+
+# published_at 常见形态：YYYY-MM-DD、YYYY-MM-DD HH:MM[:SS]、ISO(YYYY-MM-DDTHH:MM:SS)
+_DATE_RE = re.compile(
+    r"^(\d{4})-(\d{1,2})-(\d{1,2})(?:[ T](\d{1,2}):(\d{2})(?::(\d{2}))?)?"
+)
+# 相对时间：Nd / Nh / Nw（不区分大小写）
+_REL_TIME_RE = re.compile(r"^(\d+)\s*([dhw])$", re.IGNORECASE)
+# 纯日期 YYYY-MM-DD（until 边界含当天；下推保留日期形态）
+_DATE_ONLY_RE = re.compile(r"^\d{4}-\d{1,2}-\d{1,2}$")
+
+
+# 带发布时间能力（published_at）的引擎集合。时间窗的缓存键隔离与后过滤
+# 只对含这些引擎的组合生效：不带时间字段的引擎会忽略时间窗、结果相同，
+# 隔离缓存键只会白白降低命中率（7d/30d 查同一引擎本可共享缓存）。
+# local_search 聚合内部可能选中 news 类子引擎（带日期），保守纳入。
+TIME_CAPABLE_ENGINES: frozenset[str] = frozenset({
+    "realtime_index", "wayback_cdx", "local_search",
+    "local_bing_news", "local_google_news", "local_duckduckgo_news",
+    "local_ddgs_news",
+    # parallel（after_date 下推）/ you（freshness 动态化 + page_age）
+    "parallel", "you",
+    # deepseek_search：上游逐条返回 RFC 3339 date（output_map 映射
+    # published_at），日期覆盖率实测 3-5/5；缺了这一条时 --since/--until
+    # 对它静默无效（time_aware=False，后过滤整段跳过），日期最全的引擎
+    # 反而用不上时间窗。
+    "deepseek_search",
+})
+
+
+def is_time_capable(eng: str) -> bool:
+    """引擎是否可能返回 published_at（决定时间窗是否参与缓存键/后过滤）。"""
+    return eng in TIME_CAPABLE_ENGINES
+
+
+def published_ts(r: dict[str, Any]) -> float | None:
+    """解析结果的 published_at → epoch 秒；无法解析返回 None（恒排最后）。
+
+    ISO 优先（fromisoformat 支持 T/空格分隔、Z、±HH:MM 时区），
+    带时区正确换算 epoch，无时区按本地时区解释；回退 YYYY-MM-DD 手工解析。
+    """
+    raw = r.get("published_at")
+    if not raw:
+        return None
+    text = str(raw).strip()
+    if text.isdigit():  # 部分引擎给 epoch 秒时间戳
+        try:
+            return float(text)
+        except ValueError:
+            return None
+    try:
+        dt = datetime.fromisoformat(text.replace("Z", "+00:00"))
+        # aware datetime 正确换算 UTC epoch；naive 按本地时区解释
+        return dt.timestamp()
+    except ValueError:
+        pass
+    # basic ISO（YYYYMMDDTHHMMSSZ，如 GDELT seendate）：Python 3.10 的
+    # fromisoformat 不认，插入分隔符归一化成扩展格式再走同一解析
+    if len(text) >= 15 and text[:8].isdigit() and text[8] == "T" and text[9:15].isdigit():
+        try:
+            dt = datetime.fromisoformat(
+                f"{text[:4]}-{text[4:6]}-{text[6:8]}"
+                f"T{text[9:11]}:{text[11:13]}:{text[13:15]}+00:00")
+            return dt.timestamp()
+        except ValueError:
+            pass
+    m = _DATE_RE.match(text)
+    if not m:
+        return None
+    try:
+        return datetime(
+            int(m.group(1)), int(m.group(2)), int(m.group(3)),
+            int(m.group(4) or 0), int(m.group(5) or 0), int(m.group(6) or 0),
+        ).timestamp()
+    except ValueError:
+        return None
+
+
+def parse_time_value(value: Any) -> tuple[str | None, float | None]:
+    """解析单边时间窗 → (归一化 ISO 字符串, epoch 秒)。
+
+    支持：相对量（Nd/Nh/Nw）、YYYY-MM-DD、YYYY-MM-DD HH:MM[:SS]、
+    ISO 8601（含 Z / ±HH:MM）、纯数字 epoch 秒。
+    相对量归一化为绝对日期（YYYY-MM-DD），语义确定、可入缓存键；
+    无法解析返回 (None, None)，调用方保持原样下推、不参与后过滤。
+    """
+    if value in (None, ""):
+        return None, None
+    text = str(value).strip()
+    # epoch 秒
+    if text.isdigit():
+        try:
+            ts = float(text)
+            dt = datetime.fromtimestamp(ts, tz=timezone.utc)
+            return dt.isoformat(timespec="seconds"), ts
+        except (ValueError, OSError):
+            return None, None
+    # 相对量：Nd / Nh / Nw → 绝对日期（本地时区零点）
+    m = _REL_TIME_RE.match(text)
+    if m:
+        amount = int(m.group(1))
+        unit = m.group(2).lower()
+        now = datetime.now()
+        if unit == "h":
+            dt = now - timedelta(hours=amount)
+        elif unit == "w":
+            dt = now - timedelta(weeks=amount)
+        else:
+            dt = now - timedelta(days=amount)
+        d = dt.date()
+        return d.isoformat(), datetime(d.year, d.month, d.day).timestamp()
+    # 绝对时间：fromisoformat 优先（T/空格分隔、Z、±HH:MM）
+    try:
+        dt = datetime.fromisoformat(text.replace("Z", "+00:00"))
+    except ValueError:
+        return None, None
+    if dt.tzinfo is not None:
+        return dt.isoformat(timespec="seconds"), dt.timestamp()
+    # 无时区：按本地时区（与 published_ts 无时区行为一致）；
+    # 纯日期（时间为零点）保留 YYYY-MM-DD 形态下推，兼容引擎既有解析
+    if (dt.hour, dt.minute, dt.second, dt.microsecond) == (0, 0, 0, 0):
+        return dt.date().isoformat(), dt.timestamp()
+    return dt.isoformat(timespec="seconds"), dt.timestamp()
+
+
+#: 时间窗接受的写法（给用户看的唯一一份说明；CLI 的 argparse 与 MCP 的错误行
+#: 都从这里取，避免「文档说支持 2w、代码其实只认 d」这类漂移）。
+WINDOW_FORMATS_HINT = (
+    "支持 7d/24h/2w、2026-09-01、2026-09-01 12:00、"
+    "ISO 8601（含 Z / ±HH:MM）或 epoch 秒")
+
+
+def is_valid_time_window(value: Any) -> bool:
+    """入参能否解析成时间窗（判据与 `parse_time_value` 同源，不另写一套正则）。
+
+    why：此前非法值被**静默接受**——`--since garbage` 原样回显在响应里、
+    `time_filtered=0`、没有任何说明，调用方以为自己拿到了筛过的结果。
+    这是「静默不生效」里最坏的一种：不是少了一层增强，而是**答案被当成
+    已经筛过的**（同一条查询用 `--since 2026-09-01` 与 `--since garbage`
+    拿到同一批结果，且无从分辨）。
+    """
+    if value in (None, ""):
+        return True  # 没给就是没给，不是坏值
+    _iso, ts = parse_time_value(value)
+    return ts is not None
+
+
+def normalize_time_window(
+    since: str | None, until: str | None
+) -> tuple[str | None, str | None, float | None, float | None]:
+    """归一化时间窗 → (since_iso, until_iso, since_ts, until_ts)。
+
+    下推与缓存键使用归一化 ISO（相对值转绝对日期，消除 7d 与绝对日期的
+    缓存碎片）；后过滤使用 epoch 秒。非法输入 iso 保留原始字符串、
+    ts 为 None：仍会下推原值、缓存键仍区分，但不参与后过滤，不阻断搜索。
+    """
+    s_iso, s_ts = parse_time_value(since)
+    u_iso, u_ts = parse_time_value(until)
+    # 纯日期 until 语义为「含当天」：边界取当天最后一刻，
+    # 使次日零点及之后的结果被剔除、当天 23:59:59 保留
+    if u_iso and _DATE_ONLY_RE.fullmatch(u_iso):
+        try:
+            d = datetime.fromisoformat(u_iso).date()
+            u_ts = datetime(d.year, d.month, d.day, 23, 59, 59, 999999).timestamp()
+        except ValueError:
+            pass
+    s_raw = str(since).strip() if since not in (None, "") else None
+    u_raw = str(until).strip() if until not in (None, "") else None
+    return (s_iso or s_raw, u_iso or u_raw, s_ts, u_ts)
+
+
+def apply_time_window(
+    results: list[dict[str, Any]], since_ts: float | None, until_ts: float | None
+) -> tuple[list[dict[str, Any]], int]:
+    """结果后过滤保底：剔除「有 published_at 且明确超窗」的条目。
+
+    宽松策略：无时间字段的结果无法判断、予以保留（避免大多数引擎清空）；
+    只有时间明确落在窗口外的才剔除。返回 (保留列表, 剔除数) 供 envelope 上报。
+    """
+    if since_ts is None and until_ts is None:
+        return results, 0
+    kept: list[dict[str, Any]] = []
+    dropped = 0
+    for r in results:
+        ts = published_ts(r)
+        if ts is not None:
+            if since_ts is not None and ts < since_ts:
+                dropped += 1
+                continue
+            if until_ts is not None and ts > until_ts:
+                dropped += 1
+                continue
+        kept.append(r)
+    return kept, dropped
+
+
+def sort_results_by_time(results: list[dict[str, Any]], sort: str) -> list[dict[str, Any]]:
+    """按时间重排结果集：oldest 升序 / newest 降序 / relevance 原序。
+
+    排序是纯本地展示顺序：不改变结果集、不进入缓存键、不影响缓存内容；
+    无日期条目恒排最后；同时间保持原相对顺序（稳定排序，结果可复现）。
+    """
+    if sort not in ("oldest", "newest"):
+        return results
+    if len(results) <= 1:
+        return results
+
+    def _key(r: dict[str, Any]) -> tuple[int, float]:
+        ts = published_ts(r)
+        if ts is None:
+            return (1, 0.0)  # 无日期恒排最后
+        return (0, ts if sort == "oldest" else -ts)
+
+    return sorted(results, key=_key)