hidpi-mouse

核心用法

HiDPI Mouse Skill 是一套专为 Linux 桌面自动化设计的 Bash 脚本工具集，旨在解决 Claude 等 AI 助手在 HiDPI/Retina 屏幕上显示坐标与实际屏幕坐标不匹配的问题。该技能通过 click.sh、move.sh、drag.sh 等脚本提供完整的鼠标操作封装，自动检测或手动校准屏幕缩放因子（Scale Factor），将 AI 提供的显示坐标转换为 xdotool 可执行的实际屏幕坐标。

用户可通过 ./scripts/calibrate.sh 进行交互式校准，生成针对特定分辨率（1080p 到 4K+）和 DPI 设置（96 到 192+）的精确配置文件。支持单次点击、双击、右键点击、拖拽等多种操作模式，并提供 --raw 参数绕过缩放直接使用原始屏幕坐标。

显著优点

该技能的最大优势在于其通用适配能力。无论是标准 1080p 显示器还是 4K HiDPI 屏幕，无需修改自动化代码即可通过校准实现像素级精准点击。依赖体系极简且安全，仅使用 Linux 系统标配工具（xdotool、scrot、python3、bc），无额外网络依赖或动态代码加载风险。

代码质量规范严谨，所有脚本采用 set -e 错误退出机制，输入参数经过正则验证，无命令注入漏洞。文档极为完善，不仅提供常见屏幕配置的参考缩放因子表（如 3024×1772@192DPI 对应 2.08 倍），还包含详细的故障排查指南和配置重置方案。

潜在缺点与局限性

首要限制是平台依赖性。该技能仅支持 X11 显示协议，完全不兼容现代 Linux 发行版默认采用的 Wayland 会话，这限制了其在 GNOME、KDE 等新版桌面环境中的应用。其次，缩放因子检测基于启发式算法（通过 xdpyinfo、xrandr、xrdb 等工具推断），在复杂多显示器拓扑或动态分辨率切换场景下可能出现检测偏差。

此外，缓存机制相对简单（仅 1 小时 TTL 的 /tmp 文件），在长时间自动化任务中若用户更改显示设置，可能导致缓存 stale 数据引发点击偏移。作为 T3 来源的社区项目，长期维护和更新频率也存在不确定性。

适合的目标群体

该技能特别适合Linux 桌面自动化开发者和RPA（机器人流程自动化）测试人员，尤其是使用 Claude Desktop 等 AI 助手进行视觉驱动自动化工作流的技术用户。对于拥有 HiDPI/Retina 屏幕（MacBook Pro 外接显示器、4K 笔记本等）的开发者，该工具能有效解决 AI 视觉理解与本地自动化执行之间的坐标映射鸿沟。

同时适用于需要在多分辨率环境下部署自动化脚本的 DevOps 工程师，以及进行 GUI 测试的 QA 工程师。不适合普通终端用户或 Wayland 环境用户。

使用风险与注意事项

环境风险：必须确保 DISPLAY 和 XAUTHORITY 环境变量正确设置，否则 xdotool 将无法连接 X11 服务器。在 SSH 远程执行或 systemd 服务中运行时需特别注意权限上下文。

精度风险：未校准的自动检测可能存在 5-10% 的误差，在高密度界面元素（如小型按钮、菜单项）操作中可能导致误点击。建议在关键自动化流程前始终执行 calibrate.sh test 验证当前配置。

依赖风险：虽依赖工具均为标准组件，但不同发行版（如 Alpine、NixOS）可能存在路径差异或工具缺失。scrot 截图工具在某些最小化安装环境中可能需要手动安装。

安全建议：尽管代码本身无恶意行为，但自动化鼠标操作具有潜在破坏性（如误点删除按钮）。建议在调试阶段使用 move.sh 先观察目标位置，确认后再执行实际点击操作。