argo-search 2.9.7 → 2.9.8

package/scripts/engines_builders_batch15.py

@@ -0,0 +1,249 @@
+#!/usr/bin/env python3
+"""批次十五构建器：腾讯元宝搜索（2026-10-21）。
+
+  yuanbao   腾讯元宝搜索（api.wsa.cloud.tencent.com/SearchPro，需 key）
+
+为什么需要独立 builder（声明式 type: http 表达不了）：
+
+  1. **Pages 是 JSON 字符串数组**——`Response.Pages[i]` 本身是 JSON 文本，
+     要二次解析；output_map 只能走普通嵌套对象。
+  2. **错误走 HTTP 200**——鉴权失败/欠费/限流全部返回 200 + `Response.Error`。
+     声明式解析会把它当「0 结果」，把「key 错了」上报成「网上没有这个信息」
+     （与 2026-09-15 `--engine you` 的 SSL 超时同族，那条踩过一次）。
+  3. **日期是 `YYYY/MM/DD HH:MM:SS`**——不是 argo 的 ISO 约定，要归一。
+  4. **Cnt 只接受 10/20/30/50**——传别的值上游直接回 `illegal Cnt` 且 0 结果。
+
+接口事实（2026-10-21 本机实测，非文档抄录）：
+
+  POST /SearchPro
+  Authorization: Bearer <key>；Content-Type: application/json; charset=utf-8
+  body  {"Query": "...", "Cnt": N}
+  返回  Response.{RequestId, Query, Version, Pages[], Error?}
+
+  单条 Pages[i] 解析后：
+    {passage, score, date, title, url, content, site, favicon, pics}
+    （文档「输出示例」写的是 images，实测字段名是 pics；README 与文档
+     不一致时以实测为准。）
+
+  错误码 → argo 失败类别：
+    UnauthorizedOperation / ResourceNotFound  → auth        （key 错 / 服务未开通）
+    ResourceUnavailable                       → quota_exhausted（账号欠费）
+    RequestLimitExceeded                      → rate_limited
+    InvalidParameter                          → upstream    （接口契约变了）
+    InternalError / 其他                       → unknown
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import urllib.request
+from datetime import datetime, timedelta, timezone
+from typing import Any
+
+from engines_base import http_open, note_failure, safe_search
+
+_UA = "argo-search/2.9 (unified-search@local)"
+_YUANBAO_URL = "https://api.wsa.cloud.tencent.com/SearchPro"
+# 腾讯侧公布的中间价/新闻口径都按北京时间；本机可能不在东八区，日期归一
+# 必须显式指定偏移，否则跨时区机器上「今天」会错一天。
+_CST = timezone(timedelta(hours=8))
+
+# key 候选链（真源在 engine_env.KNOWN_ENV_ALIASES，这里只声明本引擎要用哪条）。
+# ⚠️ 与下方 get_env 调用里的**字面量列表**必须一致——状态层的变体感知契约由
+# tests/test_env_declaration_consistency.py 静态扫描，它只认写死在调用处的
+# ast.Constant/List/Tuple；写成 `get_env(_KEY_ENV)` 会被判成「声明了却没读到」。
+# tests/test_yuanbao_engine.py 有一条把两者钉在一起。
+_KEY_ENV = ("ARGO_YUANBAO_API_KEY", "TENCENTCLOUD_WSA_APIKEY", "YUANBAO_API_KEY")
+
+# Cnt 实测只接受 10/20/30/50（1/2/5/100 均回 "illegal Cnt"）。
+_CNT_ALLOWED = (10, 20, 30, 50)
+
+_ERROR_MAP: dict[str, tuple[str, str]] = {
+    "UnauthorizedOperation": ("auth", "key 无效或未授权"),
+    "ResourceNotFound": ("auth", "服务未开通"),
+    "ResourceUnavailable": ("quota_exhausted", "账号欠费或资源不可用"),
+    "RequestLimitExceeded": ("rate_limited", "超出频率限制"),
+    "InvalidParameter": ("upstream", "参数被拒（接口契约可能已变）"),
+    "InternalError": ("unknown", "上游内部错误"),
+}
+
+_TAG_RE = re.compile(r"</?[a-zA-Z][^>]{0,40}>")
+
+
+def yuanbao_api_key() -> str:
+    """按候选链取 key（os.environ 优先，~/.config/argo/env 热读保底）。
+
+    候选链以字面量落在 get_env 调用里（原因见 _KEY_ENV 上方注释）。
+    """
+    try:
+        from engine_env import get_env
+    except ImportError:
+        import os
+        for name in _KEY_ENV:
+            v = (os.environ.get(name) or "").strip()
+            if v:
+                return v
+        return ""
+    return (get_env(["ARGO_YUANBAO_API_KEY", "TENCENTCLOUD_WSA_APIKEY",
+                     "YUANBAO_API_KEY"]) or "").strip()
+
+
+def yuanbao_cnt(n: int) -> int:
+    """把请求条数夹到上游允许的档位。
+
+    取「能覆盖 n 的最小合法档」而不是最大档：额度按次计，多要不产生额外
+    结果价值（本地还会按 n 截断），少要则可能不够。n 超出最大档时给最大档，
+    由本地截断兜底。
+    """
+    try:
+        want = int(n)
+    except (TypeError, ValueError):
+        want = 5
+    if want <= 0:
+        want = 5
+    for v in _CNT_ALLOWED:
+        if want <= v:
+            return v
+    return _CNT_ALLOWED[-1]
+
+
+def _clean(text: Any, limit: int | None = None) -> str:
+    out = _TAG_RE.sub("", str(text or "")).strip()
+    if limit is not None and len(out) > limit:
+        out = out[:limit].rstrip()
+    return out
+
+
+def _norm_date(raw: Any) -> str:
+    """`YYYY/MM/DD HH:MM:SS`（东八区）→ ISO 带偏移；无法解析返回空串。
+
+    交出去空串而不是原样字符串：argo 的 freshness/时间窗按 ISO 或年月解析，
+    把 `2023/06/08 00:00:00` 原样当 published_at 会落到「有字段但读不出日期」
+    那一类——比没有更糟（时间窗会当它无日期剔除，但浏览者会以为有日期）。
+    """
+    text = str(raw or "").strip()
+    if not text:
+        return ""
+    for fmt in ("%Y/%m/%d %H:%M:%S", "%Y-%m-%d %H:%M:%S", "%Y/%m/%d", "%Y-%m-%d"):
+        try:
+            return datetime.strptime(text, fmt).replace(tzinfo=_CST).isoformat(
+                timespec="seconds")
+        except ValueError:
+            continue
+    return ""
+
+
+def _load_page(raw: Any) -> dict[str, Any] | None:
+    """Pages[i] 是 JSON 文本（实测），兼容上游改成对象的情形。"""
+    if isinstance(raw, dict):
+        return raw
+    if not isinstance(raw, str) or not raw.strip():
+        return None
+    try:
+        obj = json.loads(raw)
+    except (json.JSONDecodeError, TypeError):
+        return None
+    return obj if isinstance(obj, dict) else None
+
+
+def parse_yuanbao_payload(data: Any, n: int, eng: str = "yuanbao"
+                          ) -> list[dict[str, Any]]:
+    """响应体 → argo 结果条目（纯函数，门禁直接打到）。
+
+    错误路径**必须**留痕：上游把 4xx/5xx 语义全塞进 HTTP 200 的
+    `Response.Error`，不留痕就会退化成 `no-results`，把「欠费」报成
+    「网上没有」。分类交给 retry_policy 的既有映射，不在此另立一套。
+    """
+    resp = data.get("Response") if isinstance(data, dict) else None
+    if not isinstance(resp, dict):
+        note_failure(eng, "upstream", "no-response", str(data)[:160])
+        return []
+
+    err = resp.get("Error")
+    if isinstance(err, dict):
+        code = str(err.get("Code") or "").strip()
+        category, reason = _ERROR_MAP.get(code, ("unknown", code or "unknown"))
+        note_failure(eng, category, reason,
+                     f"{code}: {err.get('Message') or ''}")
+        return []
+
+    pages = resp.get("Pages")
+    if not isinstance(pages, list):
+        note_failure(eng, "upstream", "pages-not-list",
+                     f"Pages 类型 {type(pages).__name__}")
+        return []
+
+    limit = max(1, int(n or 5))
+    out: list[dict[str, Any]] = []
+    for raw in pages:
+        if len(out) >= limit:
+            break
+        item = _load_page(raw)
+        if not item:
+            continue
+        url = str(item.get("url") or "").strip()
+        title = _clean(item.get("title"), 160)
+        if not url or not title:
+            continue
+        # passage 是摘要档（实测 ~800 字），content 是更长正文（~2000 字）。
+        # 搜索层只交摘要：正文按需走 fetch/verify 链，与 DeepSeek 引擎同口径。
+        snippet = _clean(item.get("passage")) or _clean(item.get("content"), 300)
+        row: dict[str, Any] = {
+            "title": title,
+            "url": url,
+            "snippet": snippet[:600],
+            "source": eng,
+        }
+        site = _clean(item.get("site"), 60)
+        if site:
+            row["site_name"] = site
+        published = _norm_date(item.get("date"))
+        if published:
+            row["published_at"] = published
+        score = item.get("score")
+        if isinstance(score, (int, float)) and not isinstance(score, bool):
+            row["upstream_score"] = float(score)
+        out.append(row)
+    return out
+
+
+def _build_yuanbao_engine(spec: dict[str, Any]) -> Any:
+    timeout = spec.get("timeout", 12)
+    eng = spec.get("_name", "yuanbao")
+    endpoint = spec.get("url") or _YUANBAO_URL
+
+    @safe_search
+    def _engine(query: str, n: int = 5, _timeout: float | None = None,
+                depth: str = "fast", **kwargs) -> list[dict[str, Any]]:
+        to = _timeout or timeout
+        q = (query or "").strip()
+        if not q:
+            return []
+        key = yuanbao_api_key()
+        if not key:
+            # 缺 key 与「配置错了」要分开：这条是缺配置，路由层已有 env 拦截，
+            # 走到这里说明是显式 --engine 调用，留痕让错误可行动。
+            note_failure(eng, "auth", "missing-key",
+                         "未配置 " + " / ".join(_KEY_ENV))
+            return []
+        body = json.dumps({"Query": q, "Cnt": yuanbao_cnt(n)},
+                          ensure_ascii=False).encode("utf-8")
+        req = urllib.request.Request(
+            endpoint, data=body, method="POST",
+            headers={
+                "Authorization": f"Bearer {key}",
+                "Content-Type": "application/json; charset=utf-8",
+                "User-Agent": _UA,
+                "Accept": "application/json",
+            },
+        )
+        try:
+            with http_open(req, timeout=to, engine=eng) as resp:
+                data = json.loads(resp.read().decode("utf-8", "replace"))
+        except Exception as e:
+            note_failure(eng, "network", "exception", str(e)[:160])
+            return []
+        return parse_yuanbao_payload(data, n, eng)
+
+    return _engine

package/scripts/engines_builders_keyless.py

@@ -0,0 +1,111 @@
+#!/usr/bin/env python3
+"""免 key（keyless）通道构建器：官方匿名额度源。
+
+与计费通道分开注册的理由：同上游、不同经济模型。匿名额度不读 key，
+按 IP/匿名池限流；与账号档混在一个引擎里会让配额与成本记账失真
+（与 parallel / parallel_free 的既有处理一致）。
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import urllib.request
+from typing import Any
+
+from engines_base import http_open, safe_search
+
+from engines_builders_tech import _mcp_error_of, _parse_mcp_wire
+
+
+# ── Keenable 免 key 通道（官方 MCP 匿名额度）────────────────────────────────
+
+_KEENABLE_MCP_URL = "https://api.keenable.ai/mcp"
+_KEENABLE_BLOCK_RE = re.compile(r"\n\s*-{3,}\s*\n")
+
+
+def _keenable_block_to_result(block: str) -> dict[str, Any] | None:
+    """Keenable MCP 的纯文本块 → 统一结果。字段以行首标签分隔。"""
+    text = (block or "").strip()
+    if not text:
+        return None
+    title = re.search(r"(?m)^Title:\s*(.+?)\s*$", text)
+    url = re.search(r"(?m)^URL:\s*(\S+)\s*$", text)
+    if not title or not url:
+        return None
+    published = re.search(r"(?m)^Published:\s*(\S+)", text)
+    body = ""
+    m = re.search(r"(?ms)^Snippets:\s*\n?(.*)$", text)
+    if m:
+        body = m.group(1)
+    body = re.sub(r"\[\.\.\.\]", " ", body)
+    body = re.sub(r"\s+", " ", body).strip()
+    row: dict[str, Any] = {
+        "title": title.group(1).strip()[:200],
+        "url": url.group(1).strip(),
+        "snippet": body[:300],
+        "source": "keenable_free",
+    }
+    if published:
+        row["published_at"] = published.group(1).strip()[:32]
+    return row
+
+
+def _build_keenable_free_engine(spec: dict[str, Any]) -> Any:
+    """Keenable 免 key：POST 官方 MCP（tools/call search_web_pages）。
+
+    为什么单独成引擎而不是让 keenable 回退：与 tavily_free / parallel_free
+    同一条口径——keyless 是匿名额度通道，与按 credits 计费的 REST 通道
+    经济模型不同，合进一个引擎会让配额与成本记账混在一起。
+
+    上游返回纯文本块（Title/URL/Published/Snippets，`---` 分隔），不是
+    JSON；解析失败按「带 error 的记录」上报，让调度层知道是通道/格式问题，
+    而不是「网上没有」。
+    """
+    timeout = spec.get("timeout", 20)
+
+    @safe_search
+    def _engine(query: str, n: int = 5, _timeout: float | None = None,
+                **kwargs) -> list[dict[str, Any]]:
+        to = _timeout or timeout
+        body = json.dumps({
+            "jsonrpc": "2.0", "id": 1, "method": "tools/call",
+            "params": {"name": "search_web_pages",
+                       "arguments": {"query": query, "mode": "realtime"}},
+        }).encode("utf-8")
+        headers = {
+            "Content-Type": "application/json",
+            "Accept": "application/json, text/event-stream",
+            "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) "
+                          "AppleWebKit/537.36 (KHTML, like Gecko) "
+                          "Chrome/120.0.0.0 Safari/537.36",
+        }
+        req = urllib.request.Request(_KEENABLE_MCP_URL, data=body, headers=headers)
+        try:
+            with http_open(req, timeout=to, engine=spec.get("_name", "")) as resp:
+                raw = resp.read().decode("utf-8", "replace")
+        except Exception as e:
+            return [{"error": f"keenable_free mcp: {type(e).__name__}: {e}",
+                     "source": "keenable_free"}]
+        data = _parse_mcp_wire(raw)
+        if not isinstance(data, dict):
+            return [{"error": "keenable_free: 响应不是可解析的 MCP 应答",
+                     "source": "keenable_free"}]
+        mcp_err = _mcp_error_of(data)
+        if mcp_err:
+            return [{"error": mcp_err, "source": "keenable_free"}]
+        content = ((data.get("result") or {}).get("content") or [])
+        text = "".join(str(b.get("text") or "") for b in content
+                       if isinstance(b, dict))
+        if not text.strip():
+            return []
+        out: list[dict[str, Any]] = []
+        for block in _KEENABLE_BLOCK_RE.split("\n" + text):
+            row = _keenable_block_to_result(block)
+            if row:
+                out.append(row)
+            if len(out) >= max(1, int(n)):
+                break
+        return out
+
+    return _engine

package/scripts/engines_builders_tech.py

@@ -1357,4 +1357,3 @@ def _build_bing_rss_engine(spec: dict[str, Any]) -> Any:
             out.append(r)
         return out
     return _engine
-

package/scripts/evidence.py

@@ -370,6 +370,26 @@ def _age_to_score(age_years: int, year: int, precise: bool) -> tuple[float, str]
 
 # ── 交叉验证 ──────────────────────────────────────────────────────────────────
 
+# 单条结果至少覆盖 20% 的 query 单元才算「与查询相关」。与 serp_guard 的
+# SERP 覆盖率门同量级，但两处判据独立：这里回答「这批结果里几条在答这题」，
+# serp_guard 回答「这一页 SERP 是不是整体答非所问」。
+_RELEVANCE_MIN_COVERAGE = 0.2
+
+
+def _relevance_units(text: str) -> set[str]:
+    """查询/结果 → 相关性比对单元（CJK 二元组 + 小写拉丁数字词）。
+
+    复用 rank_signals.relevance_units，避免再维护第三套分词口径。
+    import 放在函数内：evidence 不是搜索热路径，但 rank_signals 较重，
+    模块级导入会让所有 evidence 调用方一起付启动成本。
+    """
+    try:
+        from rank_signals import relevance_units
+        return set(relevance_units(text or ""))
+    except ImportError:
+        return {(text or "").lower()}
+
+
 def cross_validate(results: list[dict[str, Any]], query: str) -> dict[str, Any]:
     """多来源交叉验证。"""
     if len(results) < 2:
@@ -399,11 +419,19 @@ def cross_validate(results: list[dict[str, Any]], query: str) -> dict[str, Any]:
         if not is_serp_or_jump_url(url):
             content_domains.add(domain)
 
-    query_words = set(query.lower().split())
+    # 旧口径 `any(w in text for w in query.lower().split())` 在中文查询上
+    # 两个方向都错：无空格中文被当成一个整词，结果里永远不会出现整句，
+    # 真实相关也报 0/N；反过来，结果只要带「2026」这类年份就被算作相关，
+    # 年份表垃圾页也能过。改用 CJK 二元组覆盖率（issue #18 的「0/N」信号
+    # 只有在这个口径下才可信）。
+    q_units = _relevance_units(query)
     content_matches = 0
     for r in results:
-        text = f"{r.get('title', '')} {r.get('snippet', '')}".lower()
-        if any(w in text for w in query_words if len(w) > 1):
+        text = f"{r.get('title', '')} {r.get('snippet', '')}"
+        if not q_units:
+            continue
+        hit = q_units & _relevance_units(text)
+        if len(hit) / len(q_units) >= _RELEVANCE_MIN_COVERAGE:
             content_matches += 1
 
     match_ratio = content_matches / max(len(results), 1)

package/scripts/evidence_loop.py

@@ -19,6 +19,8 @@ MECE 分工（互不重叠）：
 
 from __future__ import annotations
 
+import os
+import time
 from typing import Any, Callable, Optional
 
 
@@ -34,6 +36,23 @@ def _log(message: str) -> None:
     import logging
     logging.getLogger("unified_search.evidence_loop").debug(message)
 
+
+# verify 的全局墙钟预算（秒）。0 = 关闭，逐 URL 的 8s 降级链照旧。
+#
+# why（2026-10-22 实测）：--verify 3 的最坏一次 9.7s，而单 URL 的 fetch 链
+# deadline 是 8s（见 fetch_v3 的「deadline + 5s 上界」），3 个 URL 并行时
+# 墙钟由最慢那个定义。结果是：主搜索 1.2s，核验尾巴 9.7s，而调用方在
+# timing.elapsed_ms 里只看到 1.2s。核验是「加分项」不是「必须项」：到点
+# 未回来的 URL 进 pending（语义与 fetch 失败完全一致），已回来的照常回填。
+# 默认 5s 高于典型核验 2.9s，只砍尾部；需要完整降级链时设 0。
+def _verify_budget_s() -> float:
+    try:
+        raw = os.environ.get("ARGO_VERIFY_BUDGET_S", "5") or "5"
+        value = float(raw)
+    except ValueError:
+        return 5.0
+    return value if value > 0 else 0.0
+
 # ── 高后果域（finance / health / legal / 事实与安全）──────────────────────────
 # 命中这些域时，Agent 在把搜索结果当答案前必须先核验正文。
 HIGH_CONSEQUENCE_DOMAINS: frozenset[str] = frozenset({
@@ -516,33 +535,46 @@ def verify_results(results: list[dict[str, Any]],
     # 语义层（默认关）的输入：正文已在内存，批量一次调用；关闭时不产生任何行为
     scored_inputs: list[dict[str, Any]] = []
 
-    if len(targets) > 1:
+    def _consume(r: dict, ev: dict | None, text: str) -> None:
+        """把一条 fetch 结果记进 verified/pending；成功才产生语义输入。"""
+        if ev is None:
+            pending.append(r.get("url") or "")
+            return
+        # 不再在这里重复写证据：fetch_fn（fetch_v3）成功时已把证据分
+        # 并入该 URL 的正文条目。此处再写一遍是同源同刻的双写，
+        # 合并存储后还会因为「没有正文条目」而变成静默空操作。
+        _record_verify(r, ev, verified, revisions)
+        if text.strip():
+            scored_inputs.append({"url": r.get("url") or "",
+                                  "title": r.get("title") or "",
+                                  "text": text})
+
+    budget_s = _verify_budget_s()
+    if targets and budget_s > 0:
+        # 硬墙钟：到点就返回，未完成的 URL 进 pending，不 join 卡住的线程。
+        # 预算只约束「这次核验等多久」，不改单 URL 的降级链语义。
+        from bounded_run import TaskError, run_bounded
+        finished, unfinished = run_bounded(
+            targets, _fetch_one, budget_s,
+            max_workers=min(len(targets), 3))
+        for item, value in finished:
+            if isinstance(value, TaskError):
+                _log(f"verify fetch 任务异常 {item.get('url') or ''}: "
+                     f"{type(value.exc).__name__}")
+                pending.append(item.get("url") or "")
+                continue
+            _consume(*value)
+        for item in unfinished:
+            # 与 fetch 失败同语义：拿不到正文就标 pending，不伪造已核验
+            pending.append(item.get("url") or "")
+    elif len(targets) > 1:
         with ThreadPoolExecutor(max_workers=min(len(targets), 3)) as ex:
             futures = [ex.submit(_fetch_one, r) for r in targets]
             for fut in as_completed(futures):
-                r, ev, text = fut.result()
-                if ev is None:
-                    pending.append(r.get("url") or "")
-                    continue
-                # 不再在这里重复写证据：fetch_fn（fetch_v3）成功时已把证据分
-                # 并入该 URL 的正文条目。此处再写一遍是同源同刻的双写，
-                # 合并存储后还会因为「没有正文条目」而变成静默空操作。
-                _record_verify(r, ev, verified, revisions)
-                if text.strip():
-                    scored_inputs.append({"url": r.get("url") or "",
-                                          "title": r.get("title") or "",
-                                          "text": text})
+                _consume(*fut.result())
     else:
         for r in targets:
-            r2, ev, text = _fetch_one(r)
-            if ev is None:
-                pending.append(r2.get("url") or "")
-                continue
-            _record_verify(r2, ev, verified, revisions)
-            if text.strip():
-                scored_inputs.append({"url": r2.get("url") or "",
-                                      "title": r2.get("title") or "",
-                                      "text": text})
+            _consume(*_fetch_one(r))
 
     semantic_meta: dict[str, Any] | None = None
     if scored_inputs:

package/scripts/fetch_v3.py

@@ -865,6 +865,14 @@ def _make_result(url: str, html: str, max_chars: int,
         "error": error,
         "fetch_method": method,
     }
+    # 元数据必须从**完整 HTML** 里提：delivered_html 已按 max_chars*2 截断，
+    # 链接通常在正文中后段，截断后再解析只剩 head 里的 meta（2026-10-22 实测）。
+    if ok and html:
+        try:
+            from article_meta import extract_article_meta
+            result.update(extract_article_meta(html, url))
+        except Exception:
+            pass
     result.update(extra)
     return result
 
@@ -1530,6 +1538,17 @@ def fetch_v3(url: str, max_chars: int = 8000, timeout: float = 8.0,
     # 第三级：质量评估
     result = _assess_quality(result)
 
+    # 文章级元数据（链接/作者/站点名/摘要）：与正文同源于本次 HTML，一次解析
+    # 拿全；调用方不必为了顺着引用继续取证而重抓页面。缓存一起存（链接上限
+    # 30 条，体积可控），输出侧由 CLI/MCP 决定是否展示。
+    if result.get("success") and result.get("html"):
+        try:
+            from article_meta import extract_article_meta
+            for _mk, _mv in extract_article_meta(result["html"], url).items():
+                result.setdefault(_mk, _mv)
+        except Exception:
+            pass
+
     # 写 URL 缓存（不存大块 html，省空间）
     if not skip_cache and result.get("success"):
         try:
@@ -1693,6 +1712,8 @@ def build_parser():
                    help="从正文第 N 个字符开始输出（配合 --limit 翻页读长文）")
     p.add_argument("--limit", type=int, default=0,
                    help="本次输出字符数上限；0 表示不额外限制")
+    p.add_argument("--include-links", action="store_true",
+                   help="JSON 摘要附带正文链接（默认只给 links_count，省 token）")
     p.add_argument("--json", action="store_true",
                    help="只输出 JSON 摘要（缺省还会附人类可读的正文段；"
                         "Usage 一直把 --json 列为 Common flags，此前却报"
@@ -1740,6 +1761,10 @@ if __name__ == "__main__":
         summary["focus_applied"] = bool(r.get("focus_applied"))
     if r.get("error"):
         summary["error"] = r["error"]
+    if r.get("links"):
+        summary["links_count"] = len(r["links"])
+        if args.include_links:
+            summary["links"] = r["links"]
     print(dumps(summary))
     # __main__ 块是模块级代码，不能用 return 短路——用 if 包住人类可读段
     if not args.json:

package/scripts/gen_routing_snapshot.py

@@ -29,9 +29,20 @@ from __future__ import annotations
 
 import argparse
 import json
+import os
 import sys
+import tempfile
 from pathlib import Path
 
+# 与 tests/conftest.py 对齐：快照对账必须**确定性**。默认状态目录
+# （~/.cache/unified-search）含本机历史（学习器分数 / 熔断器计数 / 配额），
+# 会让「生成时的路由」与「pytest 里的路由」不一致——实测 2026-10-22
+# 「settlement 结算 周期」在两种环境下分别是 regex 与 tfidf，门禁稳定假红
+# （单独跑 --check 通过、pytest 里 3/3 红，根因就是两边状态目录不同）。
+# 隔离到临时目录后两边都从空状态出发，逐条一致。调用方显式设置
+# ARGO_STATE_DIR 时尊重之（便于复现某个具体状态）。
+os.environ.setdefault("ARGO_STATE_DIR", tempfile.mkdtemp(prefix="argo-snapshot-"))
+
 ROOT = Path(__file__).resolve().parent.parent
 SCRIPTS = ROOT / "scripts"
 TESTS = ROOT / "tests"

package/scripts/install.ps1

@@ -77,6 +77,15 @@ if (Test-Path (Join-Path $InstallDir ".git")) {
     Write-Host "==> 克隆仓库…"
     New-Item -ItemType Directory -Force -Path (Split-Path $InstallDir) | Out-Null
     git clone --depth 1 --branch $Branch $Repo $InstallDir
+    if ($LASTEXITCODE -ne 0 -and $Repo -like "*github.com*") {
+        $MirrorRepo = "https://ghfast.top/" + $Repo
+        Write-Host "[warn] 直连 GitHub 失败，尝试加速镜像: $MirrorRepo …"
+        git clone --depth 1 --branch $Branch $MirrorRepo $InstallDir
+        if ($LASTEXITCODE -ne 0) {
+            Write-Error "克隆失败。若处于受限网络环境，可尝试手动克隆或设置 ARGO_REPO 环境变量。"
+            exit 1
+        }
+    }
 }
 
 # 供应链加固：固定 commit 校验（ARGO_PIN），与 install.sh 对齐
@@ -94,11 +103,20 @@ if ($Pin) {
 if (-not $SkipPip) {
     Write-Host "==> 安装依赖 (PyYAML)…"
     & $script:py -m pip install pyyaml
+    if ($LASTEXITCODE -ne 0) {
+        & $script:py -m pip install -i https://pypi.tuna.tsinghua.edu.cn/simple pyyaml
+    }
     if ($LASTEXITCODE -ne 0) { Write-Host "[warn] pip 安装 PyYAML 失败，可手动: pip install pyyaml" }
     Write-Host "==> 安装可选增强 (curl_cffi: TLS 指纹伪造；rapidfuzz: 去重模糊近重复复核；缺失不影响核心功能)…"
     & $script:py -m pip install curl_cffi
+    if ($LASTEXITCODE -ne 0) {
+        & $script:py -m pip install -i https://pypi.tuna.tsinghua.edu.cn/simple curl_cffi
+    }
     if ($LASTEXITCODE -ne 0) { Write-Host "[warn] pip 安装 curl_cffi 失败（可选依赖）" }
     & $script:py -m pip install rapidfuzz
+    if ($LASTEXITCODE -ne 0) {
+        & $script:py -m pip install -i https://pypi.tuna.tsinghua.edu.cn/simple rapidfuzz
+    }
     if ($LASTEXITCODE -ne 0) { Write-Host "[warn] pip 安装 rapidfuzz 失败（可选依赖，缺失时去重回退纯 minhash）" }
 }
 

package/scripts/install.sh

@@ -104,7 +104,19 @@ elif [[ -d "$INSTALL_DIR" ]] && [[ -f "$INSTALL_DIR/scripts/search.py" ]]; then
 else
   echo "==> 克隆仓库…"
   mkdir -p "$(dirname "$INSTALL_DIR")"
-  git clone --depth 1 --branch "$BRANCH" "$REPO" "$INSTALL_DIR"
+  if ! git clone --depth 1 --branch "$BRANCH" "$REPO" "$INSTALL_DIR"; then
+    if [[ "$REPO" == *"github.com"* ]]; then
+      MIRROR_REPO="https://ghfast.top/${REPO}"
+      echo "[warn] 从 GitHub 直连克隆失败，尝试加速镜像: $MIRROR_REPO …"
+      if ! git clone --depth 1 --branch "$BRANCH" "$MIRROR_REPO" "$INSTALL_DIR"; then
+        echo "!! 克隆失败。若处于受限网络环境，可尝试手动克隆或设置 ARGO_REPO 环境变量。" >&2
+        exit 1
+      fi
+    else
+      echo "!! 克隆失败，请检查网络连接。" >&2
+      exit 1
+    fi
+  fi
 fi
 
 # 供应链加固：校验 HEAD 与预期 commit 一致（ARGO_PIN 固定）
@@ -122,13 +134,16 @@ if [[ "$SKIP_PIP" != "1" ]]; then
   echo "==> 安装依赖 (PyYAML)…"
   python3 -m pip install --user -q pyyaml 2>/dev/null \
     || python3 -m pip install -q pyyaml 2>/dev/null \
+    || python3 -m pip install --user -q -i https://pypi.tuna.tsinghua.edu.cn/simple pyyaml 2>/dev/null \
     || echo "[warn] pip 安装 PyYAML 失败，可手动: pip install pyyaml"
   echo "==> 安装可选增强 (curl_cffi: TLS 指纹伪造；rapidfuzz: 去重模糊近重复复核；缺失不影响核心功能)…"
   python3 -m pip install --user -q curl_cffi 2>/dev/null \
     || python3 -m pip install -q curl_cffi 2>/dev/null \
+    || python3 -m pip install --user -q -i https://pypi.tuna.tsinghua.edu.cn/simple curl_cffi 2>/dev/null \
     || echo "[warn] pip 安装 curl_cffi 失败（可选依赖）。需要反爬 TLS 指纹伪造时手动: pip install curl_cffi"
   python3 -m pip install --user -q rapidfuzz 2>/dev/null \
     || python3 -m pip install -q rapidfuzz 2>/dev/null \
+    || python3 -m pip install --user -q -i https://pypi.tuna.tsinghua.edu.cn/simple rapidfuzz 2>/dev/null \
     || echo "[warn] pip 安装 rapidfuzz 失败（可选依赖）。缺失时去重回退纯 minhash，需要模糊近重复复核时手动: pip install rapidfuzz"
 fi