Tinycast 从 Raycast 迁移完整指南:.rayconfig 导入、解密原理与字段映射规则

原创2026-09-19 23:20:472,246 阅读
文章标签:桌面应用

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 派生。它也是唯一被读取的格式。

导入步骤

  1. 在 Raycast 中导出设置与数据(Export Settings & Data),记下密码短语;
  2. 在 Tinycast 中进入 Settings → Backup → Raycast Export,选择 .rayconfig 文件;
  3. 输入密码短语,勾选要迁移的类别,执行导入;
  4. 退出 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。

登录后查看全文
tinycast