proxyctl 0.1.0__py3-none-any.whl

proxyctl/cli.py

@@ -0,0 +1,1355 @@
+"""proxyctl — Proxy configuration lifecycle management
+
+支持 Mihomo 后端（首发）/ Sing-box 后端（预留）
+
+用法：proxyctl [start|stop|restart|status|log|check|fix|recover|
+               mode|audit|trace|bench|dns-lock|dns-unlock]
+"""
+
+import json
+import os
+import platform
+import re
+import socket
+import subprocess
+import sys
+import time
+
+# ── 平台检测 ────────────────────────────────────────────────────────────────
+PLATFORM = platform.system()   # "Darwin" | "Linux"
+IS_MACOS = PLATFORM == "Darwin"
+IS_LINUX = PLATFORM == "Linux"
+
+# ── 路径常量 ────────────────────────────────────────────────────────────────
+HOME = os.path.expanduser("~")
+DEFAULT_CONFIG_DIR = os.path.join(HOME, ".config", "proxyctl")
+CONFIG_FILE = os.path.join(DEFAULT_CONFIG_DIR, "config.yaml")
+
+# 默认后端：mihomo（首发支持）
+DEFAULT_BACKEND = "mihomo"
+
+# ── 颜色 ────────────────────────────────────────────────────────────────────
+RED = "\033[0;31m"
+GREEN = "\033[0;32m"
+YELLOW = "\033[0;33m"
+CYAN = "\033[0;36m"
+BOLD = "\033[1m"
+NC = "\033[0m"
+
+# ── 默认配置（可通过 config.yaml 覆盖）───────────────────────────────────────
+DEFAULTS = {
+    "backend": "mihomo",  # mihomo | singbox
+    "api_base": "http://127.0.0.1:9090",
+    "api_secret": "",     # 必填：Clash API Bearer token
+    "config_dir": os.path.join(HOME, ".config"),
+    "dns_lock_label": "com.proxyctl.dns-lock",
+}
+
+SCRIPTS_DIR = os.path.dirname(os.path.realpath(__file__))
+USER_PLUGIN_DIR = os.path.join(DEFAULT_CONFIG_DIR, "plugins")
+
+
+def load_config() -> dict:
+    """加载配置文件，返回合并后的配置字典。"""
+    cfg = DEFAULTS.copy()
+    if os.path.isfile(CONFIG_FILE):
+        try:
+            import yaml
+            with open(CONFIG_FILE) as f:
+                user_cfg = yaml.safe_load(f) or {}
+            cfg.update(user_cfg)
+        except Exception as e:
+            print(f"{YELLOW}警告：读取配置文件失败：{e}{NC}")
+            print(f"  使用默认配置，可能需要在 {CONFIG_FILE} 中配置 api_secret")
+    return cfg
+
+
+# ── 后端类 ───────────────────────────────────────────────────────────────────
+
+class Backend:
+    """后端抽象基类，封装引擎名称、路径和平台差异。"""
+
+    def __init__(self, name: str, config: dict):
+        self.name = name
+        self.config = config
+        self.config_dir = config.get("config_dir", os.path.join(HOME, ".config"))
+
+    @property
+    def label(self) -> str:
+        """macOS launchctl service label。"""
+        raise NotImplementedError
+
+    @property
+    def plist(self) -> str:
+        """macOS LaunchDaemon plist 路径。"""
+        raise NotImplementedError
+
+    @property
+    def unit(self) -> str:
+        """Linux systemd user service unit 名称。"""
+        raise NotImplementedError
+
+    @property
+    def config_file(self) -> str:
+        raise NotImplementedError
+
+    @property
+    def cache_file(self) -> str:
+        raise NotImplementedError
+
+    @property
+    def log_file(self) -> str:
+        raise NotImplementedError
+
+
+class MihomoBackend(Backend):
+    """Mihomo (Clash) 后端实现"""
+
+    def __init__(self, config: dict):
+        super().__init__("mihomo", config)
+
+    @property
+    def label(self) -> str:
+        return "system/com.mihomo.tun"
+
+    @property
+    def plist(self) -> str:
+        return "/Library/LaunchDaemons/com.mihomo.tun.plist"
+
+    @property
+    def unit(self) -> str:
+        return "mihomo.service"
+
+    @property
+    def config_file(self) -> str:
+        return os.path.join(self.config_dir, "mihomo", "config.yaml")
+
+    @property
+    def cache_file(self) -> str:
+        return os.path.join(self.config_dir, "mihomo", "cache.db")
+
+    @property
+    def log_file(self) -> str:
+        return os.path.join(self.config_dir, "mihomo", "mihomo.log")
+
+
+class SingboxBackend(Backend):
+    """Sing-box 后端实现"""
+
+    def __init__(self, config: dict):
+        super().__init__("singbox", config)
+
+    @property
+    def label(self) -> str:
+        return "system/com.singbox.tun"
+
+    @property
+    def plist(self) -> str:
+        return "/Library/LaunchDaemons/com.singbox.tun.plist"
+
+    @property
+    def unit(self) -> str:
+        return "sing-box.service"
+
+    @property
+    def config_file(self) -> str:
+        return os.path.join(self.config_dir, "sing-box", "config.json")
+
+    @property
+    def cache_file(self) -> str:
+        return os.path.join(self.config_dir, "sing-box", "cache.db")
+
+    @property
+    def log_file(self) -> str:
+        return os.path.join(self.config_dir, "sing-box", "sing-box.log")
+
+
+def get_backend(config: dict) -> Backend:
+    """根据配置返回后端实例。"""
+    backend_name = config.get("backend", DEFAULT_BACKEND)
+    if backend_name == "mihomo":
+        return MihomoBackend(config)
+    else:
+        return SingboxBackend(config)
+
+
+# ── 插件加载 ─────────────────────────────────────────────────────────────────
+
+def load_plugins(config: dict):
+    """加载内置 + 用户插件目录，返回 registry。
+
+    用户禁用某插件：在 config.yaml 加 `plugins_disabled: [name1, name2]`。
+    用户插件目录：~/.config/proxyctl/plugins/*.py
+    """
+    from proxyctl.core.plugin import build_registry
+    return build_registry(config, USER_PLUGIN_DIR)
+
+
+def cmd_plugins(registry):
+    """proxyctl plugins — 显示已加载插件 + 加载期错误。"""
+    print(f"{BOLD}插件列表{NC}  (内置 + ~/.config/proxyctl/plugins/)")
+    if not registry.plugins and not registry.errors:
+        print(f"  {YELLOW}—{NC} 无已加载插件")
+    for p in registry.plugins:
+        # 简略列出该插件实现了哪些 hook（识别 dataclass 返回的方法）
+        hook_names = [
+            "check_groups", "check_targets", "check_outbound_probes",
+            "dns_hooks", "route_hooks", "status_sections",
+            "watchdog_layers", "audit_skip_hosts", "audit_known_proxy_kw",
+        ]
+        active = []
+        for h in hook_names:
+            method = getattr(type(p), h, None)
+            base_method = getattr(__import__("proxyctl.core.plugin",
+                                              fromlist=["Plugin"]).Plugin, h)
+            # 比较函数对象，子类覆盖才算 active
+            if method is not None and method is not base_method:
+                active.append(h)
+        active_str = ", ".join(active) if active else "(no hooks)"
+        print(f"  {GREEN}✓{NC} {CYAN}{p.name or type(p).__name__}{NC}  "
+              f"[{type(p).__module__}]  {active_str}")
+    if registry.errors:
+        print(f"\n{YELLOW}加载错误:{NC}")
+        for source, err in registry.errors:
+            print(f"  {RED}✗{NC} {source}  {err}")
+    print(f"\n用户插件目录: {USER_PLUGIN_DIR}")
+    if not os.path.isdir(USER_PLUGIN_DIR):
+        print(f"  {YELLOW}—{NC} 目录不存在（首次使用请 mkdir -p）")
+
+
+# ── 基础工具 ─────────────────────────────────────────────────────────────────
+
+def run(cmd: list, *, sudo: bool = False, check: bool = False,
+        capture: bool = False, stdin_text: str = None) -> subprocess.CompletedProcess:
+    """执行系统命令。sudo=True 自动加 sudo，capture=True 返回文本输出。"""
+    if sudo:
+        cmd = ["sudo"] + cmd
+    kw: dict = {"check": check}
+    if capture:
+        kw["capture_output"] = True
+        kw["text"] = True
+    if stdin_text is not None:
+        kw["input"] = stdin_text
+        kw["text"] = True
+    return subprocess.run(cmd, **kw)
+
+
+def run_out(cmd: list, *, sudo: bool = False) -> str:
+    """执行命令，返回 stdout；失败返回空字符串。"""
+    r = run(cmd, sudo=sudo, capture=True)
+    return r.stdout.strip() if r.returncode == 0 else ""
+
+
+def wait_port(port: int, timeout: float = 10.0) -> bool:
+    """轮询直到 127.0.0.1:port 就绪，超时返回 False。"""
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        try:
+            with socket.create_connection(("127.0.0.1", port), timeout=0.5):
+                return True
+        except OSError:
+            time.sleep(0.3)
+    return False
+
+
+def list_network_services() -> list:
+    """返回系统所有网络服务名称（过滤掉 * 前缀的禁用项）。"""
+    out = run_out(["networksetup", "-listallnetworkservices"])
+    return [s for s in out.splitlines()[1:] if not s.startswith("*")]
+
+
+def launchctl_running(label: str, *, sudo: bool = False) -> bool:
+    """检查 launchctl 服务是否在运行（仅 macOS）。"""
+    r = run(["launchctl", "print", label], sudo=sudo, capture=True)
+    return r.returncode == 0
+
+
+# ── 平台感知的服务管理 ──────────────────────────────────────────────────────
+
+def service_running(backend: Backend) -> bool:
+    """检查引擎服务是否在运行。"""
+    if IS_MACOS:
+        return launchctl_running(backend.label)
+    r = run(["systemctl", "--user", "is-active", "--quiet", backend.unit], capture=True)
+    return r.returncode == 0
+
+
+def service_start(backend: Backend, config: dict) -> subprocess.CompletedProcess:
+    """启动引擎服务。
+
+    Args:
+        backend: 后端实例
+        config: 全局配置（macOS 需要定位 plist 源文件）
+
+    Returns:
+        subprocess.CompletedProcess
+    """
+    if IS_MACOS:
+        if not os.path.isfile(backend.plist):
+            src = os.path.join(DEFAULT_CONFIG_DIR, "launchdaemons",
+                               os.path.basename(backend.plist))
+            if not os.path.isfile(src):
+                print(f"{RED}✗{NC} plist 源文件不存在：{src}")
+                sys.exit(1)
+            run(["cp", src, backend.plist], sudo=True)
+        return run(["launchctl", "bootstrap", "system", backend.plist],
+                   sudo=True, capture=True)
+    return run(["systemctl", "--user", "start", backend.unit], capture=True)
+
+
+def service_stop(backend: Backend) -> subprocess.CompletedProcess:
+    """停止引擎服务。"""
+    if IS_MACOS:
+        return run(["launchctl", "bootout", backend.label], sudo=True, capture=True)
+    return run(["systemctl", "--user", "stop", backend.unit], capture=True)
+
+
+def service_restart(backend: Backend) -> subprocess.CompletedProcess:
+    """重启引擎服务。"""
+    if IS_MACOS:
+        return run(["launchctl", "kickstart", "-k", backend.label],
+                   sudo=True, capture=True)
+    return run(["systemctl", "--user", "restart", backend.unit], capture=True)
+
+
+def scutil_exec(script: str):
+    """向 sudo scutil stdin 写入脚本并执行。"""
+    run(["scutil"], sudo=True, stdin_text=script)
+
+
+def get_mode(backend: Backend) -> str:
+    """从配置文件读取当前模式 (tun/proxy/mixed/unknown)。"""
+    try:
+        if backend.name == "mihomo":
+            text = open(backend.config_file).read()
+            tun_m = re.search(r'^tun:\s*\n((?:\s+.*\n)*)', text, re.M)
+            tun_block = tun_m.group(0) if tun_m else ""
+            tun_on = bool(re.search(r'enable:\s*true', tun_block))
+            auto_rt = bool(re.search(r'auto-route:\s*true', tun_block))
+            fakeip = bool(re.search(r'enhanced-mode:\s*fake-ip', text))
+            if tun_on and auto_rt and fakeip:
+                return "tun"
+            elif not auto_rt and not fakeip:
+                return "proxy"
+            return "mixed"
+        else:
+            cfg = json.load(open(backend.config_file))
+            ar = True
+            for ib in cfg.get("inbounds", []):
+                if ib.get("type") == "tun":
+                    ar = ib.get("auto_route", True)
+                    break
+            fakeip = any(r.get("server") == "fakeip-dns"
+                         for r in cfg.get("dns", {}).get("rules", []))
+            if ar and fakeip:
+                return "tun"
+            elif not ar and not fakeip:
+                return "proxy"
+            return "mixed"
+    except Exception:
+        return "unknown"
+
+
+def get_primary_resolver() -> str:
+    """返回 scutil --dns resolver #1 的第一个 nameserver。"""
+    r = subprocess.run(["scutil", "--dns"], capture_output=True, text=True)
+    in_r1 = False
+    for line in r.stdout.splitlines():
+        if "resolver #1" in line:
+            in_r1 = True
+        if in_r1 and "nameserver[0]" in line:
+            return line.split()[-1]
+    return ""
+
+
+# ── DNS 联动 ─────────────────────────────────────────────────────────────────
+
+def dns_activate(config: dict):
+    """设置系统 DNS → 127.0.0.1（三层防线）。
+
+    Args:
+        config: 全局配置字典，层 2 的 domain fallback 从 corp_dns.domain 读取
+    """
+    # 层 1: networksetup 对抗 DHCP
+    for svc in list_network_services():
+        run(["networksetup", "-setdnsservers", svc, "127.0.0.1"])
+
+    # 层 2: 劫持 AnyConnect 自己的 DNS 条目
+    ac_key = "State:/Network/Service/com.cisco.anyconnect/DNS"
+    r = subprocess.run(["sudo", "scutil"], input=f"show {ac_key}\n",
+                       capture_output=True, text=True)
+    if "ServerAddresses" in r.stdout:
+        domain = search_order = ""
+        for line in r.stdout.splitlines():
+            if "DomainName" in line and ":" in line and not domain:
+                domain = line.split(":", 1)[1].strip()
+            elif "SearchOrder" in line and ":" in line and not search_order:
+                search_order = line.split(":", 1)[1].strip()
+        corp = config.get("corp_dns", {}) or {}
+        domain = domain or corp.get("domain", "") or "example.com"
+        search_order = search_order or "1"
+        scutil_exec(
+            f"d.init\n"
+            f"d.add DomainName {domain}\n"
+            f"d.add SearchDomains * {domain}\n"
+            f"d.add SearchOrder # {search_order}\n"
+            f"d.add ServerAddresses * 127.0.0.1\n"
+            f"d.add SupplementalMatchDomains * \"\" {domain}\n"
+            f"set {ac_key}\n"
+        )
+
+    # 层 3: scutil 兜底 order:0
+    scutil_exec(
+        "d.init\n"
+        "d.add ServerAddresses * 127.0.0.1\n"
+        "d.add SupplementalMatchOrder # 0\n"
+        "set State:/Network/Service/proxyctl-dns-override/DNS\n"
+    )
+
+    run(["dscacheutil", "-flushcache"], sudo=True)
+    run(["killall", "-HUP", "mDNSResponder"], sudo=True)
+
+
+def dns_deactivate(config: dict):
+    """还原系统 DNS（清除三层注入）。
+
+    静态 IP 和 DHCP 环境均安全：层 1 仅清除手动 DNS 设置，
+    不影响静态配置中已有的 DNS；层 3 根据 corp_dns 配置决定
+    还原为企业 DNS 或直接移除 AnyConnect key。
+
+    Args:
+        config: 全局配置字典，corp_dns.server 用于 AnyConnect DNS 还原
+    """
+    # 层 1: 清空手动 DNS（networksetup -setdnsservers <svc> empty
+    # 效果：移除手动覆盖，恢复为网络服务自身的 DNS 来源——DHCP 或静态配置均可）
+    for svc in list_network_services():
+        run(["networksetup", "-setdnsservers", svc, "empty"])
+
+    # 层 2: 删除 scutil 兜底 resolver
+    scutil_exec("remove State:/Network/Service/proxyctl-dns-override/DNS\n")
+
+    # 层 3: 还原 AnyConnect DNS key（如果还指向 127.0.0.1）
+    ac_key = "State:/Network/Service/com.cisco.anyconnect/DNS"
+    r = subprocess.run(["sudo", "scutil"], input=f"show {ac_key}\n",
+                       capture_output=True, text=True)
+    addr = ""
+    for line in r.stdout.splitlines():
+        if "0 :" in line:
+            addr = line.split(":", 1)[1].strip()
+            break
+    if addr == "127.0.0.1":
+        corp = config.get("corp_dns", {}) or {}
+        corp_server = corp.get("server", "")
+        if corp_server:
+            # 有企业 DNS 配置：还原为企业 DNS 地址
+            corp_v6 = corp.get("server_v6", "")
+            corp_domain = corp.get("domain", "") or "example.com"
+            addrs = f"{corp_server} {corp_v6}" if corp_v6 else corp_server
+            scutil_exec(
+                "d.init\n"
+                f"d.add ServerAddresses * {addrs}\n"
+                f"d.add DomainName {corp_domain}\n"
+                f"d.add SearchDomains * {corp_domain}\n"
+                "d.add SearchOrder # 1\n"
+                f"d.add SupplementalMatchDomains * \"\" {corp_domain}\n"
+                f"set {ac_key}\n"
+            )
+        else:
+            # 无企业 DNS 配置：直接移除 key，vpnagentd 重连时会自动重建
+            scutil_exec(f"remove {ac_key}\n")
+
+    run(["dscacheutil", "-flushcache"], sudo=True)
+    run(["killall", "-HUP", "mDNSResponder"], sudo=True)
+
+
+def dns_lock_start(config: dict):
+    """启动 dns-lock watchdog daemon（仅 macOS）。"""
+    if not IS_MACOS:
+        return
+    dns_lock_label = config.get("dns_lock_label", DEFAULTS["dns_lock_label"])
+    dns_lock_plist_src = os.path.join(DEFAULT_CONFIG_DIR, "launchdaemons", f"{dns_lock_label}.plist")
+    dns_lock_plist = f"/Library/LaunchDaemons/{dns_lock_label}.plist"
+
+    if os.path.isfile(dns_lock_plist) and not launchctl_running(f"system/{dns_lock_label}"):
+        run(["launchctl", "bootstrap", "system", dns_lock_plist], sudo=True)
+
+
+def dns_lock_stop(config: dict):
+    """停止 dns-lock watchdog daemon（仅 macOS）。"""
+    if not IS_MACOS:
+        return
+    dns_lock_label = config.get("dns_lock_label", DEFAULTS["dns_lock_label"])
+    if launchctl_running(f"system/{dns_lock_label}"):
+        run(["launchctl", "bootout", f"system/{dns_lock_label}"], sudo=True)
+
+
+# ── 系统代理联动 ──────────────────────────────────────────────────────────────
+
+def proxy_activate():
+    """设置系统 HTTP/HTTPS/SOCKS 代理 → 127.0.0.1:7890。"""
+    for svc in list_network_services():
+        run(["networksetup", "-setwebproxy", svc, "127.0.0.1", "7890"])
+        run(["networksetup", "-setsecurewebproxy", svc, "127.0.0.1", "7890"])
+        run(["networksetup", "-setsocksfirewallproxy", svc, "127.0.0.1", "7890"])
+        run(["networksetup", "-setwebproxystate", svc, "on"])
+        run(["networksetup", "-setsecurewebproxystate", svc, "on"])
+        run(["networksetup", "-setsocksfirewallproxystate", svc, "on"])
+
+
+def proxy_deactivate():
+    """关闭系统代理。"""
+    for svc in list_network_services():
+        run(["networksetup", "-setwebproxystate", svc, "off"])
+        run(["networksetup", "-setsecurewebproxystate", svc, "off"])
+        run(["networksetup", "-setsocksfirewallproxystate", svc, "off"])
+
+
+# ── 引擎启停共用逻辑 ──────────────────────────────────────────────────────────
+
+def _wait_ready(backend: Backend):
+    """等待引擎端口就绪。
+
+    macOS：等 DNS(53) + 代理(7890)，因为可能启用 TUN/fakeip。
+    Linux（最小集）：只等代理(7890)，不劫持 DNS。
+    """
+    if IS_MACOS:
+        wait_port(53, timeout=10)
+    wait_port(7890, timeout=10)
+    time.sleep(3)
+
+
+# ── 命令：start ───────────────────────────────────────────────────────────────
+
+def cmd_start(backend: Backend, config: dict):
+    r = service_start(backend, config)
+    if r.returncode != 0:
+        print(f"{RED}✗{NC} {backend.name} 启动失败")
+        print(r.stderr if r.stderr else "")
+        sys.exit(1)
+
+    print(f"{backend.name} started")
+    _wait_ready(backend)
+
+    if IS_MACOS:
+        dns_activate(config)
+        dns_lock_start(config)
+        print("DNS → 127.0.0.1 (已激活)")
+        if get_mode(backend) == "proxy":
+            proxy_activate()
+            print("系统代理 → 127.0.0.1:7890 (已激活)")
+
+
+# ── 命令：stop ────────────────────────────────────────────────────────────────
+
+def cmd_stop(backend: Backend, config: dict):
+    if IS_MACOS:
+        dns_lock_stop(config)
+        dns_deactivate(config)
+        proxy_deactivate()
+        print("DNS → DHCP (已还原), 系统代理已关闭")
+
+    service_stop(backend)
+    print(f"{backend.name} stopped")
+
+
+# ── 命令：restart ─────────────────────────────────────────────────────────────
+
+def cmd_restart(backend: Backend, config: dict, *, clean: bool = False):
+    if clean and os.path.isfile(backend.cache_file):
+        os.remove(backend.cache_file)
+    # 人工介入后清掉 watchdog 的失败状态，避免误判为"还在触顶窗口内"
+    for f in ("/tmp/proxyctl-recover-history", "/tmp/proxyctl-recover-stuck",
+              "/tmp/proxyctl-proxy-fail", "/tmp/proxyctl-recover-cooldown",
+              "/tmp/sb-recover-history", "/tmp/sb-recover-stuck",
+              "/tmp/sb-recover-count", "/tmp/sb-proxy-fail"):
+        try: os.remove(f)
+        except (FileNotFoundError, PermissionError): pass
+    service_restart(backend)
+    print(f"{backend.name} restarted{'  (cache cleared)' if clean else ''}")
+    _wait_ready(backend)
+
+    if IS_MACOS:
+        dns_activate(config)
+        dns_lock_start(config)
+        print("DNS → 127.0.0.1 (已刷新)")
+        if get_mode(backend) == "proxy":
+            proxy_activate()
+            print("系统代理 → 127.0.0.1:7890")
+        else:
+            proxy_deactivate()
+
+
+# ── 命令：fix ─────────────────────────────────────────────────────────────────
+
+def cmd_fix(backend: Backend, config: dict):
+    """修复引擎状态：运行中则重注入 DNS/代理，已停止则还原系统配置。"""
+    api_base = config.get("api_base", DEFAULTS["api_base"])
+    api_secret = config.get("api_secret", "")
+
+    if service_running(backend):
+        if IS_MACOS:
+            print(f"{BOLD}[引擎运行中] 修复 DNS → 127.0.0.1{NC}")
+            before = get_primary_resolver()
+            print(f"  修复前 primary resolver: {before or 'unknown'}")
+
+            dns_activate(config)
+            after = get_primary_resolver()
+            if after == "127.0.0.1":
+                print(f"  {GREEN}✓{NC} primary resolver → 127.0.0.1")
+            else:
+                print(f"  {RED}✗{NC} primary resolver 仍为 {after}，需手动排查")
+
+            if get_mode(backend) == "proxy":
+                proxy_activate()
+                print(f"  {GREEN}✓{NC} 系统代理 → 127.0.0.1:7890")
+        else:
+            print(f"{BOLD}[引擎运行中] 尝试热重载配置{NC}")
+
+        # 热重载配置（跨平台，通过 Clash API）
+        if backend.name == "mihomo":
+            subprocess.run(
+                ["curl", "-s", "--noproxy", "*", "-X", "PUT",
+                 f"http://127.0.0.1:9090/configs?force=true",
+                 "-H", f"Authorization: Bearer {api_secret}",
+                 "-H", "Content-Type: application/json",
+                 "-d", json.dumps({"path": backend.config_file})],
+                capture_output=True, timeout=8
+            )
+            print(f"  {GREEN}✓{NC} mihomo 配置已热重载")
+            subprocess.run(
+                ["curl", "-s", "--noproxy", "*", "-X", "PUT",
+                 f"http://127.0.0.1:9090/cache/fakeip",
+                 "-H", f"Authorization: Bearer {api_secret}"],
+                capture_output=True, timeout=5
+            )
+            print(f"  {GREEN}✓{NC} mihomo DNS 缓存已清空")
+
+        print()
+        if IS_MACOS:
+            if before == "127.0.0.1":
+                print(f"{GREEN}{BOLD}一切正常，无需修复。{NC}")
+            else:
+                print(f"{GREEN}{BOLD}修复完成。{NC}")
+                dns_lock_label = config.get("dns_lock_label", DEFAULTS["dns_lock_label"])
+                if not launchctl_running(f"system/{dns_lock_label}"):
+                    print(f"{CYAN}建议执行 {BOLD}proxyctl dns-lock{NC}"
+                          f"{CYAN} 防止 DNS 再次被覆盖。{NC}")
+        else:
+            print(f"{GREEN}{BOLD}修复完成。{NC}")
+    else:
+        if IS_MACOS:
+            print(f"{BOLD}[引擎已停止] 还原系统配置为正常状态{NC}")
+            before = get_primary_resolver()
+
+            dns_lock_label = config.get("dns_lock_label", DEFAULTS["dns_lock_label"])
+            if launchctl_running(f"system/{dns_lock_label}"):
+                dns_lock_stop(config)
+                print(f"  {GREEN}✓{NC} dns-lock 看门狗已停止")
+
+            dns_deactivate(config)
+            after = get_primary_resolver()
+            print(f"  {GREEN}✓{NC} DNS → DHCP ({after or 'DHCP'})")
+
+            proxy_deactivate()
+            print(f"  {GREEN}✓{NC} 系统代理已关闭")
+
+            print()
+            if before != "127.0.0.1":
+                print(f"{GREEN}{BOLD}一切正常，无需修复。{NC}")
+            else:
+                print(f"{GREEN}{BOLD}还原完成。{NC}")
+        else:
+            print(f"{YELLOW}引擎已停止，无需修复。{NC}")
+            print(f"  使用 {BOLD}proxyctl start{NC} 启动引擎")
+
+
+# ── 命令：recover ─────────────────────────────────────────────────────────────
+
+def cmd_recover(backend: Backend, config: dict):
+    """切网后软恢复（清 DNS 缓存 + 重测代理组，不重启进程）"""
+    api_base = config.get("api_base", DEFAULTS["api_base"])
+    api_secret = config.get("api_secret", "")
+
+    if backend.name != "mihomo":
+        print(f"{YELLOW}recover 目前只支持 mihomo 后端；当前后端 {backend.name}{NC}")
+        print(f"请使用 {BOLD}proxyctl restart{NC}")
+        sys.exit(1)
+
+    if not launchctl_running(backend.label):
+        print(f"{RED}✗{NC} {backend.name} 未运行，请先 proxyctl start")
+        sys.exit(1)
+
+    t0 = time.monotonic()
+    auth = ["-H", f"Authorization: Bearer {api_secret}"]
+
+    # 步骤 1: 热重载 config（清 DNS cache）
+    print(f"{BOLD}[1/3]{NC} 热重载配置（清 DNS 缓存）")
+    r = subprocess.run(
+        ["curl", "-s", "-o", "/dev/null", "-w", "%{http_code}",
+         "--noproxy", "*", "-X", "PUT",
+         f"{api_base}/configs?force=true",
+         *auth, "-H", "Content-Type: application/json",
+         "-d", json.dumps({"path": backend.config_file})],
+        capture_output=True, text=True, timeout=10
+    )
+    if r.stdout.strip() in ("200", "204"):
+        print(f"  {GREEN}✓{NC} 配置已重载 (HTTP {r.stdout.strip()})")
+    else:
+        print(f"  {RED}✗{NC} 重载失败 (HTTP {r.stdout.strip() or 'n/a'})，回退到 proxyctl restart")
+        sys.exit(2)
+
+    # 步骤 2: flush fakeip cache
+    print(f"{BOLD}[2/3]{NC} 清空 fakeip 缓存")
+    subprocess.run(
+        ["curl", "-s", "-o", "/dev/null", "--noproxy", "*", "-X", "POST",
+         f"{api_base}/cache/fakeip/flush", *auth],
+        capture_output=True, timeout=5
+    )
+    print(f"  {GREEN}✓{NC} fakeip 缓存已清空")
+
+    # 步骤 3: 触发代理组 healthcheck
+    print(f"{BOLD}[3/3]{NC} 触发代理组 healthcheck")
+    r = subprocess.run(
+        ["curl", "-s", "--noproxy", "*", *auth, f"{api_base}/proxies"],
+        capture_output=True, text=True, timeout=5
+    )
+    try:
+        proxies = json.loads(r.stdout).get("proxies", {})
+    except Exception:
+        print(f"  {YELLOW}—{NC} 无法拉取 proxies 列表")
+        sys.exit(2)
+
+    import urllib.parse
+    TEST_URL = "https://www.gstatic.com/generate_204"
+    TIMEOUT_MS = 5000
+    groups_to_test = [
+        name for name, info in proxies.items()
+        if info.get("type") in ("URLTest", "Fallback", "LoadBalance")
+    ]
+    if not groups_to_test:
+        print(f"  {YELLOW}—{NC} 无 url-test 类型组")
+    else:
+        from concurrent.futures import ThreadPoolExecutor
+        encoded_url = urllib.parse.quote(TEST_URL, safe="")
+
+        def _test_group(gname: str) -> tuple:
+            encoded = urllib.parse.quote(gname, safe="")
+            endpoint = (f"{api_base}/group/{encoded}/delay"
+                        f"?url={encoded_url}&timeout={TIMEOUT_MS}")
+            rr = subprocess.run(
+                ["curl", "-s", "--noproxy", "*", "--max-time", "10",
+                 *auth, endpoint],
+                capture_output=True, text=True, timeout=12
+            )
+            try:
+                data = json.loads(rr.stdout) if rr.stdout else {}
+            except Exception:
+                data = {}
+            alive = sum(1 for v in data.values() if isinstance(v, int) and v > 0)
+            total = len(data) if data else 0
+            return gname, alive, total
+
+        with ThreadPoolExecutor(max_workers=len(groups_to_test)) as pool:
+            results = list(pool.map(_test_group, groups_to_test))
+
+        for gname, alive, total in results:
+            if total == 0:
+                mark = f"{RED}✗{NC}"
+                detail = "无响应"
+            elif alive == 0:
+                mark = f"{RED}✗{NC}"
+                detail = f"0/{total} 存活"
+            elif alive < total:
+                mark = f"{YELLOW}—{NC}"
+                detail = f"{alive}/{total} 存活"
+            else:
+                mark = f"{GREEN}✓{NC}"
+                detail = f"{alive}/{total} 存活"
+            print(f"  {mark} {CYAN}{gname}{NC}  {detail}")
+
+    elapsed = time.monotonic() - t0
+    print()
+    print(f"{GREEN}{BOLD}recover 完成{NC}  耗时 {elapsed:.1f}s")
+    print(f"建议运行 {BOLD}proxyctl check{NC} 验证恢复情况；若仍失败请 {BOLD}proxyctl restart{NC}")
+
+
+# ── 命令：mode ────────────────────────────────────────────────────────────────
+
+def cmd_mode(backend: Backend, target: str):
+    if not target:
+        cur = get_mode(backend)
+        print(f"当前：backend={backend.name} mode={cur}")
+        print("切换：proxyctl mode tun | proxyctl mode proxy")
+        return
+
+    if target not in ("tun", "proxy"):
+        print("用法：proxyctl mode [tun|proxy]")
+        print("  tun   — 全局接管 (auto_route + fakeip)")
+        print("  proxy — 仅代理端口 (7890 + real DNS)")
+        sys.exit(1)
+
+    if backend.name == "mihomo":
+        _mode_mihomo(backend.config_file, target)
+    else:
+        _mode_singbox(backend.config_file, target)
+
+    if target == "proxy":
+        proxy_activate()
+        print("系统代理 → 127.0.0.1:7890")
+    else:
+        proxy_deactivate()
+        print("系统代理已关闭")
+
+
+def _mode_mihomo(config_path: str, target: str):
+    text = open(config_path).read()
+    if target == "tun":
+        text = re.sub(r'(tun:\s*\n(?:\s*#[^\n]*\n)*\s*enable:\s*)false', r'\1true', text)
+        text = re.sub(r'(auto-route:\s*)false', r'\1true', text)
+        text = re.sub(r'enhanced-mode:\s*redir-host', 'enhanced-mode: fake-ip', text)
+        msg = "已切换到 tun 模式 (auto_route + fakeip)"
+    else:
+        text = re.sub(r'(tun:\s*\n(?:\s*#[^\n]*\n)*\s*enable:\s*)true', r'\1false', text)
+        text = re.sub(r'(auto-route:\s*)true', r'\1false', text)
+        text = re.sub(r'enhanced-mode:\s*fake-ip', 'enhanced-mode: redir-host', text)
+        msg = "已切换到 proxy_only 模式 (7890 + redir-host)"
+    open(config_path, "w").write(text)
+    print(msg)
+    print("执行 proxyctl restart 生效")
+
+
+def _mode_singbox(config_path: str, target: str):
+    cfg = json.load(open(config_path))
+    for ib in cfg.get("inbounds", []):
+        if ib.get("type") == "tun":
+            ib["auto_route"] = (target == "tun")
+            break
+    for rule in cfg.get("dns", {}).get("rules", []):
+        qt = rule.get("query_type", [])
+        if "A" in qt and "AAAA" in qt:
+            rule["server"] = "fakeip-dns" if target == "tun" else "proxy-dns"
+            break
+    with open(config_path, "w") as f:
+        json.dump(cfg, f, indent=2, ensure_ascii=False)
+        f.write("\n")
+    if target == "tun":
+        print("已切换到 tun 模式 (auto_route + fakeip)")
+    else:
+        print("已切换到 proxy_only 模式 (7890 + real DNS)")
+    print("执行 proxyctl restart 生效")
+
+
+# ── 命令：dns-lock / dns-unlock ───────────────────────────────────────────────
+
+DNS_LOCK_PLIST_TEMPLATE = """<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
+  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>{label}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>/bin/bash</string>
+    <string>{watchdog_path}</string>
+  </array>
+  <key>StartInterval</key>
+  <integer>30</integer>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PROXYCTL_CONFIG_DIR</key>
+    <string>{config_dir}</string>
+    <key>PROXYCTL_API_BASE</key>
+    <string>{api_base}</string>
+    <key>PROXYCTL_API_SECRET</key>
+    <string>{api_secret}</string>
+    <key>PROXYCTL_ENGINE_LABEL</key>
+    <string>{engine_label}</string>
+    <key>PROXYCTL_CORP_DOMAIN</key>
+    <string>{corp_domain}</string>
+    <key>PROXYCTL_TUIC_HEALTHCHECK</key>
+    <string>{tuic_healthcheck}</string>
+  </dict>
+  <key>StandardOutPath</key>
+  <string>{log_path}</string>
+  <key>StandardErrorPath</key>
+  <string>{log_path}</string>
+</dict>
+</plist>
+"""
+
+
+def _render_dns_lock_plist(backend: Backend, config: dict) -> str:
+    """根据 config 渲染 dns-lock plist 内容。
+
+    所有路径/label/secret 由 config + 默认值组合得出；plist 内容不依赖任何
+    仓库外文件（无须先复制模板到 ~/.config/proxyctl/launchdaemons/）。
+    """
+    dns_lock_label = config.get("dns_lock_label", DEFAULTS["dns_lock_label"])
+    watchdog_path = os.path.join(HOME, ".local", "bin", "proxyctl-dns-watchdog")
+    corp = (config.get("corp_dns") or {})
+    healthcheck_off = (config.get("watchdog") or {}).get("tuic_healthcheck") is False
+
+    return DNS_LOCK_PLIST_TEMPLATE.format(
+        label           = dns_lock_label,
+        watchdog_path   = watchdog_path,
+        config_dir      = DEFAULT_CONFIG_DIR,
+        api_base        = config.get("api_base", DEFAULTS["api_base"]),
+        api_secret      = config.get("api_secret", ""),
+        engine_label    = backend.label,
+        corp_domain     = corp.get("domain", ""),
+        tuic_healthcheck= "0" if healthcheck_off else "1",
+        log_path        = os.path.join(DEFAULT_CONFIG_DIR, "dns-watchdog.log"),
+    )
+
+
+def cmd_engine(backend: Backend, target: str, config: dict):
+    """proxyctl engine [singbox|mihomo] — 切换代理引擎。
+
+    无参时打印当前引擎 + 已部署 plist 状态。
+    切换时执行：停旧 daemon → 撤旧 plist → 装新 plist → 起新 daemon。
+    引擎持久化到 ~/.config/proxyctl/engine 文件。
+    """
+    engine_file = os.path.join(DEFAULT_CONFIG_DIR, "engine")
+    if not target:
+        cur = backend.name
+        sb_ok = os.path.isfile("/Library/LaunchDaemons/com.singbox.tun.plist")
+        mh_ok = os.path.isfile("/Library/LaunchDaemons/com.mihomo.tun.plist")
+        print(f"当前引擎: {cur}")
+        print(f"已部署 plist: singbox={sb_ok} mihomo={mh_ok}")
+        print("切换: proxyctl engine singbox | proxyctl engine mihomo")
+        return
+
+    if target not in ("singbox", "mihomo"):
+        print("用法: proxyctl engine [singbox|mihomo]")
+        sys.exit(1)
+    if target == backend.name:
+        print(f"已经是 {target}，无需切换")
+        return
+    if not IS_MACOS:
+        print(f"{YELLOW}engine 切换暂仅支持 macOS launchd{NC}")
+        sys.exit(1)
+
+    new_backend_cfg = dict(config)
+    new_backend_cfg["backend"] = target
+    new_backend = get_backend(new_backend_cfg)
+
+    plist_src = os.path.join(DEFAULT_CONFIG_DIR, "launchdaemons",
+                              os.path.basename(new_backend.plist))
+    # 预检
+    if not os.path.isfile(plist_src):
+        print(f"{RED}✗{NC} plist 源文件不存在: {plist_src}")
+        sys.exit(1)
+    if not os.path.isfile(new_backend.config_file):
+        print(f"{RED}✗{NC} 配置文件不存在: {new_backend.config_file}")
+        sys.exit(1)
+
+    print(f"停止 {backend.name} ...")
+    dns_lock_stop(config)
+    dns_deactivate(config)
+    proxy_deactivate()
+    run(["launchctl", "bootout", backend.label], sudo=True)
+    run(["/bin/rm", "-f", backend.plist], sudo=True)
+
+    r = run(["/bin/cp", plist_src, new_backend.plist], sudo=True, capture=True)
+    if r.returncode != 0:
+        print(f"{RED}✗{NC} 部署 plist 失败")
+        sys.exit(1)
+
+    # 持久化引擎选择
+    os.makedirs(DEFAULT_CONFIG_DIR, exist_ok=True)
+    with open(engine_file, "w") as f:
+        f.write(target)
+
+    print(f"启动 {new_backend.name} ...")
+    r = run(["launchctl", "bootstrap", "system", new_backend.plist],
+            sudo=True, capture=True)
+    if r.returncode != 0:
+        print(f"{RED}✗{NC} 启动失败")
+        sys.exit(1)
+
+    _wait_ready(new_backend)
+    dns_activate(config)
+    dns_lock_start(config)
+    print("DNS → 127.0.0.1 (已激活)")
+    if get_mode(new_backend) == "proxy":
+        proxy_activate()
+        print("系统代理 → 127.0.0.1:7890")
+    print(f"{GREEN}引擎已切换到 {new_backend.name}{NC}")
+    print(f"{CYAN}提示: 把 engine: {target} 写到 ~/.config/proxyctl/config.yaml 保持持久{NC}")
+
+
+def cmd_daemon(name: str, subcmd: str, config: dict):
+    """proxyctl daemon [name] [subcmd] — 管理 config.extra_daemons 中声明的辅助 daemon。
+
+    config 示例：
+      extra_daemons:
+        my-secondary:
+          label: com.example.my-secondary
+          plist_src: /path/to/com.example.my-secondary.plist
+          log_path:  /path/to/my-secondary.log
+          port: 7891
+    """
+    if not IS_MACOS:
+        print(f"{YELLOW}daemon 命令暂仅支持 macOS launchd{NC}")
+        return
+
+    daemons = (config.get("extra_daemons") or {})
+
+    if not name:
+        if not daemons:
+            print(f"{YELLOW}—{NC} config.yaml 中未声明任何 extra_daemons")
+            return
+        print(f"{BOLD}已声明的 daemon:{NC}")
+        for d_name, d_cfg in daemons.items():
+            label = d_cfg.get("label", "?")
+            running = launchctl_running(f"system/{label}", sudo=True)
+            mark = f"{GREEN}✓{NC}" if running else f"{YELLOW}—{NC}"
+            print(f"  {mark} {d_name}  label={label}")
+        return
+
+    d_cfg = daemons.get(name)
+    if not d_cfg:
+        print(f"{RED}✗{NC} 未声明的 daemon: {name}")
+        print(f"  请在 config.yaml extra_daemons 中加入 {name} 段")
+        sys.exit(1)
+
+    label    = d_cfg.get("label", "")
+    plist_src = os.path.expanduser(d_cfg.get("plist_src", ""))
+    log_path  = os.path.expanduser(d_cfg.get("log_path", ""))
+    port      = d_cfg.get("port")
+    if not label:
+        print(f"{RED}✗{NC} daemon {name} 缺少 label 字段")
+        sys.exit(1)
+
+    full_label = f"system/{label}"
+    plist_dst = f"/Library/LaunchDaemons/{label}.plist"
+
+    subcmd = subcmd or "status"
+    if subcmd == "start":
+        if launchctl_running(full_label, sudo=True):
+            print(f"{name} 已在运行")
+            return
+        if not os.path.isfile(plist_dst):
+            if not os.path.isfile(plist_src):
+                print(f"{RED}✗{NC} plist 源文件不存在: {plist_src}")
+                sys.exit(1)
+            run(["/bin/cp", plist_src, plist_dst], sudo=True)
+        r = run(["launchctl", "bootstrap", "system", plist_dst],
+                sudo=True, capture=True)
+        if r.returncode != 0:
+            print(f"{RED}✗{NC} {name} 启动失败")
+            sys.exit(1)
+        if port:
+            wait_port(int(port), timeout=10)
+            print(f"{GREEN}✓{NC} {name} started (127.0.0.1:{port})")
+        else:
+            print(f"{GREEN}✓{NC} {name} started")
+
+    elif subcmd == "stop":
+        if launchctl_running(full_label, sudo=True):
+            run(["launchctl", "bootout", full_label], sudo=True)
+            print(f"{name} stopped")
+        else:
+            print(f"{name} 未在运行")
+
+    elif subcmd == "restart":
+        run(["launchctl", "kickstart", "-k", full_label], sudo=True)
+        print(f"{name} restarted")
+
+    elif subcmd == "log":
+        if not log_path:
+            print(f"{RED}✗{NC} daemon {name} 未声明 log_path")
+            sys.exit(1)
+        os.execvp("tail", ["tail", "-f", log_path])
+
+    else:  # status
+        if launchctl_running(full_label, sudo=True):
+            r = subprocess.run(["sudo", "launchctl", "print", full_label],
+                               capture_output=True, text=True)
+            pid = next((l.split()[-1] for l in r.stdout.splitlines()
+                        if "pid =" in l), "?")
+            port_str = f", port {port}" if port else ""
+            print(f"{GREEN}✓{NC} {name} running (PID {pid}{port_str})")
+        else:
+            print(f"{RED}✗{NC} {name} not running")
+
+
+def cmd_dns_lock(config: dict, backend: Backend, *, reload: bool = False):
+    if not IS_MACOS:
+        print(f"{YELLOW}dns-lock 仅支持 macOS（Linux 不劫持系统 DNS）{NC}")
+        return
+    dns_lock_label = config.get("dns_lock_label", DEFAULTS["dns_lock_label"])
+    dns_lock_plist = f"/Library/LaunchDaemons/{dns_lock_label}.plist"
+    dns_watchdog = os.path.join(HOME, ".local", "bin", "proxyctl-dns-watchdog")
+
+    full_label = f"system/{dns_lock_label}"
+    already_registered = launchctl_running(full_label)
+
+    # 默认行为：如果已 registered 且 plist 已存在，认为已装好
+    # reload=True：强制 bootout + 重写 plist + 重新 bootstrap
+    if already_registered and not reload:
+        print(f"dns-lock daemon 已注册（如需更新 plist，请运行 proxyctl dns-lock --reload）")
+        return
+
+    if not os.access(dns_watchdog, os.X_OK):
+        print(f"错误：看门狗脚本不可执行 {dns_watchdog}")
+        print(f"  请先把 scripts/dns-watchdog 安装到该位置（或重新跑 install.sh）")
+        sys.exit(1)
+
+    # reload 时先 bootout
+    if already_registered:
+        r0 = run(["launchctl", "bootout", full_label], sudo=True, capture=True)
+        if r0.returncode != 0:
+            print(f"{YELLOW}⚠{NC} bootout 失败（继续尝试 bootstrap）: {r0.stderr.strip()}")
+
+    rendered = _render_dns_lock_plist(backend, config)
+    # 通过 sudo tee 写入（sudoers 允许 /usr/bin/tee <target.plist>）
+    r = run(["tee", dns_lock_plist], sudo=True, stdin_text=rendered, capture=True)
+    if r.returncode != 0:
+        print(f"{RED}✗{NC} 写入 plist 失败: {r.stderr or '权限不足，请检查 sudoers'}")
+        sys.exit(1)
+
+    r2 = run(["launchctl", "bootstrap", "system", dns_lock_plist],
+             sudo=True, capture=True)
+    if r2.returncode != 0:
+        print(f"{RED}✗{NC} bootstrap 失败: {r2.stderr}")
+        sys.exit(1)
+
+    print(f"{GREEN}dns-lock daemon 已安装并启动{NC}")
+    print(f"label: {dns_lock_label}")
+    print(f"plist: {dns_lock_plist}  (内嵌模板渲染，含 config.yaml 注入的 env)")
+    print(f"日志:  {os.path.join(DEFAULT_CONFIG_DIR, 'dns-watchdog.log')}")
+
+
+def cmd_dns_unlock(config: dict):
+    if not IS_MACOS:
+        print(f"{YELLOW}dns-unlock 仅支持 macOS{NC}")
+        return
+    dns_lock_label = config.get("dns_lock_label", DEFAULTS["dns_lock_label"])
+
+    r = run(["launchctl", "bootout", f"system/{dns_lock_label}"], sudo=True, capture=True)
+    if r.returncode == 0:
+        print(f"{GREEN}dns-lock daemon 已停止{NC}")
+    else:
+        print("dns-lock daemon 未在运行")
+    run(["rm", "-f", dns_lock_plist], sudo=True)
+    print(f"已删除 {dns_lock_plist} (源文件保留在 {DEFAULT_CONFIG_DIR}/launchdaemons/)")
+
+
+# ── 命令：env ────────────────────────────────────────────────────────────────
+
+def cmd_env(config: dict, unset: bool = False):
+    """输出设置/清除代理环境变量的 shell 语句。
+
+    用法：
+        eval $(proxyctl env)         # 设置代理
+        eval $(proxyctl env --unset) # 清除代理
+
+    Args:
+        config: 全局配置字典
+        unset: True 则输出 unset 语句
+    """
+    if unset:
+        for var in ("http_proxy", "https_proxy", "all_proxy",
+                     "HTTP_PROXY", "HTTPS_PROXY", "ALL_PROXY",
+                     "no_proxy", "NO_PROXY"):
+            print(f"unset {var};")
+        return
+
+    port = 7890  # mixed-port
+    proxy_http = f"http://127.0.0.1:{port}"
+    proxy_socks = f"socks5://127.0.0.1:{port}"
+    no_proxy = "localhost,127.0.0.1,::1,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16"
+
+    for var in ("http_proxy", "HTTP_PROXY"):
+        print(f"export {var}={proxy_http};")
+    for var in ("https_proxy", "HTTPS_PROXY"):
+        print(f"export {var}={proxy_http};")
+    for var in ("all_proxy", "ALL_PROXY"):
+        print(f"export {var}={proxy_socks};")
+    for var in ("no_proxy", "NO_PROXY"):
+        print(f"export {var}={no_proxy};")
+
+
+# ── 帮助 ──────────────────────────────────────────────────────────────────────
+
+VERSION = "0.1.0"
+
+def cmd_help(verbose: bool = False):
+    """打印帮助信息
+
+    Args:
+        verbose: 是否显示详细帮助（包含所有命令的详细说明）
+    """
+    print(f"proxyctl v{VERSION}")
+    print("Proxy configuration lifecycle management\n")
+    print("用法：proxyctl <command> [options]\n")
+
+    print("┌─ 基础操作 ─────────────────────────────────────────────────────┐")
+    print("│  start              启动后端 (Mihomo/Sing-box)                 │")
+    print("│  stop               停止后端                                   │")
+    print("│  restart            重启后端                                   │")
+    print("│  restart-clean      重启并清除缓存                             │")
+    print("│  status             系统状态面板                               │")
+    print("│  log                查看后端日志 (tail -f)                     │")
+    print("│  fix                修复 DNS/代理/刷新缓存                     │")
+    print("│  recover            切网后软恢复（清 DNS 缓存 + 重测代理组）     │")
+    print("└────────────────────────────────────────────────────────────────┘")
+
+    print("\n┌─ 诊断工具 ─────────────────────────────────────────────────────┐")
+    print("│  check              全面健康检查 (4 阶段)                        │")
+    print("│  bench [groups...]  代理组测速（默认测全部组）                  │")
+    print("│  trace <domain>     域名链路诊断                               │")
+    print("│  audit [days]       扫描日志，找疑似应直连的域名               │")
+    print("└────────────────────────────────────────────────────────────────┘")
+
+    print("\n┌─ 配置管理 ─────────────────────────────────────────────────────┐")
+    print("│  engine [singbox|mihomo]  切换代理引擎                          │")
+    print("│  mode [tun|proxy]         切换运行模式                          │")
+    print("│  dns-lock                 启动 DNS 看门狗 daemon                │")
+    print("│  dns-unlock               停止 DNS 看门狗                       │")
+    print("│  daemon [name] [subcmd]   管理 extra_daemons (claude-proxy 等)  │")
+    print("│  env                      输出代理环境变量                      │")
+    print("│  env --unset              清除代理环境变量                      │")
+    print("│  plugins                  显示已加载插件                        │")
+    print("└────────────────────────────────────────────────────────────────┘")
+
+    print("\n┌─ 其他 ─────────────────────────────────────────────────────────┐")
+    print("│  --help, -h         显示帮助信息                               │")
+    print("│  --version, -v      显示版本号                                 │")
+    print("└────────────────────────────────────────────────────────────────┘")
+
+    if verbose:
+        print("\n┌─ 命令详解 ───────────────────────────────────────────────────┐")
+        print("│                                                            │")
+        print("│  check   四阶段检查：                                       │")
+        print("│          1. 基础状态 (daemon/端口)                         │")
+        print("│          2. 代理组状态 (节点延迟/存活率)                   │")
+        print("│          3. 连通性测试 (Google/GitHub/国内网站)            │")
+        print("│          4. 出口 IP 验证 (分流是否正确)                     │")
+        print("│                                                            │")
+        print("│  trace   四阶段诊断：                                       │")
+        print("│          1. DNS 解析 (fakeip/realip)                        │")
+        print("│          2. 规则匹配预测                                    │")
+        print("│          3. 连通性测试                                      │")
+        print("│          4. 实际连接验证                                    │")
+        print("│                                                            │")
+        print("│  audit   配置审计：                                         │")
+        print("│          扫描代理日志，找出\"走代理但实际是国内 IP\"的域名    │")
+        print("│          建议添加到直连规则，可自动应用                    │")
+        print("│                                                            │")
+        print("│  recover 切网后软恢复（不重启进程）：                       │")
+        print("│          1. 热重载配置（清 DNS 缓存）                        │")
+        print("│          2. Flush fakeip cache                             │")
+        print("│          3. 触发所有代理组 healthcheck                     │")
+        print("└────────────────────────────────────────────────────────────┘")
+
+    print("\n配置文件：~/.config/proxyctl/config.yaml")
+    print("项目地址：https://github.com/crhan/proxyctl")
+    sys.exit(0)
+
+
+# ── 主入口 ────────────────────────────────────────────────────────────────────
+
+def main():
+    # 处理全局标志
+    if len(sys.argv) > 1:
+        if sys.argv[1] in ("--help", "-h", "help"):
+            cmd_help(verbose=True)
+            return
+        elif sys.argv[1] in ("--version", "-v"):
+            print(f"proxyctl v{VERSION}")
+            sys.exit(0)
+
+    config = load_config()
+    backend = get_backend(config)
+    registry = load_plugins(config)
+    api_base = config.get("api_base", DEFAULTS["api_base"])
+    api_secret = config.get("api_secret", "")
+
+    # 检查 api_secret 配置
+    if not api_secret:
+        print(f"{YELLOW}警告：未在配置文件中找到 api_secret{NC}", file=sys.stderr)
+        print(f"  请在 {CONFIG_FILE} 中配置 api_secret: <your-clash-api-secret>",
+              file=sys.stderr)
+        print(file=sys.stderr)
+
+    cmd = sys.argv[1] if len(sys.argv) > 1 else "status"
+
+    if cmd == "start":
+        cmd_start(backend, config)
+    elif cmd == "stop":
+        cmd_stop(backend, config)
+    elif cmd == "restart":
+        cmd_restart(backend, config)
+    elif cmd == "restart-clean":
+        cmd_restart(backend, config, clean=True)
+    elif cmd == "status":
+        from proxyctl.status import cmd_status
+        mode_str = get_mode(backend)
+        cmd_status(backend, api_base, api_secret, config, mode_str, registry=registry)
+    elif cmd == "log":
+        os.execvp("tail", ["tail", "-f", backend.log_file])
+    elif cmd == "check":
+        from proxyctl.check import cmd_check
+        mode_str = get_mode(backend)
+        cmd_check(backend, api_base, api_secret, config, mode_str, registry=registry)
+    elif cmd == "bench":
+        from proxyctl.check import cmd_bench
+        bench_groups = sys.argv[2:] if len(sys.argv) > 2 else None
+        default_groups = registry.collect("check_groups") if registry else None
+        cmd_bench(api_base, api_secret, bench_groups, default_groups=default_groups)
+    elif cmd == "fix":
+        cmd_fix(backend, config)
+    elif cmd == "recover":
+        cmd_recover(backend, config)
+    elif cmd == "dns-lock":
+        reload = "--reload" in sys.argv[2:]
+        cmd_dns_lock(config, backend, reload=reload)
+    elif cmd == "dns-unlock":
+        cmd_dns_unlock(config)
+    elif cmd == "env":
+        unset = "--unset" in sys.argv[2:] or "off" in sys.argv[2:]
+        cmd_env(config, unset=unset)
+    elif cmd == "plugins":
+        cmd_plugins(registry)
+    elif cmd == "engine":
+        target = sys.argv[2] if len(sys.argv) > 2 else ""
+        cmd_engine(backend, target, config)
+    elif cmd == "daemon":
+        name = sys.argv[2] if len(sys.argv) > 2 else ""
+        subcmd = sys.argv[3] if len(sys.argv) > 3 else ""
+        cmd_daemon(name, subcmd, config)
+    elif cmd == "claude-proxy":
+        # sb 时代别名，等价于 `proxyctl daemon claude-proxy <subcmd>`
+        subcmd = sys.argv[2] if len(sys.argv) > 2 else "status"
+        cmd_daemon("claude-proxy", subcmd, config)
+    elif cmd == "audit":
+        arg = sys.argv[2] if len(sys.argv) > 2 else "1"
+        apply_mode = (arg == "apply")
+        days_str = sys.argv[3] if (apply_mode and len(sys.argv) > 3) else (arg if not apply_mode else "1")
+        try:
+            days = int(days_str)
+        except ValueError:
+            days = 1
+        from proxyctl.audit import cmd_audit
+        cmd_audit(days, api_base, api_secret, apply_mode)
+    elif cmd == "mode":
+        target = sys.argv[2] if len(sys.argv) > 2 else ""
+        cmd_mode(backend, target)
+    elif cmd == "trace":
+        if len(sys.argv) < 3:
+            print("用法：proxyctl trace <domain|url>")
+            print("  诊断域名的完整访问链路：DNS → 规则预测 → 连通性测试 → 实际连接验证")
+            sys.exit(1)
+        from proxyctl.trace import cmd_trace
+        cmd_trace(sys.argv[2], api_base, api_secret, config)
+    else:
+        cmd_help()
+
+
+if __name__ == "__main__":
+    main()