截图 bug 误诊两次:原生失败被报成没权限

6 阅读5分钟

截图 bug 误诊两次:原生失败被报成没权限

结论:为了让旧开发包编得过而换的一个接口,让 XDR 屏上缩小的截图全坏了 6 天,失败还都报成没给权限。v0.14.2 换回原接口,构建在开发包低于 14 时直接失败。

Andee 是一个住在 Android 手机里的 agent,靠无障碍服务读屏幕、自己点,不需要哪个 App 给他开接口;Mac 版是同一个他在第二副身体上,看屏幕靠系统截一张图。

一、症状不是「全坏」,是「缩了就坏」

这台机器是 3024×1964 的 XDR 屏。失败的样子很挑:

调用取图尺寸结果
take_screenshot长边 1600每次失败
get_screen_element(with_shot=true)长边 1600每次失败
zoom_screen_region原生 3024×1964一直正常

zoom_screen_region 之所以活着,只因为它传 maxSide=0,走原生尺寸,凑巧是偶数。这个「一半能用」把诊断带偏了两次:人看到一半功能正常,很难相信是接口整体坏了,更容易接受「某个参数不对」。

二、误诊一:把 false 当成「没授权」

MacScreen.capture() 拿到的是原生层的一个布尔值。false 一到 Kotlin,被统一翻成权限文案,后面还跟着「把 Andee 从列表里删掉再加一遍」的步骤。

这段文案本身是对的。macOS 把屏幕录制授权绑在具体构建上,每次更新在系统眼里都是新 App,删掉重加在别的场景里确实能修。也正因为它对,这次错得毫无阻力。

真正的错误丢在 AndeeMac.swift 的 catch 里:FileHandle.standardError.write(...)。GUI 启动的 App 没有可见 stderr,那串 NSError 写完就没了。所以整条链上是这样的:

SCScreenshotManager/SCStream 抛错
  → stderr(GUI 进程里等于扔掉)
  → 原生返回 0
  → Kotlin 抛 SCREEN_RECORDING_NOTE
  → 用户去系统设置,权限本来就已经给了

修法有两半,只有一半是这次对的:错误文案换成 CAPTURE_FAILED_NOTE,明说这不是权限问题;同时把真正的 NSError 追加到 ~/Library/Application Support/Andee/screenshot_error.log。

val CAPTURE_FAILED_NOTE: String get() =
    "Screen capture failed inside ScreenCaptureKit (this is not a permission problem). " +
        "See ~/Library/Application Support/Andee/screenshot_error.log for the underlying error."

那个日志文件是后面能翻案的唯一原因。没有它,第二次误诊我连看都看不见。

顺带说一个容易忽略的点:Kotlin 侧每一处调用在截图前都已经问过「权限给了吗」,所以那句话末尾的 false,本来就不可能是权限造成的。文案和调用顺序互相矛盾,而矛盾的那个位置,正好是唯一能看见错误的地方。

三、误诊二:1039 是个奇数

1600 长边按比例下来,高度是 1039。而 ScreenCaptureKit 的流配置拒收奇数尺寸。这条推理看着是天衣无缝的:奇数被拒 → 缩小失败 → 原尺寸正常。

于是输出宽高被强制成偶数,max(2, Int(w) & ~1),打成 v0.14.1 发出去。

一小时后自己塌了:1280×827 也是奇数,在这台机器上一直能截。奇数是真的,因果关系是假的。

这也是最值得记下来的一条:一个能被观察到的事实,和一个能解释它的原因,是两件事。 1039 确实是奇数,我把它当成了原因,就再也不会去看别的地方。

四、真正的分界点是 11 月 5 日

aec109f(11-05 13:42)在给 Mac 做桌宠时,把截图接口从 SCScreenshotManager.captureImage 换成了一段单帧 SCStream。动机纯粹是构建:SCScreenshotManager 是 macOS 14 才有的,那台机器的开发包是 13。

换完之后,XDR 屏上缩小的截图开始全挂,原尺寸的照旧能用。SCStream 内部到底为什么挂,没查出来,到现在也没有。

v0.14.2 因此不做任何新推理,只做三件事:

  1. 截图回到 SCScreenshotManager.captureImage,也就是 11-05 之前那条能用的路。
  2. 偶数取整和它的理论一起删掉。
  3. buildBridge 遇到低于 14 的开发包直接 throw,不再自己造第二条截图路径:
def sdk = ['xcrun', '--show-sdk-version'].execute().text.trim()
def major = (sdk =~ /^(\d+)/) ? (sdk =~ /^(\d+)/)[0][1] as int : 0
if (major < 14) throw new GradleException(
    "The Mac bridge needs the macOS 14 SDK or newer (found: ${sdk ?: 'none'}).")

第三条是关键。同一个版本号的两个包,如果截图方式不一样,那么用户报的 bug 我复现不出来,我自己报的结论也不作数。

五、代价

Mac 版现在必须用 macOS 14 以上的开发包构建。不需要装 Xcode 本体,但链接器也从 Xcode 里来,所以只装命令行工具的老环境会直接编不出来。这是故意的。

v0.14.1 那两个提交,本地一个字节都没编译过:Command Line Tools 15.2 在 -parse 阶段就报 SwiftBridging 重复定义,而修 bug 的那半边恰好是 Swift。修 bug 的代码在未编译状态下发了版,这件事写进了提交说明和发布说明,这里也照写。

还有一个已经删掉的代价:v0.14.1 为了让「偶数」理论成立,一度让每次截图都按原生尺寸抓、再在 Java 里缩。一次点击之后每 150 毫秒轮询的 480 像素探针,于是变成一张 3024×1964 的图编解码一遍。慢得不明显,但一直在烧。

流程上也付了一次:v0.14.1 到 v0.14.2 相隔 1 小时 53 分,两个版本在同一天打,Android 包跟着重打两次,版本号从 28 走到 29。用户那边看到的是两次更新,和一份开头就承认上一版结论有误的发布说明。

现在的行为是:截图前先问一次权限,给了就不再提权限,失败只写真正的错误。日志路径固定,用户能自己打开看。