swiftui-expert-skill

SwiftUI 专家技能

何时使用

在编写、审查或重构 iOS 或 macOS 的 SwiftUI 代码时使用，包括状态管理与 @Observable 数据流、视图组合与失效/性能、列表与 ForEach 标识、环境使用、本地化、动画、Liquid Glass 采用、迁移……

操作规则

• 在每个任务开始时查阅 references/latest-apis.md，以避免使用已弃用的 API
• 优先使用原生 SwiftUI API，而非 UIKit/AppKit 桥接，除非桥接确有必要
• 关注正确性与性能；不要强制特定架构（MVVM、VIPER 等）
• 鼓励将业务逻辑与视图分离以便于测试，但不要强制规定方式
• 遵循 Apple 的人机界面指南和 API 设计模式
• 仅在用户明确要求时才采用 Liquid Glass（参见 references/liquid-glass.md）
• 将性能优化作为建议呈现，而非要求
• 对特定版本的 API 使用 #available 进行门控，并提供合理的回退方案

任务工作流

审查现有 SwiftUI 代码

• 阅读待审查的代码，确定哪些主题适用
• 标记已弃用的 API（与 references/latest-apis.md 对比）
• 对每个相关主题运行下方的主题路由器
• 验证 iOS 26+ 功能的 #available 门控和回退路径

改进现有 SwiftUI 代码

• 对照主题路由器中的主题审查当前实现
• 用 references/latest-apis.md 中的现代等效 API 替换已弃用的 API
• 重构热路径以减少不必要的状态更新
• 将复杂的视图 body 提取为单独的子视图
• 遇到 UIImage(data:) 时建议进行图像降采样（可选优化，参见 references/image-optimization.md）

实现新的 SwiftUI 功能

• 首先设计数据流：确定自有状态与注入状态
• 为最佳 diffing 组织视图结构（尽早提取子视图）
• 应用正确的动画模式（隐式与显式、过渡）
• 对所有可点击元素使用 Button；添加无障碍分组和标签
• 对特定版本的 API 使用 #available 进行门控并提供回退方案

记录新的 Instruments trace

当用户要求“record a trace”、“profile the app”、“capture a session”等时触发。完整参考：references/trace-recording.md。

1. 确认目标 —— 附加到正在运行的应用、启动一个应用，还是记录所有进程？如果用户没有说明，请询问。在有用时列出已连接的设备：

   python3 "${SKILL_DIR}/scripts/record_trace.py" --list-devices
   

2. 根据目标类型选择模板 —— SwiftUI 模板会在任何真实设备上填充 SwiftUI 泳道：物理 iOS/iPadOS 设备或宿主机 Mac。唯一的例外是 iOS 模拟器，此时 SwiftUI 泳道会返回为空——在这种情况下改用 --template "Time Profiler"（仍会提供 Time Profiler + Hangs + Animation Hitches）。始终检查 --list-devices：simulators 类型 → Time Profiler；devices 类型（真实设备和宿主机 Mac）→ 默认 SwiftUI。完整决策表见 references/trace-recording.md。
3. 开始记录。对于由 Agent 驱动、用户表示“我完成时会告诉你”的会话，请在后台启动并使用停止文件：

   python3 "${SKILL_DIR}/scripts/record_trace.py" \
       --device "<name|udid>" --attach "<AppName>" \
       --stop-file /tmp/stop-trace --output ~/Desktop/session.trace
   

   对于交互式会话，只需告诉用户完成后按 Ctrl+C。
4. 发出停止信号 —— 当用户表示已完成对应用的操练后，执行 touch /tmp/stop-trace。该脚本会干净地向 xctrace 发送 SIGINT，并最多等待 60 秒以完成收尾。
5. 分析生成的 trace（流入下方的“Trace 驱动的改进”工作流）。

追踪驱动的改进（提供 Instruments .trace）

当用户的请求引用 .trace 文件时触发。目标 SwiftUI 源文件是可选的——如果提供了，就引用具体行；如果没有，就根据追踪已揭示的视图名称和符号，推荐应查看的位置。

完整参考：references/trace-analysis.md。组合模式摘要：

1. 界定分析范围。 问问自己：用户想要整个追踪，还是一个切片？
   • “focus on X / after X / between X and Y / during X” → 先解析出一个窗口（见第 2 步）。
   • 没有范围线索 → 分析整个追踪。
2. 解析窗口（仅在用户限定了范围时）。 解析器提供两种发现模式：

   # Find a log that marks the start/end of the region of interest:
   python3 "${SKILL_DIR}/scripts/analyze_trace.py" --trace <path> \
       --list-logs --log-message-contains "loaded feed" --log-limit 5
   # Or list os_signpost intervals (paired begin/end), filterable by name:
   python3 "${SKILL_DIR}/scripts/analyze_trace.py" --trace <path> \
       --list-signposts --signpost-name-contains "ImageDecode"
   

   两种模式都接受 --window START_MS:END_MS 来限定发现范围。选择与用户描述匹配的 time_ms（用于日志）或 start_ms/end_ms（用于 signposts）。构建类似 --window 10400:11700 的窗口。
3. 运行主分析（带或不带 --window）：

   python3 "${SKILL_DIR}/scripts/analyze_trace.py" --trace <path> \
       --json-only --top 10 [--window START_MS:END_MS]
   

4. 结合 references/trace-analysis.md 解读——关键诊断：
   • 每个 correlation 内的 main_running_coverage_pct（<25% = 阻塞；≥75% = CPU 密集）。
   • swiftui-causes.top_sources 揭示更新为何持续发生——高边数的来源（如 UserDefaultObserver.send() 或宽泛的 EnvironmentWriter 条目）是结构性的失效 bug。修复一个常常会让许多下游的热点视图一起收敛。
5. 当某个具体视图显示为高开销时，问问是谁在使它失效。 使用 --fanin-for "<view name>" 获取驱动更新的来源节点的排序列表。
6. 可选地回到源码求证。 如果用户指向了某个文件，就读取它，并将视图名称 / 用户代码符号与该处的标识符匹配。如果没有，就根据 SwiftUI 报告的视图名称推荐应打开哪些文件。
7. 返回一份按优先级排序的方案。 引用证据（覆盖率 %、热点符号、重叠视图、日志时间戳、因果图边），并将每条建议路由到 Topic Router 参考。
8. 只有在用户要求修改代码时才编辑代码。

Topic Router

针对与当前任务相关的每个主题，查阅对应的参考文件：

主题	参考
状态管理	references/state-management.md
视图组合	references/view-structure.md
性能	references/performance-patterns.md
列表与 ForEach	references/list-patterns.md
布局	references/layout-best-practices.md
Sheet 与导航	references/sheet-navigation-patterns.md
ScrollView	references/scroll-patterns.md
焦点管理	references/focus-patterns.md
动画（基础）	references/animation-basics.md
动画（转场）	references/animation-transitions.md
动画（进阶）	references/animation-advanced.md
无障碍	references/accessibility-patterns.md
Swift Charts	references/charts.md
Charts 无障碍	references/charts-accessibility.md
图像优化	references/image-optimization.md
Liquid Glass (iOS 26+)	references/liquid-glass.md
macOS 场景	references/macos-scenes.md
macOS 窗口样式	references/macos-window-styling.md
macOS 视图	references/macos-views.md
文本模式	references/text-patterns.md
本地化	references/localization.md
已弃用 API 查询	references/latest-apis.md
处理软弃用 API	references/soft-deprecation.md
预览	references/previews.md
Instruments 追踪分析	references/trace-analysis.md
Instruments 追踪录制	references/trace-recording.md

正确性检查清单

以下是硬性规则——违反即 bug：

• @State 属性为 private
• 仅在子视图修改父视图状态时使用 @Binding
• 传入的值绝不声明为 @State 或 @StateObject（它们会忽略更新）
• 视图自有的对象使用 @StateObject；注入的对象使用 @ObservedObject
• iOS 17+：@State 配合 @Observable；需要绑定的注入可观察对象使用 @Bindable
• ForEach 使用稳定标识（绝不使用 .indices/\.offset；id 的生命周期长于视图，且不派生自可变内容）
• 每个 ForEach 元素的视图数量恒定；List 行是单元素
• 自定义 @Environment/@FocusedValue 键中不存储闭包
• 自定义 @Entry 默认值稳定（不含 Model()/Date()/UUID() 表达式）
• .animation(_:value:) 始终包含 value 参数
• @FocusState 属性为 private
• .focusable() 视图的点击手势处理程序内没有多余的 @FocusState 写入
• iOS 26+ API 使用 #available 进行门控并提供回退方案
• 使用图表类型的文件中包含 import Charts
• 预览使用自包含的模拟数据；不依赖实时服务或网络

参考资料

• references/latest-apis.md —— 每项任务都应首先阅读。 从已弃用到现代的 API 变迁（iOS 15+ 至 iOS 26+）
• references/state-management.md —— 属性包装器、数据流、@Observable 迁移
• references/view-structure.md —— 视图抽取、容器模式、@ViewBuilder
• references/performance-patterns.md —— 热路径优化、更新控制、_logChanges()
• references/list-patterns.md —— ForEach 标识、Table（iOS 16+）、内联过滤的陷阱
• references/layout-best-practices.md —— 布局模式、GeometryReader 的替代方案
• references/accessibility-patterns.md —— VoiceOver、动态字体、分组、特征
• references/animation-basics.md —— 隐式/显式动画、时序、性能
• references/animation-transitions.md —— 视图转场、matchedGeometryEffect、Animatable
• references/animation-advanced.md —— 阶段/关键帧动画（iOS 17+）、@Animatable 宏（iOS 26+）
• references/charts.md —— Swift Charts 标记、坐标轴、选择、样式、Chart3D（iOS 26+）
• references/charts-accessibility.md —— Charts 的 VoiceOver、Audio Graph、降级策略
• references/sheet-navigation-patterns.md —— Sheet、NavigationSplitView、Inspector
• references/scroll-patterns.md —— ScrollViewReader、程序化滚动
• references/focus-patterns.md —— 焦点状态、可聚焦视图、聚焦值、默认焦点、常见陷阱
• references/image-optimization.md —— AsyncImage、降采样、缓存
• references/liquid-glass.md —— iOS 26+ Liquid Glass 效果与降级模式
• references/macos-scenes.md —— Settings、MenuBarExtra、WindowGroup、多窗口
• references/macos-window-styling.md —— 工具栏样式、窗口尺寸、Commands
• references/macos-views.md —— HSplitView、Table、PasteButton、AppKit 互操作
• references/previews.md —— #Preview 宏、@Previewable（iOS 18+）、预览特征、用于自包含预览的模拟数据模式
• references/text-patterns.md —— Text 初始化器的选择、原样文本与本地化文本
• references/localization.md —— String Catalogs、用于包的 #bundle、LocalizedStringResource、区域感知格式化、RTL 布局、译者注释
• references/soft-deprecation.md —— 面对软弃用 API 时的处理方式（何时迁移、作用域规则、不要在不相关的编辑中迁移）
• references/trace-analysis.md —— 通过 scripts/analyze_trace.py 解析 Instruments .trace 文件；解读主线程覆盖率、高严重性 SwiftUI 更新、卡顿叙述，并将发现映射回源文件
• references/trace-recording.md —— 通过 scripts/record_trace.py 录制新的 trace：附加到正在运行的应用、启动一个全新的应用，或捕获手动停止的会话；支持用于 Agent 驱动流程的停止文件

限制

• 仅当任务明确符合其上游来源和本地项目上下文时，才使用此技能。
• 在应用更改之前，请验证命令、生成的代码、依赖项、凭据以及外部服务行为。
• 不要将示例视为针对具体环境的测试、安全审查或对破坏性或高成本操作的用户批准的替代品。