桌面应用【免费下载链接】tinycastTinycast — a tiny, fully native macOS launcher, hotkeys, and clipboard history.项目地址https://gitcode.com/GitHub_Trending/ti/tinycast点击查看免费下载Tinycast 是一个完全原生的 macOS 菜单栏启动器应用fuzzy 应用启动、全局/按应用热键、剪贴板历史、计算器、便签、snippets、quicklinks、窗口管理与 emoji 选择器并能在 JavaScriptCore 中原生运行 Raycast 扩展其工程规范文档描述了代码应该如何书写——它不是一份空泛的代码风格清单而是一份与代码库现状严格对齐的工程契约新代码读起来应当仿佛一直就在这里。本篇指南将逐节拆解这份规范为什么 Tinycast 坚持仅支持最新平台的 posture、特性如何按文件夹与 Model/Service/UI/Settings 分层、类型后缀各自意味着什么职责、Swift 6 并发模式下的具体写法、性能预算如何落实以及真正被检查的验收标准在哪里。读完你将能按照与 Tinycast 相同的工程纪律编写新功能代码。规范文档的定位guidance 与硬性约束的分界在深入具体规则之前先厘清docs/standards.md在整个文档体系中的位置。它在开篇就明确本文是guidance指导——它描述代码库已经长成的样子让新代码与之一致偏离它的好理由就是好理由a good reason to depart from it is a good reason真正被检查的是 testing.md 中的机械验收清单绝对不可违反的是 AGENTS.md 中的 Non-negotiables当本文档与代码不一致时代码更可能是对的文档可能已过期——此时应该修文档而不是改代码。这个分界至关重要规范是默认行为测试是机械门槛AGENTS.md 是底线三者职责不重叠。你在 AGENTS.md 可以看到这份底线的内容AppCore是唯一所有者、Features/*/Model/禁止导入 AppKit/SwiftUI、Swift 6 语言模式下数据竞争是硬错误、深色为基准、自绘对话框而不用NSAlert、网络请求走私有.ephemeralsession、扩展代码严格隔离在Features/Extensions/内、生成文件永不手改、DesignSystem/Scrolling/下两个文件禁止触碰等等。Posturelatest-only永远只支持最新平台规范的第一条姿态是latest-only仅最新。Tinycast 只面向一个 macOS当前稳定版、一套工具链Xcode 26、Swift 6 语言模式。为什么如此严格文档给出了核心论据兼容性地板不是一次性成本。每个 shim 都比需要它的平台活得久会被下一个看到它的特性复制粘贴并把一行调用变成没人敢删除的一层。Tinycast 没有外部 API、没有插件表面、只支持一个操作系统因此没有要与什么兼容的问题——这正是它能保持如此小巧的根本原因。项目删除过的版本门控代码体量上始终大于被门控的那个特性本身。这条姿态的具体形状以及它对应永远不做什么现代选择被拒绝的旧模式ObservationObservableObservableObject/Publishedasync/awaitcompletion handler、DispatchQueue跳转SMAppServiceLSSharedFileListshim结构化并发需要记得手动 cancel 的 detached 簿记当一个 API 出现后继者时迁移本身就是这次变更——而不是用一个保留旧写法的包装器。Carbon 的两处刻意能力缺口规范特别强调Carbon 框架有两处刻意的、非惯性的使用全局热键引擎使用RegisterEventHotKey——因为没有任何现代 API 能注册系统级组合键且CGEventTap无法看到单独的修饰键按下。见 HotKeyCenter.swift它维护entries/idToKey两张表通过RegisterEventHotKey注册、UnregisterEventHotKey注销并用一个 C 入口函数hotKeyCarbonEventHandler接收回调——该入口先把EventRef解码为纯值再跨入 actor 代码MainActor.assumeIsolated { center.handle(hotKeyID) }这正是每个原始 C 指针在跨入 actor 代码前都要被解码为纯值规则的实例。InputSourceSwitcher使用 HIToolbox 的 TIS APITISCopyCurrentKeyboardInputSource、TISCreateInputSourceList、TISSelectInputSource因为它们是枚举和选择键盘输入源的公开机制。见 InputSourceSwitcher.swift其中property(_:of:)用一个泛型辅助函数将TISGetInputSourceProperty返回的未类型化指针安全地转换为 Swift 值。架构与特性组织一特性一文件夹Model 层纯净规范的架构部分要求每个新特性满足一组规则完整架构细节见 architecture.md每个特性一个文件夹位于Tinycast/Features/Name/容纳该特性拥有的一切——模型、服务、视图和它自己的设置面板较大的特性拆分为Model/纯、Service/效果、UI/视图与特性协调器和Settings/面板小特性保持扁平如Onboarding/。当扁平文件夹不再可扫读时才拆分而非为了原则而拆分Model/禁止导入 AppKit 或 SwiftUI——时钟、文件系统、主目录、汇率表等一切环境事实都以参数注入。这是下文会展开的被强制执行的规则新的长生命周期状态属于AppCore在start()中接线不要创建第二个单例设置面板与所属特性同住只有无主的面板才住在Settings/Panes/共享视觉原语进DesignSystem/系统 shim 进Platform/两者都不得依赖任何特性。分层如何落到文件夹树architecture.md 用一个四层图描述了所有成熟子系统收敛到的同一结构文件夹树中对应为层文件夹职责规则PURE纯Model/只 import Foundation环境事实全部注入决定事情被 harness 逐字编译因此不可能漂移EFFECT效果Service/一切平台 I/OAXUIElement 调用、CGEventTap、NSWorkspace.open、URLSession、FileManager 遍历、CoreAudio 读取做事情每特性一个文件夹OBSERVABLE STATE归属各层39 个MainActor Observablestore/session/index/State 类型发布状态VIEW视图UI/Settings/SwiftUI 屏幕、视图、特性协调器——声明式、薄、不持有策略薄边界是可检查的这正是重点Model/下的文件不得 import AppKit/SwiftUI因为 harness 编译的是随仓库分发的原文件而不是拷贝——一个 harness 停止编译就是决策泄漏进效果层或效果泄漏进决策层的信号。CalcEngine.evaluate被传入一个已完成的CurrencyRates?而不是自己去取这正是它保持 Foundation-only 且可测的原因。Coordinator特性动作的唯一切面特性工作通过coordinator触达应用由AppCore调用、视图通过Environment访问。确认门confirmation gate位于 coordinator绝不位于 runner——这既让ShellCommandRunner和SystemActionRunner保持可被 harness 编译纯层又让你确定吗这一步无法被绕过。在 AppCore.swift 中可以看到这个模式的全貌二十多个 coordinator 全部以ObservationIgnored private(set) lazy var xxxCoordinator XxxCoordinator(...)的形式存在用[unowned self]捕获闭包。AppDelegate.applicationDidFinishLaunching只调用AppCore.shared.start()一件事——那是唯一的接线点start()读起来就是整个应用的启动序列。命名后缀说出类型是什么规范强调语义正确性优先——选择诚实地命名职责的后缀当现有后缀都不匹配时新增一行但绝不为凑表而重命名一个命名良好的类型。后缀含义Store拥有持久化状态并发布它RepositoryStore不隐含的文件语义——冲突检测、修订检查Coordinator特性的动作面由AppCore和 palette 调用Controller拥有一个 AppKit 窗口或表面Presenter拥有跨表面的呈现策略——一次一个、自动消失、淡出Manager拥有子系统的生命周期与策略从AppCore.start()启动Service其他类型调用的无状态能力Provider按需供给值不拥有关于其使用的策略Monitor观察外部流并报告变化不拥有策略Scanner读取文件系统以产生候选Runner按请求执行一次有副作用的操作Launcher特指NSWorkspace.open的包装器Center特指 Carbon 注册层Access一个表面的原始平台读取共享以避免 walker 之间意见不一Session一次进行中交互的瞬态状态State自身不持久化任何东西的共享可观察状态Catalog内置列表之上的纯静态命名空间Index可搜索的集合随输入变化而重建Engine纯求值器输入 → 输出Policy纯决策——无状态、无效果Manager是最值得三思的后缀它意味着生命周期策略对一个类型来说负担很重因此全项目只有两个ClipboardManager轮询并拥有捕获策略与粘贴侧握手和HotKeyManager持久化绑定驱动 Carbon 注册与双击分发。第三个 Manager 只有在它真的同时拥有两半时才成立——但先检查Store、Monitor或Coordinator是否描述得更准确因为通常三者之一是更好的答案。Registry和ViewModel已退役静态表是Catalog共享应用状态是State。SwiftUI 层的名字View、Screen、Card、Row、Sheet是另一套词汇表不受此表管辖。文件级规则每文件一个顶层类型以它命名View文件以视图命名命名空间enum以命名空间命名私有嵌套辅助类型的命名自由——此表只约束顶层类型*.generated.swift由Scripts/中的脚本生成永不手改。Swift 风格早期返回、薄视图、无处安放的 print规范要求与周边代码保持一致此外早期返回优于嵌套顶部的guard胜过包裹整个函数体的if默认let除非需要变更名字不缩写——index而非idx用命名常量或小类型解释字面量而不是写注释类型和函数保持单一职责——如果函数需要 section 注释它就该拆成两个函数视图保持声明式且薄。业务逻辑住在 model、store 或 coordinator 中——一个做决定的body是这个代码库最常见的恶化方式。优先组合而非超长body先抽子视图再抽ViewBuilder辅助错误通过DialogController用户必须确认的事或MessageHUDController瞬态的事呈现。绝不print绝不在用户关心的路径上静默try?诊断走Logger按子系统分类耗时走 Signposts.swift。两者不能互相替代删除死代码而不是注释掉或在后面留一条兼容路径。并发与生命周期Swift 6 语言模式下的房规Tinycast 在Swift 6 语言模式下构建数据竞争违规是硬错误而这正是设计而非障碍。核心规则MainActor是默认。几乎所有东西都有 UI 耦合或身份除非有理由否则假定主 actor重活或 IO 活显式地离主线程nonisolated static纯函数配合Task.detached——应用扫描、图片解码、设置面板扫描、shell 执行。保持这条边界不要引入自定义 actor架构上刻意只有一个 actor跨 actor 的模型类型是Sendable。只有在写明了理由时才用unchecked Sendable或nonisolated(unsafe)绝不图方便不新增MainActor.assumeIsolated——假设一旦错误它会在运行时 trap任何长生命周期Task都要被存储并在stop()或deinit中取消。无主的Task就是带额外步骤的泄漏块观察者走 RAII 的NotificationTokenNotificationToken.swift而不是裸addObserver加deinit移除每个捕获self的逃逸闭包用[weak self]闭包不可能比 owner 活得久时用[unowned self]如AppCore的 coordinator 接线DispatchQueue.main.async不是排序问题的修复。顺序重要就让它显式ClipboardStore用isolated deinit做 SQLite 收尾——这是资源必须在其 actor 上拆除的范式拷贝见 ClipboardStore.swift。两个值得预先知道的坑规范指出了两个值得在一个下午被它们坑到之前知道的陷阱withObservationTracking的onChange是 willSet 钩子它在写入落地之前触发因此重读必须延迟进Task——这也是重新武装跟踪的地方因为闭包是一次性的。AppCore.track是值得照抄的形状。在 AppCore.swift 中可见其实现onChange中Task { MainActor in ... }内先self.track(reads, reproject: reproject)重新武装再reproject(self)执行重投影。如果被包裹的工作抛出signpost 区间会泄漏抛出路径上.end发射被跳过除非在defer中。Signposts.interval已经这样做了——见 Signposts.swiftbeginInterval后紧跟defer { signposter.endInterval(name, state) }这正是对withIntervalSignpost跳过 end 事件的修正。Observation 专项规范记录38 个类型使用Observable没有任何东西用ObservableObject或Publishedarchitecture.md 更新为 39 个。把新东西迁移进这个模型时备忘录缓存和惰性构建的协作者上加ObservationIgnored。否则读备忘录会注册依赖视图会在自己的缓存填充时重新渲染——AppCore的 coordinators 全部是ObservationIgnored private(set) lazy正是为此绝不给Environment写类型注解针对Observable类型——宏按类型解析无键重载显式注解会改变选中的重载编译器对漏掉的注入点是盲的一个从没人注入过的层级中读Environment(AppSettings.self)的视图能编译通过、在运行时才 trap所以新增 hosting view 时要检查注入单独检查Observable类型时用swiftc -typecheck——swiftc -parse不展开宏。性能与内存预算是数字不是愿望规范给出的不是尽可能快而是预算常驻内存永远低于 100 MB。没有任何特性值得超支。palette 关闭后内存回到基线启动是应用最保护的东西。加到AppCore.start()或 initializer 的工作是代价最高的位置延迟进Task或首次使用时再做palette 必须感觉即时。召唤路径上的任何东西每次显示只解析一次绝不每次渲染解析零泄漏、无保留环。所有权是以AppCore为根的一棵树。此外testing.md 记录了 2026 年重构末期的实测基线数量级参考非契约常驻内存 40–80 MB硬上限 100 MB、RootPaletteView662 行 /AppCore284 行、注释密度 6.1%27,289 行源码中 1,653 行、harness 套件约 15 秒墙钟11 路并行。规范还强调三条反直觉原则优化前先测量缓存前先测量。该缓存的东西已经缓存了新缓存需要数字而不是直觉避免每击键/每行循环中的重复工作和不必要分配宁可换更廉价的数据结构也不要给昂贵的数据结构加缓存不为以后更快添加抽象。简洁与可维护最简单正确的方案这是整个代码库被要求达到的标准也是它保持可读的原因优先最简单正确的方案。聪明是读它的下一个人付出的代价在抽象移除的复杂性超过它增加的复杂性之前不要添加抽象。只有一个 conformer 的协议、只有一个实例化的泛型、只为一种类型存在的工厂都比具体的东西更糟除非任务就是改变行为否则保留现有行为。行为变更就是决策决策需要讨论删除而非弃用。在一个没有 API 的应用里兼容层没有受众让代码库比你发现它时更干净——但在发现它的那次变更之外的独立 commit中做。注释极简代码不是批注式散文注释规则最短也最硬一行。绝不连续两行注释——如果需要两行它就需要一个命名函数、命名常量或类型硬上限 100 字符含缩进。更长的内容属于docs/下的文档注释为什么、坑或不变式。绝不复述代码、绝不叙述过程、绝不在行内长篇论证决策优先删除注释而非更新它绝不为刚做的变更加解释性注释——diff 不是受众///文档注释公开类型/方法遵循同样规则不是堆行的许可证。值得注意这些规则刻意不被 lint——在注释写完后才触发的规则只会带来第二次编辑这些规则反而在第一遍就很容易做对。可访问性自定义控件的每一行都要说出口palette 是一个完全自定义的控件表面因此没有什么是免费的——每个自定义控件都要带 label 和描述它的 traits一行结果、一个键帽 chip、一个 footer pill、一个对话框按钮都需要显式地说出来。在写视图时加上花一行事后补等于重写。真正被检查的是什么机械门槛在 testing.md规范的收尾部分回答了这些规则到底有没有人管以上一切是 guidance。机械门槛——harness、纯度 grep、格式与 lint、干净构建——是一份清单在 testing.md 中以免因为被写下两次而漂移。不在清单上的都是判断做决定并在 PR 中说明理由如果不明显的话。这份完成定义清单五项全过才算完成是检查项命令Harness 套件./Scripts/run-tests.shLint./Scripts/lint.sh纯层纯度grep -rln import AppKit\|import SwiftUI\|import Cocoa Tinycast/Features/*/Model/必须无输出干净构建xcodebuild … -configuration Debug CODE_SIGNING_ALLOWEDNO零新增警告文档仍为真你的变更弄错的任何文档在同一 commit 中修复没有 CI每一项都在本地运行。项目不设 CI 意味着纪律必须内化——这正是规范文档存在的意义把新代码读起来像一直在那里从口头约定变成可执行的工程实践。代码库的实际构建与运行方式XcodeGen 生成Tinycast.xcodeproj、Debug 通道Tinycast Dev.app/com.tinycast.app.dev与安装版完全隔离等参见 development.md而AGENTS.md的 Non-negotiables 是唯一绝对不可违反的底线。赞分享桌面应用【免费下载链接】tinycastTinycast — a tiny, fully native macOS launcher, hotkeys, and clipboard history.项目地址https://gitcode.com/GitHub_Trending/ti/tinycast点击查看免费下载相关推荐Vector 插桩Instrumentation规范深度解读事件驱动遥测的命名与发射契约Vector 插桩Instrumentation规范深度解读事件驱动遥测的命名与发射契约 Vector 作为高性能可观测性数据管道其自身运行的内部遥测可观测性数据工程数据集成日志分析Effect Schema v4 命名规范变更解读$ 后缀到 $ 前缀的类型级标识符重命名Effect Schema v4 命名规范变更解读 $ 后缀到 $ 前缀的类型级标识符重命名 导读 本文基于 Effect Schema 在 v4 开发周期内AI Agent代码智能体后端前端移动开发桌面应用CodexBar 仓库协作指南深度解读Swift 6 菜单栏应用从构建、测试到发布的完整工程规范CodexBar 仓库协作指南深度解读Swift 6 菜单栏应用从构建、测试到发布的完整工程规范 CodexBar 是一个用 Swift 6 编写的 macOAI 应用桌面应用开发工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
