argo-search 2.9.7 → 2.9.9

package/scripts/tail_completion.py

@@ -0,0 +1,212 @@
+"""tail_completion.py — 早停后台补全：慢源交付从「丢弃」变「补齐」。
+
+## 为什么（2026-10-25）
+
+七天窗口 1185 条真实查询里 74% 发生 early-stop。被放弃的交付不是低质货：
+离线回放（bench_tail_ab --quality）显示被放弃交付 81% 来自 anysearch，相关度
+代理比全库均线高 0.125；五条对照查询里四条「唯一有结果的就是慢源」（证据与
+口径见 docs/QUALITY_OF_SLOW_SOURCES.md）。早停省的是**用户等待**，不该连
+**交付**一起丢——那是在拿准确性换速度。缩尾宽已被实证否决，本模块是拍板的
+正确方向：慢源不拖住快源（早交付），但慢源的交付进缓存（后台补全）。
+
+## 做什么
+
+engine_dispatch 在早停弃置引擎时把 (engine, holder, now_fn) 交给本模块——
+主响应与既有记账逐位不变（cancelled outcome / abandoned_ms 照记）。本模块
+起一个 daemon 收割线程，在主流程返回后继续等被弃置的引擎，宽限内完成的：
+
+1. 学习器记真实成绩（success / latency / quality / 场景分桶标签）——此前
+   cancelled 被 cache_guard.should_record_adaptive 跳过，慢源的真实表现
+   从没进过学习器，场景分桶（engine×domain×lang）也少一笔真数据；
+2. 把交付合并写回 L2 combo 缓存（URL 去重、新条目追加、缺省 score 用词面
+   相关度）——同查询第二次免费拿到「快源+慢源」的全量覆盖。
+
+timeout 弃置不收：那是引擎确实超窗（甚至卡死），补全等于鼓励慢源；
+cancelled 是「编排收工决定，引擎没失败」——两者语义不同（见
+engine_dispatch._settle_pending 的注释）。
+
+## 进程语义
+
+收割线程是 daemon；CLI 进程退出前由 atexit 宽限等待（hand_off 首次调用时
+注册，无 stranded 的进程零成本、不注册）。MCP/daemon 常驻进程不退出，
+自然收割全部。宽限从**入队时刻**起算整批（job 级 deadline），不做逐引擎
+累加——实测被放弃交付从早停时刻起的剩余等待 p50 2306ms / p90 3883ms。
+
+## 开关
+
+ARGO_TAIL_COMPLETE_S：宽限秒数（默认 3.0；0=禁用整个机制，行为回到
+纯丢弃）。改动记得同步 references/usage.md 的开关总表（usage_doc_gates）。
+"""
+
+from __future__ import annotations
+
+import atexit
+import os
+import threading
+
+_LOCK = threading.Lock()
+_JOBS: list[dict] = []
+_WORKER: threading.Thread | None = None
+_ATEXIT_REGISTERED = False
+_STATS = {"salvaged": 0, "expired": 0, "recorded": 0}
+_POLL_INTERVAL_S = 0.05
+
+
+def grace_seconds() -> float:
+    """收割宽限（ARGO_TAIL_COMPLETE_S，默认 3.0；<=0 禁用）。"""
+    try:
+        return float(os.environ.get("ARGO_TAIL_COMPLETE_S", "3.0") or 3.0)
+    except ValueError:
+        return 3.0
+
+
+def hand_off(stranded, *, query, cache_engine_key, max_results,
+             domain, mode, depth, decision, skip_cache=False,
+             cache_instance=None) -> None:
+    """把早停弃置的引擎交给后台收割。
+
+    ``stranded`` 是 engine_dispatch 产出的 ``[(engine, holder, now_fn), ...]``：
+    holder["r"] 出现即完成（与 _ingest_holder 同判据），now_fn 用于算真实
+    latency（dispatch 可能跑在单调钟上，收割线程不能用墙钟去减）。
+    ``cache_instance`` 是本次请求的缓存实例（req.cache）：补全读写的必须是
+    同一实例（L1 内存态 + L2 落盘一致），模块级没有全局缓存可拿。
+    其余参数与 finalize 的 cache.set / learner.record 同源同口径。
+    任何异常 fail-open：补全失败只丢「锦上添花」，不影响主响应。
+    """
+    grace = grace_seconds()
+    if grace <= 0 or not stranded:
+        return
+    global _ATEXIT_REGISTERED
+    with _LOCK:
+        if not _ATEXIT_REGISTERED:
+            atexit.register(wait_for_completion)
+            _ATEXIT_REGISTERED = True
+        _JOBS.append({
+            "stranded": list(stranded),
+            "deadline": _now_wall() + grace,
+            "query": query, "cache_engine_key": cache_engine_key,
+            "max_results": max_results, "domain": domain,
+            "mode": mode, "depth": depth, "decision": decision or {},
+            "skip_cache": bool(skip_cache) or cache_instance is None,
+            "cache": cache_instance,
+        })
+        _start_worker_locked()
+
+
+def wait_for_completion(timeout_s: float | None = None) -> None:
+    """等收割线程收尾（atexit 出口 / 测试用）。宽限耗尽即返回，不无限等。"""
+    t = _WORKER
+    if t is not None and t.is_alive():
+        budget = timeout_s if timeout_s is not None else grace_seconds() + 0.5
+        t.join(timeout=budget)
+
+
+def stats() -> dict:
+    """收割计数（可观测口，供诊断；不改任何行为）。"""
+    with _LOCK:
+        return dict(_STATS)
+
+
+def _now_wall() -> float:
+    import time
+    return time.time()
+
+
+def _start_worker_locked() -> None:
+    global _WORKER
+    if _WORKER is not None and _WORKER.is_alive():
+        return
+    _WORKER = threading.Thread(target=_worker, daemon=True,
+                               name="argo-tail-completion")
+    _WORKER.start()
+
+
+def _worker() -> None:
+    """串行收割队列：宽限内完成的记学习器+合并缓存，超宽限标 expired。"""
+    import time
+    while True:
+        with _LOCK:
+            if not _JOBS:
+                return
+            job = _JOBS.pop(0)
+        for eng, holder, now_fn in job["stranded"]:
+            remaining = job["deadline"] - _now_wall()
+            while holder.get("r") is None and remaining > 0:
+                time.sleep(min(_POLL_INTERVAL_S, remaining))
+                remaining = job["deadline"] - _now_wall()
+            res = (holder.get("r") or (None,))[1] if holder.get("r") else None
+            if res is None:
+                with _LOCK:
+                    _STATS["expired"] += 1
+                continue
+            goods = [r for r in (res or [])
+                     if isinstance(r, dict) and "error" not in r]
+            with _LOCK:
+                _STATS["salvaged"] += 1
+            try:
+                _record_adaptive(eng, goods, holder, now_fn, job)
+            except Exception:
+                pass
+            if not job["skip_cache"]:
+                try:
+                    _merge_into_cache(eng, goods, job)
+                except Exception:
+                    pass
+
+
+def _record_adaptive(eng, goods, holder, now_fn, job) -> None:
+    """学习器记真实成绩（口径与 search_pipeline.finalize 对齐）。"""
+    from adaptive import get_learner, scenario_of
+    from query_signals import result_relevance
+    success = bool(goods)
+    try:
+        lat_ms = float((now_fn() - holder.get("t0", now_fn())) * 1000.0)
+    except Exception:
+        lat_ms = 0.0
+    quality = None
+    if success:
+        try:
+            quality = result_relevance(job["query"], goods)
+        except Exception:
+            quality = None
+    with _LOCK:
+        _STATS["recorded"] += 1
+    get_learner().record(eng, success=success, latency_ms=max(0.0, lat_ms),
+                         cost=0.001, empty=not success, quality=quality,
+                         **scenario_of(job["decision"]))
+
+
+def _merge_into_cache(eng, goods, job) -> None:
+    """交付合并写回 L2 combo 缓存：读现条目 → URL 去重追加 → 同 key 覆盖。
+
+    只在已有缓存条目时合并（本机制补的是「快源已写的那份」）；主缓存被守卫
+    拒写时这里不硬造。score 缺省用词面相关度，保证追加条目有可排序的分数。
+    """
+    from query_signals import result_relevance
+    cache = job["cache"]
+    cur = cache.get(job["query"], job["cache_engine_key"],
+                    job["max_results"], domain=job["domain"],
+                    mode=job["mode"], depth=job["depth"])
+    if not cur or not isinstance(cur.get("results"), list) or not goods:
+        return
+    existing = {r.get("url") for r in cur["results"]
+                if isinstance(r, dict)}
+    new: list[dict] = []
+    for r in goods:
+        if not isinstance(r, dict) or r.get("url") in existing:
+            continue
+        item = dict(r)
+        if "score" not in item:
+            try:
+                item["score"] = round(float(result_relevance(job["query"], [r])), 4)
+            except Exception:
+                item["score"] = 0.3
+        new.append(item)
+    if not new:
+        return
+    payload = dict(cur)
+    payload["results"] = list(cur["results"]) + new
+    payload["engines_used"] = sorted({*(cur.get("engines_used") or []), eng})
+    cache.set(job["query"], job["cache_engine_key"], job["max_results"],
+              payload, domain=job["domain"], mode=job["mode"],
+              depth=job["depth"])

package/scripts/url_safety.py

@@ -23,6 +23,8 @@ import ipaddress
 import os
 import re
 import socket
+import time
+import urllib.parse
 from urllib.parse import urlparse
 
 
@@ -184,9 +186,10 @@ def host_is_private(host: str) -> bool:
     if host_is_private_name(host):
         return True
     norm = _normalize_numeric_host(host)
-    if norm is not None and norm != host:
-        # 数字字面量变体：直接按规范化结果查表，不依赖各系统对
-        # 八进制/十六进制/单段整数解析行为的一致性
+    if norm is not None:
+        # 数字字面量：直接按规范化结果查表，不依赖 getaddrinfo。
+        # 标准点分形式（norm == host）此前会落到 getaddrinfo——既多一次系统
+        # 调用，又让「被 mock/劫持的解析器」能影响 SSRF 判定。
         return is_private_ip(norm)
     try:
         infos = socket.getaddrinfo(host, None, proto=socket.IPPROTO_TCP)
@@ -234,3 +237,123 @@ def is_safe_fetch_url(url: str) -> bool:
     """便捷布尔封装：仅 http/https 且目标非私有地址。"""
     ok, _ = check_url(url)
     return ok
+
+
+def max_redirects() -> int:
+    """最大重定向跳数（默认 5，合法 1-20，越界回落默认）。"""
+    try:
+        from engine_env import get_env
+        val = int(str(get_env(["ARGO_MAX_REDIRECTS"])).strip())
+    except (TypeError, ValueError):
+        return 5
+    return val if 0 < val <= 20 else 5
+
+
+def check_redirect_target(url: str, start: float) -> dict | None:
+    """校验重定向目标是否可安全请求；被拦截返回统一错误 dict，放行返回 None。
+
+    与 resolve_redirect_chain 的逐跳校验对齐——此前 _do_get/_do_post 的
+    内联重定向循环只校验首跳，重定向到内网即可绕过 SSRF。
+    """
+    ok, reason = check_url(url)
+    if ok:
+        return None
+    return {
+        "status": 0, "headers": {}, "text": "",
+        "url": url,
+        "elapsed_ms": int((time.time() - start) * 1000),
+        "error": f"重定向目标被 SSRF 防护拦截: {reason}",
+    }
+
+
+def resolve_redirect_chain(url: str, headers: dict, timeout: float,
+                           limit: int | None = None) -> str | None:
+    """逐跳安全跟随重定向：每跳目标都过 SSRF 校验（curl 通道用）。
+
+    返回最终 URL；任一跳被拦截或超过跳数返回 None。
+    """
+    if limit is None:
+        limit = max_redirects()
+    current = url
+    for _ in range(limit):
+        ok, _reason = check_url(current)
+        if not ok:
+            return None
+        parsed = urlparse(current)
+        if parsed.scheme not in ("http", "https"):
+            return None
+        try:
+            from net_proxy import open_connection, request_selector, resolve_proxy
+            proxy_url = resolve_proxy(current)
+            conn, via_proxy = open_connection(parsed, timeout, proxy_url)
+            path = parsed.path or "/"
+            if parsed.query:
+                path += "?" + parsed.query
+            conn.request("HEAD", request_selector(parsed, path, via_proxy),
+                         headers=headers)
+            resp = conn.getresponse()
+            status = resp.status
+            location = resp.getheader("Location")
+            conn.close()
+        except Exception:
+            return None
+        if status not in (301, 302, 303, 307, 308) or not location:
+            return current
+        current = urllib.parse.urljoin(current, location)
+    return None
+
+
+# ── 解析即锁定（DNS rebinding / TOCTOU 防护）─────────────────────────────────
+#
+# check_url() 在请求前解析一次 DNS，http.client 在 connect() 时再解析一次——
+# 两次之间域名可改指内网（DNS rebinding）。下面两个连接类在 connect() 里
+# 解析一次、过滤私网、把结果钉给本次 TCP 连接，窗口关闭；SNI/Host 仍用原域名。
+
+
+def _is_ip_literal(host: str) -> bool:
+    """主机名是否为 IP 字面量（v4 / v6，含 [v6] 与 IPv4-mapped）。"""
+    h = (host or "").strip().strip("[]")
+    if not h:
+        return False
+    if ":" in h:            # IPv6（含 ::ffff:a.b.c.d）
+        return True
+    parts = h.split(".")
+    return len(parts) == 4 and all(p.isdigit() for p in parts)
+
+
+def resolve_public_addresses(host: str) -> list[str]:
+    """解析主机名 → 公网地址名单（过滤私网/保留段；fake-ip 占位段放行）。
+
+    返回空列表表示「无可连的公网地址」——调用方应拒绝连接（fail-closed）。
+    """
+    try:
+        infos = socket.getaddrinfo(host, None, proto=socket.IPPROTO_TCP)
+    except OSError:
+        return []
+    out: list[str] = []
+    seen: set[str] = set()
+    for info in infos:
+        ip = info[4][0]
+        if ip in seen:
+            continue
+        seen.add(ip)
+        if is_fake_ip_address(ip):      # 代理接管域名（占位段），不可直达内网
+            out.append(ip)
+            continue
+        if is_private_ip(ip):
+            continue
+        out.append(ip)
+    return out
+
+
+def pin_host(host: str) -> str | None:
+    """返回要钉扎的公网 IP；IP 字面量或显式放行私网时返回 None。
+
+    无可连的公网地址则抛错（fail-closed）。供 safe_conn 的连接类使用。
+    """
+    if allow_private() or _is_ip_literal(host):
+        return None
+    addrs = resolve_public_addresses(host)
+    if not addrs:
+        raise OSError(f"SSRF 防护：{host} 无可连的公网地址")
+    return addrs[0]

package/scripts/usage_log.py

@@ -6,6 +6,7 @@
   - 失败静默：任何异常都吞掉返回 False，绝不拖累搜索主路径
   - 目录可注入：ARGO_USAGE_LOG_DIR 覆盖（测试隔离），默认 <状态目录>/usage_log/
   - 总开关：ARGO_USAGE_LOG=0 / false 完全关闭
+  - 夹具守卫：query 流 engines_used 出现注册表外引擎名即判测试夹具，整条拒写
   - 脱敏：query 等敏感字段由调用方截断，本模块不放大
 
 Schema（每条一行 JSON，UTF-8）：
@@ -68,6 +69,40 @@ def _enabled() -> bool:
     return env_flag("ARGO_USAGE_LOG")
 
 
+# 引擎改名前的历史别名（表外但真实）：与 usage_log_clean._ALIAS_KEEP 同一账。
+_RENAMED_ALIAS_KEEP = frozenset({"openlibrary", "bing"})
+
+
+def _canonical_engines() -> frozenset[str]:
+    """注册表引擎名全集（含历史别名豁免）。注册表加载失败返回空集——
+    守卫随之失效放行（fail-open）：守卫是防脏数据的，不能反过来丢真日志。
+
+    不做外层缓存：available_engines 走 get_registry 的 mtime 指纹自愈，每次
+    现取才能看见「daemon 常驻期间新增的本地引擎」；外层冻结只会把新引擎的
+    真日志误杀成夹具。每次构建 frozenset 是微秒级，query 流每搜索只写一条。
+    """
+    try:
+        from engines import available_engines
+        return frozenset(available_engines()) | _RENAMED_ALIAS_KEEP
+    except Exception:
+        return frozenset()
+
+
+def _fixture_engines(record: dict[str, Any]) -> list[str]:
+    """query 记录里的注册表外引擎名（别名豁免后）。
+
+    engines_used 缺失/非列表/为空一律视为无夹具信号：真实搜索的该字段
+    永远是引擎 id 列表，守卫只对「有列表且含表外名」的形态做判定。
+    """
+    used = record.get("engines_used")
+    if not isinstance(used, list) or not used:
+        return []
+    canon = _canonical_engines()
+    if not canon:
+        return []
+    return [e for e in used if not isinstance(e, str) or e not in canon]
+
+
 def emit(stream: str, record: dict[str, Any]) -> bool:
     """追加一条日志记录到 <usage_log_dir>/<stream>.jsonl。
 
@@ -75,6 +110,16 @@ def emit(stream: str, record: dict[str, Any]) -> bool:
     """
     if not _enabled():
         return False
+    if stream == "query" and _fixture_engines(record):
+        # 夹具守卫（2026-10-25）：测试夹具引擎名（fast / slow / quick_primary
+        # 这类注册表外名）屡次写进生产 query.jsonl（conftest 的
+        # ARGO_USAGE_LOG=0 与 is_synthetic_run 的黑名单各漏过一批，最近一次
+        # 2026-10-24），stats 的均值与最慢/高频引擎榜随之失真。黑名单永远
+        # 追不全新夹具名，这里在唯一落盘口用注册表白名单反向判定：表外名
+        # 即夹具，整条拒写。存量清理走 usage_log_clean.py（隔离不删除）。
+        # 只拦 query 流：route/recovery 的字段形态与测试惯例不同（route 的
+        # 格式测试本身用 e0..e14 假名），且实测污染只发生在 query 流。
+        return False
     try:
         line = json.dumps(
             {

package/scripts/wide_research.py

@@ -113,6 +113,40 @@ def normalize_tracks(raw: Any, maximum: int = 9) -> list[dict[str, Any]]:
     return out
 
 
+def build_cross_lingual_tracks(question: str, maximum: int = 4) -> list[dict[str, Any]]:
+    """为溯源与多语言任务自动构建分阶段跨语言长程轨道。"""
+    q = (question or "").strip()
+    has_tracing = bool(re.search(
+        r"(?:溯源|起源|出处|最初|源头|提出者|发明|草案|历史沿革|origin|provenance|root cause|first proposed|specification|rfc|cve)",
+        q, re.I
+    ))
+    tracks = []
+    tracks.append({
+        "id": "track-primary-lang",
+        "title": "原语言背景与核心定义",
+        "question": f"{q} 背景 定义 现状",
+        "rationale": "Primary language overview and conceptual framing.",
+        "depends_on": [],
+    })
+    if has_tracing or len(tracks) < maximum:
+        tracks.append({
+            "id": "track-origin-trace",
+            "title": "源头出处与权威一手规范长程溯源",
+            "question": f"{q} original paper inception specification first proposed RFC official repository",
+            "rationale": "Cross-lingual long-range tracing for primary sources, papers, or official specifications.",
+            "depends_on": ["track-primary-lang"],
+        })
+        tracks.append({
+            "id": "track-cross-reconciliation",
+            "title": "多语言证据交叉对账与互补验证",
+            "question": f"{q} milestone benchmark evaluation comparison timeline",
+            "rationale": "Cross-lingual reconciliation of evidence, timeline differences, and complementary facts.",
+            "depends_on": ["track-origin-trace"],
+        })
+    return tracks[:maximum]
+
+
+
 def stage_tracks(tracks: list[dict[str, Any]]) -> tuple[list[list[dict[str, Any]]], list[str]]:
     """轨道分层。work package 的分层逻辑与轨道同构：id/question/depends_on。"""
     packages = [
@@ -255,6 +289,17 @@ def evaluate_gates(
     if len(caveats) + len(unanswered) >= max(3, (len(sources) + 1) // 2):
         warnings.append({"id": "high_uncertainty",
                          "detail": f"{len(caveats)} caveats and {len(unanswered)} unanswered questions exceed the evidence threshold."})
+
+    # 内容农场与镜像站占优检查
+    farm_markers = ("ctolib.com", "coder.work", "voidcn.com", "it1352.com", "oommake.com", "py4u.net",
+                    "wenku.zone", "chinadmd.com", "jb51.net", "pc6.com", "onlinedown.net")
+    farm_hits = [s for s in sources if any(m in str(s.get("url", "")).lower() for m in farm_markers)]
+    if farm_hits and len(farm_hits) >= (len(sources) + 1) // 2:
+        warnings.append({
+            "id": "content_farm_dominant",
+            "detail": f"{len(farm_hits)} sources originate from content farms or SEO scraper mirrors; evidence quality severely degraded.",
+        })
+
     cap = "low" if failures else ("medium" if warnings else "high")
     return {"passed": not failures, "conclusion_cap": cap, "failures": failures, "warnings": warnings}
 

package/scripts/zhihu_quota.py

@@ -0,0 +1,139 @@
+#!/usr/bin/env python3
+"""zhihu_quota.py — 知乎开放平台额度查询（官方 `/api/v1/quota`）。
+
+为什么需要（2026-10-21）：知乎各能力的每日免费额度是**账号级**的，同一账号的
+多个 Access Secret 共用；本地按引擎计数会与真实额度漂移。官方额度查询不消耗
+业务额度，是唯一权威来源。本模块只做读取与缓存，不参与路由决策（路由仍用
+quota.py 的本地计数），避免每次搜索多一次外呼。
+
+用法：
+  argo quota            # 人读表
+  argo quota --json     # 机器读
+  argo quota --refresh  # 跳过 10 分钟缓存
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import time
+import urllib.request
+
+from cli_io import dumps
+from engine_env import get_env
+from engines_base import http_open
+
+API_URL = "https://developer.zhihu.com/api/v1/quota"
+CACHE_TTL_S = 600
+
+# APIID → argo 引擎名（与 config.yaml / quota_profiles.json 对齐）
+API_TO_ENGINE = {
+    "global_search": "zhihu_global",
+    "zhihu_search": "zhihu",
+    "hot_list": "zhihu_hot",
+    "question_discovery": "zhihu_questions",
+    "zhida_openai": "zhida",
+    "tools": "zhihu_tools",
+    "knowledge": "zhihu_kb",
+    "user_data": "zhihu_user",
+    "creator": "zhihu_creator",
+}
+
+
+def _cache_path():
+    import argo_paths
+    return argo_paths.state_path("zhihu_quota.json")
+
+
+def _secret() -> str:
+    return get_env(["ARGO_ZHIHU_ACCESS_SECRET", "ZHIHU_ACCESS_SECRET"])
+
+
+def _load_cache() -> dict | None:
+    try:
+        raw = json.loads(_cache_path().read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return None
+    if not isinstance(raw, dict):
+        return None
+    if time.time() - float(raw.get("ts") or 0) > CACHE_TTL_S:
+        return None
+    return raw
+
+
+def _save_cache(items: list[dict]) -> None:
+    try:
+        import argo_paths
+        argo_paths.atomic_write_json(_cache_path(),
+                                     {"ts": time.time(), "items": items})
+    except Exception:
+        pass
+
+
+def fetch_quota(*, refresh: bool = False, timeout: float = 8.0) -> dict:
+    """返回 {ok, items, error, cached}；永不抛异常（观测层不阻断主路径）。"""
+    if not refresh:
+        cached = _load_cache()
+        if cached is not None:
+            return {"ok": True, "items": cached.get("items") or [], "cached": True}
+    secret = _secret()
+    if not secret:
+        return {"ok": False, "items": [], "cached": False,
+                "error": "缺少 ZHIHU_ACCESS_SECRET"}
+    req = urllib.request.Request(API_URL, headers={
+        "Authorization": f"Bearer {secret}",
+        "X-Request-Timestamp": str(int(time.time())),
+        "Content-Type": "application/json",
+        "User-Agent": "argo-search/2.6 (unified-search@local)",
+    })
+    try:
+        with http_open(req, timeout=timeout, engine="zhihu_quota") as resp:
+            data = json.loads(resp.read().decode("utf-8", "replace"))
+    except Exception as exc:
+        return {"ok": False, "items": [], "cached": False,
+                "error": f"{type(exc).__name__}: {exc}"}
+    if data.get("Code") not in (0, None):
+        return {"ok": False, "items": [], "cached": False,
+                "error": f"Code={data.get('Code')} {data.get('Message') or ''}"}
+    items = []
+    for row in data.get("Data") or []:
+        if not isinstance(row, dict):
+            continue
+        api_id = str(row.get("APIID") or "")
+        items.append({
+            "api_id": api_id,
+            "engine": API_TO_ENGINE.get(api_id, api_id),
+            "name": row.get("APIName") or api_id,
+            "total": row.get("TotalQuota"),
+            "used": row.get("TotalUsed"),
+            "remaining": row.get("RemainingQuota"),
+        })
+    _save_cache(items)
+    return {"ok": True, "items": items, "cached": False}
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(prog="argo quota",
+                                 description="知乎开放平台当日额度（官方 API）")
+    ap.add_argument("--json", action="store_true")
+    ap.add_argument("--refresh", action="store_true")
+    args = ap.parse_args(argv)
+    out = fetch_quota(refresh=args.refresh)
+    if args.json:
+        print(dumps(out))
+        return 0 if out.get("ok") else 1
+    if not out.get("ok"):
+        print(f"额度查询失败：{out.get('error')}")
+        return 1
+    print("知乎开放平台当日额度（北京时间 00:00 重置）")
+    print(f"{'引擎':<18}{'额度项':<20}{'总额':>8}{'已用':>8}{'剩余':>8}")
+    for row in out["items"]:
+        print(f"{row['engine']:<18}{row['name']:<20}"
+              f"{str(row['total']):>8}{str(row['used']):>8}{str(row['remaining']):>8}")
+    if out.get("cached"):
+        print("（10 分钟内缓存；--refresh 强制刷新）")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/sub-skills/local-search/bm25.py

@@ -43,6 +43,7 @@ _CJK_RE = re.compile(r"[\u4e00-\u9fff]+")
 
 _K1 = 1.5
 _B = 0.75
+_DELTA = 0.5          # BM25+ 下界 (Lv & Zhai 2011)：长文档命中词保底，消除过惩罚
 # 混合权重：BM25 侧。位次先验占 1 - _W_BM25。
 _W_BM25 = 0.6
 # 旧位次衰减口径（max(0.7 - idx*0.05, 0.1)）——先验的归一化基准。
@@ -79,9 +80,10 @@ class BM25:
     引擎的 5 条结果上稳定得多——「含查询词的文档有多罕见」是跨源问题。
     """
 
-    def __init__(self, docs: list[list[str]], k1: float = _K1, b: float = _B):
+    def __init__(self, docs: list[list[str]], k1: float = _K1, b: float = _B, delta: float = _DELTA):
         self.k1 = k1
         self.b = b
+        self.delta = delta
         self.n_docs = len(docs)
         self.doc_len = [len(d) for d in docs]
         self.avgdl = (sum(self.doc_len) / self.n_docs) if self.n_docs else 0.0
@@ -113,10 +115,30 @@ class BM25:
             f = self.tf.get(t, {}).get(doc_idx, 0)
             if not f:
                 continue
-            total += self.idf(t) * (f * (self.k1 + 1.0)) / (f + denom_norm)
+            sat = (f * (self.k1 + 1.0)) / (f + denom_norm)
+            # BM25+ 饱和项下界增益（Lv & Zhai 2011）
+            total += self.idf(t) * (sat + self.delta)
         return total
 
 
+def _phrase_proximity_bonus(query: str, title: str, snippet: str) -> float:
+    """词邻近度与短语连续匹配加成（归一化为 0.0~1.0）。
+
+    当完整查询短语在标题或摘要逐字紧密出现时给予增益，提升复合词精准命中率。
+    """
+    q_low = (query or "").lower().strip()
+    if not q_low or len(q_low) < 2:
+        return 0.0
+    t_low = (title or "").lower()
+    s_low = (snippet or "").lower()
+    if q_low in t_low:
+        return 1.0  # 标题完整覆盖查询短语
+    if q_low in s_low:
+        return 0.5  # 摘要完整覆盖查询短语
+    return 0.0
+
+
+
 def _doc_text(r: dict[str, Any]) -> str:
     """参与相关度计算的文档文本：title 权重高于 snippet——做法是标题
     拼两遍（TF 加成），不引入第二套字段权重机制。"""
@@ -153,7 +175,9 @@ def rerank(by_engine: dict[str, list[dict[str, Any]]], query: str,
     for (eng, idx, r), bm in zip(flat, raw):
         bm25_norm = (bm / max_raw) if max_raw > 0 else 0.0
         prior_norm = _position_prior(idx) / _PRIOR_BASE
-        r["score"] = round(w_bm25 * bm25_norm + (1.0 - w_bm25) * prior_norm, 3)
+        prox_val = _phrase_proximity_bonus(query, r.get("title", ""), r.get("snippet", ""))
+        rel_score = min(bm25_norm * 0.80 + prox_val * 0.20, 1.0) if bm25_norm > 0 else 0.0
+        r["score"] = round(w_bm25 * rel_score + (1.0 - w_bm25) * prior_norm, 3)
 
     for eng in by_engine:
         by_engine[eng].sort(