桌面图标位置锁定工具 (DesktopIconLock)

专为 Windows 10 / 11 打造的轻量原生桌面图标位置锁定与跨分辨率自适应工具。 核心特性：真实图标原生坐标读写、零遮罩、分辨率/DPI严格配置、结构保持型自适应换算、托盘开机启动、全链路白话审计日志落盘。

---

1. 核心技术原理与优势

1. 零遮罩/原生交互（满足 R4）：

   • 本程序直接操作 Windows 桌面底层 SysListView32 容器及 IFolderView2 COM 接口，按真实像素坐标读写。
   • 不创建任何可见窗口、透明叠加层或模拟图标，完全保留原生 Windows 桌面的右键菜单、拖拽、框选与毛玻璃特效。

2. 结构保持型自适应换算（满足 R2）：

   • 启动时启用 Per-Monitor-V2 DPI 感知，始终使用物理分辨率和真实 DPI，避免 125% 下把 1920x1080 错认成 1536x864。
   • 基准 Profile 会保存物理工作区、网格原点、水平/垂直步进和图标拓扑。
   • 切换分辨率或缩放后，先映射行列结构，再在同一目标行内寻找最近空位；同一行放不下时才换行，防止图标重叠、越界或跨区域乱跳。
   • 写入时临时关闭“与网格对齐”，多轮收敛后回读验证，再恢复用户偏好，避免后写入图标把先写入图标顶走。

3. 分辨率级精确锁定（满足 R3）：

   • 用户可在 1080P、2K、4K、远程桌面（RDP）等常用分辨率下，分别单独保存该分辨率的专属精确布局。
   • 精确配置必须同时匹配 显示器指纹 + 物理分辨率 + DPI；禁止把 125% 的精确坐标误套到 100%/150%。

4. 事件驱动与稳定期处理：

   • 采用系统原生消息监听机制（WM_DISPLAYCHANGE / WM_DEVICECHANGE）及桌面句柄独占钩子（SetWinEventHook），无高频轮询。
   • 显示设置变化后使用 1.2 秒主防抖和 3.2 秒二次稳定校验，避免在 Windows 中间态过早写入。

5. 全链路白话审计日志（遵循 vibe-audit-logger 3.0）：

   • 包含请求到达、参数校验、规则决策、步骤计算、存储读写、状态流转、响应返回与异常拦截全流程日志，统一由 traceId 串联并持久化保存至 logs/ 目录。

---

2. 项目目录结构

DesktopIconLock/
├── build.ps1                   // 一键构建脚本（自动定位csc，编译到dist/）
├── dist/                       // 交付程序与成品输出目录
│   ├── DesktopIconLock.exe     // 可执行主程序 (可直接常驻运行)
│   └── TestRunner.exe          // 全场景自动化测试套件
├── README.md                   // 本使用与开发说明文档
├── dist/                       // 绿色便携交付目录（程序、配置、历史与日志全部自包含在此目录）
│   ├── DesktopIconLock.exe     // 可执行主程序 (双击常驻运行)
│   ├── TestRunner.exe          // 全场景自动化测试套件
│   ├── layout.json             // 便携布局配置文件
│   ├── logs/                   // 便携审计日志目录 (audit-dev-YYYY-MM-DD.log)
│   └── history/                // 便携历史布局与截图目录
│       ├── records/            // 历史 Profile (*.history.json)
│       ├── screenshots/        // 历史全桌面截图 (*.png)
│       └── base-record.txt     // 当前历史基准标记
├── DesktopIconLock/
│   ├── Program.cs              // 应用程序主入口，单实例互斥锁与异常拦截
│   ├── Common/
│   │   └── AuditLogger.cs      // Vibe Audit Logger 3.0 白话审计日志落盘组件
│   ├── Native/
│   │   ├── User32.cs           // Win32 API / ListView 消息与句柄查找
│   │   ├── ShellInterop.cs     // IFolderView2, IShellWindows 等 COM 互操作
│   │   └── DisplayInfo.cs      // 屏幕分辨率、DPI、工作区与显示器指纹
│   ├── Core/
│   │   ├── IconAccessor.cs     // 图标坐标与文本真实跨进程读写层 (Win32/COM)
│   │   ├── LayoutStore.cs      // 配置文件读写与多Profile匹配
│   │   ├── AdaptiveMapper.cs   // 网格拓扑、区域结构、冲突消解与越界保护引擎
│   │   ├── HistoryStore.cs     // 历史布局、截图、基准标记与每模式5条轮转
│   │   ├── ScreenCaptureService.cs // 最小化窗口后捕获完整桌面截图
│   │   ├── StartupManager.cs   // HKCU Run 开机启动注册与状态校验
│   │   └── LockController.cs   // 两阶段防抖、稳定校验与 Explorer 监控
│   ├── Tray/
│   │   ├── TrayContext.cs      // 托盘菜单、历史列表和用户操作
│   │   └── HistoryPreviewForm.cs // 历史截图悬浮预览和操作按钮
│   └── Config/
│       └── layout.schema.json  // JSON 配置文件规范定义
└── Tests/
    └── TestRunner.cs           // 自动化测试用例源码 (覆盖设计文档第7节)

---

3. 快速上手与操作指南

3.1 首次运行关键设置

1. 在桌面空白处点击 鼠标右键 ->【查看】；
2. 确保取消勾选【自动排列图标】（若开启，Windows 系统会在每次刷新时强制打乱用户自定坐标）；
3. 双击运行 dist\DesktopIconLock.exe（或在根目录执行 .\build.ps1 -RunAfterBuild），程序将自动在任务栏右下角生成托盘图标（显示绿色小锁）。

3.2 一键编译构建

在根目录下使用 PowerShell 运行：

.\build.ps1                 # 编译成品输出到 dist/
.\build.ps1 -RunTests       # 编译并运行自动化测试套件
.\build.ps1 -RunAfterBuild  # 编译并直接启动后台托盘服务

3.2 托盘右键菜单功能

• 图标位置已锁定（点击解锁）：切换锁定/解锁保护模式。
• 保存当前布局：保存当前显示模式的精确坐标，并生成完整桌面截图历史记录。
• 历史布局管理：列出所有历史记录；悬停自动预览截图，点击后显示“删除、取消、基准、应用”按钮。
• 使用说明：查看操作说明。
• 日志目录：打开 logs/ 日志目录。
• 开机启动：注册或删除当前用户启动项，无需管理员权限。
• 退出程序：安全退出常驻托盘服务。

历史菜单行格式：

xxxx年xx月xx日xx时xx分xx秒 分辨率xxxx x xxxx 缩放 xxx% 序号x

同一分辨率和缩放组合最多保留5条记录；不同分辨率和缩放组合分别计算，不限制组合数量。自动轮转不会删除已经设置为基准的记录。

便携数据目录（位于程序同级目录）：

dist\layout.json
dist\logs\
dist\history\records\
dist\history\screenshots\

---

4. 自动化测试验收报告

运行 .\TestRunner.exe 可执行全场景验证，实测验收结果如下：

编号	测试场景	验收指标	测试结果
TC1	基础锁定与坐标读写	准确获取桌面 SysListView32 真实图标项与像素坐标	✅ 通过 (已识别桌面全部真实图标)
TC2	布局持久化与备份机制	支持保存/读取 JSON 配置，自动生成时间戳备份并保留最近 5 份	✅ 通过
TC3	分辨率与DPI自适应	结构保持映射、同一行优先消冲突、无重叠、无越界	✅ 通过
TC4	分辨率精确配置优先级	精确 Profile (R3) 绝对优先于自适应等比换算 (R2)	✅ 通过
TC5	配置隔离与回归	自动化测试使用独立临时配置，不污染用户真实布局	✅ 通过
TC6	审计日志规范	全流程 TraceID 串联，白话解释，统一写入 logs/ 目录落盘	✅ 通过
TC7	历史布局轮转	同一分辨率和缩放最多5条，基准记录不会被自动删除	✅ 通过
TC8	历史截图与操作	截图、基准标记、删除和Profile持久化	✅ 通过

---

5. 常见问题排查 (FAQ)

1. 图标移动后没有自动弹回？

   • 请检查托盘图标是否处于“解锁”状态（黄色开锁图标）。双击托盘图标即可切换为“已锁定”。
   • 请确保已点击过“保存当前布局”，或在“历史布局管理”中应用过一条记录。

2. 桌面使用了第三方美化软件（如 Stardock Fences、Rainmeter）？

   • 第三方桌面整理软件若接管了桌面容器，可能会隐藏或替换系统的 SysListView32。建议在原版 Windows 桌面环境中使用本工具以获得最佳原生兼容性。

3. 如何开机自启？

   • 右键托盘图标，勾选 “开机启动”。程序会写入当前用户启动项，无需管理员权限。

4. 在哪里查看本次实际截图验收？

   • 查看 TEST_REPORT.md。
   • 截图总览：artifacts/adaptive-tests/adaptive-test-contact-sheet.png。