argo-search 1.0.1 → 2.9.7

package/scripts/x_search.py

@@ -0,0 +1,234 @@
+#!/usr/bin/env python3
+"""X (Twitter) 关键词搜索（ego-browser，纯标准库，零文件读写）。
+
+定位：X 原生搜索是唯一能吃 X 布尔语法的通道——`from:`（盯人）、
+`-is:retweet`（去转发）、`min_faves:`（热度门）、`lang:`（语言）、
+`since:`/`until:`（时间窗）。这些语法在任何通用网页搜索引擎上都会被忽略，
+所以「盯一批官方号 / 按关键词找发布」这件事只能走 x.com/search 本体。
+
+通道原理：借 ego-browser 驱动用户默认浏览器（Ego Lite）打开 x.com/search，
+复用浏览器 profile 的登录态与指纹。**为什么必须登录态**：X 对未登录请求
+一律拒绝或给降级页；而 x_trending 已证明该 profile 通道长期可用。
+
+与 fxtwitter（engines/specs/fxtwitter.yaml）的关系：那是 HTTP 免登录通道，
+曾经是主路径，但上游公开实例的 `/2/search` 已停用（对任意查询恒返回
+404 + 空 results，status/profile 端点仍正常）——本脚本是它的可用替代，
+只做关键词搜索，不做单条打包（单条走 `argo tweet`）。
+
+输出：YAML 列表（title/url/snippet/source/published_at/social_meta），
+与引擎统一 schema 对齐，便于被 `argo template` 直接转发。
+
+依赖：ego-browser CLI（Ego Lite）+ 已登录的 X 会话。缺失 / 未渲染 / 结构变化
+→ stderr 报因、退出码 1（调用方对 rc!=0 只取 stderr 留痕、结果为空）。
+
+用法：
+  python3 scripts/x_search.py "OpenAI" -n 20
+  python3 scripts/x_search.py '(GPT OR Claude) release -is:retweet' --sort top --json
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import shutil
+import subprocess
+import sys
+
+JS_RESULT_WAIT_S = 15          # 浏览器内等首屏渲染的墙钟（秒）
+SUBPROC_TIMEOUT = 90           # ego-browser 子进程墙钟封顶（含滚动加载）
+X_SEARCH_BASE = "https://x.com/search"
+JSON_MARKER = "@@JSON@@"
+MAX_SCROLL = 3                 # 最多下滚几次以凑够 n（每次约一屏半）
+
+# JS 侧：抓 x.com/search 渲染结果。CFG 为 JSON 字面量（ensure_ascii 注入）。
+# 抽取口径全部走 data-testid，不碰 class 名（X 的 class 是哈希串，改版即失效）。
+_JS_TEMPLATE = """
+const CFG = %(cfg)s;
+const task = await taskSpace("argo X搜索");
+let page = null;
+try { page = task.page("p1"); } catch (e) { page = null; }
+if (!page) page = await task.newPage();
+await page.goto(%(base)s + "?q=" + encodeURIComponent(CFG.query) + "&f=" + CFG.sort);
+// 等首屏：出 article 视为渲染完成；出「无结果」文案也视为渲染完成（真·空结果）
+let rendered = false;
+for (let i = 0; i < %(wait_s)d; i++) {
+  await page.waitForTimeout(1000);
+  const st = await page.evaluate(() => ({
+    arts: document.querySelectorAll('[data-testid="cellInnerDiv"] article').length,
+    empty: /没有结果|No results for|无结果/i.test(document.body.innerText || ""),
+  }));
+  if (st.arts > 0 || st.empty) { rendered = true; break; }
+}
+let items = [];
+if (rendered) {
+  for (let s = 0; s < CFG.maxScroll; s++) {
+    const cnt = await page.evaluate(() =>
+      document.querySelectorAll('[data-testid="cellInnerDiv"] article').length);
+    if (cnt >= CFG.n) break;
+    await page.evaluate(() => window.scrollBy(0, window.innerHeight * 3));
+    await page.waitForTimeout(1200);
+  }
+  items = await page.evaluate(() => {
+    // 互动数从按钮 aria-label 取首个整数（本地化文案不同，但数字恒在前）
+    const num = (s) => {
+      const m = (s || "").match(/\\d[\\d,\\.]*/);
+      return m ? parseInt(m[0].replace(/[,\\.]/g, ""), 10) : 0;
+    };
+    const out = [];
+    const seen = new Set();
+    for (const art of document.querySelectorAll('[data-testid="cellInnerDiv"] article')) {
+      const t = art.querySelector('[data-testid="tweetText"]');
+      const a = art.querySelector('a[href*="/status/"]');
+      const tm = art.querySelector('time[datetime]');
+      const href = a ? a.href : "";
+      if (!href || seen.has(href)) continue;
+      seen.add(href);
+      const text = t ? t.innerText.trim() : "";
+      const like = art.querySelector('[data-testid="like"]');
+      const rt = art.querySelector('[data-testid="retweet"]');
+      const rp = art.querySelector('[data-testid="reply"]');
+      out.push({
+        text: text,
+        href: href,
+        published_at: tm ? tm.getAttribute("datetime") : "",
+        likes: num(like && like.getAttribute("aria-label")),
+        reposts: num(rt && rt.getAttribute("aria-label")),
+        replies: num(rp && rp.getAttribute("aria-label")),
+      });
+    }
+    return out;
+  });
+}
+console.log("%(marker)s" + JSON.stringify({ok: rendered, items: items.slice(0, CFG.n)}));
+"""
+
+
+def _build_js(query: str, n: int, sort: str) -> str:
+    """把配置注入 JS 模板。"""
+    return _JS_TEMPLATE % {
+        "cfg": json.dumps({"query": query, "n": n, "sort": sort,
+                           "maxScroll": MAX_SCROLL}, ensure_ascii=True),
+        "base": json.dumps(X_SEARCH_BASE),
+        "wait_s": JS_RESULT_WAIT_S,
+        "marker": JSON_MARKER,
+    }
+
+
+def _extract_json(stdout: str) -> dict | None:
+    """从 ego-browser 输出里取标记行 JSON（CLI 可能夹杂 notice 行）。"""
+    for line in reversed((stdout or "").splitlines()):
+        if line.startswith(JSON_MARKER):
+            try:
+                return json.loads(line[len(JSON_MARKER):])
+            except json.JSONDecodeError:
+                continue
+    return None
+
+
+def _handle_from_url(url: str) -> str:
+    """从 status URL 里取作者 handle（https://x.com/<handle>/status/<id>）。"""
+    try:
+        parts = url.split("/")
+        i = parts.index("x.com")
+        return parts[i + 1] if i + 1 < len(parts) else ""
+    except (ValueError, IndexError):
+        return ""
+
+
+def _rows(items: list[dict], n: int) -> list[dict]:
+    """ego-browser 抽取结果 → 统一 result schema（与引擎输出对齐）。"""
+    rows: list[dict] = []
+    for it in items[:n]:
+        href = str(it.get("href") or "").strip()
+        if not href.startswith(("http://", "https://")):
+            continue
+        text = str(it.get("text") or "").strip()
+        sid = href.rsplit("/", 1)[-1]
+        rows.append({
+            "title": (text[:100] + ("..." if len(text) > 100 else "")) or f"Tweet {sid}",
+            "url": href,
+            "snippet": text[:300],
+            "source": "x_search",
+            "published_at": it.get("published_at") or None,
+            "social_meta": {
+                "platform": "twitter",
+                "content_type": "tweet",
+                "id": sid,
+                "author": _handle_from_url(href),
+                "likes": it.get("likes") or 0,
+                "reposts": it.get("reposts") or 0,
+                "replies": it.get("replies") or 0,
+                "provider": "x_search",
+            },
+        })
+    return rows
+
+
+def main(argv: list | None = None) -> int:
+    ap = argparse.ArgumentParser(
+        prog="argo x-search",
+        description="X (Twitter) 关键词搜索（原生布尔语法：from:/min_faves:/-is:retweet/lang:）")
+    ap.add_argument("query", help="搜索词，支持 X 原生语法")
+    ap.add_argument("-n", "--n", type=int, default=20, help="最多返回条数（默认 20）")
+    ap.add_argument("--sort", choices=["latest", "top"], default="latest",
+                    help="latest=最新（默认，f=live）/ top=热门（f=top）")
+    ap.add_argument("--timeout", type=float, default=SUBPROC_TIMEOUT)
+    ap.add_argument("--json", action="store_true", help="JSON 输出")
+    args = ap.parse_args(argv)
+
+    query = (args.query or "").strip()
+    if not query:
+        print("x_search: 搜索词为空", file=sys.stderr)
+        return 1
+
+    if not shutil.which("ego-browser"):
+        print("x_search: ego-browser CLI 不存在（Ego Lite 未安装？）", file=sys.stderr)
+        return 1
+
+    sort = "top" if args.sort == "top" else "live"
+    try:
+        proc = subprocess.run(
+            ["ego-browser", "nodejs", "-e", _build_js(query, max(1, args.n), sort)],
+            capture_output=True, text=True, encoding="utf-8",
+            errors="replace", timeout=args.timeout)
+    except subprocess.TimeoutExpired:
+        print(f"x_search: ego-browser 超时（>{args.timeout:.0f}s）", file=sys.stderr)
+        return 1
+    except FileNotFoundError:
+        print("x_search: ego-browser 调用失败", file=sys.stderr)
+        return 1
+
+    if proc.returncode != 0:
+        tail = (proc.stderr or "").strip()[:200]
+        print(f"x_search: ego-browser rc={proc.returncode}: {tail}", file=sys.stderr)
+        return 1
+
+    data = _extract_json(proc.stdout) or _extract_json(proc.stderr)
+    if not data:
+        print("x_search: 未能解析 ego-browser 输出", file=sys.stderr)
+        return 1
+    if not data.get("ok"):
+        # 页面没渲染：多半是未登录、被风控拦下，或 X 改版
+        print("x_search: x.com/search 未渲染（未登录 / 风控 / 改版？）", file=sys.stderr)
+        return 1
+
+    rows = _rows(data.get("items") or [], max(1, args.n))
+
+    if args.json:
+        print(json.dumps(rows, ensure_ascii=False))
+        return 0
+    if not rows:
+        print(f"x_search: 「{query}」无结果", file=sys.stderr)
+        return 0
+    for i, r in enumerate(rows, 1):
+        meta = r.get("social_meta") or {}
+        print(f"### {i}. {r['title']}")
+        print(f"- **URL**: {r['url']}")
+        print(f"- @{meta.get('author', '')} · {r.get('published_at') or ''} · "
+              f"♥{meta.get('likes', 0)} ⇄{meta.get('reposts', 0)} 💬{meta.get('replies', 0)}")
+        print()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/x_trending.py

@@ -0,0 +1,189 @@
+#!/usr/bin/env python3
+"""X (Twitter) Trending 热榜（ego-browser，纯标准库，零文件读写）。
+
+定位：X Trending 热榜是别处拿不到的独家热点源（科技/娱乐/全球趋势分类、
+带实时排名）。借 ego-browser 驱动用户默认浏览器（Ego Lite）抓取
+x.com/explore/tabs/trending 的渲染结果——复用浏览器 profile 的 cookie 与
+指纹，避免匿名请求被 X 风控拦下。
+
+与 sogou_weixin_browser 的差别：本脚本**不做任何状态文件读写**（不持久化
+task space、不加文件锁），每次调用自建 task space 抓完即走。取舍：放弃
+跨调用的会话复用（X 的登录态与 cookie 在浏览器 profile 层，与 task space
+无关，冷空间实测同样取到数据），换来脚本零路径写入面。
+
+输出：热榜条目（排名、类别、话题、跳转链接），YAML 列表。
+
+依赖：ego-browser CLI（Ego Lite 浏览器）。缺失 / 未运行 / 页面结构变化 →
+stderr 报因、退出码 1（argo _run 对 rc!=0 只取 stderr 留痕，引擎返回空）。
+
+用法：
+  python3 scripts/x_trending.py --n 10
+  python3 scripts/x_trending.py "热榜" --n 5      # 位置参数兼容引擎契约，忽略
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import shutil
+import subprocess
+import sys
+
+JS_RESULT_WAIT_S = 12          # 浏览器内等渲染的墙钟
+SUBPROC_TIMEOUT = 45           # ego-browser 子进程墙钟封顶
+X_TRENDING_URL = "https://x.com/explore/tabs/trending"
+JSON_MARKER = "@@JSON@@"
+
+# JS 侧：抓 X Trending 页面。CFG 为 JSON 字面量（ensure_ascii 注入）。
+_JS_TEMPLATE = """
+const CFG = %(cfg)s;
+const task = await taskSpace("argo X热榜");
+let page = null;
+try { page = task.page("p1"); } catch (e) { page = null; }
+if (!page) page = await task.newPage();
+await page.goto(%(url)s);
+// 等热榜渲染（trend 元素出现或超时）
+let got = false;
+for (let i = 0; i < %(wait_s)d; i++) {
+  await page.waitForTimeout(1000);
+  const n = await page.evaluate(() => document.querySelectorAll('[data-testid="trend"]').length);
+  if (n > 0) { got = true; break; }
+}
+let items = [];
+if (got) {
+  items = await page.evaluate(() => {
+    const out = [];
+    for (const el of document.querySelectorAll('[data-testid="trend"]')) {
+      const text = el.innerText.trim();
+      if (!text) continue;
+      // 过滤 Promoted 广告
+      if (/promoted by/i.test(text)) continue;
+      // X 的行结构：["1", "·", "科技 趋势", "<话题>"]，分隔点行要丢掉
+      const lines = text.split("\\n").map(s => s.trim())
+        .filter(s => s && s !== "·" && s !== "．");
+      if (lines.length < 2) continue;
+      let rank = "";
+      if (/^\\d+$/.test(lines[0])) rank = lines.shift();
+      // 话题恒为最后一行；其前一行是分类（趋势类目），再前不再取
+      const topic = lines[lines.length - 1].slice(0, 100);
+      const category = lines.length >= 2 ? lines[lines.length - 2].slice(0, 40) : "";
+      if (!topic) continue;
+      const a = el.querySelector("a[href]");
+      out.push({ rank, category, topic, href: a ? a.href : "" });
+    }
+    return out;
+  });
+}
+console.log("%(marker)s" + JSON.stringify({
+  ok: got,
+  items: items.slice(0, CFG.n),
+}));
+"""
+
+
+def _build_js(n: int) -> str:
+    """把配置注入 JS 模板。"""
+    return _JS_TEMPLATE % {
+        "cfg": json.dumps({"n": n}, ensure_ascii=True),
+        "url": json.dumps(X_TRENDING_URL),
+        "wait_s": JS_RESULT_WAIT_S,
+        "marker": JSON_MARKER,
+    }
+
+
+def _extract_json(stdout: str) -> dict | None:
+    """从 ego-browser 输出里取标记行 JSON（CLI 可能夹杂 notice 行）。"""
+    for line in reversed((stdout or "").splitlines()):
+        if line.startswith(JSON_MARKER):
+            try:
+                return json.loads(line[len(JSON_MARKER):])
+            except json.JSONDecodeError:
+                continue
+    return None
+
+
+# 泛词：这些 query 只表示「我要看热榜」，不做关键词过滤
+_GENERIC_QUERIES = frozenset({
+    "", "热榜", "热搜", "热搜榜", "热门", "热门话题", "趋势", "热议", "今日热搜",
+    "trending", "trend", "trends", "hot", "top trends", "hot search",
+})
+
+
+def _focus(rows: list[dict], query: str) -> list[dict]:
+    """位置参数 query 的语义：非泛词时按关键词聚焦热榜。
+
+    例：`argo search "AI" --engine x_trending` → 只留命中 AI 的趋势条目。
+    热榜是固定榜单而非检索结果，**无命中时回落全榜**（过滤只是聚焦，
+    不该让「今天 AI 没上榜」表现为引擎空手）。
+    """
+    q = (query or "").strip()
+    if q.casefold() in _GENERIC_QUERIES:
+        return rows
+    ql = q.casefold()
+    hit = [r for r in rows
+           if ql in f"{r.get('title', '')} {r.get('snippet', '')}".casefold()]
+    return hit or rows
+
+
+def main(argv: list | None = None) -> int:
+    ap = argparse.ArgumentParser(description="X (Twitter) Trending 热榜")
+    ap.add_argument("query", nargs="?", default="",
+                    help="兼容引擎契约的位置参数（本引擎按热榜取数，忽略该值）")
+    ap.add_argument("--n", type=int, default=10)
+    ap.add_argument("--timeout", type=float, default=SUBPROC_TIMEOUT)
+    args = ap.parse_args(argv)
+
+    if not shutil.which("ego-browser"):
+        print("x_trending: ego-browser CLI 不存在（Ego Lite 未安装？）",
+              file=sys.stderr)
+        return 1
+
+    try:
+        proc = subprocess.run(
+            ["ego-browser", "nodejs", "-e", _build_js(args.n)],
+            capture_output=True, text=True, encoding="utf-8",
+            errors="replace", timeout=args.timeout)
+    except subprocess.TimeoutExpired:
+        print(f"x_trending: ego-browser 超时（>{args.timeout:.0f}s）", file=sys.stderr)
+        return 1
+    except FileNotFoundError:
+        print("x_trending: ego-browser 调用失败", file=sys.stderr)
+        return 1
+
+    if proc.returncode != 0:
+        tail = (proc.stderr or "").strip()[:200]
+        print(f"x_trending: ego-browser rc={proc.returncode}: {tail}",
+              file=sys.stderr)
+        return 1
+    data = _extract_json(proc.stdout) or _extract_json(proc.stderr)
+    if not data:
+        print("x_trending: 未能解析 ego-browser 输出", file=sys.stderr)
+        return 1
+    if not data.get("ok"):
+        print("x_trending: X Trending 页面未渲染或结构变化", file=sys.stderr)
+        return 1
+
+    rows = []
+    for it in data.get("items", []):
+        topic = str(it.get("topic") or "").strip()
+        if not topic:
+            continue
+        rank = str(it.get("rank") or "").strip()
+        category = str(it.get("category") or "").strip()
+        href = str(it.get("href") or "").strip()
+        if not href.startswith(("http://", "https://")):
+            href = f"https://x.com/search?q={topic.replace(' ', '%20')}"
+        rows.append({
+            "title": (f"{rank}. {topic}" if rank else topic)[:80],
+            "url": href,
+            "snippet": (f"X Trending | {category}" if category else "X Trending")[:200],
+        })
+
+    import yaml
+    rows = _focus(rows, args.query)
+    print(yaml.safe_dump(rows[: max(1, args.n)], allow_unicode=True, sort_keys=False))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/yaml_load.py

@@ -0,0 +1,67 @@
+#!/usr/bin/env python3
+"""yaml_load.py — YAML 解析的唯一入口（决定用哪个 loader）。
+
+## 为什么需要这个模块
+
+PyYAML 有两个语义相同的 SafeLoader 实现：
+  - `yaml.SafeLoader`   纯 Python，解析 100 KB 配置实测 **79 ms**
+  - `yaml.CSafeLoader`  libyaml C 绑定，同样内容实测 **10 ms**（快约 7.7 倍）
+
+`yaml.safe_load()` 恒走纯 Python 那条。此前 8 个模块各自直接调它，于是
+「用哪个解析器」这件事被复制了 8 份，没有任何一处能统一改进——与 fetch
+的 `--focus` 参数同一种失败模式（各写一份 → 漏改无人察觉）。
+
+本模块是 2026-09-15 冷启动优化的一部分：`import search` 曾耗时约 500 ms，
+其中约 316 ms 是 4 次 `peek_cache_db_path()` 各自解析一遍 123 KB 的
+config.yaml，而每次解析的绝大部分时间花在纯 Python 扫描器上。换成 C 版
+后单次降到约 10 ms。
+
+## 用法
+
+    from yaml_load import loads, load
+
+    data = loads(text)          # 解析字符串
+    data = load(path)           # 读取并解析文件
+
+两者在 PyYAML 缺失时抛 ImportError（与 config._require_yaml 的原契约一致，
+调用方按既有 fail-open 语义自行处理），解析失败抛 yaml.YAMLError。
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+__all__ = ["loads", "load", "safe_loader"]
+
+
+def _yaml():
+    import yaml  # type: ignore
+    return yaml
+
+
+def safe_loader() -> Any:
+    """返回可用的安全 loader 类：优先 libyaml C 版，不可用回落纯 Python。
+
+    两者语义一致（C 版就是 SafeLoader 的 C 实现），差别只在速度。
+    纯 Python 环境（未编译 libyaml）下行为与改动前完全相同。
+    """
+    yaml = _yaml()
+    return getattr(yaml, "CSafeLoader", None) or yaml.SafeLoader
+
+
+def loads(text: str) -> Any:
+    """解析 YAML 文本（安全 loader）。非 dict/list 的顶层结构按原样返回。"""
+    yaml = _yaml()
+    return yaml.load(text, Loader=safe_loader())
+
+
+def load(path: str | Path) -> Any:
+    """读取并解析 YAML 文件（UTF-8）。"""
+    text = Path(path).read_text(encoding="utf-8")
+    try:
+        return loads(text)
+    except Exception:
+        # 与 yaml.safe_load 对 file 对象的错误语义保持一致：把非 YAML 内容
+        # 造成的问题留给调用方判断（此前各自直接 safe_load 也是这个行为）
+        raise