Quellcode durchsuchen

feat(DesktopClient): 新增桌面客户端窗口后端(后台截图/窗口消息输入/PID 绑定)

- 新增 DesktopWindow mixin(module/device/method/desktop_impl.py),集中承载桌面
  客户端的窗口枚举/绑定/截图/输入实现,Handle 与 Window 各继承一份
- 桌面分支按 PID 定位窗口;后台截图走 GetWindowDC+BitBlt,输入走 PostMessage/SendMessage
- 新增 dev_tools/bind_desktop_window.py,一键绑定或按序号选择客户端窗口 PID
- connection_attr 新增 is_desktop(serial == 'desktop'),桌面模式跳过 adb server 拉起
- cBezier 抽出 human_track:桌面与模拟器两条滑动路径共用同一套拟人轨迹,
  顺带修掉纯垂直/零长度滑动原本会抛的 ValueError 与 ZeroDivisionError
User vor 1 Monat
Ursprung
Commit
d0bc419a41

+ 118 - 0
dev_tools/bind_desktop_window.py

@@ -0,0 +1,118 @@
+# -*- coding: utf-8 -*-
+"""
+桌面客户端窗口 PID 绑定工具
+============================
+把"阴阳师-网易游戏"桌面客户端窗口的 PID 写入指定 OAS 配置,并切到桌面模式
+(serial='desktop'、handle=PID、screenshot_method='window_background'、control_method='window_message')。
+
+用法:
+    ./toolkit/python.exe -m dev_tools.bind_desktop_window --config oas1 --pick
+    ./toolkit/python.exe -m dev_tools.bind_desktop_window --config oas1 --list
+    ./toolkit/python.exe -m dev_tools.bind_desktop_window --config oas1 --pid 4242
+"""
+import argparse
+import ctypes
+import sys
+from ctypes import wintypes
+
+import win32gui
+import win32process
+
+from module.config.config import Config
+from module.logger import logger
+
+DESKTOP_WINDOW_TITLES = ('阴阳师-网易游戏', '阴阳师-MuMu模拟器专版')
+
+
+def list_desktop_windows() -> list:
+    """枚举所有桌面客户端窗口,返回 [(title, hwnd, pid)]。"""
+    def enum_cb(hwnd, param):
+        param.append(hwnd)
+        return True
+
+    windows = []
+    win32gui.EnumWindows(enum_cb, windows)
+    result = []
+    for hwnd in windows:
+        title = win32gui.GetWindowText(hwnd)
+        if title in DESKTOP_WINDOW_TITLES:
+            pid = win32process.GetWindowThreadProcessId(hwnd)[1]
+            result.append((title, hwnd, pid))
+    return result
+
+
+def pick_window_under_cursor() -> int:
+    """返回鼠标光标所指窗口的句柄;无窗口返回 0。"""
+    user32 = ctypes.WinDLL('user32', use_last_error=True)
+
+    class POINT(ctypes.Structure):
+        _fields_ = [('x', ctypes.c_long), ('y', ctypes.c_long)]
+
+    point = POINT()
+    user32.GetCursorPos.argtypes = [ctypes.POINTER(POINT)]
+    user32.GetCursorPos.restype = wintypes.BOOL
+    if not user32.GetCursorPos(ctypes.byref(point)):
+        return 0
+    user32.WindowFromPoint.argtypes = [POINT]
+    user32.WindowFromPoint.restype = wintypes.HWND
+    return int(user32.WindowFromPoint(point)) or 0
+
+
+def bind_pid_to_config(config_name: str, pid: int) -> None:
+    """把 PID 写入指定配置,并切到桌面模式。"""
+    config = Config(config_name)
+    config.script.device.serial = 'desktop'
+    config.script.device.handle = str(pid)
+    # PrintWindow 对客户端的 DirectX 渲染窗口返回纯黑,桌面模式统一用 BitBlt
+    config.script.device.screenshot_method = 'window_background'
+    config.script.device.control_method = 'window_message'
+    config.save()
+    logger.info(f'Config [{config_name}] bound to desktop client PID={pid}')
+    # 绑定后检测并调整窗口客户区到 1280x720,保证识别 1:1
+    from module.device.handle import Handle
+    h = Handle(config)
+    h.desktop_window_set_size()
+
+
+def main():
+    parser = argparse.ArgumentParser(description='绑定桌面客户端窗口 PID 到 OAS 配置')
+    parser.add_argument('--config', required=True, help='配置实例名,如 oas1')
+    group = parser.add_mutually_exclusive_group(required=True)
+    group.add_argument('--pick', action='store_true', help='鼠标点选窗口(光标所指)')
+    group.add_argument('--list', action='store_true', help='从窗口列表按序号选择')
+    group.add_argument('--pid', type=int, help='直接指定 PID')
+    args = parser.parse_args()
+
+    if args.pid:
+        bind_pid_to_config(args.config, args.pid)
+        return
+
+    if args.pick:
+        input('请把鼠标移到目标游戏窗口上,然后按回车…')
+        hwnd = pick_window_under_cursor()
+        if not hwnd:
+            logger.error('未获取到光标下的窗口')
+            sys.exit(1)
+        title = win32gui.GetWindowText(hwnd)
+        if title not in DESKTOP_WINDOW_TITLES:
+            logger.error(f'光标下的窗口不是桌面客户端(标题: "{title}"),'
+                         f'请把鼠标移到游戏画面实体区域上重试')
+            sys.exit(1)
+        pid = win32process.GetWindowThreadProcessId(hwnd)[1]
+        bind_pid_to_config(args.config, pid)
+        return
+
+    windows = list_desktop_windows()
+    if not windows:
+        logger.error('未找到桌面客户端窗口,请先启动游戏')
+        sys.exit(1)
+    for i, (title, hwnd, pid) in enumerate(windows):
+        print(f'[{i}] {title}  PID={pid}  HWND=0x{hwnd:X}')
+    choice = input('请输入要绑定的序号: ')
+    idx = int(choice)
+    _, _, pid = windows[idx]
+    bind_pid_to_config(args.config, pid)
+
+
+if __name__ == '__main__':
+    main()

+ 31 - 0
module/base/cBezier.py

@@ -156,5 +156,36 @@ class BezierTrajectory:
         # return {"trackArray": np.array(s), "P": w}
         # return {"trackArray": np.array(s), "P": w}
         return [[int(s[0]), int(s[1])] for s in s]
         return [[int(s[0]), int(s[1])] for s in s]
 
 
+
+def human_track(start, end, interval=10):
+    """
+    生成 start → end 的拟人贝塞尔轨迹点,相邻两点间隔约 interval 像素。
+    轨迹阶数、波动幅度、速度分布随机,供模拟器滑动与桌面客户端滑动共用。
+
+    两种退化输入单独处理:起点终点 x 相同时贝塞尔以 x 做参数化会除零,
+    纯垂直移动退化为直线插值;距离不足以生成一个点时直接返回终点,
+    避免调用方拿到空轨迹再去取 [0]。
+    """
+    number_list = int(math.dist(start, end) / (1 * interval))
+    if number_list < 1:
+        return [tuple(end)]
+    if start[0] == end[0]:
+        dy = end[1] - start[1]
+        return [[int(start[0]), int(start[1] + dy * i / number_list)]
+                for i in range(1, number_list + 1)]
+    le = random.randint(2, 4)
+    deviation = random.randint(20, 40)
+    obbs_type = random.random()
+    # 0.8 概率先快中间慢后面快,0.1 先快后慢,0.1 先慢后快
+    if 0 < obbs_type <= 0.8:
+        b_type = 3
+    elif obbs_type < 0.9:
+        b_type = 2
+    else:
+        b_type = 1
+    return BezierTrajectory.trackArray(start=list(start), end=list(end), numberList=number_list,
+                                       le=le, deviation=deviation, bias=0.5, type=b_type,
+                                       cbb=0, yhh=20)
+
 # print(BezierTrajectory.trackArray(start=[0, 0], end=[100, 100], numberList=50, le=2,
 # print(BezierTrajectory.trackArray(start=[0, 0], end=[100, 100], numberList=50, le=2,
 #                     deviation=0, bias=0.5, type=0, cbb=0, yhh=10))
 #                     deviation=0, bias=0.5, type=0, cbb=0, yhh=10))

+ 13 - 2
module/device/connection_attr.py

@@ -60,8 +60,10 @@ class ConnectionAttr:
                 if 'eri' in k[0].split('_')[-1]:
                 if 'eri' in k[0].split('_')[-1]:
                     print(k, v)
                     print(k, v)
                     su.__setattr__(k[0], chr(8) + v)
                     su.__setattr__(k[0], chr(8) + v)
-        # Cache adb_client
-        _ = self.adb_client
+        # 桌面客户端模式不需要 adb,跳过 adb server 拉起
+        if not self.is_desktop:
+            # Cache adb_client
+            _ = self.adb_client
 
 
         # Parse custom serial
         # Parse custom serial
         # self.serial = str(self.config.Emulator_Serial)
         # self.serial = str(self.config.Emulator_Serial)
@@ -127,6 +129,15 @@ class ConnectionAttr:
     def is_emulator(self):
     def is_emulator(self):
         return self.serial.startswith('emulator-') or self.serial.startswith('127.0.0.1:')
         return self.serial.startswith('emulator-') or self.serial.startswith('127.0.0.1:')
 
 
+    @cached_property
+    def is_desktop(self):
+        """桌面客户端模式:serial 配置为 'desktop'。
+
+        不做异常兜底:读不到配置说明 Device 构造链没走到 ConnectionAttr,
+        此时静默返回 False 会把桌面模式当成模拟器模式继续跑,报错指向完全无关的地方。
+        """
+        return str(self.config.script.device.serial) == 'desktop'
+
     @cached_property
     @cached_property
     def is_network_device(self):
     def is_network_device(self):
         return bool(re.match(r'\d+\.\d+\.\d+\.\d+:\d+', self.serial))
         return bool(re.match(r'\d+\.\d+\.\d+\.\d+:\d+', self.serial))

+ 21 - 1
module/device/handle.py

@@ -18,6 +18,7 @@ from win32con import (SRCCOPY, DESKTOPHORZRES, DESKTOPVERTRES, WM_LBUTTONUP,
                       WM_LBUTTONDOWN, WM_ACTIVATE, WA_ACTIVE, MK_LBUTTON,
                       WM_LBUTTONDOWN, WM_ACTIVATE, WA_ACTIVE, MK_LBUTTON,
                       WM_NCHITTEST, WM_SETCURSOR, HTCLIENT, WM_MOUSEMOVE)
                       WM_NCHITTEST, WM_SETCURSOR, HTCLIENT, WM_MOUSEMOVE)
 from module.config.config import Config
 from module.config.config import Config
+from module.device.method.desktop_impl import DesktopWindow, DESKTOP_WINDOW_TITLES
 from module.logger import logger
 from module.logger import logger
 
 
 
 
@@ -127,7 +128,7 @@ class EmulatorFamily(Enum):
 """""
 """""
 # **********************************************************************************************************************
 # **********************************************************************************************************************
 
 
-class Handle:
+class Handle(DesktopWindow):
     emulator_list = ['MuMu12',
     emulator_list = ['MuMu12',
                      'MuMu',
                      'MuMu',
                      '雷电',
                      '雷电',
@@ -157,6 +158,8 @@ class Handle:
         'bluestacks_family': ['root_handle_title']
         'bluestacks_family': ['root_handle_title']
     }
     }
     config: Config = None
     config: Config = None
+    is_desktop_window: bool = False
+    """是否为桌面客户端模式(serial='desktop'),桌面分支统一用此标志隔离"""
 
 
     def __init__(self, config) -> None:
     def __init__(self, config) -> None:
         """
         """
@@ -173,6 +176,18 @@ class Handle:
             logger.info('Handle is empty, oas not use handle')
             logger.info('Handle is empty, oas not use handle')
             return
             return
 
 
+        # 桌面客户端模式:按 PID 定位窗口,跳过模拟器窗口树逻辑
+        if self.config.script.device.serial == 'desktop':
+            self.root_handle_title = ''
+            self.root_handle_num = 0
+            self.root_handle = self.config.script.device.handle
+            logger.info(f'Desktop handle PID is {self.root_handle}')
+            self.root_handle_num = self.find_desktop_window_by_pid(self.root_handle)
+            self.root_handle_title = DESKTOP_WINDOW_TITLES[0]
+            self.is_desktop_window = True
+            logger.info(f'Desktop client window found: title={self.root_handle_title}, hwnd={self.root_handle_num}')
+            return
+
         # 获取根的句柄
         # 获取根的句柄
         self.root_handle_title = ''
         self.root_handle_title = ''
         self.root_handle_num = 0
         self.root_handle_num = 0
@@ -347,6 +362,8 @@ class Handle:
         截屏的句柄其实并不是根句柄
         截屏的句柄其实并不是根句柄
         :return:  出错返回None
         :return:  出错返回None
         """
         """
+        if getattr(self, 'is_desktop_window', False):
+            return self.root_handle_num
         if self.emulator_family == EmulatorFamily.FAMILY_MUMU:
         if self.emulator_family == EmulatorFamily.FAMILY_MUMU:
             # 使用正则匹配12 来判定是不是mumu12这并不是一个好的方法
             # 使用正则匹配12 来判定是不是mumu12这并不是一个好的方法
             name = self.root_node.children[0].name
             name = self.root_node.children[0].name
@@ -390,6 +407,9 @@ class Handle:
         2023.7.1 在高缩放的设备上应该输出1280X720
         2023.7.1 在高缩放的设备上应该输出1280X720
         :return:
         :return:
         """
         """
+        if getattr(self, 'is_desktop_window', False):
+            # 桌面模式固定输出 1280x720(物理目标,与资产 1:1),位图由截图方法缩放得到
+            return 1280, 720
         winRect = GetWindowRect(self.screenshot_handle_num)
         winRect = GetWindowRect(self.screenshot_handle_num)
         scale_rate = window_scale_rate()
         scale_rate = window_scale_rate()
         width_before: int = winRect[2] - winRect[0]  # 右x-左x
         width_before: int = winRect[2] - winRect[0]  # 右x-左x

+ 990 - 0
module/device/method/desktop_impl.py

@@ -0,0 +1,990 @@
+# This Python file uses the following encoding: utf-8
+"""桌面客户端(阴阳师 PC 版)窗口控制实现。
+
+从 module/device/handle.py 拆出:桌面模式与模拟器模式除"窗口句柄怎么拿到"外没有
+任何共享逻辑,两者同处一个类会把 handle.py 撑到 1300+ 行,也让"移植到底动没动
+模拟器基线"难以一眼看清。这里用纯 mixin ``DesktopWindow`` 承载全部桌面分支
+(``Handle`` 继承它),handle.py 只保留模拟器逻辑与少量桌面内联判断。
+
+边界约定:
+- ``DesktopWindow`` 不定义 ``__init__``,全部实例状态由 ``Handle.__init__`` 的
+  桌面分支设置;类内方法名与 Handle 模拟器方法无重名,MRO 无歧义;
+- 本模块不反向依赖 handle.py,是叶子模块,无循环导入;
+- 模块级常量与 helper(``list_desktop_windows`` / ``desktop_window_option`` /
+  ``desktop_option2pid`` / ``dpi_awareness`` 等)一并住在这里,外部调用方直接
+  从本模块导入,不经 handle.py 转出——避免"补丁打在转出别名上静默失效"。
+"""
+
+import os
+import re
+import subprocess
+import time
+import ctypes
+from ctypes import c_long, byref, POINTER, Structure, wintypes
+
+from contextlib import contextmanager
+from pathlib import Path
+
+from win32api import SendMessage
+from win32process import GetWindowThreadProcessId
+from win32gui import (GetWindowText, EnumWindows, GetWindowRect, IsWindow,
+                      GetClientRect, ClientToScreen, GetWindowLong,
+                      SetWindowPos, GetClassName, IsIconic, ShowWindow)
+from win32con import (WM_KEYDOWN, WM_KEYUP, VK_RETURN, GWL_STYLE, GWL_EXSTYLE,
+                      HWND_TOP, SWP_NOMOVE, SWP_SHOWWINDOW, SW_RESTORE)
+
+from module.base.decorator import del_cached_property
+from module.exception import EmulatorNotRunningError
+from module.logger import logger
+
+
+# 桌面客户端窗口标题(官方桌面版,多开共用同一标题)
+DESKTOP_WINDOW_TITLES = ('阴阳师-网易游戏', '阴阳师-MuMu模拟器专版')
+# 「进程活着但窗口还没就绪」时的等待上限(秒)与轮询间隔。空窗期有两种:客户端
+# 启动期还没出窗口、确认 MPay 弹窗后销毁登录界面重建主窗口的那几秒。这段等待只
+# 轮询窗口,绝不重新启动进程——把「窗口暂时不在」当成「客户端没在运行」会拉起
+# 多余实例(单实例语义下用户正在用的那个会被顶掉),并把配置里的 handle 覆盖成新实例
+DESKTOP_WINDOW_READY_WAIT = 15
+DESKTOP_WINDOW_READY_POLL_INTERVAL = 0.5
+
+# 网易 MPay 账号登录弹窗的窗口类名。它是与游戏主窗口同 PID 的独立顶层窗口
+# (DirectUI 绘制,无子控件),不在游戏渲染面内,因此主窗口 BitBlt 截不到它,
+# 也无法用图像识别处理,只能按类名单独定位并注入消息。
+DESKTOP_LOGIN_POPUP_CLASS = 'MPAY_LOGIN'
+
+# 调整窗口尺寸时撞上客户端重建窗口的重试轮数与间隔(秒)。客户端确认登录弹窗后销毁
+# 登录界面、重建游戏主窗口,实测这段空窗期在几百毫秒到数秒之间,6 轮 × 1s 足够覆盖
+DESKTOP_RESIZE_ATTEMPTS = 6
+DESKTOP_RESIZE_RETRY_INTERVAL = 1.0
+# 关闭桌面客户端的强杀轮数。TerminateProcess 可能因权限被拒(实测本机出现过
+# (5, '拒绝访问。')),也可能进程正在退出但还没消失,因此杀完必须验证进程真的没了,
+# 没死就再杀一轮,而不是发完指令就当成功
+DESKTOP_KILL_ATTEMPTS = 3
+DESKTOP_KILL_POLL_INTERVAL = 0.5
+
+# DPI_AWARENESS_CONTEXT_PER_MONITOR_AWARE_V2,SetThreadDpiAwarenessContext 的入参
+_PER_MONITOR_AWARE_V2 = ctypes.c_void_p(-4)
+
+# 桌面客户端运行期间强制保持显示器常亮:桌面模式截图走 BitBlt,依赖 DWM 合成,
+# 屏幕一旦因电源超时关闭,DWM 停止合成,BitBlt 只能返回静止黑帧,登录循环会因此
+# 死等 300s 超时。在客户端启动时开启、关闭时清除,只锁客户端生命周期,不影响
+# OAS 空闲时用户正常让屏幕休眠。
+ES_CONTINUOUS = 0x80000000
+ES_DISPLAY_REQUIRED = 0x00000002
+
+
+@contextmanager
+def dpi_awareness():
+    """临时把当前线程切到 Per-Monitor V2 DPI 感知,退出时恢复原上下文。
+
+    OAS 进程自身未声明 DPI 感知,GDI 调用默认被系统虚拟化成逻辑像素:125% 缩放下
+    物理 1280x720 的客户区只报 1024x576,BitBlt 也只能取到画面左上角那一块(右侧
+    侧边栏与底部菜单栏直接丢失)。桌面客户端进程是 Per-Monitor DPI 感知、按物理
+    像素原生渲染,因此桌面分支的窗口测量与截图必须在感知上下文里做才能拿到完整的
+    物理像素画面。用线程级而非进程级,是为了不影响模拟器直控路径既有的逻辑像素假设。
+    """
+    user32 = ctypes.windll.user32
+    previous = None
+    try:
+        previous = user32.SetThreadDpiAwarenessContext(_PER_MONITOR_AWARE_V2)
+    except AttributeError:
+        # Windows 10 1607 以前没有该 API,退化为原有逻辑像素行为
+        pass
+    try:
+        yield
+    finally:
+        if previous:
+            user32.SetThreadDpiAwarenessContext(previous)
+
+
+def desktop_keep_screen_on(enable: bool) -> None:
+    """按桌面客户端生命周期开关「强制保持显示器常亮」。
+
+    SetThreadExecutionState 是线程级状态:ES_CONTINUOUS 保持该线程的请求,直到
+    再次调用清除。OAS worker 的任务在同一长驻线程内启停客户端,因此这里设置即可。
+
+    注意 ES_DISPLAY_REQUIRED 只「阻止未来关闭」,屏幕若已因电源超时熄灭,必须先用
+    SC_MONITORPOWER(-1) 广播把显示器物理点亮,否则 BitBlt 仍返回黑帧。
+    """
+    if enable:
+        # 物理点亮:SC_MONITORPOWER(-1) 单独发消息对部分显示器/驱动不触发硬件唤醒
+        # (实测只发它屏幕仍黑),必须再模拟一次无害键盘输入与鼠标移动,产生真实
+        # 输入事件才能真正点亮。VK_F15(0x7E) 无副作用,不会干扰游戏。
+        try:
+            # 必须用 SendMessageTimeoutW 而不是 SendMessageW:目标是
+            # HWND_BROADCAST(0xFFFF),SendMessageW 会同步等系统里每一个顶层窗口
+            # 处理完才返回,只要有一个窗口消息循环繁忙或无响应就永久阻塞调用线程
+            # (实测 pytest 里这一行挂死 26 分钟不返回,生产上等于 worker 线程卡住)。
+            # SMTO_ABORTIFHUNG(0x0002) 遇到无响应窗口直接放弃,1000ms 上限兜底。
+            ctypes.windll.user32.SendMessageTimeoutW(
+                0xFFFF, 0x0111, 0xF170, -1, 0x0002, 1000, None)
+        except Exception as e:
+            logger.warning(f'SC_MONITORPOWER wake failed: {e}')
+        try:
+            user32 = ctypes.windll.user32
+            user32.keybd_event(0x7E, 0, 0, 0)
+            user32.keybd_event(0x7E, 0, 2, 0)
+            user32.SetCursorPos(400, 300)
+        except Exception as e:
+            logger.warning(f'wake input failed: {e}')
+    state = ES_CONTINUOUS | (ES_DISPLAY_REQUIRED if enable else 0)
+    try:
+        ctypes.windll.kernel32.SetThreadExecutionState(state)
+        logger.info(f'Desktop screen keep-awake {"ON" if enable else "OFF"}')
+    except Exception as e:
+        logger.warning(f'SetThreadExecutionState({enable}) failed: {e}')
+
+
+def _window_total_size(width: int, height: int, style: int, ex_style: int) -> tuple:
+    """用 user32.AdjustWindowRectEx 计算包含标题栏/边框的窗口总尺寸 (w, h)。
+
+    pywin32 未导出 AdjustWindowRectEx,故用 ctypes 调用。
+    """
+    user32 = ctypes.windll.user32
+
+    class RECT(Structure):
+        _fields_ = [('left', c_long), ('top', c_long), ('right', c_long), ('bottom', c_long)]
+
+    user32.AdjustWindowRectEx.argtypes = [POINTER(RECT), c_long, c_long, c_long]
+    user32.AdjustWindowRectEx.restype = wintypes.BOOL
+    rect = RECT(0, 0, width, height)
+    user32.AdjustWindowRectEx(byref(rect), style, False, ex_style)
+    return rect.right - rect.left, rect.bottom - rect.top
+
+
+def _desktop_process_image(pid) -> str:
+    """返回进程 exe 完整路径;打开/查询失败(已退出、权限)返回空串。"""
+    kernel32 = ctypes.windll.kernel32
+    # PROCESS_QUERY_LIMITED_INFORMATION
+    handle = kernel32.OpenProcess(0x1000, False, int(pid))
+    if not handle:
+        return ''
+    try:
+        buf = ctypes.create_unicode_buffer(520)
+        size = ctypes.c_ulong(520)
+        if kernel32.QueryFullProcessImageNameW(handle, 0, buf, ctypes.byref(size)):
+            return buf.value
+        return ''
+    finally:
+        kernel32.CloseHandle(handle)
+
+
+def _desktop_pid_under_root(pid, root) -> bool:
+    """窗口归属进程的 exe 是否位于客户端安装目录之下。
+
+    自动启动绑定时用于排除同标题的模拟器窗口(MuMu 专版窗口标题也在
+    DESKTOP_WINDOW_TITLES 内),保证绑到的一定是安装目录拉起的客户端进程。
+    """
+    exe = _desktop_process_image(pid)
+    if not exe:
+        return False
+    root = os.path.normcase(os.path.normpath(root))
+    exe = os.path.normcase(os.path.normpath(exe))
+    return exe.startswith(root + os.sep)
+
+
+def list_desktop_windows() -> list:
+    """枚举当前所有桌面客户端窗口。
+
+    返回 [{'pid': int, 'title': str, 'x': int, 'y': int}],按屏幕位置排序。
+    桌面客户端多开时窗口标题完全相同,只能靠 PID 区分,附带左上角坐标是为了
+    让用户在界面上按"窗口摆在哪"对号入座。按坐标排序保证同一组窗口每次枚举
+    顺序稳定(EnumWindows 的返回顺序随 Z 序变化)。
+    """
+    def enum_cb(hwnd, param):
+        param.append(hwnd)
+        return True
+
+    handles = []
+    EnumWindows(enum_cb, handles)
+    result = []
+    for hwnd in handles:
+        if GetWindowText(hwnd) not in DESKTOP_WINDOW_TITLES:
+            continue
+        try:
+            rect = GetWindowRect(hwnd)
+        except Exception:
+            # 窗口在枚举与取矩形之间被关闭,跳过即可
+            continue
+        result.append({
+            'pid': GetWindowThreadProcessId(hwnd)[1],
+            'title': GetWindowText(hwnd),
+            'hwnd': hwnd,
+            'x': rect[0],
+            'y': rect[1],
+        })
+    result.sort(key=lambda w: (w['x'], w['y'], w['pid']))
+    return result
+
+
+def desktop_window_option(window: dict) -> str:
+    """把窗口信息格式化成界面下拉项文本,形如 `27272 (154,38)`。
+
+    不显示窗口标题:桌面客户端多开时标题完全相同,且中文字样在英文界面里冗余。
+    PID 放在最前,desktop_option2pid 只认第一段数字,坐标纯属给用户辨识用,
+    改动展示格式不会影响解析。
+    """
+    return f"{window['pid']} ({window['x']},{window['y']})"
+
+
+def desktop_option2pid(option: str) -> str:
+    """从下拉项文本中取回纯 PID;取不到时返回空串。
+
+    界面回传的是展示文本,但落盘的 handle 必须是纯 PID(Handle 按数字消费),
+    因此写入配置前统一在这里剥掉标题与坐标。用户手工填的纯数字原样通过。
+    """
+    if not option:
+        return ''
+    matched = re.match(r'\s*(\d+)', str(option))
+    return matched.group(1) if matched else ''
+
+
+class DesktopWindow:
+    def find_desktop_window_by_pid(self, pid) -> int:
+        """按 PID 查找桌面客户端窗口,返回窗口句柄;未找到抛 EmulatorNotRunningError。
+
+        「找不到窗口」记 warning 而非 error:本方法的调用方多为探测存在性
+        (desktop_window_exists 判断是否需要重拉、_desktop_wait_closed 确认已关闭),
+        找不到是正常答案。真正的故障由上层在拿到 EmulatorNotRunningError 后判定,
+        这样真故障不会被淹没在每轮任务收尾都出现的噪音里。
+
+        同一 PID 下可能同时存在多个标题命中的顶层窗口(客户端多开共用同一标题;
+        新版 MuMu 内核客户端启动期还带着启动器残留窗口),取客户区最大者即可。
+
+        这里刻意**不设客户区面积下限**:窗口被最小化时客户区是 0x0,但客户端仍在
+        运行,还原交给 desktop_window_restore_if_minimized。用面积下限去宣布「未运行」
+        会把这个正常挂着的客户端判成掉线 → 触发误重拉并把配置 handle 覆盖成新实例
+        (真机实测的循环就是这么起来的),而 BitBlt 截图前本来就会先把窗口还原。
+        """
+        try:
+            pid_int = int(str(pid))
+        except (TypeError, ValueError):
+            logger.error(f'Invalid desktop PID: {pid}')
+            raise EmulatorNotRunningError(f'Invalid desktop client PID: {pid}')
+
+        def enum_cb(hwnd, param):
+            param.append(hwnd)
+            return True
+
+        windows = []
+        EnumWindows(enum_cb, windows)
+        matches = []
+        for hwnd in windows:
+            if GetWindowText(hwnd) in DESKTOP_WINDOW_TITLES:
+                _, win_pid = GetWindowThreadProcessId(hwnd)
+                if win_pid == pid_int:
+                    matches.append(hwnd)
+        # 同 PID 的多个候选里取客户区最大者:正常渲染窗口面积最大,启动器残留/
+        # 最小化窗口(客户区 0x0)会排在后面。读不到客户区的(枚举与取值之间被销毁)
+        # 直接跳过,全部读不到才算未找到
+        best, best_area = 0, -1
+        for hwnd in matches:
+            try:
+                cl, ct, cr, cb = GetClientRect(hwnd)
+                area = (cr - cl) * (cb - ct)
+            except Exception:
+                continue
+            if area > best_area:
+                best, best_area = hwnd, area
+        if best:
+            return best
+        logger.warning(f'Desktop client window not found, PID={pid}')
+        raise EmulatorNotRunningError(f'Desktop client window not found, PID={pid}')
+
+    def _desktop_best_window(self, pid, fallback: int = 0) -> int:
+        """取指定 PID 下客户区最大的候选窗口;查不到时回退 fallback。
+
+        用于自动启动完成时的句柄确定:同一 PID 可能既带启动器残留窗口又带真渲染窗口,
+        取客户区最大者才不会把截图绑到残壳上。
+        """
+        try:
+            return self.find_desktop_window_by_pid(pid)
+        except EmulatorNotRunningError:
+            return fallback
+
+    def desktop_pid(self):
+        """返回当前桌面客户端 PID(int);取不到返回 None。
+
+        优先用实例 root_handle(运行时自动启动绑定后的新 PID),未设置时回退配置里的
+        handle。本会话的 PID 判断必须以实例状态为准,否则重新拉起后会误判。
+        """
+        pid = getattr(self, 'root_handle', None) or self.config.script.device.handle
+        try:
+            return int(str(pid))
+        except (TypeError, ValueError):
+            return None
+
+    def find_desktop_login_popup(self) -> int:
+        """按 PID + 类名查找 MPay 账号登录弹窗,返回句柄;没有则返回 0。
+
+        弹窗与游戏主窗口同 PID 但是独立顶层窗口(owner 为主窗口,非子窗口),
+        没有子控件可枚举,只能按窗口类名定位。
+        按 PID 过滤保证多开时各实例只处理自己客户端的弹窗。
+
+        主窗口 BitBlt 是否包含这个 owner 窗口受桌面合成状态影响,同一个弹窗可能在
+        不同错误截图中出现或消失,所以登录状态不能依赖截图判断。
+        改按「HWND 是否仍存活」判断而不再过滤 IsWindowVisible:真机验证过已登录的
+        客户端全系统枚举不到任何 MPAY_LOGIN 顶层窗口,说明客户端确认弹窗后是销毁它、
+        而非隐藏。因此 HWND 存活即代表尚未登录。
+        """
+        pid_int = self.desktop_pid()
+        if pid_int is None:
+            return 0
+
+        def enum_cb(hwnd, param):
+            param.append(hwnd)
+            return True
+
+        windows = []
+        EnumWindows(enum_cb, windows)
+        for hwnd in windows:
+            try:
+                if GetClassName(hwnd) != DESKTOP_LOGIN_POPUP_CLASS:
+                    continue
+                if GetWindowThreadProcessId(hwnd)[1] == pid_int:
+                    return hwnd
+            except Exception:
+                # 窗口在枚举与取属性之间被关闭,跳过即可
+                continue
+        return 0
+
+    def desktop_confirm_login_popup(self, wait: float = 15.0) -> bool:
+        """向 MPay 登录弹窗发送回车,并确认对应 HWND 已真实消失。
+
+        弹窗是 DirectUI 独立顶层窗口,"进入游戏"只是绘制出来的像素、没有真实控件,
+        实测后台鼠标消息(WM_MOUSEMOVE/LBUTTONDOWN/LBUTTONUP,Post 与 Send 都试过)
+        完全无响应;同步与异步回车在无前台焦点时均可触发默认按钮。因此这里只发回车,
+        并在 wait 秒内轮询确认弹窗 HWND 真的消失。
+
+        返回 True 表示弹窗确实已关闭;False 表示没有弹窗,或超时后弹窗仍然存活。
+        """
+        if not self.find_desktop_login_popup():
+            return False
+        logger.info('Desktop MPay login popup found, press Enter to enter game')
+        deadline = time.time() + wait
+        while time.time() < deadline:
+            hwnd = self.find_desktop_login_popup()
+            if not hwnd:
+                logger.info('Desktop MPay login popup confirmed closed')
+                return True
+            self._desktop_send_enter(hwnd)
+            time.sleep(1)
+        logger.warning(f'Desktop MPay login popup still present after {wait}s, Enter had no effect')
+        return False
+
+    def desktop_window_exists(self) -> bool:
+        """桌面模式:目标 PID 对应窗口仍存在即视为客户端运行中。
+
+        只判「标题命中的顶层窗口在不在」,不看客户区尺寸——窗口被最小化或被遮挡时
+        客户端仍在运行,截图方法会先把窗口还原回来再取帧。
+
+        优先用实例 root_handle(运行时自动启动绑定后的新 PID),未设置时回退配置里的
+        handle。本会话的窗口存在性判断必须以实例状态为准,否则重新拉起后会误判为未运行。
+        """
+        pid = getattr(self, 'root_handle', None) or self.config.script.device.handle
+        try:
+            self.find_desktop_window_by_pid(pid)
+            return True
+        except EmulatorNotRunningError:
+            return False
+
+    def _desktop_wait_window_ready(self, pid, wait: float = DESKTOP_WINDOW_READY_WAIT) -> bool:
+        """在 wait 秒内等待指定 PID 的客户端窗口出现;超时返回 False。
+
+        用于「进程还活着、窗口暂时不可见」的空窗期。这段时间只能等,不能重新启动
+        客户端:真正在跑的那个实例会变成多开或被顶掉,配置里的 handle 也会被新实例
+        覆盖,从此再也绑不回原来的客户端。
+        """
+        deadline = time.time() + wait
+        while True:
+            try:
+                self.find_desktop_window_by_pid(pid)
+                return True
+            except EmulatorNotRunningError:
+                pass
+            if time.time() >= deadline:
+                logger.error(f'Desktop client process alive but window not ready in {wait}s, PID={pid}')
+                return False
+            time.sleep(DESKTOP_WINDOW_READY_POLL_INTERVAL)
+
+    def desktop_client_offset(self) -> tuple:
+        """返回客户区在窗口 DC 内的偏移 (x, y),用于 BitBlt 扣除标题栏/边框。"""
+        with dpi_awareness():
+            window_rect = GetWindowRect(self.screenshot_handle_num)
+            client_origin = ClientToScreen(self.screenshot_handle_num, (0, 0))
+            return client_origin[0] - window_rect[0], client_origin[1] - window_rect[1]
+
+    def desktop_client_size(self) -> tuple:
+        """返回桌面客户端窗口客户区的物理像素尺寸 (width, height)。"""
+        with dpi_awareness():
+            rect = GetClientRect(self.screenshot_handle_num)
+            return rect[2] - rect[0], rect[3] - rect[1]
+
+    def desktop_client_size_virtual(self) -> tuple:
+        """返回客户区在 DPI 虚拟化空间下的尺寸 (width, height)。
+
+        OAS 进程未声明 DPI 感知,PostMessage 的 lParam 会被系统按该空间解释,
+        因此后台输入的坐标必须换算到这里,而不是截图所用的物理空间。
+        """
+        rect = GetClientRect(self.screenshot_handle_num)
+        return rect[2] - rect[0], rect[3] - rect[1]
+
+    def _desktop_client_size(self, hwnd):
+        """读窗口客户区物理尺寸,句柄已失效返回 None。
+
+        客户端从登录界面切到游戏主窗口时会销毁重建渲染窗口,因此调整窗口期间的任何
+        一次 Win32 调用都可能撞上失效句柄。GetClientRect 对废句柄抛
+        (1400, '无效的窗口句柄'),不接住会直接崩掉整个脚本进程。
+        """
+        if not IsWindow(hwnd):
+            return None
+        try:
+            rect = GetClientRect(hwnd)
+        except Exception as e:
+            logger.warning(f'GetClientRect failed (hwnd={hwnd}): {e}')
+            return None
+        return rect[2] - rect[0], rect[3] - rect[1]
+
+    def _desktop_clear_handle_cache(self) -> None:
+        """失效截图相关 cached_property,使其按当前 root_handle_num 重新求值。
+
+        桌面模式下 screenshot_handle_num 直接返回 root_handle_num,但它是
+        cached_property:客户端重开后 root_handle_num 已换成新 hwnd,缓存仍指向
+        旧句柄,截图时 GetClientRect 会拿废句柄抛 (1400)。
+        """
+        for prop in ('screenshot_handle_num', 'screenshot_size'):
+            if prop in self.__dict__:
+                del_cached_property(self, prop)
+
+    def _desktop_rebind_window(self) -> bool:
+        """按 PID 重新查找客户端窗口并绑定新 hwnd,返回是否绑定成功。
+
+        用于两类句柄刷新:窗口重建(登录界面切游戏主窗口)后更换句柄,以及同一 PID
+        下换到客户区更大的那个候选窗口。进程还活着,不需要重拉客户端。
+        """
+        try:
+            hwnd = self.find_desktop_window_by_pid(self.root_handle)
+        except EmulatorNotRunningError:
+            return False
+        if hwnd != self.root_handle_num:
+            logger.info(f'Desktop window handle changed, rebind hwnd {self.root_handle_num} -> {hwnd}')
+            self.root_handle_num = hwnd
+            self._desktop_clear_handle_cache()
+        return True
+
+    def desktop_window_set_size(self, width: int = 1280, height: int = 720) -> bool:
+        """桌面模式:检测窗口客户区尺寸,非目标大小时用 SetWindowPos 调整到 width×height。
+
+        窗口位置保持不变;返回是否执行了调整。全过程在 DPI 感知上下文内完成,
+        GetClientRect/SetWindowPos 处理的都是物理像素,因此目标尺寸无需按缩放比换算,
+        调整后客户区物理尺寸恰为 width×height,游戏画面与资产 1:1 对应。
+
+        客户端确认登录弹窗后会销毁登录界面、重建游戏主窗口,调整过程中旧 hwnd 随时可能
+        失效。此时不抛异常也不重拉客户端(进程还活着),而是按 PID 重新绑定重建后的
+        窗口再试,最多 DESKTOP_RESIZE_ATTEMPTS 轮。
+        """
+        if not getattr(self, 'is_desktop_window', False):
+            return False
+        for attempt in range(1, DESKTOP_RESIZE_ATTEMPTS + 1):
+            result = self._desktop_try_set_size(width, height)
+            if result is not None:
+                return result
+            if attempt >= DESKTOP_RESIZE_ATTEMPTS:
+                break
+            logger.info(f'Desktop window invalid, rebind and retry resize '
+                        f'({attempt}/{DESKTOP_RESIZE_ATTEMPTS})')
+            time.sleep(DESKTOP_RESIZE_RETRY_INTERVAL)
+            self._desktop_rebind_window()
+        logger.warning(f'Desktop window resize gave up after {DESKTOP_RESIZE_ATTEMPTS} attempts, '
+                       f'window kept invalid')
+        return False
+
+    def _desktop_try_set_size(self, width: int, height: int):
+        """单轮尝试调整窗口尺寸。
+
+        返回 True/False 表示本轮已得出结论(是否执行了调整);返回 None 表示句柄失效,
+        需由调用方重新绑定窗口后再试。三态的意义在于把「尺寸本来就对」(False)和
+        「窗口正在重建」(None)区分开,否则前者会白等重试。
+        """
+        hwnd = self.root_handle_num
+        if not hwnd or not IsWindow(hwnd):
+            logger.warning(f'Desktop window handle invalid (hwnd={hwnd})')
+            return None
+        with dpi_awareness():
+            size = self._desktop_client_size(hwnd)
+            if size is None:
+                logger.warning(f'Desktop window vanished before resize (hwnd={hwnd})')
+                return None
+            client_w, client_h = size
+            logger.info(f'Desktop client size: {client_w}x{client_h} (physical), target {width}x{height}')
+            if client_w == width and client_h == height:
+                logger.info('Desktop client size already matches target')
+                return False
+            # 用 AdjustWindowRectEx 精确计算含标题栏/边框的窗口总尺寸
+            style = GetWindowLong(hwnd, GWL_STYLE)
+            ex_style = GetWindowLong(hwnd, GWL_EXSTYLE)
+            total_w, total_h = _window_total_size(width, height, style, ex_style)
+            logger.info(f'Resize desktop window to {total_w}x{total_h} to get client {width}x{height}')
+            try:
+                SetWindowPos(hwnd, HWND_TOP, 0, 0, total_w, total_h, SWP_NOMOVE | SWP_SHOWWINDOW)
+            except Exception as e:
+                # 拒绝访问通常是目标窗口权限更高(游戏以管理员运行)或客户端锁定窗口大小
+                logger.error(f'SetWindowPos failed: {e}. '
+                             f'请以管理员身份运行 OAS,或手动把游戏窗口设为 1280x720')
+                return False
+            # 校准:SetWindowPos 后的实际客户区可能与目标差几像素,按差值持续修正。
+            # SetWindowPos 本身可能正好撞上客户端重建窗口,因此每轮都要重新确认句柄有效
+            for _ in range(5):
+                size = self._desktop_client_size(hwnd)
+                if size is None:
+                    logger.warning(f'Desktop window vanished during resize (hwnd={hwnd}), '
+                                   f'client is rebuilding its window')
+                    return None
+                cw, ch = size
+                if cw == width and ch == height:
+                    return True
+                total_w += width - cw
+                total_h += height - ch
+                logger.info(f'Calibrate desktop window to {total_w}x{total_h}, current client {cw}x{ch}')
+                try:
+                    SetWindowPos(hwnd, HWND_TOP, 0, 0, total_w, total_h, SWP_NOMOVE | SWP_SHOWWINDOW)
+                except Exception as e:
+                    logger.warning(f'SetWindowPos failed during calibration (hwnd={hwnd}): {e}')
+                    return None
+            return True
+
+    # ------------------------------------------------------------------ 桌面客户端自动生命周期
+
+    def desktop_resolve_install_root(self) -> str:
+        """解析桌面客户端安装目录:优先 desktop_game_path 配置,其次自动发现。
+
+        只认含 bin\\onmyoji.exe(或根目录 Launch.exe)的安装目录,找不到返回空串。
+        仅桌面模式调用,不影响模拟器流程。
+        """
+        configured = getattr(self.config.script.device, 'desktop_game_path', '') or ''
+        if configured:
+            root = self._desktop_root_from_path(configured)
+            if root is not None:
+                return str(root)
+            logger.warning(f'desktop_game_path 配置无效: {configured},尝试自动发现')
+        root = self._desktop_discover_install_root()
+        return str(root) if root else ''
+
+    @staticmethod
+    def _desktop_root_from_path(value: str):
+        """把用户填的路径归一化成安装目录;无效返回 None。"""
+        path = Path(value).expanduser()
+        if path.is_file():
+            # 允许直接填 bin\\onmyoji.exe 或 Launch.exe 的完整路径
+            if path.name.lower() == 'onmyoji.exe' and path.parent.name.lower() == 'bin':
+                path = path.parent.parent
+            elif path.name.lower() == 'launch.exe':
+                path = path.parent
+            else:
+                path = path.parent
+        candidate = path / 'bin' / 'onmyoji.exe'
+        if candidate.is_file():
+            return path.resolve()
+        return None
+
+    @staticmethod
+    def _desktop_discover_install_root():
+        """按 %ProgramFiles%\\Onmyoji 与注册表 Uninstall 的 InstallLocation 自动发现安装目录。"""
+        for env in ('ProgramFiles', 'ProgramFiles(x86)'):
+            raw = os.environ.get(env)
+            if raw and (Path(raw) / 'Onmyoji' / 'bin' / 'onmyoji.exe').is_file():
+                return (Path(raw) / 'Onmyoji').resolve()
+        try:
+            import winreg
+            roots = (
+                (winreg.HKEY_LOCAL_MACHINE, r'SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall'),
+                (winreg.HKEY_LOCAL_MACHINE, r'SOFTWARE\WOW6432Node\Microsoft\Windows\CurrentVersion\Uninstall'),
+                (winreg.HKEY_CURRENT_USER, r'SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall'),
+            )
+            for hive, key_path in roots:
+                try:
+                    with winreg.OpenKey(hive, key_path) as parent:
+                        for index in range(winreg.QueryInfoKey(parent)[0]):
+                            try:
+                                with winreg.OpenKey(parent, winreg.EnumKey(parent, index)) as child:
+                                    display, _ = winreg.QueryValueEx(child, 'DisplayName')
+                                    if '阴阳师' not in str(display) and 'Onmyoji' not in str(display):
+                                        continue
+                                    location, _ = winreg.QueryValueEx(child, 'InstallLocation')
+                                    if location and (Path(location) / 'bin' / 'onmyoji.exe').is_file():
+                                        return Path(location).resolve()
+                            except OSError:
+                                continue
+                except OSError:
+                    continue
+        except Exception:
+            pass
+        return None
+
+    @staticmethod
+    def desktop_game_exe(root) -> str:
+        """返回游戏可执行文件路径;找不到返回空串。
+
+        顺序即优先级:必须优先游戏本体 bin/onmyoji.exe。
+        Launch.exe 是登录器,它会再拉起 bin/onmyoji.exe,
+        导致双开且 OAS 绑定到登录器 PID 上找不到游戏窗口。
+        """
+        root = Path(root)
+        for name in ('bin/onmyoji.exe', 'Launch.exe'):
+            exe = root / name
+            if exe.is_file():
+                return str(exe)
+        return ''
+
+    def launch_desktop_client(self, timeout: int = 90) -> bool:
+        """自动启动桌面客户端并绑定新窗口的 PID/HWND,成功返回 True。
+
+        单轮 = 启动 exe → 等新窗口出现并稳定 → 绑定其 PID/HWND。到此启动即完成;
+        MPay 登录弹窗与进游戏属登录流程,由 Restart 的 app_handle_login 负责。
+        timeout 内没等到窗口说明客户端起歪了(卡加载、崩在启动期等),强杀本轮进程后
+        整轮重跑一次;第二轮仍失败则记 error 返回 False,由上层停下等人工,不无限重试。
+        安装目录/exe 找不到属配置问题,重试无意义,直接返回 False。
+        """
+        root = self.desktop_resolve_install_root()
+        if not root:
+            logger.error('未找到阴阳师桌面客户端安装目录,请在 设置-Script-设备 中填写 desktop_game_path')
+            return False
+        exe = self.desktop_game_exe(root)
+        if not exe:
+            logger.error(f'未找到游戏程序(bin\\onmyoji.exe 或 Launch.exe):{root}')
+            return False
+
+        for attempt in (1, 2):
+            pids = self._desktop_launch_attempt(exe, root, timeout, attempt)
+            if pids is None:
+                # Popen 本身失败,重试也起不来
+                return False
+            bound_pid, spawned_pid = pids
+            if bound_pid:
+                # 启动成功也要记住本轮拉起的全部 PID:onmyoji.exe 是启动器,它会派生出
+                # 真正的游戏窗口进程后自己继续存活(实测启动器 8932 派生窗口进程 6816,
+                # 89 线程 42s CPU 却无窗口)。OAS 靠枚举窗口只绑到窗口进程,关闭时若只杀
+                # 它,启动器就成了无主残留。这里留档,交给 desktop_stop_client 一并清理
+                self._desktop_spawned_pids = set(spawned_pid)
+                # 客户端已拉起,强制保持显示器常亮,防止电源超时关屏导致截图黑帧卡死
+                desktop_keep_screen_on(True)
+                return True
+            if attempt == 1:
+                # 只杀本轮确切启动的进程:绑定阶段就失败时 root_handle 仍是上一次的陈旧
+                # PID,直接调 desktop_force_kill 会误杀(PID 可能已被系统复用)
+                logger.warning('第 1 轮启动未就绪,清理本轮客户端后重试')
+                self._desktop_kill_pids(spawned_pid)
+        logger.error('桌面客户端连续 2 轮启动均未就绪,请检查客户端状态与机器负载')
+        return False
+
+    def _desktop_launch_attempt(self, exe: str, root: str, timeout: int, attempt: int):
+        """启动客户端并绑定其窗口的单轮尝试。
+
+        返回 (bound_pid, spawned_pid):bound_pid 非 0 表示本轮成功;spawned_pid 是本轮
+        Popen 出的进程与绑定到的窗口 PID 集合,供失败清理精确定位。Popen 失败返回 None。
+        """
+        before_pids = {w['pid'] for w in list_desktop_windows()}
+        logger.info(f'自动启动桌面客户端(第 {attempt} 轮): {exe}')
+        spawned = set()
+        try:
+            proc = subprocess.Popen([exe], cwd=root,
+                                    creationflags=getattr(subprocess, 'CREATE_NEW_PROCESS_GROUP', 0))
+            spawned.add(proc.pid)
+        except Exception as e:
+            logger.error(f'启动桌面客户端失败: {e}')
+            return None
+
+        deadline = time.time() + timeout
+        stable_hwnd = 0
+        stable_count = 0
+        while time.time() < deadline:
+            # 候选必须落在安装目录下的进程:客户端新旧版本窗口标题不同
+            # ("阴阳师-网易游戏" / "阴阳师-MuMu模拟器专版"),启动等待期内任何
+            # 匹配标题的新窗口都会成为候选,按 exe 归属收口,避免绑到别的进程
+            candidates = [w for w in list_desktop_windows()
+                          if w['pid'] not in before_pids
+                          and _desktop_pid_under_root(w['pid'], root)]
+            if candidates:
+                candidate = candidates[0]
+                if candidate['hwnd'] == stable_hwnd:
+                    stable_count += 1
+                else:
+                    stable_hwnd = candidate['hwnd']
+                    stable_count = 1
+                if stable_count >= 2:
+                    # 同一 PID 可能还带着启动器残留窗口(客户区极小),句柄统一取
+                    # 客户区最大者,否则截图会绑到残壳上(BitBlt 取不到画面)
+                    hwnd = self._desktop_best_window(candidate['pid'], candidate['hwnd'])
+                    self.desktop_bind_pid(candidate['pid'], hwnd)
+                    spawned.add(candidate['pid'])
+                    logger.info(f'桌面客户端已自动启动并绑定 PID={candidate["pid"]}')
+                    # 到这里启动就完成了:进程在跑、窗口句柄已绑定。
+                    # MPay 登录弹窗与进游戏属于登录流程,由 Restart 的 app_handle_login
+                    # 负责(登录循环每轮都复查弹窗,中途冒出来也能接住)。
+                    return candidate['pid'], spawned
+            time.sleep(1)
+        logger.warning(f'桌面客户端进程已启动,但 {timeout} 秒内未识别到游戏窗口')
+        return 0, spawned
+
+    def _desktop_kill_pids(self, pids) -> None:
+        """强杀指定 PID 集合(本轮启动失败的清理),逐个容错并验证真的退出。"""
+        kernel32 = ctypes.windll.kernel32
+        wait = self._desktop_close_wait_seconds()
+        for pid in pids:
+            try:
+                pid_int = int(pid)
+            except (TypeError, ValueError):
+                continue
+            for attempt in range(1, DESKTOP_KILL_ATTEMPTS + 1):
+                # PROCESS_TERMINATE(0x0001)
+                handle = kernel32.OpenProcess(0x0001, False, pid_int)
+                if not handle:
+                    # 进程已自行退出
+                    break
+                try:
+                    kernel32.TerminateProcess(handle, 0)
+                    logger.info(f'清理桌面客户端 PID={pid_int}')
+                finally:
+                    kernel32.CloseHandle(handle)
+                # 杀完必须确认进程真的没了,被拒或正在退出都会让下一轮启动撞上残留
+                if self._desktop_wait_pid_gone(pid_int, wait):
+                    break
+                logger.warning(f'桌面客户端 PID={pid_int} 强杀后仍存活,重试 '
+                               f'({attempt}/{DESKTOP_KILL_ATTEMPTS})')
+            else:
+                logger.error(f'桌面客户端 PID={pid_int} 无法清理,可能需要手动结束进程')
+        # 等窗口真的消失,避免残留窗口干扰下一轮的新窗口识别
+        self._desktop_wait_closed(wait)
+
+    def _desktop_wait_pid_gone(self, pid, wait: float) -> bool:
+        """在 wait 秒内等待指定进程退出,返回是否已退出。"""
+        deadline = time.time() + wait
+        while True:
+            if not self._desktop_pid_alive(pid):
+                return True
+            if time.time() >= deadline:
+                return False
+            time.sleep(DESKTOP_KILL_POLL_INTERVAL)
+
+    def desktop_bind_pid(self, pid, hwnd=0) -> None:
+        """把新 PID/HWND 绑定到实例,并尽量持久化到配置。"""
+        self.root_handle = str(pid)
+        if hwnd:
+            self.root_handle_num = hwnd
+        self.root_handle_title = DESKTOP_WINDOW_TITLES[0]
+        self.is_desktop_window = True
+        # 换了新 hwnd,截图句柄缓存必须同步失效,否则截图仍走上一个客户端的废句柄
+        self._desktop_clear_handle_cache()
+        # 新绑定的客户端刚启动,必然未登录,需先走 restart 登录流程
+        self._desktop_login_done = False
+        logger.info(f'Desktop client bound: PID={pid}, hwnd={hwnd}')
+        try:
+            self.config.script.device.handle = str(pid)
+            self.config.save()
+        except Exception as e:
+            logger.warning(f'持久化桌面 PID 到配置失败: {e}')
+
+    def _desktop_send_enter(self, hwnd) -> None:
+        """向窗口发送回车键,用于确认 MPay 账号登录弹窗的默认按钮"进入游戏"。
+
+        窗口可能在两条消息之间被销毁(回车已生效),此时忽略异常即可。
+        """
+        try:
+            SendMessage(hwnd, WM_KEYDOWN, VK_RETURN, 0)
+            SendMessage(hwnd, WM_KEYUP, VK_RETURN, 0)
+        except Exception as e:
+            logger.info(f'Send Enter to window {hwnd} failed (window may be closed): {e}')
+
+    def _desktop_pid_alive(self, pid) -> bool:
+        """进程是否还活着。无法判定时按「还活着」返回,宁可多等一轮也不误报已关闭。
+
+        不能只看 OpenProcess 是否成功:进程已退出但仍有内核对象引用时 OpenProcess
+        照样返回句柄,必须再用 GetExitCodeProcess 看退出码是否还是 STILL_ACTIVE(259)。
+        窗口枚举不能替代这里——强杀被拒时窗口可能已销毁而进程还在,只验窗口会误判。
+        """
+        try:
+            pid_int = int(str(pid))
+        except (TypeError, ValueError):
+            return False
+        kernel32 = ctypes.windll.kernel32
+        # PROCESS_QUERY_LIMITED_INFORMATION(0x1000),比 QUERY_INFORMATION 权限要求更低
+        handle = kernel32.OpenProcess(0x1000, False, pid_int)
+        if not handle:
+            # 打不开通常就是进程已退出;权限不足时也走这里,交给窗口检查兜底
+            return False
+        try:
+            code = ctypes.c_ulong()
+            if not kernel32.GetExitCodeProcess(handle, ctypes.byref(code)):
+                return True
+            return code.value == 259  # STILL_ACTIVE
+        finally:
+            kernel32.CloseHandle(handle)
+
+    def _desktop_wait_closed(self, wait: float) -> bool:
+        """在 wait 秒内轮询等待桌面客户端窗口消失,返回是否已关闭。"""
+        deadline = time.time() + wait
+        while True:
+            if not self.desktop_window_exists():
+                return True
+            if time.time() >= deadline:
+                return False
+            time.sleep(0.5)
+
+    def _desktop_wait_released(self, pid, wait: float) -> bool:
+        """在 wait 秒内等待客户端真正释放:窗口消失 **且** 进程退出。
+
+        两个条件都要,缺一个都可能是假关闭:
+        - 只验窗口:强杀被拒时窗口已销毁但进程还在,会漏掉残留进程
+        - 只验进程:进程刚退出时窗口可能还在被系统回收,下一轮新窗口识别会撞上
+        """
+        deadline = time.time() + wait
+        while True:
+            if not self.desktop_window_exists() and not self._desktop_pid_alive(pid):
+                return True
+            if time.time() >= deadline:
+                return False
+            time.sleep(DESKTOP_KILL_POLL_INTERVAL)
+
+    def desktop_stop_client(self) -> bool:
+        """关闭桌面客户端:强杀进程并验证真的释放,返回是否确认关闭。
+
+        客户端的退出确认框画在游戏窗口内部(不是独立顶层窗口),实测回车确认经常无效
+        (进程不退出、主窗口只是被移到屏幕外),走 WM_CLOSE + 确认反而要多等几秒还未必
+        关得掉,因此这里不发任何窗口消息,直接强杀进程。
+
+        强杀不等于已关闭:TerminateProcess 可能因权限被拒(本机出现过 (5, '拒绝访问。')),
+        进程也可能正在退出还没消失。所以每轮杀完都验证「窗口消失 且 进程退出」,没释放
+        就再杀一轮,全部轮次用尽仍在则返回 False——调用方据此决定是重建还是交人工,
+        绝不能发完 kill 指令就当成功返回。
+
+        关闭后保留原 PID 在配置里;下次检测到该 PID 无效(客户端未运行)时,
+        由启动/重拉链路重启客户端并把配置更新为重启后的新 PID。
+        """
+        # 客户端关闭后必然未登录,下次启动需重新走登录流程
+        self._desktop_login_done = False
+        # PID 要在清理句柄前取,后面的验证全靠它
+        pid = getattr(self, 'root_handle', None) or self.config.script.device.handle
+        hwnd = self.root_handle_num
+        if (not hwnd or not IsWindow(hwnd)) and not self._desktop_pid_alive(pid):
+            logger.info('Desktop client not running, skip stop')
+            # 客户端已不在,解除强制亮屏,允许系统恢复正常的显示器电源管理
+            desktop_keep_screen_on(False)
+            self._reset_desktop_handle_state()
+            # 窗口进程已没了也要收启动器:它无窗口,只看窗口永远发现不了
+            self._desktop_kill_spawned_leftovers(pid)
+            return True
+
+        wait = self._desktop_close_wait_seconds()
+        released = False
+        for attempt in range(1, DESKTOP_KILL_ATTEMPTS + 1):
+            logger.info(f'Stopping desktop client: force kill '
+                        f'({attempt}/{DESKTOP_KILL_ATTEMPTS}, PID={pid})')
+            self.desktop_force_kill()
+            if self._desktop_wait_released(pid, wait):
+                logger.info(f'Desktop client released (PID={pid})')
+                # 客户端已确认关闭,解除强制亮屏,允许系统恢复正常的显示器电源管理
+                desktop_keep_screen_on(False)
+                released = True
+                break
+            logger.warning(f'Desktop client PID={pid} still present after {wait}s, retry kill')
+        if not released:
+            # 到这里客户端确实没关掉:句柄状态照常清零(它已不可信),但把失败如实报出去
+            logger.error(f'Desktop client PID={pid} not released after '
+                         f'{DESKTOP_KILL_ATTEMPTS} force kill attempts, manual cleanup needed')
+        self._reset_desktop_handle_state()
+        # 无论窗口进程是否关掉,本轮自己拉起的启动器都要一并收掉
+        leftovers_cleared = self._desktop_kill_spawned_leftovers(pid)
+        return released and leftovers_cleared
+
+    def _desktop_kill_spawned_leftovers(self, bound_pid) -> bool:
+        """清理本次自己拉起、但没被绑定的客户端进程,返回是否已全部清掉。
+
+        onmyoji.exe 是启动器:Popen 起来后它派生真正的游戏窗口进程,自己继续存活且
+        没有窗口(实测启动器 89 线程、42s CPU、主窗口句柄为 0)。OAS 靠枚举游戏窗口
+        绑定,只会绑到窗口进程,关闭时若只杀它,启动器就成了无主残留——既占内存,
+        也让下一轮启动的窗口识别多一个干扰源。这些 PID 由 launch_desktop_client
+        在启动成功时留档到 _desktop_spawned_pids。
+        """
+        spawned = getattr(self, '_desktop_spawned_pids', None)
+        if not spawned:
+            return True
+        try:
+            bound = int(str(bound_pid))
+        except (TypeError, ValueError):
+            bound = None
+        # 已绑定的那个由主流程负责,这里只收剩下的
+        leftovers = {p for p in spawned if p != bound and self._desktop_pid_alive(p)}
+        self._desktop_spawned_pids = set()
+        if not leftovers:
+            return True
+        logger.info(f'清理本次启动残留的客户端进程(启动器): {sorted(leftovers)}')
+        self._desktop_kill_pids(leftovers)
+        still = {p for p in leftovers if self._desktop_pid_alive(p)}
+        if still:
+            logger.error(f'客户端启动器进程无法清理: {sorted(still)},可能需要手动结束')
+            return False
+        return True
+
+    def _reset_desktop_handle_state(self) -> None:
+        """清零桌面窗口句柄与截图句柄缓存。
+
+        进程已杀,hwnd 随窗口销毁立即失效。必须清零,否则后续在同一个 device 对象
+        生命周期内被唤醒的任务(如配置变更触发的即时调度)会跳过 Handle.__init__,
+        直接拿这个废句柄去 GetClientRect,抛 (1400, '无效的窗口句柄') 搞崩整个进程。
+        """
+        self.root_handle_num = 0
+        # 截图句柄缓存指向的也是刚被销毁的窗口,一并失效
+        self._desktop_clear_handle_cache()
+
+    def _desktop_close_wait_seconds(self) -> int:
+        """关闭游戏等待时长(秒),读 config.script.optimization.close_game_wait_duration。"""
+        try:
+            t = self.config.script.optimization.close_game_wait_duration
+            return t.hour * 3600 + t.minute * 60 + t.second
+        except Exception:
+            return 10
+
+    def desktop_force_kill(self) -> None:
+        """强杀桌面客户端进程(WM_CLOSE 超时未退出的兜底)。"""
+        pid = getattr(self, 'root_handle', None) or self.config.script.device.handle
+        try:
+            pid_int = int(str(pid))
+        except (TypeError, ValueError):
+            logger.error(f'Invalid desktop PID: {pid}, skip force kill')
+            return
+        kernel32 = ctypes.windll.kernel32
+        # PROCESS_TERMINATE(0x0001)
+        handle = kernel32.OpenProcess(0x0001, False, pid_int)
+        if not handle:
+            # 进程已自行退出
+            return
+        try:
+            kernel32.TerminateProcess(handle, 0)
+            logger.info(f'Desktop client PID={pid_int} force terminated')
+        finally:
+            kernel32.CloseHandle(handle)
+
+    def desktop_window_restore_if_minimized(self, wait: float = 3.0) -> bool:
+        """桌面窗口被最小化(用户误操作)时还原并等待客户区恢复,返回是否发生过还原。
+
+        还原成功后若客户区尺寸偏离目标(1280x720),一并重校准,保证识别 1:1。
+        """
+        if not getattr(self, 'is_desktop_window', False):
+            return False
+        hwnd = self.root_handle_num
+        if not hwnd or not IsIconic(hwnd):
+            return False
+        logger.warning('Desktop client window is minimized, restoring')
+        ShowWindow(hwnd, SW_RESTORE)
+        deadline = time.time() + wait
+        restored = False
+        while time.time() < deadline:
+            with dpi_awareness():
+                rect = GetClientRect(hwnd)
+            if (rect[2] - rect[0]) > 0 and (rect[3] - rect[1]) > 0:
+                restored = True
+                break
+            time.sleep(0.2)
+        if restored:
+            self.desktop_window_set_size()
+        return restored

+ 150 - 16
module/device/method/windows_impl.py

@@ -11,29 +11,35 @@ from cached_property import cached_property
 from win32gui import (GetWindowText, EnumWindows, FindWindow, FindWindowEx,
 from win32gui import (GetWindowText, EnumWindows, FindWindow, FindWindowEx,
                       IsWindow, GetWindowRect, GetWindowDC, DeleteObject,
                       IsWindow, GetWindowRect, GetWindowDC, DeleteObject,
                       SetForegroundWindow, IsWindowVisible, GetDC, GetParent,
                       SetForegroundWindow, IsWindowVisible, GetDC, GetParent,
-                      EnumChildWindows, SetForegroundWindow)
+                      EnumChildWindows, SetForegroundWindow, GetClientRect)
 from win32con import (SRCCOPY, DESKTOPHORZRES, DESKTOPVERTRES, WM_LBUTTONUP,
 from win32con import (SRCCOPY, DESKTOPHORZRES, DESKTOPVERTRES, WM_LBUTTONUP,
                       WM_LBUTTONDOWN, WM_ACTIVATE, WA_ACTIVE, MK_LBUTTON,
                       WM_LBUTTONDOWN, WM_ACTIVATE, WA_ACTIVE, MK_LBUTTON,
                       WM_NCHITTEST, WM_SETCURSOR, HTCLIENT, WM_MOUSEMOVE,
                       WM_NCHITTEST, WM_SETCURSOR, HTCLIENT, WM_MOUSEMOVE,
                       WM_PARENTNOTIFY, WM_MOUSEACTIVATE, WM_MOUSEWHEEL,
                       WM_PARENTNOTIFY, WM_MOUSEACTIVATE, WM_MOUSEWHEEL,
-                      WM_SETFOCUS)
+                      WM_SETFOCUS, WM_CAPTURECHANGED)
 from win32ui import CreateDCFromHandle, CreateBitmap
 from win32ui import CreateDCFromHandle, CreateBitmap
 from win32api import GetSystemMetrics, SendMessage, MAKELONG, PostMessage
 from win32api import GetSystemMetrics, SendMessage, MAKELONG, PostMessage
 from win32con import SRCCOPY
 from win32con import SRCCOPY
 
 
 
 
-from module.base.cBezier import BezierTrajectory
+from module.base.cBezier import human_track
 from module.exception import RequestHumanTakeover, ScriptError
 from module.exception import RequestHumanTakeover, ScriptError
 from module.base.decorator import Config
 from module.base.decorator import Config
 from module.base.timer import timer
 from module.base.timer import timer
 from module.logger import logger
 from module.logger import logger
 from module.device.handle import Handle, window_scale_rate, EmulatorFamily
 from module.device.handle import Handle, window_scale_rate, EmulatorFamily
+from module.device.method.desktop_impl import dpi_awareness
 
 
 
 
 
 
 
 
 class Window(Handle):
 class Window(Handle):
 
 
+    # 桌面模式鼠标移动:每 N 像素取一个轨迹点,并限制单次移动的点数上限,
+    # 使长距离移动的耗时与距离解耦(移动只为更新客户端悬停状态)。
+    DESKTOP_MOVE_STEP = 60
+    DESKTOP_MOVE_MAX_POINTS = 12
+
     def __init__(self, *args, **kwargs):
     def __init__(self, *args, **kwargs):
         logger.info("Window init")
         logger.info("Window init")
         super().__init__(*args, **kwargs)
         super().__init__(*args, **kwargs)
@@ -43,6 +49,8 @@ class Window(Handle):
         后台截屏
         后台截屏
         :return:
         :return:
         """
         """
+        if getattr(self, 'is_desktop_window', False):
+            return self.screenshot_desktop_bitblt()
         widthScreen, heightScreen = self.screenshot_size
         widthScreen, heightScreen = self.screenshot_size
         # 返回句柄窗口的设备环境,覆盖整个窗口,包括非客户区,标题栏,菜单,边框
         # 返回句柄窗口的设备环境,覆盖整个窗口,包括非客户区,标题栏,菜单,边框
         hwndDc = GetWindowDC(self.screenshot_handle_num)
         hwndDc = GetWindowDC(self.screenshot_handle_num)
@@ -80,6 +88,43 @@ class Window(Handle):
         mfcDc.DeleteDC()
         mfcDc.DeleteDC()
         return imgSrceen
         return imgSrceen
 
 
+    def screenshot_desktop_bitblt(self):
+        """桌面客户端后台截图:在 DPI 感知上下文内对客户区 DC 做 BitBlt。
+
+        客户端按物理像素原生渲染,感知上下文里取到的就是物理客户区(1280x720),
+        与资产 1:1,客户区 DC 原点即画面左上角、不含标题栏,故无偏移、无缩放。
+        """
+        self.desktop_window_restore_if_minimized()
+        with dpi_awareness():
+            client_rect = GetClientRect(self.screenshot_handle_num)
+            widthScreen = client_rect[2] - client_rect[0]
+            heightScreen = client_rect[3] - client_rect[1]
+            if widthScreen <= 0 or heightScreen <= 0:
+                # 最小化时客户区为 0x0,取不到内容(窗口被遮挡则可以)
+                raise RequestHumanTakeover(
+                    'Desktop client window is minimized, screenshot unavailable. '
+                    '请恢复游戏窗口(可被其他窗口遮挡,但不能最小化)'
+                )
+            hwndDc = GetDC(self.screenshot_handle_num)
+            mfcDc = CreateDCFromHandle(hwndDc)
+            saveDc = mfcDc.CreateCompatibleDC()
+            saveBitMap = CreateBitmap()
+            saveBitMap.CreateCompatibleBitmap(mfcDc, widthScreen, heightScreen)
+            saveDc.SelectObject(saveBitMap)
+            saveDc.BitBlt((0, 0), (widthScreen, heightScreen), mfcDc, (0, 0), SRCCOPY)
+            signedIntsArray = saveBitMap.GetBitmapBits(True)
+            imgSrceen = frombuffer(signedIntsArray, dtype='uint8')
+            imgSrceen.shape = (heightScreen, widthScreen, 4)
+            imgSrceen = cv2.cvtColor(imgSrceen, cv2.COLOR_BGR2RGB)
+            DeleteObject(saveBitMap.GetHandle())
+            saveDc.DeleteDC()
+            mfcDc.DeleteDC()
+        # 客户端锁定大小导致未校准到目标尺寸时兜底缩放,保证与资产同尺寸
+        target_w, target_h = self.screenshot_size
+        if (widthScreen, heightScreen) != (target_w, target_h):
+            imgSrceen = cv2.resize(imgSrceen, (target_w, target_h))
+        return imgSrceen
+
     @cached_property
     @cached_property
     def control_handle_list(self) -> list:
     def control_handle_list(self) -> list:
         """
         """
@@ -90,6 +135,9 @@ class Window(Handle):
         :return:
         :return:
         """
         """
         result = []
         result = []
+        if getattr(self, 'is_desktop_window', False):
+            # 桌面客户端无子渲染窗口,控制句柄即根窗口
+            return [self.root_handle_num]
         if self.emulator_family == EmulatorFamily.FAMILY_MUMU:
         if self.emulator_family == EmulatorFamily.FAMILY_MUMU:
             result.append(self.root_node.num)
             result.append(self.root_node.num)
             result.append(self.root_node.children[0].num)
             result.append(self.root_node.children[0].num)
@@ -141,6 +189,8 @@ class Window(Handle):
         :param fast:
         :param fast:
         :return:
         :return:
         """
         """
+        if getattr(self, 'is_desktop_window', False):
+            return self.click_desktop_window_message(x, y, fast)
         # 我不知道为什么的使用的pywin32==306的版本会导致获取的图片的是(1024, 576)
         # 我不知道为什么的使用的pywin32==306的版本会导致获取的图片的是(1024, 576)
         # 所有我在点击的时候会除以这个缩放比例
         # 所有我在点击的时候会除以这个缩放比例
         # 但是后面发现又不是影响的很奇怪
         # 但是后面发现又不是影响的很奇怪
@@ -173,6 +223,72 @@ class Window(Handle):
             time.sleep(press_time)
             time.sleep(press_time)
             SendMessage(self.control_handle_list[0], WM_LBUTTONUP, 0, clickPos)
             SendMessage(self.control_handle_list[0], WM_LBUTTONUP, 0, clickPos)
 
 
+    def desktop_message_coord(self, x, y) -> tuple:
+        """把资产坐标(截图空间 1280x720)换算成窗口消息坐标。
+
+        截图在 DPI 感知上下文内取得,是物理像素;PostMessage 由 DPI-unaware 的
+        OAS 进程发出,lParam 会被系统按虚拟化空间解释,两者相差系统缩放比。
+        """
+        target_w, target_h = self.screenshot_size
+        virtual_w, virtual_h = self.desktop_client_size_virtual()
+        return int(round(x * virtual_w / target_w)), int(round(y * virtual_h / target_h))
+
+    def _desktop_press(self, x: int, y: int, press_time: float) -> None:
+        """后台按下并保持 press_time 秒。
+
+        客户端是鼠标语义(不是模拟器的触摸协议),控件依赖 hover 状态,必须先把
+        鼠标沿轨迹移到目标点再按下;抬起后补一次移动刷新悬停状态。
+        """
+        self.desktop_window_restore_if_minimized()
+        hwnd = self.root_handle_num
+        self.move_desktop_window_message(x, y)
+        lparam = MAKELONG(*self.desktop_message_coord(x, y))
+        PostMessage(hwnd, WM_LBUTTONDOWN, MK_LBUTTON, lparam)
+        time.sleep(press_time)
+        PostMessage(hwnd, WM_LBUTTONUP, 0, lparam)
+        SendMessage(hwnd, WM_CAPTURECHANGED, 0, 0)
+        PostMessage(hwnd, WM_MOUSEMOVE, 0, lparam)
+
+    def click_desktop_window_message(self, x: int, y: int, fast: bool = False):
+        """桌面客户端后台点击,入参为客户区(1280x720)坐标。
+
+        按压时长只保留随机抖动:点击由客户端按 down/up 事件判定,不需要真人按压。
+        """
+        press_time: float = (random.randint(10, 25) if fast else random.randint(30, 60)) / 1000.0
+        self._desktop_press(x, y, press_time)
+
+    def long_click_desktop_window_message(self, x: int, y: int, duration: float):
+        """桌面客户端后台长按,duration 单位秒。"""
+        self._desktop_press(x, y, duration)
+
+    def move_desktop_window_message(self, x: int, y: int) -> None:
+        """桌面客户端后台鼠标移动:从上一落点沿拟人轨迹移到 (x, y),入参为资产坐标。
+
+        _desktop_cursor 记录当前位置,使连续操作之间的移动连贯。移动只为让客户端
+        更新悬停状态,因此按 DESKTOP_MOVE_STEP 取点并抽稀到点数上限,
+        长距离移动的耗时与距离解耦。
+        """
+        hwnd = self.root_handle_num
+        start = getattr(self, '_desktop_cursor', None)
+        target = (int(x), int(y))
+
+        def post_move(px, py):
+            PostMessage(hwnd, WM_MOUSEMOVE, 0, MAKELONG(*self.desktop_message_coord(px, py)))
+
+        if start is None or start == target:
+            # 没有历史位置(首次操作)或原地不动:直接发一次移动
+            post_move(target[0], target[1])
+            self._desktop_cursor = target
+            return
+        trace = human_track(start, target, interval=self.DESKTOP_MOVE_STEP)
+        if len(trace) > self.DESKTOP_MOVE_MAX_POINTS:
+            step = len(trace) / self.DESKTOP_MOVE_MAX_POINTS
+            trace = [trace[int(i * step)] for i in range(self.DESKTOP_MOVE_MAX_POINTS)]
+        for px, py in trace:
+            post_move(px, py)
+        post_move(target[0], target[1])
+        self._desktop_cursor = target
+
     def long_click_window_message(self, x: int, y: int, duration: float):
     def long_click_window_message(self, x: int, y: int, duration: float):
         """
         """
 
 
@@ -181,6 +297,8 @@ class Window(Handle):
         :param duration: 持续时间 单位秒
         :param duration: 持续时间 单位秒
         :return:
         :return:
         """
         """
+        if getattr(self, 'is_desktop_window', False):
+            return self.long_click_desktop_window_message(x, y, duration)
         # 我不知道为什么的使用的pywin32==306的版本会导致获取的图片的是(1024, 576)
         # 我不知道为什么的使用的pywin32==306的版本会导致获取的图片的是(1024, 576)
         # 所有我在点击的时候会除以这个缩放比例
         # 所有我在点击的时候会除以这个缩放比例
         x = int(x / self.window_scale_rate)
         x = int(x / self.window_scale_rate)
@@ -214,21 +332,11 @@ class Window(Handle):
         :param endPos:
         :param endPos:
         :return:
         :return:
         """
         """
+        if getattr(self, 'is_desktop_window', False):
+            return self.swipe_desktop_window_message(startPos, endPos)
         # 生成的坐标点列表
         # 生成的坐标点列表
         interval: int = 10  # 每次移动的间隔时间
         interval: int = 10  # 每次移动的间隔时间
-        numberList: int = int(dist(startPos, endPos) / (1 * interval))  # 表示每毫秒移动1.5个像素点, 总的时间除以每个点10ms就得到总的点的个数
-        le = random.randint(2, 4)  #
-        deviation = random.randint(20, 40)  # 幅度
-        _type: int = 3
-        obbsType = random.random()  # 0.8的概率是先快中间慢后面快, 0.1概率是先快后慢, 0.1概率先慢后快
-        if 0 < obbsType <= 0.8:
-            _type = 3
-        elif obbsType < 0.9:
-            _type = 2
-        else:
-            _type = 1
-        trace: list = BezierTrajectory.trackArray(start=startPos, end=endPos, numberList=numberList, le=le,
-                                                  deviation=deviation, bias=0.5, type=_type, cbb=0, yhh=20)
+        trace: list = human_track(startPos, endPos, interval=interval)
 
 
         # 使用生成的点列表进行拖拽
         # 使用生成的点列表进行拖拽
         handleNum = None
         handleNum = None
@@ -266,6 +374,32 @@ class Window(Handle):
         end_lparam = MAKELONG(trace[-1][0], trace[-1][1])
         end_lparam = MAKELONG(trace[-1][0], trace[-1][1])
         PostMessage(handleNum, WM_LBUTTONUP, 0, end_lparam)
         PostMessage(handleNum, WM_LBUTTONUP, 0, end_lparam)
 
 
+    def swipe_desktop_window_message(self, startPos: list, endPos: list) -> None:
+        """桌面客户端后台滑动:与模拟器同一套拟人轨迹,坐标换算到消息空间后逐点投递。"""
+        self.desktop_window_restore_if_minimized()
+        hwnd = self.root_handle_num
+        interval: int = 10
+        trace = human_track(startPos, endPos, interval=interval)
+        # 先移到起点再按下:客户端靠 hover 状态识别拖拽
+        self.move_desktop_window_message(startPos[0], startPos[1])
+        start_lparam = MAKELONG(*self.desktop_message_coord(startPos[0], startPos[1]))
+        PostMessage(hwnd, WM_LBUTTONDOWN, MK_LBUTTON, start_lparam)
+        # 最后几个点放慢,避免被判定为瞬移
+        manual_control: int = 3
+        total_len: int = len(trace)
+        for index, pos in enumerate(trace):
+            lparam = MAKELONG(*self.desktop_message_coord(pos[0], pos[1]))
+            PostMessage(hwnd, WM_MOUSEMOVE, MK_LBUTTON, lparam)
+            if manual_control >= total_len - index:
+                time.sleep(0.08)
+            else:
+                time.sleep((interval + random.randint(-2, 2)) / 1000.0)
+        time.sleep(0.05)
+        end_lparam = MAKELONG(*self.desktop_message_coord(endPos[0], endPos[1]))
+        PostMessage(hwnd, WM_LBUTTONUP, 0, end_lparam)
+        SendMessage(hwnd, WM_CAPTURECHANGED, 0, 0)
+        self._desktop_cursor = (int(endPos[0]), int(endPos[1]))
+
     def swipe_vector_window_message2(self, startPos: list, endPos: list) -> None:
     def swipe_vector_window_message2(self, startPos: list, endPos: list) -> None:
         """
         """
         后台滑动, 直线滑动
         后台滑动, 直线滑动