
Tinycast 备份与恢复.tinycast 单文件备份的构成、导入语义与安全边界【免费下载链接】tinycastTinycast — a tiny, fully native macOS launcher, hotkeys, and clipboard history.项目地址: https://gitcode.com/GitHub_Trending/ti/tinycast备份与恢复是 Tinycast 把整套配置从一台 Mac 搬到另一台的关键能力一次备份就是一个.tinycast文件导出时你勾选放进去的内容导入时再勾选放回来的内容两者相互独立——一个包含全部内容的文件也可以只恢复你的 Snippets。本文基于官方文档 website/content/docs/reference/backup.md并结合仓库源码Tinycast/Features/Backup 下的 Model / Service / Settings 三层实现与 Tests/backup-archive-test.swift完整讲解备份文件的内部结构、导出/导入操作、合并语义以及备份永远不会替你授予权限这条安全红线。一次备份 一个 .tinycast 文件Tinycast 的备份入口在Settings → Backup。一次导出会生成一个单一文件扩展名为.tinycast对应 UTIcom.tinycast.backup见 BackupActions.swift。导出和导入是两套彼此独立的勾选导出时你决定什么放进去导入时你决定什么放回来。因此一个什么都装的备份文件完全可以只恢复你的 Snippets其他类别原样不动。五大备份类别类别会带走什么Settings Shortcuts快捷方式、自定义命令、Quicklinks、窗口布局、收藏项、别名、偏好设置Clipboard History文本与图片剪贴记录含图片本体以及被复制文件的引用Snippets你的 Snippet Markdown 文件Notes你的 Note Markdown 文件Launcher Learning启动器学会的你常打开什么以及 Emoji 与计算器历史这五个类别在源码中就是BackupCategory枚举的五种 case见 BackupCategory.swiftconfiguration、clipboard、snippets、notes、learning。声明顺序而非字母序决定了选择器、manifest 和导入摘要永远按同一顺序展示BackupCategory.swift。另外启动器launcher还提供了Export Backup和Import Backup两条命令。由于命令面板没有勾选框的位置这两条命令总是取全部内容——全部导出、全部导入选择粒度只在设置面板里提供BackupActions.swift。依赖备份之前先读这一段备份格式属于 Tinycast 私有可能在版本之间发生变化。唯一承诺是备份能导入到生成它的同一个版本。.tinycast文件内部记录着写它的版本。若某个 Tinycast 版本不认识该文件它会明确告知而不是只导入一半。BackupManifest中有一个format字段读取端只接受currentFormat 1发现其它值会抛出unsupportedFormat错误提示这个备份由不同版本的 Tinycast 生成format N期望 1请从拥有你配置的那台 Mac 重新导出见 BackupManifest.swift。因此正确的使用姿势是把备份当作今天把配置搬到另一台 Mac / 重装后恢复的工具而不是长期归档。要长期归档见文末你的数据真正住在哪里一节——Snippets 和 Notes 本身就是普通 Markdown 文件。导出勾选类别生成单个文件在Settings → Backup中点击 Export 区域内的Export…按钮通过勾选BackupCategorySelection决定包含哪些类别然后保存为.tinycast文件。保存面板会以Tinycast-日期.tinycast命名日期格式为yyyy-MM-ddBackupActions.swift。从源码看导出流程分为三步BackupActions.swiftplan主线程从各个 Store 收集要写什么——配置快照、剪贴板数据库路径、Snippets/Notes 目录、Launcher Learning 记录打包成可跨线程传输的PlanBackupComposer.swift。write后台线程在暂存目录中按类别拼装 bundle 并写出manifest.jsonBackupComposer.swift。seal后台线程用 AppleArchive 把整个暂存目录压缩成单个.tinycast文件BackupArchive.swift。剪贴板历史可能达到 GB 级所以写入与压缩都在Task.detached的后台队列完成避免卡住主线程。.tinycast 文件内部长什么样BackupBundleBackupBundle.swift定义了密封前的目录布局解开一个.tinycast后你会看到路径内容manifest.json目录清单格式版本、写出的 app 版本、创建时间、各类别的条目数settings.jsonSettings Shortcuts 类别的配置快照SettingsBackup的 JSON 序列化clipboard/items.jsonl剪贴板条目一行一条JSONLclipboard/images/剪贴板图片本体snippets/*.mdSnippet Markdown 文件notes/*.mdNote Markdown 文件learning/ranking.json、learning/emoji.json、learning/calculator.json三类学习记录几个值得注意的实现细节manifest 按类别记录计数counts以BackupCategory.rawValue为键某个类别缺失就表示该类别未包含在备份中导入界面会将其灰显BackupManifest.swift。剪贴板用 JSONL 而非 JSON 数组每条剪贴记录占一行JSON 编码使用sortedKeys日期用 ISO-8601剪贴内容中的换行会被转义因此\n只可能作为行分隔符出现BackupBundle.swift。日期统一 ISO-8601编码器与解码器都配置iso8601日期策略让备份文件人眼可读、任何解码器可读BackupBundle.swift。压缩用 LZFSE 而非 LZMA因为备份负载以 PNG 为主PNG 本身已压缩过LZFSE 足够且更快BackupArchive.swift。归档字段键集只保留TYP,PAT,DAT,MOD,MTM刻意不携带 UID/GID避免把别人的文件属主恢复到你机器上BackupArchive.swift。文件名安全Snippet/Note 的标题会被清洗成文件名路径分隔符/、\、:等一律替换为-防止标题变成目录重名文件自动追加数字后缀绝不覆盖BackupBundle.swift。导入永不静默、合并而非覆盖在Settings → Backup的导入区点击Choose…选择.tinycast文件Tinycast 会先解开文件并读取 manifest把可用的类别连同条目数列出来供你勾选BackupSettingsView.swift点击Import后才真正应用。导入有四个铁律1. 导入永远不会静默每次导入都会逐类别展示一份摘要说明它做了什么应用了多少条设置、导入了多少个剪贴记录/ Snippet / Note / 学习记录。如果文件里包含自定义命令Tinycast 会在导入前弹出确认框明确警告此备份包含 N 个自定义命令和 M 个全局快捷方式。自定义命令可以运行任意 shell 代码只导入你信任的文件BackupActions.swift。一个悄悄添加 shell 命令的文件是另一种风险所以这一步不可跳过。2. 导入是添加不是覆盖Snippets 和 Notes 会落在你现有内容的旁边重名的 Note 会被加数字后缀绝不会顶掉你已有的同名文件命名去重逻辑见 BackupBundle.swift。Snippets 的去重更精细按名称 正文组合去重Pair(name, text)因此两个同名但内容不同的 Snippet 都能保留同一备份导入两次也不会得到两份拷贝BackupApplier.swift。配置字段的合并也是同样的思路SettingsBackup的每个字段都是 Optional只有文件里存在的值才会被应用SettingsBackup.swift。3. Launcher Learning 是例外整体替换学习数据是替换而非合并——两台 Mac 的习惯混在一起描述的就不是任何一台。导入时replace掉现有的排名、Emoji 频次与计算器历史BackupApplier.swift。4. 剪贴板中的文件引用只带走路径被复制的文件file 类条目在备份里只记录它的路径不带走文件字节——备份从不携带它从未持有的字节BackupComposer.swift。导入时这台 Mac 上不存在的路径会被直接丢弃而不是留下一个指向虚无的死条目BackupApplier.swift。相比之下剪贴板图片是完整存入备份的按文件名存储不依赖图片在 Mac 上的原始位置。备份永远不能授予一项能力这是整篇文档最重要的一节。有些开关被刻意排除在备份之外因为打开它们是一个你需要亲自做出的决定而不是一条可迁移的偏好Snippets开启它意味着同意关键词匹配监听键盘Extensions同意运行第三方代码Calendar同意读取你的日历Auto Join Meetings和Camera Preview同意打开链接、打开摄像头Quick Actions同意向其它应用键入文本AI和MCP servers同意把文本发给模型、运行服务器代码Search text in images and PDFs同意后台文本识别Fallback order and checkboxes可能把 shell 命令执行器放进你的启动器因此别人发给你的备份不可能替你打开键盘监听、运行第三方代码、读取日历或连接 AI 提供商——这些都需要你在应用内亲自开启并在开启前阅读它们的作用。导入 Snippets 也不会自动打开 Snippets 功能导入完成后界面会提示请在设置中开启 Snippets 以使用其关键词BackupActions.swift。这一点在源码里有逐字段的注释佐证SettingsBackup.swift 中snippetsEnabled、calendarEnabled、autoJoinMeetings、cameraPreview等字段在SettingsData里根本不存在——收集端不写、应用端不读从结构上杜绝了导入时被悄悄打开的可能而quicklinksEnabled、appleShortcutsEnabled这类打开链接/运行用户自建快捷方式不授予新权限类的开关则被允许携带SettingsBackup.swift。其它刻意排除的内容排除项原因Extensions代码、数据、登录态第三方内容且登录态存在钥匙串Keychain里AI 对话、API 密钥、所有 AI 与 MCP 设置对话和密钥留在产生它们的那台 Mac 上Quick Actions 模型、提示词、语言与自定义动作导入绝不能改变某个快捷键对你的文本做什么Extension 注册表、包管理器、自定义搜索路径它们描述的是这台 Mac不是你的设置Palette 位置、自动切换输入法、日历勾选它们属于这台 Mac 的屏幕与硬件一切缓存如汇率、更新检查它们会自己回来剪贴板图片按名称存在备份内部而不是按它们在 Mac 上的原始位置备份携带的唯一一种路径是被复制文件的位置——因为路径本身就是这条剪贴记录的内容。Launch at login和Show in menu bar稍有不同它们从实时状态读取而非从备份的静态值恢复所以会按你离开时的样子带回来见 SettingsBackup.swift 中从UserDefaults读取showInMenuBar。你的数据真正住在哪里备份带走的一切同时也是~/Library/Application Support/com.tinycast.app/下的普通文件内容位置SnippetsSnippets/NotesNotes/Quicklinksquicklinks.sqlite3另有自己的 JSON 导出Clipboard historyclipboard.sqlite3图片文件就在旁边AI chatsai-chats.sqlite3从不进备份Snippets 和 Notes 是纯 Markdown。直接复制这两个文件夹就是一个完全合格的备份而且不需要 Tinycast 就能打开阅读——这正是把它们保持为纯 Markdown 的意义。而剪贴板图片进入备份时按名称存放、AI 对话永远不离开本机这两条规则共同划出了什么可以带走、什么必须留下的边界。源码层面的安全措施与测试保障备份的只进不退安全承诺不只是界面设计还体现在归档层的硬性防护中BackupArchive.swift拒绝符号链接解包完成后会扫描整个目录树只要发现任何符号链接就判定为损坏、拒绝导入——因为透过链接读取会逃逸出解包目录。拒绝绝对路径与..解包时对每个条目做过滤凡是绝对路径或含..的条目一律跳过恶意归档无法逃出暂存目录。所有权不随行归档字段键集不含UID/GID解包出来的文件属于打开它的当前用户。这些行为都有自动化测试背书。Tests/backup-archive-test.swift 覆盖了二进制图片数据完整往返、含非 ASCII 与路径分隔符的标题安全落盘、空文件存活、manifest 往返一致、JSONL一行一条的不变式、绝对路径不逃逸、拒绝路径穿越、拒绝符号链接、类别枚举完整性与暂存清理Tests/backup-archive-test.swift。测试中特意验证解包后的文件属主是当前用户与文档备份不是长期归档的定位相互印证。导出的暂存目录放在系统 Caches 下backup-staging/每次运行先清扫超过 24 小时的孤儿目录避免一次崩溃遗留的 GB 级临时文件无人回收BackupStaging.swift离开导入设置页时已解开的暂存树也会被立即丢弃防止大文件滞留内存与磁盘BackupSettingsView.swift。小结Tinycast 的备份设计可以浓缩为三句话一个文件、两套勾选——导出勾选决定装什么导入勾选决定放回什么导入合并不覆盖——只有 Launcher Learning 例外整体替换备份永不授权——所有涉及监听键盘、运行第三方代码、读取日历、连接 AI 的开关都被结构性排除在外必须由你在应用内亲手开启。理解了这些边界你就能安全地把.tinycast当作今天搬家的工具同时清楚它的局限格式属于 Tinycast 私有、只在同版本间有保证长期归档请直接备份Snippets/与Notes/这两个 Markdown 目录。【免费下载链接】tinycastTinycast — a tiny, fully native macOS launcher, hotkeys, and clipboard history.项目地址: https://gitcode.com/GitHub_Trending/ti/tinycast创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考