AltTab macOS 人工按键重复定时器KeyRepeatTimer的时序守卫设计可见性锚点与迟到判定规则解析【免费下载链接】alt-tab-macosWindows alt-tab on macOS项目地址: https://gitcode.com/gh_mirrors/al/alt-tab-macos导读AltTabalt-tab-macos在纯修饰键快捷键如按住 ⌥ 再连按 ⇥下系统不会产生 OS 级按键重复因此必须在应用内合成一套“人工按键重复”定时器让按住快捷键时选择框持续循环推进。本篇文章以KeyRepeatTimerSpecs.md为骨架结合 KeyRepeatTimer.swift、KeyRepeatTimerTestable.swift 与 KeyRepeatTimerTests.swift 的源码与测试完整讲解这套定时器的三大核心难题与解法初始延迟宽限期从“面板真正可见”起算、双锚点可见时间戳/显示时间戳的选取逻辑、以及“迟到 tick 一律拒绝”的单发重武装机制。读完本文你将掌握这套决策内核的完整判定规则、边界常数1s 兜底预算、20ms 下限及其背后的实测 bug 根因。一、为什么需要人工按键重复1.1 系统不重复应用来合成普通带 keycode 的快捷键如 ⌘⇥由系统直接产生 auto-repeat 的 keyDown 事件无需额外处理。但纯修饰键组合例如 ⌥⇥其中 ⇥ 在 ⌥ 被按住时没有独立 keycode不会触发 OS 级重复。因此 AltTab 需要自己合成重复每次按住快捷键时用一个后台定时器按用户设置的KeyRepeat速率周期性地推进选择框。1.2 触发与停止的调用链定时器的启停由两个入口控制启动KeyRepeatTimer.startRepeatingKeyPreviousWindow()/startRepeatingKeyNextWindow()在 App.swift、App.swift 处被调用分别对应“上一个窗口”与“下一个窗口”两条人工重复链路停止KeyRepeatTimer.stopTimerForRepeatingKey(_:)在 ATShortcut.swift快捷键状态转为up时和 TilesView.swift切换器关闭时被调用。启动时有两条前置约束源码见 KeyRepeatTimer.swift仅对无 keycode 的快捷键生效previousWindowShortcut要求shortcut.keyCode .noneEsc 键被排除Esc 通过 cghid 事件通道#5585送达会产生真实 OS 重复若再叠加人工定时器被吸收的 keyDown 会让 Carbon 收不到配套的释放事件定时器永不停止选择框会一路循环到列表末尾#5742。定时器使用DispatchSource.makeTimerSource(queue: BackgroundWork.repeatingKeyQueue.strongUnderlyingQueue)跑在 BackgroundWork.swift 中定义的专用 OperationQueuerepeatingKey并发度为 1上与主线程隔离。二、初始延迟宽限期的意义2.1 速率参数的来源每次武装arm定时器时AltTab 会读取 macOS 全局默认值let repeatRate ticksToSeconds(CachedUserDefaults.globalString(KeyRepeat) ?? 6) let initialDelay ticksToSeconds(CachedUserDefaults.globalString(InitialKeyRepeat) ?? 25)其中ticksToSeconds将系统的“tick”数换算为秒Apple 硬编码60 ticks 1 秒且在高刷新率显示器如 120 FPS上依旧如此KeyRepeatTimer.swift。也就是说macOS 默认的InitialKeyRepeat25 ticks ≈ 417ms与KeyRepeat6 ticks ≈ 100ms会被换算为秒级时间戳参与判定。2.2 为什么宽限期必须从“可见”起算第一次武装定时器后首个 tick 计划在armedAt initialDelay触发。但问题在于如果用户在全屏/Space 切换后立即唤起切换器WindowServer 正忙于收尾切换动画无法立刻绘制 AltTab 的.canJoinAllSpaces面板——面板像素可能要到定时器武装后约 500ms 才真正上屏。此时后台DispatchSource仍在持续 tick队列中积压的 tick 会在面板出现的瞬间全部触发选择框在用户毫无输入的情况下一次跳过多格。因此正确的语义是初始延迟宽限期必须从“面板真正被用户看到”的时刻起算而不是从定时器武装时刻起算。普通快速唤起不受影响面板通常在武装后几十毫秒内可见。三、丢失的锚点一次 1.4 秒的实测回归3.1 可见信号为何永远收不到最初方案只锚定SwitcherSession.panelBecameVisibleAt即面板自身 WindowServerorderedIn事件。但实测2026-07-30发现该通知从不到达ordered-in 只对WindowServerEvents.wsWindows逐窗口选择加入opt-in集合中的 wid 投递而面板并不在该集合中自 Sequoia 起为强制要求。于是每个 tick 都落入兜底分支按住循环实际上从armedAt initialDelay 1s才开始——实测首跳1377ms而系统InitialKeyRepeat仅417ms每一次按住都受影响。日志佐证Carbon 热键每次按下只触发一次、忽略 auto-repeat keyDown14 次自动重复 keyDown 只产生了恰好一次state:down证明人工重复是按住期间推进选择的唯一途径。3.2 为什么不把面板加入 opt-in 集合直观的修复是把面板加进wsWindows但源码明确拒绝了这个方案SwitcherSession.swift那会把面板自身的 order/geometry 事件作为“未跟踪 wid 的输入”喂进 reducer对一个“时序细节”而言风险过大。3.3 解决方案不可能丢失的panelShownAt替代锚点由 TilesPanel.swift 的show()提供在makeKeyAndOrderFront(nil)后立即写入session.panelShownAt ProcessInfo.processInfo.systemUptime每次召唤只写一次避免同一次会话内重新显示时在用户手指下重启宽限期。该锚点不可能丢失但略微偏早——orderFront返回后 WindowServer 才真正绘制。因此可见信号panelBecameVisibleAt依然保留作为“校正层”高于显示时间戳而非被替换两者同时存在时以更晚、更真实的可见时间为准测试testTheWindowServerSignalOverridesTheShowAnchor验证。代价也在源码注释中明确陈述在真正缓慢的显示场景下宽限期从 order-front 而非 paint 起算可能让一次提前推进落地——这是“不让每次普通召唤都晚 1 秒”换来的取舍。四、显示之后的卡顿#59774.1 症状与根因可见性锚点只能覆盖“面板呈现之前”的卡顿呈现之后若发生卡顿破坏力相同而锚点看不见它。实测复现闲置 5–10 分钟后第一次 alt-tab选择框落在列表约第 8 格而非上一个窗口——这个数量由流逝时间与重复速率决定与窗口集合无关。两个设计共同制造了积压定时器按重复周期调度在自有后台队列上循环触发。主线程繁忙时每个错过的间隔都堆积一个排队 block停止定时器的 key-up 是事件源run loop 会先排空整个主 dispatch 队列、再读取下一个事件。因此积压的 tick 总是先于取消它的释放事件被执行且每个 block 重新检查now此时宽限期早已满足。4.2 两项修复单发 处理完毕后自重新武装scheduleTick每次只排一个 deadlinehandleEvent在主线程处理完当前 tick 后才调用scheduleNextTick重新调度下一发KeyRepeatTimer.swift。任何时刻最多只有一个 tick 在途卡顿只会推迟下一个 tick 而不是堆积更多。代价是间隔变为“handler 到 handler”而非“fire 到 fire”每个周期漂移一个处理周期亚毫秒级相对 33–500ms 的KeyRepeat可忽略。迟到即拒绝tick 到达主线程太晚时直接丢弃——一个等待过的 tick 不足以证明按键仍然按住详见第五节。此 bug 在 v11.4.4 之前一直被掩盖完全没有锚点时每个 tick 都走initialDelay 1s兜底反而吞掉了短于约 1.4s 的积压。五、决策内核完整判定规则5.1 纯函数内核判定逻辑被抽取为KeyRepeatTimerTestable.shouldApplyArtificialRepeat(now:firedAt:armedAt:panelBecameVisibleAt:panelShownAt:initialDelay:repeatRate:)KeyRepeatTimerTestable.swift所有输入都是systemUptime时间戳无定时器、无 DispatchSource、无 AppKit 依赖因此可以纯单元测试。核心实现仅四行if now - firedAt lateBudget(repeatRate) { return false } if let anchor panelBecameVisibleAt ?? panelShownAt { return now - anchor initialDelay } return now - armedAt initialDelay missedVisibleSignalBudget5.2 三条规则详解规则条件结果1. 迟到判定now - firedAt max(repeatRate, 20ms)拒绝无论锚点如何2. 锚点宽限期锚点已知panelBecameVisibleAt ?? panelShownAt当且仅当now - anchor initialDelay时应用WindowServer 可见时间戳优先3. 兜底两者均未知等到armedAt initialDelay 1s后照常应用关键边界说明missedVisibleSignalBudget 1秒KeyRepeatTimerTestable.swift保证可见信号缺失时按住循环不会永久卡死。它从“所有 tick 的必经路径”变成了“真正的安全网”。迟到预算下限 20msminimumLateBudget同文件第 13 行因为defaults write -g KeyRepeat 0是合法配置系统视作“重复间无延迟”。若预算允许为零规则 1 会拒绝每一个 tick把按住循环彻底锁死。边界取可见时间恰好等于initialDelay前时即应用测试testAppliesExactlyAtInitialDelayBoundary验证。实际调用时firedAt在定时器 handler 触发瞬间捕获now在跳转到主线程之后捕获KeyRepeatTimer.swift两者之差即“主线程排队延迟”。六、测试场景全景与KeyRepeatTimerTests.swift一一对应KeyRepeatTimerSpecs.md的测试场景小节与 KeyRepeatTimerTests.swift 逐条对应以下按分组整理测试固定initialDelay0.4s、repeatRate0.1s用now与各时间戳的相对位置构造场景6.1 A2 组显示时刻锚点testAppliesFromTheShowAnchorWhenNoWindowServerSignalArrives——1.4s bug 的回归测试无 WindowServer 信号时宽限期从panelShownAt起算而非arm 1stestTheWindowServerSignalOverridesTheShowAnchor——两者同时已知时可见信号优先panelBecameVisibleAt: 99.9晚于panelShownAt: 99.1拒绝应用缓慢显示不能提前开启宽限期。6.2 A 组可见时间戳已知——从可见性门控testAppliesOnceVisibleForInitialDelay——可见 0.5s 前、延迟 0.4s → 应用testSkipsWhenNotVisibleLongEnough——可见 0.1s 前、延迟 0.4s → 跳过核心修复慢显示已呈现面板但自可见以来的宽限期未满testAppliesExactlyAtInitialDelayBoundary——可见恰好initialDelay前 → 应用边界。6.3 B 组可见时间戳未知——arm 相对兜底testSkipsBeforeFallbackBudgetWhenNeverVisible——从未可见、武装 0.5s 前、延迟 0.4s → 跳过排队爆发场景面板未上屏时抑制应于~arminitialDelay到期的重复兜底仅在initialDelay 1s后打开testAppliesAfterFallbackBudgetWhenNeverVisible——从未可见、武装 1.5s 前、延迟 0.4s → 应用 0.4 1可见信号缺失不会永久卡死按住循环。6.4 C 组tick 迟到主线程testSkipsATickThatWaitedLongerThanOneRepeatInterval——#5977 回归fired 0.6s 前才执行 → 拒绝testAppliesATickThatReachedMainPromptly——普通的微秒级主线程跳转仍然正常循环testTheLateBudgetIsOneRepeatInterval——较慢的KeyRepeat容忍成比例的更长等待同一firedAt差值下repeatRate0.1拒绝、0.5应用testAZeroRepeatRateStillAppliesPromptTicks——KeyRepeat 0下 20ms 下限仍让及时 tick 应用而明显迟到者0.1s依然被拒。七、从源码看设计启示时序问题用“单一时钟 相对差”建模所有判定统一使用ProcessInfo.processInfo.systemUptime时间戳的差值避免混用绝对时间与不同时钟源。纯决策与副作用彻底分离判定规则放在KeyRepeatTimerTestable纯枚举中定时器与 AppKit 副作用留在KeyRepeatTimer使 10 个时序边界场景能被无定时器地快速单测。“锚点可能缺失”要当成一等公民panelBecameVisibleAt理论精确却实际永远收不到panelShownAt必然存在却略早——用“精确者优先、可靠者兜底”的双锚点 1s 安全网覆盖全部路径而不是赌某个信号一定会到。积压永远优先于取消事件的 run loop 语义是 #5977 的底层原因解决方式不是“更快处理”而是让定时器从“重复周期”变为“单发自再武装”从结构上消除多 tick 在途的可能。八、延伸阅读决策内核与规则注释KeyRepeatTimerTestable.swift定时器武装、handler 与再调度实现KeyRepeatTimer.swift全部时序边界测试KeyRepeatTimerTests.swift会话级锚点字段语义SwitcherSession.swiftpanelShownAt的写入点TilesPanel.swiftpanelBecameVisibleAt的当前不触发的写入逻辑WindowServerEvents.swift定时器专用后台队列BackgroundWork.swift【免费下载链接】alt-tab-macosWindows alt-tab on macOS项目地址: https://gitcode.com/gh_mirrors/al/alt-tab-macos创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考