PowerToys MouseUtils CursorWrap 故障排查与验证指南：从显示器布局采集到边缘检测自动化测试

本文基于 PowerToys 仓库中 CURSOR_WRAP_TESTS.md 测试文档及其配套脚本，系统讲解 CursorWrap（鼠标边缘环绕）功能在单/多显示器环境下失效时的标准排查流程：用 PowerShell 采集真实显示器布局、用 Python 测试套件验证边缘检测与环绕计算、用结果分析器定位根因。读完你不仅能复现官方诊断链路，还能理解其背后的"外边缘多边形 + 邻接容差"实现原理，并借助可生成 Copilot 修复提示的自动化报告快速排查问题。

CursorWrap 的工作原理与适用边界

CursorWrap 是 PowerToys MouseUtils 工具组中的鼠标增强功能：当光标到达屏幕边缘时自动从对侧边缘"环绕"回来。在动手排查之前，需要先明确其设计模型，才能判断"异常"究竟是缺陷还是预期行为：

• 单显示器场景始终可用：单个显示器没有与其他屏幕相邻的边，四条边全部是外边缘，光标无论从哪个方向越界都会环绕回同一屏幕的对侧边缘。因此单屏下 CursorWrap 的兜底逻辑不依赖任何拓扑判断。
• 多显示器场景基于"外边缘多边形"：CursorWrap 会为所有显示器的外侧边缘构造一个包围多边形，内部相邻显示器的边会被忽略。显示器与显示器之间的光标移动由 Windows 原生处理，CursorWrap 完全不介入，它只负责"最外层边界"的环绕。
• 常见的失效原因：项目文档记录的少数多屏异常案例，其根因是某台显示器没有与相邻显示器精确"吸附"对齐。Windows「显示设置」中拖动显示器时存在"贴边吸附"行为，若显示器间存在间隙，环绕行为就可能不符合直觉。

底层实现印证了这一模型：在 MonitorTopology.h 中，IdentifyOuterEdges() 负责从所有 MonitorEdge 中筛出外边缘（isOuter），而 EdgesAreAdjacent() 使用 50 像素容差（int tolerance = 50）判断两条边是否相邻，该容差与 Python 测试端 ADJACENCY_TOLERANCE = 50 一一对应；CursorWrapCore.h 中的 HandleMouseMove 则是每次鼠标移动时触发环绕判定的核心引擎。

官方标准排查流程（三步走）

当用户反馈 CursorWrap 未按预期工作，按以下顺序执行三件工具，即可获得结构化的诊断结论：

步骤	工具	作用	产物
1	Capture-MonitorLayout.ps1（PowerShell）	采集当前 PC 的真实显示器布局（位置、尺寸、DPI、缩放、主屏标记）	<用户名>_monitor_layout.json
2	monitor_layout_tests.py（Python）	基于采集到的布局 JSON 验证边缘检测与环绕行为	test_report.json
3	analyze_test_results.py（Python）	分析测试输出，解释为什么环绕不工作、给出修复建议	终端报告 / Copilot 修复提示

三个脚本均位于仓库的 CursorWrapTests 目录下。

步骤一：用 PowerShell 采集真实显示器布局

在 CursorWrapTests 目录下以 PowerShell 运行：

.\Capture-MonitorLayout.ps1

脚本默认生成名为 cursorwrap_monitor_layout.json 的文件（文档中描述的文件名模板为 "$($env:USERNAME)_monitor_layout.json"，实际默认值以脚本为准，可通过 -OutputPath 自定义）。输出的 JSON 是一个显示器数组，每个元素包含位置（left/top/right/bottom）、宽高、dpi、缩放百分比以及是否为主显示器。

参数详解

脚本支持以下开关（均选填）：

参数	说明
-OutputPath <path>	指定输出 JSON 路径，默认 cursorwrap_monitor_layout.json
-AddUserMachineNames	在输出中写入计算机名与用户名（默认留空，保护隐私）
-AddDeviceNames	输出真实设备名（如 \\.\DISPLAY1），默认匿名化为 DISPLAY1、DISPLAY2 以避免指纹识别
-Help（别名 -h/-?）	显示详细帮助信息

典型用法示例：

# 隐私安全默认（不包含用户名/机器名）
.\Capture-MonitorLayout.ps1

# 自定义文件名
.\Capture-MonitorLayout.ps1 -OutputPath "my_setup.json"

# 排障时包含完整标识信息
.\Capture-MonitorLayout.ps1 -AddUserMachineNames -AddDeviceNames

输出结构示例

{
  "captured_at": "2026-09-06T10:00:00+08:00",
  "computer_name": "",
  "user_name": "",
  "monitor_count": 2,
  "monitors": [
    {
      "left": 0,
      "top": 0,
      "right": 1920,
      "bottom": 1080,
      "width": 1920,
      "height": 1080,
      "dpi": 96,
      "scaling_percent": 100,
      "primary": true,
      "device_name": "DISPLAY1"
    }
  ]
}

源码细节：DPI 检测与坐标语义

从脚本源码看，该工具对 DPI 的探测采用三级递进策略（见 Capture-MonitorLayout.ps1 的 Get-MonitorDPI 函数）：

1. 首选 GetDpiForMonitor（shcore.dll，Windows 8.1+，Effective DPI）；
2. 失败则退回 GetDpiForMonitor 的 RAW DPI；
3. 再退回 GetDeviceCaps（gdi32.dll）的 LOGPIXELSX 传统方案；
4. 全部失败则默认 96 DPI（100% 缩放）并输出警告。

需要特别注意的是坐标单位语义：脚本输出的 left/top/right/bottom 是逻辑像素（logical pixels），即与 DPI 无关的虚拟坐标；物理像素 = 逻辑像素 ×（DPI/96）。例如 1920 逻辑像素在 150% 缩放下对应 2880 物理像素。Windows 使用逻辑像素坐标来"吸附"显示器，如果显示器在显示设置中看起来已吸附、但采集到的坐标之间存在间隙，则属于 Windows 坐标层面的问题——这正是排查多屏环绕失效时最容易误解的一点。

脚本本身还会做一次间隙预检：当检测到两块垂直重叠的显示器之间存在大于 50px 的水平间隙时，会醒目地提示"这可能是 Windows 坐标 bug（若显示器在显示设置中显示为已吸附）"。

步骤二：用 Python 测试套件验证环绕行为

monitor_layout_tests.py 不需要编译 PowerToys，只需本机安装 Python。它有两种运行模式：

模式 A：针对真实布局验证（排障主路径）

python monitor_layout_tests.py --layout-file <json文件的路径>

可加 --verbose 查看详细输出（含 ASCII 布局图与每个配置的测试细节）。

模式 B：生成配置进行全量回归

python monitor_layout_tests.py --max-monitors 10

不带 --layout-file 时，脚本会基于内置的常见分辨率（1080p、1440p、4K、带鱼屏、16:10）与 DPI 缩放档位（96/120/144/192，即 100%/125%/150%/200%）自动生成 1～10 台显示器的数千种布局组合（水平/垂直/L 形/田字格/错位对齐等），无需真实硬件即可对边缘检测逻辑做回归测试。--max-monitors 取值范围 1～10。

输出：test_report.json

两种模式都会生成 test_report.json。文档给出了单显示器全通过的样例：

{
  "summary": {
    "total_configs": 1,
    "passed": 1,
    "failed": 0,
    "total_issues": 0,
    "pass_rate": "100.00%"
  },
  "failures": [],
  "recommendations": [
    "All tests passed - edge detection logic is working correctly!"
  ]
}

summary 中的 total_configs、passed、failed、total_issues、pass_rate 共同构成测试画像；failures 数组为空代表全部通过；recommendations 数组在存在失败时给出面向具体 C++ 函数的修复线索。

测试套件内部结构与源码佐证

从 monitor_layout_tests.py 源码可看到它针对三类断言设计：

• 单显示器边缘数（validate_single_monitor）：单屏必须恰好存在 4 条外边缘，这是基线正确性检查；
• 相邻显示器检测（validate_touching_monitors）：两块水平贴合的 1080p 显示器（m1.right == m2.left 且上下对齐）应当只有 6 条外边缘（两条相接的内边被剔除）；
• 环绕计算（validate_wrap_calculation）：对每条外边缘取 5 个采样点（端点、1/4、中点、3/4），逐一验证 calculate_wrap_position 是否产生了有效环绕。

值得强调的是，这套 Python 实现刻意镜像了 C++ 代码结构：数据类 MonitorInfo/MonitorEdge、枚举 EdgeType、MonitorTopology 类与 MonitorTopology.h 中的同名结构一一对应，ADJACENCY_TOLERANCE = 50 也直接对齐 C++ 的 EdgesAreAdjacent(..., int tolerance = 50) 默认值。也就是说，用 Python 验证通过，即等价于用与 C++ 完全相同的判定逻辑覆盖了大量硬件配置。测试结束后脚本按失败与否返回退出码（有失败返回 1），便于接入 CI。

步骤三：用分析器解读失败并生成修复提示

当 test_report.json 的 failures 数组非空时，运行第二个 Python 程序 analyze_test_results.py：

python analyze_test_results.py --report test_report.json

支持的命令行选项

  -h, --help            show this help message and exit
  --report REPORT       Path to test report JSON file
  --detailed            Show detailed failure listing
  --copilot             Generate GitHub Copilot-friendly fix prompt

--report 可指向任意路径的测试报告（默认 test_report.json）；--detailed 追加逐条失败详单（配置、期望、实际、涉及的边缘类型/位置/区间、测试点坐标）；--copilot 则不输出常规分析，而是生成一段可直接粘贴给 GitHub Copilot 的、结构化 Markdown 修复提示。

全通过时的输出示例

对单显示器测试结果运行 python analyze_test_results.py --detailed 得到：

python .\analyze_test_results.py --detailed
================================================================================
CURSORWRAP TEST RESULTS ANALYSIS
================================================================================

Total Configurations Tested: 1
Passed: 1 (100.00%)
Failed: 0
Total Issues: 0

✓ ALL TESTS PASSED! Edge detection logic is working correctly.

✓ No failures to analyze!

有失败时的分析能力

存在失败时，分析器会输出四大板块：按测试类型与按显示器配置归类的失败模式统计、针对环绕计算失败的测试点位置分布（左缘/上缘等）、对三类典型问题的成因解释，以及来自 test_report.json 的修复建议。例如遇到"环绕计算失败"，分析器会指出"部分重叠问题"（Partial Overlap Problem）：当 4K 与 1080p 显示器相邻且尺寸不一时，若当前实现把"存在任何邻接段的整条边"都标记为非外边缘，那么该边不存在邻接监视器的区段本应可环绕却失效了，并引导检查 MonitorTopology.cpp 中的 IdentifyOuterEdges()。

配合 --copilot 生成的提示还会给出建议的代码改造方向（例如把整条边的二元 isOuter 标志改为按区段记录 outerRanges、让 EdgesAreAdjacent 返回重叠区间等），使 AI 辅助修复有据可依。

进阶：用可视化模拟器做人工排查

如果命令行报告仍不够直观，同目录下的 WrapSimulator 提供了一套 Tkinter 图形化模拟器（对应 README）：

python wrap_simulator.py <monitor_layout.json>

它用与 C++ 完全一致的算法渲染显示器布局：黄色条表示"该外边缘段有环绕目标"，红条纹条表示"无环绕目标的死区"，悬停/点击可查看环绕目标与问题原因码（WRAP_MODE_DISABLED、NO_OPPOSITE_OUTER_EDGES、NO_OVERLAPPING_RANGE、SINGLE_MONITOR 等）；"Test Edges" 可自动模拟光标沿所有外边缘移动并动画显示源点与环绕终点；还能在"投影增强算法（v2）"与"旧版直接重叠算法（v1）"之间切换对比死区覆盖情况，或播放 CursorLog 采集的真实光标轨迹 CSV。可配套运行 test_new_algorithm.py 对两种算法做覆盖率对比。

排查建议速查

• 单屏不环绕：与设计模型矛盾，属于基线问题，应先用 monitor_layout_tests.py 的生成模式确认单屏 4 条外边缘检测是否正常（对应 single_monitor_edges 测试）；
• 多屏部分边缘不环绕：优先怀疑显示器未精确吸附。运行 Capture-MonitorLayout.ps1 检查输出坐标是否存在 >50px 间隙，并在 Windows「显示设置」中重新拖动吸附各屏幕；
• 多分辨率混用导致死区：属于部分重叠算法限制，可用 analyze_test_results.py --copilot 获取基于区段化外边缘重构的修复方案，或以 WrapSimulator 先行验证 v2 投影算法效果；
• 回归验证：修改任何边缘检测逻辑后，运行 python monitor_layout_tests.py --max-monitors 10，确保全部配置通过、退出码为 0。

整个排查链路"采集 → 验证 → 分析"只需本机 PowerShell 与 Python，无需搭建 PowerToys 编译环境，即可把难以复现的多屏硬件问题转化为可共享、可归档的结构化 JSON 报告。