core-data-expert

Core Data 专家

为构建正确、高性能的 Core Data 栈并修复常见崩溃，提供快速、面向生产环境的指导。

Agent 行为约定（请遵循这些规则）

1. 当建议取决于功能可用性时，先确定操作系统和部署目标（例如 iOS 14+/17+ 功能）。
2. 提出修复方案前，先确认上下文类型：视图上下文（UI）还是后台上下文（繁重任务）。
3. 建议使用 NSManagedObjectID 进行跨上下文/跨任务通信；绝不要跨上下文传递 NSManagedObject 实例。
4. 尽可能优先采用轻量级迁移；对于复杂变更，使用分阶段迁移（iOS 17+）。
5. 建议批量操作时，确认已启用持久化历史记录（UI 更新通常需要此功能）。
6. 对于 CloudKit 集成，提醒开发者：Production 架构不可变。
7. 少量引用 WWDC/外部资源；优先使用此技能的 references/。

前 60 秒（分诊模板）

• 明确目标：设置、修复 Bug、迁移、性能还是 CloudKit？
• 收集最少必要信息：
  • 平台和部署目标
  • 存储类型（SQLite / 内存）以及是否启用了 CloudKit
  • 涉及的上下文（视图还是后台）以及是否使用 Swift Concurrency
  • 完整错误消息 + 堆栈跟踪/日志
• 立即分流：
  • 线程问题/崩溃 → 聚焦上下文隔离 + NSManagedObjectID 传递
  • 迁移错误 → 确认模型版本 + 迁移策略
  • 批量操作未更新 UI → 持久化历史记录 + 合并流程

路由图（快速选择合适的参考文档）

• 栈设置 / 合并策略 / 上下文 → references/stack-setup.md
• 保存模式 → references/saving.md
• 提取请求 / 列表更新 / 聚合 → references/fetch-requests.md
• 传统线程处理（perform/performAndWait、对象 ID） → references/threading.md
• Swift Concurrency（async/await、actors、Sendable、DAO） → references/concurrency.md
• 批量插入/删除/更新 → references/batch-operations.md
• 持久化历史记录 +“批量操作未更新 UI” → references/persistent-history.md
• 模型配置（约束、验证、派生属性/复合属性、可转换属性） → references/model-configuration.md
• 架构迁移（轻量级/分阶段/延迟） → references/migration.md
• CloudKit 集成与调试 → references/cloudkit-integration.md
• 性能分析与内存 → references/performance.md
• 测试模式 → references/testing.md
• 术语 → references/glossary.md

常见错误 → 下一步最佳做法

• “Failed to find a unique match for an NSEntityDescription” → references/testing.md（共享的 NSManagedObjectModel）
• NSPersistentStoreIncompatibleVersionHashError → references/migration.md（版本管理 + 迁移）
• 跨上下文/线程异常（例如在错误的上下文中删除/更新） → references/threading.md 和/或 references/concurrency.md（使用 NSManagedObjectID）
• Core Data 相关的 Sendable / actor 隔离警告 → references/concurrency.md（不要用 @unchecked Sendable 来“掩盖问题”）
• NSMergeConflict / 约束冲突 → references/model-configuration.md + references/stack-setup.md（约束 + 合并策略）
• 批量操作未更新 UI → references/persistent-history.md + references/batch-operations.md
• CloudKit 架构/同步问题 → references/cloudkit-integration.md
• 提取期间内存持续增长 → references/performance.md + references/fetch-requests.md

验证清单（修改 Core Data 代码时）

• 确认上下文与工作相匹配（UI 或后台）。
• 确保 NSManagedObject 实例不会跨上下文传递；改为传递 NSManagedObjectID。
• 如果使用批量操作，确认已启用持久化历史跟踪和合并流水线。
• 如果使用约束，确认合并策略和冲突解决策略。
• 如果涉及性能，使用 Instruments 进行分析，并验证提取批量大小和限制。

参考文件

• references/_index.md（导航）
• references/stack-setup.md
• references/saving.md
• references/fetch-requests.md
• references/threading.md
• references/concurrency.md
• references/batch-operations.md
• references/persistent-history.md
• references/model-configuration.md
• references/migration.md
• references/cloudkit-integration.md
• references/performance.md
• references/testing.md
• references/glossary.md