用途:cmux 正从单一 app target 迁移到 Packages/ 下的 Swift Package,本规范定义新包必须遵守的架构、分层、文件组织、文档、可测试性与并发约束。
主要能力与规则: 包设计:默认 internal,仅公开下游真正使用的符号;包之间构成严格无环 DAG,共享类型需上提到更低层包或在消费方定义协议接缝;一个包拥有一个完整领域(settings、appearance、workspace、terminal、browser、command palette 等);不确定时先抽取无内部依赖的叶子包。 分层:依赖只向下,依次为 Core(纯 Sendable 值、ID、DTO、错误、协议接缝,无 AppKit/SwiftUI/I/O)、Services/基础设施(actor 实现核心协议)、Domain/状态(@MainActor @Observable 模型与 Coordinator)、UI(每领域一个 UI 包,只依赖其领域包与 Core)、Executable(薄组合层,无业务逻辑)。 依赖倒置:低层发布协议,具体实现符合协议,高层只依赖协议;仅用构造器注入,禁止全局容器、单例、static let shared;app target 是唯一组合根。 状态与 SwiftUI:领域状态用 @MainActor @Observable,禁用 ObservableObject/@Published;视图用 @State、@Bindable、@Environment(M.self),禁用 @StateObject/@ObservedObject/@EnvironmentObject。 文件组织:一个文件一个主要类型,按类型命名;跨类型的一致性扩展放 TypeName+Conformance.swift;类型擦除包装器与所擦除类型相邻。 文档:Packages/ 下每个 public 符号写 Swift-DocC /// 注释,首行一句话摘要,参数/返回值/抛出用对应标记,非平凡 API 给简短示例。 包设计纪律:禁止共享单例访问器、命名空间枚举、并行手工维护的注册表、自由函数;优先编译期不变量而非运行时陷阱。 可测试性:public 类型须能在不启动 app、不依赖用户文件系统或 UserDefaults.standard 的情况下测试;UserDefaults、FileManager、路径、环境变量、时钟经 init 传入;禁止 static 测试钩子。 Swift 6 并发:新代码使用 actor、async/await、AsyncStream、@Observable、@MainActor;无书面理由禁用锁、KVO、DispatchQueue 作同步、Combine 变更传播、完成回调公共 API、DispatchQueue.main.async、sleep 轮询、单方法 actor 当互斥锁;@unchecked Sendable 与 nonisolated(unsafe) 需注释安全论证。
使用方式:新包需在 cmux.xcodeproj 的 cmux 与 cmuxTests target 中显式添加 pbxproj 条目;包物理位于 Packages/Shared、Packages/iOS 或 Packages/macOS 之一,移动包用 git mv 后运行 python3 scripts/check-workspace-package-groups.py --write,CI 用 --check 校验;不要 gitignore cmux 自有的 Package.resolved,CI 运行 python3 scripts/check-package-resolved-policy.py。
限制:现有 Packages/ 下的包早于该政策,不可作为设计参考;主 app target 代码不强制追溯文档化;链接进 macOS app 的代码需兼容 Xcode 16.2/Intel,保持 Swift 6.0 语法。