argo-search 1.0.1 → 2.9.7

package/scripts/article.py

@@ -0,0 +1,136 @@
+#!/usr/bin/env python3
+"""article.py — 微信公众号文章全文抓取。
+
+用法: argo article <url> [--json]
+      argo article <url> --json > article.json
+
+绕过 robots.txt 限制：公众号 robots 禁爬，但文章页对真实浏览器开放，
+用手机 UA 直连（curl/urllib 不遵守 robots），解析 js_content 提取正文。
+
+输出: 标题 / 作者 / 发布时间 / 正文纯文本 / 图片 URL 列表
+"""
+import argparse, json, re, sys, html as htmllib, urllib.request
+from cli_io import dumps
+
+UA = ("Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) "
+      "AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1")
+
+HEADERS = {
+    "User-Agent": UA,
+    "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
+    "Accept-Language": "zh-CN,zh;q=0.9,en;q=0.8",
+    "Referer": "https://mp.weixin.qq.com/",
+}
+
+
+def fetch(url: str, timeout: int = 30) -> str:
+    req = urllib.request.Request(url, headers=HEADERS)
+    # 起点域名白名单挡不住服务端 302：重定向的每一跳都要过 SSRF 校验
+    # （http/https scheme + 非本机/内网目标），被拒即抛错而非跟随
+    opener = urllib.request.build_opener(_SafeRedirectHandler)
+    with opener.open(req, timeout=timeout) as r:
+        return r.read().decode("utf-8", errors="ignore")
+
+
+class _SafeRedirectHandler(urllib.request.HTTPRedirectHandler):
+    """每跳重定向目标过 url_safety.check_url，拦截内网/非 http(s) 目标。"""
+
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        from url_safety import check_url
+        ok, reason = check_url(newurl)
+        if not ok:
+            raise ValueError(f"重定向目标被 SSRF 防护拦截（{reason}）: {newurl}")
+        return super().redirect_request(req, fp, code, msg, headers, newurl)
+
+
+def strip_tags(s: str) -> str:
+    s = re.sub(r"<script[\s\S]*?</script>|<style[\s\S]*?</style>", "", s)
+    s = re.sub(r"<br\s*/?>", "\n", s)
+    s = re.sub(r"</(p|div|section|h\d|li|tr|blockquote)>", "\n", s)
+    s = re.sub(r"<[^>]+>", "", s)
+    s = htmllib.unescape(s)
+    lines = [l.strip() for l in s.split("\n")]
+    return "\n".join(l for l in lines if l)
+
+
+def fetch_article(url: str, timeout: int = 30) -> dict:
+    """抓取并解析公众号文章，返回结构化 dict（CLI 与 MCP 共用主链）。
+
+    URL 非 mp.weixin.qq.com 时抛 ValueError（CLI 走 stderr 退出，
+    MCP 转 isError）；抓取失败/反爬拦截返回 {"ok": False, "error": ...}。
+    """
+    if not re.match(r"https?://mp\.weixin\.qq\.com/", url):
+        raise ValueError("仅支持 mp.weixin.qq.com 链接")
+
+    try:
+        raw = fetch(url, timeout)
+    except Exception as e:
+        return {"ok": False, "error": f"抓取失败: {e}"}
+
+    if "js_content" not in raw and "环境异常" in raw:
+        return {"ok": False, "error": "微信反爬拦截（环境异常），请稍后重试"}
+
+    def grab(pattern, default=""):
+        m = re.search(pattern, raw)
+        return m.group(1).strip() if m else default
+
+    title = grab(r'<meta property="og:title" content="([^"]+)"') or \
+        grab(r'<h1[^>]*class="rich_media_title"[^>]*>([\s\S]*?)</h1>')
+    author = grab(r'<meta property="og:article:author" content="([^"]+)"') or \
+        grab(r'id="js_name"[^>]*>([^<]+)<')
+    pubtime = grab(r'id="publish_time"[^>]*>([^<]+)<')
+
+    m = re.search(r'id="js_content"[^>]*>([\s\S]*?)</div>\s*<script', raw)
+    if not m:
+        m = re.search(r'id="js_content"[^>]*>([\s\S]*?)</div>', raw)
+    body_html = m.group(1) if m else ""
+
+    text = strip_tags(body_html)
+    imgs = re.findall(r'data-src="(https://mmbiz\.qpic\.cn/[^"]+)"', body_html)
+    if not imgs:
+        imgs = re.findall(r'src="(https://mmbiz\.qpic\.cn/[^"]+)"', body_html)
+
+    return {
+        "ok": True,
+        "url": url,
+        "title": title,
+        "author": author,
+        "publish_time": pubtime,
+        "char_count": len(text),
+        "image_count": len(imgs),
+        "images": imgs,
+        "content": text,
+    }
+
+
+def main():
+    ap = argparse.ArgumentParser(description="微信公众号文章全文抓取")
+    ap.add_argument("url", help="mp.weixin.qq.com 文章链接")
+    ap.add_argument("--json", action="store_true", help="输出 JSON")
+    args = ap.parse_args()
+
+    try:
+        out = fetch_article(args.url)
+    except ValueError as e:
+        print(str(e), file=sys.stderr)
+        sys.exit(1)
+    if not out["ok"]:
+        print(dumps(out))
+        sys.exit(1)
+
+    if args.json:
+        print(dumps(out))
+    else:
+        print(f"标题: {out['title']}")
+        print(f"作者: {out['author']}  时间: {out['publish_time']}  "
+              f"正文 {out['char_count']} 字 / {out['image_count']} 图")
+        print("---")
+        print(out["content"])
+        if out["images"]:
+            print("---")
+            for i, u in enumerate(out["images"], 1):
+                print(f"[图{i}] {u}")
+
+
+if __name__ == "__main__":
+    main()

package/scripts/arxiv_source.py

@@ -0,0 +1,201 @@
+"""arXiv 源码包（e-print）获取与安全解包 — 论文 LaTeX 精读的取数层。
+
+P1 论文深读三能力之一（2026-09-30 P0 实测后立项）：外部论文工具的
+get_paper_latex 实测 3.4s 拿到 main tex + 源文件清单，argo 此前无此能力。
+
+安全边界（全部内存态，不落盘解包）：
+  1. 只认 arxiv.org 的 https URL（scheme + 域名白名单，拒环回/私有地址）
+  2. 下载总量封顶（默认 64MB），成员数封顶（500），单文件解压封顶（2MB）
+  3. tar 成员名拒绝绝对路径 / 路径穿越 / 盘符——本模块只读内存，永不写文件
+  4. 只收 .tex/.bbl 文本（其余成员只列名不收内容）
+
+缓存：走 fetch 缓存（同 id 1h 内二读零成本），与 pdf 提取缓存同一纪律。
+"""
+from __future__ import annotations
+
+import gzip
+import io
+import tarfile
+from typing import Any
+
+from net_proxy import open_url
+from pdf_extract import CONTENT_WARNING, chunk_text
+
+# 域名白名单（e-print 只在 arxiv.org 主站）
+_ALLOWED_HOSTS = {"arxiv.org", "www.arxiv.org", "export.arxiv.org"}
+_MAX_DOWNLOAD = 64 * 1024 * 1024        # 压缩包下载上限
+_MAX_MEMBERS = 500                       # 成员数上限
+_MAX_TOTAL_UNCOMPRESSED = 64 * 1024 * 1024  # 解压总量上限
+_MAX_FILE_UNCOMPRESSED = 2 * 1024 * 1024    # 单文件解压上限（.tex/.bbl）
+_MAX_CACHE_TEXTS = 2 * 1024 * 1024       # 进缓存的文本总量上限（超出只存清单）
+_TEX_EXTS = (".tex", ".bbl")
+_DOCUMENTCLASS_RE = None  # 惰性编译（见 _is_main_candidate）
+
+
+class EprintError(Exception):
+    """e-print 取数/解包失败（消息可直接进用户输出）。"""
+
+
+def _is_main_candidate(name: str, text: str) -> bool:
+    global _DOCUMENTCLASS_RE
+    if _DOCUMENTCLASS_RE is None:
+        import re
+        _DOCUMENTCLASS_RE = re.compile(r"\\documentclass")
+    return _DOCUMENTCLASS_RE.search(text) is not None
+
+
+def _validate_url(url: str) -> None:
+    """仅允许白名单域名的 http(s) URL（拒环回/私有/保留地址）。"""
+    from urllib.parse import urlparse
+    p = urlparse(url)
+    if p.scheme not in ("http", "https"):
+        raise EprintError(f"仅允许 http(s) URL：{url[:80]}")
+    host = (p.hostname or "").lower()
+    if host not in _ALLOWED_HOSTS:
+        raise EprintError(f"域名不在白名单（{'/'.join(sorted(_ALLOWED_HOSTS))}）：{host}")
+
+
+def _safe_name(name: str) -> bool:
+    """tar 成员名安全判定：拒绝对路径/盘符/穿越（只读内存态，防御性双保险）。"""
+    if not name or name.startswith(("/", "\\")):
+        return False
+    if ":" in name.split("/")[0]:  # C:\ 盘符形态
+        return False
+    parts = name.replace("\\", "/").split("/")
+    return ".." not in parts
+
+
+def _pick_main(texts: dict[str, str]) -> str | None:
+    """主 tex：含 \\documentclass 的最大文件；没有则最大的 .tex。"""
+    candidates = [n for n in texts if n.endswith(".tex")]
+    if not candidates:
+        return None
+    doc_class = [n for n in candidates if _is_main_candidate(n, texts[n])]
+    pool = doc_class or candidates
+    return max(pool, key=lambda n: len(texts[n]))
+
+
+def parse_eprint(body: bytes, *, max_members: int = _MAX_MEMBERS,
+                 max_total: int = _MAX_TOTAL_UNCOMPRESSED,
+                 max_file: int = _MAX_FILE_UNCOMPRESSED) -> dict[str, Any]:
+    """解析 e-print 字节流（tar.gz / 单文件 gzip / 纯 tex），全内存态。
+
+    返回 {format, files:[{name,size}], texts:{name:content}, rejected:[...]}，
+    非 LaTeX 源包（如误传 PDF）抛 EprintError。
+    """
+    if body[:5] == b"%PDF-":
+        raise EprintError("这是 PDF 不是 LaTeX 源包（e-print 端点才返回源码）")
+    tf = None
+    try:
+        try:
+            tf = tarfile.open(fileobj=io.BytesIO(body), mode="r:*")
+            members = [(m.name, m.size, tf.extractfile(m)) for m in tf.getmembers()]
+            fmt = "tar"
+        except tarfile.ReadError:
+            if body[:2] == b"\x1f\x8b":  # 单文件 gzip（老论文常见：单个 .tex.gz）
+                text = gzip.decompress(body).decode("utf-8", errors="replace")
+                name = "main.tex"
+                return {"format": "gz", "main_file": name,
+                        "files": [{"name": name, "size": len(text)}],
+                        "texts": {name: text}, "rejected": []}
+            text = body.decode("utf-8", errors="replace")
+            return {"format": "plain", "main_file": "main.tex",
+                    "files": [{"name": "main.tex", "size": len(text)}],
+                    "texts": {"main.tex": text}, "rejected": []}
+    except EprintError:
+        raise
+    except Exception as e:
+        raise EprintError(f"源码包解析失败: {str(e)[:120]}")
+
+    files: list[dict[str, Any]] = []
+    texts: dict[str, str] = {}
+    rejected: list[str] = []
+    total = 0
+    if len(members) > max_members:
+        raise EprintError(f"成员数 {len(members)} 超上限 {max_members}，疑似恶意包")
+    for raw_name, size, fh in members:
+        if not _safe_name(raw_name):
+            rejected.append(raw_name)
+            continue
+        if size > max_file:
+            rejected.append(f"{raw_name}（单文件 {size} 超上限）")
+            continue
+        total += size
+        if total > max_total:
+            raise EprintError(f"解压总量超上限 {max_total // (1024 * 1024)}MB")
+        if not raw_name.lower().endswith(_TEX_EXTS) or fh is None:
+            files.append({"name": raw_name, "size": size})
+            continue
+        data = fh.read(max_file + 1)
+        if len(data) > max_file:
+            rejected.append(f"{raw_name}（解压超限）")
+            continue
+        text = data.decode("utf-8", errors="replace")
+        files.append({"name": raw_name, "size": size})
+        texts[raw_name] = text
+    main = _pick_main(texts)
+    return {"format": fmt, "files": files, "texts": texts,
+            "main_file": main, "rejected": rejected}
+
+
+def fetch_eprint(arxiv_id: str, use_cache: bool = True) -> dict[str, Any]:
+    """拉取并解析 arXiv 源码包；带 fetch 缓存（1h 内二读零成本）。
+
+    返回 parse_eprint 结果 + {"content_warning": ...}；texts 总量超缓存上限时
+    只缓存清单并置 texts_omitted（本次调用仍返回全文）。
+    """
+    aid = arxiv_id.strip()
+    if not aid or any(c.isspace() for c in aid):
+        raise EprintError(f"arXiv id 形态不对：{aid[:40]}")
+    url = f"https://arxiv.org/e-print/{aid}"
+    _validate_url(url)
+
+    cache = None
+    cache_key = f"arxiv-eprint:{aid}"
+    if use_cache:
+        try:
+            from cache import SearchCache
+            cache = SearchCache()
+            hit = cache.get_fetch(cache_key)
+            if isinstance(hit, dict) and hit.get("files"):
+                hit["_cached"] = True
+                return hit
+        except Exception:
+            cache = None
+
+    with open_url(url, timeout=60) as resp:
+        body = resp.read(_MAX_DOWNLOAD + 1)
+    if len(body) > _MAX_DOWNLOAD:
+        raise EprintError(f"源码包超过下载上限 {_MAX_DOWNLOAD // (1024 * 1024)}MB")
+
+    result = parse_eprint(body)
+    result["arxiv_id"] = aid
+    result["content_warning"] = CONTENT_WARNING
+    if cache is not None:
+        try:
+            payload = {k: v for k, v in result.items() if k != "_cached"}
+            if sum(len(t) for t in payload.get("texts", {}).values()) > _MAX_CACHE_TEXTS:
+                payload["texts"] = {}
+                payload["texts_omitted"] = True
+            cache.set_fetch(cache_key, payload)
+        except Exception:
+            pass  # 缓存写失败不影响本次结果
+    return result
+
+
+def latex_read(source: dict[str, Any], file: str | None = None,
+               start: int = 0, max_chars: int | None = None) -> dict[str, Any]:
+    """从已解析的源码包按文件分页读取（默认主 tex）；chunk 契约与 pdf 相同。"""
+    texts = source.get("texts") or {}
+    name = file or source.get("main_file")
+    if not name:
+        raise EprintError("源码包内没有可读的 .tex 文件")
+    if name not in texts:
+        if source.get("texts_omitted"):
+            raise EprintError("该源码包文本未入缓存（体积超限），请重新拉取")
+        available = ", ".join(sorted(texts))[:200] or "（无 .tex 成员）"
+        raise EprintError(f"文件 {name} 不在源码包内。可用：{available}")
+    seg = chunk_text(texts[name], start, max_chars or 12000)
+    return {"content_warning": CONTENT_WARNING, "file": name,
+            "main_file": source.get("main_file"), "source_format": source.get("format"),
+            **seg}

package/scripts/badcase_ledger.py

@@ -0,0 +1,252 @@
+#!/usr/bin/env python3
+"""badcase_ledger — 坏例账本：把分散三处的失败统一入账、可查、可做发布门禁。
+
+定位（2026-10-11 方案丙）：argo 的失败证据分散在三处、形态各异——
+  1. usage_log/query.jsonl：errors[] 非空或 count=0 的真实查询（含 serp_guard
+     整页误杀外露，见 search.py drain 处）；
+  2. usage_log/recovery.jsonl：触发过恢复链的查询（triggered=true）；
+  3. circuit_breaker.json：state != closed 的引擎（点状快照，引擎级坏例）。
+本工具把它们归一进 SQLite 账本（<state>/badcase.db），支持 ingest（幂等去重）、
+list、stats 与 check（发布前门禁：近 N 天新增坏例超阈值即非零退出）。
+
+与 replay_eval.py 的分工：replay_eval 用录制重放整条管线评打分质量（离线
+仲裁）；本账本只收纳「真实发生的失败」并让它们可归因、可回归——对应评测
+体系的 badcase 管理环节：发现 → 入账 → 归因 → 修复后 check 不复发。
+
+数据卫生：engines_used 含表外引擎名（夹具/拼写错）的记录不入账——账本只收
+真实坏例，与 usage_log_clean 的隔离口径同源（engines.available_engines）。
+
+用法：
+  python3 scripts/badcase_ledger.py ingest            # 三源归一入账（幂等）
+  python3 scripts/badcase_ledger.py list --kind query_error --limit 10
+  python3 scripts/badcase_ledger.py stats             # 按 kind/引擎聚合
+  python3 scripts/badcase_ledger.py check --since 7d --max 50   # 发布门禁
+"""
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import sqlite3
+import sys
+from collections import Counter
+from datetime import datetime, timedelta
+from pathlib import Path
+from typing import Any
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+import argo_paths  # noqa: E402
+from engines import available_engines  # noqa: E402
+from usage_log import usage_log_dir  # noqa: E402
+
+_CANON = frozenset(available_engines())
+
+_SCHEMA = (
+    "CREATE TABLE IF NOT EXISTS badcases ("
+    " id INTEGER PRIMARY KEY,"
+    " kind TEXT NOT NULL,"        # query_error | empty_result | recovery | breaker
+    " ts TEXT NOT NULL,"          # 原始 ISO 时间串；breaker 快照用入账时刻
+    " query TEXT NOT NULL DEFAULT '',"
+    " engine TEXT NOT NULL DEFAULT '',"
+    " detail TEXT NOT NULL DEFAULT '',"
+    " fingerprint TEXT NOT NULL UNIQUE)"
+)
+
+
+def db_path() -> Path:
+    return argo_paths.state_path("badcase.db")
+
+
+def _connect() -> sqlite3.Connection:
+    con = sqlite3.connect(str(db_path()), timeout=8)
+    con.execute(_SCHEMA)
+    return con
+
+
+def _rows_from_query_log(path: Path) -> list[dict[str, Any]]:
+    if not path.exists():
+        return []
+    out = []
+    for line in path.read_text(encoding="utf-8").splitlines():
+        if not line.strip():
+            continue
+        try:
+            r = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        raw_used = r.get("engines_used") or []
+        used = [e for e in raw_used if e in _CANON]
+        if not used and raw_used:
+            continue  # 表外名占满 → 夹具行，不入账（口径同 usage_log_clean）
+        raw_errors = r.get("errors")
+        # 生产日志里 errors 有两种形态：字符串列表（主流）与 int 计数（部分
+        # 旧条目）——统一成字符串列表再取前几条
+        errors = (raw_errors if isinstance(raw_errors, list)
+                  else ([str(raw_errors)] if raw_errors else []))
+        if not errors and r.get("count"):
+            continue  # 正常条目不是坏例
+        if errors:
+            out.append({"kind": "query_error", "ts": r.get("ts", ""),
+                        "query": r.get("query", ""),
+                        "engine": ",".join(used[:3]),
+                        "detail": " | ".join(str(e)[:160] for e in errors[:3])})
+        else:
+            out.append({"kind": "empty_result", "ts": r.get("ts", ""),
+                        "query": r.get("query", ""),
+                        "engine": ",".join(used[:3]),
+                        "detail": f"count=0, mode={r.get('mode')}"})
+    return out
+
+
+def _rows_from_recovery_log(path: Path) -> list[dict[str, Any]]:
+    if not path.exists():
+        return []
+    out = []
+    for line in path.read_text(encoding="utf-8").splitlines():
+        if not line.strip():
+            continue
+        try:
+            r = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        if not r.get("triggered"):
+            continue
+        out.append({"kind": "recovery", "ts": r.get("ts", ""),
+                    "query": r.get("query", ""),
+                    "engine": "",
+                    "detail": (f"level={r.get('level_used')} "
+                               f"strategy={r.get('strategy_used')} "
+                               f"recovered={r.get('recovered')}")})
+    return out
+
+
+def _rows_from_breaker(path: Path) -> list[dict[str, Any]]:
+    if not path.exists():
+        return []
+    try:
+        engines = json.loads(path.read_text(encoding="utf-8")).get("engines", {})
+    except (json.JSONDecodeError, OSError):
+        return []
+    out = []
+    now = datetime.now().astimezone().isoformat(timespec="seconds")
+    for name, st in sorted(engines.items()):
+        if st.get("state") == "closed":
+            continue
+        out.append({"kind": "breaker", "ts": now, "query": "", "engine": name,
+                    "detail": (f"state={st.get('state')} "
+                               f"failures={st.get('failures')} "
+                               f"opens={st.get('opens')}")})
+    return out
+
+
+def ingest() -> dict:
+    log_dir = usage_log_dir()
+    rows = (_rows_from_query_log(log_dir / "query.jsonl")
+            + _rows_from_recovery_log(log_dir / "recovery.jsonl")
+            + _rows_from_breaker(argo_paths.state_path("circuit_breaker.json")))
+    con = _connect()
+    added = 0
+    try:
+        for r in rows:
+            fp = hashlib.sha1("|".join(
+                [str(r["kind"]), str(r["ts"]), str(r["query"]),
+                 str(r["engine"]), str(r["detail"])[:120]])
+                .encode("utf-8")).hexdigest()
+            cur = con.execute(
+                "INSERT OR IGNORE INTO badcases(ts, query, engine, detail,"
+                " kind, fingerprint) VALUES (?,?,?,?,?,?)",
+                (r["ts"], r["query"], r["engine"], r["detail"],
+                 r["kind"], fp))
+            added += cur.rowcount
+        total = con.execute("SELECT COUNT(*) FROM badcases").fetchone()[0]
+        con.commit()
+    finally:
+        con.close()
+    return {"sources": len(rows), "added": added, "total": total,
+            "db": str(db_path())}
+
+
+def _parse_since(since: str) -> datetime:
+    """7d / 24h / 2026-10-01 → datetime（本地时区）。"""
+    since = since.strip().lower()
+    now = datetime.now().astimezone()
+    if since.endswith("d") and since[:-1].isdigit():
+        return now - timedelta(days=int(since[:-1]))
+    if since.endswith("h") and since[:-1].isdigit():
+        return now - timedelta(hours=int(since[:-1]))
+    return datetime.fromisoformat(since).astimezone()
+
+
+def _fetch(kind: str | None, since: datetime | None,
+           limit: int) -> list[dict[str, Any]]:
+    con = _connect()
+    try:
+        sql = ("SELECT ts, kind, query, engine, detail FROM badcases"
+               " WHERE 1=1")
+        params: list = []
+        if kind:
+            sql += " AND kind = ?"
+            params.append(kind)
+        if since is not None:
+            sql += " AND ts >= ?"
+            params.append(since.isoformat(timespec="seconds"))
+        sql += " ORDER BY ts DESC LIMIT ?"
+        params.append(limit)
+        keys = ["ts", "kind", "query", "engine", "detail"]
+        return [dict(zip(keys, row)) for row in con.execute(sql, params)]
+    finally:
+        con.close()
+
+
+def check(since: str, max_new: int) -> dict:
+    rows = _fetch(None, _parse_since(since), limit=10_000)
+    ok = len(rows) <= max_new
+    return {"since": since, "new_badcases": len(rows), "max": max_new,
+            "ok": ok}
+
+
+def stats() -> dict:
+    con = _connect()
+    try:
+        by_kind = dict(con.execute(
+            "SELECT kind, COUNT(*) FROM badcases GROUP BY kind").fetchall())
+        by_engine = dict(con.execute(
+            "SELECT engine, COUNT(*) FROM badcases WHERE engine != ''"
+            " GROUP BY engine ORDER BY COUNT(*) DESC LIMIT 8").fetchall())
+        total = con.execute("SELECT COUNT(*) FROM badcases").fetchone()[0]
+    finally:
+        con.close()
+    return {"total": total, "by_kind": by_kind, "top_engines": by_engine}
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(description="坏例账本（badcase 管理）")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    sub.add_parser("ingest")
+    p_list = sub.add_parser("list")
+    p_list.add_argument("--kind", default=None,
+                        choices=["query_error", "empty_result",
+                                 "recovery", "breaker"])
+    p_list.add_argument("--limit", type=int, default=10)
+    sub.add_parser("stats")
+    p_check = sub.add_parser("check")
+    p_check.add_argument("--since", default="7d")
+    p_check.add_argument("--max", type=int, default=50)
+    args = ap.parse_args(argv)
+    if args.cmd == "ingest":
+        print(json.dumps(ingest(), ensure_ascii=False))
+    elif args.cmd == "list":
+        for row in _fetch(args.kind, None, args.limit):
+            print(json.dumps(row, ensure_ascii=False))
+    elif args.cmd == "stats":
+        print(json.dumps(stats(), ensure_ascii=False))
+    elif args.cmd == "check":
+        report = check(args.since, args.max)
+        print(json.dumps(report, ensure_ascii=False))
+        return 0 if report["ok"] else 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())