argo-search 2.9.7 → 2.9.9

package/scripts/engine_dispatch.py

@@ -27,16 +27,23 @@ import threading
 from typing import Any, Callable
 
 from cache_guard import (
-    _QUOTA_ERROR_KEYWORDS,
     attempt_cache_write,
     is_state_failure_outcome,
 )
 from time_utils import is_time_capable
+from budget import over_budget_error
+from dispatch_result import DispatchResult, summarize_dispatch
 from query_signals import (
     cumulative_sufficient,
     results_sufficient,
     query_coverage_ok,
 )
+from retry_policy import (
+    NON_RETRYABLE_STATUS as _NON_RETRYABLE_STATUS,
+    classify_error_status,
+    is_retryable_failure,
+    record_attempts,
+)
 
 # 失败原因分类（engine_failure.py 的类别全集）→ 引擎结果 status 的对照表。
 # 未列出的类别经 .get(cat, "error") 归为 error：以后新增失败类别时默认可见，
@@ -158,14 +165,8 @@ def _adaptive_grace(engine: str, base_grace_s: float) -> float:
         return base_grace_s
     return max(0.3, min(base, float(p75_ms) / 1000.0))
 
-# 拦截页特征词（唯一来源）：error 文本里出现即判 blocked。HTML 引擎的反爬
-# 命中没有 error 文本（静默空结果），走 engines_base 的归因寄存器；
-# 这张表兜住「error 结果里带拦截页字样」的可见路径。
-_BLOCKED_ERROR_KEYWORDS = (
-    "just a moment", "checking your browser", "cf-browser-verification",
-    "challenge", "ddos-guard", "perimeterx", "access denied",
-    "handshake failure", "unable to handshake", "安全验证", "滑动验证",
-)
+# 失败类别与重试判据住在 retry_policy（唯一来源）：重试判据与归因判据必须
+# 同源，而本文件已接近行数上限——纯策略搬出去，两边都轻。
 
 
 def classify_engine_outcome(eng: str, res: list[dict[str, Any]],
@@ -185,19 +186,7 @@ def classify_engine_outcome(eng: str, res: list[dict[str, Any]],
     errors = [r for r in res if isinstance(r, dict) and "error" in r]
     goods = [r for r in res if isinstance(r, dict) and "error" not in r]
     if errors and not goods:
-        msg = str(errors[0].get("error", "")).lower()
-        if "timeout" in msg:
-            st = "timeout"
-        elif any(k in msg for k in _QUOTA_ERROR_KEYWORDS):
-            st = "quota-exhausted"
-        elif "rate" in msg or "429" in msg:
-            st = "rate-limited"
-        elif any(k in msg for k in _BLOCKED_ERROR_KEYWORDS):
-            st = "blocked"
-        elif "auth" in msg or "401" in msg or "403" in msg:
-            st = "auth-failed"
-        else:
-            st = "error"
+        st = classify_error_status(errors[0].get("error"))
         return {
             "engine": eng, "status": st,
             "results_count": 0, "latency_ms": latency_ms,
@@ -214,39 +203,6 @@ def classify_engine_outcome(eng: str, res: list[dict[str, Any]],
     }
 
 
-class DispatchResult:
-    """编排产出 + 两个钩子（融合后仍要补搜的路径用）。
-
-    `run_one` / `ingest` 必须外露：macro_data 域的 D6 证据下限补搜在融合之后，
-    它要跑单个引擎并把结果并进同一份账（raw_results / engine_outcomes /
-    engine_latency / wasted 计数），另起一份会让 engines_used 与配额记账对不上。
-
-    `budget_used_ms` / `budget_total_ms`：本次编排的实际墙钟消耗与总预算
-    （deep 等无预算模式 total 为 None）。搜索输出把它挂进 timing.budget，
-    让「这次离预算上限还有多远」可观测，而不必反推 process_ms。
-
-    """
-
-    __slots__ = ("raw_results", "engine_outcomes", "engine_latency",
-                 "wasted_ms", "early_stopped", "run_one", "ingest",
-                 "budget_used_ms", "budget_total_ms", "useful_ms")
-
-    def __init__(self, raw_results, engine_outcomes, engine_latency,
-                 wasted_ms, early_stopped, run_one, ingest,
-                 budget_used_ms=None, budget_total_ms=None,
-                 useful_ms: int = 0) -> None:
-        self.raw_results = raw_results
-        self.engine_outcomes = engine_outcomes
-        self.engine_latency = engine_latency
-        self.wasted_ms = wasted_ms
-        self.early_stopped = early_stopped
-        self.run_one = run_one
-        self.ingest = ingest
-        self.budget_used_ms = budget_used_ms
-        self.budget_total_ms = budget_total_ms
-        self.useful_ms = useful_ms
-
-
 def run_dispatch(*, query: str, retrieval_query: str, engines: list[str],
                  decision: dict[str, Any], parallel: bool,
                  domain: str, mode: str, depth: str,
@@ -279,6 +235,8 @@ def run_dispatch(*, query: str, retrieval_query: str, engines: list[str],
     raw_results: dict[str, list[dict[str, Any]]] = {}
     engine_outcomes: list[dict[str, Any]] = []
     engine_latency: dict[str, int] = {}
+    # 每引擎实际发出的网络请求数（含重试与 balanced 补跑）——_run_one 收账用。
+    _attempt_counts: dict[str, int] = {}
 
     # 远端配额耗尽快照（route_combo 的 F7 已在 combo 层排除 hard-down
     # 引擎；本快照供下方 per-engine 闸口兜底主路由/恢复链/显式 engine=
@@ -399,8 +357,14 @@ def run_dispatch(*, query: str, retrieval_query: str, engines: list[str],
                 since=since_iso, until=until_iso, skip_cache=skip_cache,
                 **_engine_domain_kwargs(),
             )
+            _attempt_counts[eng] = _attempt_counts.get(eng, 0) + 1
             if last_result and any("error" not in r for r in last_result):
                 return last_result
+            # 确定性失败不重试：配额/鉴权/反爬是源端状态，再发一次仍是同样
+            # 的结果，只多烧一次调用并推迟切备选（见 is_retryable_failure）。
+            # transient 与空结果沿用既有「重试一次」语义。
+            if not is_retryable_failure(last_result):
+                return last_result
         # 慢源（retries=0，超时即弃）不再用 balanced 补跑，避免超时场景双倍耗时
         if retries > 0 and depth != "balanced":
             _remain = _eng_budget - (_now() - _t_eng_start)
@@ -412,6 +376,7 @@ def run_dispatch(*, query: str, retrieval_query: str, engines: list[str],
                     since=since_iso, until=until_iso, skip_cache=skip_cache,
                     **_engine_domain_kwargs(),
                 )
+                _attempt_counts[eng] = _attempt_counts.get(eng, 0) + 1
         return last_result
 
     def _run_one(eng: str) -> tuple[str, list[dict[str, Any]], dict[str, Any], int]:
@@ -493,6 +458,14 @@ def run_dispatch(*, query: str, retrieval_query: str, engines: list[str],
                 outcome["status"] = "ok-cached" if eng_hit else "no-results-cached"
                 return eng, eng_hit, outcome, lat
 
+        # 预算：缓存命中不收费，放在缓存之后；判定/文案在 budget.py。
+        _budget_err = over_budget_error(eng)
+        if _budget_err:
+            lat = int((_now() - t_eng) * 1000)
+            outcome = classify_outcome(eng, [], lat, status_hint="skipped-budget")
+            outcome["detail"] = _budget_err
+            return eng, [], outcome, lat
+
         # 网络调用
         # 答案型域（early_min 存在，1 条快照即可交付）的慢源收紧超时：
         # FRED/Eurostat 这类 timeout=10s 的源一旦挂掉就阻塞整条串行路径，
@@ -534,6 +507,9 @@ def run_dispatch(*, query: str, retrieval_query: str, engines: list[str],
                 r.setdefault("_elapsed", lat / 1000.0)
 
         outcome = classify_outcome(eng, res, lat)
+        # 如实记账：本次实际发了几次网络请求（重试 + balanced 补跑）。
+        # 「重试了一次」此前不可见——与「早停 + wasted_ms 如实记账」同一纪律。
+        record_attempts(outcome, {"n": _attempt_counts.get(eng, 1)})
         # 失败原因合入：引擎内部那些不报错的失败路径（反爬命中/HTTP 状态码/网络异常）
         # 没有 error 文本，结果会落成 no-results；失败原因记录把它们还原成
         # 真实状态，供熔断与 --json 可观测面使用。
@@ -617,19 +593,21 @@ def run_dispatch(*, query: str, retrieval_query: str, engines: list[str],
         raw_results[eng] = res
         engine_outcomes.append(outcome)
         engine_latency[eng] = lat
-        # 完成时刻（相对本次编排起点）：wasted 的真值来源，见函数尾部的记账
         engine_done_ms[eng] = (_now() - _budget_base) * 1000.0
         if outcome["status"] in _CONTRIBUTING_STATUS:
             contributed_ms.append(engine_done_ms[eng])
 
     engine_done_ms: dict[str, float] = {}
     contributed_ms: list[float] = []
-    # 被编排主动**弃置**的引擎（早停收工时仍在跑的）已经花掉的墙钟。
-    # 这些时间既没换来结果、也没拖住返回（函数当刻就返回了），此前只把
-    # lat_ms 记进 engine_latency 就丢掉——「答案就绪后还在等」这个口径在
-    # 有界并发下恒为 0（最后完成的引擎就是触发早停的那个，wall==useful），
-    # 仪表盘因此永远显示 0，无法据此调 tail_grace / hedge / 并发上限。
+    # 早停弃置引擎已花的墙钟（并行资源浪费，不是用户等待）；记账口径见
+    # dispatch_result 模块注释。
     abandoned_ms: list[float] = []
+    # 早停弃置且仍存活的 (engine, holder, now_fn)：交 tail_completion 后台
+    # 收割（2026-10-25）。now_fn 跟 _now 走——t0_mono 传入时整套是单调钟，
+    # 收割线程不能用墙钟去减 holder["t0"]。
+    stranded: list[tuple[str, dict[str, Any], Any]] = []
+    first_result_at: float | None = None
+    first_sufficient_at: float | None = None
     # 配额批次的构造在调用方：flush 必须发生在**最后一个 _ingest 之后**，
     # 而那个点在融合后的 D6 补搜里（本模块之外）。在这里另建一个实例，
     # 调用方 flush 到的就是空批次——补搜引擎的记账永远落不了盘。
@@ -725,6 +703,10 @@ def run_dispatch(*, query: str, retrieval_query: str, engines: list[str],
                     # 弃置的引擎白花的墙钟计入 wasted（见 abandoned_ms）：
                     # 它是「调度多花了多少」的量，不是「多等了多久」。
                     abandoned_ms.append(lat_ms)
+                    # 弃置≠丢弃交付：holder 交给后台收割（宽限内完成则记
+                    # 学习器真实成绩 + 合并写缓存，见 tail_completion）。
+                    # 主响应与上面这笔 cancelled 记账逐位不变。
+                    stranded.append((eng, holder, _now))
                     _ingest(eng, [],
                             classify_outcome(eng, [], lat_ms, "cancelled"),
                             lat_ms)
@@ -787,6 +769,7 @@ def run_dispatch(*, query: str, retrieval_query: str, engines: list[str],
         """
         if not engs:
             return False
+        nonlocal first_result_at, first_sufficient_at
         queue = list(engs)
         pending: list[tuple[dict[str, Any], Any, str]] = []
         deadline = _now() + max(0.0, wait_s)
@@ -817,7 +800,10 @@ def run_dispatch(*, query: str, retrieval_query: str, engines: list[str],
                 pending.remove(item)
                 progressed = True
                 goods = _holder_goods(holder)
+                if goods and first_result_at is None:
+                    first_result_at = _now()
                 if stop is not None and stop(eng, goods):
+                    first_sufficient_at = _now()
                     _settle_pending(pending, status="cancelled")
                     return True
                 if goods and tail_grace_s > 0.0:
@@ -985,35 +971,21 @@ def run_dispatch(*, query: str, retrieval_query: str, engines: list[str],
                 tail_grace_fn=straggler_tail_fn):
             early_stopped = True
 
-
-
     budget_total_ms = int(budget_s * 1000) if budget_s is not None else None
-    # 墙钟账：`useful_ms` = 最后一个有效贡献引擎完成的时刻（答案从这一刻起
-    # 就已经在手里了）。`wasted_ms` 见下方口径说明。
-    #
-    # 此前的 wasted 是「所有非 ok 引擎的 latency 之和」——它根本不是时间量：
-    # 并行时必然大于墙钟（实测「世界杯 2026 主办国」wasted 2847ms > dispatch
-    # 2313ms），而且把「引擎如实返回了 0 条」也算成浪费。两个已知代价：
-    # ① 上一轮的优化盘点据此写下「早停与 hedge race 记账诚实、调度不用动」，
-    #    而实测调度是最大的单一浪费源；② 读者无法从它推出任何行动。
-    #
-    # 再往后改成 `wall - useful`（useful = 最后一个**贡献结果**的引擎的完成
-    # 时刻），并宣称口径是「答案就绪后还在等」。但有界并发下这仍是恒等式：
-    # 触发早停的引擎自己就是最后完成的那个，返回当刻 wall == useful，于是
-    # wasted 永远是 0——实测每轮皆 0。空转的仪表比没有仪表更糟：它让人以为
-    # 调度无浪费可调，于是谁都不会去调 tail_grace / hedge / 并发上限。
-    #
-    # 现在的口径：**被编排主动弃置的引擎已经花掉的墙钟之和**。
-    # 这些时间确实白花（没换来结果、也没拖住返回），是唯一既能算清、
-    # 又能指向具体动作的量；与 wall 无关（弃置不阻塞返回），故不再保证
-    # useful + wasted == wall。仍被等待的超时引擎不算浪费——那是引擎不健康，
-    # 在 engine_latency / 熔断里已可见。
+    # 记账口径见 dispatch_result 模块注释；wasted_ms 保留为 abandoned 别名。
     wall_ms = int((_now() - _budget_base) * 1000)
-    useful_ms = int(min(max(contributed_ms), wall_ms)) if contributed_ms else 0
+    _acc = summarize_dispatch(
+        wall_ms=wall_ms, contributed_ms=contributed_ms,
+        first_result_at=first_result_at, first_sufficient_at=first_sufficient_at,
+        base=_budget_base, abandoned_ms=abandoned_ms)
     return DispatchResult(
         raw_results, engine_outcomes, engine_latency,
-        int(sum(abandoned_ms)), early_stopped, _run_one, _ingest,
+        _acc["abandoned_engine_ms"], early_stopped, _run_one, _ingest,
         budget_used_ms=wall_ms,
         budget_total_ms=budget_total_ms,
-        useful_ms=useful_ms,
+        useful_ms=_acc["useful_ms"],
+        first_sufficient_ms=_acc["first_sufficient_ms"],
+        tail_wait_ms=_acc["tail_wait_ms"],
+        abandoned_engine_ms=_acc["abandoned_engine_ms"],
+        stranded=stranded,
     )

package/scripts/engine_env.py

@@ -186,6 +186,10 @@ KNOWN_ENV_ALIASES: dict[str, list[str]] = {
     "firecrawl": ["ARGO_FIRECRAWL_API_KEY", "FIRECRAWL_API_KEY"],  # 可选（keyless 免费层）
     "weread": ["ARGO_WEREAD_API_KEY", "WEREAD_API_KEY"],  # 微信读书 Agent Gateway
     "em_miaoxiang": ["ARGO_EASTMONEY_APIKEY", "EASTMONEY_APIKEY"],  # 东财妙想（可选）
+    # 腾讯元宝搜索：官方文档用的名字是 TENCENTCLOUD_WSA_APIKEY，
+    # argo 推荐名在前；两个都认，便于照文档配的用户直接可用。
+    "yuanbao": ["ARGO_YUANBAO_API_KEY", "TENCENTCLOUD_WSA_APIKEY",
+                "YUANBAO_API_KEY"],
 }
 
 # 占位符名 → 候选 env（用于 config 中 {TAVILY_API_KEY} 展开）
@@ -215,6 +219,7 @@ _NON_SECRET_PLACEHOLDERS = {"QUERY", "N", "TIMESTAMP", "MODE", "DEPTH", "UUID"}
 
 # 可选密钥：有则更好，缺失不阻断自动路由
 OPTIONAL_ENV_ENGINES: set[str] = {
+    "exa",          # 无 key 走官方 MCP 匿名通道（engines_builders_tech._exa_mcp_keyless）
     "github",       # GITHUB_TOKEN 仅提高限频
     "anysearch",    # ANYSEARCH_API_KEY 可选
     "firecrawl",    # FIRECRAWL_API_KEY 可选：官方免费层匿名（keyless）即可搜索

package/scripts/engine_families.py

@@ -112,12 +112,17 @@ _ENGINE_FAMILY_OVERRIDES: dict[str, str] = {
     "eastmoney": "finance_market",
     "cninfo": "finance_market",
     "seeking_alpha": "finance_market",
+    # 2026-10-21 批次十四：一手行情/公告
+    "hkex": "finance_market",       # 港交所披露易公告
+    "shfe": "finance_market",       # 上期所商品日行情
+    "defillama": "finance_market",  # 协议 TVL（链上资金规模）
     # 宏观
     "fred": "finance_macro",
     "worldbank": "finance_macro",
     "nbs_stats": "finance_macro",
     "eurostat": "finance_macro",
     "fx_rate": "finance_macro",
+    "cfets": "finance_macro",     # 人民币中间价（官方在岸口径）
     # 快讯
     "cls_telegraph": "news_flash",
     "em_global_news": "news_flash",
@@ -250,6 +255,7 @@ _ENGINE_FAMILY_OVERRIDES: dict[str, str] = {
     # 百科/实体
     "ror": "knowledge",        # 研究机构标识
     "opencorporates": "knowledge",
+    "gleif": "knowledge",        # 全球法人 LEI 注册库
     "wikisource": "knowledge",
     "zdic": "knowledge",       # 汉典：字义/音韵/字源
     # 媒体/图书/艺术

package/scripts/engine_policy.py

@@ -51,13 +51,13 @@ FORCE_DAILY_CORE: frozenset[str] = frozenset({
 # 排在通用检索源末位 + spec 的 tier=daily_support，日常 fast/auto 的 combo 预算
 # （2/3 个）够不到它，只在 deep/research 无截断时参战，共享免费层不被烧穿。
 GENERAL_FREE_FALLBACK: tuple[str, ...] = (
-    # 2026-10-17 A/B：octen 顶到第二顺位（anysearch 之后）。健康窗口里
-    # 双引擎的早停由领队的宽限窗决定，中位延迟无差；anysearch 抖动/超时
-    # 的窗口里 octen（实测 996ms / 100% 成功）先把足够结果交出来，早停把
-    # 尾延迟从 3273ms 收到 1725ms（p90 3273→1614，max 6266→1928，错误
-    # 9→0）。local_bing 退到第三位，仍是 570ms 级的快速补充源。
-    "anysearch", "octen", "local_bing", "uapi", "local_baidu", "firecrawl",
-    "parallel_free", "wikipedia",
+    # 2026-10-21 A/B：octen 顶到第一位。交错对拍（ab_eval，4 对/查询、
+    # --no-cache）里 octen 对 anysearch 8:0 全胜：露营 天幕 p90 6313→835ms、
+    # asyncio p90 2769→963ms，结果数中位同为 8。生产日志同向：general_search
+    # 346 条查询里 324 条的最后一棒是 anysearch（p50 1932ms），octen 同域
+    # p50 776ms。anysearch 退到对冲位，能力面不变（仍在 combo 内）。
+    "octen", "anysearch", "local_bing", "uapi", "local_baidu", "firecrawl",
+    "parallel_free", "tavily_free", "keenable_free", "wikipedia",
 )
 
 

package/scripts/engines.py

@@ -60,6 +60,7 @@ __all__ = [
     "_parse_semantic_scholar",
     "_ensure_engine_source",
 ]
+from engines_builders_keyless import _build_keenable_free_engine
 from engines_builders import (
     _build_who_don_engine,
     _build_who_gho_engine,
@@ -169,6 +170,11 @@ from engines_builders import (
     _build_yahoo_finance_engine,
     _build_sec_companyfacts_engine,
     _build_frankfurter_engine,
+    _build_hkex_engine,
+    _build_shfe_engine,
+    _build_cfets_engine,
+    _build_defillama_engine,
+    _build_yuanbao_engine,
     _build_seeking_alpha_engine,
     _build_qweather_engine,
     _build_wenshu_engine,
@@ -393,6 +399,7 @@ _BUILDERS = {
     "html": _build_html_engine,
     "local_search": _build_local_search_engine,
     "exa": _build_exa_engine,
+    "keenable_free": _build_keenable_free_engine,
     "anysearch": _build_anysearch_engine,
     "em_miaoxiang": _build_em_miaoxiang_engine,
     "cninfo": _build_cninfo_engine,
@@ -471,6 +478,11 @@ _BUILDERS = {
     "yahoo_finance": _build_yahoo_finance_engine,
     "sec_companyfacts": _build_sec_companyfacts_engine,
     "frankfurter": _build_frankfurter_engine,
+    "hkex": _build_hkex_engine,
+    "shfe": _build_shfe_engine,
+    "cfets": _build_cfets_engine,
+    "defillama": _build_defillama_engine,
+    "yuanbao": _build_yuanbao_engine,
     "seeking_alpha": _build_seeking_alpha_engine,
     "qweather": _build_qweather_engine,
     "wenshu": _build_wenshu_engine,
@@ -845,6 +857,15 @@ def search(query: str, engine: str, n: int = 5, timeout: float = 8, depth: str =
     except Exception:
         results = []
     results = results or []
+    # SERP 相关度守卫统一在引擎执行出口判定。放在 builder 里会漏掉
+    # people_daily 这类模糊搜索 API：它匹配不到时回整页默认 feed，形态是
+    # 正常结果，只有按 query 覆盖率才判得出来（issue #18 复现 A）。
+    # builder 已经判过垃圾的 local_* 这里拿到空列表，按早退语义不重复记账。
+    try:
+        from serp_kill_log import serp_guard_apply
+        results = serp_guard_apply(engine, query, results)
+    except ImportError:
+        pass
     # 桶化后可能多于请求数：调用方按请求 n 截断语义由 execute_search 融合层负责；
     # 此处保留全量（缓存键按 eff_n 存，命中时同样可截）。
     return results

package/scripts/engines_base.py

@@ -384,11 +384,11 @@ def _build_cli_engine(spec: dict[str, Any]) -> Any:
         args = _resolve(search_args, query, n, mode=mode, **kwargs)
         if not cmd:
             return []
-        # 跨平台解释器解析：Windows 一般没有 python3 这个可执行名
+        # 跨平台解释器：优先 sys.executable（bin/argo 已验证它带 PyYAML）；
+        # PATH 上的 python3 未必是同一解释器，见 tests/test_cli_engine_interpreter.py
         if isinstance(cmd, list) and cmd and cmd[0] == "python3":
             import shutil  # 仅 CLI 引擎解析解释器时需要，不进模块级导入链
-            py3 = shutil.which("python3") or shutil.which("python") or sys.executable
-            cmd[0] = py3
+            cmd[0] = sys.executable or shutil.which("python3") or shutil.which("python")
         for key, tmpl in filter_args.items():
             if kwargs.get(key) not in (None, ""):
                 args += _resolve(tmpl, query, n, mode=mode, **kwargs)

package/scripts/engines_builders.py

@@ -28,6 +28,9 @@ from engines_builders_batch9 import (
     _build_tle_mirror_engine,
     _build_nhtsa_vpic_engine,
 )
+from engines_builders_keyless import (
+    _build_keenable_free_engine,
+)
 from engines_builders_tech import (
     _build_exa_engine,
     _build_anysearch_engine,
@@ -85,6 +88,15 @@ from engines_builders_batch13 import (
     _build_sec_companyfacts_engine,
     _build_frankfurter_engine,
 )
+from engines_builders_batch14 import (
+    _build_hkex_engine,
+    _build_shfe_engine,
+    _build_cfets_engine,
+    _build_defillama_engine,
+)
+from engines_builders_batch15 import (
+    _build_yuanbao_engine,
+)
 from engines_builders_data import (
     _build_open_library_engine,
     _build_weread_engine,

package/scripts/engines_builders_batch10.py

@@ -20,6 +20,7 @@ import time
 import urllib.error
 import urllib.parse
 import urllib.request
+from datetime import datetime
 from typing import Any
 
 from engine_env import get_env
@@ -69,6 +70,42 @@ def _zhihu_error_item(code: Any, message: Any) -> dict[str, Any]:
     return {"error": text, "source": "zhihu_global"}
 
 
+def _zhihu_epoch(value: Any) -> int | None:
+    """ISO 时间窗 → 秒级时间戳；空/不可解析返回 None（不阻断检索）。"""
+    raw = str(value or "").strip()
+    if not raw:
+        return None
+    try:
+        return int(datetime.fromisoformat(raw.replace("Z", "+00:00")).timestamp())
+    except (TypeError, ValueError):
+        return None
+
+
+_DB_OPERATOR_RE = re.compile(r"(?:^|\s)db:(all|realtime|static)(?=\s|$)", re.I)
+
+
+def _parse_db_operator(query: str) -> tuple[str, str]:
+    """解析 `db:realtime|static|all` 查询操作符，返回 (db, 剩余查询)。"""
+    match = _DB_OPERATOR_RE.search(query or "")
+    if not match:
+        return "all", query
+    db = match.group(1).lower()
+    rest = _DB_OPERATOR_RE.sub(" ", query, count=1).strip()
+    return db, rest or (query or "")
+
+
+def _build_zhihu_publish_filter(since: Any, until: Any) -> str:
+    """把 --since/--until 下推成官方 Filter（publish_time 支持 >=/<=）。"""
+    since_ts = _zhihu_epoch(since)
+    until_ts = _zhihu_epoch(until)
+    parts = []
+    if since_ts is not None:
+        parts.append(f"publish_time>={since_ts}")
+    if until_ts is not None:
+        parts.append(f"publish_time<={until_ts}")
+    return " AND ".join(parts)
+
+
 def _build_zhihu_global_engine(spec: dict[str, Any]) -> Any:
     """知乎开放平台全网搜索（developer.zhihu.com global_search）。
 
@@ -92,12 +129,20 @@ def _build_zhihu_global_engine(spec: dict[str, Any]) -> Any:
 
         # 解析 site:/host: 站点限定语法 → Filter: host=="..."（实现单点在 cn）
         filter_expr, search_query = _parse_site_filter(query)
-
-        filtered = bool(filter_expr or kwargs.get("since"))
+        # db:realtime|static|all：官方 SearchDB 选择（默认 all）
+        db, search_query = _parse_db_operator(search_query or query)
+        # --since/--until → 官方 publish_time 过滤（文档 2026-10 正式定义）
+        _time_filter = _build_zhihu_publish_filter(kwargs.get("since"),
+                                                   kwargs.get("until"))
+        if _time_filter:
+            filter_expr = (f"{filter_expr} AND {_time_filter}"
+                           if filter_expr else _time_filter)
+
+        filtered = bool(filter_expr or db != "all")
         params: dict[str, Any] = {
             "Query": search_query or query,
             "Count": str(_ZHIHU_COUNT_MAX if filtered else min(int(n or 5), _ZHIHU_COUNT_MAX)),
-            "SearchDB": "all",
+            "SearchDB": db,
         }
         if filter_expr:
             params["Filter"] = filter_expr