proxyctl 0.5.4__tar.gz → 0.5.5__tar.gz

{proxyctl-0.5.4 → proxyctl-0.5.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: proxyctl
-Version: 0.5.4
+Version: 0.5.5
 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

{proxyctl-0.5.4 → proxyctl-0.5.5}/man/proxyctl.1

@@ -131,6 +131,12 @@ Linux systemctl --user）。
 4 阶段健康检查：basic / groups / connectivity / outbound-ip。
 \fB--plain\fR 输出 TSV（stage / ok / detail）。
 .TP
+\fBproxyctl connections\fR [\fB--app\fR \fINAME\fR ...] [\fB--all\fR] [\fB--json\fR]
+把本机 App/进程的 TCP 连接与 \fIproxy_port\fR、mihomo \fB/connections\fR
+API 的 \fIsourcePort\fR 连接详情关联。默认过滤 Codex / Claude / ChatGPT；
+\fB--all\fR 查看所有进程。只读；非 mihomo 后端或本地 API 不可用时降级输出
+unmatched。
+.TP
 \fBproxyctl trace\fR \fIDOMAIN\fR [\fB--json\fR]
 4 阶段域名链路诊断：DNS 解析 / 规则匹配预测 / 连通性 / 实际连接。
 .TP

{proxyctl-0.5.4 → proxyctl-0.5.5}/pyproject.toml

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

{proxyctl-0.5.4 → proxyctl-0.5.5}/src/proxyctl/_io.py

@@ -72,6 +72,7 @@ _COLOR_NAMES = ("RED", "GREEN", "YELLOW", "CYAN", "BOLD", "DIM", "NC")
 _COLOR_MODULES_KNOWN = (
     "proxyctl.cli", "proxyctl.status", "proxyctl.check",
     "proxyctl.trace", "proxyctl.audit", "proxyctl.explain",
+    "proxyctl.connections",
 )
 
 

{proxyctl-0.5.4 → proxyctl-0.5.5}/src/proxyctl/check.py

@@ -251,17 +251,9 @@ def _proxy_groups_section(api_base: str, api_secret: str,
         print(f"  {CYAN}{gname}{NC}({gtype}) → {BOLD}{gnow}{NC} "
               f"{ds(gnow_d)}ms  [{count_str} of {total}]{tested_str}")
 
-        # v0.5.4：selector/fallback 类型 + now 指向子组时，
-        # 跳过顶层成员列表（避免跟子组节点重复），只展开 now 那一个子组。
-        # now 指向真节点时仍打印顶层成员（用户可能想看其他可选项）。
-        sub = (proxies.get(gnow) if g.get("type") in ("Selector", "Fallback")
-               else None)
-        now_is_subgroup = bool(sub and sub.get("all"))
-        if g.get("type") in ("Selector", "Fallback") and not now_is_subgroup:
-            print_members(gmembers, gnow)
-        elif g.get("type") not in ("Selector", "Fallback"):
-            print_members(gmembers, gnow)
-        if now_is_subgroup:
+        def print_sub_summary(sub_name: str, sub: dict, is_now: bool) -> bool:
+            """打印一行子组 summary（含 → now 标记 + 健康度 + tested ago）。
+            返回该子组之前是否已展开过叶子。"""
             sub_type = "url" if sub.get("type") == "URLTest" else "sel"
             sub_now = sub.get("now", "?")
             sub_now_d = get_delay(sub_now)
@@ -275,13 +267,46 @@ def _proxy_groups_section(api_base: str, api_secret: str,
             if s_nodata: sc.append(f"{YELLOW}{s_nodata}—{NC}")
             st = group_tested_ago(sub_members)
             st_str = f"  {DIM}{st}{NC}" if st else ""
-            already = gnow in expanded_subgroups
+            already = sub_name in expanded_subgroups
             tail = f"  {DIM}(详见上方){NC}" if already else ""
-            print(f"    {CYAN}{gnow}{NC}({sub_type}) → {BOLD}{sub_now}{NC} "
-                  f"{ds(sub_now_d)}ms  [{'/'.join(sc)} of {len(sub_members)}]{st_str}{tail}")
-            if not already:
-                print_members(sub_members, sub_now)
-                expanded_subgroups.add(gnow)
+            marker = "→" if is_now else " "
+            print(f"   {marker}{CYAN}{sub_name}{NC}({sub_type}) → "
+                  f"{BOLD}{sub_now}{NC} "
+                  f"{ds(sub_now_d)}ms  [{'/'.join(sc)} of {len(sub_members)}]"
+                  f"{st_str}{tail}")
+            return already
+
+        # v0.5.5：selector/fallback 含子组时，每个子组都打一行 summary（让
+        # 用户看到兄弟子组存在 + 健康度），但只对 now 子组展开叶子（保留
+        # v0.5.3 精简意图）。混在子组里的真节点（如 local-N）按 4 列表格
+        # flush。selector/fallback 全为真节点 / 其他类型组：原 print_members
+        # 行为不变。
+        if g.get("type") in ("Selector", "Fallback"):
+            has_subgroup = any(proxies.get(m, {}).get("all") for m in gmembers)
+            if not has_subgroup:
+                print_members(gmembers, gnow)
+            else:
+                leaf_buf: list = []
+
+                def flush_leaves():
+                    if leaf_buf:
+                        print_members(leaf_buf, gnow)
+                        leaf_buf.clear()
+
+                for m in gmembers:
+                    sub = proxies.get(m, {})
+                    if sub.get("all"):
+                        flush_leaves()
+                        already = print_sub_summary(m, sub, is_now=(m == gnow))
+                        if m == gnow and not already:
+                            print_members(sub.get("all", []),
+                                          sub.get("now", "?"))
+                        expanded_subgroups.add(m)
+                    else:
+                        leaf_buf.append(m)
+                flush_leaves()
+        else:
+            print_members(gmembers, gnow)
         # 顶层组本身展开完后也标记，避免被下层组重新展开
         expanded_subgroups.add(gname)
 

{proxyctl-0.5.4 → proxyctl-0.5.5}/src/proxyctl/cli.py

@@ -70,8 +70,11 @@ def load_config() -> dict:
                 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")
+            print(f"{YELLOW}警告：读取配置文件失败：{e}{NC}", file=sys.stderr)
+            print(
+                f"  使用默认配置，可能需要在 {CONFIG_FILE} 中配置 api_secret",
+                file=sys.stderr,
+            )
     return cfg
 
 
@@ -1501,8 +1504,17 @@ def cmd_help():
           f"{DIM}一键 JSON + 关色 + 非交互{NC}")
     print()
 
+    print(f"{BOLD}常用示例{NC}")
+    print(f"  {CYAN}proxyctl doctor --json{NC}              "
+          f"{DIM}最快健康基线，agent 首选{NC}")
+    print(f"  {CYAN}proxyctl mode tun -n --json{NC}         "
+          f"{DIM}预览写操作 plan，不执行{NC}")
+    print(f"  {CYAN}proxyctl help trace{NC}                 "
+          f"{DIM}查看单命令用法和示例{NC}")
+    print()
+
     print(f"{BOLD}用法{NC}  proxyctl <command> [args] "
-          f"[--json|--plain] [--dry-run] [--no-color] [--quiet]")
+          f"[--json|--plain] [--dry-run|-n] [--no-color] [--quiet]")
     print()
 
     # 按 group 元数据驱动渲染
@@ -1533,7 +1545,7 @@ def cmd_help():
     print(f"{BOLD}全局 flag{NC}")
     print(f"  --json         输出 envelope JSON（schema v2）")
     print(f"  --plain        输出纯 TSV（audit/check 等支持表格的命令）")
-    print(f"  --dry-run      预演写操作（输出 plan，不真正执行）")
+    print(f"  --dry-run/-n   预演写操作（输出 plan，不真正执行）")
     print(f"  --no-color     关闭 ANSI（也读 NO_COLOR）")
     print(f"  --quiet/-q     压制非关键 stderr")
     print(f"  --help/-h      本帮助")
@@ -1647,6 +1659,7 @@ def cmd_version_print() -> None:
                 "lock_path_in_error":      True,
                 "side_effects_enum":       True,
                 "dry_run":                 True,
+                "dry_run_short_flag":      True,
                 "plain":                   True,
                 "flag_position_invariant": True,
                 "agents_md":               True,
@@ -1751,7 +1764,7 @@ def _extract_global_flags(argv: list) -> tuple:
     """从 argv 中剥离全局 flag，返回 (剩余 argv, flag dict)。
 
     clig.dev 原则：flag 位置无关 — 在任意位置出现的 --json / --no-color /
-    --quiet / -q / --dry-run / --plain 都会被识别并剥离，剩余位置参数顺序保持不变。
+    --quiet / -q / --dry-run / -n / --plain 都会被识别并剥离，剩余位置参数顺序保持不变。
     """
     flags = {
         "json": False, "no_color": False, "quiet": False,
@@ -1765,7 +1778,7 @@ def _extract_global_flags(argv: list) -> tuple:
             flags["no_color"] = True
         elif a in ("--quiet", "-q"):
             flags["quiet"] = True
-        elif a == "--dry-run":
+        elif a in ("--dry-run", "-n"):
             flags["dry_run"] = True
         elif a == "--plain":
             flags["plain"] = True
@@ -2732,6 +2745,10 @@ def _h_check(ctx):
     cmd_check(ctx["backend"], ctx["api_base"], ctx["api_secret"],
               ctx["config"], mode_str, registry=ctx["registry"])
 
+def _h_connections(ctx):
+    from proxyctl.connections import cmd_connections
+    cmd_connections(ctx["args"], ctx["backend"], ctx["config"])
+
 def _h_bench(ctx):
     from proxyctl.check import cmd_bench
     bench_groups = ctx["args"] or None
@@ -2898,6 +2915,7 @@ DISPATCH: dict = {
     "status":          _h_status,
     "log":             _h_log,
     "check":           _h_check,
+    "connections":     _h_connections,
     "bench":           _h_bench,
     "fix":             _h_fix,
     "recover":         _h_recover,
@@ -2965,4 +2983,4 @@ def _suggest_command_and_exit(unknown: str) -> None:
 
 
 if __name__ == "__main__":
-    main()
+    main()

{proxyctl-0.5.4 → proxyctl-0.5.5}/src/proxyctl/completion.py

@@ -4,7 +4,7 @@
 0.3.x 起补全：
 
   - 全局 flag: --help / --version / --json / --no-color / --quiet
-              / --dry-run / --plain
+              / --dry-run / -n / --plain
   - explain <topic>          → topic 列表
   - mode <tun|proxy>          → 模式
   - engine <mihomo|singbox>   → 引擎
@@ -66,7 +66,7 @@ _proxyctl_complete() {{
 
     # 第二个 token = 子命令
     if [ ${{COMP_CWORD}} -eq 1 ]; then
-        COMPREPLY=( $(compgen -W "${{cmds}} help --help --version --json --plain --dry-run --no-color --quiet" -- "${{cur}}") )
+        COMPREPLY=( $(compgen -W "${{cmds}} help --help --version --json --plain --dry-run -n --no-color --quiet" -- "${{cur}}") )
         return 0
     fi
 
@@ -133,7 +133,7 @@ _proxyctl_complete() {{
     local dry_run_cmds=({dry_run_cmds})
     for c in "${{dry_run_cmds[@]}}"; do
         if [ "$first" = "$c" ]; then
-            COMPREPLY=( $(compgen -W "--dry-run --json --no-color --quiet --help" -- "${{cur}}") )
+            COMPREPLY=( $(compgen -W "--dry-run -n --json --no-color --quiet --help" -- "${{cur}}") )
             return 0
         fi
     done
@@ -142,7 +142,7 @@ _proxyctl_complete() {{
     local plain_cmds=({plain_cmds})
     for c in "${{plain_cmds[@]}}"; do
         if [ "$first" = "$c" ]; then
-            COMPREPLY=( $(compgen -W "--plain --json --dry-run --help" -- "${{cur}}") )
+            COMPREPLY=( $(compgen -W "--plain --json --dry-run -n --help" -- "${{cur}}") )
             return 0
         fi
     done
@@ -160,7 +160,7 @@ _proxyctl_complete() {{
     fi
 
     # 默认 flag 补全
-    COMPREPLY=( $(compgen -W "--help --json --plain --dry-run --no-color --quiet" -- "${{cur}}") )
+    COMPREPLY=( $(compgen -W "--help --json --plain --dry-run -n --no-color --quiet" -- "${{cur}}") )
 }}
 complete -F _proxyctl_complete proxyctl
 """
@@ -204,6 +204,7 @@ _proxyctl() {{
     '--json[结构化 envelope v2 输出]' \\
     '--plain[纯 TSV 输出（audit/check）；与 --json 互斥]' \\
     '--dry-run[预演写命令；输出 data.plan]' \\
+    '-n[预演写命令；输出 data.plan]' \\
     '--no-color[关闭 ANSI 颜色]' \\
     '--quiet[安静模式]' \\
     '-q[安静模式]'
@@ -258,7 +259,7 @@ def _gen_fish() -> str:
              "complete -c proxyctl -l version -d '显示版本'",
              "complete -c proxyctl -l json -d 'envelope v2 输出'",
              "complete -c proxyctl -l plain -d 'TSV 输出（audit/check）'",
-             "complete -c proxyctl -l dry-run -d '预演写命令'",
+             "complete -c proxyctl -s n -l dry-run -d '预演写命令'",
              "complete -c proxyctl -l no-color -d '关闭 ANSI'",
              "complete -c proxyctl -l quiet -d '安静模式'",
              ""]

proxyctl-0.5.5/src/proxyctl/connections.py

@@ -0,0 +1,466 @@
+"""proxyctl connections — join local app sockets with mihomo connections.
+
+The command is intentionally read-only: it reads lsof/ps output and, for the
+mihomo backend, the local Clash-compatible `/connections` controller endpoint.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import subprocess
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+from typing import Any
+
+from proxyctl import _io
+from proxyctl._io import maybe_disable_module_colors
+
+BOLD = "\033[1m"
+DIM = "\033[2m"
+GREEN = "\033[0;32m"
+YELLOW = "\033[0;33m"
+CYAN = "\033[0;36m"
+NC = "\033[0m"
+
+maybe_disable_module_colors(__name__)
+
+DEFAULT_APP_FILTERS = ["Codex", "Claude", "ChatGPT"]
+
+
+@dataclass
+class LocalConnection:
+    """One local TCP connection reported by lsof.
+
+    Attributes:
+        pid: Owning process id.
+        app: Short process name from lsof.
+        fd: File descriptor label from lsof, for example ``12u``.
+        source_port: Local ephemeral port used to connect to proxy_port.
+        target_host: Destination host from lsof's NAME field.
+        target_port: Destination port from lsof's NAME field.
+        raw_name: Original lsof NAME field.
+        process: Full executable path from ps, when available.
+        command: Full command line from ps, when available.
+    """
+
+    pid: int
+    app: str
+    fd: str
+    source_port: int
+    target_host: str
+    target_port: int
+    raw_name: str
+    process: str = ""
+    command: str = ""
+
+    def matches_app(self, filters: list[str]) -> bool:
+        """Return whether this row matches any requested ``--app`` filter."""
+        if not filters:
+            return True
+        haystack = " ".join(
+            [self.app, os.path.basename(self.process), self.process, self.command]
+        ).lower()
+        return any(f.lower() in haystack for f in filters)
+
+    def to_dict(self, proxy_port: int) -> dict[str, Any]:
+        """Convert the lsof row to the JSON contract used by this command."""
+        return {
+            "app": self.app,
+            "pid": self.pid,
+            "fd": self.fd,
+            "process": self.process,
+            "local_source_port": self.source_port,
+            "target_host": self.target_host,
+            "target_port": self.target_port,
+            "connects_proxy_port": self.target_port == proxy_port,
+            "raw_lsof_name": self.raw_name,
+        }
+
+
+@dataclass
+class ConnectionArgs:
+    """Parsed arguments for ``proxyctl connections``.
+
+    Attributes:
+        app_filters: Process/app filters; empty means all processes.
+        all_apps: Whether ``--all`` was explicitly requested.
+    """
+
+    app_filters: list[str]
+    all_apps: bool = False
+
+
+def parse_args(args: list[str]) -> ConnectionArgs:
+    """Parse ``proxyctl connections`` arguments.
+
+    Supported syntax:
+        ``--app NAME`` may appear more than once.
+        ``--all`` disables the default AI app filter.
+    """
+    apps: list[str] = []
+    all_apps = False
+    idx = 0
+    while idx < len(args):
+        arg = args[idx]
+        if arg == "--all":
+            all_apps = True
+            idx += 1
+            continue
+        if arg == "--app":
+            if idx + 1 >= len(args):
+                _io.fail("connections --app 需要一个应用名",
+                         hint="proxyctl connections --app Codex --json",
+                         doc="agent-protocol", code=_io.USAGE,
+                         cmd="connections")
+            apps.append(args[idx + 1])
+            idx += 2
+            continue
+        _io.fail(f"未识别 connections 参数：{arg}",
+                 hints=["proxyctl connections --app Codex --app Claude",
+                        "proxyctl connections --all --json",
+                        "proxyctl connections --json"],
+                 doc="agent-protocol", code=_io.USAGE, cmd="connections")
+    if all_apps and apps:
+        _io.fail("connections 的 --all 与 --app 不能同时使用",
+                 hint="proxyctl connections --all --json",
+                 doc="agent-protocol", code=_io.USAGE, cmd="connections")
+    return ConnectionArgs(
+        app_filters=[] if all_apps else (apps or DEFAULT_APP_FILTERS),
+        all_apps=all_apps,
+    )
+
+
+def _parse_lsof_name(name: str) -> tuple[int, str, int] | None:
+    """Parse lsof NAME into ``(source_port, target_host, target_port)``.
+
+    The format differs slightly across macOS/Linux and IPv4/IPv6, but the
+    stable part for established TCP is ``local:port->remote:port``.
+    """
+    if "->" not in name:
+        return None
+    left, right = name.split("->", 1)
+    right = right.split(" ", 1)[0]
+    source_match = re.search(r":(\d+)$", left.strip("[]"))
+    target_match = re.search(r"(.+):(\d+)$", right.strip())
+    if not source_match or not target_match:
+        return None
+    target_host = target_match.group(1).strip("[]")
+    return int(source_match.group(1)), target_host, int(target_match.group(2))
+
+
+def _parse_endpoint(endpoint: str) -> tuple[str, int] | None:
+    """Parse ``host:port`` or ``[ipv6]:port`` endpoint text."""
+    endpoint = endpoint.strip()
+    if endpoint.startswith("["):
+        m = re.match(r"^\[([^\]]+)\]:(\d+)$", endpoint)
+        if not m:
+            return None
+        return m.group(1), int(m.group(2))
+    if ":" not in endpoint:
+        return None
+    host, port = endpoint.rsplit(":", 1)
+    try:
+        return host.strip("[]"), int(port)
+    except ValueError:
+        return None
+
+
+def parse_lsof_fields(text: str) -> list[LocalConnection]:
+    """Parse ``lsof -Fpcfn`` established TCP output."""
+    rows: list[LocalConnection] = []
+    pid: int | None = None
+    app = ""
+    fd = ""
+    for line in text.splitlines():
+        if not line:
+            continue
+        tag, value = line[0], line[1:]
+        if tag == "p":
+            try:
+                pid = int(value)
+            except ValueError:
+                pid = None
+            app = ""
+            fd = ""
+        elif tag == "c":
+            app = value
+        elif tag == "f":
+            fd = value
+        elif tag == "n" and pid is not None:
+            parsed = _parse_lsof_name(value)
+            if not parsed:
+                continue
+            source_port, target_host, target_port = parsed
+            rows.append(LocalConnection(
+                pid=pid, app=app, fd=fd, source_port=source_port,
+                target_host=target_host, target_port=target_port,
+                raw_name=value,
+            ))
+    return rows
+
+
+def parse_ss_lines(text: str) -> list[LocalConnection]:
+    """Parse Linux ``ss -Htnp`` established TCP output."""
+    rows: list[LocalConnection] = []
+    proc_re = re.compile(r'"(?P<app>[^"]+)",pid=(?P<pid>\d+),fd=(?P<fd>\d+)')
+    for line in text.splitlines():
+        parts = line.split()
+        if len(parts) < 5 or parts[0] != "ESTAB":
+            continue
+        local = _parse_endpoint(parts[3])
+        peer = _parse_endpoint(parts[4])
+        if not local or not peer:
+            continue
+        proc_match = proc_re.search(" ".join(parts[5:]))
+        if proc_match:
+            app = proc_match.group("app")
+            pid = int(proc_match.group("pid"))
+            fd = proc_match.group("fd")
+        else:
+            app, pid, fd = "", 0, ""
+        rows.append(LocalConnection(
+            pid=pid,
+            app=app,
+            fd=fd,
+            source_port=local[1],
+            target_host=peer[0],
+            target_port=peer[1],
+            raw_name=f"{parts[3]}->{parts[4]}",
+        ))
+    return rows
+
+
+def collect_lsof_connections(app_filters: list[str]) -> list[LocalConnection]:
+    """Collect local established TCP connections for the requested apps."""
+    cmd = ["lsof", "-nP", "-iTCP", "-sTCP:ESTABLISHED", "-Fpcfn"]
+    try:
+        proc = subprocess.run(cmd, capture_output=True, text=True, timeout=3)
+    except FileNotFoundError:
+        return collect_ss_connections(app_filters)
+    if proc.returncode == 127:
+        return collect_ss_connections(app_filters)
+    if proc.returncode not in (0, 1):
+        _io.fail("lsof 读取本机连接失败",
+                 hints=[proc.stderr.strip()] if proc.stderr else None,
+                 doc="troubleshooting", code=_io.DEPENDENCY_MISSING,
+                 cmd="connections")
+    rows = parse_lsof_fields(proc.stdout)
+    _enrich_with_ps(rows)
+    return [row for row in rows if row.matches_app(app_filters)]
+
+
+def collect_ss_connections(app_filters: list[str]) -> list[LocalConnection]:
+    """Collect Linux established TCP connections with ``ss``."""
+    cmd = ["ss", "-Htnp"]
+    try:
+        proc = subprocess.run(cmd, capture_output=True, text=True, timeout=3)
+    except FileNotFoundError:
+        _io.fail("读取本机连接需要 lsof 或 ss",
+                 hint="安装 lsof，或在 Linux 上安装 iproute2(ss)",
+                 doc="troubleshooting", code=_io.DEPENDENCY_MISSING,
+                 cmd="connections")
+    if proc.returncode != 0:
+        _io.fail("ss 读取本机连接失败",
+                 hints=[proc.stderr.strip()] if proc.stderr else None,
+                 doc="troubleshooting", code=_io.DEPENDENCY_MISSING,
+                 cmd="connections")
+    rows = parse_ss_lines(proc.stdout)
+    _enrich_with_ps([row for row in rows if row.pid])
+    return [row for row in rows if row.matches_app(app_filters)]
+
+
+def _enrich_with_ps(rows: list[LocalConnection]) -> None:
+    """Add process path and command line from ps; failures leave lsof data intact."""
+    seen: set[int] = set()
+    for row in rows:
+        if row.pid in seen:
+            continue
+        seen.add(row.pid)
+        process = _ps_field(row.pid, "comm=")
+        command = _ps_field(row.pid, "command=")
+        for same_pid in rows:
+            if same_pid.pid == row.pid:
+                same_pid.process = process
+                same_pid.command = command
+
+
+def _ps_field(pid: int, field: str) -> str:
+    """Read one ps output field for ``pid`` and return an empty string on failure."""
+    try:
+        proc = subprocess.run(["ps", "-p", str(pid), "-o", field],
+                              capture_output=True, text=True, timeout=1)
+    except Exception:
+        return ""
+    if proc.returncode != 0:
+        return ""
+    return proc.stdout.strip()
+
+
+def fetch_mihomo_connections(api_base: str, api_secret: str,
+                             *, timeout: float = 1.0) -> tuple[list[dict[str, Any]], dict[str, Any]]:
+    """Fetch local mihomo `/connections` data without using system proxies."""
+    url = f"{api_base.rstrip('/')}/connections"
+    headers = {}
+    if api_secret:
+        headers["Authorization"] = f"Bearer {api_secret}"
+    req = urllib.request.Request(url, headers=headers)
+    try:
+        opener = urllib.request.build_opener(urllib.request.ProxyHandler({}))
+        with opener.open(req, timeout=timeout) as resp:
+            payload = json.loads(resp.read())
+    except (urllib.error.URLError, OSError, TimeoutError,
+            json.JSONDecodeError) as exc:
+        return [], {"ok": False, "status": "error", "url": url,
+                    "error": str(exc)}
+    conns = payload.get("connections")
+    if not isinstance(conns, list):
+        return [], {"ok": False, "status": "error", "url": url,
+                    "error": "response missing connections[]"}
+    return conns, {"ok": True, "status": "ok", "url": url,
+                   "error": None, "count": len(conns)}
+
+
+def _connection_source_port(conn: dict[str, Any]) -> int | None:
+    """Return mihomo metadata.sourcePort as int when present."""
+    metadata = conn.get("metadata") or {}
+    port = metadata.get("sourcePort")
+    try:
+        return int(port)
+    except (TypeError, ValueError):
+        return None
+
+
+def _mihomo_detail(conn: dict[str, Any] | None) -> dict[str, Any] | None:
+    """Extract the stable mihomo fields needed by agents."""
+    if not conn:
+        return None
+    metadata = conn.get("metadata") or {}
+    return {
+        "host": metadata.get("host") or "",
+        "destination_ip": metadata.get("destinationIP") or "",
+        "destination_port": metadata.get("destinationPort"),
+        "network": metadata.get("network") or "",
+        "type": metadata.get("type") or "",
+        "rule": conn.get("rule") or "",
+        "rule_payload": conn.get("rulePayload") or "",
+        "chains": conn.get("chains") or [],
+        "upload": conn.get("upload"),
+        "download": conn.get("download"),
+        "start": conn.get("start") or "",
+        "id": conn.get("id") or "",
+    }
+
+
+def build_report(backend_name: str, config: dict[str, Any],
+                 parsed_args: ConnectionArgs) -> dict[str, Any]:
+    """Build the full joined connections report."""
+    proxy_port = int(config.get("proxy_port", 7890))
+    api_base = config.get("api_base", "http://127.0.0.1:9090")
+    api_secret = config.get("api_secret", "")
+
+    local_rows = [
+        row for row in collect_lsof_connections(parsed_args.app_filters)
+        if row.source_port != proxy_port
+    ]
+    api_status: dict[str, Any]
+    remote_by_port: dict[int, dict[str, Any]] = {}
+    proxy_rows = [row for row in local_rows if row.target_port == proxy_port]
+    if backend_name != "mihomo":
+        api_status = {
+            "ok": False, "status": "skipped", "url": None,
+            "error": f"connections join needs mihomo backend, current backend is {backend_name}",
+            "count": 0,
+        }
+    elif not proxy_rows:
+        api_status = {
+            "ok": True, "status": "skipped_no_proxy_connections", "url": None,
+            "error": None, "count": 0,
+        }
+    else:
+        remote_rows, api_status = fetch_mihomo_connections(api_base, api_secret)
+        remote_by_port = {
+            port: conn for conn in remote_rows
+            if (port := _connection_source_port(conn)) is not None
+        }
+
+    joined: list[dict[str, Any]] = []
+    for row in local_rows:
+        via_proxy = row.target_port == proxy_port
+        matched = remote_by_port.get(row.source_port) if via_proxy else None
+        if matched:
+            unmatched_reason = None
+        elif not via_proxy:
+            unmatched_reason = "not_proxyctl_proxy_port"
+        elif api_status["status"] == "skipped":
+            unmatched_reason = "backend_not_mihomo"
+        elif api_status["ok"] is False:
+            unmatched_reason = "mihomo_api_unavailable"
+        else:
+            unmatched_reason = "no_mihomo_source_port_match"
+        joined.append({
+            **row.to_dict(proxy_port),
+            "matched": matched is not None,
+            "unmatched_reason": unmatched_reason,
+            "mihomo": _mihomo_detail(matched),
+        })
+
+    proxy_count = sum(1 for row in local_rows if row.target_port == proxy_port)
+    return {
+        "proxy_port": proxy_port,
+        "backend": backend_name,
+        "apps": parsed_args.app_filters,
+        "all_apps": parsed_args.all_apps,
+        "api": api_status,
+        "connections": joined,
+        "summary": {
+            "local_count": len(local_rows),
+            "proxy_port_count": proxy_count,
+            "non_proxy_port_count": len(local_rows) - proxy_count,
+            "all_via_proxy_port": bool(local_rows) and proxy_count == len(local_rows),
+            "matched_count": sum(1 for item in joined if item["matched"]),
+            "unmatched_count": sum(1 for item in joined if not item["matched"]),
+        },
+    }
+
+
+def emit_human(report: dict[str, Any]) -> None:
+    """Render a compact human-readable report."""
+    api = report["api"]
+    summary = report["summary"]
+    all_proxy = "yes" if summary["all_via_proxy_port"] else "no"
+    print(f"{BOLD}proxyctl connections{NC}  backend={report['backend']} "
+          f"proxy_port={report['proxy_port']} all_via_proxy={all_proxy}")
+    if not api.get("ok"):
+        print(f"  {YELLOW}degraded:{NC} {api.get('error')}")
+    if not report["connections"]:
+        print(f"  {DIM}no local connections to proxy_port matched filters{NC}")
+        return
+    for item in report["connections"]:
+        status = f"{GREEN}matched{NC}" if item["matched"] else f"{YELLOW}unmatched{NC}"
+        target = "proxy" if item["connects_proxy_port"] else item["target_host"]
+        print(f"  {CYAN}{item['app']}{NC} pid={item['pid']} fd={item['fd']} "
+              f"src={item['local_source_port']} -> {target}:{item['target_port']} "
+              f"{status}")
+        if item["matched"]:
+            m = item["mihomo"] or {}
+            dest = m.get("host") or m.get("destination_ip") or "?"
+            print(f"    dest={dest} rule={m.get('rule') or '?'} "
+                  f"payload={m.get('rule_payload') or '-'} "
+                  f"chains={','.join(m.get('chains') or []) or '-'} "
+                  f"up={m.get('upload')} down={m.get('download')} "
+                  f"start={m.get('start') or '-'}")
+        else:
+            print(f"    reason={item['unmatched_reason']}")
+
+
+def cmd_connections(args: list[str], backend, config: dict[str, Any]) -> None:
+    """Entry point for ``proxyctl connections``."""
+    parsed_args = parse_args(args)
+    report = build_report(backend.name, config, parsed_args)
+    if _io.is_json_mode():
+        _io.emit_json(_io.envelope("connections", data=report))
+        return
+    emit_human(report)

{proxyctl-0.5.4 → proxyctl-0.5.5}/src/proxyctl/explain.py

@@ -432,14 +432,14 @@ def _t_flags(backend, config) -> TopicCard:
     return {
         "topic": "flags",
         "summary": (
-            "全局 flag 速查：--json / --plain / --dry-run / --no-color / --quiet。"
+            "全局 flag 速查：--json / --plain / --dry-run/-n / --no-color / --quiet。"
             "全部位置无关；--json 与 --plain 互斥；--dry-run 仅对写命令有效。"
         ),
         "file": "(no file)",
         "edit": (
             "  --json       envelope schema v2（含 meta.ts/elapsed_ms/request_id）\n"
             "  --plain      纯 TSV 输出（audit / check 等表格命令）\n"
-            "  --dry-run    预演写命令的 plan（list[PlanStep]），不真正执行\n"
+            "  --dry-run/-n 预演写命令的 plan（list[PlanStep]），不真正执行\n"
             "  --no-color   关闭 ANSI（也读 NO_COLOR / PROXYCTL_NO_COLOR）\n"
             "  --quiet/-q   压制非关键 stderr\n"
             "  --help/-h    单命令或全局帮助\n"
@@ -730,13 +730,13 @@ Step 5  proxyctl doctor --json            # 当前健康基线
 Step 6  proxyctl explain <topic>          # 深入概念（topic 见下）
 ```
 
-调用任何写命令前先加 `--dry-run --json` 看 `data.plan`，确认无误再去掉。
+调用任何写命令前先加 `--dry-run --json`（或 `-n --json`）看 `data.plan`，确认无误再去掉。
 
 ## Capabilities — 能做什么（按副作用三分类）
 
 | 类别 | sudo | 命令 |
 |---|---|---|
-| **只读** (side_effects=[]) | 否 | `status doctor check trace bench audit env log plugins explain agent-guide commands config path|get help version` |
+| **只读** (side_effects=[]) | 否 | `status doctor connections audit env log plugins explain agent-guide commands config path|get help version` |
 | **只读 + 网络 IO** (network-io) | 否 | `check trace bench recover`（curl/HTTP，不改本地状态） |
 | **写 proxyctl 自身配置** | 否 | `config set <key> <value>`（原子写 + .bak + YAML 校验） |
 | **写引擎配置** (config-write) | 是 | `mode tun|proxy` `audit apply` |
@@ -1047,6 +1047,15 @@ COMMANDS_META: list[dict] = [
      "args": [], "supports_json": True, "side_effects": ["network-io"],
      "needs_sudo": False, "interactive": False, "exit_codes": [0, 1, 5, 7],
      "examples": ["proxyctl check", "proxyctl check --json"]},
+    {"name": "connections", "group": "diagnostic",
+     "summary": "本机 App/进程连接与 proxy_port、mihomo /connections 按 sourcePort 关联",
+     "args": [{"name": "--app", "required": False, "repeatable": True},
+              {"name": "--all", "required": False}],
+     "supports_json": True, "side_effects": [],
+     "needs_sudo": False, "interactive": False, "exit_codes": [0, 2, 10],
+     "examples": ["proxyctl connections --app Codex --app Claude",
+                  "proxyctl connections --all --json",
+                  "proxyctl connections --app Codex --json"]},
     {"name": "trace", "group": "diagnostic", "summary": "域名链路诊断",
      "args": [{"name": "domain", "required": True}],
      "supports_json": True, "side_effects": ["network-io"],