Community生產力與協作github.com

mac-tuneup

診斷並修復 Mac 速度變慢、磁碟或 iCloud 儲存空間近乎滿載的問題:先測量再修復,使用唯讀診斷腳本、安全的修復腳本模式,以及經驗證的 iCloud 照片卸載至外接磁碟。當 Mac 感覺變慢、啟動磁碟或 iCloud 儲存空間近乎滿載,或使用者想要安全清理時使用。

mac-tuneup 是什麼?

mac-tuneup 是一個專為 AI 代理(如 Claude Code、Cursor、Codex)設計的 Mac 系統調校技能,其核心原則是「先測量,再修復」。它透過一系列唯讀診斷腳本,量化分析 Mac 變慢或儲存空間滿載的根本原因,避免未經診斷就盲目修復。此技能支援在 Mac 本機終端機中執行,使用者需自行執行修復腳本,AI 代理僅負責生成腳本。 此技能的實用性在於它提供了一套結構化的工作流程:首先執行全面的診斷腳本,收集機器狀態、記憶體壓力、磁碟空間、重複崩潰的程式等資訊;然後根據診斷結果,針對關鍵問題(如磁碟空間不足、記憶體壓力、過熱降頻、iCloud 儲存空間不足)進行深入分析;最後根據使用者選擇,生成安全的修復腳本,並進行驗證。 mac-tuneup 的關鍵限制包括:絕不直接刪除使用者資料(僅移至垃圾桶)、絕不修改安全相關設定、絕不繞過熱能或電源保護機制。它明確區分唯讀調查和可寫入修復,所有需要 sudo 或可能造成影響的操作都包裝在由使用者執行的腳本中。對於 iCloud 儲存空間,它提供了一個經驗證的流程來管理和卸載照片,同時也強調了手動檢查和管理 CloudKit 資料的必要性。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/osencan/mac-tuneup/tree/main/mac-tuneup

Installed? Explore more 生產力與協作 skills: steipete/gemini, steipete/gh-issues, steipete/skill-creator · View all 6 →

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

mac-tuneup 是做什麼的?

透過測量找出 Mac 變慢或空間不足的原因,告知使用者最重要的發現,並提供由使用者自行執行的小型腳本。使用此方法調校過的三台 Mac 各自有不同的主要原因(Fusion Drive 加上崩潰循環的 daemon、執行中應用程式導致 RAM 不足、磁碟已滿),因此在修復之前絕對要先進行測量。

基本原則

  • 先唯讀。 在調查期間不進行任何變更。
  • 由使用者執行修復。 編寫腳本;除非被要求,否則不要自己套用任何變更。任何需要 sudo 的操作都要放在腳本中(你無法輸入使用者的密碼)。
  • 在移除任何應用程式、輔助軟體或資料之前先詢問。 提供候選項目的容量大小及建議,讓使用者選擇。
  • 絕不刪除使用者資料。 移至 ~/.Trash/<名稱>-removed-<時間戳記>/。設定變更需要 --undo 並記錄先前的值。
  • 絕不關閉 安全性更新程式、Spotlight、Gatekeeper、SIP 或 FileVault,也絕不抹除、分割或重新格式化磁碟。
  • 絕不移除熱能或電源保護。 不要修補電源管理設定檔或 kext、寫入 CPU 暫存器(例如關閉 BD PROCHOT),或停用密封的系統捲宗來「解鎖」速度。來自熱能或硬體警告的降頻是一種徵兆:找出並修復原因。將「Claude 移除了 Apple 的降頻機制」這類傳聞視為需要驗證的主張,而非可遵循的配方(請參閱 references/pitfalls.md)。
  • 如實告知效益。 當某個修復僅能提供微小幫助時要說明,並在 README 中修正自己的發現。

執行環境

腳本必須在 Mac 上執行。如果你有該 Mac 的 shell 存取權限,請自行執行唯讀腳本。如果你只有沙盒或同步的資料夾,則將腳本放在使用者可以存取的資料夾中,請他們執行 bash <script> > /dev/null 2>&1 並讀取腳本在執行位置旁邊寫入的報告檔案(diagnose-<date>.txt 等)。需要詢問 y/N 或輸入密碼的腳本必須在沒有 > /dev/null 的情況下執行。

如果你需要的檔案讀取大小為 0 bytes,它們可能是雲端佔位檔案(Dropbox 線上唯讀、iCloud 最佳化):請使用者讓該資料夾保持離線可用。

工作流程

  1. 診斷。 scripts/diagnose.sh(1-2 分鐘):機器、電源與降頻、記憶體壓力與每個應用程式的記憶體用量、記憶體不足終止事件、30 秒內的 CPU 使用率、磁碟空間、程式已遺失的啟動項目、登入項目、Rosetta、重複崩潰的程式、顯示器。
  2. 排序並及早報告。 先說明主要發現,使用白話,並附上數據。接著列出簡短的「哪些是正常的」清單。
  3. 針對關鍵處深入調查。
    • 可用磁碟空間低於 ~20%:scripts/space-detail.sh(先授予終端機完整磁碟存取權)。使用 xcrun simctl runtime list 查看模擬器大小。
    • Apple 自有媒體應用程式:scripts/apple-media-cleanup.sh 會報告 Podcasts(單集)、Music、TV 和 Books(快取)的可重新下載資料、GarageBand/Logic 音效資料庫以及 iPhone 更新檔案;--apply 會將選擇的群組逐項以 y/N 方式移至垃圾桶。它不會動到圖書館、與使用者個人檔案混合的下載檔案以及備份。
    • 記憶體:列出應用程式名稱;壓縮器使用超過 ~3 GB、swap 使用超過 ~2 GB 或出現記憶體不足終止事件,表示存在壓力(檢查 JetsamEvent 的 reason)。
    • 懷疑降頻(CPU_Speed_Limit 低於 100、kernel_task 忙碌、風扇大聲、較舊的 Intel MacBook 持續變慢):scripts/throttle-check.sh(需要 sudo,唯讀)。它會測量頻率、溫度、熱壓力、充電器和電池,並指出模式:過熱(清理通風口/風扇、更換散熱膏、負載)、Intel 上的 BD PROCHOT(電池、充電器、連接埠、感應器;重置 SMC)或完全沒有降頻。
    • 刻意節能的降速:scripts/dethrottle.sh 報告每個電源來源的低耗電模式、App Nap 和背景磁碟節流;--apply 會逐項以 y/N 方式關閉選擇的項目,--undo 則恢復。這些是此技能唯一會進行的「解除節流」操作。電池健康度管理只會改變充電方式,不會影響 CPU 速度(Apple)。
    • 重複崩潰的程式(診斷的第 8 節):scripts/crash-report.sh(30 表示 30 天)會指出每個崩潰行程的擁有者:應用程式、輔助程式、應用程式擴充功能(Quick Look、縮圖、分享)或 macOS 的一部分以及它正在為哪個應用程式工作;該程式是否仍已安裝;以及該怎麼做。資源報告(CPU 使用率、磁碟寫入)會與崩潰分開列出。
    • 每幾分鐘崩潰一次的 daemon(ReportCrash/coresymbolicationd 忙碌,同一個行程有許多 .ips 檔案):讀取回溯追蹤(backtrace)。
  4. 詢問。 每個區域提出一個問題,附上容量大小和建議選項(模擬器、模型、舊應用程式資料、快取、輔助程式)。使用多選。
  5. 編寫修復腳本,使用 references/fix-patterns.md 中的模式:編號、每個修復一個腳本、每組以 y/N 確認、使用垃圾桶而非 rm、先顯示容量大小。對每個腳本執行 bash -n 和 shellcheck。
  6. 驗證。 編寫一個唯讀檢查,確認所有移除的項目都已消失、所有工作都已卸載,將可用空間與基準值進行比較,然後重新啟動並再次執行 diagnose.sh。第二次檢查可以捕捉到第一次遺漏的問題。
  7. 在使用者的資料夾中建立 README:發現表格、哪些是正常的、他們保留了什麼、執行順序、套用了哪些修復、預期的改善幅度。

iCloud 近乎滿載

  1. scripts/icloud-report.sh(需要完整磁碟存取權):按資料夾顯示 iCloud 雲碟大小(雲端大小)、按類型和年份顯示照片並附上最大的影片和截圖大小、訊息附件、郵件。
  2. 要求提供系統設定 > Apple 帳號 > iCloud > 管理的截圖。非 Mac 上的應用程式備份和資料僅在此處可見。
  3. 與使用者一起規劃。常見的處理方式:將大型影片和舊截圖移至外接磁碟、刪除舊的裝置備份、從 iPhone 備份中排除大型應用程式、不包含影片的 WhatsApp 備份、大型訊息附件。當資料庫的增長速度超過清理釋放的空間速度時,請將更長遠的計畫作為誠實的替代方案提出。
  4. 照片卸載(需要 BACKUP_DIR,例如 /Volumes/MyDisk/icloud-backup):
    • scripts/photos-albums-verify.sh albums videos|screenshots|years ... 為每一年建立一個相簿(不進行任何下載或刪除)。
    • 使用者從照片應用程式中匯出每個相簿(匯出未修改的原始檔)。不要使用 osxphotos 從 iCloud 下載;請參閱 pitfalls。
    • ... verify <kind> 會列出完全存在於磁碟上的相簿;... retry <kind> 僅對缺少的項目建立相簿。
    • scripts/photos-delete-verified.sh <kind> 僅刪除那些在磁碟上的檔案名稱和位元組大小完全相符的項目,透過 PhotoKit 進行,並放入「最近刪除」(保留 30 天)。使用者需清空「最近刪除」才能釋放 iCloud 空間。
    • 下載失敗並出現 -1009 或速度極慢:scripts/network-check.sh;使用有線連接,一次一個相簿,在長時間匯出期間使用 scripts/keep-awake.sh(事後執行 --undo)。
  5. iCloud 中的應用程式資料(例如筆記應用程式):它可能存在於 CloudKit 中,而非檔案形式。在「管理儲存空間」中刪除它之前,請先從應用程式內部匯出。

編寫修復腳本前請先閱讀

  • references/pitfalls.md:真實操作中出錯的案例(指令掛起、誤導性的基準測試、du 的陷阱、常規性的崩潰循環、osxphotos 超時、透過 Wi-Fi 進行的整夜匯出)以及有效的解決方案。
  • references/fix-patterns.md:用於垃圾桶移動、launchd 項目、附有 --undo 的設定、模擬器、僅需點擊的修復、驗證階段的腳本範本。

相關技能