argo-search 1.0.1 → 2.9.8

package/scripts/badcase_ledger.py

@@ -0,0 +1,252 @@
+#!/usr/bin/env python3
+"""badcase_ledger — 坏例账本：把分散三处的失败统一入账、可查、可做发布门禁。
+
+定位（2026-10-11 方案丙）：argo 的失败证据分散在三处、形态各异——
+  1. usage_log/query.jsonl：errors[] 非空或 count=0 的真实查询（含 serp_guard
+     整页误杀外露，见 search.py drain 处）；
+  2. usage_log/recovery.jsonl：触发过恢复链的查询（triggered=true）；
+  3. circuit_breaker.json：state != closed 的引擎（点状快照，引擎级坏例）。
+本工具把它们归一进 SQLite 账本（<state>/badcase.db），支持 ingest（幂等去重）、
+list、stats 与 check（发布前门禁：近 N 天新增坏例超阈值即非零退出）。
+
+与 replay_eval.py 的分工：replay_eval 用录制重放整条管线评打分质量（离线
+仲裁）；本账本只收纳「真实发生的失败」并让它们可归因、可回归——对应评测
+体系的 badcase 管理环节：发现 → 入账 → 归因 → 修复后 check 不复发。
+
+数据卫生：engines_used 含表外引擎名（夹具/拼写错）的记录不入账——账本只收
+真实坏例，与 usage_log_clean 的隔离口径同源（engines.available_engines）。
+
+用法：
+  python3 scripts/badcase_ledger.py ingest            # 三源归一入账（幂等）
+  python3 scripts/badcase_ledger.py list --kind query_error --limit 10
+  python3 scripts/badcase_ledger.py stats             # 按 kind/引擎聚合
+  python3 scripts/badcase_ledger.py check --since 7d --max 50   # 发布门禁
+"""
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import sqlite3
+import sys
+from collections import Counter
+from datetime import datetime, timedelta
+from pathlib import Path
+from typing import Any
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+import argo_paths  # noqa: E402
+from engines import available_engines  # noqa: E402
+from usage_log import usage_log_dir  # noqa: E402
+
+_CANON = frozenset(available_engines())
+
+_SCHEMA = (
+    "CREATE TABLE IF NOT EXISTS badcases ("
+    " id INTEGER PRIMARY KEY,"
+    " kind TEXT NOT NULL,"        # query_error | empty_result | recovery | breaker
+    " ts TEXT NOT NULL,"          # 原始 ISO 时间串；breaker 快照用入账时刻
+    " query TEXT NOT NULL DEFAULT '',"
+    " engine TEXT NOT NULL DEFAULT '',"
+    " detail TEXT NOT NULL DEFAULT '',"
+    " fingerprint TEXT NOT NULL UNIQUE)"
+)
+
+
+def db_path() -> Path:
+    return argo_paths.state_path("badcase.db")
+
+
+def _connect() -> sqlite3.Connection:
+    con = sqlite3.connect(str(db_path()), timeout=8)
+    con.execute(_SCHEMA)
+    return con
+
+
+def _rows_from_query_log(path: Path) -> list[dict[str, Any]]:
+    if not path.exists():
+        return []
+    out = []
+    for line in path.read_text(encoding="utf-8").splitlines():
+        if not line.strip():
+            continue
+        try:
+            r = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        raw_used = r.get("engines_used") or []
+        used = [e for e in raw_used if e in _CANON]
+        if not used and raw_used:
+            continue  # 表外名占满 → 夹具行，不入账（口径同 usage_log_clean）
+        raw_errors = r.get("errors")
+        # 生产日志里 errors 有两种形态：字符串列表（主流）与 int 计数（部分
+        # 旧条目）——统一成字符串列表再取前几条
+        errors = (raw_errors if isinstance(raw_errors, list)
+                  else ([str(raw_errors)] if raw_errors else []))
+        if not errors and r.get("count"):
+            continue  # 正常条目不是坏例
+        if errors:
+            out.append({"kind": "query_error", "ts": r.get("ts", ""),
+                        "query": r.get("query", ""),
+                        "engine": ",".join(used[:3]),
+                        "detail": " | ".join(str(e)[:160] for e in errors[:3])})
+        else:
+            out.append({"kind": "empty_result", "ts": r.get("ts", ""),
+                        "query": r.get("query", ""),
+                        "engine": ",".join(used[:3]),
+                        "detail": f"count=0, mode={r.get('mode')}"})
+    return out
+
+
+def _rows_from_recovery_log(path: Path) -> list[dict[str, Any]]:
+    if not path.exists():
+        return []
+    out = []
+    for line in path.read_text(encoding="utf-8").splitlines():
+        if not line.strip():
+            continue
+        try:
+            r = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        if not r.get("triggered"):
+            continue
+        out.append({"kind": "recovery", "ts": r.get("ts", ""),
+                    "query": r.get("query", ""),
+                    "engine": "",
+                    "detail": (f"level={r.get('level_used')} "
+                               f"strategy={r.get('strategy_used')} "
+                               f"recovered={r.get('recovered')}")})
+    return out
+
+
+def _rows_from_breaker(path: Path) -> list[dict[str, Any]]:
+    if not path.exists():
+        return []
+    try:
+        engines = json.loads(path.read_text(encoding="utf-8")).get("engines", {})
+    except (json.JSONDecodeError, OSError):
+        return []
+    out = []
+    now = datetime.now().astimezone().isoformat(timespec="seconds")
+    for name, st in sorted(engines.items()):
+        if st.get("state") == "closed":
+            continue
+        out.append({"kind": "breaker", "ts": now, "query": "", "engine": name,
+                    "detail": (f"state={st.get('state')} "
+                               f"failures={st.get('failures')} "
+                               f"opens={st.get('opens')}")})
+    return out
+
+
+def ingest() -> dict:
+    log_dir = usage_log_dir()
+    rows = (_rows_from_query_log(log_dir / "query.jsonl")
+            + _rows_from_recovery_log(log_dir / "recovery.jsonl")
+            + _rows_from_breaker(argo_paths.state_path("circuit_breaker.json")))
+    con = _connect()
+    added = 0
+    try:
+        for r in rows:
+            fp = hashlib.sha1("|".join(
+                [str(r["kind"]), str(r["ts"]), str(r["query"]),
+                 str(r["engine"]), str(r["detail"])[:120]])
+                .encode("utf-8")).hexdigest()
+            cur = con.execute(
+                "INSERT OR IGNORE INTO badcases(ts, query, engine, detail,"
+                " kind, fingerprint) VALUES (?,?,?,?,?,?)",
+                (r["ts"], r["query"], r["engine"], r["detail"],
+                 r["kind"], fp))
+            added += cur.rowcount
+        total = con.execute("SELECT COUNT(*) FROM badcases").fetchone()[0]
+        con.commit()
+    finally:
+        con.close()
+    return {"sources": len(rows), "added": added, "total": total,
+            "db": str(db_path())}
+
+
+def _parse_since(since: str) -> datetime:
+    """7d / 24h / 2026-10-01 → datetime（本地时区）。"""
+    since = since.strip().lower()
+    now = datetime.now().astimezone()
+    if since.endswith("d") and since[:-1].isdigit():
+        return now - timedelta(days=int(since[:-1]))
+    if since.endswith("h") and since[:-1].isdigit():
+        return now - timedelta(hours=int(since[:-1]))
+    return datetime.fromisoformat(since).astimezone()
+
+
+def _fetch(kind: str | None, since: datetime | None,
+           limit: int) -> list[dict[str, Any]]:
+    con = _connect()
+    try:
+        sql = ("SELECT ts, kind, query, engine, detail FROM badcases"
+               " WHERE 1=1")
+        params: list = []
+        if kind:
+            sql += " AND kind = ?"
+            params.append(kind)
+        if since is not None:
+            sql += " AND ts >= ?"
+            params.append(since.isoformat(timespec="seconds"))
+        sql += " ORDER BY ts DESC LIMIT ?"
+        params.append(limit)
+        keys = ["ts", "kind", "query", "engine", "detail"]
+        return [dict(zip(keys, row)) for row in con.execute(sql, params)]
+    finally:
+        con.close()
+
+
+def check(since: str, max_new: int) -> dict:
+    rows = _fetch(None, _parse_since(since), limit=10_000)
+    ok = len(rows) <= max_new
+    return {"since": since, "new_badcases": len(rows), "max": max_new,
+            "ok": ok}
+
+
+def stats() -> dict:
+    con = _connect()
+    try:
+        by_kind = dict(con.execute(
+            "SELECT kind, COUNT(*) FROM badcases GROUP BY kind").fetchall())
+        by_engine = dict(con.execute(
+            "SELECT engine, COUNT(*) FROM badcases WHERE engine != ''"
+            " GROUP BY engine ORDER BY COUNT(*) DESC LIMIT 8").fetchall())
+        total = con.execute("SELECT COUNT(*) FROM badcases").fetchone()[0]
+    finally:
+        con.close()
+    return {"total": total, "by_kind": by_kind, "top_engines": by_engine}
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(description="坏例账本（badcase 管理）")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    sub.add_parser("ingest")
+    p_list = sub.add_parser("list")
+    p_list.add_argument("--kind", default=None,
+                        choices=["query_error", "empty_result",
+                                 "recovery", "breaker"])
+    p_list.add_argument("--limit", type=int, default=10)
+    sub.add_parser("stats")
+    p_check = sub.add_parser("check")
+    p_check.add_argument("--since", default="7d")
+    p_check.add_argument("--max", type=int, default=50)
+    args = ap.parse_args(argv)
+    if args.cmd == "ingest":
+        print(json.dumps(ingest(), ensure_ascii=False))
+    elif args.cmd == "list":
+        for row in _fetch(args.kind, None, args.limit):
+            print(json.dumps(row, ensure_ascii=False))
+    elif args.cmd == "stats":
+        print(json.dumps(stats(), ensure_ascii=False))
+    elif args.cmd == "check":
+        report = check(args.since, args.max)
+        print(json.dumps(report, ensure_ascii=False))
+        return 0 if report["ok"] else 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/batch_probe.py

@@ -0,0 +1,241 @@
+#!/usr/bin/env python3
+"""batch_probe.py — 批量 URL 预检报告。
+
+第一性原理：批量抓取最贵的失败方式是「跑到一半才知道一半拿不到」。
+整批直接开工，失败会在中途以各种形态冒出来（登录墙、链接已死、
+内容早就有），此时预算已经花掉一半。预检把可预判的失败挪到开工前，
+先给一张「什么能拿、什么拿不到、为什么」的清单，再决定怎么执行。
+
+条目分四类：
+  unsupported   无法处理：不是合法的 http(s) URL——执行前就该剔除
+  needs_auth    存在但需要登录态：用户能解决（先补凭证），提前列出
+  already_have  本地归档已有该 URL 的结果：跳过，不重复抓
+  not_found     探测发现已死（404/410）：从批次里剔除或换源
+                （仅在 --probe 开启时判定；不探测不臆测）
+
+结论三档：
+  go            全部可执行
+  go_with_skips 部分可执行（清单随报告给出）
+  stop          没有可执行条目
+
+两条纪律：
+  - needs_auth 是唯一「用户可行动」的问题，报告里单独一节；
+    unsupported/not_found 是平台侧事实，列出即可。
+  - 网络探测失败（连不上）不产生判定——探测不到不等于不存在，
+    不能把「可能的问题」换成「确定的误杀」。未探测的条目类别为 None，
+    只记 unknown，不影响 go 判定。
+
+本模块只做判定，不做抓取：网络探测是可选步骤，抓取由 article/crawl
+等执行器负责。判定与 I/O 分离，保证纯函数部分可单测。
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+import urllib.parse
+from concurrent.futures import ThreadPoolExecutor
+from pathlib import Path
+from typing import Any
+from cli_io import dumps
+
+UNSUPPORTED = "unsupported"
+NEEDS_AUTH = "needs_auth"
+ALREADY_HAVE = "already_have"
+NOT_FOUND = "not_found"
+UNKNOWN = "unknown"
+
+# 用户可自行解决的问题（报告分节与文案依据）
+ACTIONABLE = {NEEDS_AUTH}
+
+# 常年登录墙的站点（公开内容也要登录才能看）。这里只列「正文必须登录」
+# 的域——「有登录墙但首页可读」的站不列，避免误杀。
+_KNOWN_LOGIN_WALLS = (
+    "x.com", "twitter.com", "instagram.com", "threads.net",
+    "facebook.com", "patreon.com", "medium.com",
+    "linux.do", "bbs.zhihu.com",
+)
+
+# 登录墙里的例外：单条推文有免登录通道（twitter_syndication 引擎走
+# cdn.syndication.twimg.com）。判 needs_auth 会把用户支去「补凭证」，
+# 而这条 URL 其实现在就能抓——同一批次里两个功能互相打架。
+_LOGIN_WALL_EXEMPT_HOSTS = ("x.com", "twitter.com")
+
+
+def _has_login_free_channel(host: str, url: str) -> bool:
+    """该 URL 是否走 argo 已有的免登录通道（目前仅单条推文）。"""
+    if not any(host == d or host.endswith("." + d)
+               for d in _LOGIN_WALL_EXEMPT_HOSTS):
+        return False
+    try:
+        from engines_builders_intl import extract_tweet_id
+    except ImportError:
+        return False
+    return extract_tweet_id(url) is not None
+
+
+_TIER_LIMITS = {"probe": 8}
+
+
+def classify_url(url: str, known_urls: set[str] | None = None) -> str:
+    """本地规则分类（无网络）。返回四类之一或 UNKNOWN（合法但无本地证据）。"""
+    u = (url or "").strip()
+    if not u:
+        return UNSUPPORTED
+    parsed = urllib.parse.urlparse(u)
+    if parsed.scheme not in ("http", "https") or not parsed.hostname:
+        return UNSUPPORTED
+    host = parsed.hostname.lower()
+    if known_urls and u in known_urls:
+        return ALREADY_HAVE
+    if any(host == d or host.endswith("." + d) for d in _KNOWN_LOGIN_WALLS):
+        # 例外的判定要用原始 URL（推文 ID 在路径/查询串里，不是 host 的一部分）
+        if _has_login_free_channel(host, u):
+            return UNKNOWN
+        return NEEDS_AUTH
+    return UNKNOWN
+
+
+def probe_liveness(url: str, timeout: float = 6.0) -> str | None:
+    """网络探测单条 URL 的存活。
+
+    返回 NOT_FOUND（404/410，确定已死）、UNKNOWN（任何其他结局——
+    包括连接失败：连不上不是「不存在」的证据）。
+    """
+    try:
+        from http_client import fetch_url
+        resp = fetch_url(url, timeout=timeout)
+        status = resp.get("status") or 0
+        if status in (404, 410):
+            return NOT_FOUND
+        return UNKNOWN
+    except Exception:
+        return UNKNOWN
+
+
+def probe_batch(
+    urls: list[str],
+    *,
+    known_urls: set[str] | None = None,
+    do_probe: bool = False,
+) -> dict[str, Any]:
+    """对一批 URL 生成预检报告。
+
+    返回 {
+      total, ready, verdict,
+      items: [{url, problem(或 None), actionable}],
+      ready_urls,          # 可执行清单
+      by_problem: {类别: [url]},
+    }
+    """
+    known = known_urls or set()
+    items: list[dict[str, Any]] = []
+
+    # 网络探测只对「本地无证据」的条目做——unsupported/auth/已归档的
+    # 判定不需要网络；探测并发受 TIER_LIMITS 约束，不放大源站压力
+    local_kinds = [classify_url(u, known) for u in urls]
+    net_kinds: dict[int, str] = {}
+    if do_probe:
+        candidates = [(i, u) for i, (u, k) in enumerate(zip(urls, local_kinds))
+                      if k == UNKNOWN]
+        if candidates:
+            with ThreadPoolExecutor(
+                    max_workers=min(len(candidates), _TIER_LIMITS["probe"])) as ex:
+                for (i, _u), kind in zip(candidates,
+                                         ex.map(lambda t: probe_liveness(t[1]),
+                                                candidates)):
+                    net_kinds[i] = kind or UNKNOWN
+
+    for i, u in enumerate(urls):
+        kind = local_kinds[i]
+        if kind == UNKNOWN and i in net_kinds:
+            kind = net_kinds[i]
+        items.append({
+            "url": u,
+            "problem": kind if kind != UNKNOWN else None,
+            "actionable": kind in ACTIONABLE,
+        })
+
+    ready = [it for it in items if it["problem"] is None]
+    by_problem: dict[str, list[str]] = {}
+    for it in items:
+        if it["problem"]:
+            by_problem.setdefault(it["problem"], []).append(it["url"])
+
+    if not ready:
+        verdict = "stop"
+    elif len(ready) < len(items):
+        verdict = "go_with_skips"
+    else:
+        verdict = "go"
+
+    return {
+        "total": len(items),
+        "ready": len(ready),
+        "verdict": verdict,
+        "items": items,
+        "ready_urls": [it["url"] for it in ready],
+        "by_problem": by_problem,
+    }
+
+
+def _format_report(report: dict[str, Any]) -> str:
+    """纯文本报告（给人看）。"""
+    lines = [
+        f"预检报告：共 {report['total']} 条，可执行 {report['ready']} 条"
+        f"（verdict={report['verdict']}）",
+        "",
+    ]
+    labels = {
+        NEEDS_AUTH: "需要登录态（可行动：先补凭证再抓）",
+        UNSUPPORTED: "无法处理（非 http(s) URL）",
+        ALREADY_HAVE: "本地归档已有（跳过不重抓）",
+        NOT_FOUND: "探测已死（404/410）",
+    }
+    for kind in (NEEDS_AUTH, UNSUPPORTED, ALREADY_HAVE, NOT_FOUND):
+        urls = report["by_problem"].get(kind) or []
+        if urls:
+            lines.append(f"■ {labels[kind]}（{len(urls)}）")
+            lines.extend(f"  - {u}" for u in urls)
+            lines.append("")
+    lines.append(f"■ 可执行清单（{len(report['ready_urls'])}）")
+    lines.extend(f"  - {u}" for u in report["ready_urls"])
+    return "\n".join(lines)
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description="批量 URL 预检")
+    ap.add_argument("urls", nargs="*", help="URL 列表（空格分隔）")
+    ap.add_argument("--file", "-f", help="从文件读取（每行一条 URL）")
+    ap.add_argument("--json", action="store_true", help="JSON 输出")
+    ap.add_argument("--probe", action="store_true",
+                    help="联网探测存活（404/410 判死；默认纯本地规则）")
+    args = ap.parse_args()
+
+    urls = list(args.urls)
+    if args.file:
+        p = Path(args.file).expanduser()
+        if not p.exists():
+            print(f"文件不存在: {p}", file=sys.stderr)
+            return 1
+        urls.extend(
+            line.strip() for line in p.read_text(encoding="utf-8").splitlines()
+            if line.strip() and not line.strip().startswith("#"))
+    if not urls:
+        from cli_io import read_stdin_if_piped
+        urls = [line.strip() for line in read_stdin_if_piped().splitlines()
+                if line.strip()]
+    if not urls:
+        ap.print_help()
+        return 1
+
+    report = probe_batch(urls, do_probe=args.probe)
+    if args.json:
+        print(dumps(report))
+    else:
+        print(_format_report(report))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/benchmark.py

@@ -10,7 +10,16 @@ benchmark.py — 性能测试
 """
 from __future__ import annotations
 
+# 状态隔离（2026-10-10 方案甲）：走真实搜索路径的脚本会写生产状态（实测夹具
+# 引擎已混入 circuit_breaker/usage_log）。须先于 argo 状态模块导入重定向
+# （机制见 argo_paths.isolate_state_dir docstring）；被测试导入时不生效。
+if __name__ == "__main__":
+    from argo_paths import isolate_state_dir
+    isolate_state_dir("argo-bench")
+
+import atexit
 import json
+import shutil
 import sys
 import time
 import os
@@ -18,6 +27,16 @@ import os
 SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
 sys.path.insert(0, SCRIPT_DIR)
 
+# 状态隔离必须早于 cache / route 的 import：两者在模块级就按当时的
+# ARGO_STATE_DIR 定下路径常量（cache.db / adaptive.db），import 之后再设环境
+# 变量对它们无效。本脚本会真读写缓存与学习库——不隔离就会把 query_0..9 这类
+# 夹具写进生产 cache.db，且缓存命中率是拿生产热缓存量出来的（数字失真）。
+# 无法像 search_benchmark.py 那样放进 main()：本文件的 cache/route 是模块级
+# import，main() 时路径早已钉死。
+import argo_paths
+_STATE_DIR = argo_paths.isolate_state_dir("argo-bench")
+atexit.register(shutil.rmtree, _STATE_DIR, ignore_errors=True)
+
 from tfidf_router import get_router, semantic_route
 from cache import SearchCache
 from route import route_query

package/scripts/bounded_run.py

@@ -0,0 +1,144 @@
+#!/usr/bin/env python3
+"""bounded_run.py — 有界并发执行：总墙钟时间一到就返回，不被慢任务拖住。
+
+背景
+----
+仓库里多处用 ``with ThreadPoolExecutor(...) as ex:`` 配合
+``as_completed(futures, timeout=T)`` 想实现「最多等 T 秒」。但 ``with`` 退出时
+会执行 ``shutdown(wait=True)``，把所有还在跑的任务 join 完才真正返回——即使
+``as_completed`` 已经超时，调用方仍会被一个卡住的网络读拖住，T 秒预算形同虚设
+（实测单查询被拖到 76s）；而且超时抛出的 TimeoutError 若没人接，会直接中断整次
+调用，已经拿到的结果也丢了。
+
+做法
+----
+改用 daemon 线程加轮询：
+
+* 任务跑在 daemon 线程上，到点就返回已完成的结果，**不去 join 还没完成的任务**
+  （daemon 线程不会阻止进程退出，各任务内部仍有自己的超时保底）；
+* 单个任务抛异常只记成该任务失败，不影响其它任务；
+* 总墙钟时间被 ``wait_s`` 硬性约束，不会超出。
+
+search.py 的引擎并发已经是这套做法，这里抽成通用实现，供 research / social /
+crawl / fetch 等复用，避免同一类问题在各处重复出现。
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from typing import Any, Callable, Generic, TypeVar
+
+I = TypeVar("I")
+O = TypeVar("O")
+
+
+class TaskError(Generic[I]):
+    """单个任务执行时抛了异常。用对象而非魔法字符串承载，避免和任务正常返回值混淆。"""
+
+    __slots__ = ("exc", "item")
+
+    def __init__(self, item: I, exc: BaseException):
+        self.item = item
+        self.exc = exc
+
+    def __repr__(self) -> str:  # pragma: no cover - 调试辅助
+        return f"TaskError(item={self.item!r}, exc={self.exc!r})"
+
+
+def run_bounded(
+    items: list[I],
+    worker: Callable[[I], O],
+    wait_s: float,
+    max_workers: int = 3,
+    *,
+    enough: Callable[[list[tuple[I, Any]]], bool] | None = None,
+    stagger_s: float = 0.0,
+    poll: float = 0.01,
+) -> tuple[list[tuple[I, Any]], list[I]]:
+    """并发执行 ``worker(item)``，总等待不超过 ``wait_s`` 秒。
+
+    返回 ``(finished, unfinished)``：
+
+    * ``finished``：已完成任务的 ``(item, value)`` 列表，按完成先后排列；
+      任务抛异常时 ``value`` 是 :class:`TaskError`，调用方按需转成失败占位。
+    * ``unfinished``：到点仍没完成（或被 ``enough`` 提前收尾时还在跑）的 item 列表，
+      调用方可据此补超时提示。这些任务不会被 join，本函数因此能准时返回。
+
+    ``enough(finished)`` 返回 True 时提前收尾：不再启动排队中的剩余任务，已在跑的
+    任务归入 unfinished。``max_workers`` 限制同时在跑的任务数。
+
+    ``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))
+    last_start: float | None = None
+    done_evt = threading.Event()
+
+    def _start(item: I) -> None:
+        holder: dict = {}
+
+        def _work() -> None:
+            try:
+                holder["v"] = worker(item)
+            except BaseException as exc:  # noqa: BLE001 - 任意任务异常都要隔离，不能让一个任务炸掉整组
+                holder["v"] = TaskError(item, exc)
+            finally:
+                done_evt.set()
+
+        th = threading.Thread(target=_work, daemon=True)
+        th.start()
+        running.append((th, item, holder))
+
+    while queue or running:
+        done_evt.clear()
+        if time.monotonic() >= deadline:
+            break
+        # 按并发上限补启动排队任务
+        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):
+                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
+        if enough is not None and enough(finished):
+            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))
+    return finished, unfinished