axiom-icloud-drive-ref by charleswiltgen/axiom
npx skills add https://github.com/charleswiltgen/axiom --skill axiom-icloud-drive-ref用途:使用通用容器进行基于文件的 iCloud 同步的全面参考 可用性:iOS 5.0+(基础功能),iOS 8.0+(iCloud Drive),iOS 11.0+(现代 API) 上下文:基于文件的云存储,非数据库(结构化数据请使用 CloudKit)
在以下情况下使用此技能:
不适用于:具有关联关系的结构化数据(请改用 axiom-cloudkit-ref)
iCloud Drive 用于基于文件的同步,而非结构化数据。
适用场景:
不适用场景:
// ✅ CORRECT: Get iCloud container
func getICloudContainerURL() -> URL? {
// nil = use first container in entitlements
return FileManager.default.url(
forUbiquityContainerIdentifier: nil
)
}
// ✅ Check if iCloud is available
if let iCloudURL = getICloudContainerURL() {
print("iCloud available: \(iCloudURL)")
} else {
print("iCloud not available (not signed in or no entitlement)")
}
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
iCloud Container/
├── Documents/ # User-visible files (Files app)
│ └── MyApp/ # Your app's documents
├── Library/ # Hidden from user
│ ├── Application Support/
│ └── Caches/
// ✅ CORRECT: Save document to iCloud
func saveToICloud(data: Data, filename: String) throws {
guard let iCloudURL = FileManager.default.url(
forUbiquityContainerIdentifier: nil
) else {
throw iCloudError.notAvailable
}
let documentsURL = iCloudURL.appendingPathComponent("Documents")
// Create directory if needed
try FileManager.default.createDirectory(
at: documentsURL,
withIntermediateDirectories: true
)
let fileURL = documentsURL.appendingPathComponent(filename)
// Use file coordination for safe access
let coordinator = NSFileCoordinator()
var error: NSError?
coordinator.coordinate(
writingItemAt: fileURL,
options: .forReplacing,
error: &error
) { newURL in
try? data.write(to: newURL)
}
if let error = error {
throw error
}
}
访问 iCloud 文件时务必使用 NSFileCoordinator。这可以防止:
// ✅ CORRECT: Coordinated read
func readICloudFile(url: URL) throws -> Data {
let coordinator = NSFileCoordinator()
var data: Data?
var coordinationError: NSError?
coordinator.coordinate(
readingItemAt: url,
options: [],
error: &coordinationError
) { newURL in
data = try? Data(contentsOf: newURL)
}
if let error = coordinationError {
throw error
}
guard let data = data else {
throw fileError.readFailed
}
return data
}
// ✅ CORRECT: Coordinated write
func writeICloudFile(data: Data, to url: URL) throws {
let coordinator = NSFileCoordinator()
var coordinationError: NSError?
coordinator.coordinate(
writingItemAt: url,
options: .forReplacing,
error: &coordinationError
) { newURL in
try? data.write(to: newURL)
}
if let error = coordinationError {
throw error
}
}
// ✅ CORRECT: Coordinated move
func moveFile(from sourceURL: URL, to destURL: URL) throws {
let coordinator = NSFileCoordinator()
var coordinationError: NSError?
coordinator.coordinate(
writingItemAt: sourceURL,
options: .forMoving,
writingItemAt: destURL,
options: .forReplacing,
error: &coordinationError
) { newSource, newDest in
try? FileManager.default.moveItem(at: newSource, to: newDest)
}
if let error = coordinationError {
throw error
}
}
// ✅ Check if file is in iCloud
func isInICloud(url: URL) -> Bool {
let values = try? url.resourceValues(forKeys: [.isUbiquitousItemKey])
return values?.isUbiquitousItem ?? false
}
// ✅ Check download status
func getDownloadStatus(url: URL) -> String {
let values = try? url.resourceValues(forKeys: [
.ubiquitousItemDownloadingStatusKey,
.ubiquitousItemIsDownloadingKey,
.ubiquitousItemDownloadingErrorKey
])
if let downloading = values?.ubiquitousItemIsDownloading, downloading {
return "Downloading..."
}
if let status = values?.ubiquitousItemDownloadingStatus {
switch status {
case .current:
return "Downloaded"
case .notDownloaded:
return "Not downloaded (iCloud only)"
case .downloaded:
return "Downloaded"
@unknown default:
return "Unknown"
}
}
return "Unknown"
}
// ✅ Check upload status
func isUploading(url: URL) -> Bool {
let values = try? url.resourceValues(forKeys: [.ubiquitousItemIsUploadingKey])
return values?.ubiquitousItemIsUploading ?? false
}
// ✅ Check for conflicts
func hasConflicts(url: URL) -> Bool {
let values = try? url.resourceValues(forKeys: [
.ubiquitousItemHasUnresolvedConflictsKey
])
return values?.ubiquitousItemHasUnresolvedConflicts ?? false
}
// ✅ CORRECT: Request download
func downloadFromICloud(url: URL) throws {
try FileManager.default.startDownloadingUbiquitousItem(at: url)
}
// ✅ Monitor download progress
let query = NSMetadataQuery()
query.predicate = NSPredicate(format: "%K == %@",
NSMetadataItemURLKey, url as NSURL)
query.searchScopes = [NSMetadataQueryUbiquitousDataScope]
NotificationCenter.default.addObserver(
forName: .NSMetadataQueryDidUpdate,
object: query,
queue: .main
) { notification in
// Check progress
if let item = query.results.first as? NSMetadataItem {
if let percent = item.value(forAttribute: NSMetadataUbiquitousItemPercentDownloadedKey) as? Double {
print("Downloaded: \(percent)%")
}
}
}
query.start()
// ✅ Get conflict versions
func getConflictVersions(for url: URL) -> [NSFileVersion]? {
return NSFileVersion.unresolvedConflictVersionsOfItem(at: url)
}
// ✅ CORRECT: Resolve conflicts
func resolveConflicts(at url: URL, keepingVersion: ConflictResolution) throws {
guard let conflicts = NSFileVersion.unresolvedConflictVersionsOfItem(at: url),
!conflicts.isEmpty else {
return // No conflicts
}
let current = try NSFileVersion.currentVersionOfItem(at: url)
switch keepingVersion {
case .current:
// Keep current version, discard others
for conflict in conflicts {
conflict.isResolved = true
}
case .other(let chosenVersion):
// Replace current with chosen conflict version
try chosenVersion.replaceItem(at: url, options: [])
chosenVersion.isResolved = true
// Mark other conflicts as resolved
for conflict in conflicts where conflict != chosenVersion {
conflict.isResolved = true
}
case .manual:
// App merges manually, then marks resolved
let mergedData = mergeConflicts(current: current, conflicts: conflicts)
try mergedData.write(to: url)
for conflict in conflicts {
conflict.isResolved = true
}
}
// Remove resolved versions
try NSFileVersion.removeOtherVersionsOfItem(at: url)
}
enum ConflictResolution {
case current
case other(NSFileVersion)
case manual
}
仅适用于小型偏好设置(总计 <1 MB,<1024 个键)
// ✅ CORRECT: Sync small preferences
let store = NSUbiquitousKeyValueStore.default
// Set values
store.set(true, forKey: "darkModeEnabled")
store.set(2.0, forKey: "textSizeMultiplier")
store.set(["en", "es"], forKey: "selectedLanguages")
// Synchronize
store.synchronize()
// Read values
let darkMode = store.bool(forKey: "darkModeEnabled")
let textSize = store.double(forKey: "textSizeMultiplier")
// Listen for changes from other devices
NotificationCenter.default.addObserver(
forName: NSUbiquitousKeyValueStore.didChangeExternallyNotification,
object: store,
queue: .main
) { notification in
// Update UI with new values
updatePreferences()
}
限制:
<!-- iCloud capability -->
<key>com.apple.developer.icloud-services</key>
<array>
<string>CloudDocuments</string>
</array>
<!-- Ubiquitous containers -->
<key>com.apple.developer.ubiquity-container-identifiers</key>
<array>
<string>iCloud.com.example.app</string>
</array>
<!-- Key-value store (if using) -->
<key>com.apple.developer.ubiquity-kvstore-identifier</key>
<string>$(TeamIdentifierPrefix)com.example.app</string>
// ✅ Present iCloud document picker
import UniformTypeIdentifiers
let picker = UIDocumentPickerViewController(
forOpeningContentTypes: [.pdf, .plainText]
)
picker.delegate = self
picker.allowsMultipleSelection = false
// Enable iCloud
picker.directoryURL = getICloudContainerURL()
present(picker, animated: true)
// ✅ Monitor iCloud directory
class ICloudMonitor {
let query = NSMetadataQuery()
func startMonitoring(directory: URL) {
query.predicate = NSPredicate(format: "%K BEGINSWITH %@",
NSMetadataItemPathKey, directory.path)
query.searchScopes = [NSMetadataQueryUbiquitousDataScope]
NotificationCenter.default.addObserver(
forName: .NSMetadataQueryDidUpdate,
object: query,
queue: .main
) { [weak self] _ in
self?.processResults()
}
query.start()
}
func processResults() {
for item in query.results {
if let metadataItem = item as? NSMetadataItem,
let url = metadataItem.value(forAttribute: NSMetadataItemURLKey) as? URL {
print("File: \(url.lastPathComponent)")
}
}
}
}
| 任务 | API | 说明 |
|---|---|---|
| 获取 iCloud URL | FileManager.default.url(forUbiquityContainerIdentifier:) | 不可用时返回 nil |
| 检查是否在 iCloud 中 | .isUbiquitousItemKey 资源值 | 布尔值 |
| 下载文件 | startDownloadingUbiquitousItem(at:) | 异步,使用 NSMetadataQuery 监控 |
| 检查下载状态 | .ubiquitousItemDownloadingStatusKey | current/notDownloaded/downloaded |
| 检查冲突 | .ubiquitousItemHasUnresolvedConflictsKey | 布尔值 |
| 解决冲突 | NSFileVersion.unresolvedConflictVersionsOfItem(at:) | 手动合并或选择版本 |
| 同步偏好设置 | NSUbiquitousKeyValueStore.default | 总计 <1 MB |
| 文件协调 | NSFileCoordinator | 始终用于 iCloud 文件 |
axiom-storage — 选择 iCloud Drive 还是 CloudKitaxiom-cloudkit-ref — 用于结构化数据同步axiom-cloud-sync-diag — 调试 iCloud 同步问题最后更新:2025-12-12 技能类型:参考指南 最低 iOS 版本:5.0(基础功能),8.0(iCloud Drive),11.0(现代 API)
每周安装量
128
代码仓库
GitHub 星标数
674
首次出现
2026年1月21日
安全审计
已安装于
opencode112
codex107
claude-code106
gemini-cli105
cursor103
github-copilot102
Purpose : Comprehensive reference for file-based iCloud sync using ubiquitous containers Availability : iOS 5.0+ (basic), iOS 8.0+ (iCloud Drive), iOS 11.0+ (modern APIs) Context : File-based cloud storage, not database (use CloudKit for structured data)
Use this skill when:
NOT for : Structured data with relationships (use axiom-cloudkit-ref instead)
iCloud Drive is for FILE-BASED sync , not structured data.
Use when :
Don't use when :
// ✅ CORRECT: Get iCloud container
func getICloudContainerURL() -> URL? {
// nil = use first container in entitlements
return FileManager.default.url(
forUbiquityContainerIdentifier: nil
)
}
// ✅ Check if iCloud is available
if let iCloudURL = getICloudContainerURL() {
print("iCloud available: \(iCloudURL)")
} else {
print("iCloud not available (not signed in or no entitlement)")
}
iCloud Container/
├── Documents/ # User-visible files (Files app)
│ └── MyApp/ # Your app's documents
├── Library/ # Hidden from user
│ ├── Application Support/
│ └── Caches/
// ✅ CORRECT: Save document to iCloud
func saveToICloud(data: Data, filename: String) throws {
guard let iCloudURL = FileManager.default.url(
forUbiquityContainerIdentifier: nil
) else {
throw iCloudError.notAvailable
}
let documentsURL = iCloudURL.appendingPathComponent("Documents")
// Create directory if needed
try FileManager.default.createDirectory(
at: documentsURL,
withIntermediateDirectories: true
)
let fileURL = documentsURL.appendingPathComponent(filename)
// Use file coordination for safe access
let coordinator = NSFileCoordinator()
var error: NSError?
coordinator.coordinate(
writingItemAt: fileURL,
options: .forReplacing,
error: &error
) { newURL in
try? data.write(to: newURL)
}
if let error = error {
throw error
}
}
Always use NSFileCoordinator when accessing iCloud files. This prevents:
// ✅ CORRECT: Coordinated read
func readICloudFile(url: URL) throws -> Data {
let coordinator = NSFileCoordinator()
var data: Data?
var coordinationError: NSError?
coordinator.coordinate(
readingItemAt: url,
options: [],
error: &coordinationError
) { newURL in
data = try? Data(contentsOf: newURL)
}
if let error = coordinationError {
throw error
}
guard let data = data else {
throw fileError.readFailed
}
return data
}
// ✅ CORRECT: Coordinated write
func writeICloudFile(data: Data, to url: URL) throws {
let coordinator = NSFileCoordinator()
var coordinationError: NSError?
coordinator.coordinate(
writingItemAt: url,
options: .forReplacing,
error: &coordinationError
) { newURL in
try? data.write(to: newURL)
}
if let error = coordinationError {
throw error
}
}
// ✅ CORRECT: Coordinated move
func moveFile(from sourceURL: URL, to destURL: URL) throws {
let coordinator = NSFileCoordinator()
var coordinationError: NSError?
coordinator.coordinate(
writingItemAt: sourceURL,
options: .forMoving,
writingItemAt: destURL,
options: .forReplacing,
error: &coordinationError
) { newSource, newDest in
try? FileManager.default.moveItem(at: newSource, to: newDest)
}
if let error = coordinationError {
throw error
}
}
// ✅ Check if file is in iCloud
func isInICloud(url: URL) -> Bool {
let values = try? url.resourceValues(forKeys: [.isUbiquitousItemKey])
return values?.isUbiquitousItem ?? false
}
// ✅ Check download status
func getDownloadStatus(url: URL) -> String {
let values = try? url.resourceValues(forKeys: [
.ubiquitousItemDownloadingStatusKey,
.ubiquitousItemIsDownloadingKey,
.ubiquitousItemDownloadingErrorKey
])
if let downloading = values?.ubiquitousItemIsDownloading, downloading {
return "Downloading..."
}
if let status = values?.ubiquitousItemDownloadingStatus {
switch status {
case .current:
return "Downloaded"
case .notDownloaded:
return "Not downloaded (iCloud only)"
case .downloaded:
return "Downloaded"
@unknown default:
return "Unknown"
}
}
return "Unknown"
}
// ✅ Check upload status
func isUploading(url: URL) -> Bool {
let values = try? url.resourceValues(forKeys: [.ubiquitousItemIsUploadingKey])
return values?.ubiquitousItemIsUploading ?? false
}
// ✅ Check for conflicts
func hasConflicts(url: URL) -> Bool {
let values = try? url.resourceValues(forKeys: [
.ubiquitousItemHasUnresolvedConflictsKey
])
return values?.ubiquitousItemHasUnresolvedConflicts ?? false
}
// ✅ CORRECT: Request download
func downloadFromICloud(url: URL) throws {
try FileManager.default.startDownloadingUbiquitousItem(at: url)
}
// ✅ Monitor download progress
let query = NSMetadataQuery()
query.predicate = NSPredicate(format: "%K == %@",
NSMetadataItemURLKey, url as NSURL)
query.searchScopes = [NSMetadataQueryUbiquitousDataScope]
NotificationCenter.default.addObserver(
forName: .NSMetadataQueryDidUpdate,
object: query,
queue: .main
) { notification in
// Check progress
if let item = query.results.first as? NSMetadataItem {
if let percent = item.value(forAttribute: NSMetadataUbiquitousItemPercentDownloadedKey) as? Double {
print("Downloaded: \(percent)%")
}
}
}
query.start()
// ✅ Get conflict versions
func getConflictVersions(for url: URL) -> [NSFileVersion]? {
return NSFileVersion.unresolvedConflictVersionsOfItem(at: url)
}
// ✅ CORRECT: Resolve conflicts
func resolveConflicts(at url: URL, keepingVersion: ConflictResolution) throws {
guard let conflicts = NSFileVersion.unresolvedConflictVersionsOfItem(at: url),
!conflicts.isEmpty else {
return // No conflicts
}
let current = try NSFileVersion.currentVersionOfItem(at: url)
switch keepingVersion {
case .current:
// Keep current version, discard others
for conflict in conflicts {
conflict.isResolved = true
}
case .other(let chosenVersion):
// Replace current with chosen conflict version
try chosenVersion.replaceItem(at: url, options: [])
chosenVersion.isResolved = true
// Mark other conflicts as resolved
for conflict in conflicts where conflict != chosenVersion {
conflict.isResolved = true
}
case .manual:
// App merges manually, then marks resolved
let mergedData = mergeConflicts(current: current, conflicts: conflicts)
try mergedData.write(to: url)
for conflict in conflicts {
conflict.isResolved = true
}
}
// Remove resolved versions
try NSFileVersion.removeOtherVersionsOfItem(at: url)
}
enum ConflictResolution {
case current
case other(NSFileVersion)
case manual
}
For small preferences only (<1 MB total, <1024 keys)
// ✅ CORRECT: Sync small preferences
let store = NSUbiquitousKeyValueStore.default
// Set values
store.set(true, forKey: "darkModeEnabled")
store.set(2.0, forKey: "textSizeMultiplier")
store.set(["en", "es"], forKey: "selectedLanguages")
// Synchronize
store.synchronize()
// Read values
let darkMode = store.bool(forKey: "darkModeEnabled")
let textSize = store.double(forKey: "textSizeMultiplier")
// Listen for changes from other devices
NotificationCenter.default.addObserver(
forName: NSUbiquitousKeyValueStore.didChangeExternallyNotification,
object: store,
queue: .main
) { notification in
// Update UI with new values
updatePreferences()
}
Limitations :
<!-- iCloud capability -->
<key>com.apple.developer.icloud-services</key>
<array>
<string>CloudDocuments</string>
</array>
<!-- Ubiquitous containers -->
<key>com.apple.developer.ubiquity-container-identifiers</key>
<array>
<string>iCloud.com.example.app</string>
</array>
<!-- Key-value store (if using) -->
<key>com.apple.developer.ubiquity-kvstore-identifier</key>
<string>$(TeamIdentifierPrefix)com.example.app</string>
// ✅ Present iCloud document picker
import UniformTypeIdentifiers
let picker = UIDocumentPickerViewController(
forOpeningContentTypes: [.pdf, .plainText]
)
picker.delegate = self
picker.allowsMultipleSelection = false
// Enable iCloud
picker.directoryURL = getICloudContainerURL()
present(picker, animated: true)
// ✅ Monitor iCloud directory
class ICloudMonitor {
let query = NSMetadataQuery()
func startMonitoring(directory: URL) {
query.predicate = NSPredicate(format: "%K BEGINSWITH %@",
NSMetadataItemPathKey, directory.path)
query.searchScopes = [NSMetadataQueryUbiquitousDataScope]
NotificationCenter.default.addObserver(
forName: .NSMetadataQueryDidUpdate,
object: query,
queue: .main
) { [weak self] _ in
self?.processResults()
}
query.start()
}
func processResults() {
for item in query.results {
if let metadataItem = item as? NSMetadataItem,
let url = metadataItem.value(forAttribute: NSMetadataItemURLKey) as? URL {
print("File: \(url.lastPathComponent)")
}
}
}
}
| Task | API | Notes |
|---|---|---|
| Get iCloud URL | FileManager.default.url(forUbiquityContainerIdentifier:) | Returns nil if unavailable |
| Check if in iCloud | .isUbiquitousItemKey resource value | Bool |
| Download file | startDownloadingUbiquitousItem(at:) | Async, monitor with NSMetadataQuery |
| Check download status | .ubiquitousItemDownloadingStatusKey | current/notDownloaded/downloaded |
| Check for conflicts | .ubiquitousItemHasUnresolvedConflictsKey |
axiom-storage — Choose iCloud Drive vs CloudKitaxiom-cloudkit-ref — For structured data syncaxiom-cloud-sync-diag — Debug iCloud sync issuesLast Updated : 2025-12-12 Skill Type : Reference Minimum iOS : 5.0 (basic), 8.0 (iCloud Drive), 11.0 (modern APIs)
Weekly Installs
128
Repository
GitHub Stars
674
First Seen
Jan 21, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykPass
Installed on
opencode112
codex107
claude-code106
gemini-cli105
cursor103
github-copilot102
Supabase Postgres 最佳实践指南 - 8大类别性能优化规则与SQL示例
78,800 周安装
| Bool |
| Resolve conflicts | NSFileVersion.unresolvedConflictVersionsOfItem(at:) | Manual merge or choose version |
| Sync preferences | NSUbiquitousKeyValueStore.default | <1 MB total |
| File coordination | NSFileCoordinator | Always use for iCloud files |