装完 Tinycast 后 10 分钟该做什么：首启引导全流程实录

装完 Tinycast 后 10 分钟该做什么首启引导全流程实录【免费下载链接】tinycastTinycast — a tiny, fully native macOS launcher, hotkeys, and clipboard history.项目地址: https://gitcode.com/GitHub_Trending/ti/tinycastTinycast 是一款完全原生、零第三方依赖的 macOS 启动器常驻内存低于 100MB剪贴板历史、窗口管理、内联计算器、原生运行 Raycast 扩展等能力全部构建在 AppKit / SwiftUI / 系统框架之上。对于第一次安装它的用户最关键的体验其实不是功能有多全而是安装完成后的那几分钟——一个没有绑定任何全局快捷键的启动器在系统里等于不存在。本文基于仓库源码把首次启动引导Onboarding从「用户看到的三个界面」拆到「AppCore 的启动时序、事件循环、权限轮询与加密解密链路」梳理出一条完整的 10 分钟上手路径全局快捷键是怎么录进去的、为什么双击修饰键能成为一种绑定、辅助功能权限为什么需要实时轮询、Raycast 数据迁移背后是一整套怎样的加密协议。引导不是页面是一段启动时序首启引导由 AppCore.start() 在全部子系统初始化之后接管。值得注意的一点引导的「是否已展示」标记不是写入 UserDefaults而是以文件形式存放在 Application Support 目录下的onboarded文件——源码注释明确写道cfprefsd会复活一个已删除的 default文件则不会。更精细的设计在于 OnboardingState.markShown() 是在展示引导的同时写入标记而不是等用户走完流程才写// First launch binds no hotkey, so guide once; the marker is written at show-time. if !OnboardingState.hasOnboarded { OnboardingState.markShown() onboardingCoordinator.showOnboarding() }也就是说即使你在中途直接杀掉进程下次启动也不会再看到引导——防重复触发机制在最底层就生效了。引导窗口本身由 OnboardingCoordinator 管理它复用了应用的AppWindowController并在每一步通过onGeometryChange实时测量内容高度让窗口「fit」到当前步骤的真实尺寸避免裁切或留白。流程走完后finishOnboarding()关闭引导窗口并直接打开启动器面板——从「配置」无缝切换到「使用」。整个引导是一个 0 到 3 的四步状态机欢迎 / 辅助功能 / Raycast 迁移 / 完成底部有点位指示、Back 和 Skip每一屏都有独立的主行动按钮文案与禁用逻辑这些都在 OnboardingView.swift 中实现。全局快捷键从组合键到双击修饰键第一步的核心是 ShortcutRecorder。这里最容易忽略的细节是它并不只支持⌘Space这类组合键而是完整支持单按 / 双击某个修饰键Command、Option、Control、Shift甚至 Globe/fn 键还会区分左右侧。这在 HotKeyBinding 里被建模为五种绑定形态.combo(KeyShortcut)、.doubleTap(DoubleTapModifier)、.modifier(ModifierKey)、.doubleModifier(ModifierKey)、.globe/.doubleGlobe。双击识别的时序参数在 DoubleTapDetector.swift 中定义得清清楚楚单次按压最长 0.25 秒超过即视为长按而非点击两次点击的间隔最长 0.30 秒。录制时按下一次修饰键后ShortcutCaptureSession 会等待ModifierKeyDetector.resolutionWindow约 0.57 秒来确认你是要第二次按下还是就单键绑定这就是「录完松开后要稍等一下」的机制来源。左右侧识别则依赖设备掩码ModifierKey为每个物理键定义了独立的deviceMask左 Control0x0001、右 Control0x2000等即使 macOS 在通用 modifier 位上只报告一个共享的位也能还原出具体的左右身份。绑定后recorder 会在键帽内以小号 L/R 前缀提示侧别。冲突检测是拒绝而非覆盖录键过程中发生冲突时行为是明确拒绝并高亮提示而不是静默覆盖。ShortcutCaptureSession.commit()会先调用HotKeyManager.conflictOwner(of:excluding:)在全部候选动作中寻找持有冲突绑定的一方一旦命中就进入flashConflict以 1.5 秒的停留时间显示「这个组合键已属于谁」。冲突判定逻辑在HotKeyBinding.conflicts(with:)中绑定完全相等必冲突共享同一个修饰键的 modifier 类绑定互斥双击与双修饰键、Globe 与修饰键、双 Globe 与双修饰键之间都有明确的交叉规则。录制期间两个事件引擎Carbon 的RegisterEventHotKey与修饰键的 event tap都会被isPaused挂起防止录键过程中自己触发自己。辅助功能权限一秒一次的实时轮询第二步「Enable Pasting」只解决一个问题让 Tinycast 能把剪贴板条目和展开后的片段粘贴回你正在使用的 App。这一步的 UI 是一个状态徽章Granted / Not granted而它背后的机制值得单独说——实时轮询。OnboardingView.swift 里有一个Timer.publish(every: 1, ...)的 1 秒刷新定时器配合.onReceive持续调用Permissions.isAccessibilityTrusted()即AXIsProcessTrusted()一旦系统授权完成徽章立刻从橙色「Not granted」翻转成绿色「Granted」主按钮也随之从「Grant Access」变成「Continue」.onReceive(refreshTimer) { _ in let trusted Permissions.isAccessibilityTrusted() if trusted ! accessibilityTrusted { accessibilityTrusted trusted } }「Grant Access」按钮走的是 Permissions.openAccessibilitySettings()通过x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility深链直达系统设置的辅助功能页用户授权后无需任何额外操作引导界面会在下一跳轮询里自动感知。整个第二步可跳过showsSkip也可稍后在「设置 → Permissions」里补开属于「可选而非阻塞」的路径设计。这个轮询模式在权限生命周期里不止出现一次ModifierTapMonitor的修饰键监听本质上是一个CGEvent全局事件 tap.cgSessionEventTap、.listenOnly即使只监听也要求辅助功能授权。它通过HealthTicker的 1 秒健康检查在 tap 创建失败、系统超时禁用或权限被撤销时自动重装/重启用没有辅助功能授权时绑定过修饰键快捷键的 recoder 上会直接出现一个橙色警告按钮点击即跳系统设置——同一个权限、同一套「实时感知」逻辑贯穿引导与日常使用。可选 Raycast 迁移密码学级的 .rayconfig 解密第三步是可选的 Raycast 数据迁移也是整个引导里工程含量最高的一环。它复用了备份模块的完整链路选择.rayconfig文件 → 输入导出密码 → 勾选要迁移的类别11 项Shortcuts、Favorites、Aliases、Emoji skin tone、Launch at login、Menu-bar icon、Clipboard history、Snippets、Quicklinks、Pop to root、Compact mode→ 异步导入并展示结果。文件选择的即时反馈是一个细节BackupActions.isRaycastExport()只读取文件前导字节RAYCFG3\n魔数不需要密码就能在文件面板关闭的瞬间判定「这是不是 Raycast 导出」避免用户为一个错误的文件白输一遍密码。真正的解密在 RaycastDecoder.swift.rayconfig是RAYCFG3容器payload 用AES-256-GCM加密密钥由scryptN16384, r8, p1, dkLen32从用户密码派生IV 与 salt 各 16 字节头部与 payload 各自 gzip 压缩payload 解压上限 512MB源码注释强调这只是一个内存上限而非 zip 炸弹防护——AES-GCM 已经对这些字节做过认证。导入任务运行在Task.detachedautoreleasepool里避免大 JSON 树在解码时堆积主线程内存。过程中任何一个错误密码错误、容器损坏、文件过大都会以明确状态显示在引导内联区域而不是抛一个笼统的失败。值得写进文章的事实Tinycast 从不读取 Raycast 的钥匙串Raycast 即使没设密码也会自动生成一个存入 login keychain密码始终由用户输入迁移完成后界面会提示「Quit and reopen Tinycast to finish.」——部分导入结果需要在重启后完全生效。另外如果 Raycast 本体还在运行BackupActions.quitRaycast() 会按com.raycastbundle-id 前缀定位并退出所有 Raycast 主程序保留后台 helper避免两套全局热键在同一时刻抢键。防重复触发的三重保险把首启引导的防重复机制串起来看一共有三层标记先行onboarded文件在展示引导的同一时刻写入中途退出也不会重放状态门控导入步骤的 Continue 按钮在「未导入但可以导入」时才可用且canImport要求「是 Raycast 导出、密码非空、类别非空、未在导入中」四条件同时成立导入中的按钮被替换为禁用的 ProgressView终点即起点最后一步「Get Started」调用finishOnboarding()关闭引导窗口并直接showPalette(mode: .launcher)把用户从向导直接送进可用的启动器——此时第一步录好的快捷键readyMessage里会拼出它的键帽组合已经生效。十 分钟的时间线因此非常清晰录一个顺手的热键含双击修饰键与冲突校验、授权辅助功能1 秒轮询自动感知、有历史数据就拖一个.rayconfig进来AES-256-GCM 全程解密最后一步直接进入启动器。对于从 Raycast 切换过来的用户迁移在这一步就把快捷指令、收藏、别名、剪贴板历史与片段带了过来配合「装完即用」的收尾首启引导的每一步都踩在「能跳过、能回补、能感知」的工程底线上。【免费下载链接】tinycastTinycast — a tiny, fully native macOS launcher, hotkeys, and clipboard history.项目地址: https://gitcode.com/GitHub_Trending/ti/tinycast创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考