VirtualDesktop 1.0.1__tar.gz

virtualdesktop-1.0.1/LICENSE

@@ -0,0 +1,21 @@
+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.

virtualdesktop-1.0.1/PKG-INFO

@@ -0,0 +1,307 @@
+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)。

virtualdesktop-1.0.1/README.md

@@ -0,0 +1,251 @@
+# 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)。