argo-search 2.9.8 → 2.9.9

package/scripts/bench_tail_ab.py

@@ -0,0 +1,281 @@
+#!/usr/bin/env python3
+"""bench_tail_ab.py — 尾延迟策略的离线 A/B 回放台（方案 A 的验收工具）。
+
+## 为什么需要它（而不是再写一个调参脚本）
+
+尾宽这条线上的教训是：**参数改动必须在同一份日志上先跑出数字**。2026-10-15
+与 2026-10-19 两次 A/B 结论相反，原因是每次都换了一批线上流量、换了一个
+估计量，最后只能判「噪声非信号」。本脚本把「候选策略」和「团队现行策略」
+放在同一条回放时间线上算，输入是本地 ``usage_log/query.jsonl`` 与
+``adaptive.db`` 的 7 天延迟分布——零网络、可复现、可对拍。
+
+## 两种运行模式
+
+* ``--dry-run``（默认）：只打印回放表格。**不做任何结论**，不写状态。
+* ``--record``：把这次的候选值写进 ``docs-local/tail_ab_<日期>.json``，
+  供下一次跑同一个 bench 时直接对拍（「上次结论是什么」不再靠记忆）。
+
+## 用法
+
+    python3 scripts/bench_tail_ab.py                  # 回放：现行 vs 候选
+    python3 scripts/bench_tail_ab.py --candidate 0.6  # 换一个候选尾宽
+
+候选策略刻意只开一个**常数**轴（尾宽上限），因为要回答的问题只有一个：
+「把尾宽从 1.5s 收到 X，在 2 引擎查询上省多少墙钟、丢掉多少慢源交付？」
+其余旋钮（起步窗、分层档位）不动——多变量同时动就没法归因，这正是前两次
+对拍失败的机制原因。
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sqlite3
+import statistics as st
+import sys
+import time
+from collections import defaultdict
+from pathlib import Path
+
+try:  # 与生产同源的路径解析（测试域可被 ARGO_STATE_DIR 重定向）
+    from argo_paths import state_path
+except ImportError:  # pragma: no cover - 直接 python3 运行时的兜底
+    def state_path(*parts: str) -> Path:
+        return Path.home() / ".cache" / "unified-search" / Path(*parts)
+
+BASE_TAIL = 1.5      # 现行固定尾宽
+START_WINDOW = 0.8   # 现行对冲起步窗
+_SYNTHETIC = {"dead_primary", "dead_backup", "fast_backup", "slow_backup",
+              "slow_primary", "quick_primary", "fast_primary", "parallel"}
+
+
+def _percentile(values: list[float], q: float) -> float:
+    if not values:
+        return 0.0
+    s = sorted(values)
+    return s[min(len(s) - 1, int(len(s) * q))]
+
+
+def load_p75(db_path: Path) -> dict[str, float]:
+    """引擎 → 7 天窗「正常交付」延迟的 P75（毫秒）；样本 <5 的引擎不给值。"""
+    if not db_path.exists():
+        return {}
+    lat: dict[str, list[float]] = defaultdict(list)
+    with sqlite3.connect(db_path) as conn:
+        for eng, ms in conn.execute(
+                "SELECT engine, latency_ms FROM engine_perf "
+                "WHERE success = 1 AND empty = 0"):
+            lat[eng].append(float(ms or 0))
+    return {e: st.quantiles(v, n=4)[2] for e, v in lat.items() if len(v) >= 5}
+
+
+def load_host_bodies(state: Path) -> dict[str, float]:
+    """站点 → 本地全文缓存里该站正文的中位字节数（「这个站被真正抓过、有料」的代理）。
+
+    数据来源是 ``fulltext/index.jsonl``（抓取正文的追加式索引）。用途只有一个：
+    判断被放弃的那条交付**有没有在被放弃之前进过正文流水线**。没进过的站点，
+    尾宽再宽也不会自动变成正文——这是「省下的墙钟到底是不是白等」的判据。
+    """
+    idx = state / "fulltext" / "index.jsonl"
+    if not idx.exists():
+        return {}
+    per: dict[str, list[float]] = defaultdict(list)
+    with idx.open(encoding="utf-8", errors="replace") as fh:
+        for line in fh:
+            try:
+                rec = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            url = str(rec.get("url") or "")
+            host = url.split("/")[2] if "://" in url else ""
+            if host:
+                per[host].append(float(rec.get("bytes") or 0))
+    return {h: st.median(v) for h, v in per.items() if v}
+
+
+def load_queries(log_path: Path) -> list[dict]:
+    if not log_path.exists():
+        return []
+    out = []
+    with log_path.open(encoding="utf-8", errors="replace") as fh:
+        for line in fh:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                rec = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            top = rec.get("engine_latency_top") or []
+            if any(isinstance(x, list) and x and x[0] in _SYNTHETIC for x in top):
+                continue  # 合成引擎（基准/混沌）不是真实流量，别混进来
+            out.append(rec)
+    return out
+
+
+def replay(queries: list[dict], p75: dict[str, float], tail_s: float) -> dict:
+    """在候选尾宽下重算每条查询的墙钟，返回新旧两组的对比。"""
+    old_walls: list[float] = []
+    new_walls: list[float] = []
+    lost_delivery = 0          # 候选策略下慢源「来不及」的次数
+    for rec in queries:
+        wall = rec.get("elapsed_ms") or 0
+        if wall <= 0:
+            continue
+        top = sorted((x for x in (rec.get("engine_latency_top") or [])
+                      if isinstance(x, list) and len(x) == 2 and isinstance(x[1], (int, float))),
+                     key=lambda x: x[1])
+        n_eng = len(rec.get("engines_used") or [])
+        if len(top) < 2 or n_eng < 2:
+            old_walls.append(wall)
+            new_walls.append(wall)
+            continue
+        fast_ms = top[0][1]
+        slow_ms = top[-1][1]
+        # 现行：慢源若在自己回来之前就已交付则无等待，否则最多再等 BASE_TAIL
+        # 已经交付的等待是**沉没成本**：慢源在窗口内回来的那条路径，两套口径
+        # 都不产生「额外等待」，也就都不该被算成可省时间。只有「慢源还没回来、
+        # 我们决定不再等」那一段才是真省下来的墙钟。
+        wait_old = BASE_TAIL * 1000 if slow_ms - fast_ms >= BASE_TAIL * 1000 else 0
+        wait_new = tail_s * 1000 if slow_ms - fast_ms >= BASE_TAIL * 1000 else 0
+        if wait_new < wait_old and slow_ms - fast_ms > tail_s * 1000:
+            lost_delivery += 1          # 候选策略会放弃这次慢源交付
+        old_walls.append(wall)
+        new_walls.append(max(0, wall - (wait_old - wait_new)))
+    return {
+        "n": len(old_walls),
+        "old": {"p50": st.median(old_walls) if old_walls else 0,
+                "p90": _percentile(old_walls, .90)},
+        "new": {"p50": st.median(new_walls) if new_walls else 0,
+                "p90": _percentile(new_walls, .90)},
+        "saved_ms_total": sum(o - n for o, n in zip(old_walls, new_walls)),
+        "slow_delivery_lost": lost_delivery,
+    }
+
+
+def lost_deliveries(queries: list[dict], p75: dict[str, float],
+                    tail_s: float) -> list[dict]:
+    """候选尾宽下**会被丢掉**的慢源交付明细（引擎 / 多等了多少 / 当时省了多少）。
+
+    为什么单独成函数：取舍不能只看总数。「224 次」里如果九成是同一台慢源，
+    那它早该被自适应降权（另一条已存在的机制），尾宽只是替它擦屁股；如果
+    分散在很多源身上，缩尾宽就是在系统性地牺牲长尾覆盖。两种结论的动作完全不同。
+    """
+    rows: list[dict] = []
+    for rec in queries:
+        top = sorted((x for x in (rec.get("engine_latency_top") or [])
+                      if isinstance(x, list) and len(x) == 2), key=lambda x: x[1])
+        if len(top) < 2 or len(rec.get("engines_used") or []) < 2:
+            continue
+        fast_ms, (slow_eng, slow_ms) = top[0][1], top[-1]
+        if slow_ms - fast_ms >= BASE_TAIL * 1000 and slow_ms - fast_ms >= tail_s * 1000:
+            rows.append({"engine": slow_eng,
+                         "extra_wait_ms": slow_ms - fast_ms,
+                         "p75_ms": p75.get(slow_eng),
+                         "query": (rec.get("query") or "")[:40]})
+    return rows
+
+
+def quality_report(lost: list[dict], host_bodies: dict[str, float],
+                   state: Path, p75: dict[str, float] | None = None) -> str:
+    """被放弃的那批交付「值不值得等」——用两条**互不冒充**的证据回答。
+
+    1. **相关度代理**（结果层）：``adaptive.db`` 里该引擎的质量分。口径是
+       ``result_relevance``——词面覆盖率，**不是内容正确性**；它只能说明
+       「结果和查询沾不沾边」，不能说明「结果对不对」。
+    2. **相对基线**（横向可比）：只看绝对值会误判——同一套代理分数在中文查询上
+       天然偏低。所以同时给出「该引擎质量 − 全部引擎均质量」，正数=比平均更相关。
+    3. **正文缓存覆盖**（证据层）：本地 ``fulltext`` 索引里该站点有没有被抓过正文。
+       没进过的站点，尾宽再宽也不会自动变成正文。
+
+    读法：相关度代理明显低于均线 **且** 从未进过正文缓存 → 早收工合理；
+    相关度不低于均线 → 放弃它就是在拿准确性换速度。
+    """
+    from collections import Counter
+    db = state / "adaptive.db"
+    per: dict[str, list[float]] = defaultdict(list)
+    if db.exists():
+        with sqlite3.connect(db) as conn:
+            for eng, qv in conn.execute(
+                    "select engine, quality from engine_perf where quality > 0"):
+                per[eng].append(float(qv))
+    q_mean = {e: st.mean(v) for e, v in per.items() if len(v) >= 5}
+    baseline = st.mean(q_mean.values()) if q_mean else 0.0
+
+    lines = ["", "=== 被放弃交付的质量画像 ===",
+             f"质量口径：result_relevance 词面覆盖代理；全库均线 {baseline:.3f}",
+             f"{'engine':16s} {'次数':>5s} {'相关度代理':>9s} {'相对均线':>9s} {'P75ms':>7s}"]
+    for eng, n in Counter(r["engine"] for r in lost).most_common():
+        q = q_mean.get(eng)
+        p = (p75 or {}).get(eng)
+        lines.append(
+            f"{eng:16s} {n:5d} {(f'{q:.3f}' if q is not None else 'n/a'):>9s} "
+            f"{(f'{q - baseline:+.3f}' if q is not None else '-'):>9s} "
+            f"{(f'{p:.0f}' if p else '-'):>7s}")
+    hosts = set(host_bodies)
+    lines.append("")
+    lines.append(f"本地正文缓存覆盖 {len(hosts)} 个站点（fulltext/index.jsonl）")
+    lines.append("读法：相对均线为负且从未进过正文缓存 → 早收工合理；"
+                 "相对均线不为负 → 放弃它是在拿准确性换速度。")
+    return "\n".join(lines)
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(description="尾宽策略离线 A/B 回放")
+    ap.add_argument("--candidate", type=float, default=0.6,
+                    help="候选尾宽（秒），默认 0.6")
+    ap.add_argument("--record", action="store_true",
+                    help="把本次回放写进 docs-local/tail_ab_<日期>.json")
+    ap.add_argument("--detail", action="store_true",
+                    help="扫表时附带「被放弃交付」的引擎分布（判断该缩尾宽还是该降权）")
+    ap.add_argument("--quality", action="store_true",
+                    help="附带质量评估：被放弃的那批交付里，有多少本来会变成正文证据")
+    ap.add_argument("--sweep", default="",
+                    help="逗号分隔的候选尾宽，一次性扫一遍（如 0.4,0.6,0.8,1.0）")
+    args = ap.parse_args(argv)
+
+    state = state_path()
+    queries = load_queries(state / "usage_log" / "query.jsonl")
+    p75 = load_p75(state / "adaptive.db")
+    if not queries:
+        print("没有可回放的查询日志（usage_log/query.jsonl 为空）；"
+              "先跑几次 argo search 再来。")
+        return 1
+    if args.sweep:
+        print(f"{'尾宽(s)':>8} {'p50(ms)':>8} {'p90(ms)':>8} {'总省(s)':>8} {'放弃交付':>8}")
+        for cand in [float(x) for x in args.sweep.split(",") if x.strip()]:
+            r = replay(queries, p75, cand)
+            print(f"{cand:8.2f} {r['new']['p50']:8.0f} {r['new']['p90']:8.0f} "
+                  f"{r['saved_ms_total'] / 1000:8.1f} {r['slow_delivery_lost']:8d}")
+        print("（扫表是给人看的：选型要同时看「省多少」和「丢掉多少慢源交付」）")
+        if args.detail:
+            lost = lost_deliveries(queries, p75, float(args.sweep.split(",")[0]))
+            from collections import Counter
+            print("被放弃的交付按引擎：", Counter(r["engine"] for r in lost).most_common(8))
+        if args.quality:
+            lost = lost_deliveries(queries, p75, float(args.sweep.split(",")[0]))
+            print(quality_report(lost, load_host_bodies(state), state, p75))
+        return 0
+    report = replay(queries, p75, args.candidate)
+    print(f"回放 {report['n']} 条真实查询（已剔合成引擎）；"
+          f"覆盖 {len(p75)} 个有延迟分布的引擎")
+    print(f"  现行尾宽 {BASE_TAIL:.2f}s： p50 {report['old']['p50']:.0f}ms  "
+          f"p90 {report['old']['p90']:.0f}ms")
+    print(f"  候选尾宽 {args.candidate:.2f}s： p50 {report['new']['p50']:.0f}ms  "
+          f"p90 {report['new']['p90']:.0f}ms")
+    print(f"  合计省 {report['saved_ms_total'] / 1000:.1f}s；"
+          f"放弃的慢源交付 {report['slow_delivery_lost']} 次（需人工评估这些查询是否本来就要慢源）")
+    if args.record:
+        out_dir = Path(__file__).resolve().parent.parent / "docs-local"
+        out_dir.mkdir(exist_ok=True)
+        path = out_dir / f"tail_ab_{time.strftime('%Y%m%d')}.json"
+        path.write_text(json.dumps({"candidate": args.candidate, **report},
+                                   ensure_ascii=False, indent=2), encoding="utf-8")
+        print(f"已记录：{path}")
+    else:
+        print("（dry-run：未做结论、未写状态。确认要上线前用 --record 留档）")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/bounded_run.py

@@ -19,16 +19,43 @@
 * 单个任务抛异常只记成该任务失败，不影响其它任务；
 * 总墙钟时间被 ``wait_s`` 硬性约束，不会超出。
 
-search.py 的引擎并发已经是这套做法，这里抽成通用实现，供 research / social /
-crawl / fetch 等复用，避免同一类问题在各处重复出现。
+时间来源（2026-10-24）
+----------------------
+本模块读时间只经 ``clock()``、等待只经 ``fetch_sleep()`` / ``poll_wait()``
+（见 ``tests/_measure.py``）。原因是实测：调度类用例红过多次，根因全是
+「把机器有多忙当成调度对不对」——轮询周期本身会吃掉十几毫秒，于是
+「等比累加 sleep 时长」与真实墙钟之间出现系统性偏差。现在一律按**剩余时间**
+（deadline 语义）判断还等不等，单次轮询抖动不再累加。
+
+「完成」的判据与池化
+--------------------
+判定某任务完成一律看 ``holder["done"]``，**不看** ``Thread.is_alive()``：
+线程跑完最后一行到被主循环观测之间有一段窗口，is_alive() 会把这段窗口里的
+任务误判成「还在跑」，旧实现因此在全量套件里间歇性把已完成结果记成超时。
+主循环改为：补发 → 收成 → 判断是否够（enough）→ 判断是否到点 → 再等一拍。
+「到点再收一次」放在循环尾部，保证最后一批结果不会被预算边界吃掉。
 """
 
 from __future__ import annotations
 
+import contextlib
 import threading
 import time
 from typing import Any, Callable, Generic, TypeVar
 
+try:  # 测试域由 tests/_measure 注入虚拟时钟；运行期退回真实时间
+    from _measure import clock, fetch_sleep, poll_wait, task_deadline  # type: ignore
+except ImportError:  # pragma: no cover - 生产路径
+    clock = time.monotonic
+    fetch_sleep = time.sleep
+
+    def poll_wait(seconds: float, evt: threading.Event | None = None) -> None:
+        (evt.wait(seconds) if evt is not None else time.sleep(seconds))
+
+    @contextlib.contextmanager
+    def task_deadline(_deadline: float | None = None, *, budget_s: float | None = None):
+        yield
+
 I = TypeVar("I")
 O = TypeVar("O")
 
@@ -62,23 +89,25 @@ def run_bounded(
 
     * ``finished``：已完成任务的 ``(item, value)`` 列表，按完成先后排列；
       任务抛异常时 ``value`` 是 :class:`TaskError`，调用方按需转成失败占位。
-    * ``unfinished``：到点仍没完成（或被 ``enough`` 提前收尾时还在跑）的 item 列表，
-      调用方可据此补超时提示。这些任务不会被 join，本函数因此能准时返回。
+    * ``unfinished``：到点仍没完成（或被 ``enough`` 提前收尾时还在跑）的 item
+      列表。这些任务不会被 join，本函数因此能准时返回。
 
-    ``enough(finished)`` 返回 True 时提前收尾：不再启动排队中的剩余任务，已在跑的
-    任务归入 unfinished。``max_workers`` 限制同时在跑的任务数。
+    ``enough(finished)`` 返回 True 时提前收尾：不再启动排队中的剩余任务，已在跑
+    的任务归入 unfinished。``max_workers`` 限制同时在跑的任务数。
 
-    ``stagger_s`` 起步间隔（秒），单调：0 = 不节流（立即填满并发位）；值越大越接近
-    严格串行（大于单任务超时上限即完全退回串行）。仅在**有任务在跑**时节制——
-    对冲语义（首任务先跑，宽限窗内交付就只付一次调用），而非无条件串行化；在跑
-    任务数为 0 时立即补发（前一个已返回，没有可对冲的对象，等满窗纯属浪费）。
+    ``stagger_s`` 起步间隔（秒），单调：0 = 不节流（立即填满并发位）；值越大越
+    接近严格串行（大于单任务超时上限即完全退回串行）。仅在**有任务在跑**时节制
+    ——对冲语义（首任务先跑，宽限窗内交付就只付一次调用），而非无条件串行化；
+    在跑任务数为 0 时立即补发（前一个已返回，没有可对冲的对象，等满窗纯属浪费）。
     engine_dispatch 的 hedged race 与 search_pipeline 的恢复链是同一哲学的两个
     配置：改这里的起步语义，两边同时生效。
     """
     queue = list(items)
     running: list[tuple[threading.Thread, I, dict]] = []
     finished: list[tuple[I, Any]] = []
-    deadline = time.monotonic() + max(0.0, float(wait_s))
+    # 预算锚点必须在启动任何线程之前取：线程一推进时钟，deadline 就跟着漂。
+    t0 = clock()
+    deadline = t0 + max(0.0, float(wait_s))
     last_start: float | None = None
     done_evt = threading.Event()
 
@@ -87,58 +116,71 @@ def run_bounded(
 
         def _work() -> None:
             try:
-                holder["v"] = worker(item)
-            except BaseException as exc:  # noqa: BLE001 - 任意任务异常都要隔离，不能让一个任务炸掉整组
+                # 任务的等待继承本轮预算：超过预算仍未回来，测试域会立刻指认
+                # 「这次等待越过了预算」，而不是让调用方事后拿墙钟去猜。
+                # 用**相对预算**而不是外围算好的绝对 deadline：那个 deadline
+                # 取自 clock()，与本层真实模式下的 monotonic 不同源（实测混用会
+                # 得到「已过期 65 秒」的假锚点，把正常等待判成越界）。
+                with task_deadline(budget_s=max(0.0, deadline - t0)):
+                    holder["v"] = worker(item)
+            except BaseException as exc:  # noqa: BLE001 - 任意任务异常都要隔离
                 holder["v"] = TaskError(item, exc)
             finally:
+                holder["done"] = True
                 done_evt.set()
 
         th = threading.Thread(target=_work, daemon=True)
         th.start()
         running.append((th, item, holder))
 
+    def _harvest() -> bool:
+        """收已完成的任务，返回本轮是否收到新结果。"""
+        got = False
+        for entry in list(running):
+            th, item, holder = entry
+            if not holder.get("done"):
+                continue
+            running.remove(entry)
+            finished.append((item, holder.get(
+                "v", TaskError(item, RuntimeError("任务结束但没有返回值")))))
+            got = True
+        return got
+
     while queue or running:
         done_evt.clear()
-        if time.monotonic() >= deadline:
-            break
-        # 按并发上限补启动排队任务
+        # 1) 补发排队任务（受并发上限与 stagger 节流约束）
         while queue and len(running) < max(1, int(max_workers)):
             if (stagger_s > 0 and running and last_start is not None
-                    and (time.monotonic() - last_start) < stagger_s):
+                    and (clock() - last_start) < stagger_s):
                 break  # 起步节流：等满 stagger 再补发（对冲）
             _start(queue.pop(0))
-            last_start = time.monotonic()
-        progressed = False
-        for entry in list(running):
-            th, item, holder = entry
-            if th.is_alive():
-                continue
-            running.remove(entry)
-            value = holder.get("v", TaskError(item, RuntimeError("任务结束但没有返回值")))
-            finished.append((item, value))
-            progressed = True
-            if enough is not None and enough(finished):
-                queue.clear()
-                break
+            last_start = clock()
+        # 2) 收成。注意不能因为收到结果就 `continue`：那会跳过本轮的
+        #    enough 判定与到点判定，把「够了就收工」变成「等下一个任务也回来」。
+        _harvest()
+        # 3) 够了就提前收工：排队中的任务不再启动（它们是主动放弃，不是超时）
         if enough is not None and enough(finished):
+            queue.clear()
+            break
+        # 4) 到点必须收工——但先再收一次，别把预算边界上刚好完成的结果丢掉
+        if clock() >= deadline:
+            _harvest()
+            break
+        # 5) 等一拍：按**剩余时间**算，不让单次抖动累加成常驻偏差
+        if not queue and not running:
             break
-        if not progressed:
-            remain = deadline - time.monotonic()
-            if remain <= 0:
-                break
-            wait_step = remain
-            if queue and stagger_s > 0 and last_start is not None:
-                wait_step = min(wait_step, max(0.0, stagger_s - (time.monotonic() - last_start)))
-            done_evt.wait(min(poll, wait_step) if poll > 0 else wait_step)
-
-    # 收尾：还活着的不等待（关键：不 join），计入 unfinished；恰在末次轮询后完成的
-    # 照常收进来，避免结果悄悄丢失。因并发上限到点仍没排上起跑的任务同样算未完成，
-    # 不能让它既不在 finished、也不在 unfinished 里被悄悄丢掉。
-    unfinished: list[I] = list(queue)
-    for th, item, holder in running:
-        if th.is_alive():
-            unfinished.append(item)
-        else:
-            value = holder.get("v", TaskError(item, RuntimeError("任务结束但没有返回值")))
-            finished.append((item, value))
+        remain = deadline - clock()
+        wait_step = remain
+        if queue and stagger_s > 0 and last_start is not None:
+            wait_step = min(wait_step, max(0.0, stagger_s - (clock() - last_start)))
+        step = min(poll, wait_step) if poll > 0 else wait_step
+        poll_wait(step, done_evt)
+
+    # 收尾：再收一次（线程与观测之间有时间差），其余不 join、计入 unfinished。
+    _harvest()
+    # 没排上起跑的任务（仍在 queue）与新起跑但没回来的任务（running）都要进
+    # unfinished：前者只是没轮到，但也确实没结果，悄悄丢掉会让调用方以为
+    # 「全部拿到了」。两者的区别用 downstream 的 enough 提前收尾路径处理：
+    # 那条路径上 queue 已被清空，所以不会有误报。
+    unfinished: list[I] = list(queue) + [item for _th, item, _h in running]
     return finished, unfinished

package/scripts/clock_bridge.py

@@ -0,0 +1,22 @@
+#!/usr/bin/env python3
+"""clock_bridge.py — 统一时钟的一行入口（2026-10-24）。
+
+计时断言与「预算夹紧」判定不该取决于机器快慢：测试域用 tests/_measure 的
+虚拟时钟，生产路径就是 ``time.monotonic``。各模块从这里取 ``clock``，不再各自
+复制一段 try/except（那会让千行文件更难拆，也容易只改一半——本文件对应的
+fetch_v3 就曾因「预算夹在超时请求上、耗时却按真实墙钟算」而被测出击穿）。
+
+与 ``tests/_measure.py`` 的关系：那个模块定义语义（虚拟/真实、预算锚点、
+确定性时间线），本模块只做「生产环境安全地取到它」这一件事。
+"""
+
+from __future__ import annotations
+
+import time
+
+try:  # 测试域：虚拟时钟（见 tests/_measure.py）
+    from _measure import clock  # type: ignore
+except ImportError:  # pragma: no cover - 生产路径
+    clock = time.monotonic
+
+__all__ = ["clock"]