Adrafinil: macOS 上的 AI 编程智能体条件式睡眠预防工具

Adrafinil: macOS 上的 AI 编程智能体条件式睡眠预防工具

Adrafinil 是一款专为 macOS 设计的实用程序，旨在仅在 AI 编程智能体活跃会话期间保持 Mac 处于唤醒状态，从而允许系统在没有工作进行时正常进入睡眠模式。与始终开启的唤醒工具不同，Adrafinil 仅在智能体执行任务中时动态阻止睡眠——包括合盖模式（clamshell）睡眠——并在会话结束时自动释放锁定。

智能体感知型睡眠管理

当一个或多个 AI 编程智能体会话持有活跃的断言（assertion）时，Adrafinil 会阻止系统进入睡眠。当没有活跃会话时，Mac 的默认睡眠行为保持不变。这种方法与 caffeinate 或 Amphetamine 等工具不同，后者通常无论实际系统活动如何都会维持恒定的唤醒状态。

支持的智能体与集成

Adrafinil 提供了一键式安装程序，可与九种 AI 智能体的钩子系统（hook systems）集成：

  • 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 空闲，断言将自动释放。
  • 开盖状态反馈 (Lid-State Feedback): 合盖时会发出提示音以确认断言已持有。重新开盖时，用户会看到运行情况摘要，包括运行了什么、达到的峰值温度以及是否发生了热量切断。

要求与安装

Adrafinil 需要 macOS Tahoe 26.4（或可能更早的 26.x 版本）并使用 Xcode 26+ 结合 Swift 6 严格并发模式构建。安装需要管理员权限，以便通过 SMAppService 注册特权辅助程序。

社区观点

虽然该工具解决了 AI 智能体用户的特定痛点，但一些社区成员提出了更简单的替代方案或表达了担忧：

  • 现有工具: 一些用户指出，Amphetamine 等应用可以设置为在特定应用关闭时结束，或者使用基于 pmset 的简单 shell 脚本可以实现类似效果。
  • 硬件风险: 用户提醒开发者，笔记本电脑在背包内无法有效散热，这证明了加入热量切断功能的必要性。
  • 手动替代方案: 一位用户建议使用虚拟 HDMI/USB-C 插头来模拟外部显示器以防止睡眠，尽管他们报告结果并不一致。

"I used to do this :// 15 年前我曾这样做来让我的笔记本电脑保持听音乐... 一个注意事项是，你的笔记本电脑在背包内无法有效散热，它会过热并自动关机。"

CLI 命令摘要

| Command | Purpose | | :--- | :--- | | | acquire <key> | 智能体轮次开始时阻止睡眠 | | release <key> | 智能体进入空闲时取消阻止睡眠 | | hold --for <time> | 为后台任务（如部署）提供限时唤醒 | | mcp | 在 stdio 上启用 Model Context Protocol 通信 | | status | 检查当前断言状态 |

Sources