Swift并发代理技能

针对支持Agent Skills开放格式的任何AI编码工具提供的专家级指导——安全的并发编程、性能优化以及Swift 6及以上版本的迁移。

本技能基于全面的Swift并发课程，提炼为可供代理使用的可操作、简洁的参考指南。

适用人群

• 正在迁移到Swift 6/严格并发模型，需要安全默认设置和快速问题排查的团队。
• 需要调试数据竞争、隔离错误或不稳定异步测试的开发者。
• 希望采用注重性能的并发模式（Actor、Task、Sendable、异步流）的任何人。

另请参阅我的其他技能：

• SwiftUI专家
• Core Data专家
• Swift测试专家

如何使用本技能

方案A：使用skills.sh（推荐）

只需一条命令即可安装本技能：

npx skills add https://github.com/avdlee/swift-concurrency-agent-skill --skill swift-concurrency

更多信息，请访问skills.sh平台页面。

然后在您的AI代理中使用该技能，例如：

使用Swift并发技能，分析当前项目以寻找Swift并发方面的改进点

方案B：Claude Code插件

个人使用

要在Claude Code中为个人使用安装本技能：

1. 添加市场：

   /plugin marketplace add AvdLee/Swift-Concurrency-Agent-Skill
   

2. 安装技能：

   /plugin install swift-concurrency@swift-concurrency-agent-skill
   

项目配置

要自动为所有在仓库中工作的人员提供此技能，请配置仓库的.claude/settings.json文件：

{
  "enabledPlugins": {
    "swift-concurrency@swift-concurrency-agent-skill": true
  },
  "extraKnownMarketplaces": {
    "swift-concurrency-agent-skill": {
      "source": {
        "source": "github",
        "repo": "AvdLee/Swift-Concurrency-Agent-Skill"
      }
    }
  }
}

当团队成员打开项目时，Claude Code会提示他们安装该技能。

方案C：使用pi包管理器

通过pi安装：

pi install https://github.com/AvdLee/Swift-Concurrency-Agent-Skill

该技能将自动在pi会话中可用。

方案D：手动安装

1. 克隆此仓库。
2. 安装或创建符号链接到swift-concurrency/文件夹，按照您所用工具的官方技能安装文档操作（见下方链接）。
3. 正常使用您的AI工具，并要求其使用“swift-concurrency”技能来处理Swift并发相关任务。

技能保存位置

请遵循您所用工具的官方文档，以下是一些常用工具的说明：

• Codex: 技能保存位置
• Claude: 使用技能
• Cursor: 启用技能

验证方法：

您的代理应参考swift-concurrency/SKILL.md中的问题排查手册，并跳转到与您遇到的错误或任务相关的参考文件。

本技能提供的内容

本技能为您的AI编码工具提供全面的Swift并发编程指导。它可以：

指导您的并发决策

• 选择适合任务的工具（async/await、Actor、Task、Task Group）
• 理解何时使用@MainActor、自定义Actor或nonisolated
• 管理隔离域并在编译时防止数据竞争
• 正确应用Sendable协议，适用于值类型和引用类型

编写安全的并发代码

• 避免常见的陷阱，如Actor重入和循环引用
• 通过适当的隔离机制防止数据竞争
• 正确处理任务取消和错误传播
• 在并发上下文中安全地管理内存

优化性能

• 在串行、异步和并行执行之间做出选择
• 减少Actor争用和不必要的挂起点
• 理解并行化的权衡

迁移到Swift 6

• 针对现有代码库的逐步迁移策略
• 逐步启用严格的并发检查
• 将基于闭包的代码重写为async/await
• 从Combine/RxSwift迁移到Swift并发
• 利用迁移工具处理即将推出的Swift新特性

测试并发代码

• 使用Swift Testing（推荐）或XCTest编写可靠的测试
• 处理测试中的@MainActor隔离
• 使用withMainSerialExecutor进行确定性测试
• 通过正确的异步处理避免测试不稳定

与Core Data集成

• 使用NSManagedObjectID在隔离域之间安全传递数据
• 实现数据访问对象（DAO）模式
• 必要时使用自定义Actor执行器
• 避免常见的Core Data并发陷阱

本技能的独特之处

专家知识：基于将大型生产代码库迁移到Swift 6的实际经验，源自全面的Swift并发课程。

不带偏见：专注于行业标准的最佳实践和编译时安全性，而非架构偏好。适用于任何Swift项目、编码风格或架构。

兼容Swift 6.2：涵盖最新的Swift并发特性，包括：

• 默认Actor隔离
• isolated deinit
• 协议的全局Actor一致性
• nonisolated(nonsending)和@concurrent
• 易于理解的并发构建设置
• 并发安全的通知功能（iOS 26+）

实用且简洁：假设您的AI代理已经足够智能。专注于开发者真正需要了解的内容，而非他们已经掌握的知识。为每种模式都提供了代码示例。

观看实际演示

技能结构

swift-concurrency/
├── SKILL.md                # 包含决策树的主技能文件
└── references/
    ├── _index.md               # 待添加描述
    ├── actors.md               # Actor 隔离、全局 Actor、可重入性
    ├── async-algorithms.md     # 待添加描述
    ├── async-await-basics.md   # async/await 语法基础
    ├── async-sequences.md      # AsyncSequence 和 AsyncStream 模式
    ├── core-data.md            # Core Data 集成模式
    ├── glossary.md             # Swift 并发相关术语与概念
    ├── linting.md              # 用于严格并发的 Lint 规则
    ├── memory-management.md    # 强引用循环、weak self、隔离的析构
    ├── migration.md            # Swift 6 迁移分步指南
    ├── performance.md          # 使用 Xcode Instruments 进行优化
    ├── sendable.md             # 隔离域与 Sendable 协议一致性
    ├── tasks.md                # Task 生命周期、取消、优先级
    ├── testing.md              # 并发代码测试
    └── threading.md            # 线程与 Task 的区别、挂起点

贡献说明

欢迎贡献！本仓库遵循 Agent Skills 开放格式，该格式有特定的结构要求。

我们强烈建议使用 AI 辅助进行贡献：

• 使用 skill-creator 技能 配合 Claude，以确保格式正确。
• 这有助于保持 Agent Skills 格式，并确保您的贡献能够与 AI 助手正常协作。

请阅读 CONTRIBUTING.md，了解：

• 如何使用 skill-creator 技能进行贡献
• Agent Skills 格式的具体要求
• 质量标准与最佳实践
• 拉取请求流程

本技能旨在反映最新的 Swift 并发最佳实践，并将随着语言的发展不断更新。

关于作者

由 Antoine van der Lee 创建，他是 Swift 并发领域的专家，同时也是 Swift 并发课程 的创建者。凭借多年在 Swift 及 Swift 并发方面的经验，他将实用知识提炼为可供 AI 助手使用的可操作指南。他在名为 SwiftLee 的博客上发表了数十篇关于 Swift 并发的文章。

许可证

本技能为开源项目，采用 MIT 许可证。详情请参阅 LICENSE 文件。

Swift-Concurrency-Agent-Skill 快速上手指南

本指南帮助中国开发者快速集成 Swift-Concurrency-Agent-Skill，为 AI 编程助手提供专家级的 Swift 并发（Swift 6+）迁移、调试及性能优化指导。

环境准备

在开始之前，请确保满足以下前置条件：

• 操作系统：macOS（推荐最新稳定版）。
• 开发工具：已安装 Xcode 及 Command Line Tools。
• AI 工具：已安装支持 Agent Skills 格式的 AI 编程工具（如 Claude Code, Cursor, Codex 等）。
• 运行时依赖：
  • Node.js (用于 skills.sh 安装方式)
  • 或者 pi 包管理器（可选）

安装步骤

根据你的使用习惯，选择以下任意一种方式进行安装：

方式 A：使用 skills.sh（推荐）

这是最通用的安装方式，适用于大多数支持该标准的 AI 代理。

1. 打开终端，运行以下命令安装技能：

   npx skills add https://github.com/avdlee/swift-concurrency-agent-skill --skill swift-concurrency
   

2. 安装完成后，该技能将自动注册到你的 AI 代理环境中。

方式 B：Claude Code 插件

如果你主要使用 Claude Code，可以通过插件市场安装。

个人使用

在 Claude Code 会话中依次执行：

/plugin marketplace add AvdLee/Swift-Concurrency-Agent-Skill
/plugin install swift-concurrency@swift-concurrency-agent-skill

团队项目配置

若需让团队成员自动获取此技能，请在项目根目录的 .claude/settings.json 中添加：

{
  "enabledPlugins": {
    "swift-concurrency@swift-concurrency-agent-skill": true
  },
  "extraKnownMarketplaces": {
    "swift-concurrency-agent-skill": {
      "source": {
        "source": "github",
        "repo": "AvdLee/Swift-Concurrency-Agent-Skill"
      }
    }
  }
}

方式 C：使用 pi 包管理器

如果你使用 pi 管理工具：

pi install https://github.com/AvdLee/Swift-Concurrency-Agent-Skill

方式 D：手动安装

1. 克隆仓库：

   git clone https://github.com/AvdLee/Swift-Concurrency-Agent-Skill.git
   

2. 将 swift-concurrency/ 文件夹 symlink 或复制到你的 AI 工具指定的 skills 目录（参考各工具官方文档，如 Cursor 或 Codex 的技能存放路径）。

基本使用

安装完成后，无需额外配置即可在对话中调用。你只需在提示词中明确指示 AI 使用该技能。

最简单的使用示例

在你的 AI 编程助手对话框中输入：

Use the swift concurrency skill and analyze the current project for Swift Concurrency improvements

中文指令示例：

使用 swift-concurrency 技能，分析当前项目并提出 Swift 并发改进建议。

典型应用场景

你可以针对具体任务发起请求，例如：

• 数据竞争调试：

  使用 swift-concurrency 技能帮我排查这个数据竞争警告，并给出修复方案。

• Swift 6 迁移：

  基于 swift-concurrency 技能，制定将本项目迁移到 Swift 6 严格并发模式的步骤。

• 代码模式优化：

  使用 swift-concurrency 技能，将这段基于 Combine 的代码重构为 async/await 模式。

• 单元测试编写：

  使用 swift-concurrency 技能，为这个 Actor 编写可靠的并发测试用例。

AI 将依据 SKILL.md 中的决策树和 references/ 目录下的专业文档，提供符合 Swift 6 标准的代码建议和解释。