VirtualDesktop 1.4.0__tar.gz → 1.5.0__tar.gz

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

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: VirtualDesktop
-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.
+Version: 1.5.0
+Summary: win10-win11 虚拟桌面
 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
@@ -56,7 +57,9 @@ Dynamic: license-file
 
 # VirtualDesktop
 
-在 Windows 上把程序的窗口放到**你看不到的地方**去运行，并读取、操作它。窗口不出现在你的屏幕上，
+win10-win11 虚拟桌面
+
+把程序的窗口放到**你看不到的地方**去运行，并读取、操作它。窗口不出现在你的屏幕上，
 退出时自动还原。
 
 ```python
@@ -78,7 +81,8 @@ 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）。
 
 | | 私有桌面 | 虚拟显示器 |
@@ -87,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、不能装驱动                     → 私有桌面
 要"退出后什么都不留"（进程随桌面一起结束）   → 私有桌面
 需要窗口完全不出现在任何可见位置          → 私有桌面
@@ -129,7 +139,7 @@ uv add VirtualDesktop             # uv（写入 pyproject.toml 并锁定）
 两条常用组合：
 
 - **只是想安静地跑一个窗口并抓图** → `OffscreenSession` + `virtual_screen`
-- **想并行跑很多互不干扰的实例** → 每个实例一个 `VirtualWorkspace("名字")`
+- **想并行跑很多互不干扰的实例，同时要窗口截图** → 每个实例一个 `VirtualWorkspace("名字")`
 
 ---
 
@@ -145,7 +155,7 @@ uv add VirtualDesktop             # uv（写入 pyproject.toml 并锁定）
 | 系统 | Windows 10 / 11（无 IddCx 版本要求） |
 | 权限 | 当前用户即可，**不提权** |
 | 驱动 | 不需要 |
-| 依赖 | 仅 Pillow |
+| 依赖 | Pillow + comtypes |
 
 ## 基本用法
 
@@ -214,19 +224,29 @@ with VirtualWorkspace("lab") as space, space.agent() as agent:
 | `agent.exec("python 代码")` | 在桌面内跑任意 Python，返回打印内容 |
 
 `exec` 是逃生舱：里面的代码能 `import VirtualDesktop`、能用 `list_windows()`、`CaptureEngine`，
-也能用你自己装的任何库。代理本身只依赖 ctypes，不需要额外安装。
+也能用你自己装的任何库。代理本身只依赖 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"`），
+> 因为它压根不绘制——本库启动程序时会由放置流程负责在目标位置恢复显示。
 
 ## 能力边界
 
@@ -239,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()` | **不能** | 依赖真实输入与前台焦点 |
 
-要点：**能用消息驱动的都能用，需要真实输入设备的都不能用，两种截图都不能用**。需要截图或需要
-真实鼠标/滚轮的应用，请改用下面的虚拟显示器方案。
+要点：**能用消息驱动的都能用，需要真实输入设备的都不能用；程序窗口截图可以，桌面截图不行**。
+需要桌面截图或真实鼠标/滚轮的应用，请改用下面的虚拟显示器方案。
 
 ## 支持的能力与调用方式
 
@@ -261,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，这是私有桌面唯一可用的取树方式：
@@ -296,7 +317,7 @@ with VirtualWorkspace("lab") as space, space.agent() as agent:
 | 系统 | **Windows 10 1809 (build 17763) 或更高**（更低版本没有 IddCx 框架） |
 | 权限 | 安装/卸载驱动需要管理员，弹**一次 UAC** |
 | 驱动 | 首次使用时自动下载安装（也可预先装好） |
-| 依赖 | 仅 Pillow |
+| 依赖 | Pillow + comtypes |
 
 ## 装驱动
 
@@ -554,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` 为真时重启 |
@@ -571,9 +592,13 @@ VIRTUALDESKTOP_LOG_FILE=<path>
 
 ## 已知限制
 
-- **私有桌面不能截图**：程序窗口截图和桌面截图都不行。窗口没有被系统合成、没有像素可读；
-  而该桌面的屏幕 DC 也拿不到（`BitBlt` 返回拒绝访问）。用 `agent.info()` / `agent.text()` 读状态，
-  需要像素请改用虚拟显示器。
+- **私有桌面不能做桌面截图**：拍整块屏幕不行，因为该桌面没有被合成到任何输出上，屏幕 DC 也
+  拿不到。**但程序窗口截图可以**——`PrintWindow` 让窗口自己绘制到调用方给的 DC，不需要屏幕，
+  所以私有桌面上的窗口截图与共享模式逐字节一致。
+- **窗口必须是显示状态才可截图**：被 `SW_HIDE` 隐藏的窗口会返回纯色块（它压根不绘制）。
+  本库启动程序时按此处理，由放置流程负责在正确位置恢复显示。
+- **共享模式下程序启动瞬间可能极短暂可见**：程序自己显示窗口，库随即隐藏并移走它。这个间隙在
+  私有桌面上不存在（窗口创建在另一块桌面上，从不经过你的屏幕）；需要完全杜绝请用私有桌面。
 - **私有桌面不能用真实鼠标 / 滚轮 / 真实键盘**：那里没有活动指针和键盘焦点；消息驱动可用。
 - **窗口无法在私有桌面之间搬运**：Windows 不允许跨桌面移动窗口。
 - 部分应用（UWP、硬件叠加层、DRM 受保护内容）任何离屏方式都抓不到——系统限制。

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

@@ -1,6 +1,8 @@
 # VirtualDesktop
 
-在 Windows 上把程序的窗口放到**你看不到的地方**去运行，并读取、操作它。窗口不出现在你的屏幕上，
+win10-win11 虚拟桌面
+
+把程序的窗口放到**你看不到的地方**去运行，并读取、操作它。窗口不出现在你的屏幕上，
 退出时自动还原。
 
 ```python
@@ -22,7 +24,8 @@ 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）。
 
 | | 私有桌面 | 虚拟显示器 |
@@ -31,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、不能装驱动                     → 私有桌面
 要"退出后什么都不留"（进程随桌面一起结束）   → 私有桌面
 需要窗口完全不出现在任何可见位置          → 私有桌面
@@ -73,7 +82,7 @@ uv add VirtualDesktop             # uv（写入 pyproject.toml 并锁定）
 两条常用组合：
 
 - **只是想安静地跑一个窗口并抓图** → `OffscreenSession` + `virtual_screen`
-- **想并行跑很多互不干扰的实例** → 每个实例一个 `VirtualWorkspace("名字")`
+- **想并行跑很多互不干扰的实例，同时要窗口截图** → 每个实例一个 `VirtualWorkspace("名字")`
 
 ---
 
@@ -89,7 +98,7 @@ uv add VirtualDesktop             # uv（写入 pyproject.toml 并锁定）
 | 系统 | Windows 10 / 11（无 IddCx 版本要求） |
 | 权限 | 当前用户即可，**不提权** |
 | 驱动 | 不需要 |
-| 依赖 | 仅 Pillow |
+| 依赖 | Pillow + comtypes |
 
 ## 基本用法
 
@@ -158,19 +167,29 @@ with VirtualWorkspace("lab") as space, space.agent() as agent:
 | `agent.exec("python 代码")` | 在桌面内跑任意 Python，返回打印内容 |
 
 `exec` 是逃生舱：里面的代码能 `import VirtualDesktop`、能用 `list_windows()`、`CaptureEngine`，
-也能用你自己装的任何库。代理本身只依赖 ctypes，不需要额外安装。
+也能用你自己装的任何库。代理本身只依赖 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"`），
+> 因为它压根不绘制——本库启动程序时会由放置流程负责在目标位置恢复显示。
 
 ## 能力边界
 
@@ -183,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()` | **不能** | 依赖真实输入与前台焦点 |
 
-要点：**能用消息驱动的都能用，需要真实输入设备的都不能用，两种截图都不能用**。需要截图或需要
-真实鼠标/滚轮的应用，请改用下面的虚拟显示器方案。
+要点：**能用消息驱动的都能用，需要真实输入设备的都不能用；程序窗口截图可以，桌面截图不行**。
+需要桌面截图或真实鼠标/滚轮的应用，请改用下面的虚拟显示器方案。
 
 ## 支持的能力与调用方式
 
@@ -205,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，这是私有桌面唯一可用的取树方式：
@@ -240,7 +260,7 @@ with VirtualWorkspace("lab") as space, space.agent() as agent:
 | 系统 | **Windows 10 1809 (build 17763) 或更高**（更低版本没有 IddCx 框架） |
 | 权限 | 安装/卸载驱动需要管理员，弹**一次 UAC** |
 | 驱动 | 首次使用时自动下载安装（也可预先装好） |
-| 依赖 | 仅 Pillow |
+| 依赖 | Pillow + comtypes |
 
 ## 装驱动
 
@@ -498,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` 为真时重启 |
@@ -515,9 +535,13 @@ VIRTUALDESKTOP_LOG_FILE=<path>
 
 ## 已知限制
 
-- **私有桌面不能截图**：程序窗口截图和桌面截图都不行。窗口没有被系统合成、没有像素可读；
-  而该桌面的屏幕 DC 也拿不到（`BitBlt` 返回拒绝访问）。用 `agent.info()` / `agent.text()` 读状态，
-  需要像素请改用虚拟显示器。
+- **私有桌面不能做桌面截图**：拍整块屏幕不行，因为该桌面没有被合成到任何输出上，屏幕 DC 也
+  拿不到。**但程序窗口截图可以**——`PrintWindow` 让窗口自己绘制到调用方给的 DC，不需要屏幕，
+  所以私有桌面上的窗口截图与共享模式逐字节一致。
+- **窗口必须是显示状态才可截图**：被 `SW_HIDE` 隐藏的窗口会返回纯色块（它压根不绘制）。
+  本库启动程序时按此处理，由放置流程负责在正确位置恢复显示。
+- **共享模式下程序启动瞬间可能极短暂可见**：程序自己显示窗口，库随即隐藏并移走它。这个间隙在
+  私有桌面上不存在（窗口创建在另一块桌面上，从不经过你的屏幕）；需要完全杜绝请用私有桌面。
 - **私有桌面不能用真实鼠标 / 滚轮 / 真实键盘**：那里没有活动指针和键盘焦点；消息驱动可用。
 - **窗口无法在私有桌面之间搬运**：Windows 不允许跨桌面移动窗口。
 - 部分应用（UWP、硬件叠加层、DRM 受保护内容）任何离屏方式都抓不到——系统限制。