Metadata-Version: 2.4
Name: VirtualDesktop
Version: 1.0.1
Summary: Automated offscreen window mounting on a virtual display for Windows: driver bootstrap, desktop binding, window hiding and PrintWindow capture behind one context manager.
Author: VirtualDesktop contributors
License: MIT License
        
        Copyright (c) 2026 offscreen-mount contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Documentation, https://github.com/Luofeng-Cloud/VirtualDesktop#readme
Project-URL: Source, https://github.com/Luofeng-Cloud/VirtualDesktop
Project-URL: Issues, https://github.com/Luofeng-Cloud/VirtualDesktop/issues
Keywords: windows,virtual-display,idd,printwindow,automation,screenshot,ocr
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Win32 (MS Windows)
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: Microsoft :: Windows :: Windows 10
Classifier: Operating System :: Microsoft :: Windows :: Windows 11
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: System :: Systems Administration
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Pillow>=9.0
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Provides-Extra: build
Requires-Dist: build>=1.0; extra == "build"
Requires-Dist: twine>=5.0; extra == "build"
Dynamic: license-file

# VirtualDesktop

在 Windows 上把窗口挂到**虚拟显示器**上截图：用户看不到、任务栏不留痕、退出自动还原。
一次 `pip install`，首次调用时自动完成虚拟显示器驱动安装。

```python
from VirtualDesktop import OffscreenSession

with OffscreenSession(target_window_title="微信") as session:
    session.mount()                 # 按需装驱动 + 隐藏窗口
    frame = session.capture()       # PrintWindow，自动回退到可用后端
    frame.image.save("wechat.png")  # PIL.Image
# 退出时窗口回到原位，任务栏样式恢复
```

适用于 UI 自动化、不在前台打扰用户的截图/OCR、需要在无人值守环境里抓取应用界面。

---

# 一、使用说明

## 安装

```bash
pip install VirtualDesktop
```

运行时依赖只有 **Pillow**。需要 **Windows 10 1809 (build 17763) 或更高**；更低版本没有
IddCx（间接显示驱动框架），无法承载虚拟显示器，`VirtualDesktop check` 会直接说明这一点。

## 快速开始

```python
from VirtualDesktop import OffscreenSession

session = OffscreenSession(
    window_class="WeChatLoginWndForPC",   # 按类名定位（也可用标题/进程名/PID）
    window_pid=1234,
)
session.mount()                # 首次会弹一次 UAC 装驱动
print(session.hide_mode_used)  # 实际用了哪种隐藏方式
frame = session.capture()
frame.image.save("shot.png")
session.unmount()              # 幂等
```

用 `with` 语句或 `try/finally` 都行：异常时同样会还原窗口。

窗口定位支持四种方式，可组合使用：`target_window_title`、`window_class`、`process_name`、
`window_pid`。不确定时先用 `VirtualDesktop list-windows` 查。

## 命令行

```bash
VirtualDesktop check                      # 只读体检：系统版本 / 显示器 / 驱动 / 缓存 / 签名
VirtualDesktop list-windows               # 列出可选窗口
VirtualDesktop capture "微信" --out wx.png --unmount
VirtualDesktop install-driver --dry-run   # 打印将要执行的特权命令，不安装
VirtualDesktop install-driver             # 安装驱动（弹一次 UAC）
VirtualDesktop uninstall-driver --purge-files
```

`capture` 和 `mount` 还支持 `--hide-mode`、`--monitor`、`--methods`、`--virtual-size`、
`--virtual-dpi`、`--ui-tree`、`--desktop-shot` 等开关，用 `--help` 查看全部。

## 两种隐藏方式

`SessionConfig.hide_mode` 三选一，默认 `virtual_screen`：

| 模式 | 做法 | 需要驱动 | 窗口在哪 |
|---|---|---|---|
| `virtual_screen`（默认） | 移到虚拟显示器 | 是 | 虚拟屏上 |
| `offscreen` | 移出所有显示器的坐标区 | 否 | 任何屏幕之外 |
| `auto` | 先试前者，不可用则退到后者 | 否 | 视情况 |

```python
from VirtualDesktop import OffscreenSession, SessionConfig

session = OffscreenSession(
    target_window_title="微信",
    config=SessionConfig(hide_mode="offscreen"),
)
session.mount(install_driver=False)   # 完全不需要驱动
```

两种模式都会去掉任务栏按钮和 Alt+Tab 痕迹，并且都能在隐藏状态下截图；`unmount()` 会把
几何还原到挂载前的状态。

> 用 `offscreen` 时窗口不在任何显示器上，所以桌面截图里**看不到它**——这是设计如此。
> 窗口自身的截图请用 `session.capture()`。

## 虚拟显示器大小与 DPI

默认与当前主屏一致，也可以指定：

```bash
VirtualDesktop capture "微信" --virtual-size 1920x1080 --virtual-dpi 125%
```

```python
from VirtualDesktop.display_setup import configure_virtual_display

result = configure_virtual_display(size="1920x1080", dpi="125%")   # 传 None 表示跟随主屏
print(result.ok, result.effective_size, result.effective_dpi)
```

## 完全不安装驱动：私有桌面

`VirtualDesktop` 创建一个私有桌面，窗口在上面运行，**零权限、零安装**：

```python
import json, tempfile
from pathlib import Path
from VirtualDesktop import VirtualDesktop

# 代理脚本在目标桌面内运行，把结果写到 --out 指定的文件
agent = Path(tempfile.mkdtemp()) / "agent.py"
agent.write_text(
    "import argparse, json\n"
    "from VirtualDesktop import CaptureEngine, list_windows, window_diagnostics\n"
    "p = argparse.ArgumentParser(); p.add_argument('--out'); a = p.parse_args()\n"
    "CaptureEngine().ensure_dpi_aware()\n"
    "data = [window_diagnostics(r.hwnd) for r in list_windows() if r.title]\n"
    "open(a.out, 'w', encoding='utf-8').write(json.dumps(data))\n",
    encoding="utf-8",
)

with VirtualDesktop("my-workspace") as desktop:
    process = desktop.launch(["charmap.exe"], show=False)
    out = Path(tempfile.mkdtemp()) / "report.json"
    windows = desktop.run_agent(agent, ["--out", str(out)])
# 退出时桌面关闭，其上进程一并结束
```

私有桌面是隔离边界：跨桌面的截图和 UI Automation 都不可用，所以枚举、截图、点击必须在目标
桌面**内的进程**里做。`run_agent` 就是为此准备的——它把你的脚本作为代理进程放进该桌面，再用
文件把结果传回来。

## 截图方式

`session.capture()` 会依次尝试多种后端，直到拿到**有内容**的帧。默认顺序：

`printwindow`（`PW_RENDERFULLCONTENT`）→ `printwindow_plain` → `wm_print` → `bitblt`

每个结果都做统计判定：方差接近 0（未绘制/全黑/全白），或单色占比 ≥ 99.9% 且无结构，即判为
失败并换下一个后端。所以"偶尔拿到黑图"会变成确定性的回退，而不是静默产出坏图。

需要指定后端或整窗（含标题栏）时：

```python
from VirtualDesktop import CaptureEngine

engine = CaptureEngine(methods=("bitblt",), client_only=False)
frame = engine.capture(hwnd, require_content=True)
print(frame.method, frame.size)      # 实际生效的后端与尺寸
```

## 配置项

所有开关都可以用环境变量设置，便于计划任务和 CI：

```
VIRTUALDESKTOP_DRIVER_POLICY=auto|never|always     VIRTUALDESKTOP_MONITOR=auto|virtual|primary|DISPLAY2
VIRTUALDESKTOP_HIDE_MODE=virtual_screen|offscreen|auto
VIRTUALDESKTOP_GITHUB_MIRRORS=<url 前缀,逗号分隔>   VIRTUALDESKTOP_CACHE_DIR=<path>
VIRTUALDESKTOP_MANIFEST=<path to manifest.json>    VIRTUALDESKTOP_SIGNATURE_POLICY=warn|strict|off
VIRTUALDESKTOP_CAPTURE_METHODS=printwindow,bitblt  VIRTUALDESKTOP_DEBUG=1
VIRTUALDESKTOP_LOG_FILE=<path>
```

## 故障排查

| 现象 | 原因 | 处理 |
|---|---|---|
| `DriverNotFoundError` | 未装虚拟显示器，且 `install_driver=False` 或 `driver_policy=never` | 去掉限制，或先跑 `VirtualDesktop install-driver` |
| `ElevationDenied` | UAC 被取消或被策略阻止 | 在管理员终端执行一次 `VirtualDesktop install-driver` |
| `unsupported-windows-build` | 系统低于 Win10 1809，没有 IddCx | 换系统，或改用 `VirtualDesktop` / `hide_mode="offscreen"` |
| 安装后没出现新的虚拟屏 | 驱动已注册但显示器未启用 | 设备管理器启用该设备；`report.requires_reboot` 为真时重启 |
| 驱动下载失败或极慢 | github.com 不可达 | 加 `VIRTUALDESKTOP_GITHUB_MIRRORS`，或预置离线缓存（见下） |
| 截图是黑帧 | 应用为硬件加速 / 受保护内容 | 属系统限制；换 `bitblt` 试试，或确认窗口确实有内容 |

**离线 / 内网部署**：把安装包按清单里的文件名（`VirtualDesktop/driver_manifest.json` 的
`artifact.filename`）放进 `VIRTUALDESKTOP_CACHE_DIR`，就不会联网下载；也可以把
`VIRTUALDESKTOP_MANIFEST` 指向自建镜像的清单（含自算摘要）。

---

# 二、安全说明

## 驱动来源与校验

虚拟显示器驱动使用
[VirtualDrivers/Virtual-Display-Driver](https://github.com/VirtualDrivers/Virtual-Display-Driver)
（`MttVDD`，IddCx 间接显示驱动，SignPath Foundation 签名）。

驱动与工具二进制**不打进 wheel**，首次使用时按需下载。下载链路有三道校验，任何一道不过就
中止，不会把未经验证的文件交给系统：

1. **SHA-256 摘要**：与随包发布的清单 `driver_manifest.json` 中固定的摘要逐字节比对，决定了
   "拿到的确实是那一个发布文件"。不匹配的文件会被隔离（`cache/quarantine`）而不是使用。
2. **Authenticode 验签**：比对签名者证书指纹与清单中固定的允许值，防止替换成其他发布者的
   同版本文件。
3. **系统安装校验**：文件最后交给 Windows 安装，由系统再验一次驱动签名。

## 国内下载加速是安全的

`github.com` 在国内经常不可达，因此清单里为每个安装包列了多个加速镜像，主 URL 失败时按顺序
重试。**加镜像不会降低安全性**：镜像只影响"从哪里拿字节"，摘要校验在拿到之后照常执行，所以
镜像要么给出完全相同的文件，要么被第 1 道校验拒绝、随后被隔离。它无法让不同的内容通过。

镜像返回的文件大小与摘要都会核对（例如驱动包固定为 132118 字节 /
`e24210692b442b39af763536330ce78b423f19342b7a7792c26de3944e418b3a`）。

需要自建或更换镜像时：

```bash
# 完整 URL 或 URL 前缀（前缀以 / 或 ? 结尾，会自动拼上原始 GitHub 链接），逗号分隔
set VIRTUALDESKTOP_GITHUB_MIRRORS=https://gh-proxy.com/,https://internal.example/mirror/
```

同样只接受 `https://`，且一样要过摘要校验。

## 权限与提权

安装/卸载驱动需要管理员权限，会弹 **一次 UAC**，由你确认。除此之外，库本身以当前用户权限
运行，不需要管理员。

如果希望完全不提权，用私有桌面（`VirtualDesktop`）或 `hide_mode="offscreen"`，
两者都不需要任何驱动。

## 运行期行为

- **不改动你的桌面**：窗口只是被移动位置，退出（含异常退出）时还原到原位与原有样式。
- **不注入目标进程**：不写目标进程内存、不挂钩子；窗口操作走公开的 Win32 窗口 API，
  截图走 `PrintWindow` 等系统接口。
- **网络访问仅限下载安装包**：没有遥测、没有上传，运行期不与任何服务器通信。
- **文件写入仅在缓存目录**：默认 `%LOCALAPPDATA%\VirtualDesktop\cache`，可用
  `VIRTUALDESKTOP_CACHE_DIR` 更改。

## 已知限制

- 部分应用（UWP、硬件叠加层、DRM 受保护内容）任何离屏方式都抓不到——系统限制，非本库缺陷。
- 自绘界面的应用（如微信 3.9.x）没有子窗口，UI Automation 只暴露顶层 `Pane`，组件粒度只能到
  窗口级；控件级定位需要靠截图像素。Electron/浏览器类应用的 UIA 树是完整的。
- ARM64 自动选用清单里的 ARM64 驱动变体；x64 / x86 共用同一份驱动包。

---

# 许可证

MIT，见 [LICENSE](LICENSE)。
