公理数据

其他 社区

技能解读

当前原文的自动摘译,尚未人工审校。

游标子代理路由

当此路由器需要专门的审核员时,委托给适当的 Cursor 子代理。

何时使用

在处理以下内容时使用此技能: 数据库(SwiftData、Core Data、GRDB、SQLiteData) 架构迁移 CloudKit 同步 文件存储(iCloud Drive、本地存储)

快速参考

症状/任务 · 参考 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

自动扫描

核心数据审计 → 委托给 core-data-auditor 子代理或 /axiom-audit 核心数据(安全违规、架构差距 — 迁移选项、线程限制、N+1 查询、合并策略、上下文隔离) 可编码审计 → 委托给 codable-auditor 子代理或 /axiom-audit 可编码(安全违规、语义差距 — 尝试?吞下错误、JSONSerialization、日期处理、静默字段删除、包装隐藏回退、跨文件策略漂移、枚举未来案例崩溃)

决策树

斯威夫特数据? → skills/swiftdata.md、skills/swiftdata-migration.md 核心数据? → skills/core-data.md、skills/core-data-diag.md GRDB? → skills/grdb.md 3a。 GRDB 性能、慢查询、性能模式设计? → skills/grdb-performance.md 3b。 FTS5(全文搜索,任意层)? → skills/sqlite-fts-ref.md

流狐档案 运行与权限由流狐静态检查推断,不代表作者声明或实际测试结果。
领域
通用
作者声明的智能体
未找到明确声明;不据此推断已兼容或已测试
静态检查
88 / 100 · 启发式扫描,不代表运行安全
运行环境证据
未执行;当前没有隔离运行测试证据
作者 / 版本 / 许可证
@CharlesWiltgen · 未声明许可证
上下文用量评级
中等消耗
接入复杂程度
需简单配置
是否需要外部接口密钥
不需要
兼容的系统
未声明(默认跨平台)
运行环境要求
未检出明确要求
检测到的文件与系统行为
  • 只读
网络行为
仅限本地
安装命令数
无(仅作为资料)

需要注意: 未声明工具权限范围;实际权限由运行环境决定。

作者说明文件(原文) SKILL.md


# Data & Persistence

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

## Cursor Subagent Routing

Delegate to the appropriate Cursor subagent when this router calls for a specialized auditor.

## 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)

## Quick Reference

| Symptom / Task | Reference |
|----------------|-----------|
| SwiftData @Model, @Query, ModelContext, sectioned queries / ResultsObserver / @Attribute(.codable) / dynamic compound predicates (`OS27`) | 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, upsert, ValueObservation, DatabaseMigrator, encryption | See `skills/grdb.md` |
| GRDB performance, indexes, EXPLAIN QUERY PLAN, cursors, observation not firing | See `skills/grdb-performance.md` |
| Full-text search (FTS5) in GRDB or SQLiteData | See `skills/sqlite-fts-ref.md` |
| Storing or querying JSON inside a SQLite column (JSON1, JSONB) | See `skills/sql-json-ref.md` |
| GRDB shared across app + widget/extension (App Group) | See `skills/grdb-app-groups.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` |

### Automated Scanning

**Core Data audit** → Delegate to the `core-data-auditor` subagent or `/axiom-audit` core-data (safety violations, architectural gaps — migration options, thread-confinement, N+1 queries, merge policies, context isolation)
**Codable audit** → Delegate to the `codable-auditor` subagent 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** → Delegate to the `icloud-auditor` subagent or `/axiom-audit` icloud (entitlement checks, file coordination, incomplete CKError matrix coverage, missing account-change observation, polling vs CKSubscriptions, SwiftData + CloudKit unsupported features, compound risks like uncoordinated I/O across extensions)
**Storage audit** → Delegate to the `storage-auditor` subagent or `/axiom-audit` storage (wrong file locations, missing backup exclusions, sensitive data on disk vs Keychain, missing App Group containers, unbounded cache growth, orphan files, compound risks like user data in tmp/ + critical content)
**Database schema audit** → Delegate to the `database-schema-auditor` subagent or `/axiom-audit` database-schema (unsafe ALTER TABLE, DROP operations, missing idempotency, FK constraints declared but not enforced, incomplete upgrade paths, compound risks like INSERT OR REPLACE on FK-referenced tables)
**GRDB performance audit** → Delegate to the `grdb-performance-auditor` subagent or `/axiom-audit` grdb-performance (raw SQL string interpolation, missing FK indexes in raw SQL, missing PRAGMA optimize for raw-GRDB apps, journal mode mismatch for app-group DBs, missing observesSuspensionNotifications for shared DBs, prefix-redundant indexes in raw SQL, legacy Record subclass, INSERT OR REPLACE misused as upsert, observation on WITHOUT ROWID tables, WITHOUT ROWID upsert below GRDB 7.11)
**SwiftData audit** → Delegate to the `swiftdata-auditor` subagent or `/axiom-audit` swiftdata (struct models, missing schema registration, array relationships without defaults, background context misuse, N+1 patterns, stale predicates, CloudKit conformance gaps, compound risks like struct model + array relationship)

## Decision Tree

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 perf, slow query, schema design for perf? → `skills/grdb-performance.md`
3b. FTS5 (full-text search, any layer)? → `skills/sqlite-fts-ref.md`
3c. DB shared across app + extension/widget/Live Activity? → `skills/grdb-app-groups.md`
4. SQLiteData? → `skills/sqlitedata.md`, `skills/sqlitedata-ref.md`
5. ANY schema migration? → `skills/database-migration.md` (ALWAYS — prevents data loss)
6. Realm migration? → `skills/realm-migration-ref.md`
7. SwiftData vs SQLiteData? → `skills/sqlitedata-migration.md`
8. Cloud sync architecture? → `skills/cloud-sync.md`
9. CloudKit? → `skills/cloudkit-ref.md`
10. iCloud Drive? → `skills/icloud-drive-ref.md`
11. Cloud sync errors? → `skills/cloud-sync-diag.md`
12. Codable/JSON serialization? → `skills/codable.md`
13. File storage strategy? → `skills/storage.md`, `skills/storage-diag.md`, `skills/storage-management-ref.md`
14. File protection? → See axiom-security (skills/file-protection-ref.md)
15. 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)
16. SecItem errors (errSecDuplicateItem, errSecItemNotFound, errSecInteractionNotAllowed)? → See axiom-security (skills/keychain-diag.md)
17. Encryption, signing, Secure Enclave, CryptoKit? → See axiom-security (skills/cryptokit.md), See axiom-security (skills/cryptokit-ref.md)
18. Quantum-secure cryptography, HPKE, ML-KEM? → See axiom-security (skills/cryptokit.md)
19. Want Core Data safety scan? → core-data-auditor (Agent)
20. Want Codable anti-pattern scan? → codable-auditor (Agent)
21. Want iCloud sync audit? → icloud-auditor (Agent)
22. Want storage location audit? → storage-auditor (Agent)
23. Want database schema/migration safety scan? → database-schema-auditor (Agent)
23a. Want GRDB performance/app-group scan? → grdb-performance-auditor (Agent)
24. Want SwiftData code audit? → swiftdata-auditor (Agent)
25. tvOS data persistence? → See axiom-swift (skills/tvos.md) (CRITICAL: no persistent local storage) + `skills/sqlitedata.md` (CloudKit SyncEngine)
26. SwiftData @MainActor / background context threading? → `/skill axiom-concurrency`
27. Structured data generation with Foundation Models? → `/skill axiom-ai`

#### Sync patterns
- HealthKit anchored/observer queries as a generalizable change-tracking pattern → See 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. |

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

## 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: "How do I make my GRDB queries faster?"
→ Read: `skills/grdb-performance.md`

User: "Add search to my GRDB-backed app" / "Add search to SQLiteData app"
→ Read: `skills/sqlite-fts-ref.md`

User: "My widget needs to read the same database as the app"
→ Read: `skills/grdb-app-groups.md`

User: "My widget shows stale data from the database"
→ Read: `skills/grdb-app-groups.md`

User: "Audit my GRDB code for performance issues"
→ Launch: `grdb-performance-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)

讨论

基于 GitHub Discussions。登录 GitHub 即可参与讨论、点赞、订阅更新。