Tinycast 从 Raycast 迁移完整指南:.rayconfig 导入、解密原理与字段映射规则
Tinycast 从 Raycast 迁移完整指南:.rayconfig 导入、解密原理与字段映射规则
Tinycast 是原生 macOS 启动器/热键/剪贴板工具,它能够直接读取 Raycast 自身的导出文件(.rayconfig),把快捷键、收藏、片段、快捷链接与剪贴板历史一次性迁移过来。本文围绕 Tinycast 的「Raycast 导入」功能展开:先说明兼容范围与完整操作步骤,再逐类解释字段映射规则(剪贴板、Snippets、Quicklinks、快捷键等),最后结合仓库源码剖析 RAYCFG3 容器的加密格式、scrypt 密钥派生与解码器/读取器的分层架构,帮助你理解导入边界、排错思路与底层原理。
从哪里发起导入
Tinycast 读取的是 Raycast 自己的导出文件,而非重新解析任何第三方中间格式。导入入口有两个:
- 设置界面:Settings → Backup → Raycast Export;
- 欢迎界面:首次打开 Tinycast 时,欢迎页也会提供相同的导入入口。
选定文件、输入密码短语、勾选要迁移的分类后即可导入。分类选择器是独立可复用的视图组件,见 RaycastImportSelection.swift:它以三列网格列出 11 个可勾选分类(Shortcuts、Favorites、Aliases、Emoji skin tone、Launch at login、Menu-bar icon、Clipboard history、Snippets、Quicklinks、Pop to root、Compact mode),并提供 Select All / Deselect All 快捷操作。
兼容范围:只读 Raycast v2.x 的 .rayconfig
仅支持 Raycast v2.0 及更新版本。 Tinycast 读取的是 Raycast v2.0 之后写入的 .rayconfig 文件,其他格式一概不读。导出前请在 Raycast → Settings → About 中确认版本号。
Raycast v1.x 导出不支持。 v1.x 格式连同 Raycast X beta 格式在 Tinycast v0.10.5 中被一并移除——是直接删除而非保留兼容层。如果选择的文件无法打开,请从当前版本的 Raycast 重新导出。
仓库文档 docs/features/raycast-import.md 给出了更精确的表述:.rayconfig 是一个 RAYCFG3 容器,内部是 AES-256-GCM 加密的载荷,密钥由 scrypt 派生。它也是唯一被读取的格式。
导入步骤
- 在 Raycast 中导出设置与数据(Export Settings & Data),记下密码短语;
- 在 Tinycast 中进入 Settings → Backup → Raycast Export,选择
.rayconfig文件; - 输入密码短语,勾选要迁移的类别,执行导入;
- 退出 Tinycast 并重新打开。
为什么必须退出并重开
导入完成后必须完整退出并重新打开 Tinycast,不是所有迁移内容都会在当前运行的进程中即时生效,只有完全重启才能让整批导入全部生效。请从菜单栏图标退出(仅关闭设置窗口是不够的),再重新打开 Tinycast。
文件识别先于密码验证
Tinycast 在输入密码短语之前就能识别文件是否为 Raycast 导出。因此密码错误时报告的是「密码错误」,而不是「这不是 Raycast 文件」。对应的错误类型定义在 RaycastImportError.swift,四种情况各有独立文案:
| 错误类型 | 含义 |
|---|---|
notRaycastFile |
文件不是 .rayconfig 导出 |
incorrectPassphrase |
密码短语错误,或文件已损坏 |
corrupt |
导出内容无法读取 |
tooLarge |
导出过大,建议清理 Raycast 剪贴板历史后重新导出 |
关于那个密码短语
即使你从未设置过密码,Raycast 也会加密导出文件。 它会自行生成一个密码并保存在你的登录钥匙串(login Keychain)中。查看方式有两种:
- Raycast → Settings → Extensions → Export Settings & Data;
- 在「钥匙串访问」中查找服务名
Raycast、账户名export_passphrase。
Tinycast 从不读取你的钥匙串——你需要自己把密码短语粘贴进 Tinycast。这是刻意的安全边界:解密只在用户输入密码短语后发生,应用自身不触碰系统钥匙串中的任何凭据。
迁移清单:什么会过来
| 类别 | 说明 |
|---|---|
| Shortcuts(快捷键) | 应用快捷键、命令快捷键,以及你的 Hyper 键设置 |
| Favorites(收藏) | 来自 Raycast 的固定项(pinned items) |
| Aliases(别名) | 应用别名 |
| Clipboard history(剪贴板历史) | 文本,以及文件仍然存在的图片 |
| Snippets(片段) | 名称、文本和关键字 |
| Quicklinks(快捷链接) | 名称、链接以及用于打开它的应用 |
| Emoji skin tone | Raycast 的默认值映射为 Tinycast 的 Default |
| Compact mode(紧凑模式) | 来自 Raycast 的窗口模式 |
| Pop to root | 仅当时间值恰好匹配 Tinycast 提供的选项时 |
| Launch at login(开机启动) | — |
| Menu bar visibility(菜单栏显示) | 来自 Raycast 的菜单栏图标设置 |
剪贴板排除应用列表(Clipboard history 中排除的应用清单)会随剪贴板历史一并迁移。
关键原则:无法识别的修饰键组合会被整体跳过。 如果某条快捷键含 Tinycast 不认识的修饰键,那么这条快捷键会被整条跳过,而不是被导入成一个与你原有设置略有不同的东西。这是刻意设计——宁可丢失,也不制造"看似正确实则不对"的绑定。
剪贴板历史的导入规则
图片只有在文件仍存在于这台 Mac 上时才会被导入。导入摘要会明确告诉你有多少张图片缺失,而不是静默丢弃。在源码层面,RaycastImportReader.swift 的 mapClipboard 逐条读取 clipboardHistory.clipboardEntries:
- 优先匹配
text/plain表示(representation),命中则导入为文本剪贴项; - 否则查找
image/*且contentType == "url"的表示,此时会用FileManager.fileExists校验图片文件路径,文件不存在则计入missing计数(对应RaycastImport.Result.missingImages,最终呈现在导入摘要中); - 时间戳同时支持带小数秒与不带小数秒的 ISO 8601 格式,解析失败时回退到当前时间。
Snippets 的导入规则
- 片段按原始顺序追加导入,不会覆盖你已有的任何片段;
- 无法读取的片段被跳过;
- 名称冲突时,新片段名会被加上编号(如
Name 2); - 重复的关键字按原样保留;
- 导入的片段默认开启、在启动器中可见、关闭确认提示;
- 导入永远不会打开「关键字展开」(keyword expansion)开关——该开关完全由你自己决定。摘要中会明确说明这一点,因此一个暂不生效的关键字不会看起来像坏了。这与「备份不能授予能力」的原则一致,参见 Backup 参考文档;
- 如果片段文件无法写入,摘要会明确提示,且其他类别仍会继续导入,互不影响。
Quicklinks 的导入规则
- 快捷链接追加到你的库中,永远不会替换现有库,重复项会被跳过,行为与 Quicklinks 的手动导入导出 一致;
- Raycast 的
{Query}占位符会被改写为 Tinycast 的{argument}; - 只要导入了至少一条快捷链接,Quicklinks 功能就会自动开启(打开链接本身不授予任何权限类别)。
从源码看,RaycastQuicklinkImport.swift 实现了这两条规则:rewrittenLink 逐个扫描花括号 token,将 {Query...} 形式(含 {Query}、{Query=xxx}、{Query|...} 等变体)改写为 {argument...},其余 token 原样保留;openWithBundleID 则把 openWith 字段中的应用路径(或以 openWithPlatforms 中的平台 id 解析出的路径)通过 Bundle 解析为 bundle ID。
源码级原理:.rayconfig 的加密容器格式
RAYCFG3 容器的线格式(wire format)在 docs/features/raycast-import.md 中有完整定义:
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)
要点解读:
- 魔数:文件以
RAYCFG3\n开头(8 字节),RaycastDecoder.isExport仅凭开头字节即可判定文件身份——这就是"未输入密码也能先识别文件"的底层原因; - 头部:gzip 压缩的 JSON,携带
schemaVersion、iv、salt(均为 16 字节、hex 编码)。schemaVersion是 Raycast 自己的容器版本号,必须为 3,否则拒绝; - 密钥派生:scrypt 参数固定为
N=16384, r=8, p=1, dkLen=32,对应实现见 Scrypt.swift; - 认证与解密:AES-256-GCM 先用 scrypt 派生出的密钥打开密封盒(SealedBox),认证失败即抛
incorrectPassphrase;成功后再解 gzip 得到载荷 JSON; - 安全边界:认证过的 payload 解压上限为 512 MB(剪贴板繁重的导出解压后会超过 64 MB),未认证的 header 上限为 1 MB——gzip 上限是内存边界而非防 zip 炸弹手段,因为字节已经过 AES-GCM 认证;
- 载荷结构:按类别组织的 JSON,包含
settings、clipboardHistory、顶层snippets(条目自报title)以及包含quicklinks与openWithPlatforms的quicklinks对象。
这些常量与流程直接对应 RaycastDecoder.swift 的实现(magic、containerSchemaVersion = 3、fixedHeaderLength = 12、maximumHeaderLength = 1 MB、maximumPayloadLength = 512 MB、authenticationTagLength = 16)。
快捷键与设置的映射细节
RaycastImportReader.swift 把解密后的载荷映射为 Tinycast 领域类型,几个值得注意的点:
- 应用快捷键:应用的启动路径藏在 applications 命令 id 中
::=::分隔符之后,通过Bundle解析为 bundle ID——与热键、收藏、别名的映射共用同一解析逻辑; - 热键形态:Raycast 热键统一作为
.combo导入(Raycast 没有双击绑定),键码为LayoutIndependent类型、修饰键使用命名形式(Meta→Command、Ctrl→Control、Alt→Option、Shift→Shift),见binding(from:); - Hyper 键:
caps_lock、right_control、right_shift、right_option、right_command会映射到 Tinycast 的物理键枚举HyperKeyPhysicalKey,没有任何值映射到.none,因此不会清空现有设置;若缺少物理键(hyperKeyCode无法识别),则相关和弦快捷键无法触发,故整组映射被跳过; - Pop to root:仅做精确匹配——
popToRootTimeout值不在 Tinycast 的PopToRootTimeout选项集内时跳过而非钳制; - 窗口模式:Raycast 的窗口模式是字符串,Tinycast 只有紧凑模式开关,故
windowMode == "compact"才置位; - 收藏与别名:只映射
e:r:applications扩展下的命令,收藏按favoriteOrder排序、以 bundle ID 为键,别名同样以 bundle ID 为键; - ULID 丢弃:Raycast 的 ULID 被丢弃,每行导入数据获得全新 UUID,与 JSON 快捷链接导入行为一致。
架构分层:纯解码层与平台层
导入链路遵循与 Features/WindowManagement/ 相同的纯层/平台层分离原则:
RaycastDecoder(纯解码层,无 AppKit 依赖):解开RAYCFG3容器,返回载荷的原始字节。因为它不依赖平台 UI,raycast-test可以把它单独编译进测试脚手架(harness)做单元测试;RaycastImportReader(平台层):需要 AppKit(Bundle解析、FileManager文件校验等),因此位于Service/目录,由应用构建而非测试脚手架覆盖;RaycastImport(纯数据):只有Result、selecting(_:)和RaycastImportOptions。selecting(_:)按勾选类别裁剪结果——快捷键/收藏/别名/设置字段/剪贴板/片段/快捷链接各自独立开关,剪贴板排除应用列表归属剪贴板历史分类;BackupActions.importRaycast:在主 actor 之外运行读取器,避免阻塞 UI。
关于测试还有一个值得注意的约束:永远不会把真实的 .rayconfig 作为 fixture 提交,测试脚手架自建 fixture;且未优化的测试脚手架中每次 scrypt 派生都要耗时数秒,因此 raycast-test 只派生一次密钥,把需要走到密钥派生的用例压缩到最少。
不在 .rayconfig 中的内容:另外两个导入器
有两类数据不在 .rayconfig 内,因此各自有独立的导入器:
- Extensions(扩展):Settings → Extensions → Import from Raycast 会复制你已安装的扩展,详见 Installing extensions;
- Script commands(脚本命令):Settings → Commands → Import Raycast Scripts 会把一个脚本文件夹转换为自定义命令,详见 Commands。
导入之后
导入面板中有一个 Quit Raycast 按钮,方便你在迁移完成后退出 Raycast。除「从 Raycast 导入扩展」这一项(其定义上需要读取 Raycast 的文件夹)之外,Tinycast 的任何功能都不依赖 Raycast 保持安装状态——迁移完成后可以随时卸载 Raycast。