axiom-concurrency

并发

任何并发、async/await、线程或 Swift 6 并发工作，都必须使用此技能。

**Claude Code 中捆绑的工具：**如果 command -v <tool> 没有找到任何内容（钩子已关闭或使用了 --bare），请使用 <plugin-root>/tools/<tool> 替代裸名称；<plugin-root> 是此技能的 Base directory for this skill: 路径向上两级的目录。

无法启动 Axiom Agent？ 如果此路由将你指向某个 Agent，请直接按照其流程操作。通过 MCP，axiom_get_agent 会返回该流程；在其他环境中，请阅读下方对应的文件，该操作只需要搜索和读取文件。

此处可用：skills/concurrency-auditor.md。

对于其他 Agent，也可以通过 MCP 使用 axiom_get_agent 获取；请使用 axiom_xclog_*、axiom_xcsym_* 和 axiom_xcprof_* 工具运行其 xclog、xcsym 和 xcprof 步骤。在其他环境中，请在 Axiom 的技能中搜索 skills/<agent>.md；如果不存在，请使用本套件的技能自行完成，并使用 PATH 中的任意 Axiom 工具。

快速参考

症状 / 任务	参考
async/await 模式、@MainActor、Actor	请参阅 skills/swift-concurrency.md
数据竞争错误、Sendable 一致性	请参阅 skills/swift-concurrency.md
Swift 6 迁移、@concurrent 属性	请参阅 skills/swift-concurrency.md
Actor 定义、可重入性、全局 Actor	请参阅 skills/swift-concurrency-ref.md
Task/TaskGroup/取消 API	请参阅 skills/swift-concurrency-ref.md
AsyncStream、continuation	请参阅 skills/swift-concurrency-ref.md
DispatchQueue → Actor 迁移	请参阅 skills/swift-concurrency-ref.md
Mutex（iOS 18+）、OSAllocatedUnfairLock	请参阅 skills/synchronization.md
原子类型、锁与 Actor 的选择	请参阅 skills/synchronization.md
MainActor.assumeIsolated	请参阅 skills/assume-isolated.md
@preconcurrency 协议一致性	请参阅 skills/assume-isolated.md
旧式委托回调	请参阅 skills/assume-isolated.md
无警告构建却因 _dispatch_assert_queue_fail 崩溃	请参阅 skills/isolation-inheritance-diag.md
崩溃特征 _swift_task_checkIsolatedSwift	请参阅 skills/isolation-inheritance-diag.md
@MainActor 类中 Core Data context.perform 运行时崩溃	请参阅 skills/isolation-inheritance-diag.md
因 receive(on:) 的放置位置导致 Combine .map/.sink 崩溃	请参阅 skills/isolation-inheritance-diag.md
因隔离继承导致委托方法崩溃（CLLocationManager、NSDocument、AVAudioPlayerDelegate、WKNavigationDelegate、PHPhotoLibraryChangeObserver）	请参阅 skills/isolation-inheritance-diag.md
PhotoKit 的 performChanges 代码块在 PhotoKit 队列上触发陷阱	请参阅 skills/isolation-inheritance-diag.md
Actor 可重入性 / await 期间状态过时	请参阅 skills/isolation-inheritance-diag.md
Swift 并发 Instruments 模板	请参阅 skills/concurrency-profiling.md
Actor 争用诊断	请参阅 skills/concurrency-profiling.md
线程池耗尽	请参阅 skills/concurrency-profiling.md

决策树

digraph concurrency {
    start [label="Concurrency task" shape=ellipse];
    what [label="What do you need?" shape=diamond];

    start -> what;
    what -> "skills/swift-concurrency.md" [label="async/await, actors,\nSendable, data races,\nSwift 6 migration"];
    what -> "skills/swift-concurrency-ref.md" [label="API syntax lookup\n(TaskGroup, AsyncStream,\ncontinuations, migration)"];
    what -> "skills/synchronization.md" [label="Mutex, locks,\natomic types"];
    what -> "skills/assume-isolated.md" [label="assumeIsolated,\n@preconcurrency"];
    what -> "skills/isolation-inheritance-diag.md" [label="warning-free build crashes\n_dispatch_assert_queue_fail\n_swift_task_checkIsolatedSwift"];
    what -> "skills/concurrency-profiling.md" [label="profile async perf,\nactor contention"];
}

1. 数据竞争／Actor 隔离／@MainActor／Sendable／Swift 6 迁移？→ skills/swift-concurrency.md 1a. 需要特定 API 语法（Actor 定义、TaskGroup、AsyncStream、continuations）？→ skills/swift-concurrency-ref.md 1b. NotificationCenter 观察者、userInfo 类型转换，或解包通知时出现 Sendable 错误？→ skills/swift-concurrency-ref.md（Typed Notifications — MainActorMessage/AsyncMessage，iOS 26+）
2. 编写 async/await 代码？→ skills/swift-concurrency.md
3. assumeIsolated / @preconcurrency？→ skills/assume-isolated.md 3a. Swift 6 构建无警告，但在生产环境中因 _dispatch_assert_queue_fail 或 _swift_task_checkIsolatedSwift 而崩溃？→ skills/isolation-inheritance-diag.md
4. Mutex / 锁 / 同步？→ skills/synchronization.md
5. 分析异步性能／Actor 争用？→ skills/concurrency-profiling.md
6. 值类型／ARC／泛型优化？→ 参见 axiom-performance（skills/swift-performance.md）
7. borrowing / consuming / ~Copyable？→ 参见 axiom-swift（skills/ownership-conventions.md）
8. Combine / @Published / AnyCancellable / 响应式流？→ 参见 axiom-uikit（skills/combine-patterns.md）
9. 想要自动化并发扫描？→ concurrency-auditor（Agent）

实践中的并发

• 使用 Swift Concurrency 执行 HealthKit 查询（规范桥接示例）→ 参见 axiom-health（skills/queries.md）

冲突解决

concurrency 与 axiom-performance：当应用卡顿或感觉运行缓慢时：

1. 先尝试 concurrency——主线程阻塞是 UI 卡顿的首要原因。在进行性能分析之前，先检查 @MainActor 上是否有同步工作。
2. 仅当并发修复无效时才使用 axiom-performance——排除明显的阻塞后再进行性能分析。
3. 要将特定卡顿定位到应用代码，请参见 axiom-performance 中的 Hang Window Workflow（skills/hang-diagnostics.md）——使用 --start-ms/--end-ms --user-binary 将 xcprof analyze 的分析范围重新限定到卡顿时间窗口，以呈现主线程上由应用拥有的栈帧。

concurrency 与 axiom-build：遇到 Swift 6 并发错误时：

• 使用 concurrency，而非 axiom-build——并发错误属于代码问题，而非环境问题。

concurrency 与 axiom-data：并发错误涉及 Core Data 或 SwiftData 时：

• Core Data 线程问题（NSManagedObjectContext 线程限制）→ 优先使用 axiom-data
• SwiftData + @MainActor ModelContext → 使用 concurrency
• 一般性的“后台保存导致数据丢失”问题 → 优先使用 axiom-data
• GRDB Sendable 模式（struct 记录、作为计算属性的 databaseSelection、Swift 6 一致性）→ 参见 axiom-data（skills/grdb-performance.md）§8

关键模式

Swift 并发（skills/swift-concurrency.md）：

• 渐进式路径：单线程 → 异步 → 并发 → actor
• 使用 @concurrent 特性强制在后台执行
• 隔离一致性、主 actor 模式
• 12 个可直接复制粘贴的模式，包括委托值捕获、在 Tasks 中使用 weak self
• 针对 7 种常见错误消息的全面决策树

API 参考（skills/swift-concurrency-ref.md）：

• Actor 定义、可重入性、全局 actor、nonisolated
• Sendable 模式、@unchecked Sendable、sending 参数
• Task/TaskGroup/取消、async let、withDiscardingTaskGroup
• AsyncStream、continuation、缓冲策略
• 隔离模式（#isolation、@preconcurrency、nonisolated(unsafe)）
• DispatchQueue/DispatchGroup/completion handler 迁移

同步（skills/synchronization.md）：

• Mutex（iOS 18+）、OSAllocatedUnfairLock（iOS 16+）、Atomic 类型
• Lock 与 actor 的选择决策树
• 危险模式：在 await 期间持有锁、在异步上下文中使用信号量

性能分析（skills/concurrency-profiling.md）：

• Swift Concurrency Instruments 模板
• 诊断主线程阻塞、actor 争用、线程池耗尽
• 协作式线程池中安全与不安全的原语

运行时隔离崩溃（skills/isolation-inheritance-diag.md）：

• _dispatch_assert_queue_fail 和 _swift_task_checkIsolatedSwift 签名
• 闭包隔离继承（Core Data perform、Combine .map、NotificationCenter .sink）
• 委托方法隔离继承（CLLocationManager、NSDocument、AVAudioPlayerDelegate、WKNavigationDelegate）
• 错误使用 MainActor.assumeIsolated
• Actor 可重入导致的状态过时

自动扫描

并发审计 → 启动 concurrency-auditor Agent 或运行 /axiom:audit concurrency（5 阶段语义审计：梳理隔离架构、检测 8 种反模式、推断缺失的并发模式、关联复合风险、评估 Swift 6.4 就绪度）

反合理化

想法	事实
“只要加上 @MainActor 就能解决”	@MainActor 有隔离继承规则。skills/swift-concurrency.md 涵盖所有模式。
“我会用 nonisolated(unsafe) 消除警告”	消除警告会掩盖数据竞争。skills/swift-concurrency.md 展示了安全模式。
“这只是一次 async 调用”	即使只有一次 async 调用，也会涉及取消和隔离。
“我知道 actor 的工作原理”	Swift 6.2 中 actor 可重入性和隔离规则发生了变化。
“我稍后再修复 Sendable 警告”	违反 Sendable 会导致运行时崩溃。现在就修复。
“我的 Swift 6 构建没有任何警告，所以隔离没问题”	静态检查看不到 SDK 回调。运行时检查仍会导致崩溃。参见 skills/isolation-inheritance-diag.md。
“我会用 MainActor.assumeIsolated 包住崩溃”	assumeIsolated 是运行时陷阱，不是消音器。假设错误就会崩溃。
“Combine 已经过时了，直接用 async/await 就行”	Combine 没有弃用通知。重写正常工作的管线是在浪费时间。参见 See axiom-uikit（skills/combine-patterns.md）。
“我会用 @unchecked Sendable 消除这个问题”	你是在向编译器隐瞒数据竞争。它会在生产环境中崩溃。
“这个异步函数会在后台线程运行”	检查它的隔离方式，不要想当然。@MainActor 异步函数完全在主 actor 上运行，而在 NonisolatedNonsendingByDefault 下（Swift 6.2+；新的 Xcode 项目会设置 SWIFT_APPROACHABLE_CONCURRENCY = YES，但该设置自身的默认值为 NO，SwiftPM 也不会启用它），nonisolated async 会运行在调用方的 actor 上——这正是导致主线程卡顿的原因。未启用该设置时，nonisolated async 会切换到全局执行器。无论哪种情况，@concurrent 都会强制在 actor 外执行工作。

示例调用

用户：“我在 Swift 6 中遇到了‘数据竞争’错误” → 阅读：skills/swift-concurrency.md

用户：“如何正确使用 @MainActor？” → 阅读：skills/swift-concurrency.md

用户：“如何创建 TaskGroup？” → 阅读：skills/swift-concurrency-ref.md

用户：“AsyncStream API 是什么？” → 阅读：skills/swift-concurrency-ref.md

用户：“如何使用 assumeIsolated？” → 阅读：skills/assume-isolated.md

用户：“我应该使用 Mutex 还是 actor？” → 阅读：skills/synchronization.md

用户：“我的异步代码运行很慢，该如何分析性能？” → 阅读：skills/concurrency-profiling.md

用户：“我的 Swift 6 构建没有警告，但在生产环境中因 _dispatch_assert_queue_fail 而崩溃” → 阅读：skills/isolation-inheritance-diag.md

用户：“Core Data 的 context.perform 在 @MainActor 视图模型中崩溃” → 阅读：skills/isolation-inheritance-diag.md

用户：“CLLocationManager 代理方法因 _swift_task_checkIsolatedSwift 而崩溃” → 阅读：skills/isolation-inheritance-diag.md

用户：“我的应用因不必要的复制而运行缓慢” → 查看 axiom-performance（skills/swift-performance.md）

用户：“检查我的代码是否存在 Swift 6 并发问题” → 调用：concurrency-auditor Agent