用途
SwiftData Expert Skill 用于构建、审查和加固 SwiftData 持久化架构，遵循 Apple 从 iOS 17 到当前更新的文档化模式。其核心目标是优先保障数据完整性、迁移安全、同步正确性和可预测的并发行为。适用于 Swift 与 SwiftUI 应用中涉及 @Model 模式、ModelContainer 配置、查询、迁移、CloudKit 同步等持久化相关任务。
主要能力
技能以“代理行为契约”约束使用方式，要求：在推荐 API 前先确认最低部署目标（尤其是 #Index、#Unique、HistoryDescriptor、DataStore、继承示例等）；在调试数据问题前确认应用已正确接入 ModelContainer；区分主 actor UI 操作与后台持久化操作；将模式变更视为迁移变更，先评估轻量级迁移，再考虑 SchemaMigrationPlan；对启用 CloudKit 的应用，在提出模型变更前验证模式兼容性约束；优先使用确定性查询定义（共享谓词、显式排序、有界获取）；读取跨进程变更时使用持久化历史令牌并清理过期历史；代码审查时优先关注数据丢失风险、意外批量删除、同步分歧和上下文隔离缺陷。
技能提供早期分析命令，用于搜索容器设置、模型定义、上下文使用、迁移与历史、CloudKit 与 App Group 等代码位置。还提供项目信息收集清单，涵盖部署目标、容器设置、自动保存与显式保存、撤销启用状态、CloudKit 能力与容器策略、App Group 存储、Core Data 共存、模式变更向后兼容性等。
使用方式
技能通过工作流决策树引导按需查阅参考文件：新模型或模式形状对应 references/modeling-and-schema.md；创建、更新、删除行为或上下文正确性对应 references/model-context-and-lifecycle.md；过滤、排序或动态列表对应 references/querying-and-fetching.md；关系建模或继承对应 references/relationships-and-inheritance.md；迁移规划、版本升级或变更跟踪对应 references/migrations-and-history.md；iCloud 同步或 CloudKit 兼容性对应 references/cloudkit-sync.md；从 Core Data 增量迁移对应 references/core-data-adoption.md；后台隔离或基于 actor 的持久化对应 references/concurrency-and-actors.md；快速诊断或 API 可用性检查对应 references/troubleshooting-and-updates.md；具体任务的端到端执行手册对应 references/implementation-playbooks.md。
技能还提供“分诊优先手册”，针对插入失败或获取为空、网络刷新后出现重复行、删除时意外数据丢失、撤销重做无效、CloudKit 同步异常、Widget 或 App Intent 变更未反映、historyTokenExpired、查询结果昂贵或不稳定等常见问题给出下一步动作。
核心模式与最佳实践
技能包含应用级容器接入（SwiftUI 的 .modelContainer 修饰符）、手动容器配置、视图初始化器中的动态查询设置、安全批量删除模式等代码示例。最佳实践包括：以模型代码为事实来源；对大型或频繁查询数据集应用显式唯一性和索引策略；插入根模型并让 SwiftData 自动遍历关系图；使用显式谓词和排序描述符保持查询行为确定性；通过 fetchLimit、偏移量、仅标识符获取限制获取范围；将删除规则视为业务规则；使用 ModelConfiguration 处理环境特定行为；将历史视为操作系统（令牌持久化、过滤、清理）；对非 UI 持久化工作使用模型 actor 或隔离上下文；根据 API 可用性和部署目标限制建议。
适用场景
适用于 Swift 与 SwiftUI 应用中使用 SwiftData 进行持久化的开发、审查、迁移和调试工作，包括模型设计、上下文管理、查询优化、关系与继承、迁移规划、CloudKit 同步、Core Data 迁移、并发隔离、故障排查等。
限制
技能要求先确认最低部署目标，部分 API 可能受部署目标限制，需提供兼容回退方案。CloudKit 同步需先完成能力设置和模式兼容性检查。模式变更需在现有用户数据上进行迁移演练，不能仅依赖干净安装验证。技能资料未提供具体收费、价格、平台支持范围或效果保证等信息。