权限与故障排查

检查实际启动应用的权限

截图需要"屏幕录制"权限，指针和键盘事件需要"辅助功能"权限。去系统设置里检查的时候，注意看的是实际启动二进制文件的那个应用。从终端切换到 IDE 或其他启动器时，权限上下文可能改变。改完权限后可能需要重启那个应用才能生效。

构建与启动

• cargo: command not found — 安装或选择 Rust 工具链，用 rustc --version 和 cargo --version 确认。
• 编译器、SDK 或 Swift 链接错误 — 检查 xcode-select -p 和 Apple 构建工具。源码链接了 macOS 和 Swift 框架，不能当作 Linux 程序来构建。
• nano-use: command not found — 在仓库根目录用 ./target/release/nano-use --help，或者按"快速开始"设置 PATH。
• unexpected argument '--version' — 这个版本没有 version 参数，用 git rev-parse HEAD 来确认检出版本。

截图与解码

成功的 screenshot 会向 stdout 写入一行 base64 PNG 加一个换行。记得把 stdout 和 stderr 分开处理。按照快速开始里的步骤解码——文件后缀是 .png 不代表内容就是 PNG。

如果 stderr 显示 未检测到活动显示器，说明需要在已登录的图形会话中运行，并检查启动器是否有显示器访问权限。受限或无界面的进程可能根本看不到显示器。即使文件存在，如果截图是空白、黑屏或不完整的，还是要检查权限和会话状态。不同应用的受保护内容和不同系统版本可能影响截图结果。

输入与参数

• unexpected argument '-480' — 加 -- 来终止选项解析：nano-use scroll -- 320 240 -480。负坐标和以连字符开头的文本也一样。
• type 命令不接受空字符串 — 传入非空的文本参数。
• 无法解析按键组合 — 用一个主键加可选修饰键，比如 shift+a。单独的 cmd 或 a+b 都不行。
• 未知按键 — 用受支持的键名。keypress 不是用来输入任意 Unicode 文本的，文本请用 type。
• 退出码为 0 但界面没变化 — 在临时文档里检查"辅助功能"权限和窗口焦点，再用新截图验证。没有可见变化不等于事件成功送达了。

解析错误的退出码是 2，这个版本处理的运行时错误写入 stderr 并以 1 退出。其他终止状态可能来自操作系统或启动器本身。

坐标与多显示器

程序用一个包住所有活动显示器的轴对齐外接矩形来校验坐标，显示器之间的空隙也能通过。显示器原点可以是负数。缩放显示器上截图的像素尺寸和桌面坐标单位可能不同——不要直接拿图片像素坐标当点击坐标用。改变显示排列或缩放设置后，记得重新截图观察。