argo-search 2.9.7 → 2.9.9

package/scripts/budget.py

@@ -0,0 +1,247 @@
+#!/usr/bin/env python3
+"""budget.py — 按引擎的月度预算（原生币种）。
+
+为什么需要（2026-10-21）：`quota.py` 的额度是**次数**（limit/used），而付费引擎
+（DeepSeek、Tavily 等）的真实约束是**钱**。按次数换算会在单价变化时失真，也会
+把「失败调用」算成花费（DeepSeek 只对成功请求计费）。本模块只做三件事：
+
+1. 读取预算（默认 → 共享文件 → env 覆盖），不碰配额状态；
+2. 把预算挂到 `quota.py` 的 profile 上（budget_amount / budget_currency / period）；
+3. 提供 `argo budget set|list|unset` 的存储原语。
+
+存储位置：`~/.config/argo/budgets.json`（POSIX）或 `%APPDATA%\\argo\\budgets.json`
+（Windows），与 `~/.config/argo/env` 同根；`ARGO_BUDGET_FILE` 可覆盖（测试/多环境）。
+格式：
+
+    {"deepseek_search": {"amount": 5.0, "currency": "CNY", "period": "month"}}
+
+env 覆盖（优先级高于文件，便于插件/临时实验）：
+  - `ARGO_BUDGETS_JSON`：整份 JSON（最高）
+  - `ARGO_BUDGET_<ENGINE>`：单引擎金额（币种按引擎 cost_unit，缺省 CNY；周期 month）
+
+默认只给 DeepSeek 一个月度体验额度（¥5 ≈ 1000 次成功调用）；其他引擎默认不设，
+沿用各自 quota_profiles.json 里的既有额度，符合「其他默认不改」。
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+__all__ = [
+    "DEFAULT_BUDGETS",
+    "budget_file",
+    "budget_signature",
+    "load_budgets",
+    "budget_for",
+    "apply_to_profiles",
+    "set_budget",
+    "unset_budget",
+]
+
+# 默认预算：只覆盖 DeepSeek。金额按人民币；折算依据是官方 5 元/千次成功请求。
+DEFAULT_BUDGETS: dict[str, dict[str, Any]] = {
+    "deepseek_search": {"amount": 5.0, "currency": "CNY", "period": "month"},
+}
+
+_ENV_JSON = "ARGO_BUDGETS_JSON"
+_ENV_FILE = "ARGO_BUDGET_FILE"
+_ENV_PREFIX = "ARGO_" + "BUDGET_"
+
+# 单引擎 env 覆盖的默认币种（金额单位必须与引擎 cost_unit 对齐，否则预算
+# 与 cost_used 是两个币种在比大小）。未列出的引擎按 CNY，与历史行为一致。
+_ENV_CURRENCY = {
+    "deepseek_search": "CNY",
+    "exa": "USD",
+    "tavily": "USD",
+}
+
+
+def budget_file() -> Path:
+    """预算文件路径（不保证存在）。"""
+    override = (os.environ.get(_ENV_FILE) or "").strip()
+    if override:
+        return Path(os.path.expanduser(override))
+    if os.name == "nt":
+        base = (os.environ.get("APPDATA") or "").strip() or os.path.expanduser("~")
+    else:
+        base = (os.environ.get("XDG_CONFIG_HOME") or "").strip() or os.path.expanduser("~/.config")
+    return Path(base) / "argo" / "budgets.json"
+
+
+def _valid(entry: Any) -> dict[str, Any] | None:
+    """校验并归一一条预算；坏条目返回 None（不阻断其他引擎）。"""
+    if not isinstance(entry, dict):
+        return None
+    try:
+        amount = float(entry.get("amount"))
+    except (TypeError, ValueError):
+        return None
+    if amount < 0:
+        return None
+    currency = str(entry.get("currency") or "CNY").strip().upper() or "CNY"
+    period = str(entry.get("period") or "month").strip().lower()
+    if period not in ("day", "month"):
+        period = "month"
+    return {"amount": amount, "currency": currency, "period": period}
+
+
+def _read_file() -> dict[str, dict[str, Any]]:
+    try:
+        raw = json.loads(budget_file().read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return {}
+    if not isinstance(raw, dict):
+        return {}
+    out: dict[str, dict[str, Any]] = {}
+    for engine, entry in raw.items():
+        if str(engine).startswith("_"):
+            continue
+        norm = _valid(entry)
+        if norm is not None:
+            out[str(engine)] = norm
+    return out
+
+
+def _read_env() -> dict[str, dict[str, Any]]:
+    out: dict[str, dict[str, Any]] = {}
+    raw = (os.environ.get(_ENV_JSON) or "").strip()
+    if raw:
+        try:
+            parsed = json.loads(raw)
+        except ValueError:
+            parsed = None
+        if isinstance(parsed, dict):
+            for engine, entry in parsed.items():
+                norm = _valid(entry)
+                if norm is not None:
+                    out[str(engine)] = norm
+    # 单引擎便捷覆盖："ARGO_BUDGET_DEEPSEEK_SEARCH"=5 → deepseek_search 5 CNY/月。
+    # 同族命名 ARGO_BUDGET_<ENGINE> 由下面按前缀解析；字面量保留给插件门禁对拍。
+    # 只认「大写化后能在默认/文件里找到的引擎」太窄；这里按环境变量名反推引擎名，
+    # 由调用方（quota）决定是否真的存在该引擎，避免拼错静默生效。
+    for key, value in os.environ.items():
+        if not key.startswith(_ENV_PREFIX) or key in (_ENV_JSON, _ENV_FILE):
+            continue
+        engine = key[len(_ENV_PREFIX):].strip().lower()
+        if not engine:
+            continue
+        try:
+            amount = float(str(value).strip())
+        except (TypeError, ValueError):
+            continue
+        if amount < 0:
+            continue
+        currency = (out.get(engine) or {}).get("currency") \
+            or _ENV_CURRENCY.get(engine, "CNY")
+        entry = {"amount": amount, "currency": currency, "period": "month"}
+        out[engine] = entry
+    return out
+
+
+def budget_signature() -> tuple[Any, ...]:
+    """预算配置源的轻量签名（文件 mtime/size + 环境变量覆盖），供热读与路由缓存换键。"""
+    p = budget_file()
+    try:
+        st = p.stat()
+        f_sig: tuple[Any, ...] = (st.st_mtime_ns, st.st_size)
+    except OSError:
+        f_sig = (0, 0)
+    return (
+        f_sig,
+        os.environ.get(_ENV_JSON, ""),
+        os.environ.get("ARGO_BUDGET_DEEPSEEK_SEARCH", ""),
+        os.environ.get("ARGO_BUDGET_EXA", ""),
+    )
+
+
+def load_budgets() -> dict[str, dict[str, Any]]:
+    """默认 → 文件 → env，逐层覆盖。"""
+    merged: dict[str, dict[str, Any]] = {k: dict(v) for k, v in DEFAULT_BUDGETS.items()}
+    merged.update(_read_file())
+    merged.update(_read_env())
+    return merged
+
+
+def budget_for(engine: str) -> dict[str, Any] | None:
+    return load_budgets().get(str(engine))
+
+
+def apply_to_profiles(profiles: dict[str, dict[str, Any]]) -> None:
+    """把预算挂到 quota profile（就地）。只覆盖存在的引擎，拼错不生效。"""
+    active = load_budgets()
+    for engine, spec in profiles.items():
+        if not isinstance(spec, dict) or str(engine).startswith("_"):
+            continue
+        entry = active.get(engine)
+        if entry is not None:
+            spec["budget_amount"] = entry["amount"]
+            spec["budget_currency"] = entry["currency"]
+            # 预算周期即重置周期；与 limit 共用同一条 `period`，避免两套时钟。
+            spec["period"] = entry["period"]
+        else:
+            spec.pop("budget_amount", None)
+            spec.pop("budget_currency", None)
+
+
+def _write(data: dict[str, Any]) -> None:
+    path = budget_file()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_suffix(path.suffix + ".tmp")
+    tmp.write_text(json.dumps(data, ensure_ascii=False, indent=2, sort_keys=True) + "\n",
+                   encoding="utf-8")
+    os.replace(tmp, path)
+
+
+def over_budget_error(engine: str) -> str | None:
+    """预算耗尽时返回可行动错误文本；未耗尽/未配预算/读失败返回 None。
+
+    放在 budget.py 而不是 dispatch：engine_dispatch 有行数门禁，预算检查是
+    「读状态 + 拼一句话」的纯策略，搬出来也让显式/自动路径共用同一文案。
+    """
+    try:
+        from engine_env import env_flag
+        if env_flag("ARGO_PAID_BUDGET_BYPASS", default=False):
+            return None
+    except Exception:
+        if (os.environ.get("ARGO_PAID_BUDGET_BYPASS", "").strip().lower()
+                in ("1", "true", "yes", "on")):
+            return None
+    try:
+        from quota import get_quota_manager
+        qm = get_quota_manager()
+        # 只认真正的 True：测试常把 quota manager 打成 MagicMock，属性调用
+        # 会返回真值 mock——不能把「mock 存在」当成预算耗尽。
+        if qm.is_over_budget(engine) is not True:
+            return None
+        st = (qm.budget_status(engine) if hasattr(qm, "budget_status")
+              else (qm.get_stats().get(engine) or {}))
+        return (f"本月预算已用完（{st.get('cost_used', 0)}/{st.get('budget')} "
+                f"{st.get('budget_currency') or ''}）；"
+                f"可用 ARGO_PAID_BUDGET_BYPASS=1 单次放行")
+    except Exception:
+        return None
+
+
+def set_budget(engine: str, amount: float, *, currency: str = "CNY",
+               period: str = "month") -> dict[str, Any]:
+    """写入一条预算（保留文件里其他引擎）。返回归一后的条目。"""
+    norm = _valid({"amount": amount, "currency": currency, "period": period})
+    if norm is None:
+        raise ValueError("预算金额必须是非负数")
+    data = _read_file()
+    data[str(engine)] = norm
+    _write(data)
+    return norm
+
+
+def unset_budget(engine: str) -> bool:
+    """删除一条预算；返回是否真的删了。"""
+    data = _read_file()
+    if engine not in data:
+        return False
+    data.pop(engine, None)
+    _write(data)
+    return True

package/scripts/budget_cli.py

@@ -0,0 +1,93 @@
+#!/usr/bin/env python3
+"""budget_cli.py — `argo budget`：按引擎的月度预算读写口。
+
+用法：
+  argo budget list [--json]
+  argo budget set <engine> <amount> [--currency CNY|USD] [--period month|day]
+  argo budget unset <engine>
+
+预算存在 ~/.config/argo/budgets.json（`ARGO_BUDGET_FILE` 可覆盖）；`quota.py`
+启动时读取，按引擎原生币种与调用成本比较。默认只有 DeepSeek ¥5/月。
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+import budget
+from cli_io import dumps
+
+
+def _cmd_list(args: argparse.Namespace) -> int:
+    items = budget.load_budgets()
+    try:
+        from quota import get_quota_manager
+        stats = get_quota_manager().get_stats()
+    except Exception:
+        stats = {}
+    rows = []
+    for engine, entry in sorted(items.items()):
+        st = stats.get(engine) or {}
+        rows.append({
+            "engine": engine,
+            "amount": entry["amount"],
+            "currency": entry["currency"],
+            "period": entry["period"],
+            "cost_used": st.get("cost_used"),
+            "cost_per_call": st.get("cost_per_call"),
+            "available": st.get("available"),
+        })
+    if args.json:
+        print(dumps({"file": str(budget.budget_file()), "budgets": rows}))
+    else:
+        print(f"预算文件：{budget.budget_file()}")
+        if not rows:
+            print("（无预算；引擎沿用 quota_profiles.json 的次数额度）")
+        for r in rows:
+            print(f"  {r['engine']:<20} {r['amount']:>8.2f} {r['currency']}/"
+                  f"{r['period']}  已用 {r['cost_used']}  可用={r['available']}")
+    return 0
+
+
+def _cmd_set(args: argparse.Namespace) -> int:
+    try:
+        entry = budget.set_budget(args.engine, args.amount,
+                                  currency=args.currency,
+                                  period=args.period)
+    except ValueError as exc:
+        print(f"设置失败：{exc}", file=sys.stderr)
+        return 2
+    print(f"已设置 {args.engine}: {entry['amount']} {entry['currency']}/{entry['period']}"
+          f"（{budget.budget_file()}）")
+    return 0
+
+
+def _cmd_unset(args: argparse.Namespace) -> int:
+    ok = budget.unset_budget(args.engine)
+    print(("已删除 " if ok else "未找到 ") + args.engine)
+    return 0 if ok else 1
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(prog="argo budget",
+                                 description="按引擎的月度预算（原生币种）")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    p_list = sub.add_parser("list", help="列出预算与本月已用")
+    p_list.add_argument("--json", action="store_true")
+    p_list.set_defaults(func=_cmd_list)
+    p_set = sub.add_parser("set", help="设置某引擎预算")
+    p_set.add_argument("engine")
+    p_set.add_argument("amount", type=float)
+    p_set.add_argument("--currency", default="CNY")
+    p_set.add_argument("--period", default="month", choices=["day", "month"])
+    p_set.set_defaults(func=_cmd_set)
+    p_unset = sub.add_parser("unset", help="删除某引擎预算")
+    p_unset.add_argument("engine")
+    p_unset.set_defaults(func=_cmd_unset)
+    args = ap.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/build_release_assets.sh

@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+# 构建 Argo Release 资产包（tar.gz、wheel 与 sha256 校验和）
+#
+# 用法：
+#   bash scripts/build_release_assets.sh
+#   产物输出至 dist/ 目录。
+
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$ROOT_DIR"
+
+VERSION=$(python3 -c 'import json; print(json.load(open("package.json"))["version"])')
+DIST_DIR="$ROOT_DIR/dist"
+STAGE_DIR="$DIST_DIR/argo-$VERSION"
+
+echo "==> 开始构建 Argo Release 资产包 (v$VERSION)..."
+rm -rf "$DIST_DIR"
+mkdir -p "$DIST_DIR" "$STAGE_DIR"
+
+# 1. 拷贝运行时必需核心文件至 staging 目录（排除测试/缓存/私有数据）
+echo "--> 组织源码资产..."
+cp -r bin config.yaml engines backends data mcp scripts sub-skills README.md SKILL.md LICENSE package.json pyproject.toml "$STAGE_DIR/"
+
+# 清理 staging 内的多余缓存与测试
+find "$STAGE_DIR" -type d -name "__pycache__" -exec rm -rf {} + 2>/dev/null || true
+find "$STAGE_DIR" -name "*.pyc" -delete 2>/dev/null || true
+rm -rf "$STAGE_DIR/data/jobs" 2>/dev/null || true
+find "$STAGE_DIR/sub-skills" -type d -name "tests" -exec rm -rf {} + 2>/dev/null || true
+find "$STAGE_DIR/sub-skills" -type d -name "__pycache__" -exec rm -rf {} + 2>/dev/null || true
+
+# 2. 打包 tar.gz
+TARBALL="$DIST_DIR/argo-v$VERSION.tar.gz"
+echo "--> 生成源码压缩包: $TARBALL"
+tar -czf "$TARBALL" -C "$DIST_DIR" "argo-$VERSION"
+
+# 3. 如果环境已安装 build 模块，打出标准 Python wheel。
+# wheel 的运行树来自 staging：构建前复制到 argo_search/_data，构建后清理。
+# 这样 pip/uvx 安装后 console script 仍能找到 config/engines/sub-skills。
+if python3 -c 'import build' 2>/dev/null; then
+    echo "--> 构建 Python Wheel 与 Sdist..."
+    PKG_DATA="$ROOT_DIR/argo_search/_data"
+    rm -rf "$PKG_DATA"
+    cp -r "$STAGE_DIR" "$PKG_DATA"
+    python3 -m build --outdir "$DIST_DIR"
+    rm -rf "$PKG_DATA"
+elif python3 -c 'import setuptools, wheel' 2>/dev/null; then
+    echo "--> 使用 setuptools 构建 Wheel..."
+    python3 setup.py bdist_wheel --dist-dir "$DIST_DIR" 2>/dev/null || true
+fi
+rm -rf "$STAGE_DIR"
+
+# 4. 生成 SHA256 校验和清单
+echo "--> 计算 SHA256 校验和..."
+(
+    cd "$DIST_DIR"
+    if command -v sha256sum >/dev/null 2>&1; then
+        sha256sum * > SHA256SUMS.txt
+    elif command -v shasum >/dev/null 2>&1; then
+        shasum -a 256 * > SHA256SUMS.txt
+    fi
+)
+
+echo "==> 构建完成！Release 资产清单:"
+ls -lh "$DIST_DIR"

package/scripts/cache.py

@@ -354,7 +354,17 @@ class SQLiteCache:
                     pass
 
     def _init_db(self):
+        if (self._db_path not in (":memory:", "")
+                and not self._db_path.startswith("file:")
+                and os.path.exists(self._db_path)
+                and not os.access(self._db_path, os.W_OK)):
+            raise _get_sqlite3().OperationalError("readonly database")
         with self._conn() as conn:
+            try:
+                if conn.execute("SELECT value FROM meta WHERE key='schema_version'").fetchone() == (str(self.SCHEMA_VERSION),):
+                    return
+            except _get_sqlite3().Error:
+                pass
             conn.executescript("""
                 CREATE TABLE IF NOT EXISTS search_cache (
                     key TEXT PRIMARY KEY,
@@ -463,6 +473,20 @@ class SQLiteCache:
                 self._hits += 1
                 return self._deserialize(value_blob, compressed)
 
+    def get_many(self, keys: list[str]) -> dict[str, dict]:
+        if not keys or self._degraded_reason is not None:
+            return {}
+        out: dict[str, dict] = {}
+        with self._lock, self._conn() as conn:
+            ph = ",".join("?" for _ in keys)
+            for k, blob, comp, ts, ttl in conn.execute(
+                f"SELECT key, value_blob, compressed, created_at, ttl "
+                f"FROM search_cache WHERE key IN ({ph})", tuple(keys)
+            ):
+                if not self._is_expired(ts, ttl):
+                    out[k] = self._deserialize(blob, comp)
+        return out
+
     def set(self, key: str, query: str, engine: str, max_results: int,
             value: dict, domain: str = "general", ttl: int | None = None,
             mode: str = "", depth: str = ""):
@@ -516,35 +540,9 @@ class SQLiteCache:
             pass
 
     def _evict_if_needed(self):
-        """空间回收三步：过期行 → LRU 淘汰 → VACUUM。
-
-        **历史 bug（2026-09-19 复现）**：判定读的是文件页数
-        （page_count × page_size），扣减的却是 payload 净长。而本库
-        `auto_vacuum=0` 且全仓无 VACUUM，页数**永不下降**——库一旦超过
-        MAX_DB_SIZE_MB，`while total_bytes > target_bytes` 就永不收敛：
-        每次 set() 把整库（含刚写入的那一行）删空，此后每次写入重复清空，
-        缓存永久 100% miss。修法是让扣减与判定同源——进入淘汰循环后一律
-        用 payload 口径，删完再 VACUUM 把文件真正缩回去（不 VACUUM 的话
-        下一轮 set() 会看到同样的页数并重删一遍，正是这个 bug 的另一半）。
-
-        另一半是**过期行**：它们对任何调用方都不可见（get() 命中即删），
-        实测线上 5521 行里 5444 行（98.6%）已过期、占 payload 的 98.3%。
-        不回收不只是占盘——find_similar 与淘汰扫描都要扫过这些永不命中的行。
-        按节流间隔回收，稳态每小时一次。
-
-        阈值口径（2026-10-15）：limit 取 `self._max_size_mb`（构造时定下），
-        不再直接读模块常量 MAX_DB_SIZE_MB——生产侧的上限现在来自 config.yaml
-        的 `cache.max_size_mb`，改配置真的会改行为。
-        """
+        """空间回收三步：过期行清扫（每小时节流）→ LRU 淘汰（按 payload 口径）→ VACUUM。"""
         with self._conn() as conn:
             limit_bytes = self._max_size_mb * 1024 * 1024
-
-            # 三条触发各自独立，代价都是 O(1)：
-            #   过期清扫（节流到每小时一次，因为它要全表扫）
-            #   LRU 淘汰（文件超限时）
-            #   纯回收（空闲页够多时——清扫刚删完一大片就会命中这条，
-            #          不把它独立出来，回收就会被节流挡到下一个清扫点，
-            #          文件白停在高水位一小时）
             if self._expiry_sweep_due(conn):
                 conn.execute(
                     "DELETE FROM search_cache WHERE created_at + ttl < ?",
@@ -557,7 +555,6 @@ class SQLiteCache:
                 "      * (SELECT page_size  FROM pragma_page_size)"
             ).fetchone()[0] or 0
             if page_bytes > limit_bytes:
-                # 按最近访问时间淘汰最旧行；扣减口径与判定同源，循环必然收敛
                 target_bytes = int(limit_bytes * 0.8)
                 payload = conn.execute(
                     "SELECT COALESCE(SUM(LENGTH(value_blob)), 0) FROM search_cache"
@@ -574,9 +571,6 @@ class SQLiteCache:
                     payload -= sum((sz or 0) for _, sz in rows)
                     conn.commit()
 
-            # 删行不会让文件变小：页进 freelist，文件停在高水位。不回收的话
-            # 稳态下会留着一整块「只有空闲页」的库——实测线上 10.1MB 文件里
-            # 活数据只有 0.12MB。判据用空闲页占比而非固定字节：小库才会回收。
             if self._free_bytes(conn) > self._RECLAIM_FREE_RATIO * (page_bytes or 1):
                 conn.execute("VACUUM")
 
@@ -603,42 +597,11 @@ class SQLiteCache:
                      mode: str = "auto", depth: str = "fast") -> list[dict]:
         """近重复查询软命中：扫描最近缓存，minhash 相似度 ≥ threshold 的条目。
 
-        返回 [{key, query, similarity}]，按相似度降序。用于语义缓存——
-        「苹果 2025 营收」可软命中「苹果 2025 年营收」的缓存。
-        扫描限制 limit 条最近查询，控制成本。
-
-        阈值 0.7：中文字符级 n-gram 下，「营收」vs「年营收」这类
-        单字差异相似度约 0.75，0.7 可捕捉近重复且排除无关查询（≈0）。
-
-        engine 隔离（v2.4.2 修复）：SQL 必须按 engine 列过滤。此前形参收了
-        engine 但 WHERE 子句只用 domain，软命中因此跨引擎串味——实测
-        `--engine v2ex` 可命中 bilibili 缓存；fetch 与 evidence 同 domain 下
-        URL 词面相似（如 x 与 x.md，相似度 0.875）会互相串正文。
-        组合键（多引擎拼接的 `a+b`）不参与软命中：组合结果集是融合产物，
-        与任何单引擎缓存都不可互换。
-
-        **engine 现在是精确匹配，不再是「auto 通配」**（2026-09-19 随之调整）：
-        engine 列从「路由出来的引擎组合」改存「请求侧身份」（用户点名的引擎
-        或 auto，见 search.execute_search 的 cache_engine_key 说明）。语义变了，
-        通配的含义也跟着变——以前 `auto` 不是列里会出现的值，通配分支其实
-        从未被走到（组合列要么是 `a+b` 要么是单引擎名）；现在 `auto` 是真实的
-        请求身份，再通配就等于让「自动路由」的请求去吃「显式指定 pypi」的
-        缓存，正是 v2.4.2 要挡的跨引擎串味。请求不同 → 结果不可互换。
-
-        限定符隔离（2026-09-18 修复）：限定符是过滤器而非内容，整串相似度
-        会被它主导——`keywords:pi-package mcp` 与 `keywords:pi-package
-        memory` 整串相似度 0.875，判别词只占几个字符，于是软命中把另一条
-        查询的结果交了出去（实测 `--engine npm` 查 mcp 拿到 memory 那批包）。
-        现在先要求限定符集合相同，再比**载荷**的相似度；无限定符的查询载荷
-        即整串，行为不变。
-
-        mode/depth 隔离（2026-09-19 修复）：这是同一类串味的第三处，前两处
-        （engine、限定符）修的时候漏了它。`_key` 刻意把 mode/depth 编进键、
-        类 docstring 也承诺「depth / mode 隔离，防 fast/deep、budget 污染」，
-        但软命中的 WHERE 只有 domain+engine：`--depth deep` 请求会软命中一条
-        按 fast 写的条目（或反过来），拿到的结果集与请求档位不匹配，而结果里
-        还报 `cached: true`。现在 WHERE 带上 mode/depth 精确匹配——它们本来
-        就是「结果集全集的组成部分」，与限定符同理：档位不同，结果就不可互换。
+        返回 [{key, query, similarity}]，按相似度降序。
+        隔离契约：
+          - engine 精确匹配（多引擎组合 a+b / a,b 不参与软命中）
+          - 限定符集合必须一致，仅对载荷计算相似度
+          - domain / mode / depth 精确匹配
         """
         nq = normalize_query(query)
         nq_quals, nq_payload = split_qualifiers(nq)
@@ -847,6 +810,7 @@ class SearchCache:
         self._l1 = LRUCache(max_size=MAX_MEMORY_ITEMS)
         self._l2 = SQLiteCache(db_path=self._db_path, ttl=self._ttl,
                                max_size_mb=self._max_size_mb)
+        self._miss_memo: tuple[float, frozenset[str]] = (0.0, frozenset())
 
     @staticmethod
     def _key(query: str, engine: str, max_results: int = 0, domain: str = "general",
@@ -931,6 +895,8 @@ class SearchCache:
                 out["_cache_level"] = "L1"
                 return out
             self._l1.remove(key)
+        if time.monotonic() - self._miss_memo[0] < 0.05 and key in self._miss_memo[1]:
+            return None
 
         hit = self._l2.get(key)
         if hit is not None:
@@ -942,11 +908,32 @@ class SearchCache:
             return out
         return None
 
+    def _read_many(self, keys: list[str]) -> dict[str, dict]:
+        if not keys or self._disabled():
+            return {}
+        out, miss, now = {}, [], time.time()
+        for k in dict.fromkeys(keys):
+            hit = self._l1.get(k)
+            if hit is not None and hit.get("_ttl", 0) > 0 and now - hit.get("_ts", 0) < hit.get("_ttl", 0):
+                out[k] = hit
+            else:
+                if hit is not None:
+                    self._l1.remove(k)
+                miss.append(k)
+        if miss:
+            l2_hits = self._l2.get_many(miss)
+            for k, hit in l2_hits.items():
+                self._l1.set(k, hit)
+                out[k] = hit
+            self._miss_memo = (time.monotonic(), frozenset(k for k in miss if k not in l2_hits))
+        return out
+
     def _write(self, key: str, query: str, engine: str, max_results: int,
                value: dict, domain: str, ttl: int,
                mode: str = "", depth: str = "") -> None:
         if self._disabled():
             return
+        self._miss_memo = (0.0, frozenset())
         payload = {**value, "_domain": domain, "_ttl": ttl, "_ts": time.time(),
                    "_max_results": max_results}
         self._l1.set(key, payload)
@@ -1173,7 +1160,7 @@ class SearchCache:
         返回 {url: {"body": {...}|None, "retrieval": {...}}}，只含本地有记录的 URL。
         """
         out: dict[str, dict] = {}
-        if not urls:
+        if not urls or self._disabled():
             return out
         try:
             from fulltext_store import path_for as _ft_path
@@ -1183,14 +1170,15 @@ class SearchCache:
             from robots_guard import known_blocked as _known_blocked
         except ImportError:
             _known_blocked = None
+        try:
+            hits = self._read_many([self._fetch_key(u) for u in urls if u])
+        except IO_BENIGN + SHAPE_BENIGN:
+            hits = {}
 
         for url in urls:
             if not url:
                 continue
-            try:
-                hit = self._read(self._fetch_key(url))
-            except IO_BENIGN + SHAPE_BENIGN:
-                hit = None
+            hit = hits.get(self._fetch_key(url))
             entry: dict = {}
 
             # ① 反面记录：以前抓过、结果不可用