PowerToys CursorWrap 可视化模拟器实战：从多显示器布局 JSON 到环绕（Wrap）行为诊断

2026-09-06 18:41:01作者：劳婵绚Shirley

导读

CursorWrap 是 Microsoft PowerToys 中 MouseUtils 模块内负责“鼠标到达屏幕外边缘后自动环绕到另一台显示器对应位置”的实用功能。当多显示器拓扑中存在偏移、错位或间隙时，环绕的“死区”（没有环绕目的地的边缘段）会导致鼠标在某些位置被“卡住”。仓库内 CursorWrap Simulator 是一套用 Python/Tkinter 编写、逻辑与 PowerToys CursorWrap C++ 实现完全对齐的可视化验证工具：它读取显示器布局 JSON，把每个显示器绘制成矩形，并用彩色边条标出哪些外边缘能够成功环绕、哪些是问题区域。读完本文，你将掌握该工具的启动方式、布局 JSON 与光标日志的格式规范、图形界面的全部交互要点、问题原因码体系，以及“原算法 vs 投影增强算法（v1/v2）”的底层原理与自动化测试方法，可直接用它复现、诊断和验证真实的 CursorWrap 失效场景。

一、工具定位：CursorWrap 功能的“可视化示波器”

CursorWrap Simulator 位于 WrapSimulator 目录下，与其 Python 双胞胎脚本 test_new_algorithm.py（命令行算法校验）共同构成完整的调试链。按 CURSOR_WRAP_TESTS.md 描述的排查流程，一旦用户报告 CursorWrap 在多显示器下不工作，维护者会先用 PowerShell 脚本 Capture-MonitorLayout.ps1 抓取当前显示器布局，再交给 monitor_layout_tests.py 批量测试、analyze_test_results.py 生成修复建议。而本模拟器则是其中“肉眼直观看到问题在哪”的关键一环。

需要特别澄清的是 CursorWrap 的职责边界（官方 README 与测试文档反复强调）：单台显示器之间的环绕由 Windows 自己处理，PowerToys CursorWrap 只关心多显示器整体“外轮廓”边缘。两个相邻显示器之间的内部边缘移动由系统接管，CursorWrap 不参与；它只处理所有显示器拼起来后暴露在外侧的边缘。C++ 侧 CursorWrapCore.cpp 中 HandleMouseMove 每次先做 IsOnOuterEdge 判断——不在外边缘就直接返回原位置，这印证了上述边界划分。

Python 模拟器在注释中明确写道“This is a Python port of the C++ MonitorTopology class”（参见 wrap_simulator.py 中的 MonitorTopology 类 docstring），因此你在图形界面看到的每一条判定逻辑，都与 MonitorTopology.cpp 的实际实现一一对应。

二、运行环境与启动方式

工具只依赖 Python 标准库：

Python 3.6+
Tkinter（Windows 上随标准 Python 发行版附带，无需额外安装）

命令行加载布局

python wrap_simulator.py <path_to_monitor_layout.json>

程序入口位于文件末尾的 main()（见 wrap_simulator.py）：json_file 为可选位置参数，通过 argparse 解析，随后创建 tk.Tk() 根窗口并启动 WrapSimulatorApp(root, json_file) 进入主事件循环。

不带参数启动

python wrap_simulator.py

此时应用以空布局打开，窗口内没有任何显示器。随后点击界面上的 "Load JSON" 按钮，在弹出的文件选择框里挑选布局文件即可加载。两种方式的加载逻辑都汇聚到 WrapSimulatorApp.load_json()（见 wrap_simulator.py），加载后自动重绘画布。

三、显示器布局 JSON 格式（输入数据契约）

布局 JSON 是整个工具的“病历单”。该文件的真实来源有两类：

用调试版 CursorWrap 运行时的拓扑导出（C++ 侧在 _DEBUG 下提供 GenerateTopologyJSON()，声明于 CursorWrapCore.h）；
用 Capture-MonitorLayout.ps1 采集当前系统（默认对计算机名/用户名/设备名做匿名化处理，-AddUserMachineNames、-AddDeviceNames 参数可控制是否包含敏感字段）；
完全手写，用于构造特定测试拓扑。

README 规定的最小可用结构如下（示例为三显示器中的第一个）：

{
  "captured_at": "2026-02-16T08:50:34+00:00",
  "computer_name": "MY-PC",
  "user_name": "User",
  "monitor_count": 3,
  "monitors": [
    {
      "left": 0,
      "top": 0,
      "right": 2560,
      "bottom": 1440,
      "width": 2560,
      "height": 1440,
      "dpi": 96,
      "scaling_percent": 100.0,
      "primary": true,
      "device_name": "DISPLAY1"
    }
  ]
}

各字段含义与作用如下（对照 Python 侧 MonitorInfo 数据类，见 wrap_simulator.py）：

字段	说明	解析处理
`left` / `top`	显示器工作区左上角的虚拟屏幕坐标	用于计算矩形几何位置
`right` / `bottom`	右下角坐标	Python 侧生成 Right/Bottom 边时取 `right - 1` / `bottom - 1`，与 C++ 的 `monitor.rect.right - 1`、`bottom - 1` 完全一致（见 MonitorTopology.cpp）
`width` / `height`	分辨率	绘制与校验用
`dpi`	显示器 DPI	缺省按 `96` 处理
`scaling_percent`	缩放百分比	缺省按 `100.0` 处理
`primary`	是否主显示器	决定橙色高亮边框
`device_name`	如 `DISPLAY1`	缺省按 `DISPLAY{i+1}` 生成，用于标签显示
`captured_at` / `computer_name` / `user_name` / `monitor_count`	元信息	元数据，算法不依赖

注意：monitor_id 字段由加载方按数组下标顺序指定（test_new_algorithm.py 中 monitor_id=i）。布局中显示器的相对摆放位置（是否错位、是否有间隙、坐标正负值）直接决定了后面可视化中的“问题段”，这正是该工具用来复现“显示器没有精确吸附到相邻显示器边缘”这一 CursorWrap 失效根因的手段。

四、可视化画布解读：颜色即诊断信息

画布按虚拟坐标等比缩放到窗口内，所有显示器以矩形绘制。核心视觉元素如下。

4.1 显示器矩形

灰色矩形：单个显示器本体（源码常量 MONITOR_FILL = "#2C3E50"）；
橙色边框：主显示器（PRIMARY_HIGHLIGHT = "#F39C12"）；
标签：标注显示器索引、设备名与分辨率。

4.2 外边缘条（绘制在显示器边界外侧）

工具只对外边缘（不与任何其他显示器相接的边缘）绘制彩色边条；边条代表算法把该条边切分后得到的若干“边缘段”。判定语义见下表（对应 wrap_simulator.py 中的常量定义）：

颜色	含义
黄色	该边缘段有环绕目的地 ✓
红色条纹	无环绕目的地 —— 问题区域 ⚠️（`NO_WRAP_COLOR = "#FF0000"`）

而边条的描边颜色表示边缘类型（与 Python EdgeType 枚举一致，wrap_simulator.py）：

描边颜色	边缘类型
红（`#FF6B6B`）	Left 左边缘
Teal 青（`#4ECDC4`）	Right 右边缘
蓝（`#45B7D1`）	Top 上边缘
绿（`#96CEB4`）	Bottom 下边缘

需要强调：这里的“黄色/红色条纹”表达的是每个分段是否有环绕目标，即旧算法（直接重叠判定）意义下的覆盖情况。绘制逻辑见 _draw_edge_bars() 与 _draw_edge_segment()（见 wrap_simulator.py），分段数据来自 get_edge_segments_with_wrap_info()（旧算法）或 get_edge_segments_with_projection()（新算法），两者以 1 像素为步长采样整条边，在环绕目标发生变化的坐标处分段（见 wrap_simulator.py）。

五、交互功能与操作要点

5.1 悬停边缘段

鼠标悬停在边缘段上时：

状态栏显示该段的环绕目标信息；
画布上画出绿色箭头，指示光标将会环绕到的位置；
目标显示器上出现绿色虚线矩形高亮环绕目的地。

5.2 点击边缘段

点击某个边缘段后，右侧信息面板显示完整分析：

该段是否可环绕、为什么可以/不可以；
问题段给出原因码（详见下文第六节）与描述；
直接给出修复建议（如“将该显示器向下延伸 X 像素”或“移动某个显示器”）。

5.3 环绕模式选择（Wrap Mode）

界面提供三种环绕模式下拉项，与 C++ WrapMode 枚举（MonitorTopology.h）及设置页下拉框一一对应：

模式	生效边缘	语义
Both	全部四条边	全方向环绕（默认）
Vertical Only	仅 Top/Bottom	只做垂直环绕
Horizontal Only	仅 Left/Right	只做水平环绕

模式切换直接影响分段结果：例如在 Vertical Only 下，Left/Right 这两类水平环绕边整条都会被标记为 WRAP_MODE_DISABLED 问题段（见 wrap_simulator.py）。

5.4 导出分析（Export Analysis）

点击 "Export Analysis" 会把当前布局的完整诊断导出为 JSON（详见下文第七节导出结构），用于算法开发、回归比对或共享给上游排查。源码中该按钮对应 _export_analysis()（wrap_simulator.py），它会遍历所有外边缘与问题段，连同 ProblemAnalysis 的原因码、建议与细节一并序列化。

5.5 边缘自动测试（Test Edges）

点击 "🧪 Test Edges" 会启动自动边缘遍历测试：

动画模拟光标沿所有外边缘逐点移动；
每个测试点的环绕结果用彩色图形表达：
- 红色圆圈：位于外边缘上的源位置；
- 绿色圆圈：环绕目的地；
- 绿色虚线：连接源与目标的环绕路径；
- 红色 X：无环绕目的地（问题区域）。
"New Algorithm" 复选框用于在两种算法间切换对比：
- NEW：投影增强算法（消除死区）；
- OLD：仅直接重叠（可能存在死区）；
结束后弹出统计摘要，给出每条边的覆盖率（每边缘覆盖像素 / 边缘总像素），便于量化对比新旧算法在同一布局下的差距。

六、问题分析机制：原因码体系

当某段没有环绕目的地时，工具会自动调用 _analyze_wrap_problem()（见 wrap_simulator.py）进行根因诊断。原因码与枚举定义（ProblemReason，wrap_simulator.py）如下：

原因码	描述	出现条件与修复思路
`WRAP_MODE_DISABLED`	该边缘类型被当前环绕模式禁用	在 Vertical Only 下点水平边，或反之；建议切回 Both 或启用对应方向
`NO_OPPOSITE_OUTER_EDGES`	整条对面类型的外边缘都不存在	例如想从左环绕，但所有右边缘都是“内边缘”（紧邻其他显示器）；分析中会列出这些被相邻显示器占据的内边缘细节
`NO_OVERLAPPING_RANGE`	对面边缘存在，但不覆盖本段的坐标区间	最常见于显示器错位/偏移场景，详见下方诊断细节
`SINGLE_MONITOR`	只有一个显示器	没有第二个显示器可环绕；提示连接更多显示器

NO_OVERLAPPING_RANGE 的专属诊断细节

对于该原因码，工具会输出（见 wrap_simulator.py）：

到最近有效环绕目的地的距离（像素，gap_to_nearest）；
按距离排序的可用对面边缘清单，每条含显示器索引、设备名、边缘坐标、边缘区间、与问题段的距离及相对方位；
间隙方位：该段的上方/下方还是左/右侧没有覆盖；
具体修复建议：例如“把本段所在显示器向下/左延伸 N 像素”，或“把对面显示器向上/右移动”，或“增加一台覆盖该区间的显示器”。

这一分析其实复刻了 C++ 侧 MonitorTopology 的 DetectMonitorGaps()（见 MonitorTopology.h 与 MonitorTopology.cpp 的 GapInfo 实现）所能发现的“显示器未吸附”问题——这也是 CURSOR_WRAP_TESTS.md 中描述的最常见失效根因。

七、导出分析的 JSON 结构

"Export Analysis" 生成的 JSON 遵循以下骨架（摘自 README，字段名与 ProblemAnalysis 数据结构对应）：

{
  "export_timestamp": "2026-02-16T08:50:34+00:00",
  "wrap_mode": "BOTH",
  "monitor_count": 3,
  "monitors": [...],
  "outer_edges": [...],
  "problem_segments": [
    {
      "source": {
        "monitor_index": 0,
        "monitor_name": "DISPLAY1",
        "edge_type": "TOP",
        "edge_position": 200,
        "segment_range": {"start": 0, "end": 200},
        "segment_length_px": 200
      },
      "analysis": {
        "reason_code": "NO_OVERLAPPING_RANGE",
        "description": "No BOTTOM outer edge overlaps...",
        "suggestion": "To fix: Either extend...",
        "details": {
          "gap_to_nearest": 200,
          "available_opposite_edges": [...]
        }
      }
    }
  ],
  "summary": {
    "total_outer_edges": 8,
    "total_problem_segments": 4,
    "total_problem_pixels": 800,
    "problems_by_reason": {"NO_OVERLAPPING_RANGE": 4},
    "has_problems": true
  }
}

顶层 summary 汇总了外边缘总数、问题段数量、问题像素总量、按原因码分类的分布以及是否整体存在问题，方便直接接入自动化回归流程。

八、算法原理：v1 直接重叠 vs v2 投影增强

这是整个模拟器的核心价值所在——用纯 Python 复刻并可视化 C++ 引擎的两种边缘环绕算法。

8.1 前置：外边缘判定（两代算法共用）

一条边被判为“外边缘”需要满足：不存在另一台显示器的对立类型边，且两者同时满足——位置差在 50 像素容差内、垂向/横向区间重叠超过容差。判定函数为 Python 的 _edges_are_adjacent()（wrap_simulator.py，常量 ADJACENCY_TOLERANCE = 50 与 C++ 完全一致），其 C++ 对应实现 EdgesAreAdjacent() 位于 MonitorTopology.cpp。随后 IdentifyOuterEdges()（MonitorTopology.cpp）逐边比对、剔除内边缘，剩余即为外边缘集合。

补充一个容易被忽略的源码细节：所有边在构建时都默认 isOuter = true，只有“被别的显示器的对立边判定为相邻”后才会被标记为内边缘；而模拟器绘图只关心最终保留的外边缘。

8.2 原始算法（v1）——直接重叠

外边缘检测：如上一节所述。
环绕目标选择：光标到达外边缘后：
- 找对立类型的外边缘（Left→Right、Top→Bottom 等），注意 Right/Bottom 边取的是“极值位置”（向左环绕找最靠左的 Left 外边缘，向右则找最靠右的 Right 外边缘，见 find_opposite_outer_edge() 的 find_max 逻辑，wrap_simulator.py）；
- 目的边必须与光标当前位置的垂直/水平坐标区间重叠；
- 光标被传送到该目的边上。
死区：外边缘上凡是“没有一条对立外边缘能重叠覆盖”的区间段，就没有环绕目的地——鼠标撞到这段就会停在边缘上，形成 README 所称的 problem area。

8.3 增强算法（v2）——带投影的环绕

v2 的目标是消除上述死区，做法是在“无直接重叠”时引入坐标投影（核心实现为 find_nearest_opposite_edge() 与 _calculate_projected_position()，见 wrap_simulator.py）：

直接重叠优先：若对立外边缘与光标垂向坐标直接重叠，直接使用（行为与 v1 相同）；
最近边投影：若无直接重叠：
- 按坐标距离找出最近的对立外边缘（等距时仍按“极值位置”方向择优）；
- 用 offset-from-boundary（从边界偏移） 方式计算投影点：若光标位于共享区域之外的上/左端，则 目标端起点 + (光标 - 源边起点)；位于共享区域下/右端则从端尾反向推算（见 _calculate_projected_position() 的边界偏移逻辑），最后把投影坐标 clamp 回目标边区间内；
- 该投影策略刻意模拟 Windows 在多显示器间切换光标时的“保留相对偏移”行为。
零死区：由此，外边缘上每个点都拥有合法的环绕目的地。

从源码结构看，C++ 侧的 FindNearestOppositeEdge、CalculateProjectedPosition 与 OppositeEdgeResult{found, requiresProjection, projectedCoordinate}（[MonitorTopology.h](https://gitcode.com/GitHub_Trending/po/PowerToys/blob/7bf87a308bdfe13313228560e2a3e31683f76172/src/modules/MouseUtils/CursorWrap/MonitorTopology.h?utm_source=gitcode_repo_files#L50-L57, L115-L123)）正是这套 v2 逻辑的生产实现，Python 端口保持了相同的方法划分与返回值语义，因此用模拟器验证出的结论可以直接反哺 C++ 实现。

8.4 覆盖率校验

validate_all_edges_have_destinations()（wrap_simulator.py）会遍历全部外边缘，用新算法切分并累加 covered/uncovered 像素，返回 coverage_percent、is_fully_covered 与遗留 problem_areas。这正是“测试边”功能与新算法开关背后的定量依据。

九、命令行算法对比测试

GUI 之外，仓库还附带了可脚本化的验证器：

python test_new_algorithm.py [layout_file.json]

脚本逻辑见 test_new_algorithm.py：不传参数时默认依次测试 mikehall_monitor_layout.json、sample_layout.json、sample_staggered.json 三个布局文件；传参则可逐一指定布局（注意它同时支持多个文件路径参数）。对每个布局：

读取 JSON，把每个显示器映射成 MonitorInfo，初始化 MonitorTopology；
OLD 算法：对每条外边缘调用 get_edge_segments_with_wrap_info(edge, WrapMode.BOTH)，统计无环绕目标的像素总数并逐段打印问题明细（含边缘类型、[start-end] 区间与像素长度）；
NEW 算法：调用 validate_all_edges_have_destinations(WrapMode.BOTH)，输出总边长、覆盖长度、覆盖率百分比与剩余问题区；
输出对比结论：若旧算法有死区而新算法为 0，则打印 SUCCESS: New algorithm eliminates all dead zones!；否则给出 WARNING 或“两算法均无死区”的提示；
最终汇总全部布局的通过情况并返回退出码（全过为 0）。

该脚本适合把多份布局文件放进 CI 或本地回归：只要新增一份用户反馈的失效布局，就能立刻知道新算法是否已经把该布局的全部死区归零。

十、光标日志回放（Cursor Log Playback）

模拟器还支持把真实记录的鼠标轨迹 CSV 播放出来，观察环绕实际发生的位置。

10.1 加载与播放控制

点击 "Load Log" 选择光标日志文件后，使用播放条控制：

▶ Play / ⏸ Pause：开始 / 暂停播放；
⏹ Stop：停止并回到开头；
⏮ Reset：不停止但重置到开头；
Speed 滑块：调节两帧间隔，10–500ms。

播放核心逻辑位于 _playback_step() 与 _validate_cursor_position()（见 wrap_simulator.py），后者会判断每个采样点落在哪台显示器上、是否发生了显示器切换。

10.2 日志 CSV 格式

列结构固定为 5 列，文件扩展名不限但内容需为逗号分隔：

display_name,x,y,dpi,scaling%

示例：

\\.\DISPLAY1,1234,567,96,100%
\\.\DISPLAY2,2560,720,144,150%
\\.\DISPLAY3,-500,800,96,100%

display_name：Windows 显示器名（如 \\.\DISPLAY1）；
x, y：虚拟屏幕坐标（可为负值，表示位于主屏左/上方）；
dpi：显示器 DPI；
scaling%：缩放百分比，带不带 % 号均可——解析器会先 rstrip('%') 再转浮点（见 CursorLogEntry.from_csv_line()，wrap_simulator.py）。

以 # 开头的行按注释忽略。解析失败（列数不足或数值非法）的行会被跳过。

10.3 播放可视化语义

图形	含义
绿色光标	显示器内部的正常移动
红色光标 + 迸发特效	检测到显示器切换/环绕事件
蓝色拖尾	最近的光标移动路径（随时间淡出）
红色虚线箭头	两台显示器之间的切换/环绕路径

播放时，一旦检测到显示器切换，播放会自动放慢，便于逐帧观察环绕行为。仓库 README 描述的样例日志 sample_cursor_log.csv（三显示器演示轨迹）与本仓库快照中的实际文件清单以当前仓库实际内容为准，若需构造，可依据上述 5 列 CSV 规格自行生成。

十一、Python 架构与 C++ 源码的映射关系

模拟器刻意保持与 C++ 实现同构的类/数据结构划分，方便对照排错（对应 README 的 Architecture 一节，可逐条到 wrap_simulator.py 与 MonitorTopology.h 核对）：

Python 构件	C++ 对应	职责
`MonitorTopology` 类	`struct MonitorTopology`	管理基于边缘的显示器布局、外边缘识别、环绕目标查找
`MonitorInfo` dataclass	`struct MonitorInfo`	显示器几何信息（Python 增加了 dpi/scaling 等模拟所需字段）
`MonitorEdge` dataclass	`struct MonitorEdge`	单条边：monitorIndex、edgeType、start/end、position、isOuter
`EdgeSegment` dataclass	（分析层概念）	一条边上带环绕信息的连续分段，`wraps_to=None` 即问题段
`CursorLogEntry` dataclass	CursorLog 工程	单条光标日志条目（CSV 解析）
`WrapSimulatorApp`	—	Tkinter GUI 应用层，仅存在于 Python 侧
`EdgeType` / `WrapMode` IntEnum	`enum class EdgeType` / `WrapMode`	边缘类型与环绕模式，枚举取值一致（Left=0…Bottom=3；Both=0…HorizontalOnly=2）

值得注意的映射细节：C++ 侧用 (monitor index, EdgeType) 作 m_edgeMap 的 key，并注释说明这是为了规避动态增删显示器导致 HMONITOR 句柄失效的问题（见 MonitorTopology.h）；Python 端口同样用 (idx, EdgeType) 构建 edge_map，保持了这一设计。此外，C++ 用 WRAP_DISTANCE_THRESHOLD = 50（CursorWrapCore.h）防抖、用 CursorDirection 在角落同时命中多条边时按移动方向优先选择边缘（PrioritizeEdgeByDirection，见 MonitorTopology.cpp），这些运行期细节并不影响模拟器对“哪些段能环绕”的静态判定，却解释了为什么真实使用中同一角落在不同移动方向下会有不同表现。

十二、集成到 PowerToys 排查工作流

综合 README、CURSOR_WRAP_TESTS.md 以及本工具的定位，当 CursorWrap 在多显示器下“失灵”时，推荐按如下闭环排查：

采集：运行 Capture-MonitorLayout.ps1，生成形如 "$($env:USERNAME)_monitor_layout.json" 的布局文件；默认匿名化输出，便于脱敏分享；
可视化复现：用 python wrap_simulator.py <布局.json> 打开，直接观察黄色/红色条纹，找出红色死区所在边缘段；
定性分析：点击问题段查看原因码与建议，判断是 NO_OVERLAPPING_RANGE（错位）还是其他原因码；
量化验证：用 monitor_layout_tests.py 生成 test_report.json，必要时配合 --verbose；失败时再用 python analyze_test_results.py --report test_report.json --detailed（或 --copilot 生成修复提示）做汇总分析；
回归预演：把该布局喂给 test_new_algorithm.py，确认投影增强算法对该布局达到 100% 覆盖；若有新死区，用 "Export Analysis" 导出结构化问题清单继续下钻。

同时记住两个关键前提（来自官方测试文档）：单显示器下所有边缘都无相邻显示器，环绕永远生效、无需本工具排查；相邻显示器之间的过渡由 Windows 负责，CursorWrap 只解决“外轮廓边缘”的环绕，因此排查目标应始终锁定最外层轮廓上的红色条纹。若显示器确实未被“吸附”（Windows 显示设置中的拖动对齐），就会在边缘间隙处产生本工具最擅长暴露的 NO_OVERLAPPING_RANGE 死区。