proxyctl 0.5.2__tar.gz → 0.5.3__tar.gz

{proxyctl-0.5.2 → proxyctl-0.5.3}/.gitignore

@@ -72,4 +72,7 @@ claude-proxy.log
 .coverage.*
 htmlcov/
 coverage.xml
-junit.xml
+junit.xml
+
+# release.yml 抽取 CHANGELOG section 用的临时文件（CI 跑完会删）
+.release-notes*.md

{proxyctl-0.5.2 → proxyctl-0.5.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: proxyctl
-Version: 0.5.2
+Version: 0.5.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
@@ -107,7 +107,7 @@ proxyctl 把 agent 友好度做成一等公民。完整接入协议见
 
 ```bash
 proxyctl agent-guide                 # Agent 入门 markdown（注入当前路径/端口）
-proxyctl agent-guide --list-sections # 15 个段，按需取小块（省 token）
+proxyctl agent-guide --list-sections # 19 个段，按需取小块（省 token）
 proxyctl --version --json            # schema_version + supported_features 探测
 proxyctl commands --json             # 全部命令元数据（机读）
 proxyctl commands --schema           # 上面 JSON 的 JSON Schema
@@ -191,6 +191,30 @@ proxyctl recover                  # 不重启引擎，热重载 + 清 fakeip +
 proxyctl recover --dry-run        # 看 3 个 Clash API endpoint 再决定
 ```
 
+### `doctor` —— 5 项健康分 + 引导建议（v0.5.0+）
+```bash
+proxyctl doctor                   # 5 项布尔健康分 + suggestions (warn/advisory)
+proxyctl doctor --json            # data.suggestions[] 含 21 条规则的检测结果
+proxyctl doctor --suggest-only    # 跳过 score 探测，仅跑建议引擎 (~0.18s)
+proxyctl doctor --since 0.4.7     # 屏蔽指定版本后引入的规则 (CI 平滑迁移)
+proxyctl doctor --no-suggest      # 关闭建议引擎，恢复 v0.4.x 极简体验
+proxyctl explain suggestion:<id>  # 每条规则有触发条件 + 修复路径 topic
+```
+21 条规则覆盖订阅过期 / autostart binary 与 PATH 漂移 / API 安全配置 /
+GeoIP 数据时效 / 代理组健康。详见 [AGENTS.md](AGENTS.md) "Doctor suggestions" 段。
+用户屏蔽某条告警：`~/.config/proxyctl/suggestions.ignore`（一行一个 id 或 fingerprint）。
+
+### `autostart` —— 自动启动 unit 管理（v0.5.0+）
+```bash
+proxyctl autostart                # plist/unit 当前状态
+proxyctl autostart inspect --json # 结构化输出含 binary/version/enabled/config_dir
+proxyctl autostart sync --dry-run # 预览 PlanStep[]
+proxyctl autostart sync           # 同步 plist/unit 到当前 PATH binary + config_dir
+```
+当 doctor 报 `autostart.binary_mismatch` / `version_mismatch` /
+`config_dir_mismatch` 时一键修复。macOS plist 用 plistlib 原地改保留
+KeepAlive / RunAtLoad 等用户定制；Linux ExecStart 缺失时拒绝执行防误覆盖。
+
 ---
 
 ## 安装
@@ -202,7 +226,7 @@ uv tool install proxyctl                # uv（推荐）
 pipx install proxyctl                   # 或 pipx
 pip install --user proxyctl             # 或 pip
 
-proxyctl --version                      # → proxyctl v0.4.7
+proxyctl --version                      # → proxyctl v0.5.1
 proxyctl --help
 ```
 
@@ -268,13 +292,14 @@ no_proxy_extra:                         # 自 0.1.5 起追加 NO_PROXY
 | `start / stop / restart / restart-clean` | 启停引擎 + DNS/代理注入 | ✅ | ✅ |
 | `status` | 一站式系统面板 | — | ✅ |
 | `check` | 4 阶段健康检查 | — | ✅ |
-| `doctor` | 5 项健康打分 | — | ✅ |
+| `doctor` | 5 项健康打分 + 21 条引导建议 (v0.5.0+) | — | ✅ |
 | `trace <domain>` | 域名链路诊断 | — | ✅ |
 | `audit [days] [apply]` | 日志驱动配置优化 | ✅ | ✅ |
 | `bench [groups]` | 节点测速 (NDJSON) | — | ✅ |
 | `fix` | 修复 DNS / 代理 / 热重载 | ✅ | ✅ |
 | `recover` | 切网后软恢复 | ✅ | ✅ |
 | `mode tun\|proxy` | 切换 TUN / 代理模式 | ✅ | ✅ |
+| `autostart [inspect\|sync]` | 自动启动 unit 管理 (v0.5.0+) | ✅ | ✅ |
 | `dns-lock / dns-unlock` | 启停 DNS 看门狗 | ✅ | ✅ |
 | `daemon` | 管理 extra_daemons | ✅ | ✅ |
 | `agent-guide / commands / explain` | agent 自描述三件套 | — | ✅ |
@@ -290,6 +315,7 @@ no_proxy_extra:                         # 自 0.1.5 起追加 NO_PROXY
 | audit (含 apply) | ✅ | ✅ |
 | recover (切网软恢复) | ✅ | ✅ |
 | mode tun \| proxy 切换 | ✅ | ✅ |
+| autostart inspect / sync | ✅ plistlib | ✅ systemd unit ExecStart |
 | dns-lock 看门狗 | ✅ | N/A* |
 
 \* Linux 下系统 DNS 由 systemd-resolved / NetworkManager / resolvconf
@@ -328,7 +354,7 @@ sing-box JSON config 解析、`trace` 的 sing-box 日志 grep、`engine` /
 git clone https://github.com/crhan/proxyctl.git
 cd proxyctl
 uv sync --group dev                    # 装运行 + 测试依赖
-uv run pytest                          # 跑 523 个测试
+uv run pytest                          # 跑 685 个测试
 uv run proxyctl status                 # 用本地源码版本
 
 export PROXYCTL_DEBUG=1                # 调试模式

{proxyctl-0.5.2 → proxyctl-0.5.3}/README.md

@@ -78,7 +78,7 @@ proxyctl 把 agent 友好度做成一等公民。完整接入协议见
 
 ```bash
 proxyctl agent-guide                 # Agent 入门 markdown（注入当前路径/端口）
-proxyctl agent-guide --list-sections # 15 个段，按需取小块（省 token）
+proxyctl agent-guide --list-sections # 19 个段，按需取小块（省 token）
 proxyctl --version --json            # schema_version + supported_features 探测
 proxyctl commands --json             # 全部命令元数据（机读）
 proxyctl commands --schema           # 上面 JSON 的 JSON Schema
@@ -162,6 +162,30 @@ proxyctl recover                  # 不重启引擎，热重载 + 清 fakeip +
 proxyctl recover --dry-run        # 看 3 个 Clash API endpoint 再决定
 ```
 
+### `doctor` —— 5 项健康分 + 引导建议（v0.5.0+）
+```bash
+proxyctl doctor                   # 5 项布尔健康分 + suggestions (warn/advisory)
+proxyctl doctor --json            # data.suggestions[] 含 21 条规则的检测结果
+proxyctl doctor --suggest-only    # 跳过 score 探测，仅跑建议引擎 (~0.18s)
+proxyctl doctor --since 0.4.7     # 屏蔽指定版本后引入的规则 (CI 平滑迁移)
+proxyctl doctor --no-suggest      # 关闭建议引擎，恢复 v0.4.x 极简体验
+proxyctl explain suggestion:<id>  # 每条规则有触发条件 + 修复路径 topic
+```
+21 条规则覆盖订阅过期 / autostart binary 与 PATH 漂移 / API 安全配置 /
+GeoIP 数据时效 / 代理组健康。详见 [AGENTS.md](AGENTS.md) "Doctor suggestions" 段。
+用户屏蔽某条告警：`~/.config/proxyctl/suggestions.ignore`（一行一个 id 或 fingerprint）。
+
+### `autostart` —— 自动启动 unit 管理（v0.5.0+）
+```bash
+proxyctl autostart                # plist/unit 当前状态
+proxyctl autostart inspect --json # 结构化输出含 binary/version/enabled/config_dir
+proxyctl autostart sync --dry-run # 预览 PlanStep[]
+proxyctl autostart sync           # 同步 plist/unit 到当前 PATH binary + config_dir
+```
+当 doctor 报 `autostart.binary_mismatch` / `version_mismatch` /
+`config_dir_mismatch` 时一键修复。macOS plist 用 plistlib 原地改保留
+KeepAlive / RunAtLoad 等用户定制；Linux ExecStart 缺失时拒绝执行防误覆盖。
+
 ---
 
 ## 安装
@@ -173,7 +197,7 @@ uv tool install proxyctl                # uv（推荐）
 pipx install proxyctl                   # 或 pipx
 pip install --user proxyctl             # 或 pip
 
-proxyctl --version                      # → proxyctl v0.4.7
+proxyctl --version                      # → proxyctl v0.5.1
 proxyctl --help
 ```
 
@@ -239,13 +263,14 @@ no_proxy_extra:                         # 自 0.1.5 起追加 NO_PROXY
 | `start / stop / restart / restart-clean` | 启停引擎 + DNS/代理注入 | ✅ | ✅ |
 | `status` | 一站式系统面板 | — | ✅ |
 | `check` | 4 阶段健康检查 | — | ✅ |
-| `doctor` | 5 项健康打分 | — | ✅ |
+| `doctor` | 5 项健康打分 + 21 条引导建议 (v0.5.0+) | — | ✅ |
 | `trace <domain>` | 域名链路诊断 | — | ✅ |
 | `audit [days] [apply]` | 日志驱动配置优化 | ✅ | ✅ |
 | `bench [groups]` | 节点测速 (NDJSON) | — | ✅ |
 | `fix` | 修复 DNS / 代理 / 热重载 | ✅ | ✅ |
 | `recover` | 切网后软恢复 | ✅ | ✅ |
 | `mode tun\|proxy` | 切换 TUN / 代理模式 | ✅ | ✅ |
+| `autostart [inspect\|sync]` | 自动启动 unit 管理 (v0.5.0+) | ✅ | ✅ |
 | `dns-lock / dns-unlock` | 启停 DNS 看门狗 | ✅ | ✅ |
 | `daemon` | 管理 extra_daemons | ✅ | ✅ |
 | `agent-guide / commands / explain` | agent 自描述三件套 | — | ✅ |
@@ -261,6 +286,7 @@ no_proxy_extra:                         # 自 0.1.5 起追加 NO_PROXY
 | audit (含 apply) | ✅ | ✅ |
 | recover (切网软恢复) | ✅ | ✅ |
 | mode tun \| proxy 切换 | ✅ | ✅ |
+| autostart inspect / sync | ✅ plistlib | ✅ systemd unit ExecStart |
 | dns-lock 看门狗 | ✅ | N/A* |
 
 \* Linux 下系统 DNS 由 systemd-resolved / NetworkManager / resolvconf
@@ -299,7 +325,7 @@ sing-box JSON config 解析、`trace` 的 sing-box 日志 grep、`engine` /
 git clone https://github.com/crhan/proxyctl.git
 cd proxyctl
 uv sync --group dev                    # 装运行 + 测试依赖
-uv run pytest                          # 跑 523 个测试
+uv run pytest                          # 跑 685 个测试
 uv run proxyctl status                 # 用本地源码版本
 
 export PROXYCTL_DEBUG=1                # 调试模式

{proxyctl-0.5.2 → proxyctl-0.5.3}/pyproject.toml

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

{proxyctl-0.5.2 → proxyctl-0.5.3}/src/proxyctl/autostart.py

@@ -218,7 +218,7 @@ def inspect_runtime(static_result: dict[str, Any], backend, *,
                     r"^\S+\s+\S+\s+(\S+)\s+(\S+\s+\S+)\s+with\s+go(\S+)\s+(\S+)",
                     raw)
                 if m:
-                    out["autostart_version"] = m.group(1)
+                    out["autostart_version"] = m.group(1).lstrip("v")
         except (subprocess.TimeoutExpired, OSError):
             pass
 
@@ -439,17 +439,23 @@ def to_suggestions(inspect_result: dict[str, Any] | None, *,
         })
 
     # 5. version_mismatch —— 优先于 binary_mismatch 之外的独立信号
+    # 同一 binary 路径不可能版本不同；直接跳过避免 strip 不一致引发的误报。
     autostart_ver = inspect_result.get("autostart_version")
-    if autostart_ver and path_version and autostart_ver != path_version:
+    same_binary = bool(binary and path_binary and binary == path_binary)
+    a_ver_norm = (autostart_ver or "").lstrip("v")
+    p_ver_norm = (path_version or "").lstrip("v")
+    if (autostart_ver and path_version
+            and not same_binary
+            and a_ver_norm != p_ver_norm):
         out.append({
             "id": "autostart.version_mismatch",
             "severity": "advisory",
             "actor": "user",
-            "title": (f"autostart 引擎版本 v{autostart_ver} "
-                      f"≠ PATH v{path_version}"),
+            "title": (f"autostart 引擎版本 v{a_ver_norm} "
+                      f"≠ PATH v{p_ver_norm}"),
             "evidence": {
-                "autostart_version": autostart_ver,
-                "path_version": path_version,
+                "autostart_version": a_ver_norm,
+                "path_version": p_ver_norm,
                 "autostart_binary": binary,
                 "path_binary": path_binary,
             },

{proxyctl-0.5.2 → proxyctl-0.5.3}/src/proxyctl/check.py

@@ -202,6 +202,9 @@ def _proxy_groups_section(api_base: str, api_secret: str,
         if col > 0:
             print(line.rstrip())
 
+    # 跟踪本次 check 输出已经展开过节点列表的子组（跨 print_group 调用复用）
+    expanded_subgroups: set[str] = set()
+
     def print_group(gname: str):
         """打印单个组的摘要 + 成员；若 selector 成员也是组则递归展开。"""
         g = proxies.get(gname)
@@ -248,31 +251,39 @@ 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}")
 
-        # selector/fallback 的成员如果也是组，展开子组详情
-        if g.get("type") in ("Selector", "Fallback"):
+        # 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)
-            for m in gmembers:
-                sub = proxies.get(m)
-                if sub and sub.get("all"):
-                    sub_type = "url" if sub.get("type") == "URLTest" else "sel"
-                    sub_now = sub.get("now", "?")
-                    sub_now_d = get_delay(sub_now)
-                    sub_members = sub.get("all", [])
-                    s_alive = sum(1 for x in sub_members if get_delay(x) > 0)
-                    s_dead  = sum(1 for x in sub_members if get_delay(x) == 0)
-                    s_nodata = sum(1 for x in sub_members if get_delay(x) < 0)
-                    sc = []
-                    if s_alive:  sc.append(f"{GREEN}{s_alive}✓{NC}")
-                    if s_dead:   sc.append(f"{RED}{s_dead}✗{NC}")
-                    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 ""
-                    active = " ←" if m == gnow else ""
-                    print(f"    {CYAN}{m}{NC}({sub_type}) → {BOLD}{sub_now}{NC} "
-                          f"{ds(sub_now_d)}ms  [{'/'.join(sc)} of {len(sub_members)}]{st_str}{active}")
-                    print_members(sub_members, sub_now)
-        else:
+        elif g.get("type") not in ("Selector", "Fallback"):
             print_members(gmembers, gnow)
+        if now_is_subgroup:
+            sub_type = "url" if sub.get("type") == "URLTest" else "sel"
+            sub_now = sub.get("now", "?")
+            sub_now_d = get_delay(sub_now)
+            sub_members = sub.get("all", [])
+            s_alive = sum(1 for x in sub_members if get_delay(x) > 0)
+            s_dead  = sum(1 for x in sub_members if get_delay(x) == 0)
+            s_nodata = sum(1 for x in sub_members if get_delay(x) < 0)
+            sc = []
+            if s_alive:  sc.append(f"{GREEN}{s_alive}✓{NC}")
+            if s_dead:   sc.append(f"{RED}{s_dead}✗{NC}")
+            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
+            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)
+        # 顶层组本身展开完后也标记，避免被下层组重新展开
+        expanded_subgroups.add(gname)
 
     # 跟踪哪些组已经作为 selector 子组展开过，避免重复
     shown = set()
@@ -405,19 +416,26 @@ def cmd_bench(api: str, api_secret: str, groups: list = None,
         print(f"  {YELLOW}—{NC} API 响应解析失败")
         return
 
+    # v0.5.3：穿透 selector 子组到真叶子节点；伪节点（DIRECT/REJECT）排除
+    from proxyctl.suggest_rules import _collect_leaves, PSEUDO_NODE_TYPES
     group_members: dict = {}
+    raw_count_total = 0  # 去重前总和（用于显示"省了多少次"）
     for gname in target_groups:
         g = proxies.get(gname)
         if not g:
             if not as_json:
                 print(f"  {YELLOW}—{NC} 组 {BOLD}{gname}{NC} 不存在，跳过")
             continue
-        members = g.get("all", [])
-        if not members:
+        leaves = [
+            l for l in _collect_leaves(gname, proxies, seen=set())
+            if proxies.get(l, {}).get("type") not in PSEUDO_NODE_TYPES
+        ]
+        if not leaves:
             if not as_json:
-                print(f"  {YELLOW}—{NC} 组 {BOLD}{gname}{NC} 无成员")
+                print(f"  {YELLOW}—{NC} 组 {BOLD}{gname}{NC} 无可测叶子节点")
             continue
-        group_members[gname] = members
+        group_members[gname] = leaves
+        raw_count_total += len(leaves)
 
     if not group_members:
         if as_json:
@@ -438,9 +456,13 @@ def cmd_bench(api: str, api_secret: str, groups: list = None,
                 seen.add(m)
 
     total = len(all_nodes)
+    dedup_saved = raw_count_total - total  # 去重省掉的探测次数
     group_names = ", ".join(group_members.keys())
     if not as_json:
-        print(f"{BOLD}测速{NC}  组: {CYAN}{group_names}{NC}  节点: {BOLD}{total}{NC}")
+        dedup_note = (f"  {DIM}(去重省 {dedup_saved} 次){NC}"
+                      if dedup_saved > 0 else "")
+        print(f"{BOLD}测速{NC}  组: {CYAN}{group_names}{NC}  "
+              f"节点: {BOLD}{total}{NC}{dedup_note}")
 
     import threading
     done_count = [0]
@@ -496,6 +518,8 @@ def cmd_bench(api: str, api_secret: str, groups: list = None,
         summary = {
             "groups": list(group_members.keys()),
             "total": total,
+            "raw_count": raw_count_total,  # 去重前各组叶子数之和
+            "dedup_saved": dedup_saved,    # 重复线路省下的探测次数
             "ok_count": ok_count,
             "fail_count": total - ok_count,
             "avg_rtt_ms": (sum(rtts) // len(rtts)) if rtts else None,
@@ -575,6 +599,13 @@ def _collect_fail_hints(collector: dict, *, dns_bad: bool, failed: bool) -> list
         # 保留旧行为：DNS 异常时引导 proxyctl fix
         hints.append("DNS unhealthy — try `proxyctl fix`")
 
+    dead = stages.get("dead_groups") or []
+    if dead:
+        names = ",".join(
+            f"{d.get('name','?')}({d.get('dead_count')}/{d.get('total_count')})"
+            for d in dead if isinstance(d, dict))
+        hints.append(f"proxy groups mostly dead: {names} — try `proxyctl bench`")
+
     return hints
 
 
@@ -859,6 +890,26 @@ def cmd_check(engine, api: str, api_secret: str,
     if as_json:
         collector["stages"]["groups"] = groups_data
 
+    # 任何组 ≥70% 节点挂掉的全局判定（不限于 check_groups 显示的组）
+    # 与 doctor 的 proxy_group.mostly_dead suggestion 共用底层规则。
+    from proxyctl import suggest_rules as _sr
+    proxies_payload = _sr.fetch_proxies(api, api_secret, timeout=1.0)
+    dead_groups = _sr.proxy_group_rules(proxies_payload)
+    if dead_groups:
+        for s in dead_groups:
+            ev = s.get("evidence") or {}
+            print(f"  {RED}✗{NC} {ev.get('group_name','?')}: "
+                  f"{ev.get('dead_count')}/{ev.get('total_count')} 节点不可达 "
+                  f"({ev.get('dead_pct_at_check')}%)")
+        fail = True
+    collector["stages"]["dead_groups"] = [
+        {"name": (s.get("evidence") or {}).get("group_name"),
+         "dead_count": (s.get("evidence") or {}).get("dead_count"),
+         "total_count": (s.get("evidence") or {}).get("total_count"),
+         "dead_pct": (s.get("evidence") or {}).get("dead_pct_at_check")}
+        for s in dead_groups
+    ]
+
     # ── 3. 连通性 ─────────────────────────────────────────────────────────────
     # 从所有插件收集 check_targets。corp-network 等内置插件根据 ctx.corp_net 决定是否启用。
     ctx = {"corp_net": corp_net, "mode": mode, "engine": engine.name}
@@ -966,6 +1017,9 @@ def cmd_check(engine, api: str, api_secret: str,
         if dns_bad:
             print(f"{CYAN}DNS 异常，执行 {BOLD}sb fix{NC}{CYAN} 修复。{NC}")
 
+    if not as_json and not as_plain:
+        _sys.exit(0 if not fail else 1)
+
     if as_json:
         _sys.stdout = _real_stdout
         from proxyctl._io import emit_json, envelope, OK, GENERIC

{proxyctl-0.5.2 → proxyctl-0.5.3}/src/proxyctl/explain.py

@@ -91,11 +91,48 @@ def _t_nodes(backend, config) -> TopicCard:
 def _t_config(backend, config) -> TopicCard:
     return {
         "topic": "config",
-        "summary": "proxyctl 自身配置（不是 mihomo 配置）。控制后端选择、Clash API、端口、企业 DNS 等。",
+        "summary": (
+            "proxyctl 自身配置（不是 mihomo 配置）。控制后端选择、Clash API、端口、"
+            "企业 DNS 等。**建议把整个 ~/.config/proxyctl/ 目录纳入 git 追踪**（详见 "
+            "explain config-tracking），订阅源 URL / Clash secret 等 secret 文件用 "
+            ".gitignore 排除，配置改动留得下回放历史。"
+        ),
         "file": _io_proxyctl_config_path(),
         "edit": f"$EDITOR {_io_proxyctl_config_path()}",
         "verify": "proxyctl config get <key>",
-        "next_commands": ["explain ports", "explain corp-dns", "explain extra-daemons"],
+        "next_commands": ["explain config-tracking", "explain ports",
+                          "explain corp-dns", "explain extra-daemons"],
+    }
+
+
+@topic("config-tracking")
+def _t_config_tracking(backend, config) -> TopicCard:
+    cfg_dir = os.path.join(os.path.expanduser("~"), ".config", "proxyctl")
+    return {
+        "topic": "config-tracking",
+        "summary": (
+            "用 git 追踪 ~/.config/proxyctl/ 的变化。proxyctl 自己不做版本控制，"
+            "但用户的 config.yaml / 插件 / 订阅契约文件经常被多个工具（用户、cron、"
+            "proxyctl autostart sync、update-subscription.sh、agent）改动，没有"
+            "版本历史时很难 diff 出'谁改了什么'。git 是最便宜的解法。"
+        ),
+        "file": f"{cfg_dir}/.git",
+        "edit": (
+            f"  cd {cfg_dir} && git init\n"
+            "  # .gitignore 必须排除 secret + 高频抖动文件（agent 别忘）：\n"
+            "  cat > .gitignore <<'EOF'\n"
+            "  subscription-source.env       # 订阅 URL 含 UUID secret\n"
+            "  subscription.json             # 流量/到期高频变化\n"
+            "  .lock.*                       # proxyctl 运行时锁文件\n"
+            "  .ipgeo-*                      # ipgeo 探针缓存\n"
+            "  *.bak                         # config set 自动备份\n"
+            "  EOF\n"
+            "  git add . && git commit -m 'init: 本机 proxyctl 配置基线'\n"
+            "  # 后续改 config 之前：git status 看上次留下了啥；改完 commit"
+        ),
+        "verify": f"cd {cfg_dir} && git log --oneline",
+        "next_commands": ["explain config", "explain plugins",
+                          "config get backend"],
     }
 
 
@@ -780,6 +817,31 @@ proxyctl 才能区分「过期 / 网络挂 / 订阅服务方挂」。
 - 用户插件目录: `~/.config/proxyctl/plugins/*.py`
 - 锁文件目录: `{lock_dir}/.lock.{{system|config|daemon}}`
 
+## Config Tracking — 用户配置目录建议纳入 git
+
+`~/.config/proxyctl/` 是用户的私人配置目录（不是 proxyctl 项目源代码）。
+被多方写入：用户手改、`config set`、`proxyctl autostart sync`、订阅脚本、
+cron、agent。**强烈建议把它纳入 git 追踪**，让你能回放"上次配置是什么样"。
+
+```bash
+cd {lock_dir} && git init
+# .gitignore 必须排除 secret + 高频抖动文件：
+cat > .gitignore <<'EOF'
+subscription-source.env       # 订阅 URL（含 UUID secret，禁止入库）
+subscription.json             # 流量/到期高频变化
+.lock.*                       # proxyctl 运行时锁
+.ipgeo-*                      # ipgeo 探针缓存
+*.bak                         # config set 自动备份
+EOF
+git add . && git commit -m 'init: 本机 proxyctl 配置基线'
+```
+
+agent 在用户机器上首次跑 proxyctl 时，**应该提示用户是否要做这一步**
+（首次见到 `{lock_dir}` 但无 `.git` 即可提示）。proxyctl 自己不动 git——
+版本控制是用户/agent 的职责，跟拉订阅是同一类边界。
+
+详见 `proxyctl explain config-tracking`。
+
 ## Exit Codes — 退出码
 
 ```

{proxyctl-0.5.2 → proxyctl-0.5.3}/src/proxyctl/suggest_rules.py

@@ -278,6 +278,9 @@ def engine_rules(current_version: str | None,
 DEAD_CHECK_GROUP_TYPES = ("URLTest", "Selector", "Fallback", "LoadBalance",
                           "Smart")
 
+# 伪节点（DIRECT/REJECT/Pass），不参与 dead 统计——它们没有"可达性"概念
+PSEUDO_NODE_TYPES = ("Direct", "Reject", "Pass", "Compatible")
+
 # 节点数少于此值的组不报告（小组本来就容易脏）
 MIN_GROUP_SIZE_FOR_DEAD_CHECK = 3
 
@@ -285,6 +288,35 @@ MIN_GROUP_SIZE_FOR_DEAD_CHECK = 3
 DEAD_PCT_THRESHOLD = 70.0
 
 
+def _collect_leaves(group_name: str, proxies: dict[str, Any],
+                    seen: set[str]) -> list[str]:
+    """穿透 selector/URLTest/Fallback 子组，递归收集所有真叶子节点。
+
+    返回去重后的叶子节点名列表。伪节点（DIRECT/REJECT）排除。
+    seen 跟踪本次调用栈访问过的组名，防止循环引用死循环。
+    """
+    if group_name in seen:
+        return []
+    seen = seen | {group_name}
+    info = proxies.get(group_name)
+    if not isinstance(info, dict):
+        return []
+    typ = info.get("type")
+    if typ in PSEUDO_NODE_TYPES:
+        return []
+    if typ not in DEAD_CHECK_GROUP_TYPES:
+        # 真叶子（Shadowsocks / Vmess / Trojan / TUIC / Hysteria / ...）
+        return [group_name]
+    leaves: list[str] = []
+    for m in info.get("all") or []:
+        if not isinstance(m, str):
+            continue
+        for leaf in _collect_leaves(m, proxies, seen):
+            if leaf not in leaves:
+                leaves.append(leaf)
+    return leaves
+
+
 def fetch_proxies(api_base: str, api_secret: str = "", *,
                   timeout: float = 0.5) -> dict[str, Any] | None:
     """调 mihomo `/proxies` API，本地 HTTP，0 外网。
@@ -320,11 +352,16 @@ def fetch_proxies(api_base: str, api_secret: str = "", *,
 
 
 def proxy_group_rules(proxies_payload: dict[str, Any] | None) -> list[dict[str, Any]]:
-    """proxy_group.mostly_dead 规则。
+    """proxy_group.mostly_dead 规则（v0.5.4 起穿透子组到叶子统计）。
 
     每个挂掉的组输出**独立**一条 suggestion（fingerprint 含 group_name），
     agent 可分别跟踪。
 
+    v0.5.4 行为变更：判定从"直接成员 delay==0"改为"穿透到叶子节点 delay==0"。
+    GLOBAL 这种 selector-of-selectors 组下的 13 个分流子组（电报/苹果/Steam
+    等）若无 latency history（mihomo 没给它们测过延迟）不再被算作 dead，
+    伪节点（DIRECT/REJECT）也排除。dead_pct 现在基于真叶子节点数。
+
     Args:
         proxies_payload: fetch_proxies() 返回；None 表示跳过整组
     """
@@ -339,14 +376,13 @@ def proxy_group_rules(proxies_payload: dict[str, Any] | None) -> list[dict[str,
             continue
         if info.get("type") not in DEAD_CHECK_GROUP_TYPES:
             continue
-        members = info.get("all") or []
-        if not isinstance(members, list) or len(members) < MIN_GROUP_SIZE_FOR_DEAD_CHECK:
+        leaves = _collect_leaves(name, proxies, seen=set())
+        if len(leaves) < MIN_GROUP_SIZE_FOR_DEAD_CHECK:
             continue
         dead = 0
-        for m in members:
-            node = proxies.get(m)
+        for leaf in leaves:
+            node = proxies.get(leaf)
             if not isinstance(node, dict):
-                # 拿不到节点信息时算"未知"，不计入死亡
                 continue
             history = node.get("history") or []
             if not history:
@@ -355,19 +391,19 @@ def proxy_group_rules(proxies_payload: dict[str, Any] | None) -> list[dict[str,
             last = history[-1] if isinstance(history[-1], dict) else {}
             if last.get("delay", 0) == 0:
                 dead += 1
-        dead_pct = (dead / len(members)) * 100.0
+        dead_pct = (dead / len(leaves)) * 100.0
         if dead_pct >= DEAD_PCT_THRESHOLD:
             out.append({
                 "id": "proxy_group.mostly_dead",
                 "severity": "warn",
                 "actor": "user",
-                "title": (f"代理组 {name} 中 {dead}/{len(members)} 节点不可达 "
+                "title": (f"代理组 {name} 中 {dead}/{len(leaves)} 叶子节点不可达 "
                           f"({dead_pct:.0f}%)"),
                 "evidence": {
                     "group_name": name,            # 进 fingerprint 的稳定字段
                     "group_type": info.get("type"),
                     "dead_count": dead,
-                    "total_count": len(members),
+                    "total_count": len(leaves),
                     # dead_pct 不进 fingerprint（抖动字段），仅供人看
                     "dead_pct_at_check": round(dead_pct, 1),
                 },