rrun-cli 0.1.0__py3-none-any.whl

rrun/__init__.py

@@ -0,0 +1,36 @@
+# -*- coding: utf-8 -*-
+"""rrun — 远程机器执行模块（Run Remote）。
+
+约定：read/write/edit 等文件操作始终发生在本地；任何远程执行都是
+「本地写脚本 → stdin 管道送远端解释器执行 → 收回 stdout/stderr/退出码」。
+
+支持语言：bash（Mac/Linux）、powershell（Windows）、python（跨平台）。
+"""
+
+try:
+    from importlib.metadata import version as _pkg_version
+
+    __version__ = _pkg_version("rrun-cli")
+except Exception:  # noqa: BLE001 - 未安装（源码直跑）时回退
+    __version__ = "0.1.0"
+
+from .executor import (
+    AUDIT_LOG,
+    EXIT_TIMEOUT,
+    EXIT_TRANSPORT_ERROR,
+    RRUN_HOME,
+    ExecResult,
+    build_ps_wrapper,
+    close_mux,
+    detect_remote_python,
+    run,
+)
+from .registry import Machine, SourceInfo, candidate_sources, load_machines, resolve_machine, scan_sources
+from .setup import SetupResult, load_requirements, setup_machine
+
+__all__ = [
+    "AUDIT_LOG", "EXIT_TIMEOUT", "EXIT_TRANSPORT_ERROR", "RRUN_HOME",
+    "ExecResult", "Machine", "SetupResult", "SourceInfo",
+    "build_ps_wrapper", "candidate_sources", "close_mux", "detect_remote_python",
+    "load_machines", "load_requirements", "resolve_machine", "run", "scan_sources", "setup_machine",
+]

rrun/__main__.py

@@ -0,0 +1,301 @@
+# -*- coding: utf-8 -*-
+"""rrun — 远程机器执行器（Run Remote）。
+
+核心约定：脚本内容（可含中文，UTF-8）经 **stdin 管道**送远端解释器执行，
+全程不走命令行参数，规避 bash->ssh->cmd 多层转码/转义问题。
+
+用法:
+    rrun exec <host> <script.py|.ps1|.sh> [ascii_args...]
+    rrun exec <host> -c "Write-Output 中文"          # lang 按 OS 推断
+    rrun exec pc_build temp/x.py --timeout 60
+    rrun exec mac_mini --lang python temp/x.py
+    rrun setup <host|--all> [--force]   # 初始化统一 python 环境（3.12 venv + 阿里源）
+    rrun pip <host> -- list             # 在统一 venv 中执行 pip
+    rrun machines                       # 列出可用机器（脱敏，含来源）
+    rrun config                         # 查看 machines.json 来源链解析
+    rrun close [<host>|--all]           # 关闭 ssh 复用连接
+
+约定:
+    - lang 推断：文件扩展名（.py/.ps1/.sh）优先，否则按机器 OS（Windows=powershell，其他=bash）。
+    - 命令行参数只允许 ASCII，透传远端（python=sys.argv；bash=$@；powershell=$args）；
+      中文/特殊字符一律写进脚本内容或 JSON 文件。
+    - python 基线锁 3.12：探测命中统一 venv（优先）/standalone 基座/存量 3.12，
+      并校验版本号；全灭则报错提示先跑 setup（exec 热路径不做隐式安装）。
+    - 退出码：远端脚本退出码原样透传；255=ssh 传输层错误；124=本地超时。
+    - 内联 -c 内容自动落盘 ~/.rrun/drops/ 留档，可复跑（RRUN_HOME 可改根目录）。
+    - 审计：每次执行追加 ~/.rrun/log/remote-exec.jsonl。
+
+退出码即远端退出码，可直接管道使用：远端 stdout→本机 stdout，stderr→stderr。
+"""
+
+import argparse
+import json
+import sys
+import time
+from pathlib import Path
+
+from .executor import RRUN_HOME, _check_ascii, _ssh_run, close_mux, run
+from .registry import load_machines, resolve_machine, scan_sources
+from .setup import setup_machine, venv_python_or_die
+
+INLINE_DROP_DIR = RRUN_HOME / "drops"
+
+
+def _parse_env(pairs) -> dict:
+    env = {}
+    for p in pairs or []:
+        if "=" not in p:
+            raise SystemExit(f"[remote-exec] --env 格式应为 KEY=VAL: {p!r}")
+        k, v = p.split("=", 1)
+        env[k] = v
+    return env
+
+
+def _drop_inline(host: str, lang: str, content: str):
+    """内联内容落盘 ~/.rrun/drops/ 留档（可复跑/可 edit 后重跑）。"""
+    ext = {"python": ".py", "powershell": ".ps1", "bash": ".sh"}.get(lang, ".txt")
+    INLINE_DROP_DIR.mkdir(parents=True, exist_ok=True)
+    path = INLINE_DROP_DIR / f"{time.strftime('%Y%m%d-%H%M%S')}_{host}{ext}"
+    path.write_text(content, encoding="utf-8")
+    return path
+
+
+def cmd_exec(ns) -> int:
+    try:
+        machine = resolve_machine(ns.host)
+    except KeyError as e:
+        raise SystemExit(f"[remote-exec] {e}")
+
+    content = ns.content
+    file = ns.script or ""
+    lang = ns.lang or ""
+    if content and file:
+        raise SystemExit("[remote-exec] 脚本文件与 -c/--content 只能二选一")
+    if not content and not file:
+        raise SystemExit("[remote-exec] 缺少脚本：给文件路径或 -c/--content")
+
+    # content 模式先确定 lang 再落盘（扩展名需要 lang）
+    script_for_log = file
+    if content:
+        if not lang:
+            lang = machine.default_lang
+        dropped = _drop_inline(machine.name, lang, content)
+        script_for_log = str(dropped)
+        print(f"[remote-exec] 内联内容已落盘: {dropped}", file=sys.stderr)
+
+    args = ns.args
+
+    try:
+        result = run(
+            ns.host, lang=lang, file=file, content=content, args=args,
+            workdir=ns.workdir or "", env=_parse_env(ns.env),
+            timeout=ns.timeout, remote_python=(ns.python or ""), utf8=not ns.no_utf8,
+            mux=not ns.no_mux,
+        )
+    except (ValueError, RuntimeError) as e:
+        raise SystemExit(f"[remote-exec] {e}")
+
+    if not ns.quiet:
+        via = script_for_log or "<stdin>"
+        extra = f" python={result.remote_python}({result.remote_python_version})" if result.lang == "python" else ""
+        print(f"[remote-exec] host={result.host} ({result.ip}) lang={result.lang}{extra} "
+              f"script={via} sha1={result.content_sha1}", file=sys.stderr)
+    sys.stdout.buffer.write(result.stdout)
+    sys.stdout.buffer.flush()
+    sys.stderr.buffer.write(result.stderr)
+    sys.stderr.buffer.flush()
+
+    if result.timed_out:
+        print(f"[remote-exec] 超时（{ns.timeout}s），本地已终止", file=sys.stderr)
+    elif result.transport_error:
+        print(f"[remote-exec] ssh 传输层错误（连接失败/认证失败/掉线），exit=255", file=sys.stderr)
+    if not ns.quiet:
+        print(f"[remote-exec] exit={result.exit_code} 耗时 {result.duration:.1f}s", file=sys.stderr)
+    return result.exit_code
+
+
+def _short_source(path_str: str) -> str:
+    """来源路径缩短显示：home → ~。"""
+    if not path_str:
+        return "-"
+    s = str(path_str)
+    home = str(Path.home())
+    if s.startswith(home):
+        return "~" + s[len(home):]
+    return s
+
+
+def cmd_machines(ns) -> int:
+    machines = load_machines()
+    if ns.json:
+        print(json.dumps([m.public_dict() for m in machines], ensure_ascii=False, indent=2))
+        return 0
+    for m in machines:
+        desc = f"  # {m.description}" if m.description else ""
+        print(f"{m.name:<24} {m.ip:<16} {m.os:<8} {m.user:<12} {m.default_lang:<11} {_short_source(m.source)}{desc}")
+    return 0
+
+
+def cmd_config(ns) -> int:
+    infos = scan_sources()
+    print("machines.json 来源链（高 → 低优先级，同名机器高优先级覆盖）:")
+    raw_total = 0
+    for i, info in enumerate(infos, 1):
+        if not info.exists:
+            state = "- 不存在"
+        elif info.error:
+            state = f"✗ 读取失败: {info.error}"
+        else:
+            state = f"✓ {info.machine_count} 台"
+            raw_total += info.machine_count
+        print(f"  [{i}] {info.label:<22} {info.path}  {state}")
+    merged = load_machines()
+    print(f"合计 {len(merged)} 台（各来源原始共 {raw_total} 台，同名覆盖后 {len(merged)} 台）")
+    return 0
+
+
+def cmd_setup(ns) -> int:
+    if ns.all:
+        hosts = [m.name for m in load_machines()]
+    elif ns.host:
+        hosts = [ns.host]
+    else:
+        raise SystemExit("[setup] 需要指定 host 或 --all")
+    results = []
+    if len(hosts) == 1:
+        print(f"[setup] {hosts[0]} 初始化中...", file=sys.stderr)
+        results.append(setup_machine(hosts[0], force=ns.force))
+    else:
+        from concurrent.futures import ThreadPoolExecutor, as_completed
+        with ThreadPoolExecutor(max_workers=ns.jobs) as pool:
+            futs = {pool.submit(setup_machine, h, force=ns.force): h for h in hosts}
+            for f in as_completed(futs):
+                r = f.result()
+                results.append(r)
+                print(f"[setup] {r.host}: {'ok' if r.ok else 'FAIL'} ({r.duration:.0f}s)", file=sys.stderr)
+    print(f"\n{'host':<24} {'结果':<6} {'python':<10} {'venv':<46} 备注")
+    for r in sorted(results, key=lambda x: x.host):
+        if r.ok:
+            note = []
+            if r.installed_standalone:
+                note.append("新装standalone")
+            if r.created_venv:
+                note.append("新建venv")
+            if not note:
+                note.append("已存在，仅校验/补装依赖")
+            print(f"{r.host:<24} {'ok':<6} {r.version:<10} {r.venv_python:<46} {'，'.join(note)}")
+        else:
+            print(f"{r.host:<24} {'FAIL':<6} {'':<10} {'':<46} {r.message[:80]}")
+    return 0 if all(r.ok for r in results) else 1
+
+
+def cmd_pip(ns) -> int:
+    try:
+        machine = resolve_machine(ns.host)
+    except KeyError as e:
+        raise SystemExit(f"[pip] {e}")
+    args = list(ns.pargs or []) + list(getattr(ns, "args", []) or [])
+    if not args:
+        raise SystemExit("[pip] 缺少 pip 参数，例：rrun pip <host> -- list")
+    try:
+        _check_ascii(args, "pip 参数")
+        py = venv_python_or_die(ns.host)
+    except (ValueError, RuntimeError) as e:
+        raise SystemExit(f"[pip] {e}")
+    joined = " ".join(args)
+    if machine.is_windows:
+        remote_cmd = f'"{py}" -m pip {joined}'
+    else:
+        remote_cmd = f"{py} -m pip {joined}"
+    t0 = time.time()
+    rc, out, err, timed_out = _ssh_run(machine, remote_cmd, b"", ns.timeout, True)
+    sys.stdout.buffer.write(out)
+    sys.stdout.buffer.flush()
+    sys.stderr.buffer.write(err)
+    sys.stderr.buffer.flush()
+    print(f"[pip] {machine.name} exit={rc} 耗时 {time.time() - t0:.1f}s", file=sys.stderr)
+    return rc
+
+
+def cmd_close(ns) -> int:
+    if ns.all:
+        hosts = [m.name for m in load_machines()]
+    elif ns.host:
+        hosts = [ns.host]
+    else:
+        raise SystemExit("[remote-exec] close 需要指定 host 或 --all")
+    rc = 0
+    for h in hosts:
+        try:
+            code, msg = close_mux(h)
+        except Exception as e:  # noqa: BLE001 - close 尽量遍历完
+            code, msg = 1, str(e)
+        print(f"[remote-exec] close {h}: {'ok' if code == 0 else msg}")
+        rc = rc or code
+    return rc
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser(
+        prog="rrun",
+        description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    sub = ap.add_subparsers(dest="subcmd", required=True)
+
+    ep = sub.add_parser("exec", help="在远端机器执行本地脚本/内联内容")
+    ep.add_argument("host", help="机器 name/ip/hostname（见 machines 子命令）")
+    ep.add_argument("script", nargs="?", help="本地脚本路径（.py/.ps1/.sh，UTF-8）")
+    ep.add_argument("--lang", choices=["bash", "powershell", "python"],
+                    help="远端解释语言（缺省：按扩展名，否则按机器 OS）")
+    ep.add_argument("-c", "--content", help="内联脚本内容（自动落盘 ~/.rrun/drops/ 留档）")
+    ep.add_argument("args", nargs="*",
+                    help="脚本参数（仅 ASCII；建议用 -- 与选项分隔，选项可放任意位置）")
+    ep.add_argument("--workdir", help="远端工作目录（bash/powershell 支持）")
+    ep.add_argument("--env", action="append", metavar="KEY=VAL",
+                    help="远端环境变量（可多次；仅 ASCII）")
+    ep.add_argument("--timeout", type=float, help="本地超时秒数（超时 exit=124）")
+    ep.add_argument("--python", dest="python", help="远端 python 路径（跳过自动探测）")
+    ep.add_argument("--no-utf8", action="store_true", help="远端 python 不加 -X utf8")
+    ep.add_argument("--no-mux", action="store_true", help="禁用 ssh ControlMaster 复用")
+    ep.add_argument("-q", "--quiet", action="store_true", help="不打印 [remote-exec] 信息行")
+    ep.set_defaults(func=cmd_exec)
+
+    mp = sub.add_parser("machines", help="列出全部来源合并后的机器（脱敏，含来源）")
+    mp.add_argument("--json", action="store_true")
+    mp.set_defaults(func=cmd_machines)
+
+    cf = sub.add_parser("config", help="查看 machines.json 来源链解析（哪些文件生效、各贡献几台）")
+    cf.set_defaults(func=cmd_config)
+
+    sp = sub.add_parser("setup", help="初始化远端统一 python 环境（3.12 venv + 阿里云源）")
+    sp.add_argument("host", nargs="?", help="机器 name/ip；--all 表示全部")
+    sp.add_argument("--all", action="store_true", help="对 machines.json 所有机器执行")
+    sp.add_argument("--force", action="store_true", help="重建 venv（不动已装的 python 本体）")
+    sp.add_argument("--jobs", type=int, default=6, help="--all 时的并发数（默认 6）")
+    sp.set_defaults(func=cmd_setup)
+
+    pp = sub.add_parser("pip", help="在远端统一 venv 中执行 pip（ad-hoc 装包）")
+    pp.add_argument("host", help="机器 name/ip")
+    pp.add_argument("pargs", nargs="*", help="pip 参数；含 - 开头选项时放 -- 之后")
+    pp.add_argument("--timeout", type=float, default=300.0, help="本地超时秒数（默认 300）")
+    pp.set_defaults(func=cmd_pip)
+
+    cp = sub.add_parser("close", help="关闭 ssh ControlMaster 复用连接")
+    cp.add_argument("host", nargs="?", help="机器 name/ip；省略时需 --all")
+    cp.add_argument("--all", action="store_true", help="关闭所有机器的复用连接")
+    cp.set_defaults(func=cmd_close)
+
+    # argparse 对 -- 的处理与子解析器/位置参数组合有 quirk，手动切分更可靠：
+    # 第一个 -- 之后的全部内容原样作为脚本参数
+    argv = sys.argv[1:]
+    passthrough: "list[str] | None" = None
+    if "--" in argv:
+        i = argv.index("--")
+        argv, passthrough = argv[:i], argv[i + 1:]
+    ns = ap.parse_args(argv)
+    if passthrough is not None:
+        ns.args = list(getattr(ns, "args", []) or []) + passthrough
+    sys.exit(ns.func(ns))
+
+
+if __name__ == "__main__":
+    main()

rrun/executor.py

@@ -0,0 +1,362 @@
+# -*- coding: utf-8 -*-
+"""远程执行核心：本地脚本 → ssh stdin 管道 → 远端解释器执行。
+
+设计要点（Phase 0 spike 实测验证）：
+- 全程 stdin 管道，脚本内容/中文不走命令行，规避多层转码转义问题。
+- Windows PowerShell：-Command - 按行执行 stdin，故载荷编码为
+  **单行纯 ASCII wrapper**（内联 base64，UTF-8 解码后 ScriptBlock 执行），
+  支持 workdir / env / args($args) / 退出码透传 / terminating error -> 1。
+- python：`python -X utf8 -`；bash：`bash -s --`。
+- ControlMaster 连接复用：首连 ~0.5s，复用 ~0.02s。
+- 退出码约定：远端脚本退出码原样透传；255 = ssh 传输层错误；124 = 本地超时。
+- 本地状态目录：~/.rrun/（RRUN_HOME 环境变量可改根目录）。
+"""
+
+import base64
+import hashlib
+import json
+import os
+import shlex
+import shutil
+import subprocess
+import time
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+
+from .registry import Machine, resolve_machine
+
+
+def _rrun_home() -> Path:
+    """本地状态根目录：$RRUN_HOME 或 ~/.rrun（放审计日志/内联落盘/用户配置）。"""
+    override = os.environ.get("RRUN_HOME", "").strip()
+    return Path(override).expanduser() if override else Path.home() / ".rrun"
+
+
+RRUN_HOME = _rrun_home()
+AUDIT_LOG = RRUN_HOME / "log" / "remote-exec.jsonl"
+
+LANGS = ("bash", "powershell", "python")
+EXT_TO_LANG = {".py": "python", ".ps1": "powershell", ".sh": "bash"}
+LANG_TO_EXT = {"python": ".py", "powershell": ".ps1", "bash": ".sh"}
+
+SSH_BASE_OPTS = [
+    "-o", "StrictHostKeyChecking=no",
+    "-o", "LogLevel=ERROR",
+    "-o", "ConnectTimeout=10",
+]
+CONTROL_PATH_DIR = Path.home() / ".ssh"
+CONTROL_PATH = str(CONTROL_PATH_DIR / "rrun-%C")
+MUX_OPTS = [
+    "-o", "ControlMaster=auto",
+    "-o", f"ControlPath={CONTROL_PATH}",
+    "-o", "ControlPersist=600",
+]
+
+EXIT_TRANSPORT_ERROR = 255  # ssh 自身失败（连不上/认证失败/掉线）
+EXIT_TIMEOUT = 124          # 本地超时杀掉 ssh 进程
+
+# 统一环境布局（setup 子命令初始化；基线版本锁 3.12）：
+#   Windows: C:\tools\remote-machine\venv\Scripts\python.exe  —— 统一 venv，常态命中
+#            C:\tools\remote-machine\python312\python.exe     —— standalone 基座（venv 损坏时降级）
+#   Mac:     ~/.remote-machine/venv/bin/python                  —— 统一 venv
+#            ~/.remote-machine/python312/bin/python3            —— standalone 基座（仅裸机安装）
+# 候选按序探测，命中后校验版本 == 3.12.x（不符继续找）；全灭 -> 报错提示跑 setup。
+REQUIRED_PY_MAJOR_MINOR = (3, 12)
+
+VENV_PY_WIN = r"C:\tools\remote-machine\venv\Scripts\python.exe"
+BASE_PY_WIN = r"C:\tools\remote-machine\python312\python.exe"
+VENV_PY_POSIX = "$HOME/.remote-machine/venv/bin/python"
+BASE_PY_POSIX = "$HOME/.remote-machine/python312/bin/python3"
+
+WINDOWS_PYTHON_CANDIDATES = [
+    VENV_PY_WIN,
+    BASE_PY_WIN,
+    r"C:\Python\Python312\python.exe",  # 存量装机（降级，无第三方库）
+]
+# setup 创建 venv 时的基座候选（不含 venv 自身）：机器已装的优先，standalone 兜底
+WINDOWS_BASE_CANDIDATES = [r"C:\Python\Python312\python.exe", BASE_PY_WIN]
+POSIX_PYTHON_CANDIDATES = [
+    VENV_PY_POSIX,
+    "python3.12", "/usr/local/bin/python3.12",
+]
+POSIX_BASE_CANDIDATES = ["python3.12", "/usr/local/bin/python3.12", BASE_PY_POSIX]
+
+PS_REMOTE_CMD = "powershell -NoProfile -NonInteractive -ExecutionPolicy Bypass -Command -"
+
+_python_cache: "dict[tuple[str, str], tuple[str, str]]" = {}  # (ip, override) -> (路径, 版本)
+
+
+@dataclass
+class ExecResult:
+    host: str
+    ip: str
+    lang: str
+    exit_code: int
+    duration: float
+    stdout: bytes = b""
+    stderr: bytes = b""
+    script_path: str = ""       # 本地脚本路径（content 模式为落盘后的路径）
+    content_sha1: str = ""
+    remote_python: str = ""     # 实际使用的远端 python（lang=python 时）
+    remote_python_version: str = ""  # 远端 python 版本（如 3.12.14）
+    transport_error: bool = False  # ssh 层失败（exit 255）
+    timed_out: bool = False
+
+    def stdout_text(self, errors: str = "replace") -> str:
+        return self.stdout.decode("utf-8", errors)
+
+    def stderr_text(self, errors: str = "replace") -> str:
+        return self.stderr.decode("utf-8", errors)
+
+
+def _check_ascii(values, what: str) -> None:
+    for v in values:
+        if not all(ord(c) < 128 for c in v):
+            raise ValueError(f"{what} 含非 ASCII：{v!r}；中文/特殊字符请写进脚本内容或 JSON 文件，不要走命令行")
+
+
+def _ps_quote(s: str) -> str:
+    """PowerShell 单引号字符串转义（入参已保证 ASCII）。"""
+    return "'" + s.replace("'", "''") + "'"
+
+
+def build_ps_wrapper(code: str, args=(), workdir: str = "", env: "dict | None" = None) -> bytes:
+    """把 PowerShell 脚本编码为单行纯 ASCII wrapper（-Command - 按行执行，禁止多行）。"""
+    _check_ascii(args, "参数")
+    parts = [
+        "[Console]::OutputEncoding=[Text.Encoding]::UTF8",
+        "$OutputEncoding=[Text.Encoding]::UTF8",
+        "$ProgressPreference='SilentlyContinue'",
+    ]
+    if workdir:
+        parts.append(f"Set-Location {_ps_quote(workdir)}")
+    for k, v in (env or {}).items():
+        parts.append(f"$env:{k}={_ps_quote(v)}")
+    b64 = base64.b64encode(code.encode("utf-8")).decode("ascii")
+    parts.append(f"$__code=[Text.Encoding]::UTF8.GetString([Convert]::FromBase64String('{b64}'))")
+    parts.append("$__args=@(" + ",".join(_ps_quote(a) for a in args) + ")")
+    parts.append(
+        "try{& ([ScriptBlock]::Create($__code)) @__args}"
+        "catch{[Console]::Error.WriteLine($_.Exception.ToString());exit 1}"
+    )
+    parts.append("if($null -ne $LASTEXITCODE){exit $LASTEXITCODE}else{exit 0}")
+    line = ";".join(parts)
+    assert all(ord(c) < 128 for c in line), "powershell wrapper 必须纯 ASCII"
+    return (line + "\n").encode("ascii")
+
+
+def _posix_prefix(workdir: str = "", env: "dict | None" = None) -> str:
+    """posix 远端命令前缀：cd + env（拼在实际命令前）。"""
+    prefix = ""
+    if workdir:
+        prefix += f"cd {shlex.quote(workdir)} && "
+    if env:
+        prefix += "env " + " ".join(f"{k}={shlex.quote(v)}" for k, v in env.items()) + " "
+    return prefix
+
+
+def build_bash_command(args=(), workdir: str = "", env: "dict | None" = None) -> str:
+    _check_ascii(args, "参数")
+    cmd = _posix_prefix(workdir, env) + "bash -s"
+    if args:
+        cmd += " -- " + " ".join(shlex.quote(a) for a in args)
+    return cmd
+
+
+def _ssh_run(machine: Machine, remote_cmd: str, stdin: bytes, timeout: "float | None",
+             mux: bool) -> "tuple[int, bytes, bytes, bool]":
+    """返回 (exit_code, stdout, stderr, timed_out)。exit 255 即传输层错误。"""
+    sshpass = shutil.which("sshpass")
+    if not sshpass:
+        raise RuntimeError("本机缺少 sshpass（sudo apt install sshpass）")
+    if mux:
+        CONTROL_PATH_DIR.mkdir(mode=0o700, exist_ok=True)
+    args = [sshpass, "-p", machine.password, "ssh", *SSH_BASE_OPTS]
+    if mux:
+        args += MUX_OPTS
+    args += [machine.target, remote_cmd]
+    try:
+        p = subprocess.run(args, input=stdin, capture_output=True,
+                           timeout=timeout if timeout and timeout > 0 else None)
+        return p.returncode, p.stdout, p.stderr, False
+    except subprocess.TimeoutExpired as e:
+        return EXIT_TIMEOUT, e.stdout or b"", (e.stderr or b"") + f"\n[remote-exec] 本地超时 {timeout}s\n".encode(), True
+
+
+# 注意：代码内不得出现任何引号（bash 探测用单引号包裹此代码；chr(46)='.'）
+_PY_VER_PRINT_CODE = "import sys;print(*sys.version_info[:3],sep=chr(46))"
+_PY_VER_CHECK_CODE = (
+    _PY_VER_PRINT_CODE + f";sys.exit(0 if sys.version_info[:2]=={REQUIRED_PY_MAJOR_MINOR} else 1)"
+)
+
+
+def _ps_probe_script(candidates) -> str:
+    """Windows 探测脚本：逐候选校验版本==3.12.x，命中输出 path|x.y.z，全灭 exit 1。"""
+    arr = ",".join(_ps_quote(c) for c in candidates)
+    return (
+        f"foreach($c in @({arr})){{"
+        "if(Test-Path $c){"
+        f"$v=& $c -X utf8 -c \"{_PY_VER_CHECK_CODE}\" 2>$null;"
+        "if($LASTEXITCODE -eq 0){Write-Output ($c+'|'+($v -join ''));exit 0}"
+        "}}"
+    )
+
+
+def _bash_probe_script(candidates) -> str:
+    """posix 探测脚本：同 Windows 语义。候选为可信常量（$HOME 需保留展开，不可 shlex.quote）。"""
+    items = " ".join(f'"{c}"' for c in candidates)
+    return (
+        f"for p in {items}; do\n"
+        '  command -v "$p" >/dev/null 2>&1 || continue\n'
+        f'  v=$("$p" -X utf8 -c \'{_PY_VER_CHECK_CODE}\' 2>/dev/null) || continue\n'
+        '  echo "$p|$v"\n'
+        "  exit 0\n"
+        "done\n"
+        "exit 1\n"
+    )
+
+
+def probe_python(machine: Machine, candidates, mux: bool = True) -> "tuple[str, str] | None":
+    """在候选中找版本==3.12.x 的远端 python，单次往返；返回 (路径, 版本)，全灭返回 None。"""
+    if machine.is_windows:
+        rc, out, _, _ = _ssh_run(machine, PS_REMOTE_CMD,
+                                 build_ps_wrapper(_ps_probe_script(candidates)), 60, mux)
+    else:
+        rc, out, _, _ = _ssh_run(machine, "bash -s",
+                                 _bash_probe_script(candidates).encode("utf-8"), 60, mux)
+    if rc != 0 or not out.strip():
+        return None
+    line = out.decode("utf-8", "replace").strip().splitlines()[-1].strip()
+    path, sep, ver = line.partition("|")
+    return (path.strip(), ver.strip()) if sep and path.strip() else None
+
+
+def probe_python_version(machine: Machine, python_path: str, mux: bool = True) -> str:
+    """尽力探测指定 python 的版本字符串（失败返回空串）。posix 路径可含 $HOME（shell 展开）。"""
+    code = _PY_VER_PRINT_CODE
+    if machine.is_windows:
+        script = f"$v=& {_ps_quote(python_path)} -X utf8 -c \"{code}\" 2>$null;if($LASTEXITCODE -eq 0){{Write-Output ($v -join '')}}"
+        rc, out, _, _ = _ssh_run(machine, PS_REMOTE_CMD, build_ps_wrapper(script), 30, mux)
+    else:
+        rc, out, _, _ = _ssh_run(machine, "bash -s",
+                                 f'"{python_path}" -X utf8 -c \'{code}\' 2>/dev/null\n'.encode(), 30, mux)
+    if rc != 0 or not out.strip():
+        return ""
+    return out.decode("utf-8", "replace").strip().splitlines()[-1].strip()
+
+
+def detect_remote_python(machine: Machine, override: str = "", mux: bool = True) -> "tuple[str, str]":
+    """解析远端 python，返回 (路径, 版本)。基线锁 3.12；machines.json "python" 字段/参数可覆盖（跳过校验）。"""
+    key = (machine.ip, override or machine.python)
+    if key in _python_cache:
+        return _python_cache[key]
+    if override or machine.python:
+        path = override or machine.python
+        result = (path, probe_python_version(machine, path, mux))
+    else:
+        candidates = WINDOWS_PYTHON_CANDIDATES if machine.is_windows else POSIX_PYTHON_CANDIDATES
+        found = probe_python(machine, candidates, mux)
+        if not found:
+            raise RuntimeError(
+                f"[{machine.name}] 未找到 python {REQUIRED_PY_MAJOR_MINOR[0]}.{REQUIRED_PY_MAJOR_MINOR[1]}"
+                f"（基线版本已锁定）。请先初始化统一环境：rrun setup {machine.name}"
+            )
+        result = found
+    _python_cache[key] = result
+    return result
+
+
+def run(host: str, lang: str = "", file: str = "", content: str = "", args=(),
+        workdir: str = "", env: "dict | None" = None, timeout: "float | None" = None,
+        remote_python: str = "", utf8: bool = True, mux: bool = True,
+        audit: bool = True) -> ExecResult:
+    """在远端机器执行本地脚本（或内联内容），返回 ExecResult。
+
+    host: 机器 name/ip/hostname；lang: bash|powershell|python（缺省按文件扩展名或机器 OS 推断）
+    file/content 二选一；args 仅允许 ASCII。
+    """
+    machine = resolve_machine(host)
+    if file and content:
+        raise ValueError("file 与 content 只能二选一")
+    if not file and not content:
+        raise ValueError("必须提供 file 或 content")
+
+    if file:
+        script_path = str(Path(file).resolve())
+        raw = Path(file).read_bytes()
+        suffix = Path(file).suffix.lower()
+    else:
+        script_path = ""
+        raw = content.encode("utf-8")
+        suffix = ""
+    if not lang:
+        lang = EXT_TO_LANG.get(suffix, machine.default_lang)
+    if lang not in LANGS:
+        raise ValueError(f"不支持的语言: {lang}（可选 {LANGS}）")
+    _check_ascii(args, "参数")
+    _check_ascii([x for kv in (env or {}).items() for x in kv], "env")
+
+    t0 = time.time()
+    remote_python_used = ""
+    remote_py_version = ""
+    if lang == "powershell":
+        remote_cmd = PS_REMOTE_CMD
+        stdin = build_ps_wrapper(raw.decode("utf-8"), args, workdir, env)
+    elif lang == "bash":
+        remote_cmd = build_bash_command(args, workdir, env)
+        stdin = raw
+    else:  # python
+        remote_python_used, remote_py_version = detect_remote_python(machine, remote_python, mux)
+        py_cmd = remote_python_used + (" -X utf8" if utf8 else "") + " -"
+        if args:
+            py_cmd += " " + " ".join(shlex.quote(a) for a in args)
+        if env or workdir:
+            if machine.is_windows:
+                raise ValueError("Windows + python 暂不支持 workdir/env，请在脚本内 os.chdir/os.environ 处理")
+            remote_cmd = _posix_prefix(workdir, env) + py_cmd
+        else:
+            remote_cmd = py_cmd
+        stdin = raw
+
+    exit_code, stdout, stderr, timed_out = _ssh_run(machine, remote_cmd, stdin, timeout, mux)
+    result = ExecResult(
+        host=machine.name, ip=machine.ip, lang=lang, exit_code=exit_code,
+        duration=time.time() - t0, stdout=stdout, stderr=stderr,
+        script_path=script_path, content_sha1=hashlib.sha1(raw).hexdigest()[:12],
+        remote_python=remote_python_used, remote_python_version=remote_py_version,
+        transport_error=(exit_code == EXIT_TRANSPORT_ERROR), timed_out=timed_out,
+    )
+    if audit:
+        _write_audit(result, args, workdir, env, timeout)
+    return result
+
+
+def _write_audit(result: ExecResult, args, workdir: str, env: "dict | None",
+                 timeout: "float | None") -> None:
+    try:
+        AUDIT_LOG.parent.mkdir(parents=True, exist_ok=True)
+        record = {
+            "ts": datetime.now().isoformat(timespec="seconds"),
+            "host": result.host, "ip": result.ip, "lang": result.lang,
+            "script": result.script_path, "sha1": result.content_sha1,
+            "args": list(args), "workdir": workdir,
+            "env_keys": sorted((env or {}).keys()),  # 只记 key，防泄密
+            "timeout": timeout, "exit_code": result.exit_code,
+            "python": result.remote_python, "python_version": result.remote_python_version,
+            "duration_s": round(result.duration, 2),
+            "transport_error": result.transport_error, "timed_out": result.timed_out,
+        }
+        with open(AUDIT_LOG, "a", encoding="utf-8") as f:
+            f.write(json.dumps(record, ensure_ascii=False) + "\n")
+    except OSError:
+        pass  # 审计失败不阻断执行
+
+
+def close_mux(host: str) -> "tuple[int, str]":
+    """关闭某台机器的 ControlMaster 复用连接。"""
+    machine = resolve_machine(host)
+    p = subprocess.run(
+        ["ssh", "-O", "exit", "-o", f"ControlPath={CONTROL_PATH}", machine.target],
+        capture_output=True, text=True, timeout=15)
+    return p.returncode, (p.stdout + p.stderr).strip()

rrun/registry.py

@@ -0,0 +1,163 @@
+# -*- coding: utf-8 -*-
+"""机器注册表：多来源加载 machines.json，按优先级 merge，解析 name/ip/hostname → Machine。
+
+来源链（高 → 低优先级；同名机器高优先级覆盖；同名/ip 冲突静默处理，不刷警告）：
+    1. $RRUN_CONFIG（os.pathsep 分隔，可多个文件）
+    2. $REMOTE_MACHINE_CONFIG（旧名，兼容）
+    3. ./machines.json（当前工作目录）
+    4. ~/.rrun/machines.json（用户级主清单）
+    5. ~/.rrun/machines.d/*.json（按文件名排序；推荐：多清单各放一个文件/软链）
+    6. 旧位置兼容：Windows C:\\tools\\remote-machine\\machines.json
+                   POSIX   ~/.remote-machine/machines.json
+
+规则：
+    - 所有来源可选；不存在 / 读失败的来源静默跳过（诊断见 scan_sources / CLI config 子命令）。
+    - 每个文件先按 os 应用自己的 defaults 段，再按 name merge（先出现者胜）。
+    - 显式传 path 给 load_machines 则退化为单文件模式（测试 / 钉死用）。
+"""
+
+import json
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+
+ENV_MACHINES_JSON = "RRUN_CONFIG"
+ENV_MACHINES_JSON_LEGACY = "REMOTE_MACHINE_CONFIG"
+
+_KNOWN_KEYS = {"name", "ip", "user", "password", "os", "hostname", "description", "python"}
+
+
+@dataclass
+class Machine:
+    name: str
+    ip: str
+    user: str
+    password: str = field(repr=False)  # 凭据不进 repr/日志
+    os: str = "Windows"                # 原样取值：Windows / Mac / Linux
+    hostname: str = ""
+    description: str = ""
+    python: str = ""                   # 可选：显式指定远端 python 路径，跳过自动探测
+    source: str = ""                   # 来源文件路径（多来源 merge 时记录出处）
+
+    @property
+    def is_windows(self) -> bool:
+        return self.os.lower() == "windows"
+
+    @property
+    def default_lang(self) -> str:
+        return "powershell" if self.is_windows else "bash"
+
+    @property
+    def target(self) -> str:
+        return f"{self.user}@{self.ip}"
+
+    def public_dict(self) -> dict:
+        """脱敏视图（不含密码），用于 CLI 展示 / prompt 注入。"""
+        return {
+            "name": self.name, "ip": self.ip, "os": self.os, "user": self.user,
+            "hostname": self.hostname, "description": self.description,
+            "default_lang": self.default_lang, "source": self.source,
+        }
+
+
+@dataclass
+class SourceInfo:
+    """单个来源的扫描诊断（CLI config 子命令用）。"""
+    label: str
+    path: Path
+    exists: bool = False
+    machine_count: int = 0
+    error: str = ""
+
+
+def candidate_sources() -> "list[tuple[str, Path]]":
+    """返回 (标签, 路径) 有序来源链（高→低优先级），按 resolved path 去重。"""
+    cands: "list[tuple[str, Path]]" = []
+    for env_name in (ENV_MACHINES_JSON, ENV_MACHINES_JSON_LEGACY):
+        env = os.environ.get(env_name, "")
+        env_paths = [x for x in env.split(os.pathsep) if x.strip()]
+        for i, p in enumerate(env_paths):
+            label = f"${env_name}" if i == 0 else f"${env_name}[{i}]"
+            cands.append((label, Path(p).expanduser()))
+    cands.append(("cwd", Path.cwd() / "machines.json"))
+    rrun_home = Path.home() / ".rrun"
+    cands.append(("user", rrun_home / "machines.json"))
+    machines_d = rrun_home / "machines.d"
+    if machines_d.is_dir():
+        for p in sorted(machines_d.glob("*.json")):
+            cands.append(("user.d", p))
+    if os.name == "nt":
+        cands.append(("legacy", Path(r"C:\tools\remote-machine\machines.json")))
+    else:
+        cands.append(("legacy", Path.home() / ".remote-machine" / "machines.json"))
+    seen: "set[str]" = set()
+    uniq: "list[tuple[str, Path]]" = []
+    for label, p in cands:
+        try:
+            key = os.path.normcase(str(p.resolve()))
+        except OSError:
+            key = os.path.normcase(str(p))
+        if key not in seen:
+            seen.add(key)
+            uniq.append((label, p))
+    return uniq
+
+
+def _load_file(path: Path) -> "list[Machine]":
+    """加载单个文件：先按 os 应用该文件自己的 defaults 段，再打 source 标签。"""
+    with open(path, encoding="utf-8") as f:
+        data = json.load(f)
+    defaults = data.get("defaults") or {}
+    result = []
+    for m in data.get("machines", []):
+        base = defaults.get(str(m.get("os", "")).lower()) or {}
+        merged = {**base, **m}  # 机器自身字段优先于 defaults
+        kwargs = {k: v for k, v in merged.items() if k in _KNOWN_KEYS}
+        machine = Machine(**kwargs)
+        machine.source = str(path)
+        result.append(machine)
+    return result
+
+
+def load_machines(path: "str | os.PathLike | None" = None) -> "list[Machine]":
+    """加载机器清单。显式传 path = 单文件模式；否则按来源链 merge（同名高优先级胜）。"""
+    if path:
+        return _load_file(Path(path))
+    merged: "dict[str, Machine]" = {}
+    for _label, p in candidate_sources():
+        if not p.is_file():
+            continue
+        try:
+            machines = _load_file(p)
+        except Exception:  # noqa: BLE001 - 坏来源静默跳过，诊断见 scan_sources()
+            continue
+        for m in machines:
+            if m.name and m.name not in merged:
+                merged[m.name] = m
+    return list(merged.values())
+
+
+def scan_sources() -> "list[SourceInfo]":
+    """扫描来源链，返回每个来源的诊断信息（存在性/机器数/错误）。"""
+    infos = []
+    for label, p in candidate_sources():
+        info = SourceInfo(label=label, path=p)
+        if p.is_file():
+            info.exists = True
+            try:
+                info.machine_count = len(_load_file(p))
+            except Exception as e:  # noqa: BLE001 - 诊断场景需要原始错误
+                info.error = f"{type(e).__name__}: {e}"
+        infos.append(info)
+    return infos
+
+
+def resolve_machine(host: str, path: "str | os.PathLike | None" = None) -> Machine:
+    """按 name / ip / hostname 解析机器；未命中时报错并列出可用机器。"""
+    machines = load_machines(path)
+    for m in machines:
+        if host and host in (m.name, m.ip, m.hostname):
+            return m
+    available = ", ".join(f"{m.name}({m.ip})" for m in machines) or "<空>"
+    sources = ", ".join(str(p) for _lbl, p in candidate_sources() if p.is_file()) or "<无可用来源>"
+    raise KeyError(f"机器 [{host}] 未找到。已扫描来源: {sources}。可用: {available}")

rrun/remote-requirements.txt

@@ -0,0 +1,4 @@
+# rrun 远端统一 venv 的标准依赖（setup 时安装）。
+# 用户级覆盖：~/.rrun/remote-requirements.txt 存在时优先生效。
+# 加依赖：改文件 → rrun setup <host>（幂等补装）。
+requests

rrun/setup.py

@@ -0,0 +1,276 @@
+# -*- coding: utf-8 -*-
+"""setup：初始化远端统一 python 环境（基线 3.12 + 统一 venv + 阿里云 pip 源）。
+
+布局（幂等，可重复执行）：
+  Windows: C:\\tools\\remote-machine\\venv\\Scripts\\python.exe  —— 统一 venv
+           C:\\tools\\remote-machine\\python312\\python.exe     —— standalone 基座（仅裸机安装）
+  Mac:     ~/.remote-machine/venv/bin/python
+           ~/.remote-machine/python312/bin/python3
+
+原则：
+  - 机器已有 3.12 则直接用作 venv 基座；没有才装 python-build-standalone
+    （免安装压缩包：零注册表、零 PATH、不改 python/py 指向，纯新增目录）。
+  - standalone 包先下载到本机缓存 ~/.cache/rrun/，再经 ssh stdin
+    推流到远端解压，远端无需访问 GitHub。
+  - pip 源（阿里云镜像）写在 venv 内 pip.ini/pip.conf，不污染机器全局配置。
+  - 标准依赖清单：默认用包内置 remote-requirements.txt；
+    ~/.rrun/remote-requirements.txt 存在时覆盖（加依赖改文件后重跑 setup）。
+"""
+
+import os
+import re
+import sys
+import time
+import urllib.request
+from dataclasses import dataclass, field
+from datetime import datetime
+from pathlib import Path
+
+from .executor import (
+    AUDIT_LOG,
+    BASE_PY_POSIX,
+    BASE_PY_WIN,
+    POSIX_BASE_CANDIDATES,
+    PS_REMOTE_CMD,
+    RRUN_HOME,
+    VENV_PY_POSIX,
+    VENV_PY_WIN,
+    WINDOWS_BASE_CANDIDATES,
+    _check_ascii,
+    _ssh_run,
+    build_ps_wrapper,
+    probe_python,
+    probe_python_version,
+)
+from .registry import Machine, resolve_machine
+
+# 标准依赖：用户级覆盖 > 包内置默认
+REQUIREMENTS_OVERRIDE = RRUN_HOME / "remote-requirements.txt"
+REQUIREMENTS_BUILTIN = Path(__file__).resolve().with_name("remote-requirements.txt")
+
+# python-build-standalone（astral-sh）固定版本，免安装压缩包
+PBS_TAG = "20260901"
+PBS_VER = "3.12.14"
+PBS_ASSETS = {
+    ("Windows", "x86_64"): f"cpython-{PBS_VER}+{PBS_TAG}-x86_64-pc-windows-msvc-install_only.tar.gz",
+    ("Mac", "arm64"): f"cpython-{PBS_VER}+{PBS_TAG}-aarch64-apple-darwin-install_only.tar.gz",
+    ("Mac", "x86_64"): f"cpython-{PBS_VER}+{PBS_TAG}-x86_64-apple-darwin-install_only.tar.gz",
+}
+PBS_DOWNLOAD_BASE = f"https://github.com/astral-sh/python-build-standalone/releases/download/{PBS_TAG}/"
+CACHE_DIR = Path(os.environ.get("XDG_CACHE_HOME", "") or Path.home() / ".cache") / "rrun"
+
+PIP_INDEX_URL = "https://mirrors.aliyun.com/pypi/simple/"
+
+TOOLS_DIR_WIN = r"C:\tools\remote-machine"
+VENV_DIR_WIN = TOOLS_DIR_WIN + r"\venv"
+
+
+@dataclass
+class SetupResult:
+    host: str
+    ok: bool
+    venv_python: str = ""
+    version: str = ""
+    base_python: str = ""
+    created_venv: bool = False
+    installed_standalone: bool = False
+    packages: "list[str]" = field(default_factory=list)
+    message: str = ""
+    duration: float = 0.0
+
+
+def load_requirements() -> "list[str]":
+    """读取标准依赖清单（过滤注释/空行）。~/.rrun/remote-requirements.txt 优先于包内置默认。"""
+    path = REQUIREMENTS_OVERRIDE if REQUIREMENTS_OVERRIDE.is_file() else REQUIREMENTS_BUILTIN
+    reqs = []
+    for line in path.read_text(encoding="utf-8").splitlines():
+        line = line.strip()
+        if line and not line.startswith("#"):
+            reqs.append(line)
+    return reqs
+
+
+def _req_import_name(req: str) -> str:
+    """requests>=2.31 -> requests（用于装后 import 自检）。"""
+    return re.split(r"[<>=!~\[ ]", req, maxsplit=1)[0].strip()
+
+
+def _ensure_local_tarball(os_name: str, arch: str) -> Path:
+    """standalone 包下载到本机缓存（远端不访问 GitHub）。"""
+    name = PBS_ASSETS[(os_name, arch)]
+    path = CACHE_DIR / name
+    if path.exists() and path.stat().st_size > 1024 * 1024:
+        return path
+    CACHE_DIR.mkdir(parents=True, exist_ok=True)
+    url = PBS_DOWNLOAD_BASE + name
+    print(f"[setup] 本机缓存缺失，下载 {url} ...", file=sys.stderr)
+    tmp = path.with_suffix(".part")
+    urllib.request.urlretrieve(url, tmp)  # noqa: S310 - 固定官方源
+    tmp.rename(path)
+    return path
+
+
+def _install_standalone(machine: Machine, mux: bool, timeout: float) -> str:
+    """推送 standalone python 到远端并解压，返回基座 python 路径。"""
+    if machine.is_windows:
+        os_name, arch = "Windows", "x86_64"
+        # 注意 cmd 陷阱：if exist 不带括号会把后续 & 链全吞进分支体，
+        # 条件为假时整行跳过且 exit=0（假成功），故条件放最后用 && 门控
+        extract_cmd = (
+            f'mkdir "{TOOLS_DIR_WIN}" 2>nul '
+            f'& rmdir /s /q "{TOOLS_DIR_WIN}\\python312" 2>nul '
+            f'& tar -xzf - -C "{TOOLS_DIR_WIN}" '
+            f'&& ren "{TOOLS_DIR_WIN}\\python" python312'
+        )
+        base_py = BASE_PY_WIN
+    else:
+        rc, out, _, _ = _ssh_run(machine, "uname -m", b"", 30, mux)
+        arch = out.decode("utf-8", "replace").strip()
+        os_name = "Mac"
+        if (os_name, arch) not in PBS_ASSETS:
+            raise RuntimeError(f"[{machine.name}] 暂不支持的架构: {arch}")
+        extract_cmd = (
+            'tools="$HOME/.remote-machine"; mkdir -p "$tools" '
+            '&& rm -rf "$tools/python312" '
+            '&& tar -xzf - -C "$tools" '
+            '&& mv "$tools/python" "$tools/python312"'
+        )
+        base_py = BASE_PY_POSIX
+    tarball = _ensure_local_tarball(os_name, arch)
+    print(f"[setup] [{machine.name}] 推送 standalone python ({tarball.name}, "
+          f"{tarball.stat().st_size // 1024 // 1024}MB) ...", file=sys.stderr)
+    rc, _, err, timed_out = _ssh_run(machine, extract_cmd, tarball.read_bytes(), timeout, mux)
+    if rc != 0:
+        raise RuntimeError(f"[{machine.name}] standalone 推送/解压失败(exit={rc}): "
+                           f"{err.decode('utf-8', 'replace')[:300]}")
+    ver = probe_python_version(machine, base_py, mux)
+    if not ver:
+        raise RuntimeError(f"[{machine.name}] standalone 解压后验证失败: {base_py}")
+    return base_py
+
+
+def _build_ps_setup(base_py: str, pkgs: "list[str]", force: bool) -> str:
+    """Windows 一键脚本：建 venv（缺/force 时）→ pip.ini → 装依赖 → 自检。全 ASCII。"""
+    pkg_args = " ".join(pkgs)
+    imports = ";".join(f"import {_req_import_name(p)}" for p in pkgs) or "pass"
+    force_lit = "$true" if force else "$false"
+    return f"""
+$tools={_ps_quote_const(TOOLS_DIR_WIN)}
+$venv="$tools\\venv"
+$venvPy="$venv\\Scripts\\python.exe"
+New-Item -ItemType Directory -Force $tools | Out-Null
+if({force_lit} -and (Test-Path $venv)){{Remove-Item -Recurse -Force $venv}}
+if(-not (Test-Path $venvPy)){{
+  if('{base_py}' -eq ''){{Write-Error "no base python";exit 1}}
+  & '{base_py}' -m venv $venv
+  if($LASTEXITCODE -ne 0){{Write-Error "venv create failed";exit 1}}
+}}
+[System.IO.File]::WriteAllText("$venv\\pip.ini","[global]`nindex-url = {PIP_INDEX_URL}`n")
+& $venvPy -m pip install --quiet --disable-pip-version-check {pkg_args}
+if($LASTEXITCODE -ne 0){{Write-Error "pip install failed";exit 1}}
+& $venvPy -X utf8 -c "import sys;{imports};print('verify ok', '.'.join(map(str,sys.version_info[:3])))"
+if($LASTEXITCODE -ne 0){{Write-Error "verify failed";exit 1}}
+"""
+
+
+def _ps_quote_const(s: str) -> str:
+    return "'" + s.replace("'", "''") + "'"
+
+
+def _build_bash_setup(base_py: str, pkgs: "list[str]", force: bool) -> str:
+    pkg_args = " ".join(pkgs)
+    imports = ";".join(f"import {_req_import_name(p)}" for p in pkgs) or "pass"
+    return f"""set -e
+tools="$HOME/.remote-machine"
+venv="$tools/venv"
+mkdir -p "$tools"
+if [ "{'1' if force else '0'}" = "1" ]; then rm -rf "$venv"; fi
+if [ ! -x "$venv/bin/python" ]; then
+  "{base_py}" -m venv "$venv"
+fi
+cat > "$venv/pip.conf" <<'EOF'
+[global]
+index-url = {PIP_INDEX_URL}
+EOF
+"$venv/bin/python" -m pip install --quiet --disable-pip-version-check {pkg_args}
+"$venv/bin/python" -X utf8 -c "import sys;{imports};print('verify ok', '.'.join(map(str,sys.version_info[:3])))"
+"""
+
+
+def setup_machine(host: str, force: bool = False, mux: bool = True,
+                  timeout: float = 600.0) -> SetupResult:
+    """初始化单台机器的统一 python 环境。幂等；force 重建 venv（不动 python 本体）。"""
+    t0 = time.time()
+    result = SetupResult(host=host, ok=False)
+    try:
+        machine = resolve_machine(host)
+        reqs = load_requirements()
+        _check_ascii(reqs, "requirements")
+        venv_py = VENV_PY_WIN if machine.is_windows else VENV_PY_POSIX
+        base_cands = WINDOWS_BASE_CANDIDATES if machine.is_windows else POSIX_BASE_CANDIDATES
+
+        hit = probe_python(machine, [venv_py], mux)
+        need_create = force or not hit
+        base_py = ""
+        if need_create:
+            base_hit = probe_python(machine, base_cands, mux)
+            if base_hit:
+                base_py = base_hit[0]
+            else:
+                base_py = _install_standalone(machine, mux, timeout)
+                result.installed_standalone = True
+            result.created_venv = True
+            result.base_python = base_py
+
+        if machine.is_windows:
+            payload = build_ps_wrapper(_build_ps_setup(base_py, reqs, force))
+            rc, out, err, _ = _ssh_run(machine, PS_REMOTE_CMD, payload, timeout, mux)
+        else:
+            payload = _build_bash_setup(base_py, reqs, force).encode("utf-8")
+            rc, out, err, _ = _ssh_run(machine, "bash -s", payload, timeout, mux)
+        if rc != 0:
+            tail = (err or out).decode("utf-8", "replace").strip()[-400:]
+            raise RuntimeError(f"setup 脚本失败(exit={rc}): {tail}")
+
+        final = probe_python(machine, [venv_py], mux)
+        if not final:
+            raise RuntimeError("setup 完成但 venv python 探测失败")
+        result.venv_python, result.version = final
+        result.packages = reqs
+        result.ok = True
+    except Exception as e:  # noqa: BLE001 - 汇总为 result，--all 继续遍历
+        result.message = str(e)
+    result.duration = time.time() - t0
+    _write_setup_audit(result)
+    return result
+
+
+def _write_setup_audit(result: SetupResult) -> None:
+    try:
+        AUDIT_LOG.parent.mkdir(parents=True, exist_ok=True)
+        record = {
+            "ts": datetime.now().isoformat(timespec="seconds"),
+            "host": result.host, "lang": "setup",
+            "exit_code": 0 if result.ok else 1,
+            "venv_python": result.venv_python, "python_version": result.version,
+            "base_python": result.base_python,
+            "created_venv": result.created_venv,
+            "installed_standalone": result.installed_standalone,
+            "packages": result.packages, "message": result.message,
+            "duration_s": round(result.duration, 2),
+        }
+        with open(AUDIT_LOG, "a", encoding="utf-8") as f:
+            import json
+            f.write(json.dumps(record, ensure_ascii=False) + "\n")
+    except OSError:
+        pass
+
+
+def venv_python_or_die(host: str, mux: bool = True) -> str:
+    """返回统一 venv 的 python 路径；未初始化则报错指路 setup。"""
+    machine = resolve_machine(host)
+    venv_py = VENV_PY_WIN if machine.is_windows else VENV_PY_POSIX
+    hit = probe_python(machine, [venv_py], mux)
+    if not hit:
+        raise RuntimeError(f"[{machine.name}] 统一 venv 未初始化，请先：rrun setup {machine.name}")
+    return hit[0]

rrun_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: rrun-cli
+Version: 0.1.0
+Summary: Run local scripts on remote machines over SSH via stdin pipes — no escaping/encoding hell. Supports python/powershell/bash, with a unified remote Python 3.12 venv provisioner.
+Author: waqiju
+License: MIT
+Project-URL: Homepage, https://github.com/waqiju/rrun
+Project-URL: Repository, https://github.com/waqiju/rrun
+Project-URL: Issues, https://github.com/waqiju/rrun/issues
+Keywords: ssh,remote-exec,powershell,windows,ops,automation
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# rrun
+
+Run local scripts on remote machines over SSH — **via stdin pipes, never via command-line arguments** — so quoting, escaping, and CJK/UTF-8 encoding survive the `bash → ssh → cmd/powershell` journey intact.
+
+```bash
+rrun exec my-win-box ./deploy.ps1          # powershell (inferred from .ps1)
+rrun exec my-mac ./build.sh                # bash
+rrun exec my-win-box ./report.py           # python (remote 3.12, -X utf8)
+rrun exec my-win-box -c "Get-Date"         # inline content (archived to ~/.rrun/drops/)
+rrun exec my-mac ./etl.py -- arg1 arg2     # ASCII args pass-through
+```
+
+Remote stdout → your stdout, remote stderr → your stderr, and the **exit code is passed through** unchanged (255 = ssh transport failure, 124 = local `--timeout`). Pipes, `&&`, and CI integration just work.
+
+## Why
+
+Running commands on remote Windows machines from a POSIX shell is a minefield: sshd lands you in `cmd` with a GBK codepage, quotes and `$` get eaten by one of three shells along the way, and any non-ASCII argument gets mojibake'd. rrun's rules:
+
+- Script content (UTF-8, Chinese welcome) is always piped through **stdin** — never the command line.
+- For PowerShell, the payload is base64-wrapped into a **single-line pure-ASCII wrapper** (`powershell -Command -` executes stdin line-by-line, multi-line fails silently), decoded and invoked as a ScriptBlock remotely.
+- Command-line arguments are restricted to ASCII and passed through safely (`sys.argv` / `$@` / `$args`). Put anything fancier in the script or a JSON file.
+
+See [docs/remote-exec-conventions.md](docs/remote-exec-conventions.md) (中文) for the full set of hard-won conventions.
+
+## Install
+
+```bash
+pipx install rrun-cli    # recommended: isolated global CLI (provides the `rrun` command)
+# or: pip install rrun-cli
+```
+
+> The PyPI distribution is named `rrun-cli` (plain `rrun` is on PyPI's prohibited-name list
+> as it's confusable with `run`), but the installed command is `rrun` — plus the legacy alias
+> `remote-machine`.
+
+Both `rrun` and the legacy alias `remote-machine` are installed.
+
+**Control machine requirements:** `ssh` + `sshpass` (`sudo apt install sshpass`), Python ≥ 3.10. Zero third-party Python dependencies.
+**Remote machines:** OpenSSH server. Windows remotes execute via PowerShell; Mac/Linux via bash.
+
+## Configuration: machines.json
+
+Credentials live in a local `machines.json` (never committed — it's a local file, `chmod 600` recommended). See [machines.template.json](machines.template.json):
+
+```json
+{
+  "defaults": { "windows": { "os": "Windows" } },
+  "machines": [
+    { "name": "my-win-box", "ip": "192.168.1.10", "os": "Windows",
+      "user": "admin", "password": "secret" }
+  ]
+}
+```
+
+Sources are merged by machine name, highest priority first (all optional, failures skipped silently):
+
+1. `$RRUN_CONFIG` (os.pathsep-separated, multiple files allowed)
+2. `$REMOTE_MACHINE_CONFIG` (legacy name, still honored)
+3. `./machines.json` (current working directory)
+4. `~/.rrun/machines.json`
+5. `~/.rrun/machines.d/*.json` (sorted by filename — point each inventory at its own file/symlink)
+6. Legacy: `~/.remote-machine/machines.json` (POSIX) / `C:\tools\remote-machine\machines.json` (Windows)
+
+Per-file `defaults` sections (keyed by `os`, lowercased) are applied before merging. Inspect the chain with `rrun config`; list machines (redacted) with `rrun machines`.
+
+## Subcommands
+
+| Command | Purpose |
+|---|---|
+| `rrun exec <host> <script\|-c ...>` | Execute a local script / inline content remotely |
+| `rrun machines [--json]` | List merged machines (redacted, with source) |
+| `rrun config` | Diagnose the machines.json source chain |
+| `rrun setup <host\|--all> [--force]` | Provision the unified remote Python 3.12 venv (idempotent) |
+| `rrun pip <host> -- list` | Run pip inside the remote unified venv |
+| `rrun close [<host>\|--all]` | Close ssh ControlMaster multiplexed connections |
+
+Useful `exec` flags: `--lang bash|powershell|python`, `--workdir`, `--env K=V`, `--timeout`, `--python <path>` (skip detection), `--no-mux`, `-q`.
+
+## Remote Python: unified 3.12 environment
+
+For `python` scripts, rrun requires a **3.12.x** interpreter on the remote, probed in order:
+
+1. Unified venv: `C:\tools\remote-machine\venv\Scripts\python.exe` / `~/.remote-machine/venv/bin/python`
+2. Standalone base: `...\python312\python.exe` / `~/.remote-machine/python312/bin/python3`
+3. Existing installs: `C:\Python\Python312\python.exe` / `python3.12` on PATH
+
+If none match, run `rrun setup <host>`. It is idempotent and non-destructive: if the machine lacks Python 3.12, a [python-build-standalone](https://github.com/astral-sh/python-build-standalone) tarball is downloaded to the local cache (`~/.cache/rrun/`) and streamed over ssh stdin — no registry, no PATH changes, no admin rights, and the remote never touches GitHub. The venv gets an Alibaba Cloud pip mirror in its own `pip.ini`/`pip.conf` (global config untouched) plus the standard packages from `remote-requirements.txt` (override with `~/.rrun/remote-requirements.txt`).
+
+## Auditing & state
+
+- Every execution appends a JSON line to `~/.rrun/log/remote-exec.jsonl` (host, lang, script sha1, exit code, duration — never passwords; env vars recorded as keys only).
+- Inline `-c` payloads are archived under `~/.rrun/drops/` for replay.
+- Root directory overridable via `$RRUN_HOME`.
+
+---
+
+## 中文简介
+
+rrun 解决「从 POSIX shell 在远程机器（尤其 Windows）执行脚本」的转码/转义地狱：
+脚本内容一律走 **stdin 管道**（UTF-8，中文随便用），命令行参数只放行 ASCII；
+PowerShell 载荷编码为单行纯 ASCII wrapper，退出码原样透传。
+
+- 安装：`pipx install rrun-cli`（控制端需 `ssh` + `sshpass`；装好后命令是 `rrun`）
+- 机器清单 `machines.json` 来源链：`$RRUN_CONFIG` → `./machines.json` → `~/.rrun/machines.json` → `~/.rrun/machines.d/*.json` → 旧位置兼容
+- 远程 python 基线锁 3.12，`rrun setup <host>` 一键幂等初始化统一 venv（standalone 基座经 ssh 推流安装，远端无需访问 GitHub，pip 走阿里云镜像）
+- 更多踩坑约定见 [docs/remote-exec-conventions.md](docs/remote-exec-conventions.md)
+
+## License
+
+MIT

rrun_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+rrun/__init__.py,sha256=C4Ur90ge4OBnk3hX38tFDuuCM528mqjyVHSmka8bUJI,1259
+rrun/__main__.py,sha256=UaSliJmYrpnp-R-CtnKRFdWqdu4IOrYJN4Q5qpWcowM,12967
+rrun/executor.py,sha256=E9kpzHO12p7ctSO414hv0itlJn8FOLPi-zhV5AzDwY8,15639
+rrun/registry.py,sha256=GJ0t9M6oIm6QxaIn2A2VDiSOi6Od7YeMyPuEpHt2DLc,6507
+rrun/remote-requirements.txt,sha256=ycll-CCbCZf2DwFzd5Uxa3ew81syJ9U_X25oqSs4GUE,218
+rrun/setup.py,sha256=C9clIXFx2geBzLKm2VdyM7c1A-XUArYQue-U1VYcHuc,11318
+rrun_cli-0.1.0.dist-info/licenses/LICENSE,sha256=u41jhONFUIF6jMQ2_7smPk0EO7D5lpA1SCvO3cNIhnU,1063
+rrun_cli-0.1.0.dist-info/METADATA,sha256=-M9zMRzC0Y6iOmoYHeblowJjFciqt0MgNPY5VFnH6Co,7261
+rrun_cli-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+rrun_cli-0.1.0.dist-info/entry_points.txt,sha256=QA2kQPFQxiDG3QcazF2mCDosr7xE9p6bVFp3TfKkH8Q,80
+rrun_cli-0.1.0.dist-info/top_level.txt,sha256=q7vXzinYW5Xp1_paTQImU_kQqzowXRYP7YsT2q1SsOQ,5
+rrun_cli-0.1.0.dist-info/RECORD,,

rrun_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

rrun_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+remote-machine = rrun.__main__:main
+rrun = rrun.__main__:main

rrun_cli-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 waqiju
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

rrun_cli-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+rrun