argo-search 1.0.1 → 2.9.8

package/scripts/engines_builders.py

@@ -0,0 +1,310 @@
+#!/usr/bin/env python3
+"""engines_builders — 聚合专用构建器导出（兼容 from engines_builders import *）。"""
+
+from engines_builders_batch9 import (
+    _build_who_don_engine,
+    _build_who_gho_engine,
+    _build_pubmed_engine,
+    _build_core_engine,
+    _build_gdacs_engine,
+    _build_obis_engine,
+    _build_worms_engine,
+    _build_energy_charts_engine,
+    _build_jolpica_engine,
+    _build_openf1_engine,
+    _build_openligadb_engine,
+    _build_artic_engine,
+    _build_cleveland_engine,
+    _build_tvmaze_engine,
+    _build_jikan_engine,
+    _build_deezer_engine,
+    _build_listenbrainz_engine,
+    _build_egov_law_engine,
+    _build_k10plus_engine,
+    _build_ror_engine,
+    _build_soilgrids_engine,
+    _build_noaa_swpc_engine,
+    _build_satnogs_engine,
+    _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,
+    _build_wechat_sogou_engine,
+    _build_hackernews_engine,
+    _build_stackoverflow_engine,
+    _build_google_scholar_engine,
+    _build_deps_dev_engine,
+    _build_endoflife_engine,
+    _build_v2ex_engine,
+    _build_github_engine,
+    _build_tineye_engine,
+    _build_bing_rss_engine,
+)
+from engines_builders_cn import (
+    _build_em_miaoxiang_engine,
+    _build_cninfo_engine,
+    _build_sina_quote_engine,
+    _build_tencent_quote_engine,
+    _build_em_flow_engine,
+    _build_ths_hot_engine,
+    _build_cls_telegraph_engine,
+    _build_em_global_news_engine,
+    _build_eastmoney_engine,
+    _build_itotii_engine,
+    _build_baidu_hot_engine,
+    _build_toutiao_hot_engine,
+    _build_bilibili_hot_engine,
+    _build_zhihu_global_engine,
+    _build_zhihu_user_engine,
+    _build_bocha_engine,
+    _build_bocha_ai_engine,
+    _build_std_samr_engine,
+    _build_openstd_engine,
+    _build_bangumi_engine,
+    _build_douban_movie_engine,
+    _build_zdic_engine,
+    _build_iplant_engine,
+    _build_people_daily_engine,
+    _build_flk_law_engine,
+    _build_wikisource_engine,
+    _build_weibo_hot_engine,
+    _build_douyin_hot_engine,
+    _build_csdn_engine,
+    _build_wallstreetcn_engine,
+    _build_weather_cn_engine,
+)
+from engines_builders_batch12 import (
+    _build_so_engine,
+    _build_shenma_engine,
+)
+
+from engines_builders_batch13 import (
+    _build_yahoo_finance_engine,
+    _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,
+    _build_douban_book_engine,
+    _build_pubchem_engine,
+    _build_gbif_engine,
+    _build_rfc_editor_engine,
+    _build_uniprot_engine,
+    _build_biorxiv_engine,
+    _build_un_comtrade_engine,
+    _build_rcsb_pdb_engine,
+    _build_courtlistener_engine,
+    _build_gutenberg_engine,
+    _build_wayback_cdx_engine,
+    _build_usgs_engine,
+    _build_nasa_cmr_engine,
+    _build_free_dictionary_engine,
+    _build_baidu_baike_engine,
+    _build_pypi_engine,
+    _build_clinicaltrials_engine,
+    _build_openfda_engine,
+    _build_juejin_engine,
+    _build_models_dev_engine,
+    _build_finviz_engine,
+    _build_seeking_alpha_engine,
+    _build_qweather_engine,
+    _build_wenshu_engine,
+    _build_jin10_engine,
+    _build_octen_engine,
+    _build_imdb_engine,
+    _build_thesportsdb_engine,
+    _build_itunes_engine,
+    _build_opencorporates_engine,
+    _build_google_patents_engine,
+    _build_marginalia_engine,
+    _build_wiby_engine,
+)
+from engines_builders_data_macro import (
+    _build_fred_engine,
+    _build_fx_rate_engine,
+    _build_worldbank_engine,
+    _build_nbs_stats_engine,
+    _build_eurostat_engine,
+)
+from engines_builders_search import (
+    _build_parallel_engine,
+    _build_parallel_free_engine,
+    _build_seltz_engine,
+    _build_you_engine,
+    _build_qwant_engine,
+    _build_ecosia_engine,
+)
+from engines_builders_intl import (
+    _build_cnii_engine,
+    _build_ndl_engine,
+    _build_kor_law_engine,
+    _build_hatena_bookmark_engine,
+    _build_dnb_engine,
+    _build_doaj_engine,
+    _build_europeana_engine,
+    _build_hal_engine,
+    _build_eu_opendata_engine,
+    _build_open_meteo_engine,
+    _build_twitter_syndication_engine,
+    _build_searchmysite_engine,
+    _build_lieu_engine,
+    _build_opensky_engine,
+    _build_electricity_maps_engine,
+    _build_usda_engine,
+    _build_tatoeba_engine,
+    _build_figshare_engine,
+    _build_tencent_kline_engine,
+    _build_qq_music_engine,
+    _build_google_news_engine,
+    _build_met_museum_engine,
+)
+from engines_builders_feeds import (
+    _build_rss_feed_engine,
+)
+
+__all__ = [
+    "_build_em_miaoxiang_engine",
+    "_build_cninfo_engine",
+    "_build_sina_quote_engine",
+    "_build_tencent_quote_engine",
+    "_build_em_flow_engine",
+    "_build_exa_engine",
+    "_build_wechat_sogou_engine",
+    "_build_hackernews_engine",
+    "_build_stackoverflow_engine",
+    "_build_std_samr_engine",
+    "_build_openstd_engine",
+    "_build_bangumi_engine",
+    "_build_douban_movie_engine",
+    "_build_zdic_engine",
+    "_build_iplant_engine",
+    "_build_people_daily_engine",
+    "_build_flk_law_engine",
+    "_build_wikisource_engine",
+    "_build_weibo_hot_engine",
+    "_build_douyin_hot_engine",
+    "_build_csdn_engine",
+    "_build_wallstreetcn_engine",
+    "_build_weather_cn_engine",
+    "_build_google_news_engine",
+    "_build_met_museum_engine",
+    "_build_google_scholar_engine",
+    "_build_v2ex_engine",
+    "_build_github_engine",
+    "_build_ths_hot_engine",
+    "_build_cls_telegraph_engine",
+    "_build_em_global_news_engine",
+    "_build_eastmoney_engine",
+    "_build_itotii_engine",
+    "_build_baidu_hot_engine",
+    "_build_toutiao_hot_engine",
+    "_build_bilibili_hot_engine",
+    "_build_open_library_engine",
+    "_build_weread_engine",
+    "_build_douban_book_engine",
+    "_build_fred_engine",
+    "_build_fx_rate_engine",
+    "_build_worldbank_engine",
+    "_build_nbs_stats_engine",
+    "_build_pubchem_engine",
+    "_build_eurostat_engine",
+    "_build_gbif_engine",
+    "_build_rfc_editor_engine",
+    "_build_uniprot_engine",
+    "_build_rcsb_pdb_engine",
+    "_build_courtlistener_engine",
+    "_build_gutenberg_engine",
+    "_build_wayback_cdx_engine",
+    "_build_usgs_engine",
+    "_build_nasa_cmr_engine",
+    "_build_free_dictionary_engine",
+    "_build_baidu_baike_engine",
+    "_build_pypi_engine",
+    "_build_clinicaltrials_engine",
+    "_build_openfda_engine",
+    "_build_juejin_engine",
+    "_build_models_dev_engine",
+    "_build_finviz_engine",
+    "_build_yahoo_finance_engine",
+    "_build_sec_companyfacts_engine",
+    "_build_frankfurter_engine",
+    "_build_seeking_alpha_engine",
+    "_build_qweather_engine",
+    "_build_wenshu_engine",
+    "_build_jin10_engine",
+    "_build_octen_engine",
+    "_build_imdb_engine",
+    "_build_thesportsdb_engine",
+    "_build_itunes_engine",
+    "_build_opencorporates_engine",
+    "_build_google_patents_engine",
+    "_build_marginalia_engine",
+    "_build_wiby_engine",
+    "_build_cnii_engine",
+    "_build_ndl_engine",
+    "_build_kor_law_engine",
+    "_build_hatena_bookmark_engine",
+    "_build_dnb_engine",
+    "_build_doaj_engine",
+    "_build_europeana_engine",
+    "_build_hal_engine",
+    "_build_eu_opendata_engine",
+    "_build_open_meteo_engine",
+    "_build_twitter_syndication_engine",
+    "_build_searchmysite_engine",
+    "_build_searchmysite_engine",
+    "_build_lieu_engine",
+    "_build_opensky_engine",
+    "_build_electricity_maps_engine",
+    "_build_usda_engine",
+    "_build_tatoeba_engine",
+    "_build_figshare_engine",
+    "_build_tencent_kline_engine",
+    "_build_qq_music_engine",
+    "_build_parallel_engine",
+    "_build_parallel_free_engine",
+    "_build_seltz_engine",
+    "_build_you_engine",
+    "_build_who_don_engine",
+    "_build_who_gho_engine",
+    "_build_pubmed_engine",
+    "_build_core_engine",
+    "_build_gdacs_engine",
+    "_build_obis_engine",
+    "_build_worms_engine",
+    "_build_energy_charts_engine",
+    "_build_jolpica_engine",
+    "_build_openf1_engine",
+    "_build_openligadb_engine",
+    "_build_artic_engine",
+    "_build_cleveland_engine",
+    "_build_tvmaze_engine",
+    "_build_jikan_engine",
+    "_build_deezer_engine",
+    "_build_listenbrainz_engine",
+    "_build_egov_law_engine",
+    "_build_k10plus_engine",
+    "_build_ror_engine",
+    "_build_soilgrids_engine",
+    "_build_noaa_swpc_engine",
+    "_build_satnogs_engine",
+    "_build_tle_mirror_engine",
+    "_build_nhtsa_vpic_engine",
+    "_build_rss_feed_engine",
+]
+

package/scripts/engines_builders_batch10.py

@@ -0,0 +1,204 @@
+#!/usr/bin/env python3
+"""批次十构建器：zhihu_global 补强。
+
+为什么不在 engines_builders_cn.py 里加（任务原指定位置）：该文件被
+test_module_size_gate.py 祖父清单冻结在 2319 行（当前恰好 2319，只能减不能增），
+且 tests/ 门禁只放行新建测试文件——门禁自身文档写明「想加功能，正解是拆模块，
+不是把数字往上调」，故按 batch9 命名先例落新文件（新增文件天然合规）。
+
+zhihu_global 说明：cn 里的旧实现与本文件同名实现并存，engines.py 注册表已
+指向本文件版本（候选池取满 + 错误文案行动提示两处补强）；cn 旧版仅在
+engines_builders 聚合层保留转出，属被取代代码。
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+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
+
+from engines_base import (
+    http_open,
+    rank_score,
+    safe_search,
+)
+from engines_builders_cn import _parse_site_filter
+
+
+class _LazyLogger:
+    """延迟创建 logger，避免 import logging 的重量级 import 链（traceback→dataclasses→inspect）。"""
+    _logger = None
+
+    def __getattr__(self, name: str):
+        if _LazyLogger._logger is None:
+            import logging
+            _LazyLogger._logger = logging.getLogger("unified_search.engines")
+            if not _LazyLogger._logger.handlers:
+                _LazyLogger._logger.setLevel(logging.WARNING)
+                _LazyLogger._logger.addHandler(logging.StreamHandler(sys.stderr))
+        return getattr(_LazyLogger._logger, name)
+
+
+logger = _LazyLogger()
+
+
+# ── zhihu_global 补强版（取代 engines_builders_cn 同名实现）───────────────────
+
+# 端点 Count 上限：官方 global_search 上限 20（cn 旧版 min(n, 20) 同源口径）
+_ZHIHU_COUNT_MAX = 20
+
+# 非成功响应 → 可行动提示。时钟偏差类按 Message 文案识别（错误码表未公开，
+# 不猜码值）：签名带 X-Request-Timestamp，本机时钟漂移会让服务端判签名过期，
+# 现象是「密钥没错却全挂」——提示必须指向校时，防止用户误判 key 失效反复换 key
+_ZHIHU_CLOCK_HINT_RE = re.compile(r"timestamp|时间戳|签名|时钟|clock", re.I)
+_ZHIHU_CLOCK_HINT = "本机时钟可能偏差导致签名过期：先校准系统时间再重试，不必反复换密钥"
+
+
+def _zhihu_error_item(code: Any, message: Any) -> dict[str, Any]:
+    """非成功响应的 error item：保留原始 code/message，时钟类追加行动提示。"""
+    text = f"zhihu_global Code={code} {str(message or '')[:100]}"
+    if _ZHIHU_CLOCK_HINT_RE.search(str(message or "")):
+        text = f"{text}；hint: {_ZHIHU_CLOCK_HINT}"
+    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）。
+
+    在 cn 旧版语义之上的两处微机制补强（2026-09-26）：
+      1. 候选池取满再截断：Filter host== 是服务端在候选池上后筛，只取 n 条
+         会把「过滤后恰好命中」的候选一并筛掉，空结果会被模型读成「知乎没有
+         相关内容」；带站点限定或时间下限（since）时取满端点 Count 上限，
+         客户端再截断到 n。since 的时间 Filter 语法官方未文档化，先只承担
+         「取满候选池」语义。
+      2. 错误码 → 行动提示：时钟偏差类错误给「校时」提示而非裸错误。
+    查询语法与 cn 版一致：site:/host: → Filter host==，普通查询 SearchDB=all。
+    """
+    timeout = spec.get("timeout", 10)
+
+    @safe_search
+    def _engine(query: str, n: int = 5, _timeout: float | None = None, **kwargs) -> list[dict[str, Any]]:
+        to = _timeout or timeout
+        secret = get_env(["ARGO_ZHIHU_ACCESS_SECRET", "ZHIHU_ACCESS_SECRET"])
+        if not secret:
+            return []
+
+        # 解析 site:/host: 站点限定语法 → Filter: host=="..."（实现单点在 cn）
+        filter_expr, search_query = _parse_site_filter(query)
+        # 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": db,
+        }
+        if filter_expr:
+            params["Filter"] = filter_expr
+        url = "https://developer.zhihu.com/api/v1/content/global_search?" + urllib.parse.urlencode(params)
+        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(urllib.request.Request(url, headers=headers), timeout=to, engine=spec.get("_name", "")) as resp:
+                data = json.loads(resp.read().decode("utf-8", "replace"))
+        except urllib.error.HTTPError as e:
+            # 401/403 等必须暴露为 error item 而非静默空——调用侧把
+            # 「没配置」「鉴权失败」「没结果」区分开才可行动
+            return [{"error": f"zhihu_global API HTTP {e.code}", "source": "zhihu_global"}]
+        except Exception as e:
+            logger.warning(f"zhihu_global 失败: {e}")
+            return [{"error": f"zhihu_global {type(e).__name__}: {e}", "source": "zhihu_global"}]
+        if data.get("Code") not in (0, None):
+            # 30001=频率限制 30002=配额限制，显式暴露供配额状态机归类
+            logger.warning(f"zhihu_global 返回码异常: {data.get('Code')} {data.get('Message')}")
+            return [_zhihu_error_item(data.get("Code"), data.get("Message"))]
+        items = (data.get("Data") or {}).get("Items") or []
+        results = []
+        for _rk3, item in enumerate(items[:n]):
+            if not isinstance(item, dict):
+                continue
+            title = (item.get("Title") or "").strip()
+            # API 标题统一带「 - 知乎」尾巴：截断前剥掉（先剥再切，尾巴不占正文）
+            if title.endswith(" - 知乎"):
+                title = title[: -len(" - 知乎")].rstrip()
+            url_ = item.get("Url") or ""
+            snippet = item.get("ContentText") or ""
+            # 去 <em> 高亮标签
+            snippet = re.sub(r"<[^>]+>", "", snippet).strip()
+            if not title and not url_:
+                continue
+            # 结构化信号：权威等级 / 互动 / 时效
+            social_meta = {
+                "author": item.get("AuthorName") or "",
+                "content_type": item.get("ContentType") or "",
+                "vote_up": item.get("VoteUpCount") or 0,
+                "comment_count": item.get("CommentCount") or 0,
+                "authority_level": item.get("AuthorityLevel") or "",
+                "edit_time": item.get("EditTime") or 0,
+            }
+            results.append({
+                "title": title[:200],
+                "url": url_,
+                "snippet": snippet[:300],
+                "source": "zhihu_global",
+                "score": rank_score(0.7, _rk3),
+                "authority_level": social_meta["authority_level"],
+                "social_meta": social_meta,
+            })
+        return results
+    return _engine

package/scripts/engines_builders_batch11.py

@@ -0,0 +1,174 @@
+#!/usr/bin/env python3
+"""批次十一构建器：图片检索能力的两个补强源（2026-09-26）。
+
+本批只收图源，目标是修「搜到图源却拿不到图」这一类缺陷的通用面：
+
+  wikimedia_commons  Wikimedia Commons（免 key，通用图库，带 CC 许可与宽高）
+
+为什么单独建一个 builder 而不是声明式 spec：Commons 的 `query.pages` 是
+**以 pageid 为键的字典**，不是数组——`_extract_items` 遇到 dict 会把它当成
+「单条结果」包成 `[{pageid: {...}}]`，声明式 output_map 取不到 title/url
+（实测返回空列表）。这属于查询形状不兼容，只能用代码展开。
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any
+
+from engines_base import (
+    finalize_image_fields,
+    rank_score,
+    safe_search,
+    http_open,
+)
+
+
+class _LazyLogger:
+    """延迟创建 logger，避免 import logging 的重量级 import 链（traceback→dataclasses→inspect）。"""
+    _logger = None
+
+    def __getattr__(self, name: str):
+        if _LazyLogger._logger is None:
+            import logging
+            _LazyLogger._logger = logging.getLogger("unified_search.engines")
+            if not _LazyLogger._logger.handlers:
+                _LazyLogger._logger.setLevel(logging.WARNING)
+                _LazyLogger._logger.addHandler(logging.StreamHandler(sys.stderr))
+        return getattr(_LazyLogger._logger, name)
+
+
+logger = _LazyLogger()
+
+_UA = "argo-search/2.9 (+batch11; wikimedia_commons)"
+_API = "https://commons.wikimedia.org/w/api.php"
+
+# Commons 的 extmetadata 是一层「字段 → {value, source, hidden}」的包装，
+# 取值要过两道：raw["LicenseShortName"]["value"]。漏掉里层取键会拿到 dict
+# 本身，_coerce_field 会把它丢成空串——表现为「许可字段时有时无」。
+#
+# 许可取两个字段：`LicenseShortName` 是给人看的（`CC BY-SA 4.0`），
+# `License` 是机器码（`cc-by-sa-4.0`）。两者都要——实测有约 8% 的文件
+# shortname 只写「Attribution」（Commons 在无法确定具体协议时的泛称），
+# 而机器码为空；反过来也有机器码齐全而 shortname 缺失的。任一可用即可判定。
+_META_FIELDS = ("LicenseShortName", "License", "Artist", "ImageDescription",
+                "LicenseUrl")
+
+
+def _meta(ext: dict[str, Any], key: str) -> str:
+    """取 extmetadata 里的纯文本值（内层是 {value, source, hidden}）。"""
+    node = ext.get(key)
+    if isinstance(node, dict):
+        node = node.get("value")
+    if node is None:
+        return ""
+    text = str(node)
+    # 上游描述字段带 HTML（<a href=...>、<span>），剥标签留文本——
+    # 交付出去的 snippet 里带标签既占字数又不可读。
+    if "<" in text and ">" in text:
+        import re
+        text = re.sub(r"<[^>]+>", " ", text)
+        text = re.sub(r"\s+", " ", text)
+    return text.strip()
+
+
+def _build_wikimedia_commons_engine(spec: dict[str, Any]) -> Any:
+    """Wikimedia Commons 通用图库（免 key、CC 素材、字段齐全）。"""
+    timeout = spec.get("timeout", 20)
+    eng = spec.get("_name", "wikimedia_commons")
+
+    @safe_search
+    def _engine(query: str, n: int = 5, _timeout: float | None = None, **kwargs) -> list[dict[str, Any]]:
+        to = _timeout or timeout
+        q = (query or "").strip()
+        if not q:
+            return []
+        # filetype:bitmap 排除 PDF/DjVu/SVG 等非位图文件——不筛的话「猫」这类
+        # 查询会混进大量古籍扫描 PDF，它们没有可直接展示的位图。
+        params = {
+            "action": "query",
+            "generator": "search",
+            "gsrsearch": f"filetype:bitmap {q}",
+            "gsrnamespace": "6",          # namespace 6 = File
+            "gsrlimit": str(max(1, min(int(n), 50))),
+            "prop": "imageinfo",
+            "iiprop": "url|size|extmetadata",
+            "iiurlwidth": "480",          # 缩略图宽度，直接可嵌入
+            "format": "json",
+            "formatversion": "2",
+        }
+        url = f"{_API}?{urllib.parse.urlencode(params)}"
+        req = urllib.request.Request(url, headers={"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 (urllib.error.URLError, OSError, ValueError) as e:
+            logger.warning(f"Wikimedia Commons 失败: {e}")
+            return []
+
+        pages: Any = ((data or {}).get("query") or {}).get("pages")
+        # formatversion=2 返回 list，=1 返回 dict。两种都收——上游改默认值
+        # 是常事，只认一种会让引擎在版本切换时静默归零。
+        if isinstance(pages, dict):
+            pages = list(pages.values())
+        if not isinstance(pages, list):
+            return []
+
+        results: list[dict[str, Any]] = []
+        for rk, page in enumerate(pages[: max(1, int(n))]):
+            if not isinstance(page, dict):
+                continue
+            info = page.get("imageinfo")
+            if isinstance(info, list):
+                info = info[0] if info else None
+            if not isinstance(info, dict):
+                continue
+            title = str(page.get("title") or "").strip()
+            # File: 前缀是 MediaWiki 的命名空间标记，不是文件名的一部分
+            title = title[5:].strip() if title.startswith("File:") else title
+            img = str(info.get("url") or "").strip()
+            if not title or not img:
+                continue
+
+            ext = info.get("extmetadata")
+            ext = ext if isinstance(ext, dict) else {}
+            license_label = _meta(ext, "LicenseShortName")
+            # shortname 是泛称（Commons 对无法确定具体协议的件写「Attribution」）
+            # 或缺失时，退到机器码 `cc-by-sa-4.0`——它虽然不好读，但能被
+            # finalize_image_fields 归一成标准标注，比一个认不出的泛称有用。
+            if not license_label or license_label.strip().lower() in (
+                    "attribution", "copyrighted", "unknown"):
+                license_label = _meta(ext, "License") or license_label
+            artist = _meta(ext, "Artist")
+            desc = _meta(ext, "ImageDescription")
+            page_url = str(page.get("descriptionurl") or "").strip()
+            if not page_url:
+                page_url = f"https://commons.wikimedia.org/wiki/File:{urllib.parse.quote(title.replace(' ', '_'))}"
+
+            snippet_bits = [b for b in (artist and f"作者 {artist}", desc) if b]
+            snippet = " · ".join(snippet_bits) or "Wikimedia Commons 开放素材"
+
+            row: dict[str, Any] = {
+                "title": title[:200],
+                "url": page_url,
+                "snippet": snippet[:300],
+                "source": eng,
+                "score": rank_score(0.85, rk),
+                # 图片直链用 imageinfo.url（原图），thumburl 是缩略图——
+                # 交付时给原图，需要小图的一方自己缩（反过来则拿不到原图）。
+                "image_url": img,
+                "image_license": license_label,
+                "image_license_url": _meta(ext, "LicenseUrl"),
+                "image_width": info.get("width"),
+                "image_height": info.get("height"),
+            }
+            results.append(row)
+        # 尺寸转 int / 许可归一 / 算商用判据——与声明式路径同一个收尾函数，
+        # 保证两类引擎交付的字段契约完全一致。
+        return finalize_image_fields(results, spec.get("image_license") or "")
+
+    return _engine