argo-search 1.0.1 → 2.9.7

package/bin/argo

@@ -0,0 +1,703 @@
+#!/usr/bin/env python3
+"""argo — unified search CLI. Usage: argo <subcommand> [args...]
+
+本文件**必须保持 Python 3.8+ 可执行**：它是 entrypoint，会先被
+`/usr/bin/env python3` 解释一次（macOS 上就是 3.9），然后才轮到
+`_pick_python()` 去挑符合 MIN_PYTHON 的解释器。因此这里禁止使用
+`X | None` 之类的 3.10+ 语法——它不是注解解析问题，而是在
+函数定义求值期就抛 TypeError，让「选解释器」的兜底逻辑根本没机会执行。
+（历史 bug：`def _engine_count() -> int | None:` 让 `argo --help`
+在系统 python3 下直接崩在 import 阶段。）
+
+这个「entrypoint 必须比目标版本更低」的约束同时说明：本文件自身的语法下限
+（3.8）与受托管脚本的下限（MIN_PYTHON）是两回事，不要合并。
+"""
+
+from __future__ import annotations
+
+import sys, os, json, subprocess, shutil, time
+
+ARGO_HOME = os.path.dirname(os.path.dirname(os.path.realpath(__file__)))
+SCRIPTS = os.path.join(ARGO_HOME, "scripts")
+
+
+# 解释器探测结果缓存。探测必须在子进程里真 import 依赖才敢用，
+# 实测一次约 80–170 ms，而这是**每次** argo 调用都要付的固定成本。缓存命中时
+# 只做一次「版本 + 依赖存在性」的廉价校验（find_spec 不 import，约 15 ms），
+# 用它挡住解释器被删/降级/换版本的情况。
+#
+# 探测的依赖只认 PyYAML（argo 唯一的必需第三方依赖，install.sh 装它）。
+# 此前还要求 requests——那是历史误留下的幽灵依赖：全仓没有任何
+# `import requests`（真实的可选增强是 curl_cffi，TLS 指纹用，缺了只是降级）。
+# 后果是新机器（照 install.sh 装完）里 6 个候选解释器全部探测失败、缓存
+# 永远不命中，每次调用白付一遍探测。
+#
+# 版本判据另有独立的历史 bug，见 MIN_PYTHON 上方说明：真正在选人并写缓存的
+# 那条路径反而没有版本闸门，3.9 会被选中并固化进缓存。
+# 缓存根的平台惯例与 argo_paths 保持一致（bin/argo 是 entrypoint，不 import
+# scripts/ 里的模块以保持零依赖）：Windows 走 LOCALAPPDATA，POSIX 走 XDG。
+def _default_cache_root():
+    if os.name == "nt":
+        base = os.environ.get("LOCALAPPDATA") or os.path.expanduser("~")
+        return os.path.join(base, "unified-search")
+    xdg = os.environ.get("XDG_CACHE_HOME", "").strip()
+    if xdg:
+        return os.path.join(xdg, "unified-search")
+    return os.path.expanduser("~/.cache/unified-search")
+
+
+_PY_CACHE = os.path.join(
+    os.environ.get("ARGO_STATE_DIR", "").strip() or _default_cache_root(),
+    ".argo_python",
+)
+
+# argo 脚本支持的最低 Python 版本。改这里就是改契约，install.sh 与此处必须一致。
+#
+# 为什么是 3.9 而不是 3.10：早期这里写着 3.10，理由是「脚本用了 `X | None` 语法」。
+# 该理由已被实测证伪——全仓 0 处 PEP604 注解，且几乎所有脚本都有
+# `from __future__ import annotations`（注解不求值，3.9 也能解析）。真实的最低
+# 门槛由**语法**决定：逐文件跨解释器 parse 对比后，全仓只剩 job.py 一处越界，
+# 而那处是 PEP 701（3.12+ 的 f-string 内嵌同类引号），已按 3.9 写法改写。
+MIN_PYTHON = (3, 9)
+
+# 两个校验脚本只差「怎么确认 PyYAML 可用」，**版本判据必须完全一致**：
+# 廉价档 find_spec（不 import，约 15 ms），严格档真 import（约 80–170 ms）。
+#
+# 历史 bug（2026-09-16 定位）：早先 strict=True 那条只有 `import yaml`、**没有版本
+# 判据**，而真正负责选人并写缓存的候选链走的正是 strict=True——于是 3.9 通过探测、
+# 被选中、被写进缓存，此后 `argo job` 永久 SyntaxError，同一缓存下其它子命令却照常
+# 运行（静默跑在不支持的解释器上）。根因是把「版本」和「依赖」两个判据拆到了两条
+# 分支上，谁抄漏一个就少一半闸门。现在两个脚本同源生成，只换 yaml 那一段。
+_PY_MIN_VER = ",".join(str(part) for part in MIN_PYTHON)
+_PY_CHEAP_CHECK = (
+    "import sys, importlib.util as u; sys.exit(0 if sys.version_info >= (%s,) "
+    "and u.find_spec('yaml') is not None else 1)" % _PY_MIN_VER
+)
+_PY_STRICT_CHECK = (
+    "import sys; sys.exit(0 if sys.version_info >= (%s,) else 1); import yaml"
+    % _PY_MIN_VER
+)
+
+
+def _probe_python(py, strict: bool) -> bool:
+    """strict=True 真 import 依赖（首次探测）；False 只做廉价存在性校验。
+
+    两条路径都必须查版本（见 _PY_*_CHECK 的说明）：strict 不是「跳过校验」，
+    只是把依赖检查做得更实。少写版本判据会让 3.9 被选中并写进缓存。
+
+    py 既可以是可执行文件路径，也可以是**参数列表**（Windows 官方启动器
+    `py -3` 的形式——它本身不是解释器，要带参数才会选版本）。
+    """
+    code = _PY_STRICT_CHECK if strict else _PY_CHEAP_CHECK
+    argv = [py] if isinstance(py, str) else list(py)
+    if not argv:
+        return False
+    try:
+        r = subprocess.run(argv + ["-c", code], capture_output=True, timeout=10)
+        return r.returncode == 0
+    except Exception:
+        return False
+
+
+def _resolve_launcher(argv: list[str]) -> str:
+    """把「启动器 + 参数」（如 Windows 的 `py -3`）解析成真实解释器绝对路径。
+
+    缓存与 execv 都只认单个绝对路径，所以必须在探测阶段就把启动器展开一次：
+    否则写进缓存的是 `py -3` 这样的组合，`_cached_python` 的 `os.path.isabs`
+    校验会直接判它不可用，缓存永远不命中。
+    """
+    try:
+        r = subprocess.run(argv + ["-c", "import sys; print(sys.executable)"],
+                           capture_output=True, text=True, timeout=10,
+                           encoding="utf-8", errors="replace")
+    except Exception:
+        return ""
+    if r.returncode != 0:
+        return ""
+    lines = [ln.strip() for ln in (r.stdout or "").splitlines() if ln.strip()]
+    p = lines[-1] if lines else ""
+    return p if p and os.path.isabs(p) else ""
+
+
+def _cached_python() -> str:
+    """读缓存的解释器绝对路径；不可用/校验不过返回空串。"""
+    try:
+        with open(_PY_CACHE, "r", encoding="utf-8") as f:
+            p = f.read().strip()
+    except OSError:
+        return ""
+    if p and os.path.isabs(p) and os.access(p, os.X_OK) and _probe_python(p, False):
+        return p
+    return ""
+
+
+def _remember_python(p: str) -> None:
+    """原子写入缓存；失败静默（只读环境下退回每次探测的老行为）。"""
+    try:
+        d = os.path.dirname(_PY_CACHE)
+        if d:
+            os.makedirs(d, exist_ok=True)
+        tmp = "%s.tmp.%d" % (_PY_CACHE, os.getpid())
+        with open(tmp, "w", encoding="utf-8") as f:
+            f.write(p)
+        os.replace(tmp, _PY_CACHE)
+    except OSError:
+        pass
+
+
+def _pick_python() -> str:
+    """选择可用解释器：ARGO_PYTHON 优先，其次高版本 python3.x，兜底当前解释器。
+
+    逐个探测版本并验证 PyYAML 依赖后选第一个可用的（判据见 _PY_*_CHECK）。
+    候选链里的 `sys.executable` 排在具体版本号之后：它可能是 3.9（macOS 系统
+    python3），只有在没有更高版本时才被选中——那时 MIN_PYTHON 仍会兜住，
+    不会静默选一个跑不动的解释器。
+
+    探测结果落盘缓存（见 _PY_CACHE）：命中时不再起子进程 import 依赖。显式
+    指定 ARGO_PYTHON 时不查也不写缓存——用户的覆盖是权威，不该被缓存遮蔽，
+    也不该把它固化下来。
+    """
+    env_py = os.environ.get("ARGO_PYTHON", "").strip()
+    if env_py:
+        p = shutil.which(env_py) if not os.path.isabs(env_py) else env_py
+        if p and _probe_python(p, True):
+            return p
+    else:
+        cached = _cached_python()
+        if cached:
+            return cached
+
+    cands = ["python3.14", "python3.13", "python3.12",
+             "python3.11", "python3.10", sys.executable,
+             # Windows：本机没有 `python3` 这个名字（上游 v2.8.5 的社区贡献已经
+             # 在 node 启动器里按平台分流，这里是 `bin/argo` 自身的对应分支）。
+             # `py` 是官方启动器，`py -3` 取最新 3.x；解析成真实路径后才入库。
+             ["py", "-3"], ["py"], "python3", "python", "python3.exe", "python.exe"]
+    for cand in cands:
+        if isinstance(cand, str):
+            if not cand:
+                continue
+            py = cand if os.path.isabs(cand) else shutil.which(cand)
+        else:
+            launcher = shutil.which(cand[0])
+            py = _resolve_launcher([launcher] + list(cand[1:])) if launcher else ""
+        if not py:
+            continue
+        if _probe_python(py, True):
+            if not env_py:
+                _remember_python(py)
+            return py
+    return sys.executable
+
+
+def _self_capable() -> bool:
+    """当前解释器是否已满足 argo 的运行要求（版本 + 依赖），进程内判定。
+
+    与 _probe_python 的分工：那个要 spawn 一个 python 进程才问出一句话，
+    这个只查 importlib 的 find_spec，零子进程。
+
+    为什么需要它：shebang 是 `#!/usr/bin/env python3`，在装了高版本 python
+    的机器上（如 homebrew 3.14）落到的往往就是 _pick_python 会选中的那个
+    解释器。此时「探测一遍 + execv 重启」纯粹是把同一个解释器再启一次，
+    每次调用白付一次进程启动与一次校验子进程。达标就地执行即可。
+
+    依赖口径与 _PY_CHEAP_CHECK / _probe_python 完全一致：只认 PyYAML 这一个
+    必需第三方依赖。这里曾多要求 requests，但全仓没有任何 `import requests`
+    （它是早已移除的幽灵依赖，可选增强是 curl_cffi）。多要求一个用户机器上
+    不存在的包，会让本函数在「照 install.sh 只装了 pyyaml」的正常环境里恒为
+    False，于是每次调用都被迫重选解释器并 execv 重启——本该省掉的重复启动，
+    在所有终端用户机器上静默失效，只在恰好装了 requests 的开发机上才生效。
+    """
+    # 版本判据必须与 _PY_*_CHECK 同源（MIN_PYTHON）。这里曾写死 (3, 10)，与
+    # 探测门槛各写一份——正是「两处各写版本号、改一处漏一处」那个形态，
+    # 一旦 MIN_PYTHON 调整就会造成「探测放行但原地执行拒绝」的不一致。
+    if sys.version_info[:2] < MIN_PYTHON:
+        return False
+    import importlib.util as _util
+    return _util.find_spec("yaml") is not None
+
+
+def _tree_tag():
+    """本检出目录短指纹（与 scripts/daemon.py._tree_tag 同算法同输入）。
+
+    daemon 的 socket/pid/指针/自启标记按检出目录隔离（踩雷记录见 daemon.py
+    该函数 docstring）：共享状态根下多个 worktree/clone 会互抢 socket、互覆盖
+    pid、互踩自启节流。两边都取 sha1(ARGO_HOME realpath)[:12]；hashlib 在
+    函数内 import，不进 entrypoint 顶层零 import 纪律路径。
+    """
+    import hashlib
+    return hashlib.sha1(ARGO_HOME.encode("utf-8")).hexdigest()[:12]
+
+
+def _daemon_env():
+    """透传给 daemon 的请求级环境变量（ARGO_* 全量 + 常见密钥命名）。
+
+    为什么需要：daemon 启动时同步一次 env 文件，此后按次覆盖
+    （`SERPER_API_KEY=x argo search`、`ARGO_LOCAL_RERANK=0 argo search`）
+    在快路径会被静默忽略——同一条命令冷路径生效、热路径不生效。daemon
+    侧请求结束即还原，不会污染后续请求。
+    """
+    env = {}
+    size = 0
+    for k, v in os.environ.items():
+        if not (k.startswith("ARGO_") or k.endswith(
+                ("_KEY", "_TOKEN", "_SECRET", "_PASSWORD", "_APIKEY"))):
+            continue
+        size += len(k) + len(v)
+        if size > 32768:
+            return {}
+        env[k] = v
+    return env
+
+
+def _clear_autostart_marker(root):
+    """删自启节流 marker。仅 daemon 陈尸场景用（见 _daemon_run ECONNREFUSED 分支）。"""
+    try:
+        os.unlink(os.path.join(root, ".daemon_autostart-" + _tree_tag()))
+    except OSError:
+        pass
+
+
+def _daemon_autostart(root, py):
+    """指针缺失/失效时后台拉起 daemon（fire-and-forget，不拖慢本次调用）。
+
+    2026-10-18 起改为**显式 opt-in**：只有 `ARGO_DAEMON=1` 才后台拉起，
+    `argo daemon start` 手动启动的实例照常服务。理由是本机实测的净收益
+    只有中位 33.5ms/笔（缓存命中 41 vs 75ms，网络查询 1–3s 时无感），
+    却要养 20–27MB 常驻进程、866 行生命周期代码与 bind/stale 竞态。
+    首次调用仍走冷路径，下一笔起享受快路径；失败静默（daemon 是加速器
+    不是依赖）；60s 节流防每次调用都拉一个；ARGO_NO_DAEMON=1 优先关闭。
+    py 必须是 _pick_python/_self_capable 判定的达标解释器（带 PyYAML、版本
+    达标）——用当前解释器盲拉，会在「当前解释器不达标」的机器上起一个跑不动
+    search 的 daemon：它每次 run 都以 exit 1 告终，而客户端对「已执行」的响应
+    不回退（与冷路径 execv 升级解释器的行为不符）。
+    """
+    if os.environ.get("ARGO_DAEMON", "").strip().lower() not in ("1", "true", "yes", "on"):
+        return 1
+    if os.name == "nt":
+        return 1  # Windows 无后台化，别拉（start 在前台阻塞）
+    marker = os.path.join(root, ".daemon_autostart-" + _tree_tag())
+    try:
+        if time.time() - os.stat(marker).st_mtime < 60:
+            return 0
+    except OSError:
+        pass
+    try:
+        devnull = open(os.devnull, "wb")
+        subprocess.Popen(
+            [py or sys.executable, os.path.join(SCRIPTS, "daemon.py"), "start"],
+            stdout=devnull, stderr=devnull, stdin=devnull,
+            start_new_session=True, close_fds=True)
+    except Exception:
+        return 1
+    # 节流 marker 写在 Popen **成功之后**：先写后拉的话，Popen 抛异常时
+    # marker 已落盘，之后 60s 不再尝试拉起（2026-10-17 审查发现 5）。
+    # 拉起风暴由 daemon start 自身的 stub 互斥 + _alive 检查兜底，不靠它。
+    try:
+        d = os.path.dirname(marker)
+        if d:
+            os.makedirs(d, exist_ok=True)
+        with open(marker, "w", encoding="utf-8") as f:
+            f.write(str(int(time.time())))
+    except OSError:
+        pass
+    return 0
+
+
+def _daemon_run(rest, py="") -> bool:
+    """UDS 快路径：daemon 在位时零 import 直达常驻进程执行 search。
+
+    收益来源是消「解释器启动 + engines 全家 import」约 85–100ms/次的固定成本
+    （详见 scripts/daemon.py 模块注释），不是快在语言。任何失败——无指针文件、
+    连不上、响应异常、非 ok、daemon 正忙/源码已变更（busy/stale）——都静默
+    返回 False 走常态路径：daemon 是加速器不是依赖，坏了 CLI 照常能跑，这里
+    绝不打印错误（会污染 agent 的 stdout 契约）。
+
+    ARGO_NO_DAEMON=1 显式关掉；ARGO_DAEMON_TIMEOUT 覆盖客户端等待上限（秒）。
+    指针文件 .daemon_sock-<树指纹> 由 daemon 写在 _default_cache_root() 下（bin 不读
+    yaml、不 import scripts 就能算出的位置），内容是真实 socket 路径——两端
+    状态根解析不一致时退化为快路径永不命中，不会错。
+    """
+    if os.environ.get("ARGO_NO_DAEMON", "").strip().lower() in ("1", "true", "yes"):
+        return False
+    root = os.environ.get("ARGO_STATE_DIR", "").strip() or _default_cache_root()
+    pointer = os.path.join(root, ".daemon_sock-" + _tree_tag())
+    sock = ""
+    try:
+        with open(pointer, encoding="utf-8") as f:
+            sock = f.read().strip()
+    except OSError:
+        _daemon_autostart(root, py)  # 首次调用：本次冷跑，后台把 daemon 拉起来
+        return False
+    if not sock or not os.path.exists(sock):
+        _daemon_autostart(root, py)
+        return False
+    try:
+        tmo = float(os.environ.get("ARGO_DAEMON_TIMEOUT", "").strip() or 120)
+    except ValueError:
+        tmo = 120.0
+    try:
+        import socket
+        req = {"op": "run", "script": "search", "args": rest,
+               "cwd": os.getcwd(), "env": _daemon_env(),
+               # 客户端自己的等待预算随请求下达：daemon 的发送超时以它为准
+               # （服务端的固定值不可能知道用户把 ARGO_DAEMON_TIMEOUT 调到
+               # 多大——硬编码 300s 会在 deep 长查询上复发「响应被丢 → 双跑」）。
+               "send_timeout": tmo + 5}
+        s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+        try:
+            s.settimeout(tmo + 5)
+            s.connect(sock)
+            s.sendall((json.dumps(req) + "\n").encode("utf-8"))
+            buf = b""
+            while not buf.endswith(b"\n"):
+                chunk = s.recv(65536)
+                if not chunk:
+                    break
+                buf += chunk
+        finally:
+            try:
+                s.close()
+            except OSError:
+                pass
+    except Exception as e:
+        # 整段（含 socket 创建）静默回退：契约是「任何失败不打断 search」，
+        # 此前 socket() 在 try 外，创建失败会穿出 main 直接 traceback。
+        # 顺带自愈：daemon 被 kill -9/OOM 后 socket 文件还在、connect 恒
+        # ECONNREFUSED，而清理陈尸只发生在 daemon 自己的 _alive()/start 里，
+        # 客户端从不调用它——不补这一手，快路径会一直失效到有人手跑
+        # `argo daemon start/status/stop`（2026-10-12 审查发现 4）。
+        #
+        # ECONNREFUSED 是「对端明确死亡」的信号（2026-10-17 审查发现 1）：
+        # 此时若 60s 节流 marker 还新鲜，_daemon_autostart 会静默 return——
+        # 既不重拉也不清尸，窗口内每笔 search 反复付 ~2.2s 冷跑。先删
+        # marker 再拉，让这次自愈真正发生；防重复拉起由 daemon start 的
+        # stub 互斥 + _alive 兜底，不会引发拉起风暴。空闲自杀路径无此问题
+        # （daemon 退出时连 marker 一起清，scripts/daemon.py 退役清理段）。
+        if isinstance(e, ConnectionRefusedError):
+            _clear_autostart_marker(root)
+        _daemon_autostart(root, py)
+        return False
+    if not buf:
+        return False
+    try:
+        resp = json.loads(buf.decode("utf-8", "replace"))
+    except ValueError:
+        return False
+    if not resp.get("ok"):
+        if not resp.get("busy"):  # busy=daemon 在跑别的，等它自然空出即可
+            _daemon_autostart(root, py)  # stale/异常：daemon 已退役或不在位，拉新的
+        return False
+    out = resp.get("stdout") or ""
+    err = resp.get("stderr") or ""
+    if out:
+        sys.stdout.write(out)
+        sys.stdout.flush()
+    if err:
+        sys.stderr.write(err)
+        sys.stderr.flush()
+    sys.exit(int(resp.get("exit_code") or 0))
+
+
+def _engine_count():
+    """收录的引擎数（config.yaml + engines/specs/*.yaml 合并口径，单一真源）。
+
+    只报「收录数」这个便宜且不随环境变的数：以前这里报的是「启用数」，
+    既与文档里的收录数对不上，配置不可读时还回退到一个写死的旧值（87），
+    用户看到的是个假数字。真读不出来就不显示数量，别编。
+
+    快路径：读 `state_root/.engine_count`（`<count>\\n<config.yaml mtime_ns>`），
+    mtime 匹配 → 直接返回（~2ms）；冷启动或 config.yaml 变更 → fallback
+    到完整 load_config()（~30ms）并回填。这样 --help 稳态下省 ~28ms，
+    且不会重蹈「写死 87」的假数字覆辙——缓存键含 config.yaml mtime，
+    config 一变就会走完整解析刷新。
+    """
+    try:
+        state_root = (os.environ.get("ARGO_STATE_DIR", "").strip()
+                      or os.path.expanduser("~/.cache/unified-search"))
+        cfg_path = os.path.join(ARGO_HOME, "config.yaml")
+        cache_file = os.path.join(state_root, ".engine_count")
+        try:
+            cfg_mtime = str(os.stat(cfg_path).st_mtime_ns)
+        except OSError:
+            cfg_mtime = None
+        if cfg_mtime:
+            try:
+                with open(cache_file, encoding="utf-8") as f:
+                    cached_count, cached_mtime = f.read().split("\n", 1)
+                if cached_mtime.strip() == cfg_mtime:
+                    return int(cached_count) or None
+            except (OSError, ValueError):
+                pass  # 冷启动 / 缓存损坏 → 走完整解析并回填
+        sys.path.insert(0, SCRIPTS)
+        from config import load_config
+        engines = load_config().get("engines") or {}
+        n = len([k for k, v in engines.items() if isinstance(v, dict)]) or None
+        if n and cfg_mtime:
+            try:
+                os.makedirs(state_root, exist_ok=True)
+                tmp = f"{cache_file}.tmp.{os.getpid()}"
+                with open(tmp, "w", encoding="utf-8") as f:
+                    f.write(f"{n}\n{cfg_mtime}")
+                os.replace(tmp, cache_file)  # 原子写：与 argo_paths.atomic_write_* 同构
+            except OSError:
+                pass  # 只读环境等：不阻断，下次仍走完整解析
+        return n
+    except Exception:
+        return None
+
+
+def _version():
+    """版本号：唯一真源是 package.json（本文件不存副本，防再添一处漂移点）。
+
+    此前 `argo --version` 落进「Unknown subcommand」——连「报版本」这个最
+    基础的环境探针都没有。只在本分支读 package.json（一次性小文件），不碰
+    scripts/ 里的重模块。
+    """
+    try:
+        import json
+        with open(os.path.join(ARGO_HOME, "package.json"), encoding="utf-8") as f:
+            return "argo " + str(json.load(f).get("version") or "unknown")
+    except Exception:
+        return "argo unknown（package.json 不可读）"
+
+
+def _usage() -> str:
+    n = _engine_count()
+    head = f"{n} 个源" if n else "多源"
+    # 花括号在 f-string 里是替换字段语法：字面量花括号必须写成 {{ }}，
+    # 漏写会抛 NameError（{status|inject|undo} 曾让 --help 直接崩溃）。
+    return f"""argo — 统一搜索与证据核验 CLI（收录 {head}）
+
+Usage:
+  argo search    "query"          统一搜索（{head}，TF-IDF路由+RRF融合）
+  argo research  "query"          深度研究（问题分解→多源采集→综合报告）
+  argo evidence  "query"          可信度评估（自动搜索 → 评分，或 pipe 搜索结果）
+  argo clarify   "query"          意图消歧（歧义检测+意图分类+路由建议）
+  argo fetch     "url"            抓取单页正文（多级降级：HTTP 内容协商→md 变体回探→TLS 指纹→jina→Parallel→浏览器；--full 读全文存档）
+  argo crawl     "url"            站点爬取（sitemap/BFS，多页抓取）
+  argo extract   "url"            结构化提取（表格/Meta/JSON-LD）
+  argo article   "url"            微信公众号文章全文抓取（标题/正文/图片）
+  argo wx        "url"            微信文章多级降级抓取（HTTP→CDP→搜狗；推荐）
+  argo screenshot "url"           网页截图（--full-page 整页 / --output 指定路径）
+  argo auth      {{login|status|logout}}  浏览器登录态（自持持久 profile；登录一次抓取带会话）
+  argo pdf       "url"            PDF 正文提取（--pages 1-5 / --password 口令）
+  argo paper     "arxiv-id"       论文深读（--outline/--section/--latex/--cited-by）
+  argo tweet     "<url|id>"       X 帖子完整打包（正文+串/引用/转发+媒体；--out 落盘）
+  argo x-search  "query"          X 关键词搜索（原生布尔语法 from:/-is:retweet/lang:；ego-browser 通道）
+  argo template  {{--list|<id>}}  查询模板（命名检索模式，展开并执行；--add 追加词）
+  argo answer    "query"          直答（Seltz 带引用合成答案，置信口径=引用计数）
+  argo watch     {{add|check|list|remove}}  观察模式（网页快照与变化检测，cron 可用）
+  argo job       "query"          招聘岗位多平台聚合（BOSS/猎聘/智联/前程无忧/597/今日招聘）
+  argo preflight "url1 url2 ..."  批量 URL 预检（登录墙/已死/已归档分类，--probe 联网探测）
+  argo cite "doi" [doi...]         DOI → 引用条目（GB/T 7714/顺序编码/APA/BibTeX，--style 可选）
+  argo local-image index [目录...]  本地图片建库（Vision；默认关，需 ARGO_LOCAL_IMAGE=1）
+  argo local-image search "词"      搜本地图片（--similar-to 给图找相似；--sheet 出联络表）
+  argo local-image stats            索引概况
+  argo mcp       {{status|inject|undo}}   多客户端 MCP 一键注入/诊断/还原
+  argo paths [--check] [--migrate]     路径自省 / 本机自检 / 搬历史状态到惯例目录
+  argo daemon    {{start|status|stop}}   常驻进程（search 自动走 UDS 快路径，消每次 ~85ms 启动+import；ARGO_NO_DAEMON=1 关）
+  argo stats [-n N]                    使用日志与反馈状态（本地使用日志只读出口）
+
+Common flags: --json --mode {{fast|auto|deep|budget}} --max-results N --depth {{fast|balanced|deep}}
+
+本机此刻可用几个源：argo search --list-engines --routable-only
+逐源费用/密钥/状态：docs/ENGINE_CATALOG.md
+"""
+
+def _pin_stdio():
+    """把本进程 stdout/stderr 的编码钉住（实现只有一处：cli_io.ensure_utf8_stdio）。
+
+    为什么在入口而不是模块 import 期：本文件先被系统 `python3` 解释一次、
+    再按需换解释器，**import 期不碰仓库内模块**是既有纪律（见文件头），
+    所以这层薄封装只负责「按需导入 + 兜异常」，判据与实现都留在 cli_io。
+
+    为什么必须最早调用：非 UTF-8 控制台（Windows 老终端）或显式
+    `PYTHONIOENCODING=ascii` 下，连 `argo --help` 的中文 usage 都会
+    UnicodeEncodeError——它在选解释器之前就发生了。
+    """
+    try:
+        sys.path.insert(0, SCRIPTS)
+        from cli_io import ensure_utf8_stdio
+        ensure_utf8_stdio()
+    except Exception:
+        # 纯加固：拿不到实现就按原样跑，不影响任何子命令
+        pass
+
+
+def main():
+    _pin_stdio()
+    if len(sys.argv) < 2 or sys.argv[1] in ("-h", "--help", "help"):
+        print(_usage())
+        # 帮助不是错误：--help/help 正常退出（0），无参数调用才是用法错误（1）
+        sys.exit(0 if len(sys.argv) >= 2 else 1)
+
+    if sys.argv[1] in ("--version", "-v", "version"):
+        print(_version())
+        sys.exit(0)
+
+    sub = sys.argv[1]
+    rest = sys.argv[2:]
+
+    # env 文件 → os.environ 同步（只填缺失，不覆盖已有值）：子进程按标准
+    # os.environ 直读密钥（读取方零改动，含其他 AGT 既有集成），未经
+    # mcp_launch.sh 注入的裸 shell 也能拿到。
+    #
+    # **必须在选解释器之前**：`_pick_python` 认的权威覆盖就是 ARGO_PYTHON，
+    # 而它读的是 os.environ——同步排在后面，用户照文档把 ARGO_PYTHON 写进
+    # `~/.config/argo/env` 就等于没写。`mcp_launch.sh` 是「先 source 再探测」
+    # （line 32 早于 line 67），两个启动器对同一个文件给出不同答案，正是本仓
+    # 反复踩过的「装了没通电」。这个变量只在「当前解释器不够用」时才被读到，
+    # 而那恰恰是用户会去写它的情形。
+    try:
+        sys.path.insert(0, SCRIPTS)
+        from engine_env import sync_envfile_to_environ
+        sync_envfile_to_environ()
+    except Exception:
+        pass
+
+    # 达标就地执行；否则按 _pick_python 选解释器并 execv 重启。
+    # 判定前置于探测：达标时连 _pick_python 的子进程校验都省掉。
+    inplace = _self_capable()
+    py = sys.executable if inplace else _pick_python()
+
+    scripts = {
+        "search":    ("search.py",     ["--json"]),
+        "research":  ("research.py",   ["--json"]),
+        "evidence":  ("evidence.py",   ["--stdin", "--json"]),
+        "clarify":   ("clarify.py",    ["--json"]),
+        # fetch 对应 MCP 的 argo_fetch（正文抓取）：CLI 与 MCP 工具面保持一一对应，
+        # 少一个入口就意味着该能力只能靠 MCP（默认关）或 --engine 绕路才够得着。
+        "fetch":     ("fetch_v3.py",   []),
+        "crawl":     ("crawl.py",      []),
+        "extract":   ("extract.py",    []),
+        "article":   ("article.py",    ["--json"]),
+        # wx：微信文章多级降级（HTTP→CDP→搜狗），article 的升级版
+        "wx":        ("wechat_article.py", ["--json"]),
+        # screenshot/pdf 对应 MCP 的 argo_screenshot / argo_pdf：CLI 与 MCP 工具面
+        # 保持一一对应，少一个入口就意味着该能力只能靠 MCP（默认关）够得着
+        "screenshot": ("screenshot.py", []),
+        "pdf":        ("pdf_extract.py", []),
+        "paper":      ("paper.py",      []),
+        # tweet：X 帖子完整打包（搜索用 argo search；这里是「给定链接吸收整份内容」）。
+        # 与 paper/article 同类：站点专用结构化提取各占一个子命令，不进搜索契约。
+        "tweet":      ("tweet.py",      []),
+        # answer/watch：MCP 工具面 2026-09-26 补齐（argo_answer/argo_watch），
+        # CLI 与 MCP 能力面自此一一对应
+        "answer":    ("answer.py",    ["--json"]),
+        "watch":     ("watch.py",      []),
+        # auth：浏览器登录态（A2，持久 profile）。login 开可见窗口扫码/登录一次，
+        # 抓取链对已登录站点自动带会话；cookie 由 Chrome 自持加密，argo 不读取。
+        # 不进 MCP 工具面：登录是用户的一次性交互动作，不是模型该调的工具。
+        "auth":      ("browser_auth.py", []),
+        "job":       ("job.py",        []),
+        "preflight": ("batch_probe.py", []),
+        "mcp":       ("mcp_setup.py",  []),
+        # stats：本地使用日志只读出口（日志与反馈的规范化入口，见 references/usage.md）
+        "stats":     ("stats_cli.py",  ["--json"]),
+        # paths：路径自省（状态目录/密钥文件到底解析到了哪里）。支持类问题的
+        # 第一问，且不必进 MCP 工具面（与 answer/watch 同类）。
+        "paths":     ("argo_paths.py", []),
+        # daemon：常驻进程管理（start/status/stop）。search 已自动走 UDS 快路径
+        # （_daemon_run），这里管生命周期；详见 scripts/daemon.py 模块注释。
+        "daemon":    ("daemon.py", []),
+        # cite：DOI → 引用条目（GB/T 7714/APA/BibTeX，Crossref+OpenAlex，免 key）
+        "cite":     ("cite_cli.py",  []),
+        # local-image：本地图片检索（Vision 索引 + 以图找相似 + 联络表）。
+        # 网络图走 `argo search`（image_search 域），本地图走这里——两者是
+        # 「全网找图」与「在自己素材里找图」的分工，不重叠。
+        "local-image": ("local_image.py", []),
+        # x-search：X 原生关键词搜索（ego-browser 通道）。X 布尔语法
+        # （from: / -is:retweet / min_faves: / lang:）只有 x.com/search 本体认，
+        # 通用网页引擎一律忽略——所以要「盯一批官方号 / 按关键词找发布」只能走它。
+        # 站点专用通道，与 tweet（单条打包）互补，不进搜索契约（同 paper/article）。
+        "x-search":  ("x_search.py", []),
+        # template：查询模板（命名检索模式 → 展开并转发给 search / x-search）。
+        # 注册表 references/query-templates.yaml，用户可加 ~/.config/argo/query-templates.yaml。
+        "template":  ("template_cli.py", []),
+    }
+
+    if sub not in scripts:
+        print(f"Unknown subcommand: {sub}", file=sys.stderr)
+        print(_usage(), file=sys.stderr)
+        sys.exit(1)
+
+    script, defaults = scripts[sub]
+    path = os.path.join(SCRIPTS, script)
+
+    # evidence: auto search → evidence pipeline (when no stdin data)
+    # 用法查询（-h/--help）不走这条管道判定：它既没有查询词也没有 stdin，
+    # 会被当成「用错了」报错并 exit 1——查用法却拿到失败码，脚本里
+    # `argo evidence --help || fallback` 会走错分支（2026-09-15 实测）。
+    # 交给通用执行路径，由 evidence.py 自己的 argparse 输出帮助并 exit 0。
+    if sub == "evidence" and not any(a in ("-h", "--help") for a in rest):
+        # 判据必须是 fd 类型而非 isatty()：非交互环境（脚本/CI/cron/agent）的
+        # 空 stdin 也不是 tty，用 isatty 会把「无数据」判成「有数据」，让
+        # `argo evidence "query"` 走进读管道分支后崩在 json.load 上。
+        sys.path.insert(0, SCRIPTS)
+        try:
+            from cli_io import read_stdin_if_piped
+        except ImportError:  # 脚本目录不可导入时按「无管道数据」处理，不猜
+            read_stdin_if_piped = lambda: ""  # type: ignore[assignment]
+        stdin_text = read_stdin_if_piped()
+        query = rest[0] if rest and not rest[0].startswith("-") else ""
+
+        if not stdin_text.strip() and query:
+            # 自动搜索 → 管道 → evidence
+            search_path = os.path.join(SCRIPTS, "search.py")
+            search_cmd = [py, search_path, query, "--json",
+                          "--mode", "fast", "--max-results", "10"]
+            result = subprocess.run(search_cmd, capture_output=True, text=True, timeout=30,
+                                    encoding="utf-8", errors="replace")
+            if result.returncode != 0:
+                print(result.stderr, file=sys.stderr)
+                sys.exit(result.returncode)
+            stdin_text = result.stdout
+
+        if stdin_text.strip():
+            # 管道模式：stdin → evidence（内容已读出，用 input= 转发给子进程）
+            evidence_args = defaults + rest
+            proc = subprocess.run([py, path] + evidence_args, input=stdin_text,
+                                  capture_output=True, text=True, timeout=60,
+                                  encoding="utf-8", errors="replace")
+            print(proc.stdout, end="")
+            if proc.stderr:
+                print(proc.stderr, file=sys.stderr)
+            sys.exit(proc.returncode)
+
+        print("evidence 需要查询词。用法：argo evidence \"query\"", file=sys.stderr)
+        sys.exit(1)
+
+    # --explain 与 --json 冲突（explain 输出纯文本干扰 JSON），自动去 --json
+    if "--explain" in rest and "--json" in defaults:
+        defaults.remove("--json")
+
+    args = defaults + rest
+
+    # daemon 快路径：search 是被 agent 循环调用最密的子命令，「解释器启动 +
+    # engines 全家 import」~85ms 固定成本放大最狠。命中常驻进程时把拼好的
+    # args 原样发过去（daemon 侧 runpy 语义与这里的原地路径一字不差），本地
+    # 只付 stdio/env 同步/_self_capable 约 20ms。--help 不走快路径（argparse
+    # 本地直接答）。任何失败在 _daemon_run 内部静默退回常态，绝不污染输出。
+    if sub == "search" and not any(a in ("-h", "--help") for a in rest):
+        if _daemon_run(args, py):
+            return
+
+    if inplace:
+        # 原地执行：省一次解释器启动，并复用本进程已 import 的模块。
+        # runpy 会正确设置 __file__ / __name__，目标脚本的
+        # `if __name__ == "__main__"` 分支照常触发，sys.exit 照常传播。
+        #
+        # run_module 而非 run_path：run_path 把源文件当「无名脚本」执行，每次
+        # 重新编译（实测 search.py 113KB ≈ 13ms），`__pycache__` 永不命中；
+        # run_module 走 importlib 的缓存校验，同一份源码只在首次或改动后编译。
+        # SCRIPTS 已在 sys.path 首位，模块名即去掉 .py 的文件名。
+        sys.argv = [path] + args
+        sys.path.insert(0, SCRIPTS)
+        import runpy
+        runpy.run_module(script[:-3], run_name="__main__")
+        return
+    os.execv(py, [py, path] + args)
+
+if __name__ == "__main__":
+    main()