cmux-architecture

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

cmux Architecture

cmux 架构

Package architecture

包架构

We are migrating cmux from a single app target into Swift Packages under

Packages/

. Every new package must satisfy three rules:

Ergonomic. Public API surface matches what callers naturally want to write. Default to internal access; expose
```
public
```
only for types and functions that downstream consumers actually use. Avoid friction such as forcing every call site through a builder or wrapper when a direct API is fine.
No dependency cycles. Packages form a strict DAG. A package may only depend on packages strictly lower in the graph. When two packages need to share a type, lift it to a common lower-level package or define a protocol seam in the consumer. Every new dependency edge requires re-checking that the graph stays acyclic.
Clear but not overly narrow responsibilities. A package owns one full domain (e.g. settings, appearance, workspace, terminal, browser, command palette), not a slice of one. A package called "appearance math" or "workspace model" is too narrow — it forces every consumer that touches the surrounding domain to also depend on the sibling slices. Prefer a single
```
CmuxAppearance
```
that owns settings, theming, colors, glass, and snapshots together, over
```
CmuxAppearanceMath
```
+
```
CmuxAppearanceTheme
```
+
```
CmuxAppearanceSettings
```
. Don't fragment a domain into
```
CmuxFooFormatting
```
+
```
CmuxFooLogic
```
+
```
CmuxFooState
```
— that's folder structure inside a single package, not module structure. A package boundary exists because more than one consumer needs the contents, or a build/test seam needs to exist.

When in doubt, extract leaf-first: pull out the package that has no internal dependencies. Consumers in the app target stay put and only update imports. Each leaf shrinks the app target without requiring downstream packages to exist yet.

The existing packages under

Packages/

predate this policy and should not be used as design references.

Wiring a new local package into the project.

cmux.xcodeproj

lists package dependencies explicitly (it is not a synchronized-folder project). Adding

Packages/CmuxFoo

means mirroring an existing package's

project.pbxproj

entries — one

XCLocalSwiftPackageReference

(in the project's

packageReferences

), one

XCSwiftPackageProductDependency

, and a

PBXBuildFile

linked in the Frameworks phase of every target that imports it. The app-target packages link into both

cmux

and

cmux-unit

(so tests can

import

and inject them); copy a recent leaf like

CmuxSocketControl

for the exact shape, then run

scripts/normalize-pbxproj.py

and

scripts/check-pbxproj.sh

. A package the app builds against but

cmux-unit

does not link will compile the app yet fail the test target.

我们正将cmux从单一应用目标迁移至

Packages/

目录下的Swift Packages。每个新包必须满足以下三条规则：

易用性：公共API的设计符合调用者的自然使用习惯。默认使用内部访问权限；仅对下游消费者实际使用的类型和函数暴露
```
public
```
权限。避免不必要的使用门槛，比如在直接API可行的情况下，强制所有调用点通过构建器或包装器进行调用。
无依赖循环：包之间形成严格的有向无环图（DAG）。一个包只能依赖图中层级更低的包。当两个包需要共享某个类型时，将其提升至共同的底层包，或在消费者中定义协议接口。每新增一条依赖关系，都需要重新检查确保图的无环性。
职责清晰不过于细分：一个包负责完整的业务域（例如：设置、外观、工作区、终端、浏览器、命令面板），而非业务域的某个切片。类似“外观计算”或“工作区模型”的包职责过于狭窄——这会迫使所有涉及相关业务域的消费者同时依赖多个兄弟切片。优先选择单一的
```
CmuxAppearance
```
包，统一管理设置、主题、颜色、玻璃效果和快照，而非拆分为
```
CmuxAppearanceMath
```
+
```
CmuxAppearanceTheme
```
+
```
CmuxAppearanceSettings
```
。不要将业务域拆分为
```
CmuxFooFormatting
```
+
```
CmuxFooLogic
```
+
```
CmuxFooState
```
——这属于单个包内的文件夹结构，而非模块结构。包边界的存在是因为有多个消费者需要其内容，或是需要构建/测试隔离层。

如有疑问，优先提取叶子包：先提取无内部依赖的包。应用目标中的消费者保持不变，仅更新导入语句。每个叶子包的提取都会缩小应用目标的规模，且无需下游包提前存在。

Packages/

目录下的现有包早于本规范，不应作为设计参考。

将新的本地包接入项目：

cmux.xcodeproj

显式列出包依赖（它不是同步文件夹项目）。添加

Packages/CmuxFoo

意味着需要镜像现有包的

project.pbxproj

条目——一个

XCLocalSwiftPackageReference

（位于项目的

packageReferences

中）、一个

XCSwiftPackageProductDependency

，以及在所有导入该包的目标的Frameworks阶段中添加一个

PBXBuildFile

链接。应用目标的包需要同时链接到

cmux

和

cmux-unit

（以便测试可以

import

并注入它们）；复制最近的叶子包（如

CmuxSocketControl

）的配置结构，然后运行

scripts/normalize-pbxproj.py

和

scripts/check-pbxproj.sh

。如果应用构建依赖某个包，但

cmux-unit

未链接该包，会导致应用编译通过但测试目标失败。

Refactor architecture: layers, Coordinator/Service/Repository, dependency inversion

重构架构：分层、Coordinator/Service/Repository、依赖倒置

These higher-level patterns are binding on every new or moved/meaningfully-rewritten file. (The full blueprint, with worked examples and the per-god decomposition, lives in the cmuxterm-hq control repo under

docs/cmux-refactor-audit/blueprint/

; the enforceable core is below.)

Layered, downward-only DAG. Packages form a strict acyclic graph in five layers; dependencies point only downward:

Core (e.g.
```
CmuxCore
```
) — pure
```
Sendable
```
values, IDs, DTOs, errors, and the protocol seams shared across domains. No AppKit/SwiftUI/I/O. The lift target when two domains need the same type.
Services / infrastructure —
```
actor
```
s implementing core protocols against the outside world (process/PTY, filesystem, sockets, web API, notifications, auth). One package per cohesive capability.
Domain / state —
```
@MainActor @Observable
```
models + Coordinators, one package per feature domain; owns that domain's mutable state.
```
CmuxSettings
```
is the exemplar.
UI — SwiftUI/AppKit views, one UI package per domain package, depending only on its domain package + Core, never on a Service directly.
```
CmuxSettingsUI
```
is the exemplar.
Executable (
```
cmuxApp
```
/
```
AppDelegate
```
) — a thin composition shim, no business logic.

Classify every extracted entity by intent:

Coordinator — a
```
@MainActor @Observable
```
orchestrator that sequences a user flow and owns navigation/selection/lifecycle state, calling Services and child models. Does no I/O itself.
Service — an
```
actor
```
(or
```
@MainActor
```
only when an AppKit main-thread API forces it) performing one outside-world capability; exposes
```
async
```
/
```
await
```
+
```
AsyncStream
```
, holds only its own resource handles, holds no UI state.
Repository — an
```
actor
```
mediating one persistence source of truth (file, defaults, web API) behind CRUD-shaped async methods returning value types. Precedents:
```
JSONConfigStore
```
,
```
UserDefaultsSettingsStore
```
.

Dependency inversion. Lower packages publish protocols; concrete Services/Repositories conform; higher layers depend on

any Protocol

, never the concrete type. Share a type by lifting it to Core or defining a protocol seam in the consumer — never a stored property reaching across modules. Injection is constructor (

init

) injection only: no global container, no singleton, no

static let shared

. The executable app target is the single composition root — the one place concretes are named and the object graph is assembled. SwiftUI

Environment

may carry already-constructed

@Observable

models down a view tree (as

SettingsRuntime

does), but is never the source of truth for service wiring.

State + SwiftUI wiring. Domain state lives in

@MainActor @Observable

models (never

ObservableObject

@Published

). A god model decomposes into cohesive child

@Observable

sub-models owned by their domain packages and composed by the home object via held references; cross-domain reads go behind read-only protocols. In views use

@State

(owned),

@Bindable

/ plain

let

(passed-in), or

@Environment(M.self)

.environment(...)

(injected) — never

@StateObject

@ObservedObject

@EnvironmentObject

.environmentObject(_:)

Executable-target boundary (three hard constraints — invert, never work around):

```
@main
```
```
cmuxApp
```
and
```
AppDelegate
```
stay in the executable target as the thin composition shim; that residual is the intended end state, not debt.
A type is declared in exactly one module and a lower package cannot extend a higher-owned type, so
```
AppDelegate+*
```
/
```
cmuxApp+*
```
/
```
Workspace+*
```
extensions do not move down: extract the behavior into a Coordinator/Service/Repository, have the god object own an instance, and reduce the extension to a one-line forward.
Stored properties cannot cross module boundaries: decompose god-model state into child
```
@Observable
```
sub-models owned by domain packages, composed by held reference, with cross-cutting reads behind read-only protocols.

这些高层级模式适用于所有新增或迁移/大幅重写的文件。（完整蓝图包含实例和详细分解，位于cmuxterm-hq控制仓库的

docs/cmux-refactor-audit/blueprint/

目录下；以下是强制执行的核心内容。）

分层、单向依赖的DAG：包分为五层，形成严格的无环图；依赖仅指向更低层级：

核心层（例如
```
CmuxCore
```
）——纯
```
Sendable
```
值、ID、DTO、错误，以及跨业务域共享的协议接口。不依赖AppKit/SwiftUI/I/O。当两个业务域需要同一类型时，将其提升至核心层。
服务/基础设施层——实现核心协议的
```
actor
```
，对接外部资源（进程/PTY、文件系统、套接字、Web API、通知、认证）。每个包对应一个内聚的功能。
业务域/状态层——
```
@MainActor @Observable
```
模型 + Coordinator，每个包对应一个功能业务域；负责该业务域的可变状态。
```
CmuxSettings
```
是典型示例。
UI层——SwiftUI/AppKit视图，每个UI包对应一个业务域包，仅依赖其对应的业务域包 + 核心层，绝不直接依赖服务层。
```
CmuxSettingsUI
```
是典型示例。
可执行层（
```
cmuxApp
```
/
```
AppDelegate
```
）——薄的组合层，无业务逻辑。

按意图对每个提取的实体进行分类：

Coordinator——
```
@MainActor @Observable
```
的编排器，负责编排用户流程，管理导航/选择/生命周期状态，调用服务和子模型。自身不执行I/O操作。
Service——
```
actor
```
（或仅在AppKit主线程API强制要求时使用
```
@MainActor
```
），执行单一外部资源操作；暴露
```
async
```
/
```
await
```
+
```
AsyncStream
```
接口，仅持有自身的资源句柄，不持有UI状态。
Repository——
```
actor
```
，通过CRUD形状的异步方法返回值类型，作为单一持久化数据源的中间层。参考示例：
```
JSONConfigStore
```
、
```
UserDefaultsSettingsStore
```
。

依赖倒置：低层包发布协议；具体的Service/Repository实现协议；高层包依赖

any Protocol

，而非具体类型。通过将类型提升至核心层或在消费者中定义协议接口来共享类型——绝不通过跨模块的存储属性实现。仅使用构造函数（

init

）注入：无全局容器、无单例、无

static let shared

。可执行应用目标是唯一的组合根——在此处指定具体类型并组装对象图。SwiftUI

Environment

可将已构造的

@Observable

模型传递给视图树（如

SettingsRuntime

的做法），但绝不是服务 wiring 的数据源。

状态 + SwiftUI wiring：业务域状态存储在

@MainActor @Observable

模型中（绝不使用

ObservableObject

@Published

）。上帝模型会分解为内聚的子

@Observable

模型，由对应的业务域包拥有，并通过引用组合到主对象中；跨业务域的读取通过只读协议实现。在视图中使用

@State

（视图自有）、

@Bindable

/ 普通

let

（传入），或

@Environment(M.self)

.environment(...)

（注入）——绝不使用

@StateObject

@ObservedObject

@EnvironmentObject

.environmentObject(_:)

。

可执行目标边界（三个硬性约束——遵守而非规避）：

```
@main
```
```
cmuxApp
```
和
```
AppDelegate
```
保留在可执行目标中作为薄组合层；这是预期的最终状态，而非技术债务。
类型仅在一个模块中声明，低层包不能扩展高层包的类型，因此
```
AppDelegate+*
```
/
```
cmuxApp+*
```
/
```
Workspace+*
```
扩展不能下移：将行为提取到Coordinator/Service/Repository中，让上帝对象持有其实例，并将扩展简化为一行转发代码。
存储属性不能跨模块边界：将上帝模型的状态分解为子
```
@Observable
```
模型，由业务域包拥有，通过引用组合，跨域读取通过只读协议实现。

File organization

文件组织

One major type per file. Each

struct

class

enum

actor

, or

protocol

that is part of a public API (or has any meaningful body) lives in its own file named after the type (

Control.swift

LabeledChoice.swift

ListControl.swift

— not one shared

SettingControl.swift

). This rule applies to all new code in

Packages/

and to any new files added to the app target.

Small, closely-bound helpers (
```
private struct
```
, nested types, single-line extensions used only inside the file) can stay with the parent type. Anything bigger or independently meaningful gets its own file.
Conformance-adding extensions for a type defined elsewhere go in
```
TypeName+Conformance.swift
```
or
```
TypeName+Feature.swift
```
, not bundled into the consuming feature file.
Type-erased wrappers (
```
AnyFoo
```
) live next to the type they erase (
```
Foo.swift
```
and
```
AnyFoo.swift
```
), each in its own file.
Existing god files (
```
ContentView.swift
```
,
```
Workspace.swift
```
,
```
TabManager.swift
```
,
```
cmuxApp.swift
```
) are the pattern this rule exists to stop. When migrating code out of them, split into one file per type even if it triples the file count. File count is cheap; "find this type" being unanswerable is expensive.

每个主要类型对应一个文件。每个属于公共API的

struct

、

class

、

enum

、

actor

或

protocol

（或任何有意义实现体的类型）都存放在以该类型命名的文件中（例如

Control.swift

、

LabeledChoice.swift

、

ListControl.swift

——而非共享的

SettingControl.swift

）。此规则适用于

Packages/

中的所有新代码，以及添加到应用目标的所有新文件。

小型、紧密关联的辅助类型（
```
private struct
```
、嵌套类型、仅在文件内部使用的单行扩展）可与父类型放在同一文件中。任何较大或独立有意义的类型都应单独放在一个文件中。
为其他地方定义的类型添加一致性的扩展，应放在
```
TypeName+Conformance.swift
```
或
```
TypeName+Feature.swift
```
中，而非捆绑到消费功能的文件中。
类型擦除包装器（
```
AnyFoo
```
）与被擦除的类型放在一起（
```
Foo.swift
```
和
```
AnyFoo.swift
```
），各占一个文件。
现有的上帝文件（
```
ContentView.swift
```
、
```
Workspace.swift
```
、
```
TabManager.swift
```
、
```
cmuxApp.swift
```
）是本规则旨在杜绝的模式。从这些文件迁移代码时，即使文件数量增加三倍，也要按每个类型一个文件拆分。文件数量的成本很低；而“找不到某个类型”的成本很高。

Documentation

文档

Every

public

symbol in any new Swift package under

Packages/

is documented with a Swift-DocC triple-slash comment at the time of writing. Treat docs as part of the API surface, not as follow-up work.

Format. Use
```
///
```
doc comments above the symbol. First line is a one-sentence summary that fits on a single line and ends with a period. If more context is needed, leave a blank
```
///
```
line, then add a discussion paragraph. Use
```
- Parameter name:
```
/
```
- Returns:
```
/
```
- Throws:
```
callouts on
```
init
```
and
```
func
```
symbols that take parameters or throw. Use Markdown freely (bold, fenced code blocks for examples, backticks for inline code).
Cross-references. Refer to other symbols using double-backticks:
```
 
```
CmuxSetting
```
 
```
. Plain backticks are for non-symbol code (
```
UserDefaults.standard
```
,
```
@AppStorage
```
).
What to document on each symbol. Types: what they represent and when to use them. Enums: meaning of each case. Init parameters: especially defaults and the reason for them. Properties: what value they hold and any invariants. Methods: what they do, plus parameters/returns/throws. Generic constraints: which
```
Value
```
/
```
Element
```
shapes the type accepts and why (e.g.,
```
Sendable & Codable
```
).
Examples. Non-trivial APIs get at least one example in a fenced
```
```swift
```
block, ideally a real declaration from this codebase. Keep examples short and idiomatic.
Internal vs public.
```
internal
```
and
```
private
```
symbols get a one-line
```
///
```
when the intent is non-obvious; verbosity is not required at that scope. The public boundary is the one that needs full coverage.
No stale docs. When you change a symbol's behavior or signature, update its doc comment in the same edit. Docs that describe last week's behavior are worse than no docs.
Don't comment-narrate the body. Doc comments describe the contract from the outside. Inline
```
//
```
comments inside method bodies are reserved for non-obvious why, not what (the existing rule from the top-level guidance still applies).

This rule applies to all packages under

Packages/

. Code in the main app target is not retroactively required to be documented, but new

public

symbols added to packages must be.

Packages/

下任何新Swift包中的每个

public

符号，在编写时都必须添加Swift-DocC三斜杠注释。将文档视为API的一部分，而非后续工作。

格式：在符号上方使用
```
///
```
文档注释。第一行是一句简短的总结，单行显示并以句号结尾。如果需要更多上下文，留一行空的
```
///
```
，然后添加讨论段落。对于带有参数或抛出异常的
```
init
```
和
```
func
```
符号，使用
```
- Parameter name:
```
/
```
- Returns:
```
/
```
- Throws:
```
标注。自由使用Markdown（粗体、示例代码块、行内代码反引号）。
交叉引用：使用双反引号引用其他符号：
```
 
```
CmuxSetting
```
 
```
。单反引号用于非符号代码（
```
UserDefaults.standard
```
、
```
@AppStorage
```
）。
每个符号的文档内容：类型：代表什么以及何时使用。枚举：每个case的含义。初始化参数：尤其是默认值及其原因。属性：存储的值以及任何不变量。方法：功能，加上参数/返回值/抛出异常说明。泛型约束：类型接受的
```
Value
```
/
```
Element
```
形状及原因（例如
```
Sendable & Codable
```
）。
示例：非平凡的API至少需要一个
```
```swift
```
代码块示例，理想情况下是本代码库中的真实声明。示例应简短且符合惯用写法。
内部与公共符号：
```
internal
```
和
```
private
```
符号在意图不明显时添加一行
```
///
```
注释；此范围不需要冗长的文档。公共边界需要完整的文档覆盖。
无过时文档：当修改符号的行为或签名时，在同一编辑中更新其文档注释。描述上周行为的文档比没有文档更糟糕。
不要注释描述实现体：文档注释从外部描述契约。方法体内部的
```
//
```
注释仅用于解释非显而易见的原因，而非内容（顶层指南中的现有规则仍然适用）。

此规则适用于

Packages/

下的所有包。主应用目标中的代码不要求追溯添加文档，但添加到包中的新

public

符号必须遵循此规则。

Package design discipline

包设计规范

These are the recurring design mistakes that have to be caught at the design step, not at code review:

No shared-singleton accessors.
```
static let standard
```
/
```
shared
```
/
```
default
```
on a package type that holds runtime state is a singleton-by-another-name. Construct the package type at the app's startup site and inject it.
```
static let
```
is fine for declarations — identifiers, schema entries, enum cases — but not for behavior.
No namespace-enums.
```
enum Foo { static func bar() }
```
(a no-case enum used as a namespace) is a fake namespace that fights the rest of the design (no instances, no DI, no test seam). Prefer a value-typed struct passed via constructor when the helper might gain configuration, or a file-scope
```
private func
```
for pure helpers internal to one file.
No parallel hand-maintained registries. When a list mirrors a set of declared items (e.g.
```
catalog.all
```
mirroring the catalog's stored properties), derive the list via
```
Mirror
```
reflection or a macro. Two sources of truth drift silently; the IDE doesn't tell you.
Prefer compile-time invariants to runtime traps. If the pattern is
```
guard ... else { assertionFailure(...); return default }
```
for a "programmer error" case, encode it in the type system (phantom types, separate concrete flavors). Runtime traps become silent fallbacks in release builds.
No free functions. Functionality is always scoped to an entity that owns the responsibility: a method on a value type, an extension on the type the operation belongs to, or a member of the Coordinator/Service/Repository that uses it. Top-level
```
func
```
declarations (any visibility, including file-scope
```
private func
```
) are banned. The only sanctioned exception is a
```
@convention(c)
```
trampoline a C API forces on us, marked with a one-line justification.
Nested types still count for the one-major-type-per-file rule. A
```
private final class WatcherAttachment
```
inside
```
JSONConfigFileWatcher.swift
```
is a major type. Move it to its own file the moment it has a meaningful body.

以下是需要在设计阶段就发现的常见设计错误，而非等到代码评审时：

无共享单例访问器：包类型上的
```
static let standard
```
/
```
shared
```
/
```
default
```
持有运行时状态，本质上是另一种形式的单例。在应用启动时构造包类型并注入。
```
static let
```
适用于声明——标识符、 schema 条目、枚举case——但不适用于行为。
无命名空间枚举：
```
enum Foo { static func bar() }
```
（无case的枚举用作命名空间）是伪命名空间，与其他设计冲突（无实例、无依赖注入、无测试隔离层）。当辅助功能可能需要配置时，优先选择通过构造函数传递的值类型结构体；对于单个文件内部的纯辅助功能，使用文件作用域的
```
private func
```
。
无并行手动维护的注册表：当列表镜像一组已声明的项时（例如
```
catalog.all
```
镜像目录的存储属性），通过
```
Mirror
```
反射或宏生成列表。两个数据源会悄然偏离；IDE不会提醒你。
优先使用编译期不变量而非运行时陷阱：如果模式是
```
guard ... else { assertionFailure(...); return default }
```
用于“程序员错误”场景，将其编码到类型系统中（幽灵类型、单独的具体类型）。运行时陷阱在发布构建中会变为静默回退。
无自由函数：功能始终归属于负责该职责的实体：值类型的方法、操作所属类型的扩展，或使用该功能的Coordinator/Service/Repository的成员。禁止顶层
```
func
```
声明（任何可见性，包括文件作用域的
```
private func
```
）。唯一允许的例外是C API强制要求的
```
@convention(c)
```
trampoline，需添加一行理由说明。
嵌套类型仍需遵守“一个主要类型一个文件”规则：
```
JSONConfigFileWatcher.swift
```
内部的
```
private final class WatcherAttachment
```
是主要类型。一旦它有有意义的实现体，就应移至单独的文件。

Testability

可测试性

Every public type added to

Packages/

must be testable from a test target without launching the app target, without booting AppKit, and without depending on the user's filesystem or

UserDefaults.standard

. Production-grade designs surface a test seam at every boundary:

No global state in package code. Every public type that needs
```
UserDefaults
```
,
```
FileManager
```
, an on-disk path, an environment variable, or a clock takes it via initializer parameter. Tests pass a
```
UserDefaults(suiteName:)
```
scoped to the test, a temp directory URL, a fixed
```
Date
```
, etc.
No reliance on
.shared
/
.standard
. A public type that hardcodes
```
UserDefaults.standard
```
or
```
FileManager.default
```
inside its implementation cannot be tested without polluting the developer's actual settings. Inject these at the seam.
Test through injected seams, never a static test hook. A
```
nonisolated(unsafe) static var fooForTesting
```
(or any global mutable "override" a test swaps in) is global state by another name: it leaks across tests, forces
```
nonisolated(unsafe)
```
, and usually needs a lock. Replace it with a protocol seam injected through
```
init
```
(e.g.
```
init(commandRunner: any CommandRunning = CommandRunner())
```
); the test passes a conforming fake. When you extract such a type into a package, deleting the static hook (and the lock it required) is part of the extraction, not a follow-up.
Public APIs return values, not side effects, where possible. A function that mutates global UserDefaults and returns
```
Void
```
is harder to test than one that returns the changed value and lets the caller persist. Prefer pure transformations + thin imperative layers.
Asynchronous APIs surface their observation as
AsyncStream
. Tests can iterate
```
AsyncStream
```
deterministically and assert the sequence of yielded values. Avoid
```
NotificationCenter
```
-only patterns where the test has to spin a runloop.
Document the test pattern alongside any non-trivial public surface. The package's
```
README.md
```
and any DocC catalog should show how to instantiate the type with test-friendly dependencies.

If a design is hard to test, it is wrong. Reach for the constructor parameter list, not the test bench.

Packages/

中添加的每个公共类型必须能够从测试目标进行测试，无需启动应用目标、无需启动AppKit、无需依赖用户的文件系统或

UserDefaults.standard

。生产级设计在每个边界都提供测试隔离层：

包代码中无全局状态：每个需要
```
UserDefaults
```
、
```
FileManager
```
、磁盘路径、环境变量或时钟的公共类型，都通过初始化参数获取。测试时传入作用域限定为测试的
```
UserDefaults(suiteName:)
```
、临时目录URL、固定
```
Date
```
等。
不依赖
.shared
/
.standard
：在实现中硬编码
```
UserDefaults.standard
```
或
```
FileManager.default
```
的公共类型，无法在不污染开发者实际设置的情况下进行测试。在隔离层注入这些依赖。
通过注入的隔离层测试，而非静态测试钩子：
```
nonisolated(unsafe) static var fooForTesting
```
（或任何测试可替换的全局可变“覆盖”）本质上是另一种形式的全局状态：它会在测试间泄漏、需要
```
nonisolated(unsafe)
```
、通常需要锁。替换为通过
```
init
```
注入的协议隔离层（例如
```
init(commandRunner: any CommandRunning = CommandRunner())
```
）；测试时传入符合协议的假实现。将此类类型提取到包中时，删除静态钩子（及其所需的锁）是提取工作的一部分，而非后续工作。
公共API尽可能返回值，而非副作用：修改全局UserDefaults并返回
```
Void
```
的函数，比返回更改后的值并让调用者持久化的函数更难测试。优先选择纯转换 + 薄命令式层。
异步API通过
AsyncStream
暴露观察结果：测试可以确定性地遍历
```
AsyncStream
```
并断言生成的值序列。避免仅使用
```
NotificationCenter
```
的模式，因为测试需要运行循环才能等待事件。
记录测试模式：任何非平凡的公共API都应附带测试模式说明。包的
```
README.md
```
和任何DocC目录应展示如何使用测试友好的依赖实例化类型。

如果某个设计难以测试，那它就是错误的。优先修改构造函数参数列表，而非测试代码。

Modern Swift concurrency

现代Swift并发

All new code in

Packages/

and any new files added to the app target use Swift 6 concurrency primitives:

actor

async

await

AsyncStream

AsyncSequence

@Observable

@MainActor

. Old primitives — locks, manual KVO,

@Published

, completion handlers,

DispatchQueue

used as a serial lock — are not allowed.

If you find yourself reaching for a lock to protect ongoing mutable shared state, the type is almost always the wrong shape — promote it to an

actor

. The exception is the narrow lock carve-out below.

Do not introduce a single-method
actor
purely as a mutex. An

actor Guard { func claim() -> Bool }

whose only job is to guard a flag is a lock with extra ceremony: it forces synchronous callers — a

Process

termination handler, a

DispatchSource

event handler, a

withCheckedContinuation

resume race — through

Task { await guard.claim() }

, which adds suspension points, ordering hops, and reentrancy surface to what is fundamentally a synchronous compare-and-set. That makes the code worse, not safer. A tiny synchronous guard like that belongs in the lock carve-out, not an actor.

When extracting existing code that uses a forbidden primitive into a package, reconsider the shape at the seam rather than copying it blindly — usually it wants an

actor

. But a one-shot single-resume guard (a

Process

termination handler vs. a timeout vs. a spawn failure racing to resume one

withCheckedContinuation

) is exactly a case the lock carve-out covers: keep a synchronous primitive, hidden behind the type. Drain

Process

pipes concurrently on detached tasks keyed by the raw fd (an

Int32

Sendable

; a

FileHandle

is not).

Forbidden in new code (no exceptions without a written justification in the PR description):

Locks.
```
NSLock
```
,
```
NSRecursiveLock
```
,
```
os_unfair_lock
```
,
```
OSAllocatedUnfairLock
```
,
```
pthread_mutex_t
```
,
```
Synchronization.Mutex
```
,
```
DispatchSemaphore
```
used as a lock. Use
```
actor
```
isolation. Mutable shared state belongs in an actor; reads and writes are
```
async
```
. (Narrow carve-out below: a lock is allowed where the
```
actor
```
/
```
async
```
alternative would genuinely worsen the code, with justification.)

KVO via
NSObject
subclassing. Any

class Foo: NSObject

whose purpose is to override

observeValue(forKeyPath:...)

or call

addObserver(_:forKeyPath:...)

. Replace with

NotificationCenter.default.notifications(named:)

AsyncSequence

, or the

NSKeyValueObservation

token API at the seam only.

DispatchQueue
used as a synchronization primitive. A
```
DispatchQueue(label:)
```
accessed via
```
queue.sync { ... }
```
to serialize mutable state is a lock with different syntax. Use an
```
actor
```
. Queues are fine for event delivery (e.g. a
```
DispatchSource
```
handler), not for protecting state.
Combine for change propagation. No
```
@Published
```
, no
```
ObservableObject
```
, no
```
PassthroughSubject
```
/
```
CurrentValueSubject
```
, no
```
AnyCancellable
```
for change observation. Use
```
@Observable
```
(Observation framework, Swift 5.9+) for SwiftUI state, or
```
AsyncStream
```
/
```
AsyncSequence
```
for cross-actor change propagation.
Completion-handler APIs. Authoring a new public API with a
```
(Result<T, Error>) -> Void
```
or
```
(T?, Error?) -> Void
```
callback is forbidden. Use
```
async throws -> T
```
. When wrapping a legacy callback at the boundary, use
```
withCheckedContinuation
```
/
```
withCheckedThrowingContinuation
```
and keep it confined to that one seam.
DispatchQueue.main.async { ... }
. Annotate the destination with
```
@MainActor
```
. Call sites either
```
await
```
the main-isolated function or are themselves
```
@MainActor
```
.
Sleeping as a synchronization substitute.
```
Task.sleep
```
/
```
Clock.sleep
```
(or any sleep) used to poll for a condition, to let state "settle" before reading it, or to race a callback/animation is forbidden — use a real signal (
```
AsyncStream
```
,
```
NSKeyValueObservation
```
, a completion, a state change).
```
DispatchQueue.asyncAfter
```
is banned outright (it is neither cancellable-by-structure nor testable). A bounded, cancellable, intended delay or deadline is allowed under the
```
Clock.sleep
```
carve-out below.

Required shape:

Mutable shared state →
```
actor
```
. Reads/writes/reset are
```
async
```
. Observers receive
```
AsyncStream
```
returned by the actor.
SwiftUI view-render-friendly state →
```
@Observable @MainActor
```
view-model that subscribes to the actor's
```
AsyncStream
```
and projects snapshots. Don't read actor state synchronously from view code.
Cross-process / cross-thread invariants → expressed via actor isolation, not via locks or queues.
New public observable surfaces →
```
AsyncStream
```
or
```
AsyncSequence
```
. Not callbacks, not
```
@Published
```
, not raw
```
NotificationCenter
```
subscription.

Acceptable with a one-line justification comment on the declaration:

These low-level primitives have no async-native replacement. They must be hidden behind an

AsyncStream

actor

surface; callers never see them.

```
DispatchSource.makeFileSystemObjectSource
```
for file watching (no Foundation async equivalent).

DispatchSource.makeReadSource

makeWriteSource

for low-level socket I/O.

A bounded, cancellable
Clock.sleep
(preferred) or
Task.sleep
for a genuine delay/deadline that is itself the intended behavior — a minimum display duration, an auto-dismiss, a check timeout. Drive it from an injected
```
Clock
```
(or a duration) so tests advance virtual time with no real waiting, and wire the sleeping
```
Task
```
's cancellation to the relevant lifecycle so a state transition cancels the pending delay (store the
```
Task
```
, cancel it on transition; or use
```
withTaskCancellationHandler
```
). For true delays/deadlines only, never to poll, settle, or race — those still require a real signal. One-line justification on the call site.
```
DispatchSource.makeTimerSource
```
(one-shot) only when a genuine deadline must fire outside any async context — a non-
```
async
```
type with no
```
Task
```
to host the sleep. Prefer the
```
Clock.sleep
```
carve-out above whenever the code is already on an actor or in async code (it is cancellation-integrated and testable; a raw
```
DispatchSource
```
timer is not, and has suspend/resume/cancel footguns). Hide the timer behind the type, cancel it on the non-timeout path, and never use it to poll or fake a sleep.
A lock for a synchronous compare-and-set called from non-async callbacks, where promoting to an
```
actor
```
would only add
```
Task
```
/
```
await
```
hops and reentrancy. The canonical case is a one-shot resume guard: several synchronous
```
Process
```
/
```
DispatchSource
```
callbacks race to resume one
```
withCheckedContinuation
```
exactly once.
```
OSAllocatedUnfairLock(initialState:)
```
guarding a
```
Bool
```
(claimed once, checked synchronously in each callback) is correct, deterministic, and lets the callback resume the continuation inline. This carve-out is for short, non-blocking critical sections over a tiny flag/counter — not for guarding ongoing domain state (that is still an
```
actor
```
). Keep it private to the type, with a one-line justification.
```
NSKeyValueObservation
```
token (the closure-based API) when wrapping a Foundation/AppKit type that exposes change only via KVO.

@unchecked Sendable
and
nonisolated(unsafe)
:

Both require a comment on the declaration explaining the safety argument. Examples that pass review:

swift

// Wraps DispatchSourceFileSystemObject; every mutation happens on `queue`.
private final class WatcherAttachment: @unchecked Sendable { ... }

// UserDefaults is Apple-documented thread-safe; OK to read nonisolated.
private nonisolated(unsafe) let defaults: UserDefaults

Without a justification comment, the diff is rejected.

@unchecked Sendable

on an entire actor or struct is almost always wrong; prefer

nonisolated(unsafe) let

on the single non-Sendable property.

Scope and enforcement:

Applies to: every new file in
```
Packages/
```
, every new file in the app target, every meaningful rewrite of an existing Swift file.
Existing app target code may continue to use the old primitives until rewritten. Do not retrofit blindly.
Code review checklist (Codex, CodeRabbit, Greptile, and human reviewers): reject diffs that introduce
```
@Published
```
/
```
ObservableObject
```
/
```
DispatchQueue.main.async
```
/
```
addObserver(_:forKeyPath:...)
```
/
```
DispatchQueue.asyncAfter
```
in new code, or
```
Task.sleep
```
/
```
Clock.sleep
```
used to poll, settle, or race rather than as a bounded, cancellable, injected-clock delay with justification. Reject a lock (
```
NSLock
```
/
```
OSAllocatedUnfairLock
```
/etc.) or
```
@unchecked Sendable
```
/
```
nonisolated(unsafe)
```
unless it falls under a documented carve-out and carries a one-line justification — and reject a single-method
```
actor
```
that exists only to guard a flag (use the lock carve-out instead).

Packages/

中的所有新代码以及添加到应用目标的所有新文件，都使用Swift 6并发原语：

actor

、

async

await

、

AsyncStream

AsyncSequence

、

@Observable

、

@MainActor

。禁止使用旧原语——锁、手动KVO、

@Published

、完成处理程序、用作串行锁的

DispatchQueue

。

如果发现自己需要用锁来保护持续的可变共享状态，那类型的设计几乎总是错误的——应将其升级为

actor

。以下是窄范围的锁例外情况。

不要仅为了互斥而引入单方法
actor
：

actor Guard { func claim() -> Bool }

的唯一作用是保护标志，这是带有额外仪式的锁：它会迫使同步调用者——

Process

终止处理程序、

DispatchSource

事件处理程序、

withCheckedContinuation

恢复竞争——通过

Task { await guard.claim() }

调用，这会为本质上是同步的比较并设置操作添加挂起点、顺序跳转和重入面。这会让代码变得更糟，而非更安全。这种微小的同步保护属于锁例外情况，而非actor。

在提取使用禁用原语的现有代码到包中时，应重新考虑隔离层的设计，而非盲目复制——通常应改为

actor

。但一次性恢复保护（例如

Process

终止处理程序、超时、生成失败竞争以恢复单个

withCheckedContinuation

）正好属于锁例外情况：保留同步原语，隐藏在类型内部。在由原始fd（

Int32

是

Sendable

；

FileHandle

不是）标识的分离任务上并发读取

Process

管道。

新代码中禁止使用（PR描述中无书面理由则无例外）：

锁：
```
NSLock
```
、
```
NSRecursiveLock
```
、
```
os_unfair_lock
```
、
```
OSAllocatedUnfairLock
```
、
```
pthread_mutex_t
```
、
```
Synchronization.Mutex
```
、用作锁的
```
DispatchSemaphore
```
。使用
```
actor
```
隔离。可变共享状态应放在actor中；读取和写入是
```
async
```
操作。（以下窄范围例外：在
```
actor
```
/
```
async
```
替代方案确实会使代码变差的情况下，允许使用锁并附上理由。）

通过
NSObject
子类化实现KVO：任何

class Foo: NSObject

，其目的是重写

observeValue(forKeyPath:...)

或调用

addObserver(_:forKeyPath:...)

。替换为

NotificationCenter.default.notifications(named:)

AsyncSequence

，或仅在隔离层使用

NSKeyValueObservation

令牌API。

用作同步原语的
DispatchQueue
：通过
```
queue.sync { ... }
```
访问的
```
DispatchQueue(label:)
```
用于序列化可变状态，本质上是语法不同的锁。使用
```
actor
```
。队列适用于事件传递（例如
```
DispatchSource
```
处理程序），而非保护状态。
使用Combine进行变更传播：禁止使用
```
@Published
```
、
```
ObservableObject
```
、
```
PassthroughSubject
```
/
```
CurrentValueSubject
```
、
```
AnyCancellable
```
进行变更观察。对于SwiftUI状态，使用
```
@Observable
```
（Observation框架，Swift 5.9+）；对于跨actor变更传播，使用
```
AsyncStream
```
/
```
AsyncSequence
```
。
完成处理程序API：禁止编写带有
```
(Result<T, Error>) -> Void
```
或
```
(T?, Error?) -> Void
```
回调的新公共API。使用
```
async throws -> T
```
。在边界包装遗留回调时，使用
```
withCheckedContinuation
```
/
```
withCheckedThrowingContinuation
```
并将其限制在该隔离层内。
DispatchQueue.main.async { ... }
：在目标函数上标注
```
@MainActor
```
。调用点要么
```
await
```
主线程隔离的函数，要么自身属于
```
@MainActor
```
。
用睡眠替代同步：禁止使用
```
Task.sleep
```
/
```
Clock.sleep
```
（或任何睡眠）来轮询条件、等待状态“稳定”后再读取，或竞争回调/动画——使用真实信号（
```
AsyncStream
```
、
```
NSKeyValueObservation
```
、完成信号、状态变更）。完全禁止
```
DispatchQueue.asyncAfter
```
（它既无法通过结构取消，也无法测试）。仅在以下例外情况允许使用
```
Clock.sleep
```
：有界、可取消、预期的延迟或截止时间。

要求的设计形状：

可变共享状态 →
```
actor
```
。读取/写入/重置是
```
async
```
操作。观察者接收actor返回的
```
AsyncStream
```
。
适合SwiftUI视图渲染的状态 →
```
@Observable @MainActor
```
视图模型，订阅actor的
```
AsyncStream
```
并提供快照。不要从视图代码同步读取actor状态。
跨进程/跨线程不变量 → 通过actor隔离表达，而非锁或队列。
新的公共可观察表面 →
```
AsyncStream
```
或
```
AsyncSequence
```
。不使用回调、
```
@Published
```
或原始
```
NotificationCenter
```
订阅。

添加一行理由注释后允许使用：

这些低级原语没有异步原生替代方案。它们必须隐藏在

AsyncStream

或

actor

表面之后；调用者永远看不到它们。

```
DispatchSource.makeFileSystemObjectSource
```
用于文件监控（Foundation无异步等效API）。

DispatchSource.makeReadSource

makeWriteSource

用于低级套接字I/O。

有界、可取消的
Clock.sleep
（优先）或
Task.sleep
用于真实的延迟/截止时间——这是预期行为的一部分，例如最小显示时长、自动关闭、检查超时。从注入的
```
Clock
```
（或时长）驱动延迟，以便测试可以推进虚拟时间而无需真实等待，并将睡眠
```
Task
```
的取消与相关生命周期关联，以便状态转换时取消待处理的延迟（存储
```
Task
```
，转换时取消；或使用
```
withTaskCancellationHandler
```
）。仅适用于真实的延迟/截止时间，绝不用于轮询、等待稳定或竞争——这些仍需使用真实信号。在调用点添加一行理由注释。
```
DispatchSource.makeTimerSource
```
（一次性）仅当真实截止时间必须在任何异步上下文之外触发时——非
```
async
```
类型且无
```
Task
```
来承载睡眠。只要代码已在actor或异步代码中，优先选择上述
```
Clock.sleep
```
例外情况（它集成了取消功能且可测试；原始
```
DispatchSource
```
定时器不具备这些特性，且有挂起/恢复/取消的陷阱）。将定时器隐藏在类型内部，在非超时路径上取消它，绝不用于轮询或模拟睡眠。
用于同步比较并设置的锁，从非异步回调调用，此时升级为
```
actor
```
只会增加
```
Task
```
/
```
await
```
跳转和重入面。典型场景是一次性恢复保护：多个同步
```
Process
```
/
```
DispatchSource
```
回调竞争以恢复单个
```
withCheckedContinuation
```
恰好一次。
```
OSAllocatedUnfairLock(initialState:)
```
保护
```
Bool
```
（仅声明一次，在每个回调中同步检查）是正确、确定性的，且允许回调内联恢复continuation。此例外情况适用于小范围、非阻塞的临界区，保护微小的标志/计数器——而非保护持续的业务域状态（仍需使用
```
actor
```
）。将其保持为类型私有，并添加一行理由注释。
```
NSKeyValueObservation
```
令牌（基于闭包的API），当包装仅通过KVO暴露变更的Foundation/AppKit类型时。

@unchecked Sendable
和
nonisolated(unsafe)
：

两者都需要在声明上添加注释，解释安全性理由。通过评审的示例：

swift

// Wraps DispatchSourceFileSystemObject; every mutation happens on `queue`.
private final class WatcherAttachment: @unchecked Sendable { ... }

// UserDefaults is Apple-documented thread-safe; OK to read nonisolated.
private nonisolated(unsafe) let defaults: UserDefaults

若无理由注释，代码变更将被拒绝。在整个actor或结构体上使用

@unchecked Sendable

几乎总是错误的；优先在单个非Sendable属性上使用

nonisolated(unsafe) let

。

范围与执行：

适用范围：
```
Packages/
```
中的每个新文件、应用目标中的每个新文件、每个现有Swift文件的大幅重写。
现有应用目标代码可继续使用旧原语，直至重写。不要盲目改造。
代码评审检查清单（Codex、CodeRabbit、Greptile及人工评审）：拒绝在新代码中引入
```
@Published
```
/
```
ObservableObject
```
/
```
DispatchQueue.main.async
```
/
```
addObserver(_:forKeyPath:...)
```
/
```
DispatchQueue.asyncAfter
```
的变更，或使用
```
Task.sleep
```
/
```
Clock.sleep
```
进行轮询、等待稳定或竞争而非有界、可取消、注入时钟延迟且无理由的变更。拒绝使用锁（
```
NSLock
```
/
```
OSAllocatedUnfairLock
```
等）或
```
@unchecked Sendable
```
/
```
nonisolated(unsafe)
```
的变更，除非属于文档化的例外情况且带有一行理由注释——拒绝仅为保护标志而存在的单方法
```
actor
```
（改用锁例外情况）。