argo-search 1.0.1 → 2.9.7

package/references/query-templates.md

@@ -0,0 +1,96 @@
+# 查询模板（Query Templates）
+
+命名好的检索模式：一步展开并执行，可组合、可扩展。日常用 `argo template`
+即可，本文件解释机制与扩展方式。
+
+## 快速上手
+
+```bash
+argo template --list                          # 列出全部模板（按分组）
+argo template ai_model_release                # 用模板搜索
+argo template ai_model_release --add "GPT-5"  # 模板 + 追加词（空格即 AND）
+argo template ai_zh --sort top -n 20 --json   # 转发参数给底层命令
+argo template ai_model_release --dry-run      # 只看展开后的命令与查询串
+```
+
+`argo template` 只做三件事：**取模板 → 展开成查询串 → 转发给该模板的 command**。
+转发参数（`-n` / `--sort` / `--json` / `--engine` / `--since` …）原样透传，
+语义仍由底层命令持有——本机制不复制任何搜索开关定义。
+
+## 随包模板
+
+源自宝玉（[@dotey](https://x.com/dotey)）《X AI 资讯检索》方法论，全部走
+`command: x-search`（X 原生搜索），查询统一带 `-is:retweet`（去转发）与
+`lang:`（语言）。
+
+| 分组 | id | 说明 |
+|------|----|------|
+| AI 模型 | `ai_model_release` | 前沿模型发布/正式开放 |
+| AI 模型 | `ai_new_model` | 新模型 / 开放权重 / 开源模型 |
+| AI 产品 | `ai_agent_product` | AI Agent / MCP / agent skills 发布 |
+| AI 产品 | `ai_coding_agent` | 编码 Agent 更新（Cursor / Claude Code / Codex / Devin …） |
+| AI 行业 | `ai_industry_funding` | 融资 / 并购 / 破产 |
+| AI 行业 | `ai_industry_policy` | 监管 / 诉讼 / 禁令 / 行政令 |
+| AI 行业 | `ai_security` | 安全 / 漏洞 / 越狱 / 泄露 |
+| AI 爆料 | `ai_leak` | 爆料 / 泄露 / 即将发布 |
+| AI 中文 | `ai_zh` | 中文 AI 资讯（发布 / 开源 / 上线） |
+| 示例 | `ai_media_tools` | 语音/视频/媒体类 AI 工具发布（自定义方向样例） |
+
+热度筛选：加 `--sort top` 走 X 的 Top 榜（默认 `latest` 最新）；或拿到结果后
+按 `social_meta.likes/reposts` 排序。
+
+## 加自己的模板（零代码）
+
+把同名文件放到用户注册表即可，**不改仓库**：
+
+```
+$XDG_CONFIG_HOME/argo/query-templates.yaml   # 缺省 ~/.config/argo/query-templates.yaml
+```
+
+或用环境变量 `ARGO_TEMPLATES_FILE` 指路径。合并规则：新 id 追加，同名 id 覆盖
+随包条目；`disabled: true` 停用随包条目。
+
+```yaml
+version: 1
+templates:
+  quantum_news:
+    description: 量子计算进展
+    category: 我的方向
+    command: x-search
+    query: '(quantum computing OR qubit) (breakthrough OR milestone) -is:retweet lang:en'
+```
+
+`command` 白名单只有两个：`x-search`（X 原生搜索）与 `search`（通用多源搜索，
+走 `argo search`）。模板是数据，**不拥有执行任意命令的能力**。
+
+## X 原生搜索语法速查（`command: x-search` 时）
+
+| 语法 | 含义 |
+|------|------|
+| `-is:retweet` | 去转发 |
+| `lang:en` / `lang:zh` | 语言 |
+| `from:OpenAI` | 盯人（可 OR：`from:OpenAI OR from:AnthropicAI`） |
+| `min_faves:100` / `min_retweets:50` | 热度门 |
+| `since:2026-10-01 until:2026-10-16` | 时间窗 |
+| `-filter:replies` | 排除回复 |
+| `filter:media` / `filter:images` / `filter:videos` | 只要媒体 |
+| 空格=AND、`OR`=或、`-词`=排除、`( )`=分组 | 布尔与分组 |
+
+「盯一批官方号」的典型写法：`from:OpenAI OR from:AnthropicAI OR from:GoogleDeepMind -is:retweet lang:en`，
+存成一条模板即可复用。
+
+## 通道说明（为什么是 x-search 而不是 fxtwitter）
+
+X 布尔语法只有 `x.com/search` 本体认，通用网页搜索引擎一律忽略——所以要
+「盯人 / 按关键词找发布」只能走 X 原生搜索。`argo x-search` 借 ego-browser
+驱动用户已登录的浏览器抓 `x.com/search`（同 `x_trending` 引擎的通道思路）。
+
+> 注：`engines/specs/fxtwitter.yaml` 的 HTTP 免登录搜索通道，上游公开实例的
+> `/2/search` 已停用（对任意查询恒返回 404 + 空结果，status/profile 端点仍正常）。
+> 关键词搜索请走 `argo x-search`；单条推文按 URL 取正文仍走 `argo tweet`。
+
+## 与其它能力的关系
+
+- **模板 ≠ 深度研究**：模板是「一次结构化检索」，要问题分解 / 多源取证 / 达标检查走 `argo research`。
+- **模板 ≠ 事实核验**：社交帖是叙事/舆情，不进事实真值（见 SKILL.md「Agent 执行纪律」）。要核到走 `argo evidence` / `--verify`。
+- **交叉核对**：X 上的说法对照 Hacker News / 官方博客 / 主流媒体（宝玉方法论第 4 条）——用 `argo search` 或 `argo research` 完成，模板只负责把 X 侧取全。

package/references/query-templates.yaml

@@ -0,0 +1,118 @@
+# Argo 查询模板注册表（Query Template Registry）
+#
+# 用途：把「命名好的检索模式」沉淀成可复用、可组合、可扩展的数据。
+# 用户不必每次手打长串布尔查询，也不必记住哪套词组合最有效。
+#
+# 调用：argo template <id> [--add 词 ...] [--dry-run] [--list]
+#   例：argo template ai_model_release --add "GPT-5" -n 20
+#       → 展开 query 并把 --add 追加成 AND 项，转发给该模板的 command
+#
+# 字段：
+#   description  一句话说明（--list 显示）
+#   category     分组（--list 按它分组；任意字符串，用户可自定义）
+#   command      目标 argo 子命令，白名单：search | x-search（缺省 search）
+#   query        查询串（原样下推；X 原生语法见文末）
+#   tags         可选，检索/过滤用
+#   note         可选，给维护者/用户的提醒（--list --json 会带出）
+#
+# 扩展（不改本文件）：把同名文件放到 $XDG_CONFIG_HOME/argo/query-templates.yaml
+# （缺省 ~/.config/argo/query-templates.yaml），或用 ARGO_TEMPLATES_FILE 指路径。
+# 用户文件按 id 合并：新增即追加，同名即覆盖；`disabled: true` 可停用随包模板。
+# 这样新增领域（量子计算 / 生物医药 / 加密货币 …）零代码，只加几行 YAML。
+#
+# 随包模板源自宝玉（@dotey）《X AI 资讯检索》方法论，全部针对 X 原生搜索
+# （command: x-search），查询统一带 `-is:retweet`（去转发）与 `lang:`（语言）。
+
+version: 1
+
+templates:
+
+  # ── 模型发布 ────────────────────────────────────────────────────────────
+  ai_model_release:
+    description: 前沿模型发布/正式开放
+    category: AI 模型
+    command: x-search
+    tags: [ai, model, release]
+    query: '(GPT OR Claude OR Gemini OR Llama OR Grok OR Qwen OR DeepSeek OR Mistral) (release OR launch OR announce OR "now available") -is:retweet lang:en'
+
+  ai_new_model:
+    description: 新模型 / 开放权重 / 开源模型
+    category: AI 模型
+    command: x-search
+    tags: [ai, model, open-weights]
+    query: '("new model" OR "open weights" OR "open-source model") AI -is:retweet lang:en'
+
+  # ── 产品与 Agent ────────────────────────────────────────────────────────
+  ai_agent_product:
+    description: AI Agent / MCP / agent skills 发布
+    category: AI 产品
+    command: x-search
+    tags: [ai, agent, mcp]
+    query: '("AI agent" OR "coding agent" OR "agent skills" OR MCP) (launch OR ships OR introducing) -is:retweet lang:en'
+
+  ai_coding_agent:
+    description: 编码 Agent 更新（Cursor / Claude Code / Codex / Devin …）
+    category: AI 产品
+    command: x-search
+    tags: [ai, coding-agent]
+    query: '(Cursor OR "Claude Code" OR Codex OR Antigravity OR Devin) (launch OR update) -is:retweet lang:en'
+
+  # ── 行业大事 ────────────────────────────────────────────────────────────
+  ai_industry_funding:
+    description: 融资 / 并购 / 破产
+    category: AI 行业
+    command: x-search
+    tags: [ai, funding, ma]
+    query: 'AI (acquires OR acquisition OR "raises" OR bankruptcy OR "Series A" OR "Series B") -is:retweet lang:en'
+
+  ai_industry_policy:
+    description: 监管 / 诉讼 / 禁令 / 行政令
+    category: AI 行业
+    command: x-search
+    tags: [ai, policy, regulation]
+    query: 'AI (regulation OR lawsuit OR ban OR "executive order" OR "AI Act") -is:retweet lang:en'
+
+  ai_security:
+    description: 安全 / 漏洞 / 越狱 / 泄露
+    category: AI 行业
+    command: x-search
+    tags: [ai, security]
+    query: 'AI ("safety" OR "security" OR vulnerability OR jailbreak OR leak) -is:retweet lang:en'
+
+  # ── 爆料 ────────────────────────────────────────────────────────────────
+  ai_leak:
+    description: 爆料 / 泄露 / 即将发布
+    category: AI 爆料
+    command: x-search
+    tags: [ai, leak, rumor]
+    query: '(spotted OR leaked OR "coming soon") (GPT OR Claude OR Gemini) -is:retweet lang:en'
+
+  # ── 中文 ────────────────────────────────────────────────────────────────
+  ai_zh:
+    description: 中文 AI 资讯（发布 / 开源 / 上线）
+    category: AI 中文
+    command: x-search
+    tags: [ai, zh]
+    query: '(大模型 OR AI) (发布 OR 开源 OR 上线) lang:zh -is:retweet'
+
+  # ── 自定义方向示例 ──────────────────────────────────────────────────────
+  # 「使用者自己的方向」——按人调整（此处以 AI 语音/视频/媒体工具为例）。
+  # 想加自己的方向：复制本条目改 id 与 query 即可（用户注册表更佳，见文件头）。
+  ai_media_tools:
+    description: 语音/视频/媒体类 AI 工具发布（自定义方向示例）
+    category: 示例（自定义方向）
+    command: x-search
+    tags: [ai, media, tts, example]
+    note: 这是「按使用者方向调整」的样例，替换关键词即可变成你自己的方向。
+    query: '("text to speech" OR TTS OR "video editing" OR "speech to text") AI (release OR open) -is:retweet lang:en'
+
+# ── X 原生搜索语法速查（供改 query 时参考）─────────────────────────────────
+#   去转发         -is:retweet
+#   语言           lang:en / lang:zh
+#   盯人           from:OpenAI  （可 OR：from:OpenAI OR from:AnthropicAI）
+#   热度门         min_faves:100 / min_retweets:50
+#   时间窗         since:2026-10-01 until:2026-10-16
+#   排除回复       -filter:replies
+#   只要媒体       filter:media / filter:images / filter:videos
+#   布尔与分组     空格=AND，OR=或，-词=排除，( ) 分组
+#   示例：from:OpenAI -is:retweet min_faves:50 since:2026-10-01

package/scripts/ab_eval.py

@@ -0,0 +1,219 @@
+#!/usr/bin/env python3
+"""ab_eval — 交错 A/B 实测（逐对随机化运行顺序，防顺序偏差）。
+
+为什么存在（2026-10-07 教训）：非交错基准里，暖连接红利让「后跑的一组」
+系统性变慢/变快，造出过 37% 的假阳性——本仓历史同类假阳性至少三次
+（roundtrip 第三次假阳性、benchmark 阈值改旗标、10-07 事件化证伪轮）。
+本工具把正确测量固化成可复用能力：**逐对抛硬币定运行序**，逐对差值出
+统计量（中位差、A 胜率、精确二项符号检验），单次快慢不作数。
+
+与 ab_eval_p0p1.py 的分工：那是 P0/P1 优化轮的一次性验收脚本（固定场景
+清单）；本工具是通用 A/B 测量器——两条带 {query} 占位符的命令即可对测
+（不同引擎组合、开关、参数档）。
+
+用法：
+  python3 scripts/ab_eval.py --pairs 10 \
+    --cmd-a "python3 scripts/search.py {query} --json --fields agent" \
+    --cmd-b "python3 scripts/search.py {query} --json --fields agent --verify 2" \
+    --query "蓝牙耳机推荐"
+
+子进程默认注入 ARGO_USAGE_LOG=0：A/B 用的是合成查询对，不进生产使用账本
+（口径同 10-10 评测隔离原则）；--usage-log 保留写入。
+
+输出 stdout 单个 JSON：per_pair（含当对运行序）+ stats。exit 恒 0（测量
+工具不是门禁）；质量守卫字段 count_median_a/b 供人工判断结果数回退。
+
+尾判据（2026-10-15 增补，B-4）：stats 里除中位差/符号检验外，还给
+p90_a/b、max_a/b 与 tail_verdict。**中位差不等于改动可用**——中位由最快的
+那个引擎决定，把并发从 3 提到 6 只可能动尾部（上游限流、连接竞争）：中位纹
+丝不动而 p90/max 翻倍的改动，只看中位会被放行。判据因此是「尾不退化」：
+p90 与 max 各自不超过容忍倍数才 passed。
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import math
+import os
+import random
+import shlex
+import statistics
+import subprocess
+import sys
+import time
+
+_RUN_TIMEOUT_S = 120
+
+# 尾退化容忍倍数：p90 允许 +10%、max 允许 +25%（单点极值天然更抖，给宽些）。
+# 判据是「不退化」而不是「必须变快」：并发上调的收益在中位/成功率，不在尾部。
+_DEFAULT_P90_TOL = 1.10
+_DEFAULT_MAX_TOL = 1.25
+
+
+def percentile_nearest_rank(values: list[float], p: float) -> float | None:
+    """最近秩分位数（ceil(p·n) 取第 k 小），与 adaptive.latency_percentile 同口径。
+
+    不用 statistics.quantiles：它要求 n≥2 且走插值，n=10 的 p90 会取到第 9 与
+    第 10 个样本之间的值——尾判据要的是「真实观测到的第 90 百分位」，插值会
+    把单点极值摊薄。
+    """
+    vals = sorted(float(v) for v in values)
+    if not vals:
+        return None
+    k = max(1, min(len(vals), math.ceil(float(p) * len(vals))))
+    return vals[k - 1]
+
+
+def tail_verdict(a_ms: list[float], b_ms: list[float], *,
+                 p90_tol: float = _DEFAULT_P90_TOL,
+                 max_tol: float = _DEFAULT_MAX_TOL) -> dict:
+    """B 相对 A 的尾延迟判定：p90 与 max 都不超容忍倍数才算 passed。
+
+    只比同一批配对的耗时样本（A/B 各自独立取数，不配对相减——尾延迟关心的是
+    「最坏那一档变成了多少」，不是逐对差值的分布）。
+    """
+    a_p90 = percentile_nearest_rank(a_ms, 0.9)
+    b_p90 = percentile_nearest_rank(b_ms, 0.9)
+    a_max = max(a_ms) if a_ms else None
+    b_max = max(b_ms) if b_ms else None
+
+    def _ratio(a, b):
+        if a is None or b is None or a <= 0:
+            return None
+        return round(b / a, 3)
+
+    r90, rmax = _ratio(a_p90, b_p90), _ratio(a_max, b_max)
+    reasons = []
+    if r90 is not None and r90 > p90_tol:
+        reasons.append(f"p90 退化 {r90:.2f}x > {p90_tol:.2f}x")
+    if rmax is not None and rmax > max_tol:
+        reasons.append(f"max 退化 {rmax:.2f}x > {max_tol:.2f}x")
+    if a_p90 is None or b_p90 is None:
+        reasons.append("样本不足，无法判定")
+    return {
+        "p90_a_ms": a_p90, "p90_b_ms": b_p90, "p90_ratio": r90,
+        "max_a_ms": a_max, "max_b_ms": b_max, "max_ratio": rmax,
+        "p90_tol": p90_tol, "max_tol": max_tol,
+        "passed": not reasons,
+        "reason": "；".join(reasons) or "尾延迟未退化",
+    }
+
+
+def _run_once(cmd: str, query: str, keep_usage: bool) -> dict:
+    # {query} 由本函数负责加引号（shlex.quote）：含空格查询此前会把命令拆成
+    # 多个 argv，argparse 直接 rc=2——占位符两侧不要再自行加引号。
+    substituted = cmd.replace("{query}", shlex.quote(query))
+    env = dict(os.environ)
+    if not keep_usage:
+        env["ARGO_USAGE_LOG"] = "0"
+    t0 = time.monotonic()
+    try:
+        proc = subprocess.run(substituted, shell=True, capture_output=True,
+                              text=True, encoding="utf-8", errors="replace",
+                              timeout=_RUN_TIMEOUT_S, env=env)
+    except subprocess.TimeoutExpired:
+        return {"ok": False, "reason": f"timeout>{_RUN_TIMEOUT_S}s"}
+    wall_ms = round((time.monotonic() - t0) * 1000)
+    if proc.returncode != 0:
+        return {"ok": False, "reason": f"rc={proc.returncode}",
+                "stderr_tail": proc.stderr[-200:], "wall_ms": wall_ms}
+    try:
+        d = json.loads(proc.stdout)
+    except json.JSONDecodeError:
+        return {"ok": False, "reason": "stdout 非 JSON", "wall_ms": wall_ms,
+                "stdout_head": proc.stdout[:120]}
+    timing = d.get("timing") or {}
+    return {"ok": True, "elapsed_ms": timing.get("elapsed_ms", wall_ms),
+            "count": d.get("count"), "wall_ms": wall_ms}
+
+
+def _sign_test_p(wins: int, losses: int) -> float:
+    """精确二项双尾符号检验（无平局计入 n）。"""
+    n = wins + losses
+    if n == 0:
+        return 1.0
+    k = min(wins, losses)
+    tail = sum(_comb(n, i) for i in range(0, k + 1)) / (2 ** n)
+    return min(1.0, 2 * tail)
+
+
+def _comb(n: int, k: int) -> float:
+    from math import comb
+    return comb(n, k)
+
+
+def evaluate(cmd_a: str, cmd_b: str, query: str, pairs: int, seed: int | None,
+             keep_usage: bool) -> dict:
+    rng = random.Random(seed)
+    per_pair = []
+    for i in range(pairs):
+        a_first = rng.random() < 0.5
+        runs = {}
+        for label in (("a", "b") if a_first else ("b", "a")):
+            cmd = cmd_a if label == "a" else cmd_b
+            runs[label] = _run_once(cmd, query, keep_usage)
+        per_pair.append({"pair": i + 1, "a_first": a_first,
+                         "a": runs["a"], "b": runs["b"]})
+    diffs, a_wins, b_wins, ties = [], 0, 0, 0
+    for r in per_pair:
+        a, b = r["a"], r["b"]
+        if not (a.get("ok") and b.get("ok")):
+            continue  # 失败对不进统计，账面保留
+        d = a["elapsed_ms"] - b["elapsed_ms"]
+        diffs.append(d)
+        if d < 0:
+            a_wins += 1
+        elif d > 0:
+            b_wins += 1
+        else:
+            ties += 1
+    counts_a = [r["a"]["count"] for r in per_pair
+                if r["a"].get("ok") and r["a"].get("count") is not None]
+    counts_b = [r["b"]["count"] for r in per_pair
+                if r["b"].get("ok") and r["b"].get("count") is not None]
+    elapsed_a = [r["a"]["elapsed_ms"] for r in per_pair
+                 if r["a"].get("ok") and r["a"].get("elapsed_ms") is not None]
+    elapsed_b = [r["b"]["elapsed_ms"] for r in per_pair
+                 if r["b"].get("ok") and r["b"].get("elapsed_ms") is not None]
+    verdict = tail_verdict(elapsed_a, elapsed_b)
+    stats = {
+        "valid_pairs": len(diffs),
+        "failed_pairs": pairs - len(diffs),
+        "median_diff_ms": statistics.median(diffs) if diffs else None,
+        "mean_diff_ms": round(statistics.fmean(diffs), 1) if diffs else None,
+        "a_wins": a_wins, "b_wins": b_wins, "ties": ties,
+        "sign_test_p": round(_sign_test_p(a_wins, b_wins), 4),
+        "count_median_a": statistics.median(counts_a) if counts_a else None,
+        "count_median_b": statistics.median(counts_b) if counts_b else None,
+        "p90_a_ms": verdict["p90_a_ms"], "p90_b_ms": verdict["p90_b_ms"],
+        "p90_ratio": verdict["p90_ratio"],
+        "max_a_ms": verdict["max_a_ms"], "max_b_ms": verdict["max_b_ms"],
+        "max_ratio": verdict["max_ratio"],
+        # 尾判据与中位判据并列给出：两者结论不一致时以 tail_verdict 为准
+        # （中位不动的改动同样可能把 p90/max 拉爆）。
+        "tail_verdict": verdict,
+    }
+    return {"query": query, "pairs": pairs, "seed": seed,
+            "order": "逐对随机（a_first 字段记录当对顺序）",
+            "per_pair": per_pair, "stats": stats}
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(description="交错 A/B 实测（随机化逐对顺序）")
+    ap.add_argument("--cmd-a", required=True, help="A 变体命令，含 {query} 占位")
+    ap.add_argument("--cmd-b", required=True, help="B 变体命令，含 {query} 占位")
+    ap.add_argument("--query", required=True)
+    ap.add_argument("--pairs", type=int, default=10)
+    ap.add_argument("--seed", type=int, default=None,
+                    help="固定种子可复现当轮运行序")
+    ap.add_argument("--usage-log", action="store_true",
+                    help="子进程查询写入生产使用账本（默认不写）")
+    args = ap.parse_args(argv)
+    report = evaluate(args.cmd_a, args.cmd_b, args.query, args.pairs,
+                      args.seed, args.usage_log)
+    print(json.dumps(report, ensure_ascii=False))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())