core-data-expert

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Core Data Expert

Core Data专家

Fast, production-oriented guidance for building correct, performant Core Data stacks and fixing common crashes.

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

Agent behavior contract (follow these rules)

Agent行为约定（遵守以下规则）

Determine OS/deployment target when advice depends on availability (iOS 14+/17+ features, etc.).
Identify the context type before proposing fixes: view context (UI) vs background context (heavy work).
Recommend
```
NSManagedObjectID
```
for cross-context/cross-task communication; never pass
NSManagedObject
instances across contexts.
Prefer lightweight migration when possible; use staged migration (iOS 17+) for complex changes.
When recommending batch operations, verify persistent history tracking is enabled (often required for UI updates).
For CloudKit integration, remind developers that Production schema is immutable.
Reference WWDC/external resources sparingly; prefer this skill’s
```
references/
```
.

当建议依赖于功能可用性时（如iOS 14+/17+特性等），明确操作系统/部署目标。
在提出修复方案前，先确定上下文类型：视图上下文（UI） vs 后台上下文（繁重任务）。
推荐使用
```
NSManagedObjectID
```
进行跨上下文/跨任务通信；绝对不要跨上下文传递
NSManagedObject
实例。
尽可能优先使用轻量迁移；对于复杂变更，使用分段迁移（iOS 17+）。
当推荐批量操作时，确认已启用持久化历史跟踪（这通常是UI更新的必要条件）。
对于CloudKit集成，提醒开发者生产环境 schema 不可修改。
尽量少引用WWDC或外部资源；优先使用本技能的
```
references/
```
目录下的内容。

First 60 seconds (triage template)

前60秒（分诊模板）

Clarify the goal: setup, bugfix, migration, performance, CloudKit?
Collect minimal facts:
- platform + deployment target
- store type (SQLite / in-memory) and whether CloudKit is enabled
- context involved (view vs background) and whether Swift Concurrency is in use
- exact error message + stack trace/logs
Branch immediately:
- threading/crash → focus on context confinement +
```
NSManagedObjectID
```
  handoff
- migration error → identify model versions + migration strategy
- batch ops not updating UI → persistent history tracking + merge pipeline

明确目标：配置、bug修复、迁移、性能优化、CloudKit集成？
收集关键信息：
- 平台 + 部署目标
- 存储类型（SQLite / 内存）以及是否启用CloudKit
- 涉及的上下文（视图 vs 后台）以及是否使用Swift Concurrency
- 确切的错误信息 + 堆栈跟踪/日志
立即分支处理：
- 线程/崩溃问题 → 聚焦上下文约束 +
```
NSManagedObjectID
```
  传递
- 迁移错误 → 识别模型版本 + 迁移策略
- 批量操作未更新UI → 持久化历史跟踪 + 合并流水线

Routing map (pick the right reference fast)

路由地图（快速选择正确参考资料）

Stack setup / merge policies / contexts →
```
references/stack-setup.md
```
Saving patterns →
```
references/saving.md
```
Fetch requests / list updates / aggregates →
```
references/fetch-requests.md
```
Traditional threading (perform/performAndWait, object IDs) →
```
references/threading.md
```
Swift Concurrency (async/await, actors, Sendable, DAOs) →
```
references/concurrency.md
```
Batch insert/delete/update →
```
references/batch-operations.md
```
Persistent history tracking + “batch ops not updating UI” →
```
references/persistent-history.md
```
Model configuration (constraints, validation, derived/composite, transformables) →
```
references/model-configuration.md
```
Schema migration (lightweight/staged/deferred) →
```
references/migration.md
```
CloudKit integration & debugging →
```
references/cloudkit-integration.md
```
Performance profiling & memory →
```
references/performance.md
```
Testing patterns →
```
references/testing.md
```
Terminology →
```
references/glossary.md
```

栈配置 / 合并策略 / 上下文 →
```
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
```
Schema迁移（轻量/分段/延迟） →
```
references/migration.md
```
CloudKit集成与调试 →
```
references/cloudkit-integration.md
```
性能分析与内存 →
```
references/performance.md
```
测试模式 →
```
references/testing.md
```
术语表 →
```
references/glossary.md
```

Common errors → next best move

常见错误 → 下一步最佳操作

“Failed to find a unique match for an NSEntityDescription” →
```
references/testing.md
```
(shared
```
NSManagedObjectModel
```
)

NSPersistentStoreIncompatibleVersionHashError
→

references/migration.md

(versioning + migration)

Cross-context/threading exceptions (e.g. delete/update from wrong context) →
```
references/threading.md
```
and/or
```
references/concurrency.md
```
(use
```
NSManagedObjectID
```
)
Sendable / actor-isolation warnings around Core Data →
```
references/concurrency.md
```
(don’t “paper over” with
```
@unchecked Sendable
```
)

NSMergeConflict
/ constraint violations →

references/model-configuration.md

references/stack-setup.md

(constraints + merge policy)

Batch operations not updating UI →

references/persistent-history.md

references/batch-operations.md

CloudKit schema/sync issues →
```
references/cloudkit-integration.md
```

Memory grows during fetch →

references/performance.md

references/fetch-requests.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 schema/同步问题 →
```
references/cloudkit-integration.md
```

获取数据时内存增长 →

references/performance.md

references/fetch-requests.md

Verification checklist (when changing Core Data code)

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

Confirm the context matches the work (UI vs background).
Ensure
```
NSManagedObject
```
instances never cross contexts; pass
```
NSManagedObjectID
```
instead.
If using batch ops, confirm persistent history tracking + merge pipeline.
If using constraints, confirm merge policy and conflict resolution strategy.
If performance-related, profile with Instruments and validate fetch batching/limits.

确认上下文与任务匹配（UI vs 后台）。
确保
```
NSManagedObject
```
实例绝不跨上下文传递；改用
```
NSManagedObjectID
```
。
如果使用批量操作，确认已启用持久化历史跟踪 + 合并流水线。
如果使用约束，确认合并策略和冲突解决策略。
如果是性能相关问题，使用Instruments分析并验证获取请求的批处理/限制。

Reference files

参考文件

```
references/_index.md
```
(navigation)
```
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
```

```
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
```