proxyctl 0.5.4__tar.gz → 0.5.6__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: proxyctl
-Version: 0.5.4
+Version: 0.5.6
 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.6}/man/proxyctl.1

@@ -131,6 +131,33 @@ Linux systemctl --user）。
 4 阶段健康检查：basic / groups / connectivity / outbound-ip。
 \fB--plain\fR 输出 TSV（stage / ok / detail）。
 .TP
+\fBproxyctl connections\fR [\fB--host\fR \fITEXT\fR ...] [\fB--chain\fR \fITEXT\fR ...] [\fB--route\fR \fIKIND\fR ...] [\fB--preset\fR \fINAME\fR ...] [\fB--agent\fR \fINAME\fR ...] [\fB--query\fR \fITEXT\fR ...] [\fB--app\fR \fINAME\fR ...] [\fB--all\fR] [\fB--json\fR]
+把本机 App/进程的 TCP 连接与 \fIproxy_port\fR、mihomo \fB/connections\fR
+API 的 \fIsourcePort\fR 连接详情关联。默认不做 AI 工具过滤，输出全部可关联
+目的站点；\fB--host\fR 按 host/rulePayload/IP 过滤，\fB--chain\fR /
+\fB--line\fR 按 Mihomo 链路节点过滤，\fB--route\fR 按 route_kind 过滤
+（proxy/direct/reject/unknown，也接受 代理/直连/拒绝/未知），\fB--preset\fR
+使用预设（如 ai/openai/anthropic/coding），\fB--agent\fR 按工具过滤（如
+codex/claude/chatgpt/openclaw），\fB--query\fR / \fB--filter\fR 做全文过滤。
+\fB--app\fR 保留兼容，用于进程/App 过滤；\fB--all\fR 为兼容 no-op。
+macOS 上还会用 \fBnetstat -anv\fR 反查被
+Network/System Extension 接管后的 socket owner，并在 JSON 中输出
+\fBproxy_owner_connections\fR 与 \fBproxy_owner_groups\fR。后者按
+rulePayload / host / IP 聚合目的地，输出 app_contexts / candidate_contexts，
+并标出 mixed_chains / mixed_route_kind。
+只读；非 mihomo 后端或本地 API 不可用时降级输出 unmatched。
+.TP
+\fBproxyctl traffic\fR [snapshot|sample|watch|report] [\fB--by\fR \fIline,app\fR] [\fB--interval\fR \fISEC\fR] [\fB--count\fR \fIN\fR] [\fB--since\fR \fI1h\fR] [\fB--store\fR \fIDIR\fR] [\fB--host\fR \fITEXT\fR ...] [\fB--chain\fR \fITEXT\fR ...] [\fB--route\fR \fIKIND\fR ...] [\fB--preset\fR \fINAME\fR ...] [\fB--agent\fR \fINAME\fR ...] [\fB--json\fR]
+按当前活跃 Mihomo \fB/connections\fR 的 upload/download 统计流量快照。
+默认 \fB--by line\fR 按首个链路节点统计线路；也可用
+\fB--by line,app\fR 进一步按软件归因。软件归因分可信度：
+可见进程为 process/socket-owner，被 Network/System Extension 遮蔽时按目的域名
+给出 inferred 候选。\fBsample\fR 记录一次连接计数器增量，
+\fBwatch\fR 按间隔重复记录，\fBreport\fR 读取已记录增量并按
+\fB--since\fR 汇总。人类输出模式下 \fBwatch\fR 每次采样都会实时打印一行进度；
+\fB--json\fR 保持最终单个 envelope。首次看到的连接只建立基线，不回填此前已经
+产生的字节；未运行 sample/watch 的时间段无法补算。
+.TP
 \fBproxyctl trace\fR \fIDOMAIN\fR [\fB--json\fR]
 4 阶段域名链路诊断：DNS 解析 / 规则匹配预测 / 连通性 / 实际连接。
 .TP

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

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

{proxyctl-0.5.4 → proxyctl-0.5.6}/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.connections_human", "proxyctl.traffic",
 )
 
 
@@ -398,7 +399,7 @@ def lock_paths(lock_dir: str | None = None) -> dict[str, str]:
     home = os.path.expanduser("~")
     base = lock_dir or os.path.join(home, ".config", "proxyctl")
     # 已知锁名（与 cli._exec_with_lock 一致）
-    names = ["system", "config", "daemon"]
+    names = ["system", "config", "daemon", "traffic"]
     return {n: os.path.join(base, f".lock.{n}") for n in names}
 
 

{proxyctl-0.5.4 → proxyctl-0.5.6}/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.6}/src/proxyctl/cli.py

@@ -2,8 +2,8 @@
 
 支持 Mihomo 后端（首发）/ Sing-box 后端（预留）
 
-用法：proxyctl [start|stop|restart|status|log|check|fix|recover|
-               mode|audit|trace|bench|dns-lock|dns-unlock]
+用法：proxyctl [start|stop|restart|status|log|check|connections|traffic|
+               fix|recover|mode|audit|trace|bench|dns-lock|dns-unlock]
 """
 
 import functools
@@ -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,
@@ -1667,6 +1680,8 @@ def cmd_version_print() -> None:
                 "doctor_since_filter":             True,   # 0.5.0: --since <version> 屏蔽未来规则
                 "suggestions_ignore_file":         True,   # 0.5.0: ~/.config/proxyctl/suggestions.ignore
                 "proxy_group_dead_check":          True,   # 0.5.0: proxy_group.mostly_dead 规则
+                "traffic_snapshot":                True,   # 0.5.6+: active /connections traffic grouping
+                "traffic_history":                 True,   # 0.5.6+: sample/watch/report recorded deltas
             },
         }
         _io.emit_json(_io.envelope("version", data=data))
@@ -1751,7 +1766,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 +1780,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 +2747,14 @@ 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_traffic(ctx):
+    from proxyctl.traffic import cmd_traffic
+    cmd_traffic(ctx["args"], ctx["backend"], ctx["config"])
+
 def _h_bench(ctx):
     from proxyctl.check import cmd_bench
     bench_groups = ctx["args"] or None
@@ -2898,6 +2921,8 @@ DISPATCH: dict = {
     "status":          _h_status,
     "log":             _h_log,
     "check":           _h_check,
+    "connections":     _h_connections,
+    "traffic":         _h_traffic,
     "bench":           _h_bench,
     "fix":             _h_fix,
     "recover":         _h_recover,
@@ -2965,4 +2990,4 @@ def _suggest_command_and_exit(unknown: str) -> None:
 
 
 if __name__ == "__main__":
-    main()
+    main()

{proxyctl-0.5.4 → proxyctl-0.5.6}/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 '安静模式'",
              ""]