debug-control-plane 0.1.0__tar.gz

debug_control_plane-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026-present tangxiaolu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

debug_control_plane-0.1.0/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.4
+Name: debug-control-plane
+Version: 0.1.0
+Summary: Multi-product reusable debug control plane (device discovery + MCP adapter).
+Author: tangxiaolu
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp<2,>=1.28
+Requires-Dist: httpx>=0.28
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Requires-Dist: pytest-cov>=4; extra == "test"
+Requires-Dist: ruff>=0.4; extra == "test"
+Dynamic: license-file
+
+# debug-control-plane (Python)
+
+Multi-product reusable debug control plane — Python slice.
+多产品复用的调试控制平面——Python 切片。
+
+Provides / 提供：
+- **device_discovery**: USB/WiFi device discovery + cross-identity pairing (USB identity source / LAN scan / VPN-immune subnet / device pool with TTL).
+  USB/WiFi 设备发现 + 跨身份配对（USB 身份源 / LAN 扫描 / VPN 免疫网段 / 带 TTL 的设备池）。
+- **mcp_plane**: MCP adapter over the R019 8-endpoint debug HTTP protocol — capability mirror (dynamic tools), bridge client, bare server, and a `SemanticProvider` protocol hook for product semantic sugar.
+  建立在 R019 8 端点调试 HTTP 协议之上的 MCP 适配器——能力镜像（动态 tools）、桥客户端、裸服务端，以及供产品语义糖接入的 `SemanticProvider` 协议钩子。
+
+## Dependency direction / 依赖方向
+
+```
+business app (pantas_launcher / future products)   业务应用（pantas_launcher / 未来产品）
+        │  depends on (downward)                     依赖（向下）
+        ▼
+debug_control_plane (this package)                        本包
+        │  depends on (downward)                     依赖（向下）
+        ▼
+  mcp (SDK) · httpx (HTTP client)
+```
+
+This package is **pure infrastructure**: it MUST NOT import any business package (`pantas_launcher`, `host4_flutter_gmacro`, gamepad/feature code). Business apps depend on this package; never the reverse.
+本包是**纯基础设施**：绝不 import 任何业务包（`pantas_launcher`、`host4_flutter_gmacro`、手柄/特性代码）。业务应用依赖本包，反之禁止。
+
+## Install / 安装
+
+```bash
+# editable install — picks up source changes without reinstall
+# 可编辑安装——源码改动即时生效，无需重装
+python -m pip install -e .
+
+# import sanity check / 导入自检
+python -c "import debug_control_plane; print(debug_control_plane.__version__)"
+```
+
+## Layout / 结构
+
+```
+python/
+├── pyproject.toml                  # single-package, two sub-packages / 单包双子包
+├── README.md                       # this file
+├── LICENSE                         # MIT
+└── debug_control_plane/
+    ├── __init__.py                 # __version__ = "0.1.0"
+    ├── device_discovery/           # USB/LAN device discovery + device pool
+    │   ├── device_candidates.py
+    │   ├── device_pool.py          # identity-keyed pool, TTL expiry / 身份键池，TTL 过期
+    │   ├── endpoint.py
+    │   ├── protocol.py
+    │   └── discovery/
+    │       ├── usb_identity.py     # USB identity source (adb / flutter devices) / USB 身份源
+    │       ├── lan_scan.py         # LAN /hello probe / LAN /hello 探测
+    │       ├── vpn_immune.py       # VPN-immune subnet calc / VPN 免疫网段计算
+    │       ├── cross_identify.py   # USB ⊕ LAN cross pairing / USB ⊕ LAN 交叉配对
+    │       └── manual_registry.py  # manually-told devices / 人工告知设备
+    └── mcp_plane/                  # MCP adapter
+        ├── capability_mirror.py    # dynamic tools from /hello / 由 /hello 动态镜像 tools
+        ├── bridge_client.py        # HTTP bridge client / HTTP 桥客户端
+        ├── server.py               # bare stdio MCP server / 裸 stdio MCP 服务端
+        └── semantic_provider.py    # SemanticProvider Protocol (product hook) / 语义糖协议钩子
+```
+
+## Console script / 控制台脚本
+
+```
+debug-control-plane-server
+```
+
+Points at `debug_control_plane.mcp_plane.server:main` — a bare server (no business capability assembly) for debugging / plane self-testing.
+指向 `debug_control_plane.mcp_plane.server:main`——裸服务端（无业务能力装配），用于调试 / 平面自测。
+
+## Version / 版本
+
+`0.1.0` — initial release, API unstable. 首发，API 不稳定。
+
+## License / 许可证
+
+Licensed under the MIT License — see [LICENSE](LICENSE).
+采用 MIT 许可证授权——见 [LICENSE](LICENSE)。

debug_control_plane-0.1.0/README.md

@@ -0,0 +1,81 @@
+# debug-control-plane (Python)
+
+Multi-product reusable debug control plane — Python slice.
+多产品复用的调试控制平面——Python 切片。
+
+Provides / 提供：
+- **device_discovery**: USB/WiFi device discovery + cross-identity pairing (USB identity source / LAN scan / VPN-immune subnet / device pool with TTL).
+  USB/WiFi 设备发现 + 跨身份配对（USB 身份源 / LAN 扫描 / VPN 免疫网段 / 带 TTL 的设备池）。
+- **mcp_plane**: MCP adapter over the R019 8-endpoint debug HTTP protocol — capability mirror (dynamic tools), bridge client, bare server, and a `SemanticProvider` protocol hook for product semantic sugar.
+  建立在 R019 8 端点调试 HTTP 协议之上的 MCP 适配器——能力镜像（动态 tools）、桥客户端、裸服务端，以及供产品语义糖接入的 `SemanticProvider` 协议钩子。
+
+## Dependency direction / 依赖方向
+
+```
+business app (pantas_launcher / future products)   业务应用（pantas_launcher / 未来产品）
+        │  depends on (downward)                     依赖（向下）
+        ▼
+debug_control_plane (this package)                        本包
+        │  depends on (downward)                     依赖（向下）
+        ▼
+  mcp (SDK) · httpx (HTTP client)
+```
+
+This package is **pure infrastructure**: it MUST NOT import any business package (`pantas_launcher`, `host4_flutter_gmacro`, gamepad/feature code). Business apps depend on this package; never the reverse.
+本包是**纯基础设施**：绝不 import 任何业务包（`pantas_launcher`、`host4_flutter_gmacro`、手柄/特性代码）。业务应用依赖本包，反之禁止。
+
+## Install / 安装
+
+```bash
+# editable install — picks up source changes without reinstall
+# 可编辑安装——源码改动即时生效，无需重装
+python -m pip install -e .
+
+# import sanity check / 导入自检
+python -c "import debug_control_plane; print(debug_control_plane.__version__)"
+```
+
+## Layout / 结构
+
+```
+python/
+├── pyproject.toml                  # single-package, two sub-packages / 单包双子包
+├── README.md                       # this file
+├── LICENSE                         # MIT
+└── debug_control_plane/
+    ├── __init__.py                 # __version__ = "0.1.0"
+    ├── device_discovery/           # USB/LAN device discovery + device pool
+    │   ├── device_candidates.py
+    │   ├── device_pool.py          # identity-keyed pool, TTL expiry / 身份键池，TTL 过期
+    │   ├── endpoint.py
+    │   ├── protocol.py
+    │   └── discovery/
+    │       ├── usb_identity.py     # USB identity source (adb / flutter devices) / USB 身份源
+    │       ├── lan_scan.py         # LAN /hello probe / LAN /hello 探测
+    │       ├── vpn_immune.py       # VPN-immune subnet calc / VPN 免疫网段计算
+    │       ├── cross_identify.py   # USB ⊕ LAN cross pairing / USB ⊕ LAN 交叉配对
+    │       └── manual_registry.py  # manually-told devices / 人工告知设备
+    └── mcp_plane/                  # MCP adapter
+        ├── capability_mirror.py    # dynamic tools from /hello / 由 /hello 动态镜像 tools
+        ├── bridge_client.py        # HTTP bridge client / HTTP 桥客户端
+        ├── server.py               # bare stdio MCP server / 裸 stdio MCP 服务端
+        └── semantic_provider.py    # SemanticProvider Protocol (product hook) / 语义糖协议钩子
+```
+
+## Console script / 控制台脚本
+
+```
+debug-control-plane-server
+```
+
+Points at `debug_control_plane.mcp_plane.server:main` — a bare server (no business capability assembly) for debugging / plane self-testing.
+指向 `debug_control_plane.mcp_plane.server:main`——裸服务端（无业务能力装配），用于调试 / 平面自测。
+
+## Version / 版本
+
+`0.1.0` — initial release, API unstable. 首发，API 不稳定。
+
+## License / 许可证
+
+Licensed under the MIT License — see [LICENSE](LICENSE).
+采用 MIT 许可证授权——见 [LICENSE](LICENSE)。

debug_control_plane-0.1.0/debug_control_plane/__init__.py

@@ -0,0 +1,7 @@
+"""debug_control_plane — multi-product debug control plane.
+
+Reusable across products: device discovery (USB/WiFi/identity) + MCP adapter
+(debug HTTP protocol → MCP tool surface). Extracted from pantas_launcher R019/
+R020 (S2 Python slice, R021-BF004).
+"""
+__version__ = "0.1.0"

debug_control_plane-0.1.0/debug_control_plane/device_discovery/__init__.py

@@ -0,0 +1,82 @@
+"""device_discovery — 设备发现平面 (网络 DTO + 设备池 + 发现逻辑).
+
+BF006 迁入 (R021):
+  - network 3 模块 (protocol / endpoint / device_candidates, 字节级零修改,
+    自旧 network 子包)
+  - device_pool (认身份不认地址)
+  - discovery/ 5 模块 (USB / LAN / 手动 / 交叉识别)
+  - AD-B9: DeviceUnreachable 下沉 (直继承 Exception 脱离协议层基类反向依赖;
+    BF007 删旧定义 + 改正向 import)
+
+零业务依赖: 不 import 旧 network 子包 / host4 gmacro / launcher /
+协议层 client / mcp plane. 纯 stdlib + 同包相对 import, 可独立 pip install.
+"""
+from .device_candidates import (
+    CommandRunner,
+    ConnectedDeviceEndpoint,
+    ConnectedDeviceInventory,
+    IosDeviceCandidate,
+    discover_connected_device_endpoints,
+    discover_connected_device_inventory,
+    discover_connected_devices,
+    discover_ios_flutter_candidates,
+)
+from .device_pool import DevicePool, DeviceRecord
+from .discovery.cross_identify import CrossIdentify
+from .discovery.lan_scan import LanCandidate, LanScan
+from .discovery.manual_registry import ManualRegistry
+from .discovery.usb_identity import UsbCandidate, UsbIdentity
+from .discovery.vpn_immune import VpnImmune
+from .endpoint import (
+    Endpoint,
+    UrlOpen,
+    default_urlopen,
+    discover_default_endpoints,
+    discover_targets,
+    local_ipv4_addresses,
+    probe_hello,
+)
+from .protocol import (
+    ControllerProfile,
+    DebugEvent,
+    DeviceUnreachable,
+    NetworkState,
+    NetworkTarget,
+)
+
+__all__ = [
+    # protocol (BF006 network DTO + AD-B9 DeviceUnreachable)
+    "NetworkTarget",
+    "NetworkState",
+    "DebugEvent",
+    "ControllerProfile",
+    "DeviceUnreachable",
+    # endpoint (BF006 network probe)
+    "Endpoint",
+    "UrlOpen",
+    "default_urlopen",
+    "probe_hello",
+    "discover_targets",
+    "discover_default_endpoints",
+    "local_ipv4_addresses",
+    # device_candidates (BF006 connected-device inventory)
+    "CommandRunner",
+    "ConnectedDeviceEndpoint",
+    "ConnectedDeviceInventory",
+    "IosDeviceCandidate",
+    "discover_connected_device_endpoints",
+    "discover_connected_device_inventory",
+    "discover_connected_devices",
+    "discover_ios_flutter_candidates",
+    # device_pool (BF006 认身份不认地址)
+    "DevicePool",
+    "DeviceRecord",
+    # discovery (BF006 USB/LAN/手动/交叉)
+    "LanScan",
+    "LanCandidate",
+    "UsbIdentity",
+    "UsbCandidate",
+    "ManualRegistry",
+    "VpnImmune",
+    "CrossIdentify",
+]

debug_control_plane-0.1.0/debug_control_plane/device_discovery/device_candidates.py

@@ -0,0 +1,326 @@
+"""Connected device endpoint discovery for Network mode."""
+
+from __future__ import annotations
+
+import json
+import re
+import subprocess
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+from .endpoint import Endpoint
+
+CommandRunner = Callable[[list[str], float], str]
+
+
+@dataclass(frozen=True)
+class ConnectedDeviceEndpoint:
+    endpoint: Endpoint
+    label: str
+    platform: str
+
+
+@dataclass(frozen=True)
+class ConnectedDeviceInventory:
+    device_id: str
+    label: str
+    platform: str
+    state: str
+    endpoint: Endpoint | None = None
+
+
+def discover_connected_device_endpoints(
+    *,
+    default_port: int = 18080,
+    run_command: CommandRunner | None = None,
+) -> list[Endpoint]:
+    devices = discover_connected_devices(
+        default_port=default_port,
+        run_command=run_command,
+    )
+    return [device.endpoint for device in devices]
+
+
+def discover_connected_device_inventory(
+    *,
+    default_port: int = 18080,
+    run_command: CommandRunner | None = None,
+) -> list[ConnectedDeviceInventory]:
+    runner = run_command or _run_command
+    devices: list[ConnectedDeviceInventory] = []
+
+    for device in _android_connected_devices(runner, default_port):
+        devices.append(
+            ConnectedDeviceInventory(
+                device_id=f"{device.endpoint.host}:{device.endpoint.port}",
+                label=device.label,
+                platform="android",
+                state="connected",
+                endpoint=device.endpoint,
+            )
+        )
+
+    for device in _ios_inventory_devices(runner):
+        if not any(
+            existing.platform == "ios" and existing.label == device.label
+            for existing in devices
+        ):
+            devices.append(device)
+
+    return devices
+
+
+def discover_connected_devices(
+    *,
+    default_port: int = 18080,
+    run_command: CommandRunner | None = None,
+) -> list[ConnectedDeviceEndpoint]:
+    runner = run_command or _run_command
+    devices: list[ConnectedDeviceEndpoint] = []
+    seen: set[tuple[str, int]] = set()
+
+    for device in _android_connected_devices(runner, default_port):
+        key = (device.endpoint.host, device.endpoint.port)
+        if key not in seen:
+            seen.add(key)
+            devices.append(device)
+
+    return devices
+
+
+def _android_connected_devices(
+    run_command: CommandRunner,
+    default_port: int,
+) -> list[ConnectedDeviceEndpoint]:
+    try:
+        output = run_command(["adb", "devices", "-l"], 5.0)
+    except OSError:
+        return []
+    devices: list[ConnectedDeviceEndpoint] = []
+    for line in output.splitlines()[1:]:
+        parts = line.split()
+        if len(parts) < 2 or parts[1] != "device":
+            continue
+        serial = parts[0]
+        ip = _android_device_ip(serial, run_command)
+        if ip is None:
+            continue
+        model = _metadata_value(parts, "model") or serial
+        devices.append(
+            ConnectedDeviceEndpoint(
+                endpoint=Endpoint(ip, default_port),
+                label=model,
+                platform="android",
+            )
+        )
+    return devices
+
+
+def _android_device_ip(serial: str, run_command: CommandRunner) -> str | None:
+    try:
+        output = run_command(["adb", "-s", serial, "shell", "ip", "route", "get", "1.1.1.1"], 5.0)
+    except OSError:
+        return None
+    match = re.search(r"\bsrc\s+(\d+\.\d+\.\d+\.\d+)\b", output)
+    return match.group(1) if match else None
+
+
+def _ios_inventory_devices(run_command: CommandRunner) -> list[ConnectedDeviceInventory]:
+    try:
+        output = run_command(["xcrun", "devicectl", "list", "devices"], 8.0)
+    except OSError:
+        return []
+    devices: list[ConnectedDeviceInventory] = []
+    for line in output.splitlines():
+        if ".coredevice.local" not in line:
+            continue
+        parsed = _parse_ios_device_line(line)
+        if parsed is None:
+            continue
+        label, identifier, state = parsed
+        if state != "connected":
+            continue
+        devices.append(
+            ConnectedDeviceInventory(
+                device_id=identifier,
+                label=label,
+                platform="ios",
+                state=state,
+                endpoint=None,
+            )
+        )
+    return devices
+
+
+def _parse_ios_device_line(line: str) -> tuple[str, str, str] | None:
+    hostname = _extract_coredevice_hostname(line)
+    if hostname is None:
+        return None
+    prefix, suffix = line.split(hostname, 1)
+    parts = suffix.split()
+    if len(parts) < 2:
+        return None
+    label = prefix.strip() or hostname
+    identifier = parts[0]
+    state = parts[1]
+    return label, identifier, state
+
+
+def _is_available_ios_device(line: str) -> bool:
+    return " connected " in f" {line} "
+
+
+def _extract_coredevice_hostname(line: str) -> str | None:
+    match = re.search(r"([\w.-]+\.coredevice\.local)", line)
+    return match.group(1) if match else None
+
+
+def _metadata_value(parts: list[str], key: str) -> str | None:
+    prefix = f"{key}:"
+    for part in parts:
+        if part.startswith(prefix):
+            return part[len(prefix) :]
+    return None
+
+
+def _run_command(command: list[str], timeout: float) -> str:
+    try:
+        result = subprocess.run(
+            command,
+            check=False,
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+        )
+    except subprocess.TimeoutExpired as error:
+        output = error.stdout or ""
+        if isinstance(output, bytes):
+            return output.decode("utf-8", errors="replace")
+        return output
+    if result.returncode != 0:
+        raise OSError(result.stderr.strip() or f"command failed: {' '.join(command)}")
+    return result.stdout
+
+
+# ---------------------------------------------------------------------------
+# R020-BF002: iOS device discovery via `flutter devices` (USB identity source).
+#
+# 新增独立函数,不改旧 `_ios_inventory_devices`(xcrun devicectl 路径,保留供 GUI
+# 兼容)。原因:iPhone X 真机 iOS 16,`xcrun devicectl` 永远 unavailable
+# (memory ios16-device-devicectl-pitfall),`flutter devices` 是可用路径。
+#
+# 设计见 .dev-flow/R020/analysis/2026-08-08--mcp-bridge-device-discovery-backend.md
+#   §2「iOS 发现不可用」+ analysis iOS/Android §USB 通道
+# ---------------------------------------------------------------------------
+
+
+# macOS 上 flutter 不在默认 PATH,显式回退路径(防止 mcp_debug_bridge 进程环境没装 fvm)
+_FLUTTER_CANDIDATES: tuple[str, ...] = (
+    "flutter",
+    "/usr/local/bin/flutter",
+    "/opt/homebrew/bin/flutter",
+    "fvm",
+)
+
+
+@dataclass(frozen=True)
+class IosDeviceCandidate:
+    """iOS 设备身份候选(来自 `flutter devices` 解析)。
+
+    供 R020 mcp_debug_bridge/discovery USB 身份源消费(BF004 UsbCandidate 用此)。
+    `device_id` = usbmuxd id(如 3992f440...,稳定身份源);
+    `model` = 机型显示名(iPhone X / iPhone 14 Pro 等,弱唯一供交叉识别用)。
+    """
+
+    device_id: str            # usbmuxd id (`flutter devices --machine` id 字段)
+    model: str                # 机型 (`flutter devices --machine` name 字段)
+    platform: str = "ios"
+
+
+def discover_ios_flutter_candidates(
+    *,
+    run_command: CommandRunner | None = None,
+) -> list[IosDeviceCandidate]:
+    """iOS 设备身份候选(经 `flutter devices`,不调 devicectl)。
+
+    R020-BF002 落地:替代 iOS 16 不可用的 `_ios_inventory_devices`(devicectl 路径)。
+    解析 `flutter devices --machine` 的 JSON 输出,只取真机(emulator/simulator 排除)。
+
+    Args:
+        run_command: 可注入命令执行器(默认 _run_command),便于 mock 测试
+
+    Returns:
+        IosDeviceCandidate 列表(空列表表示无真机或 flutter 不可用)
+    """
+    runner = run_command or _run_command
+    output = _try_flutter_devices_machine(runner)
+    if output is None:
+        return []
+    return _parse_flutter_devices_machine(output)
+
+
+def _try_flutter_devices_machine(run_command: CommandRunner) -> str | None:
+    """尝试多个 flutter 候选命令,返回首个成功的 `flutter devices --machine` 输出。
+
+    所有候选都失败(或 _FLUTTER_CANDIDATES 为空)→ None。
+    """
+    for flutter in _FLUTTER_CANDIDATES:
+        try:
+            return run_command([flutter, "devices", "--machine"], 8.0)
+        except OSError:
+            continue
+    return None
+
+
+def _parse_flutter_devices_machine(output: str) -> list[IosDeviceCandidate]:
+    """解析 `flutter devices --machine` JSON。
+
+    `flutter devices --machine` 输出 JSON 数组,元素结构(节选):
+      {
+        "id": "<usbmuxd id 或 emulator-id>",
+        "name": "iPhone X",
+        "targetPlatform": "ios",
+        "emulator": false,
+        "category": "mobile",
+        "platform": "ios" / "android-ios",
+        ...
+      }
+
+    真机筛选:`emulator == false` 且 `targetPlatform`/`platform` 含 "ios"。
+    """
+    try:
+        data = json.loads(output)
+    except (json.JSONDecodeError, ValueError):
+        return []
+    if not isinstance(data, list):
+        return []
+    candidates: list[IosDeviceCandidate] = []
+    for entry in data:
+        if not isinstance(entry, dict):
+            continue
+        if not _is_ios_physical_device(entry):
+            continue
+        device_id = entry.get("id")
+        model = entry.get("name") or entry.get("model")
+        if not isinstance(device_id, str) or not device_id:
+            continue
+        if not isinstance(model, str):
+            model = device_id
+        candidates.append(IosDeviceCandidate(device_id=device_id, model=model))
+    return candidates
+
+
+def _is_ios_physical_device(entry: dict[str, Any]) -> bool:
+    """判断 flutter devices 条目是否 iOS 物理真机(排除 simulator/emulator)。"""
+    is_emulator = entry.get("emulator")
+    if is_emulator is True:
+        return False
+    platform = str(entry.get("targetPlatform") or entry.get("platform") or "")
+    if "ios" not in platform:
+        return False
+    # simulator 设备类别/id 形如 "iOS Simulator" / "ios-simulator"
+    category = str(entry.get("category") or "")
+    if "simulator" in category.lower():
+        return False
+    return True