axiom-data

数据与持久化

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

无法启动 Axiom Agent？ 如果此路由指引你使用某个 Agent，请直接按照其流程操作。通过 MCP，axiom_get_agent 会返回该 Agent；在其他环境中，请读取下方对应的文件，只需使用文件搜索和读取功能即可。

此处可用：skills/codable-auditor.md、skills/core-data-auditor.md、skills/database-schema-auditor.md、skills/grdb-performance-auditor.md、skills/icloud-auditor.md、skills/storage-auditor.md、skills/swiftdata-auditor.md。

对于其他 Agent，通过 MCP 使用 axiom_get_agent 也能获取；请使用 axiom_xclog_*、axiom_xcsym_* 和 axiom_xcprof_* 工具，执行其 xclog、xcsym 和 xcprof 步骤。在其他环境中，请在 Axiom 的技能中搜索 skills/<agent>.md；如果找不到，请使用本套技能自行完成相关工作，并使用 PATH 中的任意 Axiom 工具。

适用场景

在以下情况下使用此技能：

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

快速参考

症状 / 任务	参考
SwiftData @Model、@Query、ModelContext、分区查询 / ResultsObserver / @Attribute(.codable) / 动态复合谓词（OS27）	参见 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 查询、upsert、ValueObservation、DatabaseMigrator、加密	参见 skills/grdb.md
GRDB 性能、索引、EXPLAIN QUERY PLAN、游标、观察未触发	参见 skills/grdb-performance.md
在 GRDB 或 SQLiteData 中进行全文搜索（FTS5）	参见 skills/sqlite-fts-ref.md
在 SQLite 列中存储或查询 JSON（JSON1、JSONB）	参见 skills/sql-json-ref.md
在应用与小组件/扩展之间共享 GRDB（App Group）	参见 skills/grdb-app-groups.md
SQLiteData @Table、CRUD、SyncEngine	参见 skills/sqlitedata.md
SQLiteData 高级模式、CTE、视图	参见 skills/sqlitedata-ref.md
@Shared / @SharedReader、appStorage 或 fileStorage 持久化、自定义 SharedKey、@FetchAll 上的 isLoading / loadError	参见 skills/swift-sharing.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
Keychain / 安全凭据存储	参见 axiom-security (skills/keychain.md)
Keychain 错误（errSecDuplicateItem）	参见 axiom-security (skills/keychain-diag.md)
Keychain 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

自动化扫描

Core Data 审计 → 启动 core-data-auditor agent 或 /axiom:audit core-data（安全违规、架构缺陷——迁移选项、线程隔离、N+1 查询、合并策略、上下文隔离） Codable 审计 → 启动 codable-auditor agent 或 /axiom:audit codable（安全违规、语义缺陷——try? 吞掉错误、JSONSerialization、日期处理、静默丢弃字段、包装器隐藏的回退逻辑、跨文件策略偏差、枚举未来 case 导致崩溃） iCloud 审计 → 启动 icloud-auditor agent 或 /axiom:audit icloud（权限检查、文件协调、CKError 矩阵覆盖不完整、缺少账户变更观察、使用轮询而非 CKSubscriptions、SwiftData + CloudKit 不支持的功能、复合风险，例如扩展之间未协调的 I/O） 存储审计 → 启动 storage-auditor agent 或 /axiom:audit storage（文件位置错误、缺少备份排除项、磁盘上的敏感数据未存入 Keychain、缺少 App Group 容器、缓存无限增长、孤立文件、复合风险，例如用户数据存放于 tmp/ 且包含关键内容） 数据库架构审计 → 启动 database-schema-auditor agent 或 /axiom:audit database-schema（不安全的 ALTER TABLE、DROP 操作、缺少幂等性、声明了外键约束但未强制执行、升级路径不完整、复合风险，例如对被外键引用的表使用 INSERT OR REPLACE） GRDB 性能审计 → 启动 grdb-performance-auditor agent 或 /axiom:audit grdb-performance（原始 SQL 字符串插值、原始 SQL 中缺少外键索引、原始 GRDB 应用缺少 PRAGMA optimize、App Group 数据库的日志模式不匹配、共享数据库缺少 observesSuspensionNotifications、原始 SQL 中存在前缀冗余索引、旧版 Record 子类、将 INSERT OR REPLACE 错用作 upsert、在 WITHOUT ROWID 表上进行观察、WITHOUT ROWID upsert 缺陷） SwiftData 审计 → 启动 swiftdata-auditor agent 或 /axiom:audit swiftdata（结构体模型、缺少架构注册、数组关系缺少默认值、后台上下文使用不当、N+1 模式、过期谓词、CloudKit 一致性缺陷、复合风险，例如结构体模型 + 数组关系）

决策树

1. SwiftData？→ skills/swiftdata.md、skills/swiftdata-migration.md
2. Core Data？→ skills/core-data.md、skills/core-data-diag.md
3. GRDB？→ skills/grdb.md 3a. GRDB 性能、慢查询或面向性能的架构设计？→ skills/grdb-performance.md 3b. FTS5（全文搜索，任意层）？→ skills/sqlite-fts-ref.md 3c. 应用与扩展程序／小组件／实时活动之间共享数据库？→ skills/grdb-app-groups.md
4. SQLiteData？→ skills/sqlitedata.md、skills/sqlitedata-ref.md 4a. @Shared／@SharedReader，或 @FetchAll 背后的加载／错误状态？→ skills/swift-sharing.md
5. 任何数据库架构迁移？→ skills/database-migration.md（始终使用——防止数据丢失）
6. Realm 迁移？→ skills/realm-migration-ref.md
7. SwiftData 与 SQLiteData 的选择？→ skills/sqlitedata-migration.md
8. 云同步架构？→ skills/cloud-sync.md
9. CloudKit？→ skills/cloudkit-ref.md
10. iCloud Drive？→ skills/icloud-drive-ref.md
11. 云同步错误？→ skills/cloud-sync-diag.md
12. Codable／JSON 序列化？→ skills/codable.md
13. 文件存储策略？→ skills/storage.md、skills/storage-diag.md、skills/storage-management-ref.md
14. 文件保护？→ 参阅 axiom-security（skills/file-protection-ref.md）
15. Keychain／安全存储令牌、密码和机密？→ 参阅 axiom-security（skills/keychain.md）、参阅 axiom-security（skills/keychain-diag.md）、参阅 axiom-security（skills/keychain-ref.md）
16. SecItem 错误（errSecDuplicateItem、errSecItemNotFound、errSecInteractionNotAllowed）？→ 参阅 axiom-security（skills/keychain-diag.md）
17. 加密、签名、Secure Enclave、CryptoKit？→ 参阅 axiom-security（skills/cryptokit.md）、参阅 axiom-security（skills/cryptokit-ref.md）
18. 抗量子密码学、HPKE、ML-KEM？→ 参阅 axiom-security（skills/cryptokit.md）
19. 想要进行 Core Data 安全扫描？→ core-data-auditor（Agent）
20. 想要进行 Codable 反模式扫描？→ codable-auditor（Agent）
21. 想要进行 iCloud 同步审计？→ icloud-auditor（Agent）
22. 想要进行存储位置审计？→ storage-auditor（Agent）
23. 想要进行数据库架构／迁移安全扫描？→ database-schema-auditor（Agent） 23a. 想要进行 GRDB 性能／应用组扫描？→ grdb-performance-auditor（Agent）
24. 想要进行 SwiftData 代码审计？→ swiftdata-auditor（Agent）
25. tvOS 数据持久化？→ 参阅 axiom-swift（skills/tvos.md）（重要：每次启动之间，所有本地目录都可能被清除，因此 iCloud 是事实来源）+ skills/sqlitedata.md（CloudKit SyncEngine）
26. SwiftData @MainActor／后台上下文线程处理？→ /skill axiom-concurrency
27. 使用 Foundation Models 生成结构化数据？→ /skill axiom-ai

同步模式

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

反合理化

想法	现实
“只是添加一列，不需要迁移”	未经迁移就更改架构会导致用户遇到崩溃。database-migration 可防止数据丢失。
“我会手动处理迁移”	手动迁移容易遗漏边缘情况。database-migration 提供安全的增量模式，以及两种可供测试的迁移路径。
“只是简单的查询，不需要这个技能”	查询模式可防止 N+1 和线程安全问题。这个技能提供可直接复制粘贴的解决方案。
“CloudKit 同步很简单”	CloudKit 有 15 种以上的故障模式。cloud-sync-diag 可系统地诊断这些问题。
“我对 Codable 足够熟悉了”	Codable 有会导致静默数据丢失的陷阱（try? 会吞掉错误）。codable 技能可防止生产环境中的错误。
“@Shared 只是多了几步操作的 @AppStorage”	修改必须通过 $shared.withLock 进行；普通 setter 已弃用，并且在 Swift 6.3 下使用低于 Sharing 2.8 的版本时，凡是将 SwiftUI 绑定链入共享状态的地方都会导致编译错误。swift-sharing 提供了迁移方案。
“我会在 tvOS 上使用本地存储”	tvOS 上没有任何本地目录能保证在应用重新启动后仍然存在——系统会清理这些目录，首先清理 Caches。请参阅 axiom-swift（skills/tvos.md）中的 iCloud 优先模式。
“用 UserDefaults 存这个令牌没问题”	UserDefaults 未加密、会备份到 iCloud，并且对 MDM 配置文件可见。一次审计就能发现这个问题。keychain 可安全存储令牌。
“我会用 CommonCrypto 自己加密”	CryptoKit 用单行 API 取代了 CommonCrypto 中令人头疼的缓冲区管理。cryptokit 可防止误用。

关键模式：迁移

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

这可以防止：

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

示例调用

用户：“我需要为 SwiftData 模型添加一列” → 阅读：skills/database-migration.md（关键——可避免数据丢失）

用户：“如何使用复杂筛选条件查询 SwiftData？” → 阅读：skills/swiftdata.md

用户：“CloudKit 同步不起作用” → 阅读：skills/cloud-sync-diag.md

用户：“应该使用 SwiftData 还是 SQLiteData？” → 阅读：skills/sqlitedata-migration.md

用户：“如何将设置持久化到 UserDefaults，并在所有位置监听它？” → 阅读：skills/swift-sharing.md

用户：“为什么我的 @FetchAll 为空——它正在加载还是加载失败了？” → 阅读：skills/swift-sharing.md

用户：“检查我的 Core Data 代码是否存在安全问题” → 启动：core-data-auditor Agent

用户：“发布前扫描 Codable 反模式” → 启动：codable-auditor Agent

用户：“审计我的 iCloud 同步实现” → 启动：icloud-auditor Agent

用户：“检查我的文件是否存储在正确的位置” → 启动：storage-auditor Agent

用户：“审计我的数据库迁移是否安全” → 启动：database-schema-auditor Agent

用户：“如何提高 GRDB 查询的速度？” → 阅读：skills/grdb-performance.md

用户：“为我的 GRDB 应用添加搜索” / “为 SQLiteData 应用添加搜索” → 阅读：skills/sqlite-fts-ref.md

用户：“我的小组件需要读取与应用相同的数据库” → 阅读：skills/grdb-app-groups.md

用户：“我的小组件显示的是数据库中的过时数据” → 阅读：skills/grdb-app-groups.md

用户：“审计我的 GRDB 代码是否存在性能问题” → 启动：grdb-performance-auditor Agent

用户：“检查我的 SwiftData 模型是否存在问题” → 启动：swiftdata-auditor Agent

用户：“如何在 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）

用户：“我需要使用 Secure Enclave 对数据签名” → 调用：参阅 axiom-security（skills/cryptokit.md）

用户：“什么是 ML-KEM？我应该使用它吗？” → 调用：参阅 axiom-security（skills/cryptokit.md）