feat: publish workphone SDK deployment and API docs

sdk/agent/hawk/network.py

@@ -0,0 +1,109 @@
+"""
+Hawk 网络层 - 仅做合法网络恢复：开 WiFi、打开设置、连接已保存网络、重试
+
+不包含且永不包含：破解密码、未授权访问、绕过认证等任何违规操作。
+若设备上无可用已保存网络，仅打开系统 WiFi 设置供用户手动连接或输入密码。
+"""
+
+import logging
+import time
+from typing import Dict, Any
+
+logger = logging.getLogger(__name__)
+
+
+def _shell_out(device, cmd: str) -> str:
+    """执行 shell 并返回输出字符串（兼容 u2 的 AdbDevice）。"""
+    try:
+        r = device.shell(cmd)
+        return (getattr(r, "output", None) or str(r) or "").strip()
+    except Exception:
+        return ""
+
+
+def is_network_available(device) -> bool:
+    """检测当前是否有网络（ping 或 shell 查连接状态）。"""
+    try:
+        out = _shell_out(device, "ping -c 1 -W 2 8.8.8.8 2>/dev/null && echo ok || echo fail")
+        if out and "ok" in out:
+            return True
+        out = _shell_out(device, "dumpsys wifi | grep -i 'mWifiInfo' | head -1")
+        return "SSID:" in out
+    except Exception as e:
+        logger.debug(f"is_network_available: {e}")
+        return False
+
+
+def try_reconnect_network(device, max_steps: int = 5) -> Dict[str, Any]:
+    """
+    在设备上尝试恢复网络（仅合法操作）：
+    1. 开 WiFi（若被关）
+    2. 打开系统「网络/WiFi」设置页，便于连接已保存网络或用户手动输入
+    3. 可选：通过 UI 点击「已保存网络」进行连接（不输入新密码、不破解）
+    4. 等待后再次检测网络
+
+    device: uiautomator2 设备对象（可为 None，此时只返回建议）
+    """
+    result = {"success": False, "message": "", "steps": []}
+
+    if device is None:
+        result["message"] = "无设备句柄，无法执行网络恢复"
+        return result
+
+    try:
+        # Step 1: 尝试通过 shell 开启 WiFi（合法系统 API）
+        try:
+            device.shell("svc wifi enable 2>/dev/null")
+            result["steps"].append("svc wifi enable")
+            time.sleep(2)
+        except Exception as e:
+            result["steps"].append(f"svc wifi enable 失败: {e}")
+
+        if is_network_available(device):
+            result["success"] = True
+            result["message"] = "WiFi 已开启且检测到网络"
+            return result
+
+        # Step 2: 打开系统设置中的网络/WiFi 页面，供用户连接或输入密码
+        try:
+            device.app_start("com.android.settings")
+            time.sleep(1.5)
+            # 尝试进入 WLAN / 网络 / WiFi 设置
+            for text in ["WLAN", "网络", "Wi‑Fi", "WiFi", "互联网"]:
+                try:
+                    if device(text=text).wait(timeout=2):
+                        device(text=text).click()
+                        result["steps"].append(f"打开设置并点击 {text}")
+                        break
+                except Exception:
+                    continue
+            time.sleep(2)
+        except Exception as e:
+            result["steps"].append(f"打开设置失败: {e}")
+
+        # Step 3: 若有「已保存」或「已知网络」列表，可点击第一个尝试连接（仅限已保存，不涉及破解）
+        try:
+            for hint in ["已保存", "已知网络", "已连接", "连接"]:
+                if device(textContains=hint).wait(timeout=1.5):
+                    device(textContains=hint).click()
+                    result["steps"].append(f"点击包含「{hint}」的项")
+                    time.sleep(2)
+                    break
+        except Exception:
+            pass
+
+        # Step 4: 再次检测
+        time.sleep(2)
+        if is_network_available(device):
+            result["success"] = True
+            result["message"] = "网络已恢复（已连接或已打开设置）"
+        else:
+            result["message"] = "已打开 WiFi 设置，请在本机选择已保存网络或手动输入密码连接"
+            result["steps"].append("建议用户在设置页手动连接")
+
+    except Exception as e:
+        logger.exception("try_reconnect_network 异常")
+        result["message"] = str(e)
+        result["steps"].append(f"异常: {e}")
+
+    return result