ghlink 0.4.15__py3-none-any.whl

ghlink/__init__.py

@@ -0,0 +1,4 @@
+"""ghlink - GitHub 链路自愈工具。"""
+
+__version__ = "0.4.15"
+SCHEMA_VERSION = 1

ghlink/builtin_github520.py

@@ -0,0 +1,56 @@
+"""内置 GitHub520 兜底数据（v0.3.0 新增，李工 2026-08-22 定）。
+
+背景：新安装/首次拉取失败时若无缓存，ghlink 拿不到任何社区 IP →
+      GitHub520 段为空、非核心域名无 hosts 条目。内置一份最新快照兜底，
+      保证首装断网/拉取失败也能直接可用。
+
+格式：hosts 文本快照（与 raw.hellogithub.com/hosts 同构），由
+      github520.parse_hosts() 解析——数据即字符串，避免大字典触发
+      SonarCloud 重复代码块误报（D 级质量门禁）。
+
+更新规则：每次发版前抓取 https://raw.hellogithub.com/hosts 更新本文件。
+核心域名（github.com/api.github.com）仍由动态自愈兜底，解析时剔除。
+"""
+
+# 快照时间：2026-08-22T07:51:33+08:00（来源 raw.hellogithub.com/hosts）
+BUILTIN_GITHUB520_HOSTS = """140.82.113.25 alive.github.com
+20.205.243.168 api.github.com
+140.82.114.21 api.individual.githubcopilot.com
+185.199.111.133 avatars.githubusercontent.com
+185.199.111.133 avatars0.githubusercontent.com
+185.199.111.133 avatars1.githubusercontent.com
+185.199.111.133 avatars2.githubusercontent.com
+185.199.111.133 avatars3.githubusercontent.com
+185.199.111.133 avatars4.githubusercontent.com
+185.199.111.133 avatars5.githubusercontent.com
+185.199.111.133 camo.githubusercontent.com
+140.82.114.22 central.github.com
+185.199.111.133 cloud.githubusercontent.com
+20.205.243.165 codeload.github.com
+140.82.114.22 collector.github.com
+185.199.111.133 desktop.githubusercontent.com
+185.199.111.133 favicons.githubusercontent.com
+159.106.121.75 gist.github.com
+16.15.237.95 github-cloud.s3.amazonaws.com
+52.216.62.41 github-com.s3.amazonaws.com
+16.15.223.74 github-production-release-asset-2e65be.s3.amazonaws.com
+54.231.229.17 github-production-repository-file-5c1aeb.s3.amazonaws.com
+52.217.64.212 github-production-user-asset-6210df.s3.amazonaws.com
+192.0.66.2 github.blog
+20.205.243.166 github.com
+140.82.113.18 github.community
+185.199.110.215 github.githubassets.com
+203.111.254.117 github.global.ssl.fastly.net
+185.199.111.153 github.io
+185.199.111.133 github.map.fastly.net
+185.199.111.153 githubstatus.com
+140.82.112.26 live.github.com
+185.199.111.133 media.githubusercontent.com
+185.199.111.133 objects.githubusercontent.com
+13.107.42.16 pipelines.actions.githubusercontent.com
+185.199.111.133 raw.githubusercontent.com
+185.199.111.133 user-images.githubusercontent.com
+150.171.110.104 vscode.dev
+140.82.114.21 education.github.com
+185.199.111.133 private-user-images.githubusercontent.com
+"""

ghlink/config.py

@@ -0,0 +1,73 @@
+"""配置加载：JSON 配置，零依赖。
+
+config.example.json 为模板。字段：
+- probe: targets(探测域名列表), timeout_sec, round_interval_min
+- trigger: consecutive_failures(默认3), cooldown_min(默认15), verify_success_rounds(默认2)
+- resolver: doh_sources, cache_ttl_sec, max_candidates
+- notify: feishu_webhook(空=关闭), enabled(默认true)
+- state_file, lock_file, hosts_backup_dir
+"""
+
+import json
+import os
+from typing import Any, Dict
+
+DEFAULT_CONFIG: Dict[str, Any] = {
+    "probe": {
+        "targets": [
+            "github.com",
+            "api.github.com",
+            "codeload.github.com",
+            "github.global.ssl.fastly.net",
+            # v0.2.18 扩域（赛博 22:20 定案，李工 23:21 批准并入 v0.2.19 规划）：
+            # GitHub 生态核心域名，覆盖 clone/raw/release 下载链盲区
+            "raw.githubusercontent.com",
+            "objects.githubusercontent.com",
+            "gist.github.com",
+            "github.githubassets.com",
+        ],
+        "timeout_sec": 15,  # v0.2.8：5→15（慢链路不误杀，李工 23:15 实测定论）
+        # 目标域名健康度管理（v0.2）：长期不可达域名自动降级，核心域名优先保证切换成功
+        "core_targets": ["github.com", "api.github.com"],  # 核心域名永不降级
+        "degrade_after_rounds": 3,  # v0.2.18：非核心域名连续失败 N 轮 → 降级（1h 粒度 ≈ 3h）
+        "recover_rounds": 2,  # 降级域名连续成功 N 轮 → 恢复纳入
+    },
+    "trigger": {
+        # v0.2.18（李工 22:27 定：探测 1 小时不频繁）：阈值按 1h 粒度核算
+        "consecutive_failures": 3,  # 连续 3 小时失败才触发切换
+        "cooldown_min": 180,  # 切换冷却 3 小时（原 15min 在 1h 粒度下无意义）
+        "verify_success_rounds": 2,  # 切换后连续 2 小时成功才回 normal
+    },
+    "resolver": {
+        "doh_sources": [
+            "https://dns.alidns.com/resolve",
+            "https://doh.pub/dns-query",
+            "https://cloudflare-dns.com/dns-query",
+            "https://dns.google/resolve",
+        ],
+        "cache_ttl_sec": 3600,
+        "max_candidates": 5,
+    },
+    "notify": {"enabled": True, "feishu_webhook": ""},
+    "state_file": "ghlink_status.json",
+    "lock_file": "ghlink.lock",
+    "hosts_backup_dir": "backup",
+}
+
+
+def load_config(path: str) -> Dict[str, Any]:
+    """加载配置，缺失字段回退默认值。"""
+    cfg = json.loads(json.dumps(DEFAULT_CONFIG))  # deep copy
+    if path and os.path.exists(path):
+        with open(path, encoding="utf-8") as f:
+            user_cfg = json.load(f)
+        _deep_merge(cfg, user_cfg)
+    return cfg
+
+
+def _deep_merge(base: Dict[str, Any], override: Dict[str, Any]) -> None:
+    for k, v in override.items():
+        if isinstance(v, dict) and isinstance(base.get(k), dict):
+            _deep_merge(base[k], v)
+        else:
+            base[k] = v

ghlink/github520.py

@@ -0,0 +1,257 @@
+"""GitHub520 hosts 段集成（v0.2.18，赛博 22:20 两步走第二步，李工 23:21 并入）。
+
+设计（赛博定案）：
+- 周期拉取 https://raw.hellogithub.com/hosts（默认 1 小时，SwitchHosts 同款）
+- 合入 ghlink 独立段落（# ghlink Start/End），核心域名 ghlink 自愈优先
+- 写入前基础可达性抽检（坏 IP 不入场）
+- 核心域名（github.com/api.github.com）仍走 ghlink 动态验证兜底，
+  非核心域名才用 GitHub520 社区 IP——互补而不互相拖累
+"""
+
+import json
+import os
+import time
+import urllib.request
+from typing import Any, Dict, List
+
+from .builtin_github520 import BUILTIN_GITHUB520_HOSTS  # v0.4.2：首装断网/拉取失败兜底
+
+# 拉取状态缓存文件（放 state 同目录）
+_CACHE_NAME = "ghlink520_cache.json"
+
+
+def _cache_path(state_dir: str = "") -> str:
+    """缓存文件路径：优先 state 目录，兜底用户目录。"""
+    if state_dir:
+        return os.path.join(state_dir, _CACHE_NAME)
+    return os.path.join(os.path.expanduser("~"), ".ghlink", _CACHE_NAME)
+
+
+def fetch_hosts(url: str, timeout_sec: float = 30) -> str:
+    """拉取 GitHub520 hosts 文本（失败抛异常，由调用方降级）。"""
+    req = urllib.request.Request(url, headers={"User-Agent": "ghlink/0.4.2"})
+    with urllib.request.urlopen(req, timeout=timeout_sec) as resp:
+        return resp.read().decode("utf-8", errors="replace")
+
+
+def parse_hosts(text: str) -> Dict[str, List[str]]:
+    """解析 hosts 文本 → {domain: [ips]}。跳过注释/空行/坏行。"""
+    entries: Dict[str, List[str]] = {}
+    for line in text.splitlines():
+        line = line.strip()
+        if not line or line.startswith("#"):
+            continue
+        parts = line.split()
+        if len(parts) < 2:
+            continue
+        ip, domain = parts[0], parts[1].rstrip(".")
+        # 只收 GitHub 生态域名（防社区列表混入无关项）
+        if not domain.endswith(
+            ("github.com", "githubusercontent.com", "githubassets.com", "fastly.net")
+        ):
+            continue
+        entries.setdefault(domain, [])
+        if ip not in entries[domain]:
+            entries[domain].append(ip)
+    return entries
+
+
+def _safe_cache_path(state_dir: str = "") -> str:
+    """校验并规范化缓存路径（SonarCloud S8707：防符号链接/路径逃逸）。
+
+    要求：绝对路径 + realpath 解析符号链接 + 位于允许目录
+    （用户主目录或系统临时目录）内。
+    """
+    import tempfile
+
+    path = _cache_path(state_dir)
+    resolved = os.path.realpath(path)
+    if not os.path.isabs(resolved):
+        raise ValueError(f"cache path must be absolute: {path}")
+    allowed_roots = (os.path.expanduser("~"), tempfile.gettempdir())
+    for root in allowed_roots:
+        root = os.path.realpath(root)
+        if resolved == root or resolved.startswith(root + os.sep):
+            return resolved
+    raise ValueError(f"cache path outside allowed dirs: {resolved}")
+
+
+def _ip_reachable(ip: str, timeout_sec: float = 2.0) -> bool:
+    """基础可达性抽检：TCP 443 连通即认为可用（防坏 IP 入场）。
+
+    v0.4.2（拂晓实测建议）：超时 5s→2s 收敛——TCP 443 建连 <2s 即可判通断，
+    40 行 × 5s 串行最坏 200s，2s + 并行后显著提速。
+    """
+    import socket
+
+    try:
+        sock = socket.create_connection((ip, 443), timeout=timeout_sec)
+        sock.close()
+        return True
+    except OSError:
+        return False
+
+
+def _precheck_ips(
+    ips: List[str],
+    timeout_sec: float = 2.0,
+    max_check: int = 5,
+    cache: Dict[str, bool] | None = None,
+) -> List[str]:
+    """v0.4.2（拂晓实测建议落地）：并行预检 + 短路 + 去重缓存。
+
+    - 并行：ThreadPoolExecutor 并发 TCP 443 预检（40 行最坏从串行 200s → 并行 ~2s）
+    - 短路：每域名最多预检前 max_check 条（first-match-wins 只吃首条）
+    - 去重：同 IP 本轮只预检一次（cache dict 跨域名共享结果）
+    - 语义：可达排前（ok_ips + rest），未预检的排后——保持现有排序语义
+    """
+    from concurrent.futures import ThreadPoolExecutor
+
+    cache = cache if cache is not None else {}
+    to_check = [ip for ip in ips[:max_check] if ip not in cache]
+    with ThreadPoolExecutor(max_workers=max(len(to_check), 1)) as pool:
+        futs = {pool.submit(_ip_reachable, ip, timeout_sec): ip for ip in to_check}
+        for f in futs:
+            cache[futs[f]] = f.result()
+    ok = [ip for ip in ips if cache.get(ip)]
+    rest = [ip for ip in ips if ip not in ok]
+    return ok + rest
+
+
+def filter_reachable(entries: Dict[str, List[str]], max_ips: int = 2) -> Dict[str, List[str]]:
+    """抽检：每域名保留可达 IP（最多 max_ips 个），全不可达则剔除该域名。
+
+    v0.4.2（拂晓实测建议）：改用 _precheck_ips 并行预检（超时 2s、短路前 5 条、去重）。
+    """
+    out: Dict[str, List[str]] = {}
+    cache: Dict[str, bool] = {}
+    for domain, ips in entries.items():
+        ranked = _precheck_ips(ips, timeout_sec=2.0, max_check=5, cache=cache)
+        ok_ips = [ip for ip in ranked if cache.get(ip)][:max_ips]
+        if ok_ips:
+            out[domain] = ok_ips
+    return out
+
+
+def load_cached(state_dir: str = "") -> Dict[str, List[str]]:
+    """读本地缓存（拉取失败时兜底，防坏 IP 列表已抽检过）。"""
+    try:
+        path = _safe_cache_path(state_dir)
+        if os.path.exists(path):
+            with open(path, encoding="utf-8") as f:
+                data = json.load(f)
+            return dict(data.get("entries", {}))
+    except (OSError, ValueError):
+        pass
+    return {}
+
+
+def cache_age(state_dir: str = "") -> float:
+    """v0.4.2：返回本地缓存年龄（秒）；无缓存/损坏返回超大值（视为过期需重拉）。"""
+    try:
+        path = _safe_cache_path(state_dir)
+        if os.path.exists(path):
+            with open(path, encoding="utf-8") as f:
+                data = json.load(f)
+            ts = float(data.get("ts", 0))
+            if ts:
+                return time.time() - ts
+    except (OSError, ValueError):
+        pass
+    return float("inf")
+
+
+def save_cache(entries: Dict[str, List[str]], state_dir: str = "") -> None:
+    """保存抽检后的缓存（供下次拉取失败兜底）。"""
+    try:
+        path = _safe_cache_path(state_dir)
+        os.makedirs(os.path.dirname(path), exist_ok=True)
+        with open(path, "w", encoding="utf-8") as f:
+            json.dump({"ts": time.time(), "entries": entries}, f)
+    except (OSError, ValueError):
+        pass
+
+
+def sync_github520(cfg: Dict[str, Any], state_dir: str = "") -> Dict[str, List[str]]:
+    """日常轮次：拉取 + 解析 + 抽检 + 缓存；失败回退缓存/内置快照。
+
+    返回非核心域名的社区 IP（核心域名由动态自愈优先，不写死静态 IP）。
+    """
+    return _sync(cfg, state_dir, include_core=False)
+
+
+def initial_entries(cfg: Dict[str, Any], state_dir: str = "") -> Dict[str, List[str]]:
+    """首装全量兜底（v0.4.2 新增，李工 12:35 点 1）：含全部域名（含核心），
+    预检过的 IP 排前、未预检的排后——首装/动态失败时 hosts 必有可用条目。
+    """
+    return _sync(cfg, state_dir, include_core=True, full_write=True)
+
+
+def _sync(
+    cfg: Dict[str, Any],
+    state_dir: str = "",
+    include_core: bool = False,
+    full_write: bool = False,
+) -> Dict[str, List[str]]:
+    """核心同步逻辑。include_core=保留核心域名；full_write=全量写（预检过排前）。"""
+    g = cfg.get("github520", {})
+    if not g.get("enabled", True):
+        return {}
+    url = g.get("url", "https://raw.hellogithub.com/hosts")
+    timeout_sec = float(g.get("timeout_sec", 30))
+    core = set(cfg.get("probe", {}).get("core_targets", ["github.com", "api.github.com"]))
+
+    try:
+        text = fetch_hosts(url, timeout_sec)
+        entries = parse_hosts(text)
+        if not include_core:
+            entries = {d: ips for d, ips in entries.items() if d not in core}
+        if full_write:
+            entries = _sort_prechecked_first(entries, min(timeout_sec, 5.0))
+        else:
+            entries = filter_reachable(entries)
+        if entries:
+            save_cache(entries, state_dir)
+            return entries
+    except Exception:
+        pass
+    # 拉取失败 → 缓存兜底（缓存已抽检过）
+    cached = load_cached(state_dir)
+    if cached:
+        if include_core:
+            # v0.4.3（李工 8 bug 点④ + 顾笙无缓存场景验证）：首装全量语义下
+            # 缓存是 sync_github520(include_core=False) 存的，本就不含核心域名——
+            # 若直接剔除核心，动态从未成功 + 拉取失败时 hosts 段无 github.com
+            # 主条目。从内置快照补齐核心域名静态 IP（20.205.243.166 github.com 等）。
+            builtin = parse_hosts(BUILTIN_GITHUB520_HOSTS)
+            for _d in core:
+                if _d in builtin and _d not in cached:
+                    cached[_d] = builtin[_d]
+            return cached
+        return {d: ips for d, ips in cached.items() if d not in core}
+    # 内置快照兜底（防首装断网尴尬）
+    builtin = parse_hosts(BUILTIN_GITHUB520_HOSTS)
+    if not include_core:
+        builtin = {d: ips for d, ips in builtin.items() if d not in core}
+    if full_write:
+        builtin = _sort_prechecked_first(builtin, min(timeout_sec, 5.0))
+    else:
+        builtin = filter_reachable(builtin)
+    if builtin:
+        save_cache(builtin, state_dir)
+        return builtin
+    return {}
+
+
+def _sort_prechecked_first(
+    entries: Dict[str, List[str]], timeout_sec: float = 2.0
+) -> Dict[str, List[str]]:
+    """v0.4.2：全量写入时预检过的 IP 排前、未预检的排后（hosts 取首个命中）。
+
+    v0.4.2（拂晓实测建议）：走 _precheck_ips 并行预检（超时 2s、短路前 5 条、去重缓存）。
+    """
+    out: Dict[str, List[str]] = {}
+    cache: Dict[str, bool] = {}
+    for domain, ips in entries.items():
+        out[domain] = _precheck_ips(ips, timeout_sec=timeout_sec, max_check=5, cache=cache)
+    return out

ghlink/hosts_manager.py

@@ -0,0 +1,259 @@
+"""hosts 段落式管理：写入/备份/回滚/自检。
+
+约定（借鉴 GitHub520 思路，全新实现）：
+- hosts 段落标记：# ghlink Start / # ghlink End，段落可重复安全更新
+- GitHub520 静态兜底子段：# ghlink520 Start / # ghlink520 End（v0.2.19 起）
+  —— 初始化时合入一次，后续动态更新自动保留（不重复合入、不丢失）
+- 写入前 backup_hosts()，写入后立即自检（probe 替换域名），失败 restore_hosts()
+- 自检失败 → 回滚 + degraded 状态 + 告警，坏配置绝不留场
+- v0.2.19（李工 8 条）：正常态也保持 hosts 段存在（全局访问生效），
+  写入前与现有段落比较，内容无变化不落盘（避免频繁写盘/flushdns）
+"""
+
+from typing import Dict, List
+
+from . import platform_adapter
+
+START_MARK = "# ghlink Start"
+END_MARK = "# ghlink End"
+G520_START = "# ghlink520 Start"
+G520_END = "# ghlink520 End"
+
+
+def build_block(entries: Dict[str, List[str]]) -> str:
+    """由 {domain: [ips]} 生成 hosts 段落文本（含 Start/End 标记）。"""
+    lines = [START_MARK]
+    for domain, ips in entries.items():
+        for ip in ips:
+            lines.append(f"{ip} {domain}")
+    lines.append(END_MARK)
+    return "\n".join(lines) + "\n"
+
+
+def build_combined_block(dynamic: Dict[str, List[str]], g520: Dict[str, List[str]]) -> str:
+    """生成「动态段 + GitHub520 静态子段」复合段落。
+
+    结构：
+        # ghlink Start
+        <动态 IP：8 域名>
+        # ghlink520 Start
+        <GitHub520 社区 IP：非核心域名>
+        # ghlink520 End
+        # ghlink End
+
+    g520 为空时不输出子段标记，段落保持原样（向后兼容旧 hosts）。
+    """
+    lines = [START_MARK]
+    for domain, ips in dynamic.items():
+        for ip in ips:
+            lines.append(f"{ip} {domain}")
+    if g520:
+        lines.append(G520_START)
+        for domain, ips in g520.items():
+            for ip in ips:
+                lines.append(f"{ip} {domain}")
+        lines.append(G520_END)
+    lines.append(END_MARK)
+    return "\n".join(lines) + "\n"
+
+
+def _read_hosts(path: str) -> str:
+    try:
+        with open(path, encoding="utf-8", errors="replace") as f:
+            return f.read()
+    except OSError:
+        return ""
+
+
+def _write_hosts(path: str, content: str) -> bool:
+    try:
+        with open(path, "w", encoding="utf-8") as f:
+            f.write(content)
+        return True
+    except OSError:
+        return False
+
+
+def _extract_section(content: str, start_mark: str, end_mark: str) -> str:
+    """提取段落内部文本（不含标记）；段落缺失/标记不完整返回 ''。"""
+    start = content.find(start_mark)
+    end = content.find(end_mark)
+    if start == -1 or end == -1 or end <= start:
+        return ""
+    return content[start + len(start_mark) : end]
+
+
+def current_ghlink_block(path: str = "") -> str:
+    """读取当前 hosts 中的 # ghlink Start/End 段全文（含标记）；不存在返回 ''。"""
+    path = path or platform_adapter.get_hosts_path()
+    content = _read_hosts(path)
+    start = content.find(START_MARK)
+    end = content.find(END_MARK)
+    if start == -1 or end == -1 or end <= start:
+        return ""
+    return content[start : end + len(END_MARK)]
+
+
+def current_g520_entries(path: str = "") -> Dict[str, List[str]]:
+    """从当前 hosts 提取 GitHub520 子段条目 {domain: [ips]}；无子段返回 {}。
+
+    v0.2.19：初始化合入后，动态更新时从现有 hosts 保留该子段（不重复拉取/合入）。
+    """
+    path = path or platform_adapter.get_hosts_path()
+    content = _read_hosts(path)
+    section = _extract_section(content, G520_START, G520_END)
+    if not section:
+        return {}
+    entries: Dict[str, List[str]] = {}
+    for line in section.splitlines():
+        line = line.strip()
+        if not line or line.startswith("#"):
+            continue
+        parts = line.split()
+        if len(parts) < 2:
+            continue
+        ip, domain = parts[0], parts[1].rstrip(".")
+        entries.setdefault(domain, [])
+        if ip not in entries[domain]:
+            entries[domain].append(ip)
+    return entries
+
+
+def apply_block(
+    block: str,
+    backup_dir: str = "backup",
+    preserve_g520: bool = True,
+) -> tuple:
+    """写入 hosts（替换旧段落）；提权/写入失败返回 (False, "")。
+
+    参数：
+    - block: 新段落全文（含 # ghlink Start/End 标记）
+    - preserve_g520: 若现有 hosts 含 GitHub520 子段而新 block 不含，
+      则自动保留子段（v0.2.19 初始化合一次、动态更新不丢兜底段）
+
+    返回 (ok, backup_path)：ok=False 表示写入失败；ok=True 时 backup_path
+    为本次写入前的备份文件路径（供自检失败回滚使用）。
+    """
+    if not platform_adapter.ensure_privilege():
+        return False, ""
+    path = platform_adapter.get_hosts_path()
+    content = _read_hosts(path)
+
+    # v0.2.19：动态段更新时保留现有 GitHub520 子段（初始化已合入，不重复拉取）
+    if preserve_g520 and G520_START not in block:
+        g520 = _extract_section(content, G520_START, G520_END)
+        if g520:
+            # 把子段插入 # ghlink End 之前
+            end_pos = block.rfind(END_MARK)
+            if end_pos != -1:
+                sub = f"\n{G520_START}{g520}{G520_END}"
+                block = block[:end_pos] + sub + block[end_pos:]
+
+    # v0.4.0（李工 12:35 点 3）：段落插到文件最前优先命中（first-match-wins），
+    # 避免用户预存条目在段落前遮蔽 ghlink 写入；段落外内容零改动
+    start = content.find(START_MARK)
+    end = content.find(END_MARK)
+    if start != -1 and end != -1 and end > start:
+        before = content[:start]
+        after = content[end + len(END_MARK) :]
+        content = before + block + after
+        # 若段落不在文件最前（前面还有非空内容），把段落提前到最前
+        if before.strip():
+            content = block + "\n" + before + after
+    elif start == -1 and end == -1:
+        content = block + "\n" + content.rstrip("\n") + "\n"
+    else:
+        # 段落标记不完整，视为异常：整体重建安全内容
+        return False, ""
+
+    # v0.2.19：内容无变化不落盘（避免每轮写盘 + flushdns）
+    if content == _read_hosts(path):
+        return True, ""
+
+    backup = platform_adapter.backup_hosts(backup_dir)
+    if not backup:
+        return False, ""
+    if not _write_hosts(path, content):
+        platform_adapter.restore_hosts(backup)
+        return False, ""
+    platform_adapter.flush_dns()
+    return True, backup
+
+
+def remove_block(path: str = "") -> bool:
+    """v0.4.1（拂晓 Linux 严格测试发现）：移除 hosts 中的 ghlink 段落（含 ghlink520 子段），
+    还原基线（disable/卸载时调用，李工"卸载也直接删"要求）。段落不存在返回 True（幂等）。"""
+    if not platform_adapter.ensure_privilege():
+        return False
+    path = path or platform_adapter.get_hosts_path()
+    content = _read_hosts(path)
+    start = content.find(START_MARK)
+    end = content.find(END_MARK)
+    if start == -1 or end == -1 or end <= start:
+        return True  # 无段落，幂等成功
+    # 移除段落（含段落前后的多余空行清理）
+    before = content[:start]
+    after = content[end + len(END_MARK) :]
+    new_content = before + after
+    # 清理段落移除后残留的双空行
+    while "\n\n\n" in new_content:
+        new_content = new_content.replace("\n\n\n", "\n\n")
+    if new_content == content:
+        return True
+    if not _write_hosts(path, new_content):
+        return False
+    platform_adapter.flush_dns()
+    return True
+
+
+def detect_external_dupes(path: str = "") -> Dict[str, str]:
+    """v0.4.0（李工 12:35 点 3）：检测段落外预存的 GitHub 生态域名条目。
+
+    返回 {domain: "ip"}——用户在 ghlink 块之外已配置的条目，
+    first-match-wins 下可能与 ghlink 写入冲突。enable 时调用，命中则告警+备份。
+    """
+    path = path or platform_adapter.get_hosts_path()
+    content = _read_hosts(path)
+    # 剔除 ghlink 段落（含 ghlink520 子段）
+    start = content.find(START_MARK)
+    end = content.find(END_MARK)
+    if start != -1 and end != -1 and end > start:
+        content = content[:start] + content[end + len(END_MARK) :]
+    out: Dict[str, str] = {}
+    for line in content.splitlines():
+        line = line.strip()
+        if not line or line.startswith("#"):
+            continue
+        parts = line.split()
+        if len(parts) < 2:
+            continue
+        ip, domain = parts[0], parts[1].rstrip(".")
+        if domain.endswith(
+            (".github.com", "github.com", "githubusercontent.com", "githubassets.com", "fastly.net")
+        ):
+            out.setdefault(domain, ip)
+    return out
+
+
+def verify_after_apply(targets: List[str], timeout_sec: float) -> bool:
+    """写入后立即自检：新 IP 下全部目标连通才算成功。
+
+    v0.4.4（李工 03:27 终裁 B 方案，顾笙无缓存场景专项发现）：分级宽容降级——
+    先三层全检（TCP+TLS+HTTP HEAD），失败目标用 TCP-only 复检：
+    TCP 通判通过（与预检同口径，防 TLS 干扰误杀——TLS 握手被干扰但 IP 实际可达
+    时不再回滚清空兜底写入）；TCP 也不通才判失败（真坏 IP 仍回滚，坏配置绝不留场）。
+    """
+    from . import probe
+
+    results = probe.probe_all(targets, timeout_sec)
+    failed = [h for h, r in results.items() if not r.get("ok")]
+    if not failed:
+        return True
+    # 分级宽容：失败目标 TCP-only 复检（TCP 通即通过）
+    tcp_results = probe.probe_tcp_only_many(failed, timeout_sec)
+    return all(r.get("ok") for r in tcp_results.values())
+
+
+def rollback(backup_path: str) -> bool:
+    """回滚 hosts 到备份版本。"""
+    return platform_adapter.restore_hosts(backup_path)