Tinycast原生 macOS 启动器的技术解析与实战指南——零依赖、SwiftUI 渲染 Raycast 扩展【免费下载链接】tinycastTinycast — a tiny, fully native macOS launcher, hotkeys, and clipboard history.项目地址: https://gitcode.com/GitHub_Trending/ti/tinycastTinycast 是一个完全原生的 macOS 启动器launcher以“一个全局热键调起你整天要用的所有东西”为设计目标并将常驻内存控制在 100 MB 以下。它由 SwiftUI 与 AppKit 编写、零第三方依赖、无 Electron、无遥测同时能原生运行真实的 Raycast 扩展并以 SwiftUI 渲染。本文以仓库 README.md 为骨架结合 docs/architecture.md、docs/development.md 以及各功能模块文档完整讲解它的功能清单、安装与权限配置、使用入门、从源码构建的流程以及其分层架构与核心子系统启动器、命令面板、热键、剪贴板、Raycast 扩展运行时的底层实现原理。项目概览一个 100 MB 内存预算内的全栈生产力工具Tinycast 的定位在 README.md 第一段就写得很明确tiny, fully native macOS launcher——小巧、完全原生的 macOS 启动器One hotkey, everything you reach for all day, under 100 MB of RAM一个热键搞定你整天要伸手去拿的一切内存占用低于 100 MB。技术选型上它刻意与常见竞品保持距离SwiftUI AppKit零第三方依赖没有 Electron没有遥测。同时它并不封闭——可以运行你已经安装的真实 Raycast 扩展并把它们的界面渲染成原生 SwiftUI而不是塞进一个浏览器内核。项目免费、开源采用 AGPL-3.0 许可证。从仓库结构看docs/README.md 提供了完整文档索引这是一个组织极其严谨的代码库docs/下按“每个文档一个职责”的原则分别覆盖架构architecture.md、工程标准standards.md、测试testing.md、开发development.md、发布release.md、签名signing.md与设计系统ui.md每个功能模块还有一份独立的 feature 文档且都要求以## Invariants不变量开头。功能矩阵启动器之外的一整个工具箱README.md 的 Features 章节罗列了 18 项核心能力每一项在Tinycast/Features/下都有对应的Model/、Service/、UI/、Settings/源码目录与docs/features/文档App launcher应用启动器——模糊搜索并启动任何应用、固定收藏、查看运行状态、退出单个应用或一键退出全部应用。Global hotkey全局热键——一个快捷键从任何地方调起命令面板。Per-app hotkeys按应用热键——为某个应用绑定一个按键按一下切换聚焦/隐藏。Search Files文件搜索——从你指定的文件夹中打开文件与文件夹底层走 Spotlight不维护自己的索引。Dictionary词典——通过 Define Word 命令查词或从启动器的 fallback 入口查询当前输入内容读取 Mac 自带的词典。Clipboard history剪贴板历史——文本与图片可搜索可粘贴回你正在使用的应用。Calculator计算器——在面板内直接完成数学计算、单位换算、实时货币与加密货币换算。Quicklinks快捷链接——把 URL、搜索、文件或 deeplink 变成一个命令支持为输入、剪贴板或日期占位。Apple Shortcuts快捷指令——搜索并运行你在“快捷指令”App 里构建的快捷指令支持别名与全局热键。Snippets文本片段——可复用的 Markdown 模板支持动态占位符、参数、嵌套引用与可选的关键词展开。Custom commands自定义命令——通过模糊搜索或专属全局热键运行命名 Shell 命令。Window management窗口管理——34 个 Rectangle 风格动作半屏、四分之一、三分之一、缩放、微调、跨显示器移动、全屏与 Spaces。System actions系统动作——锁定、睡眠、重启、清空废纸篓、切换外观、蓝牙、静音、隐藏文件等等。Calendar and meetings日历与会议——下一个会议显示在空白面板与菜单栏中一键加入或让它自动加入。Notes笔记——在一个悬浮编辑器中管理无限制的纯 Markdown 文件可从面板搜索并即写即渲染。Emoji picker表情符号选择器——一个可搜索的表情网格一次按键即可唤出。AI chatAI 对话——使用自己的 API Key 或已安装的 AI 账号在面板内对话。与所有 AI 功能一样默认关闭。Quick Actions快捷动作——在任何应用中修复语法、改写、翻译或总结选中的文本。Raycast extensionsRaycast 扩展——原生运行你已经拥有的扩展渲染为 SwiftUI。Backup and import备份与导入——把设置导出到文件或从 Raycast 导入你的配置。值得注意的是README 中强调Clipboard history是唯一默认开启的功能开关——这一点在 docs/features/clipboard.md 的 Invariants 中被证实clipboardEnabledships on且“该键缺失”必须优先于存储的false关闭即完全关闭轮询器停止、SQLite 文件关闭、启动器命令与快捷键消失、Tab 跳过该屏幕。安装指南Homebrew Tap 与 DMG 两种途径Tinycast 的官方安装路径是 Homebrew。按照 README.md 的 Install 章节第一步添加第三方 tapmacOS 对第三方 tap 有信任要求brew trust --tap abue-ammar/tinycast # 第三方 tap 必需 brew tap abue-ammar/tinycast然后根据你的 Mac 类型选择对应的安装命令你的 Mac安装命令Apple siliconmacOS 26 或更新brew install --cask tinycastIntelmacOS 26brew install --cask tinycast-universal不确定自己的芯片苹果菜单 → 关于本机。Homebrew 也会自行校验并拒绝安装不匹配的版本。需要尝鲜版可以执行brew install --cask tinycastbeta它会在稳定版旁边安装Tinycast Beta.app拥有自己独立的设置与权限仅限 Apple siliconmacOS 26。两个关键细节Quarantine 标志Homebrew 在每次安装与更新时都会清除 macOS 的 quarantine 标志因此正常安装后无需额外操作。DMG 方式如果从 Releases 下载 DMG由于 Tinycast 是自签名应用需要手动清除一次隔离标志xattr -dr com.apple.quarantine /Applications/Tinycast.app权限说明Accessibility 是唯一必需的授权Tinycast 对系统权限极其克制——Accessibility辅助功能是它唯一要求的权限且只在特定场景下需要当 Tinycast 需要向其他应用粘贴或展开文本时这也是 Snippets 关键词展开唯一需要的权限。触发时机与授予方式是“首次使用即提示”当你第一次使用需要该权限的功能时Tinycast 会弹出提示然后在系统设置 → 隐私与安全性 → 辅助功能中授予即可。需要强调的是Snippets 功能默认是禁用的且按键匹配全部在本地完成从不存储、从不外发。从 docs/features/hotkeys.md 可以进一步看到这个权限在底层的多处应用DoubleTapMonitor双击修饰键、HyperKeyTapHyper 键、CommandEscapeTap⌘⎋ 拦截都是CGEventTap都依赖 Accessibility 授权其中DoubleTapMonitor采用.tailAppendEventTapHyperKeyTap采用 modifying tap两者都“只在需要时才安装”并从不主动弹窗索要权限——由一秒一次的健康检查定时器在授权落地瞬间自动安装。使用入门五分钟上手README.md 的 Using it 章节给出了最简洁的启动路径打开设置 → 通用录制一个全局快捷键用于调起 Tinycast。在任何地方按下它 → 命令面板浮现。输入以过滤↵启动。Tab在 Apps 与 Clipboard 之间切换↑/↓移动选择Esc关闭。设置 → 快捷键——搜索某个应用或自定义命令并录制全局快捷键。设置 → Snippets——启用该功能然后创建带展开关键词的模板。这五步背后是一个精心设计的命令面板docs/features/palette.md它是无边框悬浮NSPanel由PaletteWindowController独占持有窗口 framehosting view 设置sizingOptions []SwiftUI 永不驱动窗口尺寸面板的扁平selection索引必须与可见行顺序完全一致这个映射由Features/PaletteRowIndex.swift承担并保持Foundation-only 纯函数因此Tests/palette-selection-test.swift直接编译发布源码来验证。面板的导航模型也很有设计感由“召唤”决定屏幕如何安置而不是由模式决定。PaletteCoordinator.navigate(to:)是唯一规则——面板已打开时进入某个屏幕是“导航”当前屏幕被压栈成为返回步面板隐藏时进入某个屏幕是“召唤”新屏幕成为根。Tab 键在三个读者直接打开的界面间循环launcher → AI chat → clipboard → launcher。从源码构建工具链、开发通道与生成数据README.md 将构建指南指向 docs/development.md那里给出了完整的本地开发闭环环境要求macOS 26 或更新Liquid GlassXcode 26提供 SwiftUI macro 插件与 SDK[XcodeGen]生成工程文件以及用于 lint 的brew install swiftlintNode仅用于数据生成脚本与run-tests.sh驱动的两个 stub 服务器——构建应用本身完全不需要 Node首次设置创建一次Tinycast Self-Signed代码签名身份——构建用它签名从而保证每次重建后 macOS 不会忘记 Accessibility 授权详见 docs/signing.md §1。构建与运行open Tinycast.xcodeproj # 然后 ⌘R或命令行方式xcodebuild -project Tinycast.xcodeproj -scheme Tinycast -configuration Debug buildTinycast.xcodeproj是提交进仓库、由project.yml通过 XcodeGen 生成的——修改project.yml中的工程设置后运行xcodegen generate并提交结果。仓库没有Package.swift且严禁使用Bundle.module。Dev 通道与正式版完全隔离Debug 构建是独立通道Tinycast Dev.appbundle idcom.tinycast.app.dev。所有持久化数据都按 bundle id 隔离——~/Library/Preferences/id.plist设置与热键绑定、~/Library/Application Support/id/引导标记、笔记、片段、快捷链接、剪贴板历史、计算器历史、启动排序与常用表情、~/Library/Caches/id/汇率、更新检查、暂存下载、SMAppService登录项与 TCC 授权——因此本地构建既读不到也不会覆盖已安装应用的状态两者可以并行运行。值得注意的设计原则只有可重新获取的东西才有资格进 Caches其余一律进 Application Support——因为~/Library/Caches不在 Time Machine 备份范围内且系统在磁盘紧张时会不经通知直接回收。生成数据三个 Swift 文件由脚本生成、禁止手改每个脚本都会下载数据源因此需联网执行后提交结果node Scripts/gen-emoji.js # - Tinycast/Features/Emoji/Model/EmojiData.generated.swift node Scripts/gen-currencies.js # - Tinycast/Features/Calculator/Model/CurrencyData.generated.swift node Scripts/gen-countries.js # - Tinycast/Features/Calculator/Model/CountryZoneData.generated.swiftgen-currencies.js很有意思它把汇率接口自身的报价列表、Unicode CLDR 的货币显示名与 CLDR 的补充货币数据哪些代码还在流通按 ISO 代码做三方 join从而保证货币表与实时汇率源永不脱节。架构纵深四层分层与单一拥有者核心要真正理解 Tinycastdocs/architecture.md 是必读文档。它的架构核心可以概括为两条主线四层分层纯逻辑与副作用严格分离每个成熟的子系统都收敛为四个层次且Tests/下的独立 harness 是让它们保持分离的机制┌─ PURE ─────────────────────────────────────────────────────┐ │ 仅 Foundation。无 AppKit、无时钟、无网络、无文件系统。 │ │ 一切环境事实都是注入的参数。 │ │ ⇒ 由 harness 原样编译发布源码因此永不漂移。 │ │ SearchRelevance · CalcEngine · ClipboardStore · │ │ PaletteRowIndex · WindowPlacementEngine · ... │ ├───────────────────────────┬─────────────────────────────────┤ ┌─ EFFECT ──────────────────▼─────────────────────────────────┐ │ 所有平台 I/O每个功能一个文件夹。 │ │ AppIndex · AXWindowAccess · HotKeyCenter · CalendarStore · │ │ SnippetKeywordListener · Paster · ... │ ├───────────────────────────┬─────────────────────────────────┤ ┌─ OBSERVABLE STATE ────────▼─────────────────────────────────┐ │ 39 个 MainActor Observable 的 store/session/index/State │ ├───────────────────────────┬─────────────────────────────────┤ ┌─ VIEW ────────────────────▼─────────────────────────────────┐ │ SwiftUI 屏幕、视图与各功能的 coordinator——声明式、薄、无策略 │ └──────────────────────────────────────────────────────────────┘对应到文件夹树就是每个功能的Model/、Service/、UI/加Settings/Observable 状态归属于拥有它的那一层。这条规则是可检查的Model/下的文件不得 import AppKit 或 SwiftUI因为 harness 编译的是发布源码而非副本——harness 编译失败就是“决策泄漏进了副作用层或副作用泄漏进了决策层”的信号。单一拥有者核心Single-owner coreAppCore.sharedApp/AppCore.swift是MainActor单例拥有应用里所有长生命周期对象各 storeAppIndex、ClipboardStore、SnippetsStore、QuicklinkStore等、管理器与时钟ClipboardManager、HotKeyManager、HyperKeyTap等、共享状态、20 个功能 coordinator 与全部窗口控制器。AppDelegate.applicationDidFinishLaunching只做一件事——调用AppCore.shared.start()。这是唯一的装配点start()读起来就是整个应用的启动序列。两条硬性规则功能动作必须落在该功能的 coordinator 上视图永远不得绕过 coordinator 直接改 storeAppCore只持有把热键连接到 coordinator 的闭包装配。视图通过Environment注入AppCore并把它当作 coordinators 的定位器core.quicklinkCoordinator.deleteQuicklink(…)是标准形态。新的长生命周期状态属于AppCore在start()中接线不得创建并行的单例。观察模型与并发39 个类型是MainActor Observable完全不用ObservableObject或Published视图通过Environment而非EnvironmentObject读取状态。目标以Swift 6 语言模式编译数据竞争是硬错误重型与 IO 型工作应用扫描、图片解码、设置面板扫描、Shell 执行、汇率拉取通过Task.detached驱动的nonisolated static函数推离主线程——全应用刻意只有一个 actor。启动器内部模糊匹配、评分表与学习排序README.md 只提了一句“fuzzy-search and launch anything”而 docs/features/launcher.md 把这一句展开成了一个精巧的排序系统。AppIndex.scan()在后台枚举用户的搜索范围默认覆盖/Applications、/System/Applications及其Utilities目录、~/Applications等按 bundle ID 去重最早的范围获胜。搜索范围是用户可在设置 → 应用 → 搜索范围编辑的持久化为AppSettings.searchScopes。评分模型分两层total quality usage quality cell(role, tier) shape shape ∈ [0, 99] usage LauncherRankingStore.usage(…) usage ∈ [0, 2_999]其中cell(role, tier)是一张按“角色 × 匹配层级”排布的常数表例如userAlias · exact 7_000name · exact 6_500name · subsequence 1_000。文档强调“表里每个间隙都以‘学习到的选择次数’来计”——一个 gap 意味着较弱匹配需要被用户反复选中那么多次才能反超这是学习永远无法跨越的防火墙。三条不等式P1/P2/P3在Tests/fuzz-test.swift中对发布常量断言其中P1 是唯一的绝对保证一个精确输入的显示名或用户别名在没有任何学习量的情况下永远压过任意使用量的弱匹配。启动器还内置了 学习排序frecency频率 衰减的新近度数据存于本地launcher-ranking.json可逐项重置或在通用设置中全部清除。打开列表刻意保持字母序——frecency 曾在此试验后被回退因为“学习过的应用浮到顶部、字母序在其下继续”会让列表看起来像被两种原则打乱。热键引擎纯 Carbon 注册 双击修饰键 Hyper Key热键子系统docs/features/hotkeys.md是完全自研、零依赖的。HotKeyManager拥有四个组件KeyShortcutCarbon keycode 修饰键的 Sendable 模型用UCKeyTranslate生成布局感知的键帽字形、HotKeyBinding动作真正绑定的东西.combo或.doubleTap、HotKeyCenterCarbonRegisterEventHotKey层可暂停、DoubleTapModifier/Detector/Monitor双击修饰键栈。三个值得注意的机制持久化格式绑定以 JSON 字符串存于hotkey.action的 UserDefaults 键下HotKeyAction.defaultsKey是唯一计算键名的地方同时兼任HotKeyCenter的注册 id二者不会漂移。例如hotkey.command:clipboard-history。双击修饰键任何动作都可以绑定到“双击单独的修饰键”⌃/⌥/⇧/⌘。DoubleTapDetector是纯 Foundation、时钟注入的识别器由Tests/hotkey-test.swift驱动它在第二次释放时触发而非第二次按下这样动作运行时修饰键已经抬起面板不会带着幽灵 ⌘ 打开。双击需要 Accessibility 授权但从不主动索要。Hyper KeyHyperKeyTap用 modifyingCGEventTap把一颗物理键Caps Lock 或右侧修饰键变成全局的 ⌃⌥(⇧)⌘ 组合键。Caps Lock 必须在源头停止当 Caps Lock——CapsLockRemap安装 IOKitUserKeyMapping把它重映射为 F18与hidutil同机制随后由 tap 拦截。任何超集组合在键帽上统一渲染为单个✦符号。剪贴板历史SQLite FTS5唯一的默认开启功能剪贴板子系统docs/features/clipboard.md是 Tinycast 最“重”的模块之一。它基于 SQLiteclipboard.sqlite3存行 三元组 FTS5 索引图片 blob 以松散 PNG 文件存放全部位于~/Library/Application Support/bundle-id/。最新的 1000 行镜像进可观察的items窗口FTS 搜索可达更早的行。轮询式捕获ClipboardManager以 0.5 秒Timer监视NSPasteboard.general.changeCountTinycast 自己的每次写入都会盖上私有internalType标记轮询器跳过携带标记的内容从而避免“自己粘贴自己”的循环。文件 URL 先于文本读取——因为 Finder 会在public.file-url旁放上文件的显示名文本优先会让IMG_1234.png被记成一段散文。文件以引用而非副本记录行指向文件所在处绝不复制因此owns()所有权规则保证了清理永远不会删到 Tinycast 没写过的文件。其他亮点图片与 PDF 文本搜索默认关闭开关按机器保存且排除在设置备份之外识别运行在独立的ClipboardTextHelper子进程中每个条目一个、用后即弃Vision 与 PDFKit 的内存分配随进程退出而释放从不堆积在主应用内。彩色识别ColorValue是剪贴板色板与启动器色卡共用的唯一解析器接受 CSS 拼写四种 hex 长度 rgb()/hsl()及其 alpha 形式存储 sRGB 分量颜色被拒绝而不是近似因为一个错误的色块比没有更糟。粘贴两种风味public.file-url让 Finder/Mail 收到文件本身.string携带路径刻意不用 Finder 选择的名字——因为文本字段或终端几乎总是要路径名字可从路径还原而路径无法从名字还原。Raycast 扩展运行时无 Node 的 JavaScriptCore 渲染管线这是 Tinycast 最具技术野心的部分docs/features/extensions.md运行真实的 Raycast 扩展——同一个package.json与 Raycast 自己产出的预构建 CommonJS bundle——原生渲染进命令面板。没有 Electron、没有浏览器、没有 Node.js。工作方式一个 Raycast 扩展命令是一个预构建的 CommonJS 文件保持react、react/jsx-runtime、raycast/api与 Node 内建模块 external。Tinycast 供应这些依赖、运行 bundle、渲染它产出的 React 树command.js (esbuild 输出, 依赖内联) │ require(raycast/api), require(react), require(node:fs), … ▼ RaycastRuntime.generated.js ← 在 app bundle 内; React 19 react-reconciler │ raycast/api shim Node/web polyfills │ 把渲染树输出为 JSON ▲ dispatch(handlerId, args) ▼ │ ExtensionRuntime (JavaScriptCore, 私有串行队列) │ RenderTree / RenderValue (Sendable) ▲ host calls ▼ │ ExtensionManager (MainActor) ── ExtensionHostBridge ── Clipboard / storage / toasts / fetch / exec │ ▼ ExtensionScreen → Features/Extensions/* → 命令面板为什么选 JavaScriptCore因为它随 macOS 自带嵌入成本零二进制体积、无需 vendored C。QuickJS 要增加约 1 MB 外加构建系统绕路而这里的工作量并不在解释器而在raycast/apishim 与 Node 表面层——两者换引擎都一样。Tinycast/Resources/RaycastRuntime.generated.js约 200 KB 压缩由Scripts/raycast-runtime/build.mjs生成并提交与EmojiData.generated.swift相同的模式构建 Tinycast 永远不需要 Node。运行时源码位于 Scripts/raycast-runtime/ 下包含src/index.jsSwift 调用的__tinycast对象、src/reconciler.js把 React 提交进 JSON 树的 host config、src/api/components.js全部raycast/api组件与src/node-shims.jspath/fs/os/child_process/crypto/zlib 等 Node shim。关键设计决策同一时刻只运行一个命令且每个命令拥有独立的JSContext。启动新命令会停止上一个并整个丢弃其 contextExtensionRuntime.shutdown()。这是从 bug 中学来的教训定时器是全局的React 的调度器通过setTimeout驱动每次 commit因此在 teardown 时“清理”扩展残留的定时器会连带取消调度器的定时器导致isMessageLoopRunning被锁死、之后每一个会话都永远卡在 “Starting…”。丢弃 context 一劳永逸。两种 host call异步invoke用于需要主 actor 的一切剪贴板、toast、窗口控制、fetch、exec、OAuth阻塞invokeSync仅用于同步 Node shimfs.readFileSync、execSync、createHash、gunzipSync——安全是因为 Swift 完全在 JS 队列上服务它们不碰主 actor不会死锁。ExtensionRuntime的unchecked Sendable是承重设计所有JSContext/JSValue触碰都在其私有串行队列上只有纯Sendable值RenderValue、RenderTree、JSON 字符串进出边界。关闭即关闭extensionsEnabled是 opt-in 的开启时会先确认——这是运行第三方代码的同意。关闭时停止运行中的命令、丢弃 JS context、清空已安装集合与启动器行refresh()在关闭时提前返回不扫描、不持有任何东西。支持的表面组件方面支持List、Grid、Detail、Form含 TextField/PasswordField/TextArea/Checkbox/Dropdown/TagPicker/DatePicker/FilePicker、ActionPanel含 Section/Submenu与全部 Action 便捷变体API 支持Clipboard、LocalStorage、Cache、showToast、showHUD、confirmAlert、getSelectedText、useNavigation、OAuthPKCEtoken 存于登录钥匙串、LaunchType等Node 内建覆盖path、fs、os、child_process、crypto、zlib、http/https、stream、url、buffer、events等。文档也诚实列出了不支持项menu-bar命令、依赖 Raycast PKCE 代理的 OAuth 流程、AI/BrowserExtension/WindowManagement服务、WebSocket、流式spawn、net/tls等。文档、测试与贡献约定README 把仓库的文档体系组织得很清晰构建与发布工作流见 docs/development.md其余一切架构、工程标准、设计系统、每个功能一份文档由 docs/README.md 索引。每个功能文档必须以## Invariants开头改动该区域前先读它。测试方面Tests/ 下是独立 harness——它们不在 Xcode 工程里而是由 Scripts/run-tests.sh 直接编译发布源码这正是“Model 层必须纯净”这一规则可执行的原因。性能基准也有明确预算例如fuzz-test.swift会编译真实的SearchRelevance.swift断言评分表的约束不等式。贡献规则在 README 中有醒目要求写代码前必须先开 issue 并取得一致意见强制要求——不关闭approved标记 issue 的 PR 会被自动关闭功能集是刻意封闭的“别的启动器有”不是理由。每个 PR 都要接受内存预算约束视觉变更需要前后对比视频模板见 CONTRIBUTING.md安全漏洞走 SECURITY.md。总结从 README.md 出发Tinycast 是一个技术密度极高的 macOS 原生启动器100 MB 内存预算内的全栈生产力工具、零第三方依赖的工程纪律、Foundation-only 与 effect 严格分层的架构、把 Raycast 扩展跑进 JavaScriptCore 并渲染为原生 SwiftUI 的运行时。它既适合普通用户作为 Raycast 的开源替代品brew 一行安装、唯一权限要求、功能默认关闭的设计哲学也适合开发者研究“如何在 macOS 上零依赖地构建一个自带 JS 引擎的生产力应用”。后续深入请从 docs/architecture.md 开始按 docs/README.md 的索引逐功能阅读。【免费下载链接】tinycastTinycast — a tiny, fully native macOS launcher, hotkeys, and clipboard history.项目地址: https://gitcode.com/GitHub_Trending/ti/tinycast创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Tinycast：原生 macOS 启动器的技术解析与实战指南——零依赖、SwiftUI 渲染 Raycast 扩展
Tinycast原生 macOS 启动器的技术解析与实战指南——零依赖、SwiftUI 渲染 Raycast 扩展【免费下载链接】tinycastTinycast — a tiny, fully native macOS launcher, hotkeys, and clipboard history.项目地址: https://gitcode.com/GitHub_Trending/ti/tinycastTinycast 是一个完全原生的 macOS 启动器launcher以“一个全局热键调起你整天要用的所有东西”为设计目标并将常驻内存控制在 100 MB 以下。它由 SwiftUI 与 AppKit 编写、零第三方依赖、无 Electron、无遥测同时能原生运行真实的 Raycast 扩展并以 SwiftUI 渲染。本文以仓库 README.md 为骨架结合 docs/architecture.md、docs/development.md 以及各功能模块文档完整讲解它的功能清单、安装与权限配置、使用入门、从源码构建的流程以及其分层架构与核心子系统启动器、命令面板、热键、剪贴板、Raycast 扩展运行时的底层实现原理。项目概览一个 100 MB 内存预算内的全栈生产力工具Tinycast 的定位在 README.md 第一段就写得很明确tiny, fully native macOS launcher——小巧、完全原生的 macOS 启动器One hotkey, everything you reach for all day, under 100 MB of RAM一个热键搞定你整天要伸手去拿的一切内存占用低于 100 MB。技术选型上它刻意与常见竞品保持距离SwiftUI AppKit零第三方依赖没有 Electron没有遥测。同时它并不封闭——可以运行你已经安装的真实 Raycast 扩展并把它们的界面渲染成原生 SwiftUI而不是塞进一个浏览器内核。项目免费、开源采用 AGPL-3.0 许可证。从仓库结构看docs/README.md 提供了完整文档索引这是一个组织极其严谨的代码库docs/下按“每个文档一个职责”的原则分别覆盖架构architecture.md、工程标准standards.md、测试testing.md、开发development.md、发布release.md、签名signing.md与设计系统ui.md每个功能模块还有一份独立的 feature 文档且都要求以## Invariants不变量开头。功能矩阵启动器之外的一整个工具箱README.md 的 Features 章节罗列了 18 项核心能力每一项在Tinycast/Features/下都有对应的Model/、Service/、UI/、Settings/源码目录与docs/features/文档App launcher应用启动器——模糊搜索并启动任何应用、固定收藏、查看运行状态、退出单个应用或一键退出全部应用。Global hotkey全局热键——一个快捷键从任何地方调起命令面板。Per-app hotkeys按应用热键——为某个应用绑定一个按键按一下切换聚焦/隐藏。Search Files文件搜索——从你指定的文件夹中打开文件与文件夹底层走 Spotlight不维护自己的索引。Dictionary词典——通过 Define Word 命令查词或从启动器的 fallback 入口查询当前输入内容读取 Mac 自带的词典。Clipboard history剪贴板历史——文本与图片可搜索可粘贴回你正在使用的应用。Calculator计算器——在面板内直接完成数学计算、单位换算、实时货币与加密货币换算。Quicklinks快捷链接——把 URL、搜索、文件或 deeplink 变成一个命令支持为输入、剪贴板或日期占位。Apple Shortcuts快捷指令——搜索并运行你在“快捷指令”App 里构建的快捷指令支持别名与全局热键。Snippets文本片段——可复用的 Markdown 模板支持动态占位符、参数、嵌套引用与可选的关键词展开。Custom commands自定义命令——通过模糊搜索或专属全局热键运行命名 Shell 命令。Window management窗口管理——34 个 Rectangle 风格动作半屏、四分之一、三分之一、缩放、微调、跨显示器移动、全屏与 Spaces。System actions系统动作——锁定、睡眠、重启、清空废纸篓、切换外观、蓝牙、静音、隐藏文件等等。Calendar and meetings日历与会议——下一个会议显示在空白面板与菜单栏中一键加入或让它自动加入。Notes笔记——在一个悬浮编辑器中管理无限制的纯 Markdown 文件可从面板搜索并即写即渲染。Emoji picker表情符号选择器——一个可搜索的表情网格一次按键即可唤出。AI chatAI 对话——使用自己的 API Key 或已安装的 AI 账号在面板内对话。与所有 AI 功能一样默认关闭。Quick Actions快捷动作——在任何应用中修复语法、改写、翻译或总结选中的文本。Raycast extensionsRaycast 扩展——原生运行你已经拥有的扩展渲染为 SwiftUI。Backup and import备份与导入——把设置导出到文件或从 Raycast 导入你的配置。值得注意的是README 中强调Clipboard history是唯一默认开启的功能开关——这一点在 docs/features/clipboard.md 的 Invariants 中被证实clipboardEnabledships on且“该键缺失”必须优先于存储的false关闭即完全关闭轮询器停止、SQLite 文件关闭、启动器命令与快捷键消失、Tab 跳过该屏幕。安装指南Homebrew Tap 与 DMG 两种途径Tinycast 的官方安装路径是 Homebrew。按照 README.md 的 Install 章节第一步添加第三方 tapmacOS 对第三方 tap 有信任要求brew trust --tap abue-ammar/tinycast # 第三方 tap 必需 brew tap abue-ammar/tinycast然后根据你的 Mac 类型选择对应的安装命令你的 Mac安装命令Apple siliconmacOS 26 或更新brew install --cask tinycastIntelmacOS 26brew install --cask tinycast-universal不确定自己的芯片苹果菜单 → 关于本机。Homebrew 也会自行校验并拒绝安装不匹配的版本。需要尝鲜版可以执行brew install --cask tinycastbeta它会在稳定版旁边安装Tinycast Beta.app拥有自己独立的设置与权限仅限 Apple siliconmacOS 26。两个关键细节Quarantine 标志Homebrew 在每次安装与更新时都会清除 macOS 的 quarantine 标志因此正常安装后无需额外操作。DMG 方式如果从 Releases 下载 DMG由于 Tinycast 是自签名应用需要手动清除一次隔离标志xattr -dr com.apple.quarantine /Applications/Tinycast.app权限说明Accessibility 是唯一必需的授权Tinycast 对系统权限极其克制——Accessibility辅助功能是它唯一要求的权限且只在特定场景下需要当 Tinycast 需要向其他应用粘贴或展开文本时这也是 Snippets 关键词展开唯一需要的权限。触发时机与授予方式是“首次使用即提示”当你第一次使用需要该权限的功能时Tinycast 会弹出提示然后在系统设置 → 隐私与安全性 → 辅助功能中授予即可。需要强调的是Snippets 功能默认是禁用的且按键匹配全部在本地完成从不存储、从不外发。从 docs/features/hotkeys.md 可以进一步看到这个权限在底层的多处应用DoubleTapMonitor双击修饰键、HyperKeyTapHyper 键、CommandEscapeTap⌘⎋ 拦截都是CGEventTap都依赖 Accessibility 授权其中DoubleTapMonitor采用.tailAppendEventTapHyperKeyTap采用 modifying tap两者都“只在需要时才安装”并从不主动弹窗索要权限——由一秒一次的健康检查定时器在授权落地瞬间自动安装。使用入门五分钟上手README.md 的 Using it 章节给出了最简洁的启动路径打开设置 → 通用录制一个全局快捷键用于调起 Tinycast。在任何地方按下它 → 命令面板浮现。输入以过滤↵启动。Tab在 Apps 与 Clipboard 之间切换↑/↓移动选择Esc关闭。设置 → 快捷键——搜索某个应用或自定义命令并录制全局快捷键。设置 → Snippets——启用该功能然后创建带展开关键词的模板。这五步背后是一个精心设计的命令面板docs/features/palette.md它是无边框悬浮NSPanel由PaletteWindowController独占持有窗口 framehosting view 设置sizingOptions []SwiftUI 永不驱动窗口尺寸面板的扁平selection索引必须与可见行顺序完全一致这个映射由Features/PaletteRowIndex.swift承担并保持Foundation-only 纯函数因此Tests/palette-selection-test.swift直接编译发布源码来验证。面板的导航模型也很有设计感由“召唤”决定屏幕如何安置而不是由模式决定。PaletteCoordinator.navigate(to:)是唯一规则——面板已打开时进入某个屏幕是“导航”当前屏幕被压栈成为返回步面板隐藏时进入某个屏幕是“召唤”新屏幕成为根。Tab 键在三个读者直接打开的界面间循环launcher → AI chat → clipboard → launcher。从源码构建工具链、开发通道与生成数据README.md 将构建指南指向 docs/development.md那里给出了完整的本地开发闭环环境要求macOS 26 或更新Liquid GlassXcode 26提供 SwiftUI macro 插件与 SDK[XcodeGen]生成工程文件以及用于 lint 的brew install swiftlintNode仅用于数据生成脚本与run-tests.sh驱动的两个 stub 服务器——构建应用本身完全不需要 Node首次设置创建一次Tinycast Self-Signed代码签名身份——构建用它签名从而保证每次重建后 macOS 不会忘记 Accessibility 授权详见 docs/signing.md §1。构建与运行open Tinycast.xcodeproj # 然后 ⌘R或命令行方式xcodebuild -project Tinycast.xcodeproj -scheme Tinycast -configuration Debug buildTinycast.xcodeproj是提交进仓库、由project.yml通过 XcodeGen 生成的——修改project.yml中的工程设置后运行xcodegen generate并提交结果。仓库没有Package.swift且严禁使用Bundle.module。Dev 通道与正式版完全隔离Debug 构建是独立通道Tinycast Dev.appbundle idcom.tinycast.app.dev。所有持久化数据都按 bundle id 隔离——~/Library/Preferences/id.plist设置与热键绑定、~/Library/Application Support/id/引导标记、笔记、片段、快捷链接、剪贴板历史、计算器历史、启动排序与常用表情、~/Library/Caches/id/汇率、更新检查、暂存下载、SMAppService登录项与 TCC 授权——因此本地构建既读不到也不会覆盖已安装应用的状态两者可以并行运行。值得注意的设计原则只有可重新获取的东西才有资格进 Caches其余一律进 Application Support——因为~/Library/Caches不在 Time Machine 备份范围内且系统在磁盘紧张时会不经通知直接回收。生成数据三个 Swift 文件由脚本生成、禁止手改每个脚本都会下载数据源因此需联网执行后提交结果node Scripts/gen-emoji.js # - Tinycast/Features/Emoji/Model/EmojiData.generated.swift node Scripts/gen-currencies.js # - Tinycast/Features/Calculator/Model/CurrencyData.generated.swift node Scripts/gen-countries.js # - Tinycast/Features/Calculator/Model/CountryZoneData.generated.swiftgen-currencies.js很有意思它把汇率接口自身的报价列表、Unicode CLDR 的货币显示名与 CLDR 的补充货币数据哪些代码还在流通按 ISO 代码做三方 join从而保证货币表与实时汇率源永不脱节。架构纵深四层分层与单一拥有者核心要真正理解 Tinycastdocs/architecture.md 是必读文档。它的架构核心可以概括为两条主线四层分层纯逻辑与副作用严格分离每个成熟的子系统都收敛为四个层次且Tests/下的独立 harness 是让它们保持分离的机制┌─ PURE ─────────────────────────────────────────────────────┐ │ 仅 Foundation。无 AppKit、无时钟、无网络、无文件系统。 │ │ 一切环境事实都是注入的参数。 │ │ ⇒ 由 harness 原样编译发布源码因此永不漂移。 │ │ SearchRelevance · CalcEngine · ClipboardStore · │ │ PaletteRowIndex · WindowPlacementEngine · ... │ ├───────────────────────────┬─────────────────────────────────┤ ┌─ EFFECT ──────────────────▼─────────────────────────────────┐ │ 所有平台 I/O每个功能一个文件夹。 │ │ AppIndex · AXWindowAccess · HotKeyCenter · CalendarStore · │ │ SnippetKeywordListener · Paster · ... │ ├───────────────────────────┬─────────────────────────────────┤ ┌─ OBSERVABLE STATE ────────▼─────────────────────────────────┐ │ 39 个 MainActor Observable 的 store/session/index/State │ ├───────────────────────────┬─────────────────────────────────┤ ┌─ VIEW ────────────────────▼─────────────────────────────────┐ │ SwiftUI 屏幕、视图与各功能的 coordinator——声明式、薄、无策略 │ └──────────────────────────────────────────────────────────────┘对应到文件夹树就是每个功能的Model/、Service/、UI/加Settings/Observable 状态归属于拥有它的那一层。这条规则是可检查的Model/下的文件不得 import AppKit 或 SwiftUI因为 harness 编译的是发布源码而非副本——harness 编译失败就是“决策泄漏进了副作用层或副作用泄漏进了决策层”的信号。单一拥有者核心Single-owner coreAppCore.sharedApp/AppCore.swift是MainActor单例拥有应用里所有长生命周期对象各 storeAppIndex、ClipboardStore、SnippetsStore、QuicklinkStore等、管理器与时钟ClipboardManager、HotKeyManager、HyperKeyTap等、共享状态、20 个功能 coordinator 与全部窗口控制器。AppDelegate.applicationDidFinishLaunching只做一件事——调用AppCore.shared.start()。这是唯一的装配点start()读起来就是整个应用的启动序列。两条硬性规则功能动作必须落在该功能的 coordinator 上视图永远不得绕过 coordinator 直接改 storeAppCore只持有把热键连接到 coordinator 的闭包装配。视图通过Environment注入AppCore并把它当作 coordinators 的定位器core.quicklinkCoordinator.deleteQuicklink(…)是标准形态。新的长生命周期状态属于AppCore在start()中接线不得创建并行的单例。观察模型与并发39 个类型是MainActor Observable完全不用ObservableObject或Published视图通过Environment而非EnvironmentObject读取状态。目标以Swift 6 语言模式编译数据竞争是硬错误重型与 IO 型工作应用扫描、图片解码、设置面板扫描、Shell 执行、汇率拉取通过Task.detached驱动的nonisolated static函数推离主线程——全应用刻意只有一个 actor。启动器内部模糊匹配、评分表与学习排序README.md 只提了一句“fuzzy-search and launch anything”而 docs/features/launcher.md 把这一句展开成了一个精巧的排序系统。AppIndex.scan()在后台枚举用户的搜索范围默认覆盖/Applications、/System/Applications及其Utilities目录、~/Applications等按 bundle ID 去重最早的范围获胜。搜索范围是用户可在设置 → 应用 → 搜索范围编辑的持久化为AppSettings.searchScopes。评分模型分两层total quality usage quality cell(role, tier) shape shape ∈ [0, 99] usage LauncherRankingStore.usage(…) usage ∈ [0, 2_999]其中cell(role, tier)是一张按“角色 × 匹配层级”排布的常数表例如userAlias · exact 7_000name · exact 6_500name · subsequence 1_000。文档强调“表里每个间隙都以‘学习到的选择次数’来计”——一个 gap 意味着较弱匹配需要被用户反复选中那么多次才能反超这是学习永远无法跨越的防火墙。三条不等式P1/P2/P3在Tests/fuzz-test.swift中对发布常量断言其中P1 是唯一的绝对保证一个精确输入的显示名或用户别名在没有任何学习量的情况下永远压过任意使用量的弱匹配。启动器还内置了 学习排序frecency频率 衰减的新近度数据存于本地launcher-ranking.json可逐项重置或在通用设置中全部清除。打开列表刻意保持字母序——frecency 曾在此试验后被回退因为“学习过的应用浮到顶部、字母序在其下继续”会让列表看起来像被两种原则打乱。热键引擎纯 Carbon 注册 双击修饰键 Hyper Key热键子系统docs/features/hotkeys.md是完全自研、零依赖的。HotKeyManager拥有四个组件KeyShortcutCarbon keycode 修饰键的 Sendable 模型用UCKeyTranslate生成布局感知的键帽字形、HotKeyBinding动作真正绑定的东西.combo或.doubleTap、HotKeyCenterCarbonRegisterEventHotKey层可暂停、DoubleTapModifier/Detector/Monitor双击修饰键栈。三个值得注意的机制持久化格式绑定以 JSON 字符串存于hotkey.action的 UserDefaults 键下HotKeyAction.defaultsKey是唯一计算键名的地方同时兼任HotKeyCenter的注册 id二者不会漂移。例如hotkey.command:clipboard-history。双击修饰键任何动作都可以绑定到“双击单独的修饰键”⌃/⌥/⇧/⌘。DoubleTapDetector是纯 Foundation、时钟注入的识别器由Tests/hotkey-test.swift驱动它在第二次释放时触发而非第二次按下这样动作运行时修饰键已经抬起面板不会带着幽灵 ⌘ 打开。双击需要 Accessibility 授权但从不主动索要。Hyper KeyHyperKeyTap用 modifyingCGEventTap把一颗物理键Caps Lock 或右侧修饰键变成全局的 ⌃⌥(⇧)⌘ 组合键。Caps Lock 必须在源头停止当 Caps Lock——CapsLockRemap安装 IOKitUserKeyMapping把它重映射为 F18与hidutil同机制随后由 tap 拦截。任何超集组合在键帽上统一渲染为单个✦符号。剪贴板历史SQLite FTS5唯一的默认开启功能剪贴板子系统docs/features/clipboard.md是 Tinycast 最“重”的模块之一。它基于 SQLiteclipboard.sqlite3存行 三元组 FTS5 索引图片 blob 以松散 PNG 文件存放全部位于~/Library/Application Support/bundle-id/。最新的 1000 行镜像进可观察的items窗口FTS 搜索可达更早的行。轮询式捕获ClipboardManager以 0.5 秒Timer监视NSPasteboard.general.changeCountTinycast 自己的每次写入都会盖上私有internalType标记轮询器跳过携带标记的内容从而避免“自己粘贴自己”的循环。文件 URL 先于文本读取——因为 Finder 会在public.file-url旁放上文件的显示名文本优先会让IMG_1234.png被记成一段散文。文件以引用而非副本记录行指向文件所在处绝不复制因此owns()所有权规则保证了清理永远不会删到 Tinycast 没写过的文件。其他亮点图片与 PDF 文本搜索默认关闭开关按机器保存且排除在设置备份之外识别运行在独立的ClipboardTextHelper子进程中每个条目一个、用后即弃Vision 与 PDFKit 的内存分配随进程退出而释放从不堆积在主应用内。彩色识别ColorValue是剪贴板色板与启动器色卡共用的唯一解析器接受 CSS 拼写四种 hex 长度 rgb()/hsl()及其 alpha 形式存储 sRGB 分量颜色被拒绝而不是近似因为一个错误的色块比没有更糟。粘贴两种风味public.file-url让 Finder/Mail 收到文件本身.string携带路径刻意不用 Finder 选择的名字——因为文本字段或终端几乎总是要路径名字可从路径还原而路径无法从名字还原。Raycast 扩展运行时无 Node 的 JavaScriptCore 渲染管线这是 Tinycast 最具技术野心的部分docs/features/extensions.md运行真实的 Raycast 扩展——同一个package.json与 Raycast 自己产出的预构建 CommonJS bundle——原生渲染进命令面板。没有 Electron、没有浏览器、没有 Node.js。工作方式一个 Raycast 扩展命令是一个预构建的 CommonJS 文件保持react、react/jsx-runtime、raycast/api与 Node 内建模块 external。Tinycast 供应这些依赖、运行 bundle、渲染它产出的 React 树command.js (esbuild 输出, 依赖内联) │ require(raycast/api), require(react), require(node:fs), … ▼ RaycastRuntime.generated.js ← 在 app bundle 内; React 19 react-reconciler │ raycast/api shim Node/web polyfills │ 把渲染树输出为 JSON ▲ dispatch(handlerId, args) ▼ │ ExtensionRuntime (JavaScriptCore, 私有串行队列) │ RenderTree / RenderValue (Sendable) ▲ host calls ▼ │ ExtensionManager (MainActor) ── ExtensionHostBridge ── Clipboard / storage / toasts / fetch / exec │ ▼ ExtensionScreen → Features/Extensions/* → 命令面板为什么选 JavaScriptCore因为它随 macOS 自带嵌入成本零二进制体积、无需 vendored C。QuickJS 要增加约 1 MB 外加构建系统绕路而这里的工作量并不在解释器而在raycast/apishim 与 Node 表面层——两者换引擎都一样。Tinycast/Resources/RaycastRuntime.generated.js约 200 KB 压缩由Scripts/raycast-runtime/build.mjs生成并提交与EmojiData.generated.swift相同的模式构建 Tinycast 永远不需要 Node。运行时源码位于 Scripts/raycast-runtime/ 下包含src/index.jsSwift 调用的__tinycast对象、src/reconciler.js把 React 提交进 JSON 树的 host config、src/api/components.js全部raycast/api组件与src/node-shims.jspath/fs/os/child_process/crypto/zlib 等 Node shim。关键设计决策同一时刻只运行一个命令且每个命令拥有独立的JSContext。启动新命令会停止上一个并整个丢弃其 contextExtensionRuntime.shutdown()。这是从 bug 中学来的教训定时器是全局的React 的调度器通过setTimeout驱动每次 commit因此在 teardown 时“清理”扩展残留的定时器会连带取消调度器的定时器导致isMessageLoopRunning被锁死、之后每一个会话都永远卡在 “Starting…”。丢弃 context 一劳永逸。两种 host call异步invoke用于需要主 actor 的一切剪贴板、toast、窗口控制、fetch、exec、OAuth阻塞invokeSync仅用于同步 Node shimfs.readFileSync、execSync、createHash、gunzipSync——安全是因为 Swift 完全在 JS 队列上服务它们不碰主 actor不会死锁。ExtensionRuntime的unchecked Sendable是承重设计所有JSContext/JSValue触碰都在其私有串行队列上只有纯Sendable值RenderValue、RenderTree、JSON 字符串进出边界。关闭即关闭extensionsEnabled是 opt-in 的开启时会先确认——这是运行第三方代码的同意。关闭时停止运行中的命令、丢弃 JS context、清空已安装集合与启动器行refresh()在关闭时提前返回不扫描、不持有任何东西。支持的表面组件方面支持List、Grid、Detail、Form含 TextField/PasswordField/TextArea/Checkbox/Dropdown/TagPicker/DatePicker/FilePicker、ActionPanel含 Section/Submenu与全部 Action 便捷变体API 支持Clipboard、LocalStorage、Cache、showToast、showHUD、confirmAlert、getSelectedText、useNavigation、OAuthPKCEtoken 存于登录钥匙串、LaunchType等Node 内建覆盖path、fs、os、child_process、crypto、zlib、http/https、stream、url、buffer、events等。文档也诚实列出了不支持项menu-bar命令、依赖 Raycast PKCE 代理的 OAuth 流程、AI/BrowserExtension/WindowManagement服务、WebSocket、流式spawn、net/tls等。文档、测试与贡献约定README 把仓库的文档体系组织得很清晰构建与发布工作流见 docs/development.md其余一切架构、工程标准、设计系统、每个功能一份文档由 docs/README.md 索引。每个功能文档必须以## Invariants开头改动该区域前先读它。测试方面Tests/ 下是独立 harness——它们不在 Xcode 工程里而是由 Scripts/run-tests.sh 直接编译发布源码这正是“Model 层必须纯净”这一规则可执行的原因。性能基准也有明确预算例如fuzz-test.swift会编译真实的SearchRelevance.swift断言评分表的约束不等式。贡献规则在 README 中有醒目要求写代码前必须先开 issue 并取得一致意见强制要求——不关闭approved标记 issue 的 PR 会被自动关闭功能集是刻意封闭的“别的启动器有”不是理由。每个 PR 都要接受内存预算约束视觉变更需要前后对比视频模板见 CONTRIBUTING.md安全漏洞走 SECURITY.md。总结从 README.md 出发Tinycast 是一个技术密度极高的 macOS 原生启动器100 MB 内存预算内的全栈生产力工具、零第三方依赖的工程纪律、Foundation-only 与 effect 严格分层的架构、把 Raycast 扩展跑进 JavaScriptCore 并渲染为原生 SwiftUI 的运行时。它既适合普通用户作为 Raycast 的开源替代品brew 一行安装、唯一权限要求、功能默认关闭的设计哲学也适合开发者研究“如何在 macOS 上零依赖地构建一个自带 JS 引擎的生产力应用”。后续深入请从 docs/architecture.md 开始按 docs/README.md 的索引逐功能阅读。【免费下载链接】tinycastTinycast — a tiny, fully native macOS launcher, hotkeys, and clipboard history.项目地址: https://gitcode.com/GitHub_Trending/ti/tinycast创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考