VirtualDesktop 1.3.1__tar.gz → 1.4.0__tar.gz

{virtualdesktop-1.3.1 → virtualdesktop-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: VirtualDesktop
-Version: 1.3.1
+Version: 1.4.0
 Summary: Multi-window virtual-display workspaces on Windows: one pip install bootstraps the virtual display driver, hosts programs on a virtual or private desktop, keeps them off the physical screens, and hands out real window handles for automation and PrintWindow capture.
 Author: VirtualDesktop contributors
 License: MIT License
@@ -84,14 +84,52 @@ uv add VirtualDesktop             # uv（写入 pyproject.toml 并锁定）
 | | 私有桌面 | 虚拟显示器 |
 |---|---|---|
 | 一句话 | 另开一个桌面，窗口与你的桌面完全隔离 | 多一块屏幕，窗口仍在你的桌面上、只是画在看不见的地方 |
-| 隔离强度 | **强**：独立窗口命名空间，外部进程看不到、碰不到 | **弱**：窗口是普通窗口，任何程序都能找到并操作它 |
+| 底层 | 内核**对象**（`CreateDesktopW`），独立窗口命名空间 + DACL | 显示**设备**（IddCx 驱动），系统多出一块 `\\.\DISPLAYn` |
 | 需要权限 | **零**：不需要驱动、不弹 UAC | 装一次驱动，弹**一次 UAC** |
-| 能截图吗 | **不能**（窗口截图、桌面截图都不行） | **能**（两种都行） |
-| 外部自动化库能用吗 | **不能**（要在桌面内跑代理） | **能**（pywinauto / UIA / pyautogui 直接用） |
-| 适合 | 多实例并行、强隔离、不要截图 | UI 自动化、截图 OCR、无人值守抓界面 |
+| 系统要求 | Win10 / 11 任意 | Win10 1809 (17763) 起 |
+| 程序窗口截图 | **不能** | **能** |
+| 桌面截图 | **不能** | **能** |
+| 读窗口属性 / 枚举子控件 | 能（桌面内代理） | 能（外部进程直接） |
+| 点击控件 / 送入字符 | 能（窗口消息） | 能（消息 + 真实输入） |
+| 真实鼠标 / 滚轮 / 键盘 | **不能** | **能** |
+| 外部 pywinauto / pyautogui 直接驱动 | **不能** | **能** |
+| 窗口跨桌面搬运 | **不能**（Windows 限制） | 能（在显示器之间移动） |
+| 推荐场景 | 多实例并行、强隔离、不要截图 | UI 自动化、截图 OCR、无人值守抓界面 |
 
-> **只想跑一个窗口、要截图** → 用虚拟显示器侧的 `OffscreenSession`，最省事。
-> **要多个实例互不干扰、不需要截图** → 用私有桌面。
+### 隔离强度分级
+
+两套方案的隔离**不是"强/弱"两档，而是三个层面各不相同**，按你需要防住什么来选：
+
+| 隔离层面 | 私有桌面 | 虚拟显示器 | 说明 |
+|---|---|---|---|
+| 窗口**发现**（能否枚举到） | **隔离** | 不隔离 | 私有桌面：`EnumWindows`/`FindWindow` 从外部看不到 |
+| 窗口**输入**（真实鼠标键盘） | **隔离** | 不隔离 | 私有桌面：没有活动指针与键盘焦点 |
+| 窗口**截图**（像素可读性） | **隔离** | 不隔离 | 私有桌面：从不参与系统合成，没有像素 |
+| 窗口**消息**（`SendMessage` 等） | **不隔离** | 不隔离 | 拿到句柄即可投递消息，DACL 保护的是桌面对象而不是窗口消息 |
+| 进程**生命周期** | **隔离** | 不隔离 | 私有桌面关闭时其上进程一并结束；虚拟显示器上的程序由你负责 |
+
+> 关键提醒：私有桌面**不等于**"完全无法访问"。它挡的是**发现**、**输入**和**截图**，
+> 挡不住"已知句柄后投递消息"。所以不要把私有桌面当作进程级安全沙箱使用——它没有降低
+> 目标进程的权限，只是把它挪到了另一个窗口命名空间。
+
+### 推荐怎么选
+
+```
+要截图（窗口截图或桌面截图）              → 虚拟显示器
+要用真实鼠标 / 滚轮 / 键盘，或 pyautogui    → 虚拟显示器
+要用 pywinauto / UIA 从外部直接驱动窗口     → 虚拟显示器
+只处理一个窗口、要截图，越省事越好          → OffscreenSession（虚拟显示器侧）
+─────────────────────────────────────────────────────────────
+要多个实例互不干扰、且不需要截图            → 私有桌面
+不能弹 UAC、不能装驱动                     → 私有桌面
+要"退出后什么都不留"（进程随桌面一起结束）   → 私有桌面
+需要窗口完全不出现在任何可见位置          → 私有桌面
+```
+
+两条常用组合：
+
+- **只是想安静地跑一个窗口并抓图** → `OffscreenSession` + `virtual_screen`
+- **想并行跑很多互不干扰的实例** → 每个实例一个 `VirtualWorkspace("名字")`
 
 ---
 
@@ -169,6 +207,7 @@ with VirtualWorkspace("lab") as space, space.agent() as agent:
 | `agent.adopt(pid)` | 接上桌面内已在运行的程序 |
 | `agent.info(window)` | 标题、类名、矩形、`child_count`、`buttons` |
 | `agent.text(window)` | 窗口标题 |
+| `agent.uia_tree(window)` | 完整 UIA 树（在桌面内遍历） |
 | `agent.click(window, text=/index=)` | 点击控件（走窗口消息，见下） |
 | `agent.keys(window, "...")` | 送入字符（走窗口消息） |
 | `agent.windows()` | 该桌面上的窗口清单 |
@@ -210,6 +249,38 @@ with VirtualWorkspace("lab") as space, space.agent() as agent:
 要点：**能用消息驱动的都能用，需要真实输入设备的都不能用，两种截图都不能用**。需要截图或需要
 真实鼠标/滚轮的应用，请改用下面的虚拟显示器方案。
 
+## 支持的能力与调用方式
+
+| 能力 | 是否支持 | 怎么调 |
+|---|---|---|
+| 在一个桌面里跑多个程序 | **支持** | 连续 `agent.launch([...])`，各自拿到不同句柄 |
+| 多个独立桌面同时在线 | **支持** | 多个 `VirtualWorkspace("名字")` 并存，句柄与名字互不相同 |
+| 拿到窗口句柄 | **支持** | `agent.launch([...]).hwnd` / `agent.adopt(pid).hwnd` / `desktop.find_window(pid)` |
+| 读标题 / 类名 / 矩形 / 尺寸 | **支持** | `agent.info(window)` |
+| 枚举子控件与按钮文字 | **支持** | `agent.info(window)["child_count"]` / `["buttons"]` |
+| 完整 UIA 树 | **支持** | `agent.uia_tree(window)` |
+| 点击控件 / 送入字符 | **支持** | `agent.click(window, text=...)` / `agent.keys(window, "...")` |
+| 在桌面内跑任意 Python | **支持** | `agent.exec("...")`（可用 comtypes、pywinauto） |
+| 程序窗口截图 / 桌面截图 | **不支持** | 见上方原因；改用虚拟显示器 |
+| 跨桌面搬运窗口、移到主屏 | **不支持** | `move_to` 一律报 `cannot-cross-desktop`；只能在目标桌面重新 `launch` |
+
+`agent.uia_tree()` 在**桌面内**遍历 UIA，这是私有桌面唯一可用的取树方式：
+
+```python
+with VirtualWorkspace("lab") as space, space.agent() as agent:
+    window = agent.launch(["charmap.exe"])
+    tree = agent.uia_tree(window)          # view="RawView" 默认；也可 ControlView / ContentView
+    print(tree["count"])
+    for node in tree["nodes"][:5]:
+        print(node["control"], node["name"], node["enabled"])
+```
+
+> 不要用 `GetRootElement()`：它属于**输入桌面**，在私有桌面里走它拿不到任何目标窗口。
+> 库内部用的是 `ElementFromHandle(hwnd)`。
+
+> 在里面用 comtypes / pywinauto 是安全的：窗口枚举已不再绑定调用者线程，所以
+> `from pywinauto import Application` 放在文件顶部也不会影响私有桌面。
+
 ---
 
 # 第二部分：虚拟显示器
@@ -424,6 +495,26 @@ print(current_primary_size())                            # (1920, 1080)
 > 用真实输入时，窗口所在显示器必须是活动桌面的一部分；`pyautogui` 这类库还需要窗口能取得前台
 > 焦点。若目标窗口拿不到焦点，请改用消息驱动（`agent.click()` / `WM_CHAR`）。
 
+## 支持的能力与调用方式
+
+| 能力 | 是否支持 | 怎么调 |
+|---|---|---|
+| 在一个工作区里跑多个程序 | **支持** | 连续 `ws.launch([...])`，运行中可随时新增 |
+| 多个工作区同时在线 | **支持** | 多个 `VirtualWorkspace(SHARED)` 并存，各自独立停靠位 |
+| 拿到窗口句柄给外部用 | **支持** | `ws.describe()["windows"]`（真实 HWND，无包装） |
+| 读标题 / 类名 / 矩形 | **支持** | 外部 pywinauto 直接读，或 `ws.windows()` |
+| 枚举子控件 | **支持** | 外部 pywinauto `children(visible_only=False)` |
+| 完整 UIA 树 | **支持** | 外部 UIA，或 `--ui-tree DIR` |
+| 程序窗口截图 | **支持** | `ws.capture(hwnd, save_to=...)` / `CaptureEngine.capture(hwnd)` |
+| 桌面截图 | **支持**（`virtual_screen`） | `ws.capture_desktop()` / `capture_monitor()` / `capture_all_screens()` |
+| 真实鼠标 / 滚轮 / 键盘 | **支持**（`virtual_screen`） | pywinauto `click_input()` / `type_keys()`，或 pyautogui |
+| 在显示器之间移动窗口 | **支持** | `move_to("\\\\.\\DISPLAY2")` / `move_all_to(...)` / `move_to_primary()` |
+| 退出时还原窗口 | **支持** | `with` 退出自动还原；异常退出同样还原 |
+| 退出时卸载驱动 | **支持** | `uninstall_on_exit=True` 或 `close(uninstall=True)` |
+| 桌面截图（`offscreen` 模式） | **不支持** | 窗口在所有显示器之外，拍不到；改用 `virtual_screen` |
+| 真实鼠标 / 滚轮 / 键盘（`offscreen`） | **不支持** | 同上：指针被钳制回屏幕边缘 |
+| 跨私有桌面搬运窗口 | **不支持** | Windows 不允许；`move_to` 会明确报错 |
+
 ---
 
 # 通用功能
@@ -464,7 +555,8 @@ VIRTUALDESKTOP_LOG_FILE=<path>
 | `ElevationDenied` | UAC 被取消或被策略阻止 | 在管理员终端执行一次 `VirtualDesktop install-driver` |
 | `unsupported-windows-build` | 系统低于 Win10 1809，没有 IddCx | 换系统，或用私有桌面（不需要驱动） |
 | `capture-needs-shared-workspace` | 想截私有桌面里的窗口 | 私有桌面不支持截图，改用虚拟显示器 |
-| `SetThreadDesktop ... error 170` | 当前线程已有窗口，无法再绑定桌面 | 在创建窗口之前 `bind_thread()`，或用 `agent()` |
+| `SetThreadDesktop ... error 170` | 你自己在绑定线程，而该线程已有窗口或已初始化 COM | 直接调用 `bind_thread()` 时才会遇到；库内部的枚举不再绑定调用者线程 |
+| 某程序在私有桌面上找不到窗口 | 控制台类程序（`cmd.exe`、`ping.exe`）的窗口属于 `conhost.exe`，不在自己 pid 下 | 报错会提示；用 `agent.exec()` 在桌面内驱动它，或换 GUI 程序 |
 | 安装后没出现新的虚拟屏 | 驱动已注册但显示器未启用 | 设备管理器启用；`report.requires_reboot` 为真时重启 |
 | 驱动下载失败或极慢 | github.com 不可达 | 设 `VIRTUALDESKTOP_GITHUB_MIRRORS`，或预置离线缓存 |
 | 窗口截图是黑帧 | 应用为硬件加速 / 受保护内容 | 系统限制；换 `bitblt` 试试，或确认窗口有内容 |
@@ -472,7 +564,6 @@ VIRTUALDESKTOP_LOG_FILE=<path>
 | 桌面截图拍不到工作区窗口 | 用了 `offscreen`，窗口在所有显示器之外 | 改用 `hide_mode="virtual_screen"` |
 | `capture_desktop()` 报"workspace is not open" | offscreen 模式下没有绑定显示器 | 改用 `capture_all_screens()`，或用 `virtual_screen` |
 | 真实鼠标点击无效 | 窗口在屏幕之外，或拿不到前台焦点 | 用 `virtual_screen`，或改用消息驱动 |
-| 某程序在私有桌面上找不到窗口 | 控制台类（cmd）等窗口不参与常规枚举 | 换程序，或用 `agent.exec()` 在桌面内直接操作 |
 
 **离线 / 内网部署**：把安装包按清单里的文件名（`VirtualDesktop/driver_manifest.json` 的
 `artifact.filename`）放进 `VIRTUALDESKTOP_CACHE_DIR` 即可，不会联网；也可用

{virtualdesktop-1.3.1 → virtualdesktop-1.4.0}/README.md

@@ -28,14 +28,52 @@ uv add VirtualDesktop             # uv（写入 pyproject.toml 并锁定）
 | | 私有桌面 | 虚拟显示器 |
 |---|---|---|
 | 一句话 | 另开一个桌面，窗口与你的桌面完全隔离 | 多一块屏幕，窗口仍在你的桌面上、只是画在看不见的地方 |
-| 隔离强度 | **强**：独立窗口命名空间，外部进程看不到、碰不到 | **弱**：窗口是普通窗口，任何程序都能找到并操作它 |
+| 底层 | 内核**对象**（`CreateDesktopW`），独立窗口命名空间 + DACL | 显示**设备**（IddCx 驱动），系统多出一块 `\\.\DISPLAYn` |
 | 需要权限 | **零**：不需要驱动、不弹 UAC | 装一次驱动，弹**一次 UAC** |
-| 能截图吗 | **不能**（窗口截图、桌面截图都不行） | **能**（两种都行） |
-| 外部自动化库能用吗 | **不能**（要在桌面内跑代理） | **能**（pywinauto / UIA / pyautogui 直接用） |
-| 适合 | 多实例并行、强隔离、不要截图 | UI 自动化、截图 OCR、无人值守抓界面 |
+| 系统要求 | Win10 / 11 任意 | Win10 1809 (17763) 起 |
+| 程序窗口截图 | **不能** | **能** |
+| 桌面截图 | **不能** | **能** |
+| 读窗口属性 / 枚举子控件 | 能（桌面内代理） | 能（外部进程直接） |
+| 点击控件 / 送入字符 | 能（窗口消息） | 能（消息 + 真实输入） |
+| 真实鼠标 / 滚轮 / 键盘 | **不能** | **能** |
+| 外部 pywinauto / pyautogui 直接驱动 | **不能** | **能** |
+| 窗口跨桌面搬运 | **不能**（Windows 限制） | 能（在显示器之间移动） |
+| 推荐场景 | 多实例并行、强隔离、不要截图 | UI 自动化、截图 OCR、无人值守抓界面 |
 
-> **只想跑一个窗口、要截图** → 用虚拟显示器侧的 `OffscreenSession`，最省事。
-> **要多个实例互不干扰、不需要截图** → 用私有桌面。
+### 隔离强度分级
+
+两套方案的隔离**不是"强/弱"两档，而是三个层面各不相同**，按你需要防住什么来选：
+
+| 隔离层面 | 私有桌面 | 虚拟显示器 | 说明 |
+|---|---|---|---|
+| 窗口**发现**（能否枚举到） | **隔离** | 不隔离 | 私有桌面：`EnumWindows`/`FindWindow` 从外部看不到 |
+| 窗口**输入**（真实鼠标键盘） | **隔离** | 不隔离 | 私有桌面：没有活动指针与键盘焦点 |
+| 窗口**截图**（像素可读性） | **隔离** | 不隔离 | 私有桌面：从不参与系统合成，没有像素 |
+| 窗口**消息**（`SendMessage` 等） | **不隔离** | 不隔离 | 拿到句柄即可投递消息，DACL 保护的是桌面对象而不是窗口消息 |
+| 进程**生命周期** | **隔离** | 不隔离 | 私有桌面关闭时其上进程一并结束；虚拟显示器上的程序由你负责 |
+
+> 关键提醒：私有桌面**不等于**"完全无法访问"。它挡的是**发现**、**输入**和**截图**，
+> 挡不住"已知句柄后投递消息"。所以不要把私有桌面当作进程级安全沙箱使用——它没有降低
+> 目标进程的权限，只是把它挪到了另一个窗口命名空间。
+
+### 推荐怎么选
+
+```
+要截图（窗口截图或桌面截图）              → 虚拟显示器
+要用真实鼠标 / 滚轮 / 键盘，或 pyautogui    → 虚拟显示器
+要用 pywinauto / UIA 从外部直接驱动窗口     → 虚拟显示器
+只处理一个窗口、要截图，越省事越好          → OffscreenSession（虚拟显示器侧）
+─────────────────────────────────────────────────────────────
+要多个实例互不干扰、且不需要截图            → 私有桌面
+不能弹 UAC、不能装驱动                     → 私有桌面
+要"退出后什么都不留"（进程随桌面一起结束）   → 私有桌面
+需要窗口完全不出现在任何可见位置          → 私有桌面
+```
+
+两条常用组合：
+
+- **只是想安静地跑一个窗口并抓图** → `OffscreenSession` + `virtual_screen`
+- **想并行跑很多互不干扰的实例** → 每个实例一个 `VirtualWorkspace("名字")`
 
 ---
 
@@ -113,6 +151,7 @@ with VirtualWorkspace("lab") as space, space.agent() as agent:
 | `agent.adopt(pid)` | 接上桌面内已在运行的程序 |
 | `agent.info(window)` | 标题、类名、矩形、`child_count`、`buttons` |
 | `agent.text(window)` | 窗口标题 |
+| `agent.uia_tree(window)` | 完整 UIA 树（在桌面内遍历） |
 | `agent.click(window, text=/index=)` | 点击控件（走窗口消息，见下） |
 | `agent.keys(window, "...")` | 送入字符（走窗口消息） |
 | `agent.windows()` | 该桌面上的窗口清单 |
@@ -154,6 +193,38 @@ with VirtualWorkspace("lab") as space, space.agent() as agent:
 要点：**能用消息驱动的都能用，需要真实输入设备的都不能用，两种截图都不能用**。需要截图或需要
 真实鼠标/滚轮的应用，请改用下面的虚拟显示器方案。
 
+## 支持的能力与调用方式
+
+| 能力 | 是否支持 | 怎么调 |
+|---|---|---|
+| 在一个桌面里跑多个程序 | **支持** | 连续 `agent.launch([...])`，各自拿到不同句柄 |
+| 多个独立桌面同时在线 | **支持** | 多个 `VirtualWorkspace("名字")` 并存，句柄与名字互不相同 |
+| 拿到窗口句柄 | **支持** | `agent.launch([...]).hwnd` / `agent.adopt(pid).hwnd` / `desktop.find_window(pid)` |
+| 读标题 / 类名 / 矩形 / 尺寸 | **支持** | `agent.info(window)` |
+| 枚举子控件与按钮文字 | **支持** | `agent.info(window)["child_count"]` / `["buttons"]` |
+| 完整 UIA 树 | **支持** | `agent.uia_tree(window)` |
+| 点击控件 / 送入字符 | **支持** | `agent.click(window, text=...)` / `agent.keys(window, "...")` |
+| 在桌面内跑任意 Python | **支持** | `agent.exec("...")`（可用 comtypes、pywinauto） |
+| 程序窗口截图 / 桌面截图 | **不支持** | 见上方原因；改用虚拟显示器 |
+| 跨桌面搬运窗口、移到主屏 | **不支持** | `move_to` 一律报 `cannot-cross-desktop`；只能在目标桌面重新 `launch` |
+
+`agent.uia_tree()` 在**桌面内**遍历 UIA，这是私有桌面唯一可用的取树方式：
+
+```python
+with VirtualWorkspace("lab") as space, space.agent() as agent:
+    window = agent.launch(["charmap.exe"])
+    tree = agent.uia_tree(window)          # view="RawView" 默认；也可 ControlView / ContentView
+    print(tree["count"])
+    for node in tree["nodes"][:5]:
+        print(node["control"], node["name"], node["enabled"])
+```
+
+> 不要用 `GetRootElement()`：它属于**输入桌面**，在私有桌面里走它拿不到任何目标窗口。
+> 库内部用的是 `ElementFromHandle(hwnd)`。
+
+> 在里面用 comtypes / pywinauto 是安全的：窗口枚举已不再绑定调用者线程，所以
+> `from pywinauto import Application` 放在文件顶部也不会影响私有桌面。
+
 ---
 
 # 第二部分：虚拟显示器
@@ -368,6 +439,26 @@ print(current_primary_size())                            # (1920, 1080)
 > 用真实输入时，窗口所在显示器必须是活动桌面的一部分；`pyautogui` 这类库还需要窗口能取得前台
 > 焦点。若目标窗口拿不到焦点，请改用消息驱动（`agent.click()` / `WM_CHAR`）。
 
+## 支持的能力与调用方式
+
+| 能力 | 是否支持 | 怎么调 |
+|---|---|---|
+| 在一个工作区里跑多个程序 | **支持** | 连续 `ws.launch([...])`，运行中可随时新增 |
+| 多个工作区同时在线 | **支持** | 多个 `VirtualWorkspace(SHARED)` 并存，各自独立停靠位 |
+| 拿到窗口句柄给外部用 | **支持** | `ws.describe()["windows"]`（真实 HWND，无包装） |
+| 读标题 / 类名 / 矩形 | **支持** | 外部 pywinauto 直接读，或 `ws.windows()` |
+| 枚举子控件 | **支持** | 外部 pywinauto `children(visible_only=False)` |
+| 完整 UIA 树 | **支持** | 外部 UIA，或 `--ui-tree DIR` |
+| 程序窗口截图 | **支持** | `ws.capture(hwnd, save_to=...)` / `CaptureEngine.capture(hwnd)` |
+| 桌面截图 | **支持**（`virtual_screen`） | `ws.capture_desktop()` / `capture_monitor()` / `capture_all_screens()` |
+| 真实鼠标 / 滚轮 / 键盘 | **支持**（`virtual_screen`） | pywinauto `click_input()` / `type_keys()`，或 pyautogui |
+| 在显示器之间移动窗口 | **支持** | `move_to("\\\\.\\DISPLAY2")` / `move_all_to(...)` / `move_to_primary()` |
+| 退出时还原窗口 | **支持** | `with` 退出自动还原；异常退出同样还原 |
+| 退出时卸载驱动 | **支持** | `uninstall_on_exit=True` 或 `close(uninstall=True)` |
+| 桌面截图（`offscreen` 模式） | **不支持** | 窗口在所有显示器之外，拍不到；改用 `virtual_screen` |
+| 真实鼠标 / 滚轮 / 键盘（`offscreen`） | **不支持** | 同上：指针被钳制回屏幕边缘 |
+| 跨私有桌面搬运窗口 | **不支持** | Windows 不允许；`move_to` 会明确报错 |
+
 ---
 
 # 通用功能
@@ -408,7 +499,8 @@ VIRTUALDESKTOP_LOG_FILE=<path>
 | `ElevationDenied` | UAC 被取消或被策略阻止 | 在管理员终端执行一次 `VirtualDesktop install-driver` |
 | `unsupported-windows-build` | 系统低于 Win10 1809，没有 IddCx | 换系统，或用私有桌面（不需要驱动） |
 | `capture-needs-shared-workspace` | 想截私有桌面里的窗口 | 私有桌面不支持截图，改用虚拟显示器 |
-| `SetThreadDesktop ... error 170` | 当前线程已有窗口，无法再绑定桌面 | 在创建窗口之前 `bind_thread()`，或用 `agent()` |
+| `SetThreadDesktop ... error 170` | 你自己在绑定线程，而该线程已有窗口或已初始化 COM | 直接调用 `bind_thread()` 时才会遇到；库内部的枚举不再绑定调用者线程 |
+| 某程序在私有桌面上找不到窗口 | 控制台类程序（`cmd.exe`、`ping.exe`）的窗口属于 `conhost.exe`，不在自己 pid 下 | 报错会提示；用 `agent.exec()` 在桌面内驱动它，或换 GUI 程序 |
 | 安装后没出现新的虚拟屏 | 驱动已注册但显示器未启用 | 设备管理器启用；`report.requires_reboot` 为真时重启 |
 | 驱动下载失败或极慢 | github.com 不可达 | 设 `VIRTUALDESKTOP_GITHUB_MIRRORS`，或预置离线缓存 |
 | 窗口截图是黑帧 | 应用为硬件加速 / 受保护内容 | 系统限制；换 `bitblt` 试试，或确认窗口有内容 |
@@ -416,7 +508,6 @@ VIRTUALDESKTOP_LOG_FILE=<path>
 | 桌面截图拍不到工作区窗口 | 用了 `offscreen`，窗口在所有显示器之外 | 改用 `hide_mode="virtual_screen"` |
 | `capture_desktop()` 报"workspace is not open" | offscreen 模式下没有绑定显示器 | 改用 `capture_all_screens()`，或用 `virtual_screen` |
 | 真实鼠标点击无效 | 窗口在屏幕之外，或拿不到前台焦点 | 用 `virtual_screen`，或改用消息驱动 |
-| 某程序在私有桌面上找不到窗口 | 控制台类（cmd）等窗口不参与常规枚举 | 换程序，或用 `agent.exec()` 在桌面内直接操作 |
 
 **离线 / 内网部署**：把安装包按清单里的文件名（`VirtualDesktop/driver_manifest.json` 的
 `artifact.filename`）放进 `VIRTUALDESKTOP_CACHE_DIR` 即可，不会联网；也可用

{virtualdesktop-1.3.1 → virtualdesktop-1.4.0}/VirtualDesktop/__init__.py

@@ -63,7 +63,7 @@ from .workspace import SHARED, VirtualWorkspace, WorkspaceWindow
 from .agent import AgentProcess, AgentSession
 from .display_setup import configure_virtual_display, current_primary_dpi, current_primary_size
 
-__version__ = "1.3.1"
+__version__ = "1.4.0"
 
 __all__ = [
     "__version__",

{virtualdesktop-1.3.1 → virtualdesktop-1.4.0}/VirtualDesktop/_desktop_runtime.py

@@ -229,6 +229,81 @@ def _exec(code: str) -> dict:
     return {"ok": True, "stdout": buffer.getvalue()}
 
 
+def _uia_tree(hwnd: int, *, depth: int = 8, max_nodes: int = 500, view: str = "RawView") -> dict:
+    """Walk the UI Automation tree of ``hwnd`` **from inside this desktop**.
+
+    Uses ``ElementFromHandle`` rather than ``GetRootElement``: the root element belongs to the
+    *input* desktop, so from a private desktop it yields a single node and none of the application's
+    windows.  An element obtained from a handle is not restricted that way (measured: root -> 1
+    node, ``FromHandle`` -> the window's real subtree).
+
+    Running inside the desktop is the whole point: a UIA client elsewhere resolves elements against
+    the desktop it is attached to, so an outside dump returns nothing for a private desktop.
+    """
+    try:
+        import comtypes.client
+        from comtypes.gen import UIAutomationClient as UIA
+    except Exception as exc:  # noqa: BLE001 - comtypes is optional
+        return {
+            "ok": True,
+            "tree": {
+                "error": f"UI Automation unavailable inside the desktop: {type(exc).__name__}: {exc}",
+                "nodes": [],
+            },
+        }
+
+    automation = comtypes.client.CreateObject(UIA.CUIAutomation, interface=UIA.IUIAutomation)
+    root = automation.ElementFromHandle(hwnd)
+    if root is None:
+        return {"ok": True, "tree": {"error": "ElementFromHandle returned null", "nodes": []}}
+    walker = {
+        "RawView": automation.RawViewWalker,
+        "ControlView": automation.ControlViewWalker,
+        "ContentView": automation.ContentViewWalker,
+    }.get(view, automation.RawViewWalker)
+
+    nodes: list = []
+
+    def visit(element, level: int) -> None:
+        if level > depth or len(nodes) >= max_nodes:
+            return
+        try:
+            box = element.CurrentBoundingRectangle
+            nodes.append(
+                {
+                    "depth": level,
+                    "name": element.CurrentName or "",
+                    "control": str(element.CurrentControlType),
+                    "type_id": int(element.CurrentControlType),
+                    "automation": element.CurrentAutomationId or "",
+                    "class": element.CurrentClassName or "",
+                    "handle": int(element.CurrentNativeWindowHandle or 0),
+                    "x": int(box.left),
+                    "y": int(box.top),
+                    "w": int(box.right - box.left),
+                    "h": int(box.bottom - box.top),
+                    "enabled": bool(element.CurrentIsEnabled),
+                    "offscreen": bool(element.CurrentIsOffscreen),
+                    "focusable": bool(element.CurrentIsKeyboardFocusable),
+                }
+            )
+        except Exception:  # noqa: BLE001 - one dying element must not end the walk
+            return
+        try:
+            child = walker.GetFirstChildElement(element)
+        except Exception:  # noqa: BLE001
+            return
+        while child is not None and len(nodes) < max_nodes:
+            visit(child, level + 1)
+            try:
+                child = walker.GetNextSiblingElement(child)
+            except Exception:  # noqa: BLE001
+                break
+
+    visit(root, 0)
+    return {"ok": True, "tree": {"view": view, "count": len(nodes), "nodes": nodes}}
+
+
 def _handle(request: dict) -> dict:
     if not _kernel32.GetCurrentProcessId():  # pragma: no cover - keeps kernel32 referenced
         pass
@@ -246,6 +321,13 @@ def _handle(request: dict) -> dict:
         return _screenshot(int(request["hwnd"], 0), str(request["path"]))
     if command == "windows":
         return _windows()
+    if command == "uia_tree":
+        return _uia_tree(
+            int(request["hwnd"], 0),
+            depth=int(request.get("depth", 8)),
+            max_nodes=int(request.get("max_nodes", 500)),
+            view=str(request.get("view", "RawView")),
+        )
     if command == "exec":
         return _exec(str(request.get("code", "")))
     return {"ok": False, "error": f"unknown command {command!r}"}

virtualdesktop-1.4.0/VirtualDesktop/_enumerate.py

@@ -0,0 +1,97 @@
+"""One-shot window enumerator that runs *on* a private desktop.
+
+``VirtualDesktop.list_windows`` and ``find_window`` used to enumerate in-process after calling
+``SetThreadDesktop`` on the caller's thread.  That is fragile for a reason that has nothing to do
+with this library: ``SetThreadDesktop`` fails with ``ERROR_BUSY`` (170) once the thread owns any
+window or hook, and initialising COM/OLE — which merely **importing** pywinauto or comtypes does —
+creates a thread-scoped hidden window.  A caller who wrote the natural
+
+    from pywinauto import Application
+    from VirtualDesktop import VirtualWorkspace
+
+could therefore never use a private desktop at all, and the error said nothing about why.
+
+This helper removes the caller's thread from the picture: it is started **on** the desktop through
+``VirtualDesktop.launch`` (``CreateProcessW`` with ``lpDesktop``), so ``EnumWindows`` sees that
+desktop's windows from a thread that belongs to it.  It writes one JSON document and exits.
+
+Invoked by the library, not by users; this file is also fine to run by hand for debugging:
+
+    python _enumerate.py --out windows.json
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+# Started through CreateProcessW by absolute path, so this file's directory is on sys.path and its
+# parent (the package root) is what ``import VirtualDesktop`` needs.
+_PACKAGE_ROOT = Path(__file__).resolve().parent.parent
+if str(_PACKAGE_ROOT) not in sys.path:
+    sys.path.insert(0, str(_PACKAGE_ROOT))
+
+
+def _record_to_dict(record) -> dict:
+    """Reuse ``WindowRecord.to_dict`` so both enumeration paths return one shape."""
+    try:
+        return record.to_dict()
+    except Exception:  # noqa: BLE001 - fall back to the fields the callers rely on
+        return {
+            "hwnd": int(record.hwnd),
+            "title": record.title,
+            "class_name": record.class_name,
+            "pid": record.pid,
+            "process_name": record.process_name,
+            "visible": bool(record.visible),
+            "minimized": bool(record.minimized),
+            "rect": list(record.rect),
+            "owner": int(getattr(record, "owner", 0) or 0),
+            "tool_window": bool(getattr(record, "tool_window", False)),
+        }
+
+
+def enumerate_here() -> dict:
+    from VirtualDesktop import list_windows
+
+    return {
+        "ok": True,
+        "windows": [_record_to_dict(r) for r in list_windows()],
+    }
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--out", required=True, help="path of the JSON file to write")
+    parser.add_argument(
+        "--errors",
+        default="",
+        help="optional path to also receive a traceback when enumeration fails",
+    )
+    args = parser.parse_args()
+
+    out = Path(args.out)
+    try:
+        payload = enumerate_here()
+    except BaseException as exc:  # noqa: BLE001 - the parent needs the reason, not a silent exit
+        import traceback
+
+        text = f"{type(exc).__name__}: {exc}\n\n{traceback.format_exc()}"
+        payload = {"ok": False, "error": text}
+        if args.errors:
+            try:
+                Path(args.errors).write_text(text, encoding="utf-8")
+            except OSError:
+                pass
+
+    try:
+        out.write_text(json.dumps(payload, ensure_ascii=False), encoding="utf-8")
+    except OSError:
+        return 2
+    return 0 if payload.get("ok") else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

{virtualdesktop-1.3.1 → virtualdesktop-1.4.0}/VirtualDesktop/agent.py

@@ -181,6 +181,26 @@ class AgentSession:
 
     # -- convenience -------------------------------------------------------------------
 
+    def _report_to_workspace(self, record) -> None:
+        """Tell the owning workspace about a window found here, when there is one.
+
+        Agents are also used through a bare :class:`~VirtualDesktop.desktop_session.VirtualDesktop`,
+        which has no workspace, so this is a no-op there.
+        """
+        workspace = getattr(self.desktop, "_workspace", None)
+        if workspace is None:
+            return
+        try:
+            workspace._remember_isolated(
+                hwnd=record.hwnd,
+                pid=record.pid,
+                title=record.title,
+                class_name=record.class_name,
+                rect=record.rect,
+            )
+        except Exception:  # noqa: BLE001 - bookkeeping must not break the launch
+            log.debug("could not report window 0x%X to the workspace", record.hwnd, exc_info=True)
+
     def launch(
         self,
         argv: Sequence[str],
@@ -194,6 +214,7 @@ class AgentSession:
         record = self.desktop.find_window(
             process.pid, timeout=timeout or self.timeout, title_hint=title
         )
+        self._report_to_workspace(record)
         return AgentProcess(
             pid=process.pid, hwnd=record.hwnd, title=record.title, command=command[0]
         )
@@ -201,6 +222,7 @@ class AgentSession:
     def adopt(self, pid: int, *, timeout: Optional[float] = None, title: Optional[str] = None) -> AgentProcess:
         """Attach to a program already running on the desktop."""
         record = self.desktop.find_window(pid, timeout=timeout or self.timeout, title_hint=title)
+        self._report_to_workspace(record)
         return AgentProcess(pid=pid, hwnd=record.hwnd, title=record.title)
 
     def windows(self) -> List[Dict[str, Any]]:
@@ -223,6 +245,29 @@ class AgentSession:
         """Type ``text`` into ``window`` using character messages (no keyboard focus needed)."""
         return int(self.command("keys", hwnd=_handle(window), text=text).get("sent", 0))
 
+    def uia_tree(
+        self,
+        window: Any,
+        *,
+        depth: int = 8,
+        max_nodes: int = 500,
+        view: str = "RawView",
+    ) -> Dict[str, Any]:
+        """The UI Automation tree of ``window``, walked **inside this desktop**.
+
+        This is the only way to read the tree of a window on a private desktop: a UIA client
+        resolves elements against the desktop it is attached to, so an outside dump sees nothing.
+        Inside here it uses ``ElementFromHandle`` (``GetRootElement`` would return the *input*
+        desktop's root and find none of this desktop's windows).
+
+        ``view`` is ``RawView`` (everything, needed for Electron/Chromium), ``ControlView``
+        (meaningful controls only) or ``ContentView``.
+        """
+        payload = self.command(
+            "uia_tree", hwnd=_handle(window), depth=depth, max_nodes=max_nodes, view=view
+        )
+        return dict(payload.get("tree") or {})
+
     def screenshot(self, window: Any, path: str) -> Dict[str, Any]:
         """Not available: a window on a private desktop has no pixels to capture.