mac-health

mac-health 技能指引 (Agent Skill Guide)

本技能規範 AI Agent 如何使用 diagnose.py、optimizer.py、compare.py 進行嚴謹、客觀、不誇大結論的 macOS 系統健康診斷與改善閉環。

---

1. 核心分析與判斷準則 (RCA Calibration Principles)

1. 嚴格分級分類：
   • CONFIRMED BOTTLENECK：必須有明確、充分且不可辯駁的實質證據（例如：Critical 記憶體壓力且 Free < 20%、CPU 持續 > 85% 且特定進程獨佔、SSD 可用空間 < 15GB）。
   • LIKELY CONTRIBUTOR：指標處於 Warning 且有單一巨量進程（> 2GB RAM / > 50% CPU）。
   • ATTENTION：歷史 Swap 較高、短暫 I/O 觀測較忙、或 Memory Free 位於 30%~40% 邊界但無失控進程。
   • NORMAL：指標處於安全區間。
   • UNKNOWN：無法確定或無足夠權限取得之數據。
2. Top Process 語意修正 (Notable != Problem)：
   • 單一 WebKit / 瀏覽器進程使用 500MB ~ 1.2GB RAM 屬於現代多工作瀏覽器分頁之常見正常負載，標記為 Notable process，嚴禁直接判定為卡頓主因或問題進程。
   • 嚴禁直接建議終止 WebKit raw PID（例如禁止 kill PID 82252）。建議優先順序：1. 使用者自行檢視分頁並關閉不需要的分頁；2. 瀏覽器若持續卡頓建議正常重啟瀏覽器；3. 只有確認失控且獲明確核准才進行進程終止。
3. Swap 歷史語意：
   • 歷史累積 Swap 高（如 20 GB）但當前即時 Memory Pressure 處於 Normal/穩態時，僅為 Historical memory pressure evidence 或 ATTENTION，不得直接宣稱為「當前已確認瓶頸」。
4. 重新啟動 Mac 語意修正：
   • 重開機分類為 Low-cost troubleshooting / reset step。
   • 禁止宣稱「徹底恢復流暢度」、「恢復出廠狀態」或「一定能改善」。
   • 建議措辭：「如果目前仍有明顯卡頓，可在工作告一段落後正常重新啟動，作為低風險排查步驟；重啟會重置目前程序與 Swap 狀態，但不能保證根本問題消失。」
5. 預期效益措辭嚴謹：
   • 優先使用「可能降低 Memory Pressure」、「可能釋放約 X MB process RSS」、「可能有助於改善反應速度」，禁止無證據承諾百分比或系統一定變快。
6. 保守 Optimization Gate：
   • 若 Confirmed bottleneck = None，預設回覆 「目前不需要立即修改系統。」，不為了交差而硬生產生優化動作。

---

2. Agent 標準輸出順序

未找到 Confirmed Bottleneck 時，必須優先明確宣告無確認瓶頸，接著條列各項指標：

Mac Health 診斷與分析報告
────────────────────────

Confirmed bottleneck:
None (目前沒有已確認的效能瓶頸)

Likely contributor:
None

Attention:
• Memory: 歷史 Swap 累計較高 (X GB)，當前 derived pressure 位於 warning 邊界 (Free: Y%)。無單一失控進程。

Normal:
• CPU (即時使用率 X%，負載正常)
• Disk capacity (剩餘 X GB, 空間充足)
• Disk I/O observation (抽樣讀寫平穩)
• Thermal (溫度正常，無熱降頻)
• Spotlight (索引待機正常)

Notable processes:
• com.apple.WebKit.WebContent (PID: X, 650 MB) — 屬於現代多工作網頁常見佔用，未確認異常。

Recommendation:
目前不需要立即修改系統。
若實際仍感到卡頓，可先檢視並關閉確定不需要的瀏覽器分頁；若卡頓持續，可於工作告一段落後正常重新啟動 Mac 作為低風險排查步驟。

---

3. 安全操作分級 (Safety Levels)