Adrafinil: macOS AI 編碼代理程式的條件式睡眠防止工具

Adrafinil: macOS AI 編碼代理程式的條件式睡眠防止工具

Adrafinil 是一款專為 macOS 設計的工具，旨在僅在 AI 編碼代理程式活躍的工作階段期間保持 Mac 喚醒，並允許系統在沒有工作進行時正常進入睡眠狀態。與始終開啟的喚醒工具不同，Adrafinil 僅在代理程式執行任務的中途動態地阻止睡眠——包括闔蓋模式 (clamshell) 睡眠——並在工作階段結束後自動釋放鎖定。

代理程式感知型睡眠管理

當一個或多個 AI 編碼代理程式工作階段持有活躍的斷言 (assertion) 時，Adrafinil 才會防止系統進入睡眠。當沒有任何工作階段處於活躍狀態時，Mac 的預設睡眠行為將保持不變。這種方法與 caffeinate 或 Amphetamine 等工具不同，後者通常不論實際系統活動如何，都會維持恆定的喚醒狀態。

支援的代理程式與整合

Adrafinil 提供一鍵式安裝程式，可與九種 AI 代理程式的掛鉤 (hook) 系統整合：

  • Claude Code
  • Codex
  • Cursor
  • Gemini CLI
  • Aider
  • Hermes
  • OpenCode
  • Cline
  • Pi

整合是透過一個內建的 CLI 處理的，代理程式在任務開始時會呼叫它來 acquire 一個工作階段金鑰，並在代理程式進入閒置狀態時呼叫它來 release。這些 CLI 呼叫經過優化，往返時間低於 50ms，以確保不會阻礙代理程式的工作流程。

技術架構與安全性

由於覆蓋闔蓋模式睡眠需要 root 權限，Adrafinil 使用分層架構來最小化特權攻擊面。

權限層級

  1. Adrafinil.app: 一個面向使用者的介面列應用程式，負責處理 UI、設定以及闔蓋摘要資訊。
  2. AdrafinilDaemon: 一個以使用者身份運行的 LaunchAgent。此組件負責管理引用計數斷言註冊表、監控溫度與闔蓋狀態，並處理 CLI socket。
  3. AdrafinilHelper: 一個 root 層級的 SMAppService LaunchDaemon。這是唯一具有存取睡眠阻止 API 的組件，並提供簡單的 setSleepBlocked(Bool) 方法。它在執行指令前會驗證呼叫者的程式碼簽章要求。

睡眠阻止機制

Adrafinil 對於閒置睡眠使用標準的 IOPMAssertion。為了處理闔蓋模式睡眠，它採用了 pmset disablesleep 1。開發者指出，公開的 IOPM 斷言（如 caffeinate 所使用的）不足以讓闔蓋的 Mac 保持喚醒。為了防止狀態洩漏，helper 在重新啟動時會先將 disablesleep 重設為 0，然後再重新套用當前狀態。

安全與監控功能

為了防止硬體損壞並確保系統穩定性，Adrafinil 包含幾項自動化防護措施：

  • 溫度切斷 (Thermal Cutout): 如果在闔蓋時 CPU 或表面溫度超過預設閾值，所有斷言將被強制釋放，以防止 Mac 在密閉空間（例如筆記型電腦包）中過熱。
  • 閒置釋放 (Idle Release): 如果持有者程序結束或在指定分鐘數內保持 CPU 閒置，斷言將會自動釋放。
  • 闔蓋狀態回饋: 闔蓋時會發出提示音以確認斷言已被持有。重新開啟時，使用者會看到一份摘要，說明執行了哪些工作，達到過的峰值溫度，以及是否發生了溫度切斷。

需求與安裝

Adrafinil 需要 macOS Tahoe 26.4（或可能更早的 26.x 版本）並使用 Xcode 26+ 與 Swift 6 嚴格並行處理 (strict concurrency) 建置。安裝需要管理員權限以透過 SMAppService 註冊特權輔助程式。

社群觀點

雖然此工具解決了 AI 代理程式使用者的特定痛點，但一些社群成員提出了更簡單的替代方案或提出了疑慮：

  • 現有工具: 一些使用者指出，Amphetamine 等應用程式可以在特定應用程式關閉時結束，或使用 pmset 的簡單 shell 腳本可以達到類似效果。
  • 硬體風險: 使用者提醒開發者，筆記型電腦在背包內無法有效散熱，這證明了加入溫度切斷功能的必要性。
  • 手動替代方案: 有一名使用者建議使用虛擬 HDMI/USB-C 插頭來模擬外部顯示器以防止睡眠，但他們報告結果並不一致。

"I used to do this 15 years ago to keep listening to music from my laptop... One caveat, your laptop cannot cool inside a backpack, it will overheat and shut down anyway."

CLI 指令摘要

| Command | Purpose | | :--- | :--- | | | acquire <key> | 當代理程式回合開始時阻止睡眠 | | release <key> | 當代理程式進入閒置時解除阻止睡眠 | | hold --for <time> | 為背景任務（例如部署）提供限時喚醒功能 | | mcp | 在 stdio 上啟用 Model Context Protocol 通訊 | | status | 檢查當前斷言狀態 |

Sources