proxyctl 0.4.5__tar.gz → 0.4.7__tar.gz

{proxyctl-0.4.5 → proxyctl-0.4.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: proxyctl
-Version: 0.4.5
+Version: 0.4.7
 Summary: Proxy configuration lifecycle management for macOS and Linux
 Project-URL: Homepage, https://github.com/crhan/proxyctl
 Project-URL: Issues, https://github.com/crhan/proxyctl/issues
@@ -193,7 +193,7 @@ uv tool install proxyctl                # uv（推荐）
 pipx install proxyctl                   # 或 pipx
 pip install --user proxyctl             # 或 pip
 
-proxyctl --version                      # → proxyctl v0.4.3
+proxyctl --version                      # → proxyctl v0.4.7
 proxyctl --help
 ```
 

{proxyctl-0.4.5 → proxyctl-0.4.7}/README.md

@@ -164,7 +164,7 @@ uv tool install proxyctl                # uv（推荐）
 pipx install proxyctl                   # 或 pipx
 pip install --user proxyctl             # 或 pip
 
-proxyctl --version                      # → proxyctl v0.4.3
+proxyctl --version                      # → proxyctl v0.4.7
 proxyctl --help
 ```
 

{proxyctl-0.4.5 → proxyctl-0.4.7}/man/proxyctl.1

@@ -1,4 +1,4 @@
-.TH PROXYCTL 1 "2026-05" "proxyctl 0.4.5" "User Commands"
+.TH PROXYCTL 1 "2026-05" "proxyctl 0.4.7" "User Commands"
 .SH NAME
 proxyctl \- Proxy configuration lifecycle management for macOS / Linux
 .SH SYNOPSIS

{proxyctl-0.4.5 → proxyctl-0.4.7}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "proxyctl"
-version = "0.4.5"
+version = "0.4.7"
 description = "Proxy configuration lifecycle management for macOS and Linux"
 readme = "README.md"
 requires-python = ">=3.10"

{proxyctl-0.4.5 → proxyctl-0.4.7}/src/proxyctl/cli.py

@@ -6,6 +6,7 @@
                mode|audit|trace|bench|dns-lock|dns-unlock]
 """
 
+import functools
 import json
 import os
 import platform
@@ -250,6 +251,69 @@ def run_out(cmd: list, *, sudo: bool = False) -> str:
     return r.stdout.strip() if r.returncode == 0 else ""
 
 
+@functools.lru_cache(maxsize=4)
+def get_engine_version(backend_name: str) -> dict | None:
+    """运行 `<backend> -v` 解析引擎版本信息。
+
+    proxyctl 是引擎生命周期管理器，但之前没在任何 status 里显示引擎版本——
+    导致 debug TUIC / DNS 问题时无法快速判定"是不是引擎版本 regression"。
+    本函数填补此缺陷（v0.4.7+）。
+
+    Args:
+        backend_name: "mihomo" / "singbox" / 等等。
+
+    Returns:
+        dict 或 None（binary 找不到 / -v 失败 / 解析失败）:
+            {
+              "binary":     "/opt/homebrew/bin/mihomo",
+              "version":    "1.19.25",
+              "platform":   "darwin arm64",
+              "go_version": "1.26.3",
+              "build_date": "2026-05-16",
+              "raw":        "Mihomo Meta 1.19.25 darwin arm64 with go1.26.3 2026-05-16T14:37:07Z",
+            }
+
+    mihomo -v 输出范本:
+        Mihomo Meta 1.19.25 darwin arm64 with go1.26.3 2026-05-16T14:37:07Z
+        Use tags: with_gvisor
+
+    sing-box version 输出范本 (供后续扩展):
+        sing-box version 1.10.0
+        Environment: go1.22.5 darwin/arm64
+        Tags: ...
+
+    LRU cache 4 项：避免每次 status 都跑 subprocess（同进程内常量）。
+    """
+    import shutil
+    import re
+    binary = shutil.which(backend_name)
+    if not binary:
+        return None
+    try:
+        r = subprocess.run([binary, "-v"], capture_output=True, text=True, timeout=3)
+    except (subprocess.TimeoutExpired, OSError):
+        return None
+    out = (r.stdout or "").strip()
+    if not out or r.returncode != 0:
+        return None
+    raw = out.split("\n", 1)[0].strip()
+    info: dict = {"binary": binary, "raw": raw}
+    # 匹配 mihomo: "Mihomo Meta 1.19.25 darwin arm64 with go1.26.3 2026-05-16T14:37:07Z"
+    m = re.match(
+        r"^\S+\s+\S+\s+(\S+)\s+(\S+\s+\S+)\s+with\s+go(\S+)\s+(\S+)",
+        raw,
+    )
+    if m:
+        info["version"] = m.group(1)
+        info["platform"] = m.group(2)
+        info["go_version"] = m.group(3)
+        info["build_date"] = m.group(4).split("T")[0]
+    else:
+        # 兜底：能拿到 raw 就行，version 字段留空让 agent 自己处理
+        info["version"] = None
+    return info
+
+
 def wait_port(port: int, timeout: float = 10.0) -> bool:
     """轮询直到 127.0.0.1:port 就绪，超时返回 False。"""
     deadline = time.monotonic() + timeout
@@ -1584,6 +1648,7 @@ def cmd_version_print() -> None:
                 "lifecycle_dry_run":       True,   # 0.4.2: start/stop/restart/recover --dry-run
                 "version_subcommand":      True,   # 0.4.2: `proxyctl version` 子命令
                 "status_subscription":     True,   # 0.4.4: status envelope.data.subscription
+                "engine_version":          True,   # 0.4.7: status/doctor data.engine_version (mihomo -v)
             },
         }
         _io.emit_json(_io.envelope("version", data=data))

{proxyctl-0.4.5 → proxyctl-0.4.7}/src/proxyctl/explain.py

@@ -119,7 +119,9 @@ def _t_engine(backend, config) -> TopicCard:
         "topic": "engine",
         "summary": (
             f"代理引擎（后端）。当前：{backend.name}。"
-            "支持 mihomo / sing-box；通过 proxyctl engine <name> 切换后端，"
+            "支持 mihomo（首发，端到端验证）/ sing-box（预留，未端到端验证 — "
+            "类 / 路径 / audit / trace 解析已实现，但完整启停闭环未跑过生产）；"
+            "通过 proxyctl engine <name> 切换后端，"
             "通过 proxyctl mode <tun|proxy> 切换流量入站方式。"
         ),
         "file": f"{backend.config_file}",
@@ -997,7 +999,7 @@ COMMANDS_META: list[dict] = [
      "supports_json": False, "side_effects": ["config-write"],
      "supports_dry_run": True,
      "needs_sudo": True, "interactive": False,
-     "exit_codes": [0, 1, 2, 4, 6, 8],
+     "exit_codes": [0, 1, 2],
      "examples": ["proxyctl mode tun", "proxyctl mode tun --dry-run"]},
     {"name": "engine", "group": "config", "summary": "切换代理引擎后端",
      "args": [{"name": "target", "choices": ["mihomo", "singbox"], "required": False}],
@@ -1441,7 +1443,7 @@ def cmd_doctor(args: list, backend, config) -> None:
     as_json = GLOBAL_FLAGS_REF().get("json", False)
 
     # 从 cli.py 复用 service_running，但为避免循环 import 在这里独立判断
-    from proxyctl.cli import service_running, get_mode
+    from proxyctl.cli import service_running, get_mode, get_engine_version
     port = config.get("proxy_port", 7890)
     api_base = config.get("api_base", "http://127.0.0.1:9090")
 
@@ -1480,6 +1482,7 @@ def cmd_doctor(args: list, backend, config) -> None:
         "hint": hint,
         # informational fields (W15 in 0.3.0):
         "engine": backend.name,
+        "engine_version": get_engine_version(backend.name),  # v0.4.7+, None 即未知
         "mode": mode_str,
         "port": port,
         "config_path": _io_proxyctl_config_path(),
@@ -1495,8 +1498,10 @@ def cmd_doctor(args: list, backend, config) -> None:
         sys.exit(code)
 
     icon = lambda b: f"{GREEN}✓{NC}" if b else f"{RED}✗{NC}"
+    ev = data.get("engine_version") or {}
+    ev_tag = f" v{ev['version']}" if ev.get("version") else ""
     print(f"{BOLD}proxyctl doctor{NC}  ({score}/{len(flags)})  "
-          f"{DIM}engine={backend.name} mode={mode_str} port={port}{NC}")
+          f"{DIM}engine={backend.name}{ev_tag} mode={mode_str} port={port}{NC}")
     print(f"  {icon(engine_up)}  engine_up        ({backend.name} 服务运行中)")
     print(f"  {icon(port_listen)}  port_listen      (127.0.0.1:{port})")
     print(f"  {icon(dns_ok)}  dns_ok           (系统 DNS 含 127.0.0.1)")

{proxyctl-0.4.5 → proxyctl-0.4.7}/src/proxyctl/status.py

@@ -16,6 +16,7 @@ GREEN  = "\033[0;32m"
 YELLOW = "\033[0;33m"
 CYAN   = "\033[0;36m"
 BOLD   = "\033[1m"
+DIM    = "\033[2m"
 NC     = "\033[0m"
 
 from proxyctl._io import maybe_disable_module_colors as _pc_maybe_disable
@@ -68,7 +69,10 @@ def _ifconfig_ip(iface: str) -> str:
 # ── 数据采集函数（可并发） ────────────────────────────────────────────────────
 
 def _gather_engine(engine) -> dict:
-    """采集引擎进程信息：PID、运行次数、运行时间。"""
+    """采集引擎进程信息：PID、运行次数、运行时间、版本（v0.4.7+）。"""
+    from proxyctl.cli import get_engine_version
+    version_info = get_engine_version(engine.name)  # None / dict
+
     if IS_LINUX:
         # systemd --user：用 systemctl show 获取 PID
         r = subprocess.run(
@@ -83,7 +87,8 @@ def _gather_engine(engine) -> dict:
             r2 = subprocess.run(["ps", "-o", "etime=", "-p", pid],
                                 capture_output=True, text=True)
             etime = r2.stdout.strip()
-        return {"pid": pid, "runs": runs, "daemon_up": daemon_up, "etime": etime}
+        return {"pid": pid, "runs": runs, "daemon_up": daemon_up,
+                "etime": etime, "version": version_info}
 
     # macOS: launchctl
     pid   = _launchctl_pid(engine.label)
@@ -94,7 +99,8 @@ def _gather_engine(engine) -> dict:
         r = subprocess.run(["ps", "-o", "etime=", "-p", pid],
                            capture_output=True, text=True)
         etime = r.stdout.strip()
-    return {"pid": pid, "runs": runs, "daemon_up": daemon_up, "etime": etime}
+    return {"pid": pid, "runs": runs, "daemon_up": daemon_up,
+            "etime": etime, "version": version_info}
 
 
 def _gather_ports(claude_proxy_label: str,
@@ -312,7 +318,14 @@ def _print_engine(engine, mode: str, d_engine: dict, d_ports: dict):
     else:
         mode_tag = f"{YELLOW}{mode}{NC}"
 
-    print(f"{BOLD}引擎{NC}  {GREEN}{engine.name}{NC} · {mode_tag}")
+    # 引擎名 + 模式 + 版本号（v0.4.7+，引擎 binary 找不到时只显示名字）
+    ver = d_engine.get("version") or {}
+    ver_str = ""
+    if ver.get("version"):
+        ver_str = f" {DIM}v{ver['version']}{NC}"
+        if ver.get("build_date"):
+            ver_str += f" {DIM}({ver['build_date']}, go{ver.get('go_version','?')}){NC}"
+    print(f"{BOLD}引擎{NC}  {GREEN}{engine.name}{NC}{ver_str} · {mode_tag}")
 
     if d_engine["daemon_up"]:
         runs_str = (f"  {YELLOW}runs={d_engine['runs']}{NC}"