Tinycast 工程规范完全指南：Posture、不可妥协项与完成标准解读

Tinycast 工程规范完全指南：Posture、不可妥协项与完成标准解读

【免费下载链接】tinycastTinycast — a tiny, fully native macOS launcher, hotkeys, and clipboard history.项目地址: https://gitcode.com/GitHub_Trending/ti/tinycast

本篇技术指南以 Tinycast 仓库根目录的 AGENTS.md 为核心，系统拆解这个完全原生、零第三方依赖的 macOS 启动器（launcher）项目在工程组织上的全部硬性规则：为什么它只面向最新版 macOS、AppCore为何是唯一状态所有者、Model/层为何被"编译级"强制保持纯净，以及一个改动达到什么标准才算真正完成。读完你既能按这套规范参与 Tinycast 的代码维护，也能把其中的"单一所有权 + 分层纯净 + 可机械验证的完成标准"方法论迁移到自己的 Swift 项目中。

项目定位：一个刻意保持"小"的 macOS 菜单栏启动器

Tinycast 是一个原生 macOS 菜单栏启动器：模糊匹配的应用启动器、全局与按应用热键、文本/图片剪贴板历史、内联计算器、浮动笔记、snippets、quicklinks、窗口管理与 emoji 选择器，并能在 JavaScriptCore 中原生运行 Raycast 扩展。技术栈是 SwiftUI + AppKit，以无 Dock 图标的 accessory 形式运行（LSUIElement），零第三方依赖（见 README.md 与 AGENTS.md 开头）。

但从工程角度看，这个项目最值得研究的不是功能列表，而是它如何用规范把代码库规模压到极小。仓库的 AGENTS.md 正是这套规范的源头：它定义了全局 Posture、目录地图、十条"不可妥协项"、命名与注释约定，以及提交前的完成检查清单。以下是逐节解读。

Posture：只支持最新版，永远（latest-only, always）

AGENTS.md 的 "Posture: latest-only, always" 是全项目最根本的工程决策：

Tinycast targets one macOS — the current stable release — and nothing else.macOS 26+，Xcode 26 工具链，Swift 6 语言模式。没有兼容性下限要守护、没有 shim 层、没有废弃技术债。

这一决策直接体现在工程配置中：project.yml 里deploymentTarget.macOS: "26.0"、SWIFT_VERSION: "6.0"、SWIFT_STRICT_CONCURRENCY: complete。它带来的具体写码规则是：

• 优先使用现代 Apple API：用 Observation 而不是ObservableObject；用 Swift Concurrency 而不是DispatchQueue或 completion handler；用SMAppService而不是登录项 shim；用结构化并发而不是脱离管理的零散任务。
• 迁移，绝不包装：当一个 API 出现现代替代品时，直接采用新 API 并删除旧调用点。保留旧写法的包装层是这个项目花最大力气清除的东西。
• 废弃 API 即缺陷（"A deprecated API is a defect, not a warning to live with"），不是可以容忍的警告。
• 不加兼容层、不留遗留变通、不采用旧架构模式：删除优于弃用；提高最低 macOS 版本就等于删掉了支持旧版本的代码。
• 除非被明确要求，永不主动引入向后兼容：没有版本开关、没有迁移脚手架、没有"以防万一"的回退。代码库本身不携带任何迁移代码。

Carbon 的两个"能力缺口"特例

唯一例外是 Carbon，但这是刻意选择的能力缺口依赖，而非惯性：现代 API 中没有任何东西能注册系统级组合键（chord），而 HIToolbox 的 TIS API 仍是枚举与选择键盘输入法的公开机制。详细论证见 docs/standards.md#posture 以及 docs/architecture.md 中的描述——每个原始 C 指针在进入 actor 代码前都会被解码为纯值。

为什么如此严格

docs/standards.md#posture 给出了理由：兼容性下限不是一次性成本。每个 shim 都会比需要它的平台活得更久、被下一个看到的 feature 复制、把一行调用变成没人敢删的一层。Tinycast 没有外部 API、没有插件面、只支持一个 OS，所以"它没有需要兼容的东西"——这正是它保持小的全部原因。文档还记录了一个可验证的经验事实：项目已删除的版本门控代码，一贯比它所门控的功能本身还要大。

目录导览：Where things are

AGENTS.md 用两张表给出了全仓库地图，这是理解"规范落在哪个文件"的入口：

配套的"读什么文档"索引表同样关键——它定义了改动前的强制阅读路径：

值得注意的是 docs/architecture.md 提供的完整目录树：App/是组合根，DesignSystem/与Platform/是两个"不得依赖任何 feature"的共享层，Features/下每个 feature 自成一体，Resources/里提交了嵌入的RaycastRuntime.generated.js（所以构建应用永远不需要 Node）。

不可妥协项（Non-negotiables）：十条不能破坏的底线

AGENTS.md 的核心是十条"没有明确任务就绝不能破坏"的规则（feature 专属的 invariants 在各自 feature 的文档里，以## Invariants章节出现）。下面逐条展开，并给出仓库中的实现证据。

1.AppCore是唯一所有者

新的长生命周期状态必须放在AppCore上，在start()中完成 wiring——绝不创建与之竞争的 singleton。视图通过@Environment访问 feature 的coordinator，而不是AppCore。

源码印证：Tinycast/App/AppCore.swift 是一个@MainActor @Observable的final class AppCore（static let shared），持有约二十个 store（AppIndex、ClipboardStore、SnippetsStore、QuicklinkStore等）、管理器/监控器/时钟（ClipboardManager、HotKeyManager、HyperKeyTap、RunningAppsMonitor、SnippetKeywordListener）、共享状态（AppSettings、PaletteState等），以及二十个 feature coordinator。它的start()方法（AppCore.swift#L220-L363）就是整个应用的启动序列，一屏可读。

配合 AppDelegate.swift#L11-L13，applicationDidFinishLaunching只做一件事：AppCore.shared.start()。这是唯一的 wiring 点。coordinator 全部声明为@ObservationIgnored private(set) lazy——这正是 docs/architecture.md 强调的：memo 缓存和惰性构建的协作对象必须加@ObservationIgnored，否则读取 memo 会注册依赖、导致视图在自身缓存填充时重渲染。

2.Model/纯净层：编译强制，而非约定

Features/*/Model/下的文件不得 import AppKit 或 SwiftUI，且所有环境事实（时钟、文件系统、主目录、汇率）都以注入参数传入。

这条规则的独特之处在于它由编译强制：Tests/的 harness 直接编译仓库里"正版"的源码（而非副本），所以一旦Model/泄漏了 AppKit/SwiftUI import，harness 立刻编译失败。相关命令见 docs/testing.md#purity-checks：

grep -rln 'import AppKit\|import SwiftUI\|import Cocoa' Tinycast/Features/*/Model/

这条 grep 必须返回空。典型例证：CalcEngine通过now/calendar/rates参数注入时钟与汇率（见 docs/architecture.md 对Model/层的定义：只依赖 Foundation，外加数据需要的 SQLite3 或 CoreGraphics，环境事实全部注入——这是做决策的层；Service/是执行动作的层，所有AXUIElement、CGEventTap、NSWorkspace.open、URLSession都住在这里）。

3. Swift 6 语言模式：数据竞争即硬错误

@MainActor是默认；跨 actor 的模型类型是Sendable；重活或 IO 活作为nonisolated函数由Task.detached驱动到主线程外。不要引入第二个 actor。

工程配置SWIFT_STRICT_CONCURRENCY: complete+SWIFT_VERSION: "6.0"（project.yml）落实了这一点。更细的并发约定在 docs/standards.md#concurrency-and-lifetime：任何长生命周期Task都要存储在stop()或deinit中取消（无主的Task是"带额外步骤的泄漏"）；block observer 走 RAII 的NotificationToken（Platform/NotificationToken.swift）；每个捕获self的逃逸闭包用[weak self]（或闭包不可能比 owner 活得久时用[unowned self]，如AppCore的 coordinator wiring）。ClipboardStore用isolated deinit做 SQLite 拆除——这是"资源必须在其 actor 上拆除"的样板写法。

4. 深色是基线

Theme.Colors通过ramp/adaptive按 appearance 解析；每个深色值都是强制深色构建当初发布的Color.white.opacity(…)，是"重申"而非"重新推导"。自由调整浅色分支；只有任务本身是改深色时才动深色分支。AppAppearance驱动NSApp.appearance，.system映射为nil让 AppKit 自行跟随 macOS。

源码印证见 AppCore.swift#L586-L588：applyAppearance()即NSApp.appearance = settings.appearance.nsAppearance，注释明确.system解析为nil，AppKit 无轮询地跟随 macOS。设计令牌的唯一来源是 Tinycast/DesignSystem/Theme.swift。

5. 自己呈现对话框，绝不使用系统控件

问题走DialogController，报告走HUDPresenter（HUD）。从不使用NSAlert、NSSlider或系统 popover。

docs/architecture.md 进一步解释这是"承重"的：对话框是 borderless 的DialogPanel，由DialogController驱动，是全应用唯一的确认/失败/取值 presenter；呈现是async的所以不阻塞主 actor，且 presenter 在已有对话框时拒绝第二个——靠这一点、而不是靠一个 flag，阻止了按住热键堆叠对话框。AppCore上的showNotice、confirm、reportFailure、showMessage、pickVolume都是转发器（AppCore.swift#L644-L711），确保DialogController与MessageHUDController单一所有。

6. 网络会话与备份安全

联网 feature 使用私有的.ephemeral、urlCache = nil会话，绝不使用URLSession.shared，让"自己的缓存文件"成为磁盘上唯一副本。CurrencyRateStore是参照实现——复制它，不要发明第二种形态。授予能力的 flag 绝不随备份携带：snippetsEnabled被排除在设置备份之外，防止导入备份时意外授予按键监听能力。

这条在 docs/testing.md 的手动回归清单中有对应验证项："snippetsEnabledis not in the exported file, and importing does not enable snippets"。

7. 扩展隔离：不透明的盒子

扩展相关的一切视图、行、菜单、几何与尺寸常量都写在Features/Extensions/内部，绝不放进DesignSystem/、绝不挂到Theme上、绝不被其他 feature 拿来复用。另一个表面可以把扩展渲染成不透明盒子（LauncherScreen对ExtensionArgumentsAccessory正是这么做的），但绝不伸进其内部。

理由是扩展运行的是不受控的第三方代码，所以它绝不能反过来强制改变 launcher 表面的任何东西。"为留在隔离区内而复制一个视图或一段布局数学，是正确的取舍"——这是全项目唯一让"禁止重复"规则让步的地方。可共享的只有：Theme的基础令牌（间距、圆角、颜色）、作为同一批令牌视图层的InterfaceMetrics、作为数据形态的PopoverMenuItem，以及Platform/。ExtensionActionsPanel与ExtensionGridGeometry之所以存在，正是因为 palette 自己的菜单和 emoji 网格必须保持自由演进。

8.AppEntry.Kind是唯一身份来源

AppEntry.Kind是唯一说明"一个 entry 是什么"的地方：每个 launcher section 与每个VisibilityStore类别各一个 case——绝不靠嗅探 entry ID 来重新推导类别。哪个 pane 列出某个命令是另一回事，SettingsTab.ownedCommands是唯一陈述它的地方。

9. 生成文件永不手编

EmojiData.generated.swift←node Scripts/gen-emoji.js；CurrencyData.generated.swift←node Scripts/gen-currencies.js；CountryZoneData.generated.swift←node Scripts/gen-countries.js；Resources/RaycastRuntime.generated.js←Scripts/raycast-runtime/build.mjs。运行时文件被提交进仓库，所以构建应用永远不需要 Node。

docs/development.md#generated-data 补充了细节：生成脚本各自下载数据源（需联网运行后提交结果），gen-currencies.js把汇率 feed 自己的报价列表与 CLDR 数据按 ISO 代码连接——所以"币种表"与"汇率来源"永远不会漂移；只有无歧义的数据才会被生成，有争议的（如多个国家共用的dollars、pounds）留给CalcCurrency.contested手写。

10. 两个滚动文件禁区

DesignSystem/Scrolling/EdgeDissolve.swift与ThinScrollbar.swift禁止改动：两者都是对着 palette 的悬浮条肉眼调校的，任何编辑都是视觉回归。若修滚动 bug 需要动它们，说明真正的修复在别处。

值得提前知道的约定（Conventions）

类型后缀表：后缀说明"它是什么"

AGENTS.md 指向 docs/standards.md#naming 的完整表格。语义正确性永远优先于后缀一致性：选能诚实描述类型职责的后缀，没有合适时新增一行，绝不为凑表而改名。关键条目：

注意Manager是唯一需要三思的后缀（生命周期 + 策略负担很重），因此全项目只有两个：ClipboardManager和HotKeyManager。Registry与ViewModel已被退役：静态表是Catalog，共享应用状态是State。

注释规范：罕见、一行、解释 why

AGENTS.md 的规则言简意赅：注释罕见、单行、解释为什么（gotcha 或 invariant），从不解释做了什么。禁止连续两行注释、禁止扩展成块：一行写不下就命名一个函数/常量/类型。硬上限 100 字符，删除优于更新，绝不为你刚做的改动加注释。而且"没有任何工具 lint 这条——第一次就要写对"（docs/standards.md#comments 明确这是刻意选择：规则在注释写完后才触发等于买第二次编辑）。值得注意的是 docs/development.md#linting 提到 SwiftLint 实际会检查可机器检查的两条：100 字符上限与连续注释禁令。

Debug 构建是独立渠道

Debug 构建运行的是Tinycast Dev.app/com.tinycast.app.dev——本地运行绝不与已安装副本共享 prefs、缓存、TCC 授权或登录项。任何新持久化的东西都必须以Bundle.main.bundleIdentifier为 key。

配置证据在 project.yml 的 Debug config：PRODUCT_NAME: Tinycast Dev、PRODUCT_BUNDLE_IDENTIFIER: com.tinycast.app.dev。docs/development.md#the-dev-channel 展开说明：prefs 在~/Library/Preferences/<id>.plist，数据在~/Library/Application Support/<id>/，可重取的数据才进~/Library/Caches/<id>/（因为 Caches 不进 Time Machine、系统可能在磁盘压力下静默回收）。两个已知后果：Dev 构建首次会自己申请 Accessibility、默认无热键绑定；Hyper Key 的 Caps Lock 重映射是hidutil状态、系统级而非按 bundle，退出一个构建会清掉另一个的重映射。

XcodeGen 拥有项目

Tinycast.xcodeproj被提交，但由project.yml生成：改完project.yml后运行xcodegen generate并提交两者。不用 SwiftPM，永远不用Bundle.module。

构建命令（docs/development.md#build--run）：

open Tinycast.xcodeproj # 然后 ⌘R # 或命令行： xcodebuild -project Tinycast.xcodeproj -scheme Tinycast -configuration Debug build

若xcode-select指向 Command Line Tools 而非 Xcode，需前缀DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer（SwiftUI 的@State/@FocusState宏需要 Xcode 的 macOS 平台）。

Before you finish：完成标准（Definition of Done）

AGENTS.md 的收尾清单指向 docs/testing.md#definition-of-done——"机械标准只写在一处，所以不会因写了两遍而漂移"。五项全部通过才算改动完成：

测试体系：没有 XCTest target 的独立 harness

Tinycast 刻意没有 XCTest target 与 UI 测试，自动化测试是一组独立 harness（Tests/下每个 Swift 文件一个）。这与纯净层规则形成闭环：每个 harness 直接编译它守护的"已发布源码"而非副本，因此"harness 停止编译"就意味着Model/泄漏了 AppKit/SwiftUI，或一个 effect 泄漏进了决策——这比断言失败更常见，也更重要。

Scripts/run-tests.sh 的机制值得一提：

• 运行整个套件：./Scripts/run-tests.sh；只跑单个：./Scripts/run-tests.sh calc-test（名字是 harness 名）。
• 套件并行执行，hw.ncpu个 worker 同时跑；TINYCAST_TEST_JOBS=1强制串行；TINYCAST_TEST_TIMEOUT（默认 300 秒）超时杀掉卡死的 harness。
• 每个 harness 必须把自己的临时状态根植于专属位置（UUID 后缀的temporaryDirectory、UserDefaults(suiteName:)、NSPasteboard.withUniqueName()），因为 harness 在真实登录会话、无沙箱、无 fixture 世界里运行，绝不能改动与日常使用共享的机器状态——NSPasteboard.general是最大的陷阱：正在运行的 Tinycast 会把每次写入都当作真实复制记入剪贴板历史。
• 脚本文件头就记录了run-tests.sh的教训：绝不在set -e脚本里用&&连接编译与运行——set -e规定忽略非末尾 AND-OR 列表成员的失败，swiftc … && /tmp/x会吞掉编译错误让脚本继续跑（历史上有 CI 连续 25 个阶段对"根本没编译成功"的 harness 报成功）。

harness 与所守护模块的映射表很庞大（docs/testing.md#what-to-run-when），例如：fuzz-test守护Launcher/Model/SearchRelevance.swift等排序相关文件；calc-test守护整个Calculator/Model/；raycast-test守护RaycastDecoder、Scrypt、Zlib；ext-test端到端在 JavaScriptCore 里启动真实 bundle 并渲染。需要服务器的两个 harness 自带 stub（Tests/ai-fixtures/codex-stub.js、mcp-stub.js），被复制进 scratch 目录并前置到 PATH。

构建与大小检查

docs/testing.md#build-and-size-checks 的机械标准还包括：零新增警告（存量警告不是你的问题）；未经说明理由不得新增@unchecked Sendable、nonisolated(unsafe)或assumeIsolated；类型检查器不得超时（LauncherList.rows已带显式注解，修超时的方式是加注解而非重构）；普通改动 Release 二进制增长 < 2%。

性能测量走Platform/Signposts.swift在com.tinycast.perf子系统发射的八个 interval（AppCore.start、AppIndex.scan、AppIndex.rank、PaletteWindowController.show、UninstallScanner.discover、UninstallScanner.measure、FileSearchService.search、Notes.search），用 Instruments 的 Time Profiler 或os_signpost过滤到该子系统即可，无需重新编译。文档记录的基线（2026 重构结束时在main上测得）只能当数量级参考而非契约：Release 二进制 3,655,736 B、常态驻留内存 40–80 MB（硬上限 100 MB）、harness 套件约 15 秒墙钟（11 路并行，串行约 98 秒、改造前约 140 秒）。

从 AGENTS.md 到四层架构：规范如何落地

若把 AGENTS.md 视为"宪法"，docs/architecture.md 就是"地图"。每个成熟子系统都收敛到四层，而Tests/的 harness 正是把各层隔开的机制：

PURE（Foundation only，环境事实全部注入）→ EFFECT（平台 I/O）→ OBSERVABLE STATE（@MainActor @Observable）→ VIEW（SwiftUI 视图 + coordinator）

在文件夹树上对应Model/、Service/、UI/+Settings/；可观察状态住在拥有它的那一层。规则可检查（这正是重点）：Model/不得 import AppKit/SwiftUI，因为 harness 编译的是已发布源码。边界把 effect 挡在决策之外：CalcEngine.evaluate被交给一个成品CurrencyRates?而不是自己去取——这使它保持 Foundation-only 且可测试。确认门（confirmation gate）住在 coordinator 而不是 runner 里——这就是为什么ShellCommandRunner与SystemActionRunner能保持可被 harness 编译，而"你确定吗？"步骤依然无法绕过。

观察层（Observation）有三个容易踩的坑（docs/architecture.md#observation，与 docs/standards.md 重复强调）：memo 缓存与惰性协作对象要加@ObservationIgnored；@Environment上绝不写类型注解（宏按类型解析无 key 重载，注解会改变所选重载）；编译器看不见遗漏的注入点——在没人注入的层级里读@Environment(AppSettings.self)会编译通过但运行时 trap，所以加新 hosting view 时要检查注入。另外withObservationTracking的onChange是willSet 钩子（写入落地前触发、一次性），所以重读要推迟进Task并在那里重新布防——AppCore.track（AppCore.swift#L599-L612）就是该形态的样板。

结语：把 Tinycast 的规范用起来

AGENTS.md 是一份罕见的、可执行的工程宪法：它把"最新优先"、"单一所有权"、"纯净分层"、"编译级强制"与"一处定义、五步验收的完成标准"绑定成一个自洽体系，而其每一条都能在仓库源码、工程配置与测试脚本中找到落实证据。对 Tinycast 的贡献者来说，动手前的正确路径是：改 wiring 先读 docs/architecture.md，写 Swift 先读 docs/standards.md，声称完成前跑完 docs/testing.md 的五项检查。对其他 macOS/Swift 项目而言，哪怕只移植"用 harness 编译正版源码以强制纯净层"和"单一组合根 + 无竞争单例"这两条，也能显著降低代码库长期腐化的速度。

【免费下载链接】tinycastTinycast — a tiny, fully native macOS launcher, hotkeys, and clipboard history.项目地址: https://gitcode.com/GitHub_Trending/ti/tinycast