axiom-data

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Data & Persistence

数据与持久化

You MUST use this skill for ANY data persistence, database, storage, CloudKit, or serialization work.

任何涉及数据持久化、数据库、存储、CloudKit或序列化的工作都必须使用本技能。

When to Use

使用场景

Use this skill when working with:

Databases (SwiftData, Core Data, GRDB, SQLiteData)
Schema migrations
CloudKit sync
File storage (iCloud Drive, local storage)
Data serialization (Codable, JSON)
Storage strategy decisions
Keychain / secure credential storage
Encryption, signing, key management (CryptoKit)

在处理以下内容时使用本技能：

数据库（SwiftData、Core Data、GRDB、SQLiteData）
架构迁移
CloudKit同步
文件存储（iCloud Drive、本地存储）
数据序列化（Codable、JSON）
存储策略决策
钥匙串/安全凭证存储
加密、签名、密钥管理（CryptoKit）

Quick Reference

快速参考

Symptom / Task	Reference
SwiftData @Model, @Query, ModelContext	See `skills/swiftdata.md`
SwiftData schema migration, VersionedSchema	See `skills/swiftdata-migration.md`
SwiftData migration crashes, data loss	See `skills/swiftdata-migration-diag.md`
Migrating from Realm to SwiftData	See `skills/realm-migration-ref.md`
SwiftData vs SQLiteData decision	See `skills/sqlitedata-migration.md`
GRDB queries, ValueObservation, DatabaseMigrator	See `skills/grdb.md`
SQLiteData @Table, CRUD, SyncEngine	See `skills/sqlitedata.md`
SQLiteData advanced patterns, CTEs, views	See `skills/sqlitedata-ref.md`
Core Data stack, relationships, concurrency	See `skills/core-data.md`
Core Data migration crashes, thread errors	See `skills/core-data-diag.md`
ANY schema migration safety	See `skills/database-migration.md`
Codable, JSON encoding/decoding	See `skills/codable.md`
Cloud sync architecture, offline-first	See `skills/cloud-sync.md`
CloudKit, CKSyncEngine, CKRecord	See `skills/cloudkit-ref.md`
iCloud Drive, ubiquitous containers	See `skills/icloud-drive-ref.md`
Cloud sync errors, conflict resolution	See `skills/cloud-sync-diag.md`
Storage strategy, where to store data	See `skills/storage.md`
Storage issues, files disappeared	See `skills/storage-diag.md`
Storage management, disk pressure	See `skills/storage-management-ref.md`
Keychain / secure credential storage	See axiom-security (skills/keychain.md)
Keychain errors (errSecDuplicateItem)	See axiom-security (skills/keychain-diag.md)
Keychain API reference	See axiom-security (skills/keychain-ref.md)
Encryption / signing / key management	See axiom-security (skills/cryptokit.md)
CryptoKit API reference	See axiom-security (skills/cryptokit-ref.md)
File protection, NSFileProtection	See axiom-security (skills/file-protection-ref.md)
tvOS data persistence (no local storage)	See axiom-swift (skills/tvos.md)
tvOS + CloudKit SyncEngine	See `skills/sqlitedata.md`

症状/任务	参考文档
SwiftData @Model、@Query、ModelContext	参见 `skills/swiftdata.md`
SwiftData架构迁移、VersionedSchema	参见 `skills/swiftdata-migration.md`
SwiftData迁移崩溃、数据丢失	参见 `skills/swiftdata-migration-diag.md`
从Realm迁移至SwiftData	参见 `skills/realm-migration-ref.md`
SwiftData与SQLiteData选型决策	参见 `skills/sqlitedata-migration.md`
GRDB查询、ValueObservation、DatabaseMigrator	参见 `skills/grdb.md`
SQLiteData @Table、CRUD、SyncEngine	参见 `skills/sqlitedata.md`
SQLiteData高级模式、CTE、视图	参见 `skills/sqlitedata-ref.md`
Core Data堆栈、关系、并发	参见 `skills/core-data.md`
Core Data迁移崩溃、线程错误	参见 `skills/core-data-diag.md`
任何架构迁移安全问题	参见 `skills/database-migration.md`
Codable、JSON编码/解码	参见 `skills/codable.md`
云同步架构、离线优先	参见 `skills/cloud-sync.md`
CloudKit、CKSyncEngine、CKRecord	参见 `skills/cloudkit-ref.md`
iCloud Drive、通用容器	参见 `skills/icloud-drive-ref.md`
云同步错误、冲突解决	参见 `skills/cloud-sync-diag.md`
存储策略、数据存储位置选择	参见 `skills/storage.md`
存储问题、文件丢失	参见 `skills/storage-diag.md`
存储管理、磁盘压力	参见 `skills/storage-management-ref.md`
钥匙串/安全凭证存储	参见axiom-security（skills/keychain.md）
钥匙串错误（errSecDuplicateItem）	参见axiom-security（skills/keychain-diag.md）
钥匙串API参考	参见axiom-security（skills/keychain-ref.md）
加密/签名/密钥管理	参见axiom-security（skills/cryptokit.md）
CryptoKit API参考	参见axiom-security（skills/cryptokit-ref.md）
文件保护、NSFileProtection	参见axiom-security（skills/file-protection-ref.md）
tvOS数据持久化（无本地存储）	参见axiom-swift（skills/tvos.md）
tvOS + CloudKit SyncEngine	参见 `skills/sqlitedata.md`

Automated Scanning

自动化扫描

Core Data audit → Launch

core-data-auditor

agent or

/axiom:audit core-data

(safety violations, architectural gaps — migration options, thread-confinement, N+1 queries, merge policies, context isolation) Codable audit → Launch

codable-auditor

agent or

/axiom:audit codable

(safety violations, semantic gaps — try? swallowing errors, JSONSerialization, date handling, silent field drops, wrapper-hidden fallbacks, cross-file strategy drift, enum future-case crashes) iCloud audit → Launch

icloud-auditor

agent or

/axiom:audit icloud

(entitlement checks, file coordination, CloudKit anti-patterns) Storage audit → Launch

storage-auditor

agent or

/axiom:audit storage

(wrong file locations, missing backup exclusions, data loss risks) Database schema audit → Launch

database-schema-auditor

agent or

/axiom:audit database-schema

(unsafe ALTER TABLE, DROP operations, missing idempotency, foreign key misuse) SwiftData audit → Launch

swiftdata-auditor

agent or

/axiom:audit swiftdata

(struct models, missing VersionedSchema, relationship defaults, background context misuse, N+1 patterns)

Core Data审计 → 启动

core-data-auditor

代理或

/axiom:audit core-data

（检测安全违规、架构缺陷——迁移选项、线程限制、N+1查询、合并策略、上下文隔离） Codable审计 → 启动

codable-auditor

代理或

/axiom:audit codable

（检测安全违规、语义缺陷——try?吞掉错误、JSONSerialization、日期处理、字段静默丢失、包装器隐藏回退、跨文件策略漂移、枚举未来案例崩溃） iCloud审计 → 启动

icloud-auditor

代理或

/axiom:audit icloud

（检测权限检查、文件协调、CloudKit反模式） 存储审计 → 启动

storage-auditor

代理或

/axiom:audit storage

（检测错误文件位置、缺失备份排除项、数据丢失风险） 数据库架构审计 → 启动

database-schema-auditor

代理或

/axiom:audit database-schema

（检测不安全ALTER TABLE、DROP操作、缺失幂等性、外键误用） SwiftData审计 → 启动

swiftdata-auditor

代理或

/axiom:audit swiftdata

（检测结构体模型、缺失VersionedSchema、关系默认值、后台上下文误用、N+1模式）

Decision Tree

决策树

SwiftData? →

skills/swiftdata.md

skills/swiftdata-migration.md

Core Data? →

skills/core-data.md

skills/core-data-diag.md

GRDB? →
```
skills/grdb.md
```

SQLiteData? →

skills/sqlitedata.md

skills/sqlitedata-ref.md

ANY schema migration? →
```
skills/database-migration.md
```
(ALWAYS — prevents data loss)
Realm migration? →
```
skills/realm-migration-ref.md
```
SwiftData vs SQLiteData? →
```
skills/sqlitedata-migration.md
```
Cloud sync architecture? →
```
skills/cloud-sync.md
```
CloudKit? →
```
skills/cloudkit-ref.md
```
iCloud Drive? →
```
skills/icloud-drive-ref.md
```
Cloud sync errors? →
```
skills/cloud-sync-diag.md
```
Codable/JSON serialization? →
```
skills/codable.md
```

File storage strategy? →

skills/storage.md

skills/storage-diag.md

skills/storage-management-ref.md

File protection? → See axiom-security (skills/file-protection-ref.md)
Keychain / storing tokens, passwords, secrets securely? → See axiom-security (skills/keychain.md), See axiom-security (skills/keychain-diag.md), See axiom-security (skills/keychain-ref.md)
SecItem errors (errSecDuplicateItem, errSecItemNotFound, errSecInteractionNotAllowed)? → See axiom-security (skills/keychain-diag.md)
Encryption, signing, Secure Enclave, CryptoKit? → See axiom-security (skills/cryptokit.md), See axiom-security (skills/cryptokit-ref.md)
Quantum-secure cryptography, HPKE, ML-KEM? → See axiom-security (skills/cryptokit.md)
Want Core Data safety scan? → core-data-auditor (Agent)
Want Codable anti-pattern scan? → codable-auditor (Agent)
Want iCloud sync audit? → icloud-auditor (Agent)
Want storage location audit? → storage-auditor (Agent)
Want database schema/migration safety scan? → database-schema-auditor (Agent)
Want SwiftData code audit? → swiftdata-auditor (Agent)
tvOS data persistence? → See axiom-swift (skills/tvos.md) (CRITICAL: no persistent local storage) +
```
skills/sqlitedata.md
```
(CloudKit SyncEngine)
SwiftData @MainActor / background context threading? →
```
/skill axiom-concurrency
```
Structured data generation with Foundation Models? →
```
/skill axiom-ai
```

使用SwiftData？ →

skills/swiftdata.md

、

skills/swiftdata-migration.md

使用Core Data？ →

skills/core-data.md

、

skills/core-data-diag.md

使用GRDB？ →
```
skills/grdb.md
```

使用SQLiteData？ →

skills/sqlitedata.md

、

skills/sqlitedata-ref.md

涉及任何架构迁移？ →
```
skills/database-migration.md
```
（必须阅读——防止数据丢失）
Realm迁移？ →
```
skills/realm-migration-ref.md
```
SwiftData与SQLiteData选型？ →
```
skills/sqlitedata-migration.md
```
云同步架构？ →
```
skills/cloud-sync.md
```
使用CloudKit？ →
```
skills/cloudkit-ref.md
```
使用iCloud Drive？ →
```
skills/icloud-drive-ref.md
```
云同步错误？ →
```
skills/cloud-sync-diag.md
```
Codable/JSON序列化？ →
```
skills/codable.md
```

文件存储策略？ →

skills/storage.md

、

skills/storage-diag.md

、

skills/storage-management-ref.md

文件保护？ → 参见axiom-security（skills/file-protection-ref.md）
钥匙串/安全存储令牌、密码、密钥？ → 参见axiom-security（skills/keychain.md）、参见axiom-security（skills/keychain-diag.md）、参见axiom-security（skills/keychain-ref.md）
SecItem错误（errSecDuplicateItem、errSecItemNotFound、errSecInteractionNotAllowed）？ → 参见axiom-security（skills/keychain-diag.md）
加密、签名、安全飞地、CryptoKit？ → 参见axiom-security（skills/cryptokit.md）、参见axiom-security（skills/cryptokit-ref.md）
抗量子密码学、HPKE、ML-KEM？ → 参见axiom-security（skills/cryptokit.md）
需要Core Data安全扫描？ → core-data-auditor（代理）
需要Codable反模式扫描？ → codable-auditor（代理）
需要iCloud同步审计？ → icloud-auditor（代理）
需要存储位置审计？ → storage-auditor（代理）
需要数据库架构/迁移安全扫描？ → database-schema-auditor（代理）
需要SwiftData代码审计？ → swiftdata-auditor（代理）
tvOS数据持久化？ → 参见axiom-swift（skills/tvos.md）（重点：无持久化本地存储）+
```
skills/sqlitedata.md
```
（CloudKit SyncEngine）
SwiftData @MainActor / 后台上下文线程？ →
```
/skill axiom-concurrency
```
用基础模型生成结构化数据？ →
```
/skill axiom-ai
```

Sync patterns

同步模式

HealthKit anchored/observer queries as a generalizable change-tracking pattern → See axiom-health (skills/sync-and-background.md)

HealthKit锚定/观察者查询作为通用变更追踪模式 → 参见axiom-health（skills/sync-and-background.md）

Anti-Rationalization

常见认知误区

Thought	Reality
"Just adding a column, no migration needed"	Schema changes without migration crash users. database-migration prevents data loss.
"I'll handle the migration manually"	Manual migrations miss edge cases. database-migration covers rollback and testing.
"Simple query, I don't need the skill"	Query patterns prevent N+1 and thread-safety issues. The skill has copy-paste solutions.
"CloudKit sync is straightforward"	CloudKit has 15+ failure modes. cloud-sync-diag diagnoses them systematically.
"I know Codable well enough"	Codable has silent data loss traps (try? swallows errors). codable skill prevents production bugs.
"I'll use local storage on tvOS"	tvOS has NO persistent local storage. System deletes Caches at any time. See axiom-swift (skills/tvos.md) for the iCloud-first pattern.
"UserDefaults is fine for this token"	UserDefaults is unencrypted, backed up to iCloud, and visible to MDM profiles. One audit catches it. keychain stores tokens securely.
"I'll encrypt it myself with CommonCrypto"	CryptoKit replaced CommonCrypto's buffer-management nightmares with one-line APIs. cryptokit prevents misuse.

错误想法	实际情况
"只是加个字段，不需要迁移"	无迁移的架构变更会导致用户崩溃。database-migration可防止数据丢失。
"我手动处理迁移就行"	手动迁移会遗漏边缘场景。database-migration涵盖回滚和测试。
"简单查询，不需要用这个技能"	查询模式可避免N+1和线程安全问题。本技能提供可直接复用的解决方案。
"CloudKit同步很简单"	CloudKit有15种以上的失败模式。cloud-sync-diag可系统诊断这些问题。
"我对Codable足够了解"	Codable存在静默数据丢失陷阱（try?吞掉错误）。本技能可避免生产环境bug。
"我在tvOS上用本地存储"	tvOS没有持久化本地存储。系统会随时删除缓存文件。请参见axiom-swift（skills/tvos.md）了解iCloud优先模式。
"用UserDefaults存这个令牌没问题"	UserDefaults未加密，会备份到iCloud，且对MDM配置文件可见。一次审计就能发现问题。应使用钥匙串安全存储令牌。
"我自己用CommonCrypto加密"	CryptoKit用一行API替代了CommonCrypto繁琐的缓冲区管理。cryptokit可避免误用。

Critical Pattern: Migrations

关键模式：迁移

ALWAYS read
skills/database-migration.md
when adding/modifying database columns.

This prevents:

"FOREIGN KEY constraint failed" errors
"no such column" crashes
Data loss from unsafe migrations

添加/修改数据库列时，务必阅读
skills/database-migration.md
。

这可防止：

"FOREIGN KEY constraint failed"错误
"no such column"崩溃
不安全迁移导致的数据丢失

Example Invocations

调用示例

User: "I need to add a column to my SwiftData model" → Read:

skills/database-migration.md

(critical - prevents data loss)

User: "How do I query SwiftData with complex filters?" → Read:

skills/swiftdata.md

User: "CloudKit sync isn't working" → Read:

skills/cloud-sync-diag.md

User: "Should I use SwiftData or SQLiteData?" → Read:

skills/sqlitedata-migration.md

User: "Check my Core Data code for safety issues" → Launch:

core-data-auditor

agent

User: "Scan for Codable anti-patterns before release" → Launch:

codable-auditor

agent

User: "Audit my iCloud sync implementation" → Launch:

icloud-auditor

agent

User: "Check if my files are stored in the right locations" → Launch:

storage-auditor

agent

User: "Audit my database migrations for safety" → Launch:

database-schema-auditor

agent

User: "Check my SwiftData models for issues" → Launch:

swiftdata-auditor

agent

User: "How do I persist data on tvOS?" → Invoke: See axiom-swift (skills/tvos.md) + Read:

skills/sqlitedata.md

User: "My tvOS app loses data between launches" → Invoke: See axiom-swift (skills/tvos.md)

User: "How do I store an auth token securely?" → Invoke: See axiom-security (skills/keychain.md)

User: "errSecDuplicateItem but I checked and the item doesn't exist" → Invoke: See axiom-security (skills/keychain-diag.md)

User: "How do I encrypt data with AES in Swift?" → Invoke: See axiom-security (skills/cryptokit.md)

User: "I need to sign data with the Secure Enclave" → Invoke: See axiom-security (skills/cryptokit.md)

User: "What's ML-KEM and should I use it?" → Invoke: See axiom-security (skills/cryptokit.md)

用户："我需要给SwiftData模型加个字段" → 阅读：

skills/database-migration.md

（重点——防止数据丢失）

用户："如何用复杂过滤器查询SwiftData？" → 阅读：

skills/swiftdata.md

用户："CloudKit同步不工作" → 阅读：

skills/cloud-sync-diag.md

用户："我应该用SwiftData还是SQLiteData？" → 阅读：

skills/sqlitedata-migration.md

用户："检查我的Core Data代码是否有安全问题" → 启动：

core-data-auditor

代理

用户："发布前扫描Codable反模式" → 启动：

codable-auditor

代理

用户："审计我的iCloud同步实现" → 启动：

icloud-auditor

代理

用户："检查我的文件是否存在正确位置" → 启动：

storage-auditor

代理

用户："审计我的数据库迁移是否安全" → 启动：

database-schema-auditor

代理

用户："检查我的SwiftData模型是否有问题" → 启动：

swiftdata-auditor

代理

用户："如何在tvOS上持久化数据？" → 调用：参见axiom-swift（skills/tvos.md）+ 阅读：

skills/sqlitedata.md

用户："我的tvOS应用重启后丢失数据" → 调用：参见axiom-swift（skills/tvos.md）

用户："如何安全存储认证令牌？" → 调用：参见axiom-security（skills/keychain.md）

用户："出现errSecDuplicateItem错误，但我检查过该条目不存在" → 调用：参见axiom-security（skills/keychain-diag.md）

用户："如何在Swift中用AES加密数据？" → 调用：参见axiom-security（skills/cryptokit.md）

用户："我需要用安全飞地签名数据" → 调用：参见axiom-security（skills/cryptokit.md）

用户："ML-KEM是什么，我应该用它吗？" → 调用：参见axiom-security（skills/cryptokit.md）