argo-search 2.9.7 → 2.9.8

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

@@ -413,322 +413,43 @@ def _lang_param(param: str, query: str) -> str:
         return ""
 
 
-# ── HTML 解析 ──────────────────────────────────────────────────────────────────
-
-def _select_with_bs4(soup: Any, selector: str):
-    try:
-        return soup.select(selector)
-    except Exception:
-        return []
-
-
-def _select_first_with_bs4(soup: Any, selector: str) -> Any:
-    items = _select_with_bs4(soup, selector)
-    return items[0] if items else None
-
-
-def _fallback_extract(html: str, engine_name: str, base: str,
-                         default_score: float = 0.45, max_items: int = 8) -> list[dict[str, Any]]:
-    """通用解析保底：选择器 0 命中时，用链接 + 锚文本启发式回退。
-
-    零依赖：只用 BeautifulSoup 已有能力，抽页面内最像「结果卡片」的链接块，
-    避免页面改版导致整引擎 0 结果。命中者 score 保守（0.45 起），不与主映射抢位。
-    """
-    try:
-        from bs4 import BeautifulSoup
-        soup = BeautifulSoup(html, "html.parser")
-    except Exception:
-        return []
-    for sel in ("nav", "header", "footer", "script", "style", "noscript"):
-        try:
-            for tag in soup.select(sel):
-                tag.decompose()
-        except Exception:
-            pass
-    candidates: list[tuple[str, str, str]] = []
-    for a in soup.find_all("a", href=True):
-        try:
-            href = str(a.get("href") or "").strip()
-            title = a.get_text(strip=True)
-        except Exception:
-            continue
-        if not title or len(title) < 6:
-            continue
-        if href.startswith("#") or href.startswith("javascript:"):
-            continue
-        low = href.lower()
-        if any(x in low for x in ("login", "signin", "signup", "cookie", "privacy", "terms")):
-            continue
-        parent = a.parent
-        snippet = ""
-        try:
-            if parent is not None:
-                snippet = parent.get_text(" ", strip=True)[:300]
-                if snippet == title:
-                    gp = parent.parent
-                    snippet = gp.get_text(" ", strip=True)[:300] if gp is not None else ""
-        except Exception:
-            snippet = ""
-        if href.startswith("/"):
-            try:
-                href = urllib.parse.urljoin(base, href)
-            except Exception:
-                pass
-        candidates.append((title[:200], href[:500], snippet))
-        if len(candidates) >= max_items * 3:
-            break
-    seen: set[str] = set()
-    out: list[dict[str, Any]] = []
-    for title, url, snippet in candidates:
-        key = url or title
-        if not key or key in seen:
-            continue
-        seen.add(key)
-        out.append({
-            "title": title,
-            "url": url,
-            "snippet": snippet,
-            "score": round(max(default_score - len(out) * 0.05, 0.1), 3),
-            "source": engine_name,
-            "_fallback": True,
-        })
-        if len(out) >= max_items:
-            break
-    return out
-
-
-def _parse_html(engine_name: str, html: str, spec: dict[str, Any],
-                maps: dict[str, Any]) -> list[dict[str, Any]]:
-    html_maps = maps.get("html", {})
-    mapping = html_maps.get(engine_name, html_maps.get("default", {}))
-    container_sel = mapping.get("container")
-    title_sel = mapping.get("title")
-    url_sel = mapping.get("url")
-    snippet_sel = mapping.get("snippet")
-    url_attr = mapping.get("url_attr", "href")
-    default_score = mapping.get("score", 0.5)
-
-    if not container_sel:
-        return []
-
-    try:
-        from bs4 import BeautifulSoup
-        soup = BeautifulSoup(html, "html.parser")
-        containers = _select_with_bs4(soup, container_sel)
-    except Exception:
-        return []
-
-    results: list[dict[str, Any]] = []
-    base = spec.get("_base", spec.get("url", ""))
-    for idx, item in enumerate(containers):
-        try:
-            title_el = _select_first_with_bs4(item, title_sel) if title_sel else None
-            url_el = _select_first_with_bs4(item, url_sel) if url_sel else None
-            snippet_el = _select_first_with_bs4(item, snippet_sel) if snippet_sel else None
-
-            title = title_el.get_text(strip=True)[:200] if title_el else ""
-            url = ""
-            if url_el and url_el.has_attr(url_attr):
-                url = url_el[url_attr]
-            snippet = snippet_el.get_text(strip=True)[:300] if snippet_el else ""
-
-            if not title and not url:
-                continue
-
-            if url and url.startswith("/"):
-                url = urllib.parse.urljoin(base, url)
-
-            score = max(default_score - idx * 0.05, 0.1)
-            results.append({
-                "title": title,
-                "url": url,
-                "snippet": snippet,
-                "score": round(score, 3),
-                "source": engine_name,
-            })
-        except Exception:
-            continue
-    if not results:
-        try:
-            fb = _fallback_extract(html, engine_name, base, default_score=0.45, max_items=8)
-            if fb:
-                return fb
-        except Exception:
-            pass
-    return results
-
+# ── HTML / XML / JSON 解析（解耦至 parsers.py） ──────────────────────────────
+from parsers import (
+    _fallback_extract,
+    _format_url,
+    _get_path,
+    _parse_html,
+    _parse_json as _raw_parse_json,
+    _parse_xml as _raw_parse_xml,
+    _select_first_with_bs4,
+    _select_with_bs4,
+)
 
-# ── XML / RSS 解析 ─────────────────────────────────────────────────────────────
 
 def _parse_xml(engine_name: str, text: str, maps: dict[str, Any],
                is_rss: bool = False) -> list[dict[str, Any]]:
-    if is_rss:
-        mapping = maps.get("rss", {}).get("default", {})
-    else:
-        mapping = maps.get("xml", {}).get(engine_name, {})
-
-    entry_path = mapping.get("entry_path") or mapping.get("item_path", ".//item")
-    title_tag = mapping.get("title", "title")
-    url_tag = mapping.get("url", "link")
-    snippet_tag = mapping.get("snippet", "description")
-    pub_tag = mapping.get("published_at", "pubDate")
-    namespaces = mapping.get("namespaces", {})
-
-    def _find_tag(entry: Any, tag: str) -> str:
-        """按标签取值，兼容 atom:xxx 命名空间前缀。"""
-        if tag.startswith("atom:"):
-            tag_name = tag.split(":")[1]
-            ns = namespaces.get("atom")
-            node = entry.find(f"{{{ns}}}{tag_name}") if ns else None
-            return (node.text or "").strip() if node is not None else ""
-        node = entry.findtext(tag, default="")
-        return (node or "").strip()
-
-    results: list[dict[str, Any]] = []
-    try:
-        root = ET.fromstring(text)
-    except ET.ParseError:
-        return results
-
-    if entry_path.startswith(".//{"):
-        entries = root.findall(entry_path, namespaces)
-    else:
-        entries = root.findall(entry_path)
-
-    for idx, entry in enumerate(entries):
-        try:
-            title = _find_tag(entry, title_tag)
-            url = _find_tag(entry, url_tag)
-            snippet = _find_tag(entry, snippet_tag)
-            raw_pub = _find_tag(entry, pub_tag) if pub_tag else ""
-
-            title = re.sub(r"\s+", " ", title)[:200]
-            snippet = re.sub(r"\s+", " ", snippet)[:300]
-            score = max(0.7 - idx * 0.05, 0.1)
-            results.append({
-                "title": title,
-                "url": url,
-                "snippet": snippet,
-                "score": round(score, 3),
-                "source": engine_name,
-                "published_at": _normalize_date(raw_pub),
-            })
-        except Exception:
-            continue
-    return results
-
-
-# ── JSON 解析 ──────────────────────────────────────────────────────────────────
-
-def _get_path(data: Any, path: str) -> Any:
-    if path == ".":
-        return data
-    obj = data
-    for part in path.split("."):
-        if part.isdigit() and isinstance(obj, (list, tuple)):
-            idx = int(part)
-            obj = obj[idx] if idx < len(obj) else None
-        elif isinstance(obj, dict):
-            obj = obj.get(part)
-        else:
-            return None
-    return obj
-
-
-def _format_url(template: str | None, item: dict[str, Any], default: str = "") -> str:
-    if not template:
-        return default
-    try:
-        return template.format(**item)
-    except (KeyError, IndexError):
-        return default
+    return _raw_parse_xml(engine_name, text, maps, is_rss=is_rss, normalize_date_fn=_normalize_date)
 
 
 def _parse_json(engine_name: str, text: str, maps: dict[str, Any]) -> list[dict[str, Any]]:
-    mapping = maps.get("json", {}).get(engine_name, {})
-    items_path = mapping.get("items", ".")
-    title_key = mapping.get("title")
-    url_key = mapping.get("url")
-    snippet_key = mapping.get("snippet")
-    url_template = mapping.get("url_template")
-    published_key = mapping.get("published_at")
-
-    results: list[dict[str, Any]] = []
-    try:
-        data = json.loads(text)
-    except json.JSONDecodeError:
-        return results
-
-    items = _get_path(data, items_path)
-    if not isinstance(items, list):
-        return results
-
-    for idx, item in enumerate(items):
-        if not isinstance(item, dict):
-            if engine_name == "local_pubmed" and isinstance(item, str):
-                item = {"pmid": item}
-            else:
-                continue
-
-        title = url = snippet = ""
-        if title_key:
-            raw = _get_path(item, title_key)
-            if isinstance(raw, list):
-                raw = raw[0] if raw else ""
-            title = str(raw or "")[:200]
-        if url_key:
-            raw = _get_path(item, url_key)
-            url = str(raw or "")[:500]
-        elif url_template:
-            url = _format_url(url_template, item)
-        if snippet_key:
-            raw = _get_path(item, snippet_key)
-            snippet = str(raw or "")[:300]
-        published_at = _normalize_date(_get_path(item, published_key)) if published_key else None
-
-        title = re.sub(r"<[^>]+>", " ", title)
-        title = re.sub(r"\s+", " ", title).strip()
-        snippet = re.sub(r"<[^>]+>", " ", snippet)
-        snippet = re.sub(r"\s+", " ", snippet).strip()
-
-        score = max(0.7 - idx * 0.05, 0.1)
-        results.append({
-            "title": title,
-            "url": url,
-            "snippet": snippet,
-            "score": round(score, 3),
-            "source": engine_name,
-            "published_at": published_at,
-        })
-    return results
-
-
-# ── 单个引擎执行 ─────────────────────────────────────────────────────────────────
-
-# ddgs 各子命令支持的 timelimit 取值：videos 仅 d/w/m（无 y）。
-# 传 y 会直接 crash（Invalid value for '-t'），必须按下推子命令过滤。
-_DDGS_TIMELIMITS: dict[str, set[str]] = {
-    "text": {"d", "w", "m", "y"},
-    "news": {"d", "w", "m", "y"},
-    "images": {"d", "w", "m", "y"},
-    "videos": {"d", "w", "m"},
-}
-
-# ddgs 失败信号标记：9.14.4 起这些错误在 rc=0 时打到 stdout（吞错根源，
-# 实测 yahoo 间歇 "No results"、bing TLS "ConnectError" 均 rc=0），
-# 必须在任何解析前统一识别；命中后重试 1 次（后端间歇失败实测 20-50%）。
-_CLI_ERROR_MARKERS: tuple[str, ...] = (
-    "DDGSException", "No results", "ConnectError", "ConnectTimeout",
-    "ReadTimeout", "Timeout", "backends do not exist",
+    return _raw_parse_json(engine_name, text, maps, normalize_date_fn=_normalize_date)
+
+
+# ── CLI 工具引擎调度（解耦至 cli_runner.py） ────────────────────────────────────
+from cli_runner import (
+    _CLI_AVAIL_CACHE,
+    _CLI_AVAIL_TTL,
+    _CLI_ERROR_MARKERS,
+    _CLI_RETRIES,
+    _DDGS_TIMELIMITS,
+    _RETRY_FAST_S,
+    _attempt_loop,
+    _check_cli_available,
+    _parse_cli_json,
+    _parse_cli_output,
+    _run_cli_engine as _raw_run_cli_engine,
+    _since_to_ddgs_timelimit,
 )
-_CLI_RETRIES = 1
-
-# 重试的「快失败」判据（秒，2026-09-29 G 修订）：只有**快**结束的失败才值得
-# 重试——传输层瞬时错误（DecodeError/ConnectError）在连接阶段就暴露（实测
-# <2.5s）；跑了数秒才返回的 "No results" 意味着后端真的做完了检索，是真空
-# 或慢性故障，重试大概率重演。实测尾部形态：第一次 4.4s 慢空 → 重试 →
-# 第二次挂满 8s 超时 = 12.1s；本判据把这类尾部砍回单次（~4s）。
-_RETRY_FAST_S = 2.5
 
 # 第二引擎共识宽限（秒，2026-10-06）：够数早停从「死等 ≥2 引擎」改为
 # 「先等 1s 收共识，宽限到点放行」。语义与实测依据见 search_engines 内
@@ -737,373 +458,9 @@ _CONSENSUS_GRACE_S = 1.0
 _CONSENSUS_POLL_S = 0.25
 
 
-def _since_to_ddgs_timelimit(since: str | None, until: str | None) -> str | None:
-    """Convert since/until to ddgs timelimit argument.
-    
-    ddgs supports: d (day), w (week), m (month), y (year)
-    """
-    if not since:
-        return None
-    
-    # Parse relative time like 7d, 1m, 3w
-    match = re.match(r'^(\d+)([dwmy])$', since.lower())
-    if match:
-        num, unit = match.groups()
-        num = int(num)
-        # Map to ddgs timelimit
-        if unit == 'y':
-            return 'y'
-        elif unit == 'm':
-            return 'm'
-        elif unit == 'w':
-            return 'w'
-        elif unit == 'd':
-            if num >= 365:
-                return 'y'
-            elif num >= 30:
-                return 'm'
-            elif num >= 7:
-                return 'w'
-            else:
-                return 'd'
-    
-    return None
-
-
 def _run_cli_engine(spec: dict[str, Any], query: str, n: int, timeout: float,
-                     since: str | None = None, until: str | None = None) -> tuple[list[dict[str, Any]], str]:
-    """Run a CLI-based search engine (e.g., ddgs).
-    
-    Args:
-        since: Time window start (7d, 1m, etc.)
-        until: Time window end
-    """
-    cli_cmd = spec.get("cli_command", "")
-    cli_args_template = spec.get("cli_args", [])
-    key = spec.get("key", cli_cmd)
-    
-    if not cli_cmd:
-        return [], "CLI engine missing cli_command"
-    
-    # Check if CLI is available
-    if not _check_cli_available(cli_cmd):
-        return [], f"{cli_cmd} not available"
-    
-    # Add time limit if since/until provided
-    time_limit = _since_to_ddgs_timelimit(since, until)
-    
-    # Build command with query and result count substitution
-    cli_args = []
-    for arg in cli_args_template:
-        formatted = arg.format(query=query, n=n)
-        cli_args.append(formatted)
-    
-    # Insert time limit if supported and needed
-    # 按子命令限定取值：videos 不支持 y，直接追加 -t y 会让 ddgs 报错退出。
-    if time_limit and "-t" not in cli_args and "--timelimit" not in cli_args:
-        sub = next((a for a in cli_args_template if not str(a).startswith("-")), None)
-        allowed = _DDGS_TIMELIMITS.get(str(sub), _DDGS_TIMELIMITS["text"])
-        if time_limit in allowed:
-            cli_args.extend(["-t", time_limit])
-    
-    # 区域参数（ddgs -r region）：按查询主语言映射（zh→cn-zh 等），
-    # 引擎声明 use_lang_region: true 时启用；显式 -r 不覆盖。
-    if spec.get("use_lang_region") and not any(a in ("-r", "--region") for a in cli_args):
-        region = _lang_param("region", query)
-        if region:
-            cli_args.extend(["-r", region])
-    
-    # 结构化 JSON 输出：ddgs -o <file> 把结果写入文件（stdout 无输出），
-    # 避免脆弱的文本行解析；失败回退文本解析。引擎声明 output_format: json。
-    output_format = spec.get("output_format", "")
-    tmp_path: str | None = None
-    if output_format == "json" and not any(
-        a in ("-o", "--output") for a in cli_args
-    ):
-        import tempfile
-        fd, tmp_path = tempfile.mkstemp(suffix=".json", prefix="ddgs_")
-        os.close(fd)
-        _TMP_FILES.add(tmp_path)  # 兜底登记：弃置线程对应的进程若直接退出也可清理
-        cli_args.extend(["-o", tmp_path])
-    
-    cmd = [cli_cmd] + cli_args
-
-    # 失败重试：ddgs 各 backend 间歇性失败（yahoo "No results"、bing TLS
-    # ConnectError 均实测存在），且 9.14.4 起这些错误在 rc=0 时打到 stdout，
-    # 输出文件为 0 字节。逐次尝试：识别错误信号 → 重试 1 次 → 明确错误。
-    last_err = ""
-    try:
-        return _attempt_loop(cmd, cli_cmd, key, tmp_path, timeout)
-    finally:
-        # 函数级兜底：覆盖 helper 内全部早退路径（timeout/FileNotFound/异常/
-        # 正常返回），保证临时文件与登记表条目都被清（2026-10-12 审查：
-        # 早退分支此前直接 return，daemon 常驻期间在 /tmp 累积输出文件）。
-        if tmp_path is not None:
-            try:
-                os.unlink(tmp_path)
-            except OSError:
-                pass
-            _TMP_FILES.discard(tmp_path)
-
-
-def _attempt_loop(cmd: list[str], cli_cmd: str, key: str,
-                  tmp_path: str | None, timeout: float):
-    """CLI 引擎的单引擎尝试循环（从 _run_cli_engine 提取，便于统一收尾）。
-
-    返回 (results, err)；临时文件的清理由调用方 finally 统一负责。
-    """
-    last_err = ""
-    for attempt in range(_CLI_RETRIES + 1):
-        t_attempt = time.monotonic()
-        try:
-            result = subprocess.run(
-                cmd,
-                capture_output=True,
-                text=True,
-                encoding="utf-8",  # Windows GBK locale 下 UTF-8 输出会解码崩
-                errors="replace",
-                timeout=timeout,
-            )
-        except subprocess.TimeoutExpired:
-            # 慢失败不重试：后端 timeout 秒都没回来，0.3s 后再来一次大概率
-            # 还是 timeout（网络/服务端慢是相关信号），重试只把最坏墙钟翻倍、
-            # 结果仍为空（实测空结果查询单引擎 15.8s = 8s×2+0.3s）。快失败
-            # （DecodeError/No results，2-3s 内返回）才是真间歇，下方重试。
-            return [], f"{cli_cmd} timed out after {timeout}s"
-        except FileNotFoundError:
-            return [], f"{cli_cmd} not found"
-        except Exception as e:
-            return [], f"{cli_cmd} error: {e}"
-
-        combined_output = result.stdout + result.stderr
-
-        # 结构化 JSON 优先（ddgs -o json 输出到临时文件）：有结果直接返回，
-        # stdout 的 warning（如 bing "backends do not exist" 但结果正常）不干扰。
-        if tmp_path is not None:
-            json_ok = False
-            try:
-                with open(tmp_path, encoding="utf-8") as f:
-                    data = json.load(f)
-                parsed = _parse_cli_json(data, key)
-                if parsed:
-                    return parsed, ""
-                json_ok = True  # 合法空列表：真无结果，不重试
-            except (OSError, ValueError):
-                json_ok = False
-            finally:
-                # 逐次 unlink：防重试读到上一轮的陈旧输出文件。登记表条目
-                # 不在这里摘——重试第二次会把同一路径重新写出来，若那次
-                # 超时/异常，登记表仍持有路径，atexit 与调用方 finally 都能
-                # 兜住（2026-10-12 审查：提前 discard 会让它失去双重兜底）。
-                try:
-                    os.unlink(tmp_path)
-                except OSError:
-                    pass
-            if json_ok:
-                return [], ""
-        else:
-            json_ok = False
-
-        # 无 JSON 结果：识别错误信号（无论 rc）→ 重试。
-        # 9.14.4 常见 rc=0 + stdout 错误 + 空输出文件，
-        # 旧逻辑只在 rc!=0 分支检查，导致静默吞错返回 0 结果。
-        err_marker = next(
-            (m for m in _CLI_ERROR_MARKERS if m in combined_output), None
-        )
-        if err_marker:
-            detail = combined_output.strip().replace("\n", " ")[:120]
-            last_err = f"{cli_cmd}: {err_marker}: {detail}"
-            # 快失败判据：慢失败（后端真跑完了检索的慢空/慢性故障）不重试
-            if attempt < _CLI_RETRIES and time.monotonic() - t_attempt <= _RETRY_FAST_S:
-                time.sleep(0.3)
-                continue
-            return [], last_err
-        if result.returncode != 0:
-            last_err = f"{cli_cmd} exit {result.returncode}: {combined_output[:200]}"
-            if attempt < _CLI_RETRIES and time.monotonic() - t_attempt <= _RETRY_FAST_S:
-                time.sleep(0.3)
-                continue
-            return [], last_err
-
-        # 0 字节/解析失败或无 -o 引擎：文本解析保底（handles text/news/images/videos）
-        parsed, parse_err = _parse_cli_output(result.stdout, key)
-        if parsed:
-            return parsed, parse_err
-        last_err = f"{cli_cmd}: empty output"
-        if attempt < _CLI_RETRIES and time.monotonic() - t_attempt <= _RETRY_FAST_S:
-            time.sleep(0.3)
-            continue
-        return [], last_err
-    return [], last_err
-
-
-def _parse_cli_json(data: Any, engine_name: str) -> list[dict[str, Any]]:
-    """解析 ddgs 结构化 JSON 输出（-o json 写入文件）。
-
-    ddgs 各子命令的 JSON item 形态：
-      text:   {title, href, body}
-      news:   {date, title, body, url, image, source}
-      images: {title, image, thumbnail, url, height, width, source}
-      videos: {title, content, duration, provider}
-    统一映射为 argo 结果字段；news 的 date 归一化为 published_at。
-    """
-    if not isinstance(data, list):
-        return []
-    results: list[dict[str, Any]] = []
-    for item in data:
-        if not isinstance(item, dict):
-            continue
-        title = item.get("title", "")
-        url = item.get("href", item.get("url", item.get("link", "")))
-        snippet = item.get("body", item.get("snippet",
-                                            item.get("description", item.get("content", ""))))
-        if not title and not url:
-            continue
-        r: dict[str, Any] = {
-            "title": str(title),
-            "url": str(url),
-            "snippet": str(snippet),
-            "source": engine_name,
-        }
-        for key in ("image", "thumbnail", "source", "duration", "provider",
-                    "height", "width"):
-            if key in item and item[key] not in (None, ""):
-                r[key] = item[key]
-        date = item.get("date")
-        if date:
-            r["published_at"] = str(date)[:64]
-        # 元数据增强：author/publisher/info 拼入 snippet，
-        # 否则这些字段会被通用映射丢弃。
-        meta = " · ".join(
-            str(item[k]) for k in ("author", "publisher", "info")
-            if item.get(k)
-        )
-        if meta:
-            r["snippet"] = (str(snippet) + " · " + meta)[:400] if snippet else meta[:400]
-        results.append(r)
-    return results
-
-
-def _check_cli_available(cmd: str) -> bool:
-    """Check if a CLI command is available（结果缓存 TTL=_CLI_AVAIL_TTL）。
-
-    判据用 `shutil.which`：微秒级、无子进程。旧判据是 `cmd --help` 子进程
-    （ddgs 冷启 ~190ms），而 TTL 缓存只在**同一进程内**有效——CLI 用法下
-    每次 argo 调用都是新进程，等于每次搜索都白付一次 190ms。which 只回答
-    「PATH 上有没有这个可执行文件」，正是可用性判定需要的判据； shim 损坏
-    （能 which 到但跑不动）由后续真实调用暴露，与改动前的失败路径相同。
-    """
-    import shutil
-
-    now = time.time()
-    hit = _CLI_AVAIL_CACHE.get(cmd)
-    if hit is not None and now - hit[0] < _CLI_AVAIL_TTL:
-        return hit[1]
-    ok = shutil.which(cmd) is not None
-    _CLI_AVAIL_CACHE[cmd] = (time.time(), ok)
-    return ok
-
-
-def _parse_cli_output(stdout: str, engine_name: str) -> tuple[list[dict[str, Any]], str]:
-    """Parse output from CLI search tools like ddgs.
-    
-    Handles multiple output formats:
-    - text: title/href/body
-    - news: date/title/body/url/image/source
-    - images: title/image/thumbnail/url/height/width/source
-    - videos: title/content/duration/provider
-    """
-    results = []
-    
-    # Try JSON parse first
-    try:
-        data = json.loads(stdout)
-        if isinstance(data, list):
-            for item in data:
-                result = {
-                    "title": item.get("title", ""),
-                    "url": item.get("href", item.get("url", item.get("link", ""))),
-                    "snippet": item.get("body", item.get("snippet", item.get("description", item.get("content", "")))),
-                    "source": engine_name,
-                }
-                for key in ["date", "image", "thumbnail", "source"]:
-                    if key in item:
-                        result[key] = item[key]
-                results.append(result)
-            return results, ""
-    except json.JSONDecodeError:
-        pass
-    
-    # Parse text format with flexible field detection
-    current_result = {}
-    current_field = None
-    
-    for line in stdout.split("\n"):
-        line_stripped = line.strip()
-        if not line_stripped:
-            continue
-        
-        # Detect numbered entry start: "1.", "2.", etc.
-        # （此前 len<=4 的任意数字行都被当分隔符，正文数字会被误切；
-        #   仅识别「数字+句点」形式的序号）
-        if re.fullmatch(r"\d+\.\s*", line_stripped):
-            if current_result:
-                results.append(current_result)
-                current_result = {}
-                current_field = None
-            continue
-        
-        # Detect field lines with flexible matching
-        field_matched = False
-        for field, target_key in [
-            ("title", "title"),
-            ("href", "url"),
-            ("url", "url"),
-            ("body", "snippet"),
-            ("snippet", "snippet"),
-            ("description", "snippet"),
-            ("content", "snippet"),
-            ("date", "date"),
-            ("image", "image"),
-            ("thumbnail", "thumbnail"),
-            ("source", "source"),
-            ("duration", "duration"),
-            ("provider", "provider"),
-            ("height", "height"),
-            ("width", "width"),
-        ]:
-            if line_stripped.startswith(field) and len(line_stripped) > len(field):
-                value = line_stripped[len(field):].strip()
-                if value:
-                    current_result[target_key] = value
-                    current_field = field
-                    field_matched = True
-                    break
-        
-        if not field_matched and current_field:
-            # Continuation of multi-line field value
-            if current_field in ("body", "snippet", "description", "content"):
-                current_result.setdefault("snippet", "")
-                current_result["snippet"] += " " + line_stripped
-    
-    if current_result:
-        results.append(current_result)
-    
-    # Ensure all results have required fields, score, and published_at
-    for i, r in enumerate(results):
-        r.setdefault("source", engine_name)
-        r.setdefault("title", "")
-        r.setdefault("url", "")
-        r.setdefault("snippet", "")
-        # Add score based on result position (higher = better)
-        r.setdefault("score", round(0.9 - (i * 0.05), 2))
-        # Add published_at for time-window filtering
-        if "date" in r:
-            r["published_at"] = r["date"]
-        else:
-            r.setdefault("published_at", "")
-    
-    return results, ""
+                    since: str | None = None, until: str | None = None) -> tuple[list[dict[str, Any]], str]:
+    return _raw_run_cli_engine(spec, query, n, timeout, since=since, until=until, lang_param_fn=_lang_param)
 
 
 def _resolve_redirect_results(results: list[dict[str, Any]], n: int,