VirtualDesktop 1.3.1__tar.gz → 1.4.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: VirtualDesktop
-Version: 1.3.1
+Version: 1.4.1
 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
@@ -47,6 +47,7 @@ Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: Pillow>=9.0
+Requires-Dist: comtypes>=1.2.0
 Provides-Extra: test
 Requires-Dist: pytest>=7.0; extra == "test"
 Provides-Extra: build
@@ -78,20 +79,59 @@ pip install VirtualDesktop        # pip
 uv add VirtualDesktop             # uv（写入 pyproject.toml 并锁定）
 ```
 
-运行时依赖只有 **Pillow**。若国内镜像同步滞后导致找不到最新版，加
+运行时依赖：**Pillow**（帧图像）与 **comtypes**（UI Automation 是 COM API）。不需要 pywin32——
+库访问 Win32 全部走 ctypes。若国内镜像同步滞后导致找不到最新版，加
 `--default-index https://pypi.org/simple`（uv）或 `-i https://pypi.org/simple`（pip）。
 
 | | 私有桌面 | 虚拟显示器 |
 |---|---|---|
 | 一句话 | 另开一个桌面，窗口与你的桌面完全隔离 | 多一块屏幕，窗口仍在你的桌面上、只是画在看不见的地方 |
-| 隔离强度 | **强**：独立窗口命名空间，外部进程看不到、碰不到 | **弱**：窗口是普通窗口，任何程序都能找到并操作它 |
+| 底层 | 内核**对象**（`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("名字")`
 
 ---
 
@@ -107,7 +147,7 @@ uv add VirtualDesktop             # uv（写入 pyproject.toml 并锁定）
 | 系统 | Windows 10 / 11（无 IddCx 版本要求） |
 | 权限 | 当前用户即可，**不提权** |
 | 驱动 | 不需要 |
-| 依赖 | 仅 Pillow |
+| 依赖 | Pillow + comtypes |
 
 ## 基本用法
 
@@ -169,13 +209,14 @@ 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()` | 该桌面上的窗口清单 |
 | `agent.exec("python 代码")` | 在桌面内跑任意 Python，返回打印内容 |
 
 `exec` 是逃生舱：里面的代码能 `import VirtualDesktop`、能用 `list_windows()`、`CaptureEngine`，
-也能用你自己装的任何库。代理本身只依赖 ctypes，不需要额外安装。
+也能用你自己装的任何库。代理本身只依赖 ctypes 与 comtypes。
 
 ### 私有桌面不能截图
 
@@ -210,6 +251,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` 放在文件顶部也不会影响私有桌面。
+
 ---
 
 # 第二部分：虚拟显示器
@@ -225,7 +298,7 @@ with VirtualWorkspace("lab") as space, space.agent() as agent:
 | 系统 | **Windows 10 1809 (build 17763) 或更高**（更低版本没有 IddCx 框架） |
 | 权限 | 安装/卸载驱动需要管理员，弹**一次 UAC** |
 | 驱动 | 首次使用时自动下载安装（也可预先装好） |
-| 依赖 | 仅 Pillow |
+| 依赖 | Pillow + comtypes |
 
 ## 装驱动
 
@@ -424,6 +497,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 +557,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 +566,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.1}/README.md

@@ -22,20 +22,59 @@ pip install VirtualDesktop        # pip
 uv add VirtualDesktop             # uv（写入 pyproject.toml 并锁定）
 ```
 
-运行时依赖只有 **Pillow**。若国内镜像同步滞后导致找不到最新版，加
+运行时依赖：**Pillow**（帧图像）与 **comtypes**（UI Automation 是 COM API）。不需要 pywin32——
+库访问 Win32 全部走 ctypes。若国内镜像同步滞后导致找不到最新版，加
 `--default-index https://pypi.org/simple`（uv）或 `-i https://pypi.org/simple`（pip）。
 
 | | 私有桌面 | 虚拟显示器 |
 |---|---|---|
 | 一句话 | 另开一个桌面，窗口与你的桌面完全隔离 | 多一块屏幕，窗口仍在你的桌面上、只是画在看不见的地方 |
-| 隔离强度 | **强**：独立窗口命名空间，外部进程看不到、碰不到 | **弱**：窗口是普通窗口，任何程序都能找到并操作它 |
+| 底层 | 内核**对象**（`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("名字")`
 
 ---
 
@@ -51,7 +90,7 @@ uv add VirtualDesktop             # uv（写入 pyproject.toml 并锁定）
 | 系统 | Windows 10 / 11（无 IddCx 版本要求） |
 | 权限 | 当前用户即可，**不提权** |
 | 驱动 | 不需要 |
-| 依赖 | 仅 Pillow |
+| 依赖 | Pillow + comtypes |
 
 ## 基本用法
 
@@ -113,13 +152,14 @@ 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()` | 该桌面上的窗口清单 |
 | `agent.exec("python 代码")` | 在桌面内跑任意 Python，返回打印内容 |
 
 `exec` 是逃生舱：里面的代码能 `import VirtualDesktop`、能用 `list_windows()`、`CaptureEngine`，
-也能用你自己装的任何库。代理本身只依赖 ctypes，不需要额外安装。
+也能用你自己装的任何库。代理本身只依赖 ctypes 与 comtypes。
 
 ### 私有桌面不能截图
 
@@ -154,6 +194,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` 放在文件顶部也不会影响私有桌面。
+
 ---
 
 # 第二部分：虚拟显示器
@@ -169,7 +241,7 @@ with VirtualWorkspace("lab") as space, space.agent() as agent:
 | 系统 | **Windows 10 1809 (build 17763) 或更高**（更低版本没有 IddCx 框架） |
 | 权限 | 安装/卸载驱动需要管理员，弹**一次 UAC** |
 | 驱动 | 首次使用时自动下载安装（也可预先装好） |
-| 依赖 | 仅 Pillow |
+| 依赖 | Pillow + comtypes |
 
 ## 装驱动
 
@@ -368,6 +440,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 +500,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 +509,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.1}/VirtualDesktop/__init__.py

@@ -1,135 +1,135 @@
-"""``VirtualDesktop`` – an offscreen window workstation for Windows.
-
-The public surface is deliberately small:
-
-* :class:`~VirtualDesktop.session.OffscreenSession` – mount, capture, restore.
-* :func:`~VirtualDesktop.session.probe_environment` – diagnostics without side effects.
-* :class:`~VirtualDesktop.driver.DriverInstaller` – explicit driver control.
-* :mod:`VirtualDesktop.errors` – every exception, each with a ``code`` and a ``hint``.
-
-Typical use::
-
-    from VirtualDesktop import OffscreenSession
-
-    with OffscreenSession(target_window_title="WeChat") as session:
-        session.mount()
-        frame = session.capture()          # PIL image
-        frame.image.save("wechat.png")
-
-Nothing is installed until ``mount()`` actually needs a virtual display, and nothing is
-moved until a target window has been found, so a failed call leaves the machine as it was.
-"""
-
-from __future__ import annotations
-
-from ._log import enable_debug_logging, get_logger
-from ._winapi import (
-    IS_WINDOWS,
-    MonitorInfo,
-    enumerate_monitors,
-    is_admin,
-    list_windows,
-    select_virtual_monitor,
-)
-from .capture import DEFAULT_METHODS, CaptureEngine, Frame, analyze_image
-from .config import DriverConfig, SessionConfig
-from .desktop import DesktopBinding, current_desktop_name, ensure_default_desktop
-from .driver import DriverInstaller, InstallReport, virtual_display_present
-from .errors import (
-    AmbiguousWindowError,
-    CaptureError,
-    ConfigError,
-    DesktopBindError,
-    DownloadError,
-    DriverInstallError,
-    DriverNotFoundError,
-    DriverVerificationError,
-    ElevationDenied,
-    ElevationRequired,
-    ExtractionError,
-    IntegrityError,
-    MissingDependencyError,
-    OffscreenMountError,
-    SessionStateError,
-    UnsupportedPlatformError,
-    WindowMountError,
-    WindowNotFoundError,
-)
-from .manifest import load_manifest
-from .session import OffscreenSession, probe_environment
-from .desktop_session import DesktopProcess, VirtualDesktop, current_desktop_name
-from .window import WindowMounter, WindowRecord, find_window, window_diagnostics
-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"
-
-__all__ = [
-    "__version__",
-    # session
-    "OffscreenSession",
-    "probe_environment",
-    # drivers
-    "DriverInstaller",
-    "InstallReport",
-    "virtual_display_present",
-    "load_manifest",
-    # windows and displays
-    "WindowMounter",
-    "WindowRecord",
-    "find_window",
-    "window_diagnostics",
-    "enumerate_monitors",
-    "select_virtual_monitor",
-    "MonitorInfo",
-    "list_windows",
-    "ensure_default_desktop",
-    "current_desktop_name",
-    "DesktopBinding",
-    # private virtual desktop (no admin, no driver)
-    "VirtualDesktop",
-    "DesktopProcess",
-    # multi-window virtual-display workspace (externally controllable)
-    "VirtualWorkspace",
-    "WorkspaceWindow",
-    "SHARED",
-    # in-desktop agent (for isolated workspaces / private desktops)
-    "AgentSession",
-    "AgentProcess",
-    # virtual display geometry
-    "configure_virtual_display",
-    "current_primary_size",
-    "current_primary_dpi",
-    # capture
-    "CaptureEngine",
-    "Frame",
-    "analyze_image",
-    "DEFAULT_METHODS",
-    # configuration
-    "DriverConfig",
-    "SessionConfig",
-    # platform helpers
-    "IS_WINDOWS",
-    "is_admin",
-    "enable_debug_logging",
-    # errors
-    "OffscreenMountError",
-    "UnsupportedPlatformError",
-    "MissingDependencyError",
-    "ConfigError",
-    "IntegrityError",
-    "DownloadError",
-    "ExtractionError",
-    "ElevationRequired",
-    "ElevationDenied",
-    "DriverInstallError",
-    "DriverNotFoundError",
-    "DriverVerificationError",
-    "DesktopBindError",
-    "WindowNotFoundError",
-    "AmbiguousWindowError",
-    "WindowMountError",
-    "CaptureError",
-    "SessionStateError",
-]
+"""``VirtualDesktop`` 鈥?an offscreen window workstation for Windows.
+
+The public surface is deliberately small:
+
+* :class:`~VirtualDesktop.session.OffscreenSession` 鈥?mount, capture, restore.
+* :func:`~VirtualDesktop.session.probe_environment` 鈥?diagnostics without side effects.
+* :class:`~VirtualDesktop.driver.DriverInstaller` 鈥?explicit driver control.
+* :mod:`VirtualDesktop.errors` 鈥?every exception, each with a ``code`` and a ``hint``.
+
+Typical use::
+
+    from VirtualDesktop import OffscreenSession
+
+    with OffscreenSession(target_window_title="WeChat") as session:
+        session.mount()
+        frame = session.capture()          # PIL image
+        frame.image.save("wechat.png")
+
+Nothing is installed until ``mount()`` actually needs a virtual display, and nothing is
+moved until a target window has been found, so a failed call leaves the machine as it was.
+"""
+
+from __future__ import annotations
+
+from ._log import enable_debug_logging, get_logger
+from ._winapi import (
+    IS_WINDOWS,
+    MonitorInfo,
+    enumerate_monitors,
+    is_admin,
+    list_windows,
+    select_virtual_monitor,
+)
+from .capture import DEFAULT_METHODS, CaptureEngine, Frame, analyze_image
+from .config import DriverConfig, SessionConfig
+from .desktop import DesktopBinding, current_desktop_name, ensure_default_desktop
+from .driver import DriverInstaller, InstallReport, virtual_display_present
+from .errors import (
+    AmbiguousWindowError,
+    CaptureError,
+    ConfigError,
+    DesktopBindError,
+    DownloadError,
+    DriverInstallError,
+    DriverNotFoundError,
+    DriverVerificationError,
+    ElevationDenied,
+    ElevationRequired,
+    ExtractionError,
+    IntegrityError,
+    MissingDependencyError,
+    OffscreenMountError,
+    SessionStateError,
+    UnsupportedPlatformError,
+    WindowMountError,
+    WindowNotFoundError,
+)
+from .manifest import load_manifest
+from .session import OffscreenSession, probe_environment
+from .desktop_session import DesktopProcess, VirtualDesktop, current_desktop_name
+from .window import WindowMounter, WindowRecord, find_window, window_diagnostics
+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.4.1"
+
+__all__ = [
+    "__version__",
+    # session
+    "OffscreenSession",
+    "probe_environment",
+    # drivers
+    "DriverInstaller",
+    "InstallReport",
+    "virtual_display_present",
+    "load_manifest",
+    # windows and displays
+    "WindowMounter",
+    "WindowRecord",
+    "find_window",
+    "window_diagnostics",
+    "enumerate_monitors",
+    "select_virtual_monitor",
+    "MonitorInfo",
+    "list_windows",
+    "ensure_default_desktop",
+    "current_desktop_name",
+    "DesktopBinding",
+    # private virtual desktop (no admin, no driver)
+    "VirtualDesktop",
+    "DesktopProcess",
+    # multi-window virtual-display workspace (externally controllable)
+    "VirtualWorkspace",
+    "WorkspaceWindow",
+    "SHARED",
+    # in-desktop agent (for isolated workspaces / private desktops)
+    "AgentSession",
+    "AgentProcess",
+    # virtual display geometry
+    "configure_virtual_display",
+    "current_primary_size",
+    "current_primary_dpi",
+    # capture
+    "CaptureEngine",
+    "Frame",
+    "analyze_image",
+    "DEFAULT_METHODS",
+    # configuration
+    "DriverConfig",
+    "SessionConfig",
+    # platform helpers
+    "IS_WINDOWS",
+    "is_admin",
+    "enable_debug_logging",
+    # errors
+    "OffscreenMountError",
+    "UnsupportedPlatformError",
+    "MissingDependencyError",
+    "ConfigError",
+    "IntegrityError",
+    "DownloadError",
+    "ExtractionError",
+    "ElevationRequired",
+    "ElevationDenied",
+    "DriverInstallError",
+    "DriverNotFoundError",
+    "DriverVerificationError",
+    "DesktopBindError",
+    "WindowNotFoundError",
+    "AmbiguousWindowError",
+    "WindowMountError",
+    "CaptureError",
+    "SessionStateError",
+]