proxyctl 0.4.1__tar.gz → 0.4.3__tar.gz

{proxyctl-0.4.1 → proxyctl-0.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: proxyctl
-Version: 0.4.1
+Version: 0.4.3
 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
@@ -64,11 +64,18 @@ PROXYCTL_AGENT=1 proxyctl <cmd>      # 一键 --json + 关色 + 非交互
 - envelope schema v2：`schema_version / cmd / ok / data / error / code / hints[] / warnings[] / doc / meta{{ts,elapsed_ms,proxyctl_version,request_id}}`
 - 退出码分语义：`0 OK / 2 USAGE / 3 NOT_FOUND / 4 PERMISSION / 5 ENGINE_DOWN / 6 CONFIG_ERR / 7 NETWORK_ERR / 8 LOCKED / 9 TIMEOUT / 10 DEPENDENCY_MISSING`
 - 写命令支持 `--dry-run` 输出结构化 plan（`data.plan = [PlanStep, ...]`）；自 0.4.0 起
-  `plan.target` 全部真实化，`action=="subprocess"` 的 target.split() 可直接当 argv 复读：
+  `plan.target` 全部真实化，`action=="subprocess"` 的 target.split() 可直接当 argv 复读；
+  自 0.4.2 起 `start / stop / restart / restart-clean / recover` 也加入 `--dry-run` 行列
+  （之前是文档承诺但实际真跑，已修复）：
   ```bash
   proxyctl dns-unlock --dry-run --json | jq -r '.data.plan[] | select(.action=="subprocess").target'
   # → launchctl bootout system/com.proxyctl.dns-lock
   # → rm -f /Library/LaunchDaemons/com.proxyctl.dns-lock.plist
+
+  proxyctl stop --dry-run --json | jq -r '.data.plan[] | select(.action=="subprocess").target'
+  # macOS → launchctl bootout system/com.proxyctl.dns-lock
+  #       → launchctl bootout system/com.mihomo.tun
+  # Linux → systemctl --user stop mihomo.service
   ```
   PlanStep.action 枚举：`subprocess / system_op / fs_write / fs_copy / fs_write_atomic / fs_remove / edit_yaml / scan_log / http_put`。
   CI 层 contract test（`tests/integration/test_plan_exec_contract.py`）保证 plan ↔ exec 永不漂移。

{proxyctl-0.4.1 → proxyctl-0.4.3}/README.md

@@ -35,11 +35,18 @@ PROXYCTL_AGENT=1 proxyctl <cmd>      # 一键 --json + 关色 + 非交互
 - envelope schema v2：`schema_version / cmd / ok / data / error / code / hints[] / warnings[] / doc / meta{{ts,elapsed_ms,proxyctl_version,request_id}}`
 - 退出码分语义：`0 OK / 2 USAGE / 3 NOT_FOUND / 4 PERMISSION / 5 ENGINE_DOWN / 6 CONFIG_ERR / 7 NETWORK_ERR / 8 LOCKED / 9 TIMEOUT / 10 DEPENDENCY_MISSING`
 - 写命令支持 `--dry-run` 输出结构化 plan（`data.plan = [PlanStep, ...]`）；自 0.4.0 起
-  `plan.target` 全部真实化，`action=="subprocess"` 的 target.split() 可直接当 argv 复读：
+  `plan.target` 全部真实化，`action=="subprocess"` 的 target.split() 可直接当 argv 复读；
+  自 0.4.2 起 `start / stop / restart / restart-clean / recover` 也加入 `--dry-run` 行列
+  （之前是文档承诺但实际真跑，已修复）：
   ```bash
   proxyctl dns-unlock --dry-run --json | jq -r '.data.plan[] | select(.action=="subprocess").target'
   # → launchctl bootout system/com.proxyctl.dns-lock
   # → rm -f /Library/LaunchDaemons/com.proxyctl.dns-lock.plist
+
+  proxyctl stop --dry-run --json | jq -r '.data.plan[] | select(.action=="subprocess").target'
+  # macOS → launchctl bootout system/com.proxyctl.dns-lock
+  #       → launchctl bootout system/com.mihomo.tun
+  # Linux → systemctl --user stop mihomo.service
   ```
   PlanStep.action 枚举：`subprocess / system_op / fs_write / fs_copy / fs_write_atomic / fs_remove / edit_yaml / scan_log / http_put`。
   CI 层 contract test（`tests/integration/test_plan_exec_contract.py`）保证 plan ↔ exec 永不漂移。

{proxyctl-0.4.1 → proxyctl-0.4.3}/man/proxyctl.1

@@ -1,4 +1,4 @@
-.TH PROXYCTL 1 "2026-05" "proxyctl 0.4.1" "User Commands"
+.TH PROXYCTL 1 "2026-05" "proxyctl 0.4.3" "User Commands"
 .SH NAME
 proxyctl \- Proxy configuration lifecycle management for macOS / Linux
 .SH SYNOPSIS
@@ -33,14 +33,19 @@ audit / check 支持 \fB--plain\fR TSV 输出；
 写命令预演：输出 \fIdata.plan = [PlanStep, ...]\fR（不真正执行）。
 PlanStep 字段：step / action / target / reversible / requires_sudo /
 side_effects / summary。
-适用：mode / engine / fix / audit apply / config set / daemon /
-dns-lock / dns-unlock。
+适用：\fBstart / stop / restart / restart-clean / recover\fR（自 0.4.2）/
+mode / engine / fix / audit apply / config set / daemon /
+claude-proxy / dns-lock / dns-unlock。
 .IP
 \fB自 0.4.0\fR：plan.target 全部真实化（无 \fI<...>\fR 占位符）；
 action=\fBsubprocess\fR 的 target.split() 可直接当 argv（run 时
 prepend sudo）。action 枚举：subprocess / system_op / fs_write /
 fs_copy / fs_write_atomic / fs_remove / edit_yaml / scan_log /
 http_put。CI 层 contract test 保证 plan ↔ exec 永不漂移。
+.IP
+\fB自 0.4.2\fR：原本 dispatcher 未接卫语句、`--dry-run` 被静默吃掉真执行的
+5 个写命令补齐 plan helper；lifecycle plan 按 \fIIS_MACOS\fR 平台分流，
+macOS 列 launchctl + 系统联动，Linux 列 systemctl --user。
 .TP
 .BR --no-color
 关闭 ANSI 颜色（默认按 isatty / NO_COLOR / TERM=dumb / PROXYCTL_NO_COLOR 自动判断）。
@@ -90,17 +95,24 @@ engine / mode / port / config_path / engine_config_path / lock_held / lock_path
 .TP
 \fBproxyctl completion\fR \fIbash\fR | \fIzsh\fR | \fIfish\fR
 生成 shell 补全脚本。
+.TP
+.B proxyctl version [--json]
+显示版本号 + supported_features。等价 \fB--version\fR flag（自 0.4.2 起也提供
+子命令形式，方便 agent 通过 DISPATCH 探测）。
 
 .SS 生命周期（写：sudo + process + system）
 .TP
-.B proxyctl start / stop / restart / restart-clean
+.B proxyctl start / stop / restart / restart-clean [\fB--dry-run\fR]
 启停代理引擎（写系统 DNS / 代理 / launchd）。restart-clean 额外清缓存。
+全部支持 \fB--dry-run\fR（自 0.4.2）；plan 按平台分流（macOS launchctl /
+Linux systemctl --user）。
 .TP
 .B proxyctl fix [--dry-run]
 修复 DNS / 代理 / 热重载（system + cache）。
 .TP
-.B proxyctl recover
+.B proxyctl recover [\fB--dry-run\fR]
 切网后软恢复：热重载 + 清 fakeip + 重测代理组（不重启进程）。
+\fB--dry-run\fR 自 0.4.2 起列出三个 Clash API endpoint。
 
 .SS 模式 / 引擎（写：sudo + config-write）
 .TP

{proxyctl-0.4.1 → proxyctl-0.4.3}/pyproject.toml

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

{proxyctl-0.4.1 → proxyctl-0.4.3}/src/proxyctl/check.py

@@ -532,6 +532,52 @@ def _fetch_probe(probe, env_clean: dict, proxy_port: int = 7890) -> str:
     return text
 
 
+def _collect_fail_hints(collector: dict, *, dns_bad: bool, failed: bool) -> list[str]:
+    """从 check 的 collector 提取每个失败 stage 的简短摘要。
+
+    设计目标：envelope.ok=False 时 agent 不需要挖 stages.*.ok 自行定位真凶。
+    本函数为 cmd_check 在 emit_json 之前调用，输出 hints 列表。
+
+    Args:
+        collector: cmd_check 沉淀的事实快照（见 cmd_check.collector）
+        dns_bad:   basic.network.dns 不健康
+        failed:    整体是否任一 stage fail（fail 变量真值）
+
+    Returns:
+        摘要 hint 行列表。整体 pass 时返回空列表。
+    """
+    hints: list[str] = []
+    if not failed:
+        return hints
+
+    stages = collector.get("stages") or {}
+    basic = stages.get("basic") or {}
+    ports = basic.get("ports") or {}
+    fail_ports = ports.get("fail") or []
+    if fail_ports:
+        hints.append(f"missing ports: {' '.join(fail_ports)}")
+
+    if basic.get("daemon_up") is False:
+        hints.append("engine not running")
+
+    # connectivity: 列表形式，每项 {name, url, ok, message}
+    conn = stages.get("connectivity") or []
+    failed_conns = [c.get("name", "?") for c in conn
+                    if isinstance(c, dict) and not c.get("ok")]
+    if failed_conns:
+        hints.append(f"connectivity failed: {','.join(failed_conns)}")
+
+    split = stages.get("split_routing")
+    if isinstance(split, dict) and split.get("ok") is False:
+        hints.append("split routing inactive (proxy == direct egress)")
+
+    if dns_bad:
+        # 保留旧行为：DNS 异常时引导 proxyctl fix
+        hints.append("DNS unhealthy — try `proxyctl fix`")
+
+    return hints
+
+
 def cmd_check(engine, api: str, api_secret: str,
               config: dict, mode_str: str = "", registry=None):
     """proxyctl check — 4 阶段全面健康检查。
@@ -923,11 +969,13 @@ def cmd_check(engine, api: str, api_secret: str,
     if as_json:
         _sys.stdout = _real_stdout
         from proxyctl._io import emit_json, envelope, OK, GENERIC
-        hint = "proxyctl fix" if dns_bad else None
+        # 失败时聚合每个失败 stage 的简短摘要到 hints。
+        # 不让 agent 在 envelope.ok=False 时还要挖 stages.*.ok 才定位真凶。
+        hints = _collect_fail_hints(collector, dns_bad=dns_bad, failed=fail)
         emit_json(envelope("check", data=collector,
                            ok=(not fail),
                            code=OK if not fail else GENERIC,
-                           hint=hint))
+                           hints=hints))
         _sys.exit(0 if not fail else 1)
     if as_plain:
         _sys.stdout = _real_stdout

{proxyctl-0.4.1 → proxyctl-0.4.3}/src/proxyctl/cli.py

@@ -1581,6 +1581,8 @@ def cmd_version_print() -> None:
                 "doctor_healthy_field":    True,   # 0.3.3
                 "agent_guide_sections":    True,   # 0.3.3
                 "log_ndjson_v2":           True,
+                "lifecycle_dry_run":       True,   # 0.4.2: start/stop/restart/recover --dry-run
+                "version_subcommand":      True,   # 0.4.2: `proxyctl version` 子命令
             },
         }
         _io.emit_json(_io.envelope("version", data=data))
@@ -1814,6 +1816,50 @@ def _dns_unlock_subprocess_argvs(plist_path: str,
     ]
 
 
+def _service_start_argvs(backend: Backend) -> list[list[str]]:
+    """返回 service_start 的 argv list（不含 sudo），平台分流。
+
+    macOS：[cp <src> <dst>, launchctl bootstrap system <plist>]
+      cp 是 conditional（plist 已存在时跳过），plan 作为上界总展示。
+    Linux：[systemctl --user start <unit>]
+    """
+    if IS_MACOS:
+        src = os.path.join(DEFAULT_CONFIG_DIR, "launchdaemons",
+                            os.path.basename(backend.plist))
+        return [
+            ["cp", src, backend.plist],
+            ["launchctl", "bootstrap", "system", backend.plist],
+        ]
+    return [["systemctl", "--user", "start", backend.unit]]
+
+
+def _service_stop_argvs(backend: Backend) -> list[list[str]]:
+    """返回 service_stop 的 argv list（不含 sudo），平台分流。"""
+    if IS_MACOS:
+        return [["launchctl", "bootout", backend.label]]
+    return [["systemctl", "--user", "stop", backend.unit]]
+
+
+def _service_restart_argvs(backend: Backend) -> list[list[str]]:
+    """返回 service_restart 的 argv list（不含 sudo），平台分流。"""
+    if IS_MACOS:
+        return [["launchctl", "kickstart", "-k", backend.label]]
+    return [["systemctl", "--user", "restart", backend.unit]]
+
+
+def _recover_curl_endpoints(api_base: str) -> dict:
+    """返回 cmd_recover 三个 Clash API endpoint 的 URL。
+
+    每个 endpoint 进入 plan 时作为 http_put action 的 target；contract test
+    用宽松断言（actual curl argv 中包含该 URL 子串）验证 plan ↔ exec 一致。
+    """
+    return {
+        "configs_reload": f"{api_base}/configs?force=true",
+        "fakeip_flush":   f"{api_base}/cache/fakeip/flush",
+        "proxies":        f"{api_base}/proxies",
+    }
+
+
 def _plan_mode(backend, target: str) -> list[dict]:
     """mode tun / mode proxy 的 plan。
 
@@ -2048,6 +2094,192 @@ def _plan_dns_unlock(config: dict) -> list[dict]:
     ]
 
 
+# ── start / stop / restart / restart-clean / recover plan helpers ───────────
+#
+# 0.4.2 起，原本完全没接 _maybe_dry_run 的 5 个写命令补上 plan：
+# - 跨平台：plan 按 IS_MACOS 分流，macOS 列 launchctl + 系统联动；
+#   Linux 列 systemctl --user
+# - actual ⊆ plan：DNS 注入 / proxy 激活等 iterating system_op 用描述性
+#   target；conditional 步骤（首次 cp、dns-lock conditional bootstrap、
+#   proxy_activate 仅 mode==proxy）作为上界总列出，contract test 用
+#   silence_helpers + actual ⊆ plan 方向天然容纳。
+
+def _plan_start(backend, config) -> list[dict]:
+    """start 的 plan：启动引擎 + macOS 系统联动（DNS/dns-lock/proxy）。"""
+    argvs = _service_start_argvs(backend)
+    if not IS_MACOS:
+        return [
+            {"action": "subprocess",
+             "target": " ".join(argvs[0]),
+             "summary": f"通过 systemctl --user 启动 {backend.unit}",
+             "reversible": True, "requires_sudo": False,
+             "side_effects": ["process"]},
+        ]
+    dns_lock_label = config.get("dns_lock_label", DEFAULTS["dns_lock_label"])
+    dns_lock_plist = f"/Library/LaunchDaemons/{dns_lock_label}.plist"
+    proxy_port = config.get("proxy_port", DEFAULTS["proxy_port"])
+    return [
+        {"action": "subprocess",
+         "target": " ".join(argvs[0]),
+         "summary": f"如 {backend.plist} 不存在则从源拷贝 plist（首次安装）",
+         "reversible": True, "requires_sudo": True,
+         "side_effects": ["config-write"]},
+        {"action": "subprocess",
+         "target": " ".join(argvs[1]),
+         "summary": f"启动引擎 {backend.name}",
+         "reversible": True, "requires_sudo": True,
+         "side_effects": ["process"]},
+        {"action": "system_op",
+         "target": "networksetup -setdnsservers (per service) 127.0.0.1 + "
+                   "scutil 三层注入 + dscacheutil -flushcache",
+         "summary": "系统 DNS → 127.0.0.1（三层防线）",
+         "reversible": True, "requires_sudo": True,
+         "side_effects": ["system"]},
+        {"action": "subprocess",
+         "target": " ".join(["launchctl", "bootstrap", "system",
+                              dns_lock_plist]),
+         "summary": f"启动 DNS 看门狗 daemon（如已部署但未运行）",
+         "reversible": True, "requires_sudo": True,
+         "side_effects": ["process"]},
+        {"action": "system_op",
+         "target": f"networksetup -setwebproxy* / -setsecurewebproxy* / "
+                   f"-setsocksfirewallproxy* (per service) 127.0.0.1:{proxy_port}",
+         "summary": "开启系统代理（仅 mode=proxy 时；mode=tun 时跳过）",
+         "reversible": True, "requires_sudo": True,
+         "side_effects": ["system"]},
+    ]
+
+
+def _plan_stop(backend, config) -> list[dict]:
+    """stop 的 plan：停止引擎 + macOS 还原系统配置。"""
+    argvs = _service_stop_argvs(backend)
+    if not IS_MACOS:
+        return [
+            {"action": "subprocess",
+             "target": " ".join(argvs[0]),
+             "summary": f"通过 systemctl --user 停止 {backend.unit}",
+             "reversible": True, "requires_sudo": False,
+             "side_effects": ["process"]},
+        ]
+    dns_lock_label = config.get("dns_lock_label", DEFAULTS["dns_lock_label"])
+    full_lock_label = f"system/{dns_lock_label}"
+    return [
+        {"action": "subprocess",
+         "target": " ".join(["launchctl", "bootout", full_lock_label]),
+         "summary": "停止 DNS 看门狗 daemon（如在跑）",
+         "reversible": True, "requires_sudo": True,
+         "side_effects": ["process"]},
+        {"action": "system_op",
+         "target": "networksetup -setdnsservers (per service) empty + "
+                   "scutil remove + dscacheutil -flushcache",
+         "summary": "还原系统 DNS（清除三层注入）",
+         "reversible": True, "requires_sudo": True,
+         "side_effects": ["system"]},
+        {"action": "system_op",
+         "target": "networksetup -setwebproxystate / -setsecurewebproxystate / "
+                   "-setsocksfirewallproxystate (per service) off",
+         "summary": "关闭系统代理",
+         "reversible": True, "requires_sudo": True,
+         "side_effects": ["system"]},
+        {"action": "subprocess",
+         "target": " ".join(argvs[0]),
+         "summary": f"停止引擎 {backend.name}",
+         "reversible": True, "requires_sudo": True,
+         "side_effects": ["process"]},
+    ]
+
+
+def _plan_restart(backend, config, *, clean: bool = False) -> list[dict]:
+    """restart / restart-clean 的 plan。
+
+    clean=True 时额外加 fs_remove backend.cache_file。
+    """
+    steps: list[dict] = []
+    if clean:
+        steps.append({
+            "action": "fs_remove",
+            "target": backend.cache_file,
+            "summary": f"删除引擎缓存 {backend.cache_file}",
+            "reversible": False,
+            "side_effects": ["cache"],
+        })
+    steps.append({
+        "action": "fs_remove",
+        "target": "/tmp/proxyctl-recover-* /tmp/sb-recover-* /tmp/sb-proxy-fail",
+        "summary": "清空 watchdog 失败状态文件（避免误判触顶窗口）",
+        "reversible": False,
+        "side_effects": ["cache"],
+    })
+    argvs = _service_restart_argvs(backend)
+    if not IS_MACOS:
+        steps.append({
+            "action": "subprocess",
+            "target": " ".join(argvs[0]),
+            "summary": f"通过 systemctl --user 重启 {backend.unit}",
+            "reversible": True, "requires_sudo": False,
+            "side_effects": ["process"],
+        })
+        return steps
+    proxy_port = config.get("proxy_port", DEFAULTS["proxy_port"])
+    dns_lock_label = config.get("dns_lock_label", DEFAULTS["dns_lock_label"])
+    dns_lock_plist = f"/Library/LaunchDaemons/{dns_lock_label}.plist"
+    steps.extend([
+        {"action": "subprocess",
+         "target": " ".join(argvs[0]),
+         "summary": f"重启引擎 {backend.name}",
+         "reversible": True, "requires_sudo": True,
+         "side_effects": ["process"]},
+        {"action": "system_op",
+         "target": "networksetup -setdnsservers (per service) 127.0.0.1 + "
+                   "scutil 三层注入 + dscacheutil -flushcache",
+         "summary": "系统 DNS → 127.0.0.1（刷新三层防线）",
+         "reversible": True, "requires_sudo": True,
+         "side_effects": ["system"]},
+        {"action": "subprocess",
+         "target": " ".join(["launchctl", "bootstrap", "system",
+                              dns_lock_plist]),
+         "summary": "启动 DNS 看门狗 daemon（如已部署但未运行）",
+         "reversible": True, "requires_sudo": True,
+         "side_effects": ["process"]},
+        {"action": "system_op",
+         "target": f"networksetup -setwebproxy* / -setsecurewebproxy* / "
+                   f"-setsocksfirewallproxy* (per service) 127.0.0.1:{proxy_port}",
+         "summary": "开启系统代理（mode=proxy 时）/ 关闭（mode=tun 时）",
+         "reversible": True, "requires_sudo": True,
+         "side_effects": ["system"]},
+    ])
+    return steps
+
+
+def _plan_recover(backend, config) -> list[dict]:
+    """recover 的 plan：3 个 Clash API 请求，不重启进程。
+
+    用 http_put action（与 _plan_fix 风格一致），实际 cmd_recover 还会对
+    /group/<name>/delay endpoint 并发请求 N 次做 healthcheck —— plan 把
+    healthcheck 整体折成一个 http_put step，target=描述性 endpoint pattern。
+    """
+    api_base = config.get("api_base", DEFAULTS["api_base"])
+    eps = _recover_curl_endpoints(api_base)
+    return [
+        {"action": "http_put",
+         "target": eps["configs_reload"],
+         "summary": "热重载配置（PUT /configs?force=true，清 DNS 缓存）",
+         "reversible": True,
+         "side_effects": ["network-io"]},
+        {"action": "http_put",
+         "target": eps["fakeip_flush"],
+         "summary": "清空 fakeip 缓存（POST /cache/fakeip/flush）",
+         "reversible": True,
+         "side_effects": ["cache", "network-io"]},
+        {"action": "http_put",
+         "target": eps["proxies"],
+         "summary": "拉取 proxies 列表 + 对 URLTest/Fallback/LoadBalance 组并发 "
+                   "GET /group/<name>/delay 触发 healthcheck",
+         "reversible": True,
+         "side_effects": ["network-io"]},
+    ]
+
+
 # ── 主入口 ────────────────────────────────────────────────────────────────────
 
 def main():
@@ -2138,12 +2370,31 @@ def main():
 
 # ── Dispatch handlers + 路由表 ────────────────────────────────────────────
 
-def _h_start(ctx):    cmd_start(ctx["backend"], ctx["config"], registry=ctx["registry"])
-def _h_stop(ctx):     cmd_stop(ctx["backend"], ctx["config"], registry=ctx["registry"])
-def _h_restart(ctx):  cmd_restart(ctx["backend"], ctx["config"], registry=ctx["registry"])
+def _h_start(ctx):
+    _maybe_dry_run("start", lambda: _plan_start(ctx["backend"], ctx["config"]))
+    cmd_start(ctx["backend"], ctx["config"], registry=ctx["registry"])
+
+def _h_stop(ctx):
+    _maybe_dry_run("stop", lambda: _plan_stop(ctx["backend"], ctx["config"]))
+    cmd_stop(ctx["backend"], ctx["config"], registry=ctx["registry"])
+
+def _h_restart(ctx):
+    _maybe_dry_run(
+        "restart",
+        lambda: _plan_restart(ctx["backend"], ctx["config"], clean=False))
+    cmd_restart(ctx["backend"], ctx["config"], registry=ctx["registry"])
+
 def _h_restart_clean(ctx):
-    cmd_restart(ctx["backend"], ctx["config"], clean=True, registry=ctx["registry"])
-def _h_recover(ctx):  cmd_recover(ctx["backend"], ctx["config"])
+    _maybe_dry_run(
+        "restart-clean",
+        lambda: _plan_restart(ctx["backend"], ctx["config"], clean=True))
+    cmd_restart(ctx["backend"], ctx["config"], clean=True,
+                registry=ctx["registry"])
+
+def _h_recover(ctx):
+    _maybe_dry_run("recover",
+                   lambda: _plan_recover(ctx["backend"], ctx["config"]))
+    cmd_recover(ctx["backend"], ctx["config"])
 def _h_dns_unlock(ctx):
     _maybe_dry_run("dns-unlock", lambda: _plan_dns_unlock(ctx["config"]))
     _exec_with_lock("daemon", "dns-unlock", cmd_dns_unlock, ctx["config"])
@@ -2317,6 +2568,11 @@ def _h_help(ctx):
         cmd_help()
 
 
+def _h_version(ctx):
+    """proxyctl version — 子命令形式，与 --version flag 输出一致。"""
+    cmd_version_print()
+
+
 DISPATCH: dict = {
     "start":           _h_start,
     "stop":            _h_stop,
@@ -2346,6 +2602,7 @@ DISPATCH: dict = {
     "doctor":          _h_doctor,
     "completion":      _h_completion,
     "help":            _h_help,
+    "version":         _h_version,
 }
 
 

{proxyctl-0.4.1 → proxyctl-0.4.3}/src/proxyctl/completion.py

@@ -26,8 +26,10 @@ from __future__ import annotations
 import sys
 
 
-# 0.3.x：写命令支持 --dry-run（与 COMMANDS_META.supports_dry_run 同步）
-_DRY_RUN_CMDS = ("mode", "engine", "fix", "audit", "config",
+# 写命令支持 --dry-run（与 COMMANDS_META.supports_dry_run 同步）
+# 0.4.2 起，lifecycle 4 个 + recover 也补齐 --dry-run。
+_DRY_RUN_CMDS = ("start", "stop", "restart", "restart-clean", "recover",
+                 "mode", "engine", "fix", "audit", "config",
                  "daemon", "claude-proxy", "dns-lock", "dns-unlock")
 # 0.3.x：audit / check 支持 --plain
 _PLAIN_CMDS = ("audit", "check")

{proxyctl-0.4.1 → proxyctl-0.4.3}/src/proxyctl/explain.py

@@ -858,23 +858,30 @@ COMMANDS_META: list[dict] = [
     {"name": "start", "group": "lifecycle", "summary": "启动引擎 + 注入 DNS/代理",
      "args": [], "supports_json": False,
      "side_effects": ["process", "system"],
+     "supports_dry_run": True,
      "needs_sudo": True, "interactive": False,
-     "exit_codes": [0, 1, 5], "examples": ["proxyctl start"]},
+     "exit_codes": [0, 1, 5],
+     "examples": ["proxyctl start", "proxyctl start --dry-run"]},
     {"name": "stop", "group": "lifecycle", "summary": "停止引擎 + 还原系统配置",
      "args": [], "supports_json": False,
      "side_effects": ["process", "system"],
+     "supports_dry_run": True,
      "needs_sudo": True, "interactive": False,
-     "exit_codes": [0, 1], "examples": ["proxyctl stop"]},
+     "exit_codes": [0, 1],
+     "examples": ["proxyctl stop", "proxyctl stop --dry-run"]},
     {"name": "restart", "group": "lifecycle", "summary": "重启引擎",
      "args": [], "supports_json": False,
      "side_effects": ["process", "system"],
+     "supports_dry_run": True,
      "needs_sudo": True, "interactive": False, "exit_codes": [0, 1],
-     "examples": ["proxyctl restart"]},
+     "examples": ["proxyctl restart", "proxyctl restart --dry-run"]},
     {"name": "restart-clean", "group": "lifecycle", "summary": "重启并清除缓存",
      "args": [], "supports_json": False,
      "side_effects": ["process", "system", "cache"],
+     "supports_dry_run": True,
      "needs_sudo": True, "interactive": False, "exit_codes": [0, 1],
-     "examples": ["proxyctl restart-clean"]},
+     "examples": ["proxyctl restart-clean",
+                  "proxyctl restart-clean --dry-run"]},
     # diagnostic
     {"name": "status", "group": "diagnostic", "summary": "系统状态面板",
      "args": [], "supports_json": True, "side_effects": [],
@@ -935,8 +942,9 @@ COMMANDS_META: list[dict] = [
     {"name": "recover", "group": "maintenance",
      "summary": "切网后软恢复（清 DNS 缓存 + 重测代理组，不重启）",
      "args": [], "supports_json": False, "side_effects": ["cache", "network-io"],
+     "supports_dry_run": True,
      "needs_sudo": False, "interactive": False, "exit_codes": [0, 1, 2, 5, 7],
-     "examples": ["proxyctl recover"]},
+     "examples": ["proxyctl recover", "proxyctl recover --dry-run"]},
     # daemon / dns-lock
     {"name": "daemon", "group": "daemon",
      "summary": "管理 extra_daemons（如 claude-proxy）",
@@ -1050,6 +1058,11 @@ COMMANDS_META: list[dict] = [
      "needs_sudo": False, "interactive": False, "exit_codes": [0, 2],
      "examples": ["proxyctl help", "proxyctl help mode",
                   "proxyctl mode --help"]},
+    {"name": "version", "group": "agent",
+     "summary": "版本号 + supported_features（等价 --version；--json 输出 envelope）",
+     "args": [], "supports_json": True, "side_effects": [],
+     "needs_sudo": False, "interactive": False, "exit_codes": [0],
+     "examples": ["proxyctl version", "proxyctl version --json"]},
 ]