VirtualDesktop 1.4.1__tar.gz → 1.5.0__tar.gz

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

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: VirtualDesktop
-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.
+Version: 1.5.0
+Summary: win10-win11 虚拟桌面
 Author: VirtualDesktop contributors
 License: MIT License
         
@@ -57,7 +57,9 @@ Dynamic: license-file
 
 # VirtualDesktop
 
-在 Windows 上把程序的窗口放到**你看不到的地方**去运行，并读取、操作它。窗口不出现在你的屏幕上，
+win10-win11 虚拟桌面
+
+把程序的窗口放到**你看不到的地方**去运行，并读取、操作它。窗口不出现在你的屏幕上，
 退出时自动还原。
 
 ```python
@@ -89,40 +91,46 @@ uv add VirtualDesktop             # uv（写入 pyproject.toml 并锁定）
 | 底层 | 内核**对象**（`CreateDesktopW`），独立窗口命名空间 + DACL | 显示**设备**（IddCx 驱动），系统多出一块 `\\.\DISPLAYn` |
 | 需要权限 | **零**：不需要驱动、不弹 UAC | 装一次驱动，弹**一次 UAC** |
 | 系统要求 | Win10 / 11 任意 | Win10 1809 (17763) 起 |
-| 程序窗口截图 | **不能** | **能** |
-| 桌面截图 | **不能** | **能** |
+| **程序窗口截图** | **能**（窗口需已显示） | **能** |
+| **桌面截图** | **不能**（没有屏幕 DC） | **能** |
 | 读窗口属性 / 枚举子控件 | 能（桌面内代理） | 能（外部进程直接） |
 | 点击控件 / 送入字符 | 能（窗口消息） | 能（消息 + 真实输入） |
 | 真实鼠标 / 滚轮 / 键盘 | **不能** | **能** |
 | 外部 pywinauto / pyautogui 直接驱动 | **不能** | **能** |
 | 窗口跨桌面搬运 | **不能**（Windows 限制） | 能（在显示器之间移动） |
-| 推荐场景 | 多实例并行、强隔离、不要截图 | UI 自动化、截图 OCR、无人值守抓界面 |
+| 推荐场景 | 多实例并行、强隔离、不需要桌面截图 | UI 自动化、截图 OCR、无人值守抓界面 |
 
 ### 隔离强度分级
 
-两套方案的隔离**不是"强/弱"两档，而是三个层面各不相同**，按你需要防住什么来选：
+两套方案的隔离**不是"强/弱"两档，而是几个层面各不相同**，按你需要防住什么来选：
 
 | 隔离层面 | 私有桌面 | 虚拟显示器 | 说明 |
 |---|---|---|---|
 | 窗口**发现**（能否枚举到） | **隔离** | 不隔离 | 私有桌面：`EnumWindows`/`FindWindow` 从外部看不到 |
 | 窗口**输入**（真实鼠标键盘） | **隔离** | 不隔离 | 私有桌面：没有活动指针与键盘焦点 |
-| 窗口**截图**（像素可读性） | **隔离** | 不隔离 | 私有桌面：从不参与系统合成，没有像素 |
+| 窗口**像素**（能否截图） | **不隔离** | 不隔离 | `PrintWindow` 让**应用自己绘制**，不需要屏幕，所以私有桌面同样能截 |
 | 窗口**消息**（`SendMessage` 等） | **不隔离** | 不隔离 | 拿到句柄即可投递消息，DACL 保护的是桌面对象而不是窗口消息 |
 | 进程**生命周期** | **隔离** | 不隔离 | 私有桌面关闭时其上进程一并结束；虚拟显示器上的程序由你负责 |
 
-> 关键提醒：私有桌面**不等于**"完全无法访问"。它挡的是**发现**、**输入**和**截图**，
-> 挡不住"已知句柄后投递消息"。所以不要把私有桌面当作进程级安全沙箱使用——它没有降低
-> 目标进程的权限，只是把它挪到了另一个窗口命名空间。
+> 关键提醒：私有桌面**不等于**"完全无法访问"。它挡的是**发现**和**真实输入**，
+> 挡不住"已知句柄后投递消息"，也挡不住窗口自己绘制出来的像素。所以不要把私有桌面当作
+> 进程级安全沙箱使用——它没有降低目标进程的权限，只是把它挪到了另一个窗口命名空间。
+>
+> 反过来，**"私有桌面截不了图"是个流传很广的误解**。真正的限制只有两条：
+> ①**桌面截图**（拍整块屏幕）不行，因为那块桌面没有被合成到任何输出上；
+> ②被 `SW_HIDE` 隐藏的窗口拍出来是纯色块，因为它压根不绘制。窗口只要**显示着**
+> （本库默认如此），私有桌面上的窗口截图与共享模式**逐字节一致**。
 
 ### 推荐怎么选
 
 ```
-要截图（窗口截图或桌面截图）              → 虚拟显示器
+要桌面截图（拍整块屏幕/虚拟屏）            → 虚拟显示器
 要用真实鼠标 / 滚轮 / 键盘，或 pyautogui    → 虚拟显示器
 要用 pywinauto / UIA 从外部直接驱动窗口     → 虚拟显示器
 只处理一个窗口、要截图，越省事越好          → OffscreenSession（虚拟显示器侧）
+要窗口截图、但连驱动都不想装               → 私有桌面
 ─────────────────────────────────────────────────────────────
-要多个实例互不干扰、且不需要截图            → 私有桌面
+要多个实例互不干扰                        → 私有桌面
 不能弹 UAC、不能装驱动                     → 私有桌面
 要"退出后什么都不留"（进程随桌面一起结束）   → 私有桌面
 需要窗口完全不出现在任何可见位置          → 私有桌面
@@ -131,7 +139,7 @@ uv add VirtualDesktop             # uv（写入 pyproject.toml 并锁定）
 两条常用组合：
 
 - **只是想安静地跑一个窗口并抓图** → `OffscreenSession` + `virtual_screen`
-- **想并行跑很多互不干扰的实例** → 每个实例一个 `VirtualWorkspace("名字")`
+- **想并行跑很多互不干扰的实例，同时要窗口截图** → 每个实例一个 `VirtualWorkspace("名字")`
 
 ---
 
@@ -218,17 +226,27 @@ with VirtualWorkspace("lab") as space, space.agent() as agent:
 `exec` 是逃生舱：里面的代码能 `import VirtualDesktop`、能用 `list_windows()`、`CaptureEngine`，
 也能用你自己装的任何库。代理本身只依赖 ctypes 与 comtypes。
 
-### 私有桌面不能截图
+### 私有桌面的截图能力
 
-两种截图都不行，且原因不同：
+**程序窗口能截，桌面不能截**，原因是两条不同的路：
 
 | 类型 | 结果 | 原因 |
 |---|---|---|
-| 程序窗口截图 | **不能** | 该桌面的窗口从不被系统合成，没有像素可读 |
-| 桌面截图 | **不能** | 拿不到该桌面的屏幕 DC（`BitBlt` 返回拒绝访问） |
+| 程序窗口截图 | **能** | `PrintWindow` 让**窗口自己绘制**到调用方给的 DC，不需要屏幕，也不需要合成 |
+| 桌面截图 | **不能** | 拍整块屏幕需要该桌面的屏幕 DC，拿不到（`BitBlt` 返回拒绝访问） |
+
+```python
+with VirtualWorkspace("lab") as space, space.agent() as agent:
+    window = agent.launch(["charmap.exe"])
+    frame = agent.screenshot(window, r"C:\绝对路径\window.png")   # 路径必须绝对
+    print(frame.method, frame.size, frame.analysis.blank)
+```
+
+路径必须**绝对**：截图由桌面内的进程执行，它的工作目录不是调用者的。省略 `path` 则只返回
+内存中的帧、不落盘。
 
-`agent.screenshot()` 会**明确报错**（`code="capture-needs-shared-workspace"`）而不是产出空白图。
-要读状态用 `agent.info()` / `agent.text()`；要像素请改用虚拟显示器。
+> 窗口必须是**显示状态**。被 `SW_HIDE` 隐藏的窗口会返回纯色块（`code="capture-blank-window"`），
+> 因为它压根不绘制——本库启动程序时会由放置流程负责在目标位置恢复显示。
 
 ## 能力边界
 
@@ -241,15 +259,15 @@ with VirtualWorkspace("lab") as space, space.agent() as agent:
 | 用外部进程的 pywinauto 连上并读属性 | **能** | 拿得到句柄就能读 |
 | 点击控件（`BM_CLICK` 等窗口消息） | **能** | 消息直接投递给窗口，不需要指针 |
 | 送入字符（`WM_CHAR` 消息） | **能** | 同上 |
-| **程序窗口截图** | **不能** | 桌面从不被系统合成，窗口没有像素 |
+| **程序窗口截图** | **能** | `PrintWindow` 让窗口自己绘制，不需要屏幕或合成 |
 | **桌面截图** | **不能** | 拿不到该桌面的屏幕 DC（`BitBlt` 返回拒绝访问） |
 | 移动真实鼠标来点击 | **不能** | 该桌面不是活动桌面，没有指针 |
 | 滚轮（真实滚轮事件） | **不能** | 同"移动真实鼠标" |
 | 发送真实键盘输入（`SendInput`） | **不能** | 键盘只发给活动桌面 |
 | `pywinauto` 的 `click_input()` / `type_keys()` | **不能** | 依赖真实输入与前台焦点 |
 
-要点：**能用消息驱动的都能用，需要真实输入设备的都不能用，两种截图都不能用**。需要截图或需要
-真实鼠标/滚轮的应用，请改用下面的虚拟显示器方案。
+要点：**能用消息驱动的都能用，需要真实输入设备的都不能用；程序窗口截图可以，桌面截图不行**。
+需要桌面截图或真实鼠标/滚轮的应用，请改用下面的虚拟显示器方案。
 
 ## 支持的能力与调用方式
 
@@ -263,7 +281,8 @@ with VirtualWorkspace("lab") as space, space.agent() as agent:
 | 完整 UIA 树 | **支持** | `agent.uia_tree(window)` |
 | 点击控件 / 送入字符 | **支持** | `agent.click(window, text=...)` / `agent.keys(window, "...")` |
 | 在桌面内跑任意 Python | **支持** | `agent.exec("...")`（可用 comtypes、pywinauto） |
-| 程序窗口截图 / 桌面截图 | **不支持** | 见上方原因；改用虚拟显示器 |
+| 程序窗口截图 | **支持** | `agent.screenshot(window, "绝对路径")` |
+| 桌面截图 | **不支持** | 拿不到该桌面的屏幕 DC；需要拍屏幕请用虚拟显示器 |
 | 跨桌面搬运窗口、移到主屏 | **不支持** | `move_to` 一律报 `cannot-cross-desktop`；只能在目标桌面重新 `launch` |
 
 `agent.uia_tree()` 在**桌面内**遍历 UIA，这是私有桌面唯一可用的取树方式：
@@ -556,7 +575,7 @@ VIRTUALDESKTOP_LOG_FILE=<path>
 | `DriverNotFoundError` | 未装虚拟显示器且不允许安装 | 去掉限制，或先跑 `VirtualDesktop install-driver` |
 | `ElevationDenied` | UAC 被取消或被策略阻止 | 在管理员终端执行一次 `VirtualDesktop install-driver` |
 | `unsupported-windows-build` | 系统低于 Win10 1809，没有 IddCx | 换系统，或用私有桌面（不需要驱动） |
-| `capture-needs-shared-workspace` | 想截私有桌面里的窗口 | 私有桌面不支持截图，改用虚拟显示器 |
+| `capture-blank-window` | 窗口被 `SW_HIDE` 隐藏，不绘制，只能拍到纯色块 | 让它处于显示状态；本库启动程序时会自动在目标位置恢复显示 |
 | `SetThreadDesktop ... error 170` | 你自己在绑定线程，而该线程已有窗口或已初始化 COM | 直接调用 `bind_thread()` 时才会遇到；库内部的枚举不再绑定调用者线程 |
 | 某程序在私有桌面上找不到窗口 | 控制台类程序（`cmd.exe`、`ping.exe`）的窗口属于 `conhost.exe`，不在自己 pid 下 | 报错会提示；用 `agent.exec()` 在桌面内驱动它，或换 GUI 程序 |
 | 安装后没出现新的虚拟屏 | 驱动已注册但显示器未启用 | 设备管理器启用；`report.requires_reboot` 为真时重启 |
@@ -573,9 +592,13 @@ VIRTUALDESKTOP_LOG_FILE=<path>
 
 ## 已知限制
 
-- **私有桌面不能截图**：程序窗口截图和桌面截图都不行。窗口没有被系统合成、没有像素可读；
-  而该桌面的屏幕 DC 也拿不到（`BitBlt` 返回拒绝访问）。用 `agent.info()` / `agent.text()` 读状态，
-  需要像素请改用虚拟显示器。
+- **私有桌面不能做桌面截图**：拍整块屏幕不行，因为该桌面没有被合成到任何输出上，屏幕 DC 也
+  拿不到。**但程序窗口截图可以**——`PrintWindow` 让窗口自己绘制到调用方给的 DC，不需要屏幕，
+  所以私有桌面上的窗口截图与共享模式逐字节一致。
+- **窗口必须是显示状态才可截图**：被 `SW_HIDE` 隐藏的窗口会返回纯色块（它压根不绘制）。
+  本库启动程序时按此处理，由放置流程负责在正确位置恢复显示。
+- **共享模式下程序启动瞬间可能极短暂可见**：程序自己显示窗口，库随即隐藏并移走它。这个间隙在
+  私有桌面上不存在（窗口创建在另一块桌面上，从不经过你的屏幕）；需要完全杜绝请用私有桌面。
 - **私有桌面不能用真实鼠标 / 滚轮 / 真实键盘**：那里没有活动指针和键盘焦点；消息驱动可用。
 - **窗口无法在私有桌面之间搬运**：Windows 不允许跨桌面移动窗口。
 - 部分应用（UWP、硬件叠加层、DRM 受保护内容）任何离屏方式都抓不到——系统限制。

{virtualdesktop-1.4.1 → virtualdesktop-1.5.0}/README.md

@@ -1,6 +1,8 @@
 # VirtualDesktop
 
-在 Windows 上把程序的窗口放到**你看不到的地方**去运行，并读取、操作它。窗口不出现在你的屏幕上，
+win10-win11 虚拟桌面
+
+把程序的窗口放到**你看不到的地方**去运行，并读取、操作它。窗口不出现在你的屏幕上，
 退出时自动还原。
 
 ```python
@@ -32,40 +34,46 @@ uv add VirtualDesktop             # uv（写入 pyproject.toml 并锁定）
 | 底层 | 内核**对象**（`CreateDesktopW`），独立窗口命名空间 + DACL | 显示**设备**（IddCx 驱动），系统多出一块 `\\.\DISPLAYn` |
 | 需要权限 | **零**：不需要驱动、不弹 UAC | 装一次驱动，弹**一次 UAC** |
 | 系统要求 | Win10 / 11 任意 | Win10 1809 (17763) 起 |
-| 程序窗口截图 | **不能** | **能** |
-| 桌面截图 | **不能** | **能** |
+| **程序窗口截图** | **能**（窗口需已显示） | **能** |
+| **桌面截图** | **不能**（没有屏幕 DC） | **能** |
 | 读窗口属性 / 枚举子控件 | 能（桌面内代理） | 能（外部进程直接） |
 | 点击控件 / 送入字符 | 能（窗口消息） | 能（消息 + 真实输入） |
 | 真实鼠标 / 滚轮 / 键盘 | **不能** | **能** |
 | 外部 pywinauto / pyautogui 直接驱动 | **不能** | **能** |
 | 窗口跨桌面搬运 | **不能**（Windows 限制） | 能（在显示器之间移动） |
-| 推荐场景 | 多实例并行、强隔离、不要截图 | UI 自动化、截图 OCR、无人值守抓界面 |
+| 推荐场景 | 多实例并行、强隔离、不需要桌面截图 | UI 自动化、截图 OCR、无人值守抓界面 |
 
 ### 隔离强度分级
 
-两套方案的隔离**不是"强/弱"两档，而是三个层面各不相同**，按你需要防住什么来选：
+两套方案的隔离**不是"强/弱"两档，而是几个层面各不相同**，按你需要防住什么来选：
 
 | 隔离层面 | 私有桌面 | 虚拟显示器 | 说明 |
 |---|---|---|---|
 | 窗口**发现**（能否枚举到） | **隔离** | 不隔离 | 私有桌面：`EnumWindows`/`FindWindow` 从外部看不到 |
 | 窗口**输入**（真实鼠标键盘） | **隔离** | 不隔离 | 私有桌面：没有活动指针与键盘焦点 |
-| 窗口**截图**（像素可读性） | **隔离** | 不隔离 | 私有桌面：从不参与系统合成，没有像素 |
+| 窗口**像素**（能否截图） | **不隔离** | 不隔离 | `PrintWindow` 让**应用自己绘制**，不需要屏幕，所以私有桌面同样能截 |
 | 窗口**消息**（`SendMessage` 等） | **不隔离** | 不隔离 | 拿到句柄即可投递消息，DACL 保护的是桌面对象而不是窗口消息 |
 | 进程**生命周期** | **隔离** | 不隔离 | 私有桌面关闭时其上进程一并结束；虚拟显示器上的程序由你负责 |
 
-> 关键提醒：私有桌面**不等于**"完全无法访问"。它挡的是**发现**、**输入**和**截图**，
-> 挡不住"已知句柄后投递消息"。所以不要把私有桌面当作进程级安全沙箱使用——它没有降低
-> 目标进程的权限，只是把它挪到了另一个窗口命名空间。
+> 关键提醒：私有桌面**不等于**"完全无法访问"。它挡的是**发现**和**真实输入**，
+> 挡不住"已知句柄后投递消息"，也挡不住窗口自己绘制出来的像素。所以不要把私有桌面当作
+> 进程级安全沙箱使用——它没有降低目标进程的权限，只是把它挪到了另一个窗口命名空间。
+>
+> 反过来，**"私有桌面截不了图"是个流传很广的误解**。真正的限制只有两条：
+> ①**桌面截图**（拍整块屏幕）不行，因为那块桌面没有被合成到任何输出上；
+> ②被 `SW_HIDE` 隐藏的窗口拍出来是纯色块，因为它压根不绘制。窗口只要**显示着**
+> （本库默认如此），私有桌面上的窗口截图与共享模式**逐字节一致**。
 
 ### 推荐怎么选
 
 ```
-要截图（窗口截图或桌面截图）              → 虚拟显示器
+要桌面截图（拍整块屏幕/虚拟屏）            → 虚拟显示器
 要用真实鼠标 / 滚轮 / 键盘，或 pyautogui    → 虚拟显示器
 要用 pywinauto / UIA 从外部直接驱动窗口     → 虚拟显示器
 只处理一个窗口、要截图，越省事越好          → OffscreenSession（虚拟显示器侧）
+要窗口截图、但连驱动都不想装               → 私有桌面
 ─────────────────────────────────────────────────────────────
-要多个实例互不干扰、且不需要截图            → 私有桌面
+要多个实例互不干扰                        → 私有桌面
 不能弹 UAC、不能装驱动                     → 私有桌面
 要"退出后什么都不留"（进程随桌面一起结束）   → 私有桌面
 需要窗口完全不出现在任何可见位置          → 私有桌面
@@ -74,7 +82,7 @@ uv add VirtualDesktop             # uv（写入 pyproject.toml 并锁定）
 两条常用组合：
 
 - **只是想安静地跑一个窗口并抓图** → `OffscreenSession` + `virtual_screen`
-- **想并行跑很多互不干扰的实例** → 每个实例一个 `VirtualWorkspace("名字")`
+- **想并行跑很多互不干扰的实例，同时要窗口截图** → 每个实例一个 `VirtualWorkspace("名字")`
 
 ---
 
@@ -161,17 +169,27 @@ with VirtualWorkspace("lab") as space, space.agent() as agent:
 `exec` 是逃生舱：里面的代码能 `import VirtualDesktop`、能用 `list_windows()`、`CaptureEngine`，
 也能用你自己装的任何库。代理本身只依赖 ctypes 与 comtypes。
 
-### 私有桌面不能截图
+### 私有桌面的截图能力
 
-两种截图都不行，且原因不同：
+**程序窗口能截，桌面不能截**，原因是两条不同的路：
 
 | 类型 | 结果 | 原因 |
 |---|---|---|
-| 程序窗口截图 | **不能** | 该桌面的窗口从不被系统合成，没有像素可读 |
-| 桌面截图 | **不能** | 拿不到该桌面的屏幕 DC（`BitBlt` 返回拒绝访问） |
+| 程序窗口截图 | **能** | `PrintWindow` 让**窗口自己绘制**到调用方给的 DC，不需要屏幕，也不需要合成 |
+| 桌面截图 | **不能** | 拍整块屏幕需要该桌面的屏幕 DC，拿不到（`BitBlt` 返回拒绝访问） |
+
+```python
+with VirtualWorkspace("lab") as space, space.agent() as agent:
+    window = agent.launch(["charmap.exe"])
+    frame = agent.screenshot(window, r"C:\绝对路径\window.png")   # 路径必须绝对
+    print(frame.method, frame.size, frame.analysis.blank)
+```
+
+路径必须**绝对**：截图由桌面内的进程执行，它的工作目录不是调用者的。省略 `path` 则只返回
+内存中的帧、不落盘。
 
-`agent.screenshot()` 会**明确报错**（`code="capture-needs-shared-workspace"`）而不是产出空白图。
-要读状态用 `agent.info()` / `agent.text()`；要像素请改用虚拟显示器。
+> 窗口必须是**显示状态**。被 `SW_HIDE` 隐藏的窗口会返回纯色块（`code="capture-blank-window"`），
+> 因为它压根不绘制——本库启动程序时会由放置流程负责在目标位置恢复显示。
 
 ## 能力边界
 
@@ -184,15 +202,15 @@ with VirtualWorkspace("lab") as space, space.agent() as agent:
 | 用外部进程的 pywinauto 连上并读属性 | **能** | 拿得到句柄就能读 |
 | 点击控件（`BM_CLICK` 等窗口消息） | **能** | 消息直接投递给窗口，不需要指针 |
 | 送入字符（`WM_CHAR` 消息） | **能** | 同上 |
-| **程序窗口截图** | **不能** | 桌面从不被系统合成，窗口没有像素 |
+| **程序窗口截图** | **能** | `PrintWindow` 让窗口自己绘制，不需要屏幕或合成 |
 | **桌面截图** | **不能** | 拿不到该桌面的屏幕 DC（`BitBlt` 返回拒绝访问） |
 | 移动真实鼠标来点击 | **不能** | 该桌面不是活动桌面，没有指针 |
 | 滚轮（真实滚轮事件） | **不能** | 同"移动真实鼠标" |
 | 发送真实键盘输入（`SendInput`） | **不能** | 键盘只发给活动桌面 |
 | `pywinauto` 的 `click_input()` / `type_keys()` | **不能** | 依赖真实输入与前台焦点 |
 
-要点：**能用消息驱动的都能用，需要真实输入设备的都不能用，两种截图都不能用**。需要截图或需要
-真实鼠标/滚轮的应用，请改用下面的虚拟显示器方案。
+要点：**能用消息驱动的都能用，需要真实输入设备的都不能用；程序窗口截图可以，桌面截图不行**。
+需要桌面截图或真实鼠标/滚轮的应用，请改用下面的虚拟显示器方案。
 
 ## 支持的能力与调用方式
 
@@ -206,7 +224,8 @@ with VirtualWorkspace("lab") as space, space.agent() as agent:
 | 完整 UIA 树 | **支持** | `agent.uia_tree(window)` |
 | 点击控件 / 送入字符 | **支持** | `agent.click(window, text=...)` / `agent.keys(window, "...")` |
 | 在桌面内跑任意 Python | **支持** | `agent.exec("...")`（可用 comtypes、pywinauto） |
-| 程序窗口截图 / 桌面截图 | **不支持** | 见上方原因；改用虚拟显示器 |
+| 程序窗口截图 | **支持** | `agent.screenshot(window, "绝对路径")` |
+| 桌面截图 | **不支持** | 拿不到该桌面的屏幕 DC；需要拍屏幕请用虚拟显示器 |
 | 跨桌面搬运窗口、移到主屏 | **不支持** | `move_to` 一律报 `cannot-cross-desktop`；只能在目标桌面重新 `launch` |
 
 `agent.uia_tree()` 在**桌面内**遍历 UIA，这是私有桌面唯一可用的取树方式：
@@ -499,7 +518,7 @@ VIRTUALDESKTOP_LOG_FILE=<path>
 | `DriverNotFoundError` | 未装虚拟显示器且不允许安装 | 去掉限制，或先跑 `VirtualDesktop install-driver` |
 | `ElevationDenied` | UAC 被取消或被策略阻止 | 在管理员终端执行一次 `VirtualDesktop install-driver` |
 | `unsupported-windows-build` | 系统低于 Win10 1809，没有 IddCx | 换系统，或用私有桌面（不需要驱动） |
-| `capture-needs-shared-workspace` | 想截私有桌面里的窗口 | 私有桌面不支持截图，改用虚拟显示器 |
+| `capture-blank-window` | 窗口被 `SW_HIDE` 隐藏，不绘制，只能拍到纯色块 | 让它处于显示状态；本库启动程序时会自动在目标位置恢复显示 |
 | `SetThreadDesktop ... error 170` | 你自己在绑定线程，而该线程已有窗口或已初始化 COM | 直接调用 `bind_thread()` 时才会遇到；库内部的枚举不再绑定调用者线程 |
 | 某程序在私有桌面上找不到窗口 | 控制台类程序（`cmd.exe`、`ping.exe`）的窗口属于 `conhost.exe`，不在自己 pid 下 | 报错会提示；用 `agent.exec()` 在桌面内驱动它，或换 GUI 程序 |
 | 安装后没出现新的虚拟屏 | 驱动已注册但显示器未启用 | 设备管理器启用；`report.requires_reboot` 为真时重启 |
@@ -516,9 +535,13 @@ VIRTUALDESKTOP_LOG_FILE=<path>
 
 ## 已知限制
 
-- **私有桌面不能截图**：程序窗口截图和桌面截图都不行。窗口没有被系统合成、没有像素可读；
-  而该桌面的屏幕 DC 也拿不到（`BitBlt` 返回拒绝访问）。用 `agent.info()` / `agent.text()` 读状态，
-  需要像素请改用虚拟显示器。
+- **私有桌面不能做桌面截图**：拍整块屏幕不行，因为该桌面没有被合成到任何输出上，屏幕 DC 也
+  拿不到。**但程序窗口截图可以**——`PrintWindow` 让窗口自己绘制到调用方给的 DC，不需要屏幕，
+  所以私有桌面上的窗口截图与共享模式逐字节一致。
+- **窗口必须是显示状态才可截图**：被 `SW_HIDE` 隐藏的窗口会返回纯色块（它压根不绘制）。
+  本库启动程序时按此处理，由放置流程负责在正确位置恢复显示。
+- **共享模式下程序启动瞬间可能极短暂可见**：程序自己显示窗口，库随即隐藏并移走它。这个间隙在
+  私有桌面上不存在（窗口创建在另一块桌面上，从不经过你的屏幕）；需要完全杜绝请用私有桌面。
 - **私有桌面不能用真实鼠标 / 滚轮 / 真实键盘**：那里没有活动指针和键盘焦点；消息驱动可用。
 - **窗口无法在私有桌面之间搬运**：Windows 不允许跨桌面移动窗口。
 - 部分应用（UWP、硬件叠加层、DRM 受保护内容）任何离屏方式都抓不到——系统限制。

{virtualdesktop-1.4.1 → virtualdesktop-1.5.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.4.1"
+__version__ = "1.5.0"
 
 __all__ = [
     "__version__",

{virtualdesktop-1.4.1 → virtualdesktop-1.5.0}/VirtualDesktop/_desktop_runtime.py

@@ -310,6 +310,77 @@ def _uia_tree(hwnd: int, *, depth: int = 8, max_nodes: int = 500, view: str = "R
     return {"ok": True, "tree": {"view": view, "count": len(nodes), "nodes": nodes}}
 
 
+def _capture(hwnd: int, path: str, *, client_only=None, methods=None, require_content=None) -> dict:
+    """Capture ``hwnd`` and write it to ``path``, **from inside this desktop**.
+
+    The capture has to happen here for the same reason the UIA walk does: ``IsWindow`` and
+    ``GetWindowRect`` are scoped to the calling thread's desktop and report
+    ``ERROR_INVALID_WINDOW_HANDLE`` for a window on another desktop, so the capture engine cannot
+    even validate a cross-desktop handle.  Run inside, the handle is ordinary and every backend
+    works — ``PrintWindow`` asks the owning process to paint itself, which needs no screen.
+
+    A window that was never shown still answers ``PrintWindow`` successfully and paints a solid
+    rectangle, so a blank frame is reported as an error rather than saved as a real screenshot.
+    """
+    from VirtualDesktop.capture import CaptureEngine
+
+    engine = CaptureEngine(methods=tuple(methods)) if methods else CaptureEngine()
+    engine.ensure_dpi_aware()
+
+    # A window that was just created may not have painted yet, and a window created with SW_HIDE
+    # never paints at all.  Retry briefly so the first case succeeds and the second still gets a
+    # clear "blank" answer instead of a generic failure.
+    #
+    # ``require_content=False`` here on purpose: the engine's own validation raises a generic
+    # CaptureError for a blank frame, which looks identical to a real backend failure.  Taking the
+    # frame and judging it ourselves is what makes "the window was never shown" reportable.
+    deadline = time.monotonic() + 6.0
+    last_error = ""
+    last_stats: dict = {}
+    last_method = ""
+    last_size: list = []
+    while True:
+        try:
+            frame = engine.capture(
+                hwnd,
+                client_only=client_only,
+                require_content=False,
+                save_to=path,
+            )
+        except Exception as exc:  # noqa: BLE001 - retried below, then reported
+            last_error = f"{type(exc).__name__}: {exc}"
+            if time.monotonic() >= deadline:
+                return {"ok": False, "error": last_error}
+            time.sleep(0.3)
+            continue
+
+        blank = bool(frame.analysis.blank) if frame.analysis is not None else False
+        last_stats = frame.analysis.to_dict() if frame.analysis is not None else {}
+        last_method = frame.method
+        last_size = list(frame.size)
+        if not blank:
+            return {
+                "ok": True,
+                "saved": path,
+                "method": frame.method,
+                "size": list(frame.size),
+                "blank": False,
+                "analysis": last_stats,
+            }
+        if time.monotonic() >= deadline:
+            return {
+                "ok": False,
+                "error": "the captured frame is blank; the window was probably never shown",
+                "hint": "A window created with SW_HIDE does not paint itself. Launch it with "
+                "show=True (agent.launch does this by default), or call ShowWindow(SW_SHOW) first.",
+                "blank": True,
+                "method": last_method,
+                "size": last_size,
+                "analysis": last_stats,
+            }
+        time.sleep(0.3)
+
+
 def _handle(request: dict) -> dict:
     if not _kernel32.GetCurrentProcessId():  # pragma: no cover - keeps kernel32 referenced
         pass
@@ -325,6 +396,14 @@ def _handle(request: dict) -> dict:
         return _keys(int(request["hwnd"], 0), str(request.get("text", "")))
     if command == "screenshot":
         return _screenshot(int(request["hwnd"], 0), str(request["path"]))
+    if command == "capture":
+        return _capture(
+            int(request["hwnd"], 0),
+            str(request["path"]),
+            client_only=request.get("client_only"),
+            methods=request.get("methods"),
+            require_content=request.get("require_content"),
+        )
     if command == "windows":
         return _windows()
     if command == "uia_tree":

{virtualdesktop-1.4.1 → virtualdesktop-1.5.0}/VirtualDesktop/_winapi.py

@@ -646,6 +646,31 @@ def _process_name_for_pid(pid: int, cache: Optional[dict] = None) -> str:
     return name
 
 
+def pid_alive(pid: int) -> bool:
+    """Whether a process still exists.
+
+    A process that has exited but whose handle we never had is not a failure here: the caller only
+    needs "is it still running", and ``ERROR_INVALID_PARAMETER`` from ``OpenProcess`` for a dead pid
+    answers exactly that.
+    """
+    if not IS_WINDOWS:  # pragma: no cover - Windows-only library
+        return False
+    if not pid:
+        return False
+    PROCESS_QUERY_LIMITED_INFORMATION = 0x1000
+    STILL_ACTIVE = 259
+    handle = kernel32.OpenProcess(PROCESS_QUERY_LIMITED_INFORMATION, False, int(pid))
+    if not handle:
+        return False
+    try:
+        code = wintypes.DWORD()
+        if not kernel32.GetExitCodeProcess(handle, ctypes.byref(code)):
+            return False
+        return code.value == STILL_ACTIVE
+    finally:
+        kernel32.CloseHandle(handle)
+
+
 def list_windows(*, include_hidden: bool = True) -> List[WindowRecord]:
     """Enumerate top-level windows with the metadata needed for selection."""
     require_windows("list_windows")

{virtualdesktop-1.4.1 → virtualdesktop-1.5.0}/VirtualDesktop/agent.py

@@ -207,10 +207,17 @@ class AgentSession:
         *,
         title: Optional[str] = None,
         timeout: Optional[float] = None,
+        show: bool = True,
     ) -> AgentProcess:
-        """Start a program on the desktop and wait for its window."""
+        """Start a program on the desktop and wait for its window.
+
+        ``show`` defaults to ``True`` — counter-intuitive for a *hidden* desktop, but load-bearing:
+        a window created with ``SW_HIDE`` still answers ``PrintWindow`` successfully, yet paints
+        nothing, so ``screenshot()`` would return a solid rectangle.  Showing it costs nothing (the
+        desktop is not displayed on any monitor) and is what makes the window capturable.
+        """
         command = [str(a) for a in argv]
-        process = self.desktop.launch(command, show=False, wait_for_window=0.0)
+        process = self.desktop.launch(command, show=show, wait_for_window=0.0)
         record = self.desktop.find_window(
             process.pid, timeout=timeout or self.timeout, title_hint=title
         )
@@ -268,22 +275,102 @@ class AgentSession:
         )
         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.
-
-        Kept as an explicit failure rather than removed, so a caller who expects it gets a reason
-        instead of an ``AttributeError``.  All four capture backends were measured inside a private
-        desktop and all return a blank frame — ``PrintWindow`` (both flag variants) and ``WM_PRINT``
-        give variance 0, and ``BitBlt`` fails outright, because the desktop is never composited.
-
-        Use :class:`~VirtualDesktop.workspace.VirtualWorkspace` in shared mode when screenshots are
-        required: its windows live on the virtual display but stay ordinary, paintable windows.
+    def screenshot(
+        self,
+        window: Any,
+        path: Optional[str] = None,
+        *,
+        client_only: Optional[bool] = None,
+        methods: Optional[Sequence[str]] = None,
+        require_content: Optional[bool] = None,
+    ):
+        """Capture ``window`` and return the :class:`~VirtualDesktop.capture.Frame`.
+
+        The capture runs **inside the desktop**, not in the calling process.  That is not a
+        preference: ``IsWindow`` and ``GetWindowRect`` are scoped to the caller's desktop and report
+        ``ERROR_INVALID_WINDOW_HANDLE`` for a window elsewhere, so the capture engine cannot even
+        validate a cross-desktop handle from outside.  Inside, the handle is ordinary and
+        ``PrintWindow`` works — it asks the owning process to paint itself into our DC, which needs
+        no screen and no compositing.
+
+        A window that was never shown still answers ``PrintWindow`` successfully and paints a solid
+        rectangle, so a blank result raises rather than being returned as a screenshot.
+        :meth:`launch` shows windows by default for exactly this reason.
+
+        ``path`` is optional.  When given it must be **absolute** — it is resolved by the desktop
+        process, whose working directory is not the caller's.  When omitted, the frame is captured
+        to a temporary file inside the desktop and read back into memory here.
         """
-        raise OffscreenMountError(
-            "windows on a private desktop cannot be captured; there are no pixels to read",
-            code="capture-needs-shared-workspace",
-            hint="Use VirtualWorkspace(VirtualWorkspace.SHARED) — its windows are ordinary windows "
-            "on the virtual display and capture normally — or read state with info()/text() here.",
+        hwnd = _handle(window)
+        required_path = Path(path) if path else None
+        target = required_path or Path(self._control) / f"shot-{uuid.uuid4().hex[:8]}.png"
+        try:
+            payload = self.command(
+                "capture",
+                hwnd=hwnd,
+                path=str(target),
+                client_only=client_only,
+                methods=list(methods) if methods else None,
+                require_content=require_content,
+            )
+        except OffscreenMountError as exc:
+            if exc.code != "agent-command-failed":
+                raise
+            # The runtime reports a blank frame as data; surface it with the same explicit code the
+            # rest of the library uses instead of the generic "command failed".
+            details = exc.details or {}
+            blank = bool(details.get("blank"))
+            raise OffscreenMountError(
+                str(details.get("error") or exc),
+                code="capture-blank-window" if blank else "capture-failed",
+                hint=details.get("hint"),
+                details=details,
+            ) from exc
+        try:
+            return self._frame_from(payload, target, hwnd, client_only=client_only)
+        finally:
+            if required_path is None:
+                try:
+                    target.unlink(missing_ok=True)
+                except OSError:  # pragma: no cover - scratch cleanup is best effort
+                    pass
+
+    def _frame_from(
+        self, payload: Dict[str, Any], image_path: Path, hwnd: str, *, client_only
+    ):
+        """Rebuild a :class:`~VirtualDesktop.capture.Frame` from the desktop's report."""
+        from PIL import Image
+
+        from .capture import Frame, ImageAnalysis
+
+        image = Image.open(image_path)
+        image.load()
+        stats = payload.get("analysis") or {}
+        analysis = (
+            ImageAnalysis(
+                width=int(stats.get("width", image.width)),
+                height=int(stats.get("height", image.height)),
+                variance=float(stats.get("variance", 0.0)),
+                mean=float(stats.get("mean", 0.0)),
+                max_value=int(stats.get("max_value", 0)),
+                dominant_ratio=float(stats.get("dominant_ratio", 0.0)),
+                uniform=bool(stats.get("uniform", False)),
+                blank=bool(stats.get("blank", False)),
+                reason=str(stats.get("reason", "")),
+            )
+            if stats
+            else None
+        )
+        return Frame(
+            image=image,
+            hwnd=int(hwnd, 16),
+            method=str(payload.get("method", "")),
+            region=None,
+            client_only=bool(client_only) if client_only is not None else None,
+            dpi_aware=True,
+            attempts=[],
+            analysis=analysis,
+            duration=0.0,
         )
 
     def exec(self, code: str, *, timeout: Optional[float] = None) -> str:
@@ -304,6 +391,11 @@ def _handle(window: Any) -> str:
     return hex(int(handle))
 
 
+def _handle_int(window: Any) -> int:
+    """The same handle as :func:`_handle`, but as an ``int`` for the in-process capture API."""
+    return int(_handle(window), 16)
+
+
 def _python() -> str:
     """Same interpreter as the caller, so imports resolve the same way."""
     import sys

{virtualdesktop-1.4.1 → virtualdesktop-1.5.0}/VirtualDesktop/capture.py

@@ -446,7 +446,12 @@ class CaptureEngine:
         (PNG by default) before returning it.
         """
         require_windows("CaptureEngine.capture")
-        if not user32.IsWindow(hwnd):
+        # ``IsWindow`` is scoped to the **calling thread's desktop**, so it answers False for a
+        # window that lives on another desktop — which is exactly the case this library creates
+        # (``VirtualDesktop``) and would make capture impossible there.  ``GetWindowRect`` accepts
+        # any valid handle regardless of desktop, so it is the right validity probe here.
+        probe = _RECT()
+        if not user32.GetWindowRect(hwnd, ctypes.byref(probe)):
             raise CaptureError(
                 f"0x{hwnd:X} is not a window (it may have been closed)", code="invalid-hwnd"
             )