swiftui-expert-skill

SwiftUI Expert Skill

操作准则

• 每个任务开始时，先查阅 references/latest-apis.md，避免使用已废弃的 API
• 除非必须进行桥接，否则优先使用原生 SwiftUI API，而不是 UIKit/AppKit 桥接方案
• 聚焦于代码正确性与性能表现；不强求特定的架构模式（如 MVVM、VIPER 等）
• 鼓励将业务逻辑与视图解耦以提升可测试性，但不对具体实现方式做强制规定
• 遵循 Apple 的《人机界面指南》（HIG）及 API 设计模式
• 仅在用户明确要求时才采用 Liquid Glass 样式（参见 references/liquid-glass.md）
• 将性能优化方案作为建议提出，而非硬性指标
• 对特定版本生效的 API 使用 #available 做版本隔离，并提供合理的降级兼容处理

任务工作流

审查现有的 SwiftUI 代码

• 阅读待审查的代码，识别涉及的技术主题
• 标记已废弃的 API（对照 references/latest-apis.md 核对）
• 根据涉及的各个主题，运行下方的“主题路由（Topic Router）”
• 校验 iOS 26+ 新特性的 #available 版本检查及降级兼容路径

优化现有的 SwiftUI 代码

• 对照主题路由中的技术主题，审计当前代码实现
• 将废弃 API 替换为 references/latest-apis.md 中推荐的现代替代方案
• 重构热点路径（hot paths），减少不必要的状态更新
• 将复杂的视图 body 拆分为独立的子视图
• 检测到 UIImage(data:) 时建议进行图片降采样（可选优化项，参见 references/image-optimization.md）

实现新的 SwiftUI 功能

• 优先设计数据流：明确区分视图自主持有的状态与外部注入的状态
• 合理规划视图结构以实现最佳 diff 性能（尽早拆分子视图）
• 应用正确的动画模式（隐式/显式动画、视图转场动画）
• 所有可点击元素统一使用 Button；补充无障碍分组与标签（accessibility grouping and labels）
• 对特定版本 API 使用 #available 做版本防护，并提供备用降级方案

录制新的 Instruments Trace

当用户提出“录制 trace”、“性能剖析（profile）”、“捕获会话”等需求时触发。完整参考：references/trace-recording.md。

1. 确认目标 — 是附加到正在运行的 App、启动新 App，还是录制所有进程？若用户未明确说明，先询问。必要时可列出已连接的设备：

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

2. 根据目标类型选择模板 — SwiftUI 模板可以在任何真机（实体 iOS/iPadOS 设备或宿主 Mac）上填充 SwiftUI 轨道（lane）。唯一的例外是 iOS 模拟器（iOS Simulator），在该环境下 SwiftUI 轨道数据为空 — 此时应切换为 --template "Time Profiler"（依然能获取 Time Profiler + Hangs + Animation Hitches）。务必先检查 --list-devices：simulators 类型 → Time Profiler；devices 类型（真机与宿主 Mac）→ 默认 SwiftUI。完整决策表参见 references/trace-recording.md。
3. 开始录制。对于 Agent 驱动的会话（用户表示“完成时我会告诉你”），请在后台启动并使用 stop-file：

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

   对于交互式会话，直接告知用户完成后按 Ctrl+C 终止即可。
4. 发送停止信号 — 当用户告知 App 操作测试完成后，执行 touch /tmp/stop-trace。脚本会平滑向 xctrace 发送 SIGINT 信号并等待最多 60 秒以收尾生成文件。
5. 分析生成的 trace 文件（切入下方的“基于 Trace 驱动的优化”工作流）。

基于 Trace 驱动的优化（已提供 Instruments .trace）

只要用户的请求中引用了 .trace 文件即触发。目标 SwiftUI 源码文件为可选 — 如果提供了源码文件，请引用具体行号；若未提供，请根据 trace 中已暴露的视图名称和符号推荐排查位置。

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

1. 确定分析范围。 思考：用户想要分析完整的 trace，还是其中的某个片段？
   • “关注 X / X 之后 / X 与 Y 之间 / X 运行期间” → 先确定时间窗口（window）（见步骤 2）。
   • 无明确范围指示 → 分析整个 trace。
2. 确定时间窗口（仅在用户指定了范围时）。 解析器提供两种探索模式：

   # 查找标记感兴趣区域起点/终点的日志：
   python3 "${SKILL_DIR}/scripts/analyze_trace.py" --trace <path> \
       --list-logs --log-message-contains "loaded feed" --log-limit 5
   # 或列出 os_signpost 区间（成对的 begin/end），支持按名称过滤：
   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 进行解读 — 核心诊断指标：
   • 每次关联数据中的 main_running_coverage_pct（<25% 表示主线程受阻/阻塞；≥75% 表示 CPU 密集型/瓶颈）。
   • swiftui-causes.top_sources 能揭示视图频繁刷新的根本原因 — 高出度（high-edge-count）数据源（例如 UserDefaultObserver.send() 或过于宽泛的 EnvironmentWriter 条目）通常属于结构性失效 Bug。修复其中一个往往就能级联消除大量下游热点视图的刷新。
5. 当某个具体视图显示开销巨大时，追查是谁导致了它失效。 使用 --fanin-for "<view name>" 获取触发其更新的源节点排名列表。
6. （可选）结合源码验证。 若用户指定了源码文件，阅读并匹配其中的视图名称/用户代码符号；若未指定，根据 SwiftUI 报告的视图名称推荐用户应当打开哪些文件。
7. 输出带优先级排序的改进方案。 列举相关依据（覆盖率 %、热点符号、重叠视图、日志时间戳、因果图边数），并将每条建议路由映射至主题路由（Topic Router）的参考文档。
8. 仅在用户显式要求修改代码时才进行代码编辑。

主题路由

请查阅与当前任务相关的各个主题参考文档：

技术主题	参考文档
状态管理 (State management)	references/state-management.md
视图组合 (View composition)	references/view-structure.md
性能优化 (Performance)	references/performance-patterns.md
列表与 ForEach (Lists and ForEach)	references/list-patterns.md
布局 (Layout)	references/layout-best-practices.md
弹窗与导航 (Sheets and navigation)	references/sheet-navigation-patterns.md
ScrollView 滚动视图	references/scroll-patterns.md
焦点管理 (Focus management)	references/focus-patterns.md
基础动画 (Animations - basics)	references/animation-basics.md
转场动画 (Animations - transitions)	references/animation-transitions.md
高级动画 (Animations - advanced)	references/animation-advanced.md
无障碍功能 (Accessibility)	references/accessibility-patterns.md
Swift Charts 图表	references/charts.md
图表无障碍支持 (Charts accessibility)	references/charts-accessibility.md
图片优化 (Image optimization)	references/image-optimization.md
Liquid Glass 效果 (iOS 26+)	references/liquid-glass.md
macOS 场景 (macOS scenes)	references/macos-scenes.md
macOS 窗口样式 (macOS window styling)	references/macos-window-styling.md
macOS 视图 (macOS views)	references/macos-views.md
文本排版与模式 (Text patterns)	references/text-patterns.md
本地化与国际化 (Localization)	references/localization.md
废弃 API 检索 (Deprecated API lookup)	references/latest-apis.md
软弃用 API 处理 (Handling soft-deprecated APIs)	references/soft-deprecation.md
视图预览 (Previews)	references/previews.md
Instruments trace 分析 (Instruments trace analysis)	references/trace-analysis.md
Instruments trace 录制 (Instruments trace recording)	references/trace-recording.md

正确性检查清单

以下为硬性规则 —— 任何违反均视为 Bug：

• [ ] @State 属性必须声明为 private
• [ ] 仅在子视图需要修改父视图状态时才使用 @Binding
• [ ] 外部传入的值绝不声明为 @State 或 @StateObject（因为它们会忽略外部更新）
• [ ] 视图自主持有的对象使用 @StateObject；外部注入的对象使用 @ObservedObject
• [ ] iOS 17+：结合 @Observable 使用 @State；外部注入且需要绑定时使用 @Bindable
• [ ] ForEach 使用稳定的标识符（严禁使用 .indices/\.offset；id 的生命周期需长于视图本身且不得派生自可变内容）
• [ ] 每个 ForEach 元素生成的视图数量保持恒定；List 行视图应当是一元的（unary）
• [ ] 自定义 @Environment/@FocusedValue 键中不得存储闭包（closures）
• [ ] 自定义 @Entry 的默认值必须是稳定的（严禁包含 Model()/Date()/UUID() 等计算表达式）
• [ ] .animation(_:value:) 必须始终包含 value 参数
• [ ] @FocusState 属性必须声明为 private
• [ ] 在可焦点化 .focusable() 视图的点击手势回调内部，不得进行冗余的 @FocusState 写入操作
• [ ] iOS 26+ API 必须使用 #available 做版本防护并提供降级支持
• [ ] 使用图表类型的文集中必须包含 import Charts
• [ ] Previews 预览必须使用自包含的 Mock 数据；不得依赖在线服务或网络请求

参考文档

• references/latest-apis.md -- 每个任务的首要必读文档。 废弃 API 到现代 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、动态字体（Dynamic Type）、无障碍分组与特征
• 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+）、预览特征（traits）、自包含预览的 Mock 数据模式
• references/text-patterns.md -- Text 初始化方法选择、逐字显示（verbatim）与本地化文本对比
• references/localization.md -- String Catalogs、Package 专属 #bundle、LocalizedStringResource、感知 Locale 的格式化、RTL 布局、翻译员注释
• references/soft-deprecation.md -- 软弃用 API 处理规范（何时迁移、作用域规则、切勿在不相关修改中捎带迁移）
• references/trace-analysis.md -- 通过 scripts/analyze_trace.py 解析 Instruments .trace 文件；解读主线程覆盖率、高开销 SwiftUI 更新、卡顿描述，并将分析结果映射回源码文件
• references/trace-recording.md -- R

<!-- truncated for translation batch; full body continues in source -->