debug-control-plane 0.1.0__py3-none-any.whl

debug_control_plane/device_discovery/discovery/manual_registry.py

@@ -0,0 +1,245 @@
+"""Manual device registry — human-told fallback channel (R020-BF007).
+
+Role (design §3.4 ManualRegistry / §4.2.1 register_device tool / §4.3 devices.json):
+    When auto-discovery (BF002 USB + BF005 LAN scan) misses a device the AI
+    knows about (e.g. the phone is on a different subnet, behind a VPN the
+    host can't see, or simply not yet probed), the human can explicitly tell
+    the bridge ``register_device(host=192.168.1.34)``. This service probes
+    that single host's ``/hello``, and on success registers a
+    :class:`DeviceRecord` with ``source="manual"`` in :class:`DevicePool`.
+
+Three concerns kept separate (design §3.4 single-direction dependency):
+
+  * **Identity** (``device_id``) is host-derived — ``manual-<sha1(host)[:16]>``
+    via :func:`device_pool.manual_device_id`. **NEVER** sourced from
+    ``/hello.deviceId`` (R019 fixed string ``gmacro-virtual-iOS`` collides
+    across devices — backend D9, enforced by BF001 ``manual_device_id``).
+  * **Reachability** is verified by reusing :func:`endpoint.probe_hello`
+    (BF002, design D8 zero-rewrite). A failed probe does NOT pollute the
+    pool (analysis L3) — the caller sees ``RegisterResult(ok=False)`` with a
+    :class:`DeviceUnreachable` error (BF008 exception model, shared vocab).
+  * **Persistence** is delegated to :meth:`DevicePool.upsert` (BF001.3
+    identity-only — this module never touches devices.json directly).
+
+Why inject ``LanScan`` if ``register`` only uses ``probe_hello``? The task
+skeleton (tasks.md BF007) specifies ``__init__(self, pool, lan_scan)`` for
+forward-compat with BF011 server wiring (the server already holds a LanScan
+instance). Holding it is cheap; not calling ``scan()`` from ``register``
+keeps single-host registration O(1) (no /24 sweep).
+
+Design references:
+  - tasks: .dev-flow/R020/mcp-bridge-device-discovery-tasks.md BF007 (L472-497)
+  - design: .dev-flow/R020/analysis/2026-08-08--mcp-bridge-device-discovery-backend.md
+            §3.4 ManualRegistry / §4.2.1 / §4.3
+  - test:  .dev-flow/R020/analysis/2026-08-08--mcp-bridge-device-discovery-test.md §2.1
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from ..device_pool import DevicePool, DeviceRecord, manual_device_id
+from ..endpoint import Endpoint, UrlOpen, default_urlopen, probe_hello
+
+# AD-B9: DeviceUnreachable 自 mcp_debug_bridge/bridge_client 下沉至 device_discovery/protocol.
+from ..protocol import DeviceUnreachable
+
+if TYPE_CHECKING:  # pragma: no cover - typing only
+    from ..protocol import NetworkTarget
+    from .lan_scan import LanScan
+
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+#: R019 debug plane HTTP port (mobile app listens here). Matches BF005/BF008.
+DEFAULT_PORT = 18080
+
+#: probe /hello timeout. Single-host probe — slightly more generous than
+#: BF005's 2.5s sweep default, since a single explicit host deserves one
+#: full timeout window before we declare it unreachable.
+DEFAULT_PROBE_TIMEOUT = 3.0
+
+
+# ---------------------------------------------------------------------------
+# Result type
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class RegisterResult:
+    """Outcome of :meth:`ManualRegistry.register`.
+
+    Two-state result (never raises — :meth:`register` catches all probe
+    failures and returns ``ok=False``). The caller dispatches:
+
+      * ``ok=True``  → use ``record`` (already in the pool).
+      * ``ok=False`` → inspect ``error`` (always :class:`DeviceUnreachable`
+        for probe failures); the pool is untouched.
+
+    Why a result object instead of raising? Two reasons:
+      1. The MCP ``register_device`` tool wants to translate probe failures
+         into the ``device_unreachable`` MCP error, not a Python traceback —
+         a result object makes that translation explicit at the call site.
+      2. ``register`` must be total: a typo'd host or a powered-off phone is
+         a normal input, not an exceptional state (analysis L3 "人工告知也可能
+         告知错误").
+    """
+
+    ok: bool
+    record: DeviceRecord | None = None
+    error: DeviceUnreachable | None = None
+
+
+# ---------------------------------------------------------------------------
+# Service
+# ---------------------------------------------------------------------------
+
+
+class ManualRegistry:
+    """Human-told device registration service (design §3.4 / analysis L3).
+
+    Wraps :func:`endpoint.probe_hello` + :meth:`DevicePool.upsert` into a
+    single ``register(host, port, label)`` call that:
+
+      1. Probes ``http://{host}:{port}/hello`` (reuses BF002 ``probe_hello``,
+         D8 zero-rewrite). On failure returns ``RegisterResult(ok=False)``
+         with :class:`DeviceUnreachable` — the pool is NOT modified.
+      2. Derives ``device_id = manual_device_id(host)`` (BF001 helper,
+         ``manual-<sha1(host)[:16]>``). Independent of ``/hello.deviceId``
+         (backend D9).
+      3. Builds a :class:`DeviceRecord` with ``source="manual"`` and the
+         probe's runtime fields (hardware_name/machine_id/platform +
+         last_known_host/last_seen), then :meth:`DevicePool.upsert` it.
+         Persistence (devices.json) is delegated to DevicePool — this module
+         never writes the file directly (BF001.3 identity-only).
+
+    Args:
+        pool: BF001 DevicePool — identity store + persistence (never None).
+        lan_scan: BF005 LanScan — held for forward-compat with BF011 server
+            wiring; ``register`` does NOT call ``scan()`` (single-host probe
+            only). Accepting it here lets the server pass its existing
+            LanScan instance without a second constructor.
+        port: default port (18080, R019 debug plane). Per-call ``port``
+            override in :meth:`register` takes precedence.
+        probe_timeout: single-host probe timeout (default 3.0s).
+        urlopen: injectable urlopen for testing (defaults to
+            ``endpoint.default_urlopen`` = ``urllib.request.urlopen``).
+    """
+
+    def __init__(
+        self,
+        pool: DevicePool,
+        lan_scan: LanScan,
+        *,
+        port: int = DEFAULT_PORT,
+        probe_timeout: float = DEFAULT_PROBE_TIMEOUT,
+        urlopen: UrlOpen | None = None,
+    ) -> None:
+        self._pool = pool
+        self._lan_scan = lan_scan
+        self._port = port
+        self._probe_timeout = probe_timeout
+        self._urlopen: UrlOpen = urlopen if urlopen is not None else default_urlopen
+
+    def register(
+        self,
+        host: str,
+        *,
+        port: int | None = None,
+        label: str | None = None,
+        note: str | None = None,
+    ) -> RegisterResult:
+        """Probe ``host`` and register it as a manual device on success.
+
+        Args:
+            host: target IPv4 (or hostname) the human told us about.
+            port: override the registry's default port (default None → use
+                ``self._port``).
+            label: human-readable label. Defaults to ``host`` when None.
+            note: optional human annotation persisted with the identity
+                (BF001.3 ``note`` field; meaningful only for source="manual").
+
+        Returns:
+            :class:`RegisterResult`. ``ok=True`` + ``record`` on success;
+            ``ok=False`` + ``error`` (DeviceUnreachable) on any probe failure.
+            Never raises — all probe exceptions are caught and surfaced as
+            ``ok=False`` (analysis L3: 人工告知也可能告知错误).
+        """
+        effective_port = self._port if port is None else port
+        endpoint = Endpoint(host, effective_port)
+        target = self._safe_probe(endpoint)
+        if target is None:
+            return RegisterResult(
+                ok=False,
+                error=DeviceUnreachable(
+                    f"probe /hello failed for {host}:{effective_port} "
+                    f"(host unreachable, timed out, or returned invalid /hello)"
+                ),
+            )
+
+        record = self._build_record(host, target, label=label, note=note)
+        self._pool.upsert(record)
+        return RegisterResult(ok=True, record=record)
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _safe_probe(self, endpoint: Endpoint) -> NetworkTarget | None:
+        """Probe ``/hello`` and never raise.
+
+        ``probe_hello`` (BF002) already swallows OSError/URLError/TimeoutError
+        /JSONDecodeError → None. We additionally catch any unexpected
+        exception (defensive — a buggy urlopen shouldn't crash the registry)
+        and return None, so :meth:`register` always returns a
+        :class:`RegisterResult`.
+        """
+        try:
+            return probe_hello(
+                endpoint,
+                timeout=self._probe_timeout,
+                urlopen=self._urlopen,
+            )
+        except Exception:  # noqa: BLE001 (defensive — never crash register)
+            return None
+
+    @staticmethod
+    def _build_record(
+        host: str,
+        target: NetworkTarget,
+        *,
+        label: str | None,
+        note: str | None,
+    ) -> DeviceRecord:
+        """Assemble the DeviceRecord from a successful probe.
+
+        Identity: ``device_id`` is host-derived (NEVER ``target.device_id``);
+        ``label`` falls back to ``host`` when the human didn't supply one.
+        Runtime: ``last_known_host``/``last_seen`` record the probe moment
+        (memory-only per BF001.3); ``hardware_name``/``machine_id``/
+        ``platform`` come straight from /hello (may be None on old phones).
+        """
+        return DeviceRecord(
+            device_id=manual_device_id(host),
+            label=label if label else host,
+            source="manual",
+            last_known_host=host,
+            last_seen=time.time(),
+            hardware_name=target.hardware_name,
+            machine_id=target.machine_id,
+            platform=target.platform,
+            network_target=target,
+            note=note,
+        )
+
+
+__all__ = [
+    "DEFAULT_PORT",
+    "DEFAULT_PROBE_TIMEOUT",
+    "ManualRegistry",
+    "RegisterResult",
+]

debug_control_plane/device_discovery/discovery/usb_identity.py

@@ -0,0 +1,228 @@
+"""USB 设备身份源服务 (R020-BF004).
+
+职责 (design §3.4 + analysis iOS/Android §USB 通道): 通过 USB 通道 (Android
+``adb devices -l`` / iOS ``flutter devices``) 取设备**身份** (serial /
+usbmuxd id / 机型 / LAN IP), 供下游 BF006 cross_identify 做 USB⊕LAN 交叉识别.
+
+设计要点:
+  * **USB 仅当身份源不当数据通道** (analysis backlog 红线 / BF004.3): 本服务
+    只取身份字段, **绝不**做 ``adb forward`` / ``iproxy`` 数据通道转发.
+    ``android_lan_ip`` 是身份辅助 (供 BF006 交叉识别用), 不是数据通道.
+  * **分端策略** (memory ios16-device-devicectl-pitfall):
+    - Android: ``adb devices -l`` → serial + model; LAN IP 经
+      ``adb shell ip route get 1.1.1.1`` 精确拿 (供 BF006 交叉识别用).
+    - iOS: **只**走 ``flutter devices --machine`` (BF002.2
+      ``discover_ios_flutter_candidates``, 解析 usbmuxd id + 机型);
+      **绝不**调 ``xcrun devicectl`` (iPhone X iOS 16 永远 unavailable).
+  * **复用 device_candidates** (D8 + BF004 决策 1, 不改旧函数):
+    - Android: 复用 ``_android_device_ip(serial, run_command)`` 拿精确 LAN IP;
+      serial + model 自己解析 ``adb devices -l`` 输出 (device_candidates
+      ``_android_connected_devices`` 内部已做此解析但暴露的 ConnectedDeviceEndpoint
+      丢失 serial, 故 BF004 自行解析以保留 device_id=serial).
+    - iOS: 直接调 ``discover_ios_flutter_candidates(run_command=...)`` 拿
+      ``IosDeviceCandidate`` (device_id=usbmuxd id, model), 转 UsbCandidate.
+  * **异常容忍** (与 device_candidates + BF003/BF005 同模式): adb/flutter 不可用
+    (命令不存在 / 超时 / 无设备) → 返回空列表, 不抛异常.
+
+设计来源:
+  - tasks: .dev-flow/R020/mcp-bridge-device-discovery-tasks.md BF004 节
+  - design: .dev-flow/R020/analysis/2026-08-08--mcp-bridge-device-discovery-backend.md
+            §3.4 Discovery (UsbIdentity 角色) + D9 device_id 来源
+  - analysis: .dev-flow/R020/analysis/2026-08-08--mcp-bridge-device-discovery.md
+            §USB 通道 (USB 仅身份不数据通道) + §iOS/Android
+  - test:  .dev-flow/R020/analysis/2026-08-08--mcp-bridge-device-discovery-test.md §2.1
+  - memory: ios16-device-devicectl-pitfall (iOS 16 devicectl 永远 unavailable)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+# device_candidates 是 device_discovery 顶层模块 (BF006 自旧 network 子包迁入).
+# 复用其解析函数 (D8 零重写), 不改其旧函数.
+from ..device_candidates import (
+    CommandRunner,
+    _android_device_ip,
+    _metadata_value,
+    _run_command,
+    discover_ios_flutter_candidates,
+)
+
+# ---------------------------------------------------------------------------
+# UsbCandidate dataclass (BF004.2)
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class UsbCandidate:
+    """USB 身份候选 (单台已连接的物理设备).
+
+    跨平台统一身份容器: Android 来自 ``adb`` serial, iOS 来自 ``flutter``
+    usbmuxd id. ``device_id`` 是稳定身份键 (BF006 cross_identify 用此匹配
+    LAN 响应, design D9); ``android_lan_ip`` 是 Android 独有的身份辅助字段
+    (经 ``adb shell ip route`` 精确拿, iOS 恒 None), 供 BF006 做交叉识别桥梁.
+
+    Attributes:
+        device_id: 稳定身份标识. Android = adb serial (如 ``R58M1234567``);
+            iOS = usbmuxd id (如 ``3992f440...``, ``flutter devices --machine``
+            的 ``id`` 字段).
+        model: 机型显示名 (Android = ``model:`` 字段值如 ``SM-G991B``;
+            iOS = ``flutter devices --machine`` 的 ``name`` 字段如 ``iPhone X``).
+            弱唯一, 仅用于交叉识别 + 显示.
+        platform: ``"android"`` 或 ``"ios"``.
+        android_lan_ip: Android 经 ``adb shell ip route get 1.1.1.1`` 精确拿的
+            LAN IP (供 BF006 交叉识别用); iOS 恒 ``None`` (USB 仅身份, iOS LAN
+            IP 由 BF005 LanScan 在 LAN 侧发现, 不在 USB 侧拿).
+    """
+
+    device_id: str
+    model: str
+    platform: str
+    android_lan_ip: str | None = None
+
+
+# ---------------------------------------------------------------------------
+# UsbIdentity 服务 (BF004.1)
+# ---------------------------------------------------------------------------
+
+
+class UsbIdentity:
+    """USB 设备身份源服务 (Android ``adb`` / iOS ``flutter`` 分端).
+
+    分端取 USB 已连接设备的身份 (serial / usbmuxd id / 机型 / LAN IP), 返回
+    ``UsbCandidate`` 列表. **仅身份, 不做数据通道** (BF004.3, 不调
+    ``adb forward`` / ``iproxy``).
+
+    Example::
+
+        svc = UsbIdentity()
+        android = svc.android()        # [UsbCandidate(device_id="R58M...", ...)]
+        ios = svc.ios()                # [UsbCandidate(device_id="3992f440...", ...)]
+        all_devs = svc.all_candidates()  # android + ios 合并
+
+    Args:
+        run_command: 可注入的命令执行器 (默认 device_candidates._run_command,
+            即 subprocess.run 封装); 测试时注入 mock runner (按 command 前缀
+            返回预设输出或抛 OSError). 与 BF003/BF005/device_candidates 同模式.
+    """
+
+    def __init__(self, *, run_command: CommandRunner | None = None) -> None:
+        self._run_command: CommandRunner = run_command or _run_command
+
+    def android(self) -> list[UsbCandidate]:
+        """Android USB 身份候选 (经 ``adb devices -l`` + ``adb shell ip route``).
+
+        解析 ``adb devices -l`` 输出取 ``device`` 状态的 serial + model; 对每个
+        serial 调 device_candidates ``_android_device_ip(serial)`` 经
+        ``adb shell ip route get 1.1.1.1`` 拿精确 LAN IP (供 BF006 交叉识别).
+
+        Returns:
+            ``UsbCandidate`` 列表 (platform="android"); 空 list 表示 adb 不可用 /
+            无设备 / 无 LAN IP (拿不到 LAN IP 的设备跳过, 与 device_candidates
+            ``_android_connected_devices`` 一致). 永不抛异常.
+
+        Side effects:
+            调用 ``adb devices -l`` + 每台设备一次 ``adb shell ip route``.
+        """
+        try:
+            output = self._run_command(["adb", "devices", "-l"], 5.0)
+        except OSError:
+            # adb 不可用 / 超时 / 命令失败 → 与 device_candidates 同模式返空
+            return []
+        candidates: list[UsbCandidate] = []
+        for serial, model in _parse_adb_devices_output(output):
+            lan_ip = _android_device_ip(serial, self._run_command)
+            if lan_ip is None:
+                # 拿不到 LAN IP 的设备跳过 (与 _android_connected_devices 一致:
+                # 没有可用 LAN IP 的 Android 设备对 BF006 交叉识别无意义)
+                continue
+            candidates.append(
+                UsbCandidate(
+                    device_id=serial,
+                    model=model,
+                    platform="android",
+                    android_lan_ip=lan_ip,
+                )
+            )
+        return candidates
+
+    def ios(self) -> list[UsbCandidate]:
+        """iOS USB 身份候选 (经 ``flutter devices --machine``, 不调 devicectl).
+
+        复用 BF002.2 ``discover_ios_flutter_candidates`` 解析 ``flutter devices
+        --machine`` JSON, 取真机 (排除 simulator/emulator) 的 usbmuxd id + 机型;
+        绝不调 ``xcrun devicectl`` (iPhone X iOS 16 永远 unavailable,
+        memory ios16-device-devicectl-pitfall).
+
+        Returns:
+            ``UsbCandidate`` 列表 (platform="ios", android_lan_ip=None); 空 list
+            表示 flutter 不可用 / 无真机 / 解析失败. 永不抛异常.
+
+        Side effects:
+            调用 ``flutter devices --machine`` (内部已处理多 flutter 候选命令
+            ``flutter`` / ``/usr/local/bin/flutter`` / ``fvm`` 等).
+        """
+        ios_candidates = discover_ios_flutter_candidates(run_command=self._run_command)
+        return [
+            UsbCandidate(
+                device_id=cand.device_id,
+                model=cand.model,
+                platform="ios",
+                android_lan_ip=None,  # iOS LAN IP 由 BF005 LanScan 在 LAN 侧发现
+            )
+            for cand in ios_candidates
+        ]
+
+    def all_candidates(self) -> list[UsbCandidate]:
+        """所有 USB 已连接设备 (Android + iOS 合并, Android 在前).
+
+        Returns:
+            ``UsbCandidate`` 列表 (先 android() 后 ios()); 两个端都不抛异常,
+            任一端失败只贡献空列表.
+        """
+        return [*self.android(), *self.ios()]
+
+
+# ---------------------------------------------------------------------------
+# adb devices -l 解析 (BF004 自行解析以保留 serial, 不复用 _android_connected_devices
+# 因其暴露的 ConnectedDeviceEndpoint 丢失 serial — BF004 device_id=serial 需保留)
+# ---------------------------------------------------------------------------
+
+
+#: ``adb devices -l`` 输出行的 ``device`` 状态标记 (其余 ``offline``/``unauthorized`` 跳过).
+_ADB_DEVICE_STATE_CONNECTED = "device"
+
+
+def _parse_adb_devices_output(output: str) -> list[tuple[str, str]]:
+    """解析 ``adb devices -l`` 输出, 返回 ``[(serial, model), ...]``.
+
+    只取状态为 ``device`` (已授权连接) 的行; ``offline`` / ``unauthorized`` /
+    ``recovery`` 等状态跳过. model 来自 ``model:`` 元数据字段 (如
+    ``model:SM-G991B``); 缺失则回退 serial (与 device_candidates
+    ``_metadata_value(parts, "model") or serial`` 一致).
+
+    Args:
+        output: ``adb devices -l`` 的原始标准输出.
+
+    Returns:
+        ``[(serial, model), ...]`` 列表, 顺序与输入一致; 输出为空 / 全非 device
+        状态 → 空列表.
+    """
+    results: list[tuple[str, str]] = []
+    # 第一行是 "List of devices attached" 表头, 但稳妥起见逐行判断状态字段
+    # (而非简单 splitlines()[1:], 防御空输出 / 单行输出).
+    for line in output.splitlines():
+        parts = line.split()
+        if len(parts) < 2 or parts[1] != _ADB_DEVICE_STATE_CONNECTED:
+            continue
+        serial = parts[0]
+        # 复用 device_candidates._metadata_value (D8 零重写, 同模块已 export).
+        model = _metadata_value(parts, "model") or serial
+        results.append((serial, model))
+    return results
+
+
+__all__ = [
+    "UsbCandidate",
+    "UsbIdentity",
+]

debug_control_plane/device_discovery/discovery/vpn_immune.py

@@ -0,0 +1,103 @@
+"""VPN-immune LAN CIDR service (R020-BF003).
+
+封装 :mod:`device_discovery.endpoint` 的路由表网段计算, 对上层
+(LanScan / DevicePool) 暴露稳定的 ``lan_cidr()`` 接口, 同时记录 fallback
+事件 (路由表失败 → socket 出口法) 供上层日志 / 诊断.
+
+设计参考:
+  - design §5.4 VPN-immune 网段计算 (route -n get default → en0 → ipconfig
+    getifaddr → /24 CIDR; 失败 fallback socket 出口法, 仅兜底不主导)
+  - design §4.2 BF003 角色: VpnImmune 在 LanScan 上游提供网段来源
+  - tasks BF003: 封装 endpoint.vpn_immune_lan_cidrs + 暴露 fallback 可观测性
+
+隐蔽坑 (design §5.4): 全局 VPN (Surge/ClashX TUN 模式 ``utun1024=198.18.0.1``)
+劫持 ``socket.connect((1.1.1.1,80))`` 出口, 返回 198.18.x 而非真实 LAN. 本服务
+依赖 endpoint 的路由表法 (读 route 输出的 interface 行), 默认路径避开 TUN 污染;
+fallback 路径会暴露 ``socket_fallback`` source + 诊断 note 提示上层注意.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from ..endpoint import (
+    CommandRunner,
+    _run_command_default,
+    vpn_immune_lan_cidrs_traced,
+)
+
+#: 路由表成功 source 标记 (design §5.4 主路径).
+SOURCE_ROUTE_TABLE = "route_table"
+
+#: socket 出口法 fallback source 标记 (design §5.4 兜底路径, 可能受 VPN TUN 污染).
+SOURCE_SOCKET_FALLBACK = "socket_fallback"
+
+#: fallback 路径的诊断 note (供上层日志提示运维者注意 VPN TUN 风险).
+_FALLBACK_NOTE = (
+    "route table unavailable, socket fallback (may be VPN TUN polluted)"
+)
+
+
+@dataclass
+class FallbackEvent:
+    """VpnImmune 网段解析事件 (供上层日志 / 诊断).
+
+    每次 :meth:`VpnImmune.lan_cidr` 调用后刷新 ``VpnImmune.last_event``.
+
+    Attributes:
+        source: ``"route_table"`` (路由表成功) 或 ``"socket_fallback"``
+            (回退 socket 出口法, 可能受 VPN TUN 污染).
+        cidrs: 本次返回的 CIDR 列表 (与 ``lan_cidr()`` 返回值一致, 拷贝).
+        note: 诊断说明; route_table 路径为空字符串, socket_fallback 路径
+            含 VPN TUN 污染风险提示.
+    """
+
+    source: str
+    cidrs: list[str]
+    note: str = ""
+
+
+@dataclass
+class VpnImmune:
+    """VPN-immune LAN 网段服务 (design §5.4).
+
+    封装 endpoint 的路由表法, 对上层暴露 ``lan_cidr() → list[str]``; 记录
+    fallback 事件 (路由表失败 → socket 出口法) 供诊断.
+
+    Example::
+
+        svc = VpnImmune()
+        cidrs = svc.lan_cidr()           # ["192.168.1.0/24"]
+        event = svc.last_event           # FallbackEvent(source="route_table", ...)
+        if event.source == "socket_fallback":
+            log.warning("LAN scan may be polluted by VPN TUN: %s", event.note)
+
+    Args:
+        run_command: 可注入命令执行器 (默认 ``_run_command_default`` 即 subprocess.run);
+            测试时注入 mock runner (前缀匹配 command → 返回字符串或抛 OSError).
+        cidr_prefix_len: CIDR 前缀长度 (默认 24, 与 discover_default_endpoints 一致).
+    """
+
+    run_command: CommandRunner = _run_command_default
+    cidr_prefix_len: int = 24
+    last_event: FallbackEvent | None = field(default=None, init=False)
+
+    def lan_cidr(self) -> list[str]:
+        """返回真实 LAN 网段列表 (路由表法, VPN TUN 不污染).
+
+        Returns:
+            CIDR 字符串列表 (如 ``["192.168.1.0/24"]``); 空列表表示无 LAN 可达.
+            路由表失败时回退 socket 出口法, 不抛异常 (返回可能含 198.18.x).
+
+        Side effects:
+            刷新 :attr:`last_event` — 上层可读 ``source`` / ``note`` 做诊断.
+        """
+        cidrs, source = vpn_immune_lan_cidrs_traced(
+            run_command=self.run_command, cidr_prefix_len=self.cidr_prefix_len
+        )
+        note = "" if source == SOURCE_ROUTE_TABLE else _FALLBACK_NOTE
+        # 拷贝 cidrs 避免外部 mutate 污染内部 state (dataclass 默认可变默认值陷阱)
+        self.last_event = FallbackEvent(
+            source=source, cidrs=list(cidrs), note=note
+        )
+        return cidrs