axiom-swift

Swift 语言与平台

对于任何 Swift 惯用写法审查、所有权／不可复制类型、Transferable／拖放、调试深层链接或 tvOS 开发，你都必须使用此技能。

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

此处可用：skills/swift-simplifier.md。

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

快速参考

症状／任务	参考
过时的 Swift 模式（Date()、CGFloat、DateFormatter）	请参阅 skills/swift-modern.md
Foundation 现代化（FormatStyle、URL.documentsDirectory）	请参阅 skills/swift-modern.md
Claude 在 Swift 代码中常见的幻觉	请参阅 skills/swift-modern.md
Swift 6.4 惯用写法 — anyAppleOS、weak let、~Sendable（OS27）	请参阅 skills/swift-modern.md
不可复制类型（~Copyable）	请参阅 skills/ownership-conventions.md
borrowing/consuming 参数所有权	请参阅 skills/ownership-conventions.md
InlineArray、Span、值泛型；Swift 6.4 borrow/mutate 访问器（OS27）	请参阅 skills/ownership-conventions.md
降低 ARC 开销	请参阅 skills/ownership-conventions.md
拖放（.draggable、.dropDestination）	请参阅 skills/transferable-ref.md
复制／粘贴（.copyable、PasteButton）	请参阅 skills/transferable-ref.md
ShareLink、内容共享	请参阅 skills/transferable-ref.md
自定义 UTType 声明	请参阅 skills/transferable-ref.md
TransferRepresentation 选择	请参阅 skills/transferable-ref.md
仅用于模拟器测试的调试深层链接	请参阅 skills/deep-link-debugging.md
导航至特定屏幕以截取屏幕截图	请参阅 skills/deep-link-debugging.md
tvOS 焦点引擎、Siri Remote 输入	请参阅 skills/tvos.md
tvOS 存储限制（本地存储无法保证持久性）	请参阅 skills/tvos.md
tvOS 文本输入、AVPlayer 调优	请参阅 skills/tvos.md
TVUIKit 组件	请参阅 skills/tvos.md
简化 Swift 以提升清晰度（保持行为不变的清理）	swift-simplifier Agent — /axiom:audit swift-simplify

决策树

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

    start -> what;
    what -> "skills/swift-modern.md" [label="modern idioms,\noutdated patterns,\nFoundation APIs"];
    what -> "skills/ownership-conventions.md" [label="~Copyable, borrowing,\nconsuming, InlineArray,\nSpan, ARC reduction"];
    what -> "skills/transferable-ref.md" [label="drag & drop, copy/paste,\nShareLink, UTTypes,\nTransferable conformance"];
    what -> "skills/deep-link-debugging.md" [label="debug deep links,\nsimulator navigation,\nscreenshot automation"];
    what -> "skills/tvos.md" [label="tvOS app,\nFocus Engine,\nSiri Remote, storage"];
}

1. 过时的 Swift 模式／现代 API 替换／Claude 幻觉？ -> skills/swift-modern.md
2. ~Copyable／borrowing／consuming／InlineArray／Span？ -> skills/ownership-conventions.md
3. 拖放／复制粘贴／ShareLink／Transferable／UTTypes？ -> skills/transferable-ref.md
4. 调试深层链接／模拟器导航／截图自动化？ -> skills/deep-link-debugging.md
5. tvOS 开发／焦点引擎／Siri Remote／存储／AVPlayer？ -> skills/tvos.md
6. Swift 并发（async/await、actors、Sendable）-> /skill axiom-concurrency
7. Swift 性能（COW、ARC、泛型优化）-> 请参阅 axiom-performance（skills/swift-performance.md）
8. Codable 模式（JSON、CodingKeys、枚举序列化）-> 请参阅 axiom-data（skills/codable.md）
9. 简化 Swift 以提升清晰度（guard／可选值清理、if/switch 表达式、样板代码）？ -> swift-simplifier Agent（/axiom:audit swift-simplify）

冲突解决

swift 与 concurrency：出现 Swift 6 并发错误时：

• 使用 concurrency，而不是 swift——并发错误是 Actor 隔离或 Sendable 问题。skills/swift-modern.md 介绍并发的默认做法，但详细模式在 axiom-concurrency 中。

swift 与 performance：优化 Swift 代码时：

• 如果问题涉及借用、消耗、~Copyable、InlineArray 或 Span 的所有权，使用 swift -> skills/ownership-conventions.md
• 如果问题涉及 COW、ARC 性能分析、泛型特化或 Instruments 工作流，使用 performance -> axiom-performance

swift 与 swiftui：实现拖放或复制/粘贴时：

• 对于 Transferable 一致性、表示形式选择和 UTType 声明，使用 swift -> skills/transferable-ref.md
• 对于视图级修饰符（.draggable、.dropDestination 样式、动画），使用 swiftui

swift 与 integration：分享内容时：

• ShareLink + Transferable -> 使用 swift（skills/transferable-ref.md）
• UIActivityViewController 自定义、分享扩展 -> 使用 integration

swift 与 axiom-build：tvOS 构建失败时：

• 环境/Xcode 问题 -> 优先使用 axiom-build
• tvOS 平台特定代码问题（Focus Engine、存储、无 WebView）-> 使用 swift（skills/tvos.md）

关键模式

现代 Swift 惯用写法（skills/swift-modern.md）：

• Claude 默认采用的 12+ 种过时模式（Date()、CGFloat、DateFormatter、DispatchQueue.main.async）
• Foundation 现代化（FormatStyle、URL.documentsDirectory、.replacing()）
• Claude 容易遗漏的 SwiftUI 便捷 API（ContentUnavailableView.search、LabeledContent）
• Swift 6.4 并发默认做法
• 12+ 种常见的 Claude 幻觉及其纠正方法

所有权与不可复制类型（skills/ownership-conventions.md）：

• 借用/消耗参数修饰符及 7 种模式
• ~Copyable 类型：FileHandle 模式、限制表、常见编译器错误
• InlineArray：使用值泛型的固定大小栈分配数组
• Span 系列：以安全的连续内存访问替代 UnsafeBufferPointer
• 判断何时使用所有权修饰符、何时跳过的决策树

Transferable 与分享（skills/transferable-ref.md）：

• 决策树：CodableRepresentation、DataRepresentation、FileRepresentation 与 ProxyRepresentation
• 拖放、复制/粘贴、ShareLink，包含完整的 SwiftUI API
• 自定义 UTType 声明（Swift + Info.plist，两者缺一不可）
• 7 种常见错误及修复方法（表示形式排序、缺少 Info.plist、命中测试）
• 通过 NSItemProvider 与 UIKit 桥接

调试深层链接（skills/deep-link-debugging.md）：

• 用于模拟器导航的仅调试 URL 方案
• 集成 NavigationPath，实现可靠路由
• 状态配置链接（错误状态、空状态）
• 与 /axiom:screenshot 和 simulator-tester Agent 集成
• 通过可视化验证，将迭代速度提升 60-75%

tvOS 开发（skills/tvos.md）：

• 双重焦点系统（UIKit Focus Engine + SwiftUI @FocusState）
• Siri Remote 输入（两代设备、三个输入层）
• 存储限制（无法保证本地存储持久化；需要 iCloud）
• 无 WebView（仅 JavaScriptCore，不支持 DOM）
• AVPlayer 调优、Menu 按钮状态机
• TVUIKit 组件

反合理化

想法	现实
“Date() 没问题，大家都这么用”	自 Swift 5.6 起，Date.now 就是现代写法。skills/swift-modern.md 列出了 Claude 常犯的 12 种以上错误。
“我不需要所有权修饰符”	对大多数代码来说，确实如此。但 ~Copyable 类型必须使用它们，而热路径中的大型值类型也能从中获得可衡量的性能提升。
“Transferable 只是用于拖放的 Codable”	Transferable 有 4 种表示类型、排序规则和 Info.plist 要求。用错会导致跨应用失败，而且不会报错。
“我直接把 iOS 代码用在 tvOS 上就行”	tvOS 不保证本地存储持久化，没有 WebView，采用双焦点系统，还要支持两代遥控器硬件。代码可以顺利编译，却会在运行时失败。
“调试深层链接太麻烦了”	手动导航每次迭代要花 2-3 分钟。深层链接能将时间缩短到 45 秒。一次调试下来，可以省下数小时。
“SwiftUI 用的就是 CGFloat”	Swift 5.5+ 支持隐式的 Double-CGFloat 桥接。除可选值、inout 和 ObjC 桥接 API 外，其他地方都用 Double。
“我之后再添加 Info.plist 条目”	自定义 UTTypes 在应用内无需 Info.plist 就能使用，但跨应用时会悄无声息地失败。这是 Transferable 最常见的“开发环境正常，生产环境出错”问题。
“FormatStyle 太冗长了”	val.formatted(.number.precision(.fractionLength(2))) 具有类型安全性，且支持本地化。String(format:) 两者都不具备。

调用示例

用户：“这段 Swift 代码用了现代写法吗？” -> 阅读：skills/swift-modern.md

用户：“如何使用 borrowing 和 consuming？” -> 阅读：skills/ownership-conventions.md

用户：“如何让我的模型支持拖动？” -> 阅读：skills/transferable-ref.md

用户：“如何用自定义预览实现 ShareLink？” -> 阅读：skills/transferable-ref.md

用户：“我需要用于模拟器测试的调试深层链接” -> 阅读：skills/deep-link-debugging.md

用户：“我正在开发 tvOS 应用，焦点导航不起作用” -> 阅读：skills/tvos.md

用户：“什么是 InlineArray？我应该在什么时候使用它？” -> 阅读：skills/ownership-conventions.md

用户：“我的拖放功能在应用内正常，但跨应用不行” -> 阅读：skills/transferable-ref.md

用户：“tvOS 总是丢失我保存的数据” -> 阅读：skills/tvos.md

用户：“如何优化大型结构体的传递？” -> 阅读：skills/ownership-conventions.md

用户：“我需要修复 async/await 代码” -> 查看 /skill axiom-concurrency

用户：“检查我的代码是否存在 Swift 6 并发问题” -> 查看 /skill axiom-concurrency