把 Raycast 十年家当搬进 Tinycast:导出、解密、勾选的全流程实录
把 Raycast 十年家当搬进 Tinycast:导出、解密、勾选的全流程实录
在 macOS 效率工具圈子里,Raycast 多年的使用积累往往是一笔沉甸甸的"数字资产":几十条全局快捷键、上百条剪贴板历史、精心整理的 Snippets、以及习惯成自然的 Quicklinks。换用新启动器最怕的不是功能差异,而是这些家当被锁在一份不知道如何打开的加密文件里。开源原生启动器 Tinycast 给出的答案是:只认 Raycast v2.x 的 .rayconfig 导出文件,用纯 Swift 实现的 scrypt + AES-256-GCM 把它解开,再让你逐项勾选 11 类数据迁移过来。这篇文章沿着"导出 → 解密 → 勾选 → 收尾"的完整链路,把每一处关键代码和设计决策都摊开来看。
第一步:导出 .rayconfig,密码到底在哪
Raycast 的数据导出入口在 Raycast → Settings → Extensions → Export Settings & Data,产出的就是一个 .rayconfig 文件。这个文件不是明文 JSON,而是一个带签名头的容器,Tinycast 源码里把它叫作 RAYCFG3——魔数、版本、加密参数、载荷一起打包(RaycastDecoder.swift):
file = "RAYCFG3\n" ‖ UInt32LE(header.count) ‖ gzip(header JSON) ‖ ciphertext ‖ tag(16)
body = AES-256-GCM(gzip(payload JSON))
key = scrypt(passphrase, salt, N=16384, r=8, p=1, dkLen=32)
绝大多数用户的一个直觉误区是"我导出时没设过密码,这个文件应该没加密"。实际上,Raycast 即使用户没有主动设置密码,也会自动生成一个随机口令,并把口令存进 macOS 登录钥匙串(服务名 Raycast、账号 export_passphrase),在导出设置界面里就能看到。也就是说,.rayconfig 永远是加密的,你只是不知道钥匙放哪了。
而 Tinycast 的态度很明确:它绝不读你的钥匙串。官方文档写得很直白:"Tinycast never reads the keychain; the user supplies the passphrase."(raycast-import.md)。用户必须手动输入导出时设置的密码,这把"是否信任第三方应用读取系统钥匙串"的决定权完全留给了用户——一个启动器多读一次钥匙串,就意味着你的所有凭据都暴露在它的代码审计范围内。
选择文件时还有一个贴心的交互细节:RaycastDecoder.isExport 只读取文件头部几个魔数字节就能判定"这到底是不是 Raycast 导出"(BackupActions.swift 用 Data(contentsOf:options:.mappedIfSafe) 映射读入),所以"选文件"和"输密码"被拆成两步——文件还没选错之前,根本不需要你费劲敲密码。
guard isExport(raw) else { throw RaycastImportError.notRaycastFile }
对应的错误文案也分层清晰:notRaycastFile(不像 Raycast 导出)、incorrectPassphrase(密码错误或文件损坏)、corrupt(无法解析)、tooLarge(超过载荷上限),见 RaycastImportError.swift。错误的归因被刻意切细,避免"密码错了"和"文件坏了"混在一起误导排查。
第二步:解密——手写的 scrypt 与 AES-GCM
拿到文件、输入密码之后,真正解包逻辑都在 RaycastDecoder.swift 的 decrypt(_:passphrase:) 里。整个过程分成三层:
第一层是"前 12 字节固定头 + 变长头"。 固定头是魔数 RAYCFG3\n(8 字节)加 4 字节小端序的 header 长度。变长头本身是 gzip 压缩的 JSON,解压后包含 schemaVersion、iv、salt 三项关键参数。schemaVersion 必须严格等于 3——这是 Raycast v2.x 容器的版本号,任何其他值(包括未来的 schema 4)都会被直接拒绝,这是容器版本一致性约束。iv 和 salt 都是 16 字节十六进制字符串,各自解码后还要校验长度。
第二层是密钥派生。 这是整个导入流程最硬核的部分:Tinycast 没有引入任何第三方加密库,而是用 Swift + CryptoKit 从零实现了 RFC 7914 标准的 scrypt(Scrypt.swift)。参数是 Raycast 固定的 N=16384, r=8, p=1, dkLen=32,实现路径完整覆盖 PBKDF2-HMAC-SHA256 前置散列、ROMix 迭代、BlockMix 与 Salsa20/8 置换。对一个"零第三方依赖"为卖点的原生应用来说,这等于把密码学最吃内存的 KDF 也揽进了自己审计范围——代码注释里也强调,这是为了"让导入不需要任何第三方加密依赖"。
let key = Scrypt.derive(
passphrase: Array(passphrase.utf8), salt: UInt8,
n: 16384, r: 8, p: 1, dkLen: 32)
第三层才是 AES-GCM 解密。 用派生出的 32 字节密钥构造 AES.GCM.SealedBox(nonce 即 header 里的 iv),调用 CryptoKit 的 open。注意一个工程细节:密码错误并不是靠"解密结果解析失败"来发现的,而是直接由 GCM 的认证标签校验失败触发——GCM 在解密前就会校验 16 字节 tag,所以错误密码会立刻抛出 RaycastImportError.incorrectPassphrase,根本不会把伪造的明文交到下一步。解密成功后再做一次 gzip 解压,得到类别键控的 JSON 载荷。
边界防御也做得相当克制:变长头上限 1 MB,载荷解压上限 512 MB。文档里特别澄清,这个 512 MB 的上限不是 zip 炸弹防护——因为 AES-GCM 已经认证过这些字节了,它纯粹是内存边界;而未认证的 header 才需要限制在 1 MB。剪贴板历史动辄解压出几十 MB,所以 512 MB 的留量是够用的。
这些细节不是嘴上说说,Tests/raycast-test.swift 里有一整套针对容器格式的测试:错误的密码必须抛 incorrectPassphrase;魔数截断要抛 notRaycastFile;任何短于固定头的截断都不允许被"读出来"而是直接拒绝;连非零起点的 Data 切片、超范围 header 长度这些刁钻输入都被遍历覆盖。测试夹具还在进程内动态构建,明确约定"绝不把真实的 .rayconfig 提交进仓库"。这份测试基建本身就是解码器可靠性的最好证明。
第三步:勾选 11 类项目,一次只搬你想要的
解密只是拿到了 JSON,真正的"搬家"从 RaycastImportReader.swift 开始。在导入之前,用户会面对一个三列网格的勾选面板(RaycastImportSelection.swift),对应 11 个可独立导入的类别(RaycastImport.swift):
| 类别 | 说明 |
|---|---|
| Shortcuts | 全局快捷键、Hyper Key |
| Favorites | 应用收藏(按 bundle ID) |
| Aliases | 应用别名 |
| Emoji skin tone | Emoji 肤色偏好 |
| Launch at login | 开机启动 |
| Menu-bar icon | 菜单栏图标可见性 |
| Clipboard history | 剪贴板历史 |
| Snippets | 代码片段 |
| Quicklinks | 快捷链接 |
| Pop to root | 面板弹回根层级超时 |
| Compact mode | 紧凑模式及收藏显示 |
RaycastImportOptions 是一个用位标志实现的 OptionSet,勾选结果通过 selecting(_:) 在数据层完成裁剪——注意它的设计原则是"按字段裁剪、多余的直接丢弃",因为 apply() 本身就是逐字段写入的,裁剪过的数据结构天然安全。UI 层默认全选,也支持 Select All / Deselect All 一键切换。
字段映射的规则值得逐一细看,因为它们决定了"搬家"的还原度:
- 快捷键:Raycast 的 Hyper Key 物理键代码映射到 Tinycast 的枚举(
caps_lock、right_control等),映射表里明确注释"没有任何东西映射到.none,所以没匹配到就清除"。所有热键统一以.combo(组合键)形式导入,因为 Raycast 没有双击触发机制。修饰键的Meta/Ctrl/Alt/Shift一一对应到command/control/option/shift,按键码走LayoutIndependent布局无关码。 - 应用收藏与别名:都从 Raycast 的
commands数组里筛出extensionId == "e:r:applications"的命令。命令 id 里藏在::=::之后的尾巴就是应用路径,再通过Bundle解析成 bundle ID——收藏保留 Raycast 里的favoriteOrder排序,别名只导入非空且经 trim 的值。 - 剪贴板历史(RaycastClipboardImport.swift):每条记录有多重 representations,
text/plain永远优先;空文本会回落到image/*表示;只有contentType == "url"且文件仍然存在的图片才会变成图片剪贴项,缺失的图片会被计数上报而不是静默丢弃。时间戳支持带小数秒的 ISO8601,pinned: true的条目导入后仍是置顶状态,且pinnedAt用原始createdAt作为确定性回退——所以导入的置顶项按创建时间排序,最老的在最前。乱写的 pin 值(字符串、数字、数组)一律按"未置顶"处理,不会丢弃文本。 - Snippets(RaycastSnippetImport.swift):Raycast 的
title字段映射为名称,空名称条目直接丢弃;keyword经 trim 后为空则视为无关键字。 - Quicklinks(RaycastQuicklinkImport.swift):这是映射细节最丰富的一类。Raycast 的参数占位符
{Query}会被重写成 Tinycast 的{argument}(含{Query=}、{Query|}这类带修饰的变体);openWith可能是应用路径也可能是平台 id,二者都要解析成 bundle ID;导入走QuicklinkArchive.merge,是合并进现有库而不是整库替换。Raycast 的 ULID 会被丢弃,每条 Quicklink 换发全新的 UUID。
导入执行在 BackupActions.importRaycast 里,它刻意跑在 Task.detached + autoreleasepool 中——剪贴板历史可以有几 GB 的 JSON 树,离主线程解析、随池子释放内存是基本操作。导入 Snippets 前会先启动 Snippets 存储,让新片段立刻在启动器中可用;导入至少一条 Quicklink 会自动打开 quicklinksEnabled 开关,因为"打开链接不授予任何权限类"。
第四步:收尾清单——重启、退出 Raycast、核对报告
导入完成不等于一切就绪。设置面板(BackupSettingsView.swift)会给出三件必须做的事,每一件背后都有对应的代码逻辑:
1. 退出 Raycast。 面板里有一个实时冲突提示:只要检测到正在运行的 Raycast,就会显示橙色警示"Raycast is running — quit it to avoid hotkey conflicts"并给出 Quit Raycast 按钮。实现上,BackupActions.quitRaycast() 遍历运行中的应用,凡是 bundle ID 前缀命中 com.raycast 且 activationPolicy != .prohibited 的一律 terminate()——跳过 .prohibited 是为了不误杀 Raycast 的后台辅助进程,只退出主应用本体。逻辑是:快捷键冲突必须靠"另一方先停"来避免,Tinycast 不会去抢。
2. 重启 Tinycast。 不是所有导入的字段都能在运行中的应用里即时落定,所以导入成功的消息末尾固定追加一句"Quit and reopen Tinycast to finish"(restartAfterImportText)。这是典型的"写盘已成功、运行时未热载"的诚实声明——宁可让用户手动重启一次,也不假装全部即时生效。
3. 核对导入报告。 导入结果不是一句干巴巴的"成功",而是一句按实际迁移量逐类组装的话术(raycastText):应用了多少条设置/快捷键/收藏/别名、导入了多少条剪贴板、多少条 Snippets、多少条 Quicklinks,缺失图片单独计数,Snippets 导入失败或 Quicklinks 库不可用也会单独报错而不中止其余部分。代码注释点明设计意图:"one sentence per category that actually moved, so an import is never silent"——每个实际移动过的类别都有一句话,导入永远不会无声无息。剪贴板历史进入后还会过一遍 Tinycast 的保留策略(默认三个月),老的非置顶条目会被修剪,而置顶条目豁免。
另外值得补一句:这个导入能力不只藏在设置里。首次启动引导(OnboardingView.swift)把"导入 Raycast 导出"做成了可选的第二步——快捷键配置、辅助功能权限、Raycast 导入三步走,全程标记防重复触发。如果你当时跳过了,随时可以从 Settings → Backup 再回来。
一条可审计、可验证的迁移链路
回过头看,这条迁移链路最值得称道的是它把"信任"问题拆得清清楚楚:格式是公开的 wire layout,scrypt 参数和 AES-GCM 结构在 raycast-import.md 里画成图;解密器保持平台无关、可以脱离整个应用单独编译测试;错误分层让"文件选错、密码输错、数据损坏"三种场景各有各的报错;导入行为要么合并、要么裁剪、要么明说"需要重启",没有一项是悄悄覆盖的。而它连版本策略都很克制——只认 v2.x 的 RAYCFG3,v1.x 导出和 Raycast X beta 的格式从 v0.10.5 起直接删除而不是兼容背负。对想彻底接管自己数据的人来说,这样的"十年家当搬运工"才搬得踏实。