VirtualDesktop 1.3.0__tar.gz → 1.4.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: VirtualDesktop
-Version: 1.3.0
+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、无人值守抓界面 |
+
+### 隔离强度分级
+
+两套方案的隔离**不是"强/弱"两档，而是三个层面各不相同**，按你需要防住什么来选：
+
+| 隔离层面 | 私有桌面 | 虚拟显示器 | 说明 |
+|---|---|---|---|
+| 窗口**发现**（能否枚举到） | **隔离** | 不隔离 | 私有桌面：`EnumWindows`/`FindWindow` 从外部看不到 |
+| 窗口**输入**（真实鼠标键盘） | **隔离** | 不隔离 | 私有桌面：没有活动指针与键盘焦点 |
+| 窗口**截图**（像素可读性） | **隔离** | 不隔离 | 私有桌面：从不参与系统合成，没有像素 |
+| 窗口**消息**（`SendMessage` 等） | **不隔离** | 不隔离 | 拿到句柄即可投递消息，DACL 保护的是桌面对象而不是窗口消息 |
+| 进程**生命周期** | **隔离** | 不隔离 | 私有桌面关闭时其上进程一并结束；虚拟显示器上的程序由你负责 |
+
+> 关键提醒：私有桌面**不等于**"完全无法访问"。它挡的是**发现**、**输入**和**截图**，
+> 挡不住"已知句柄后投递消息"。所以不要把私有桌面当作进程级安全沙箱使用——它没有降低
+> 目标进程的权限，只是把它挪到了另一个窗口命名空间。
+
+### 推荐怎么选
 
-> **只想跑一个窗口、要截图** → 用虚拟显示器侧的 `OffscreenSession`，最省事。
-> **要多个实例互不干扰、不需要截图** → 用私有桌面。
+```
+要截图（窗口截图或桌面截图）              → 虚拟显示器
+要用真实鼠标 / 滚轮 / 键盘，或 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()` | 该桌面上的窗口清单 |
@@ -177,6 +216,18 @@ with VirtualWorkspace("lab") as space, space.agent() as agent:
 `exec` 是逃生舱：里面的代码能 `import VirtualDesktop`、能用 `list_windows()`、`CaptureEngine`，
 也能用你自己装的任何库。代理本身只依赖 ctypes，不需要额外安装。
 
+### 私有桌面不能截图
+
+两种截图都不行，且原因不同：
+
+| 类型 | 结果 | 原因 |
+|---|---|---|
+| 程序窗口截图 | **不能** | 该桌面的窗口从不被系统合成，没有像素可读 |
+| 桌面截图 | **不能** | 拿不到该桌面的屏幕 DC（`BitBlt` 返回拒绝访问） |
+
+`agent.screenshot()` 会**明确报错**（`code="capture-needs-shared-workspace"`）而不是产出空白图。
+要读状态用 `agent.info()` / `agent.text()`；要像素请改用虚拟显示器。
+
 ## 能力边界
 
 私有桌面的窗口**不在交互桌面上**，所以按输入机制分，能做的事如下：
@@ -185,17 +236,50 @@ with VirtualWorkspace("lab") as space, space.agent() as agent:
 |---|---|---|
 | 找到窗口、读标题 / 类名 / 矩形 | 能 | 读窗口属性，跨桌面可用 |
 | 枚举子控件、读控件文字 | 能 | 同上 |
+| 用外部进程的 pywinauto 连上并读属性 | **能** | 拿得到句柄就能读 |
 | 点击控件（`BM_CLICK` 等窗口消息） | **能** | 消息直接投递给窗口，不需要指针 |
 | 送入字符（`WM_CHAR` 消息） | **能** | 同上 |
-| **截图** | **不能** | 桌面从不被系统合成，没有像素可读 |
+| **程序窗口截图** | **不能** | 桌面从不被系统合成，窗口没有像素 |
+| **桌面截图** | **不能** | 拿不到该桌面的屏幕 DC（`BitBlt` 返回拒绝访问） |
 | 移动真实鼠标来点击 | **不能** | 该桌面不是活动桌面，没有指针 |
 | 滚轮（真实滚轮事件） | **不能** | 同"移动真实鼠标" |
 | 发送真实键盘输入（`SendInput`） | **不能** | 键盘只发给活动桌面 |
 | `pywinauto` 的 `click_input()` / `type_keys()` | **不能** | 依赖真实输入与前台焦点 |
-| 用外部进程的 pywinauto 直接连上它 | **不能** | 跨桌面拿不到窗口 |
 
-要点：**能用消息驱动的都能用，需要真实输入设备的都不能用**。需要截图或需要真实鼠标/滚轮的应用，
-请改用下面的虚拟显示器方案。
+要点：**能用消息驱动的都能用，需要真实输入设备的都不能用，两种截图都不能用**。需要截图或需要
+真实鼠标/滚轮的应用，请改用下面的虚拟显示器方案。
+
+## 支持的能力与调用方式
+
+| 能力 | 是否支持 | 怎么调 |
+|---|---|---|
+| 在一个桌面里跑多个程序 | **支持** | 连续 `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` 放在文件顶部也不会影响私有桌面。
 
 ---
 
@@ -288,7 +372,17 @@ VirtualWorkspace(VirtualWorkspace.SHARED, monitor="primary")           # 主屏
 
 ## 截图
 
-`capture()` 依次尝试多种后端直到拿到**有内容**的帧，默认顺序：
+要分清两种，它们走**完全不同的通路**，能力也不同：
+
+| 类型 | 拍什么 | 走哪条路 | 怎么调 |
+|---|---|---|---|
+| **程序窗口截图** | 某一个窗口自己的像素 | `PrintWindow(hwnd)` | `CaptureEngine.capture(hwnd)` / `space.capture(hwnd)` |
+| **桌面截图** | 整块屏幕（含其上所有窗口） | `ImageGrab` / `BitBlt` 屏幕 DC | `capture_all_screens()` / `capture_monitor()` / `space.capture_desktop()` |
+
+### 程序窗口截图
+
+按句柄拍，窗口在屏幕外也能拍，是抓单个程序界面最可靠的方式。`capture()` 依次尝试多种后端直到
+拿到**有内容**的帧，默认顺序：
 
 `printwindow`（`PW_RENDERFULLCONTENT`）→ `printwindow_plain` → `wm_print` → `bitblt`
 
@@ -303,6 +397,39 @@ frame = engine.capture(hwnd, require_content=True)
 print(frame.method, frame.size)
 ```
 
+```python
+with VirtualWorkspace(VirtualWorkspace.SHARED) as space:
+    entry = space.launch(["charmap.exe"])
+    space.capture(entry.hwnd, save_to="window.png")
+```
+
+### 桌面截图
+
+拍的是**屏幕**，不是某个窗口。`virtual_screen_rect()` 是整张虚拟桌面（含所有显示器，处理好负坐标），
+`capture_monitor()` 是单块显示器。在虚拟显示器模式下，`space.capture_desktop()` 等价于
+`capture_monitor(space.monitor)`。
+
+```python
+from VirtualDesktop import CaptureEngine
+from VirtualDesktop.desktop_capture import capture_all_screens, capture_monitor
+
+CaptureEngine().ensure_dpi_aware()      # 拍摄前必须做，见下方警告
+
+whole = capture_all_screens()           # 整张虚拟桌面
+whole.image.save("desktop.png")
+print(whole.rect, whole.size, whole.method)
+
+one = capture_monitor(device="\\\\.\\DISPLAY2")   # 只拍某一块屏
+```
+
+> **拍摄前先确保 DPI 感知。** 矩形由 `GetSystemMetrics` / `EnumDisplayMonitors` 计算，它们对
+> **不感知 DPI** 的进程返回的是**缩放后的逻辑值**；而像素抓取返回的是**物理像素**。两者不一致时
+> 会**静默裁掉**画面右下角（125% 缩放下 1920×1080 的屏只拿到 1536×864，少 384×216 像素，且不报错）。
+> 先调一次 `CaptureEngine().ensure_dpi_aware()` 即可，`VirtualWorkspace` 内部已自动处理。
+
+> **桌面截图只有虚拟显示器模式可用。** offscreen 模式下窗口被移到所有显示器**之外**，桌面截图按
+> 定义拍不到它们；而私有桌面根本没有可拍的屏幕 DC。
+
 ## 用自动化库控制窗口
 
 窗口是普通窗口，直接从你的进程用即可：
@@ -358,7 +485,8 @@ print(current_primary_size())                            # (1920, 1080)
 | 枚举子控件、读控件文字 | 能 | 能 |
 | 点击控件（窗口消息） | 能 | 能 |
 | 送入字符（窗口消息） | 能 | 能 |
-| **截图** | **能** | **能** |
+| **程序窗口截图** | **能** | **能** |
+| **桌面截图** | **能**（拍到窗口） | **不能**（窗口在所有显示器之外） |
 | 外部 pywinauto / UIA 直接连上 | 能 | 能 |
 | 移动真实鼠标来点击 | 能 | **不能**（窗口在屏幕之外） |
 | 滚轮 | 能 | **不能** |
@@ -367,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` 会明确报错 |
+
 ---
 
 # 通用功能
@@ -407,12 +555,15 @@ 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` 试试，或确认窗口有内容 |
+| 窗口截图是黑帧 | 应用为硬件加速 / 受保护内容 | 系统限制；换 `bitblt` 试试，或确认窗口有内容 |
+| 桌面截图少了右下角 | 进程不感知 DPI，矩形按逻辑坐标算 | 先调 `CaptureEngine().ensure_dpi_aware()` |
+| 桌面截图拍不到工作区窗口 | 用了 `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` 即可，不会联网；也可用
@@ -420,8 +571,9 @@ VIRTUALDESKTOP_LOG_FILE=<path>
 
 ## 已知限制
 
-- **私有桌面不能截图**：它的窗口没有被系统合成，没有任何后端能读到像素；`agent.screenshot()`
-  会明确报错。
+- **私有桌面不能截图**：程序窗口截图和桌面截图都不行。窗口没有被系统合成、没有像素可读；
+  而该桌面的屏幕 DC 也拿不到（`BitBlt` 返回拒绝访问）。用 `agent.info()` / `agent.text()` 读状态，
+  需要像素请改用虚拟显示器。
 - **私有桌面不能用真实鼠标 / 滚轮 / 真实键盘**：那里没有活动指针和键盘焦点；消息驱动可用。
 - **窗口无法在私有桌面之间搬运**：Windows 不允许跨桌面移动窗口。
 - 部分应用（UWP、硬件叠加层、DRM 受保护内容）任何离屏方式都抓不到——系统限制。

{virtualdesktop-1.3.0 → 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、无人值守抓界面 |
+
+### 隔离强度分级
+
+两套方案的隔离**不是"强/弱"两档，而是三个层面各不相同**，按你需要防住什么来选：
+
+| 隔离层面 | 私有桌面 | 虚拟显示器 | 说明 |
+|---|---|---|---|
+| 窗口**发现**（能否枚举到） | **隔离** | 不隔离 | 私有桌面：`EnumWindows`/`FindWindow` 从外部看不到 |
+| 窗口**输入**（真实鼠标键盘） | **隔离** | 不隔离 | 私有桌面：没有活动指针与键盘焦点 |
+| 窗口**截图**（像素可读性） | **隔离** | 不隔离 | 私有桌面：从不参与系统合成，没有像素 |
+| 窗口**消息**（`SendMessage` 等） | **不隔离** | 不隔离 | 拿到句柄即可投递消息，DACL 保护的是桌面对象而不是窗口消息 |
+| 进程**生命周期** | **隔离** | 不隔离 | 私有桌面关闭时其上进程一并结束；虚拟显示器上的程序由你负责 |
+
+> 关键提醒：私有桌面**不等于**"完全无法访问"。它挡的是**发现**、**输入**和**截图**，
+> 挡不住"已知句柄后投递消息"。所以不要把私有桌面当作进程级安全沙箱使用——它没有降低
+> 目标进程的权限，只是把它挪到了另一个窗口命名空间。
+
+### 推荐怎么选
 
-> **只想跑一个窗口、要截图** → 用虚拟显示器侧的 `OffscreenSession`，最省事。
-> **要多个实例互不干扰、不需要截图** → 用私有桌面。
+```
+要截图（窗口截图或桌面截图）              → 虚拟显示器
+要用真实鼠标 / 滚轮 / 键盘，或 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()` | 该桌面上的窗口清单 |
@@ -121,6 +160,18 @@ with VirtualWorkspace("lab") as space, space.agent() as agent:
 `exec` 是逃生舱：里面的代码能 `import VirtualDesktop`、能用 `list_windows()`、`CaptureEngine`，
 也能用你自己装的任何库。代理本身只依赖 ctypes，不需要额外安装。
 
+### 私有桌面不能截图
+
+两种截图都不行，且原因不同：
+
+| 类型 | 结果 | 原因 |
+|---|---|---|
+| 程序窗口截图 | **不能** | 该桌面的窗口从不被系统合成，没有像素可读 |
+| 桌面截图 | **不能** | 拿不到该桌面的屏幕 DC（`BitBlt` 返回拒绝访问） |
+
+`agent.screenshot()` 会**明确报错**（`code="capture-needs-shared-workspace"`）而不是产出空白图。
+要读状态用 `agent.info()` / `agent.text()`；要像素请改用虚拟显示器。
+
 ## 能力边界
 
 私有桌面的窗口**不在交互桌面上**，所以按输入机制分，能做的事如下：
@@ -129,17 +180,50 @@ with VirtualWorkspace("lab") as space, space.agent() as agent:
 |---|---|---|
 | 找到窗口、读标题 / 类名 / 矩形 | 能 | 读窗口属性，跨桌面可用 |
 | 枚举子控件、读控件文字 | 能 | 同上 |
+| 用外部进程的 pywinauto 连上并读属性 | **能** | 拿得到句柄就能读 |
 | 点击控件（`BM_CLICK` 等窗口消息） | **能** | 消息直接投递给窗口，不需要指针 |
 | 送入字符（`WM_CHAR` 消息） | **能** | 同上 |
-| **截图** | **不能** | 桌面从不被系统合成，没有像素可读 |
+| **程序窗口截图** | **不能** | 桌面从不被系统合成，窗口没有像素 |
+| **桌面截图** | **不能** | 拿不到该桌面的屏幕 DC（`BitBlt` 返回拒绝访问） |
 | 移动真实鼠标来点击 | **不能** | 该桌面不是活动桌面，没有指针 |
 | 滚轮（真实滚轮事件） | **不能** | 同"移动真实鼠标" |
 | 发送真实键盘输入（`SendInput`） | **不能** | 键盘只发给活动桌面 |
 | `pywinauto` 的 `click_input()` / `type_keys()` | **不能** | 依赖真实输入与前台焦点 |
-| 用外部进程的 pywinauto 直接连上它 | **不能** | 跨桌面拿不到窗口 |
 
-要点：**能用消息驱动的都能用，需要真实输入设备的都不能用**。需要截图或需要真实鼠标/滚轮的应用，
-请改用下面的虚拟显示器方案。
+要点：**能用消息驱动的都能用，需要真实输入设备的都不能用，两种截图都不能用**。需要截图或需要
+真实鼠标/滚轮的应用，请改用下面的虚拟显示器方案。
+
+## 支持的能力与调用方式
+
+| 能力 | 是否支持 | 怎么调 |
+|---|---|---|
+| 在一个桌面里跑多个程序 | **支持** | 连续 `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` 放在文件顶部也不会影响私有桌面。
 
 ---
 
@@ -232,7 +316,17 @@ VirtualWorkspace(VirtualWorkspace.SHARED, monitor="primary")           # 主屏
 
 ## 截图
 
-`capture()` 依次尝试多种后端直到拿到**有内容**的帧，默认顺序：
+要分清两种，它们走**完全不同的通路**，能力也不同：
+
+| 类型 | 拍什么 | 走哪条路 | 怎么调 |
+|---|---|---|---|
+| **程序窗口截图** | 某一个窗口自己的像素 | `PrintWindow(hwnd)` | `CaptureEngine.capture(hwnd)` / `space.capture(hwnd)` |
+| **桌面截图** | 整块屏幕（含其上所有窗口） | `ImageGrab` / `BitBlt` 屏幕 DC | `capture_all_screens()` / `capture_monitor()` / `space.capture_desktop()` |
+
+### 程序窗口截图
+
+按句柄拍，窗口在屏幕外也能拍，是抓单个程序界面最可靠的方式。`capture()` 依次尝试多种后端直到
+拿到**有内容**的帧，默认顺序：
 
 `printwindow`（`PW_RENDERFULLCONTENT`）→ `printwindow_plain` → `wm_print` → `bitblt`
 
@@ -247,6 +341,39 @@ frame = engine.capture(hwnd, require_content=True)
 print(frame.method, frame.size)
 ```
 
+```python
+with VirtualWorkspace(VirtualWorkspace.SHARED) as space:
+    entry = space.launch(["charmap.exe"])
+    space.capture(entry.hwnd, save_to="window.png")
+```
+
+### 桌面截图
+
+拍的是**屏幕**，不是某个窗口。`virtual_screen_rect()` 是整张虚拟桌面（含所有显示器，处理好负坐标），
+`capture_monitor()` 是单块显示器。在虚拟显示器模式下，`space.capture_desktop()` 等价于
+`capture_monitor(space.monitor)`。
+
+```python
+from VirtualDesktop import CaptureEngine
+from VirtualDesktop.desktop_capture import capture_all_screens, capture_monitor
+
+CaptureEngine().ensure_dpi_aware()      # 拍摄前必须做，见下方警告
+
+whole = capture_all_screens()           # 整张虚拟桌面
+whole.image.save("desktop.png")
+print(whole.rect, whole.size, whole.method)
+
+one = capture_monitor(device="\\\\.\\DISPLAY2")   # 只拍某一块屏
+```
+
+> **拍摄前先确保 DPI 感知。** 矩形由 `GetSystemMetrics` / `EnumDisplayMonitors` 计算，它们对
+> **不感知 DPI** 的进程返回的是**缩放后的逻辑值**；而像素抓取返回的是**物理像素**。两者不一致时
+> 会**静默裁掉**画面右下角（125% 缩放下 1920×1080 的屏只拿到 1536×864，少 384×216 像素，且不报错）。
+> 先调一次 `CaptureEngine().ensure_dpi_aware()` 即可，`VirtualWorkspace` 内部已自动处理。
+
+> **桌面截图只有虚拟显示器模式可用。** offscreen 模式下窗口被移到所有显示器**之外**，桌面截图按
+> 定义拍不到它们；而私有桌面根本没有可拍的屏幕 DC。
+
 ## 用自动化库控制窗口
 
 窗口是普通窗口，直接从你的进程用即可：
@@ -302,7 +429,8 @@ print(current_primary_size())                            # (1920, 1080)
 | 枚举子控件、读控件文字 | 能 | 能 |
 | 点击控件（窗口消息） | 能 | 能 |
 | 送入字符（窗口消息） | 能 | 能 |
-| **截图** | **能** | **能** |
+| **程序窗口截图** | **能** | **能** |
+| **桌面截图** | **能**（拍到窗口） | **不能**（窗口在所有显示器之外） |
 | 外部 pywinauto / UIA 直接连上 | 能 | 能 |
 | 移动真实鼠标来点击 | 能 | **不能**（窗口在屏幕之外） |
 | 滚轮 | 能 | **不能** |
@@ -311,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` 会明确报错 |
+
 ---
 
 # 通用功能
@@ -351,12 +499,15 @@ 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` 试试，或确认窗口有内容 |
+| 窗口截图是黑帧 | 应用为硬件加速 / 受保护内容 | 系统限制；换 `bitblt` 试试，或确认窗口有内容 |
+| 桌面截图少了右下角 | 进程不感知 DPI，矩形按逻辑坐标算 | 先调 `CaptureEngine().ensure_dpi_aware()` |
+| 桌面截图拍不到工作区窗口 | 用了 `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` 即可，不会联网；也可用
@@ -364,8 +515,9 @@ VIRTUALDESKTOP_LOG_FILE=<path>
 
 ## 已知限制
 
-- **私有桌面不能截图**：它的窗口没有被系统合成，没有任何后端能读到像素；`agent.screenshot()`
-  会明确报错。
+- **私有桌面不能截图**：程序窗口截图和桌面截图都不行。窗口没有被系统合成、没有像素可读；
+  而该桌面的屏幕 DC 也拿不到（`BitBlt` 返回拒绝访问）。用 `agent.info()` / `agent.text()` 读状态，
+  需要像素请改用虚拟显示器。
 - **私有桌面不能用真实鼠标 / 滚轮 / 真实键盘**：那里没有活动指针和键盘焦点；消息驱动可用。
 - **窗口无法在私有桌面之间搬运**：Windows 不允许跨桌面移动窗口。
 - 部分应用（UWP、硬件叠加层、DRM 受保护内容）任何离屏方式都抓不到——系统限制。

{virtualdesktop-1.3.0 → 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.0"
+__version__ = "1.4.0"
 
 __all__ = [
     "__version__",

{virtualdesktop-1.3.0 → 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}"}