Show HN: Adrafinil – 仅在 AI Agent 工作时保持合盖 Mac 唤醒

背景

凌晨 3 点，你已经入睡，但你的 AI 编程助手（Agent）并没有休息。它可能正处于你数小时前启动的会话中，还在进行复杂的思考或代码生成。此时，你像闭合眼睑一样合上了 MacBook 的屏幕。

传统的 macOS 睡眠管理工具（如 caffeinate 或 Amphetamine）属于“兴奋剂”类应用：它们无论是否有人使用，都会让机器保持永久唤醒状态。这种“始终在线”的策略不仅浪费电力，还可能导致设备过热，尤其是在合盖携带或存放时。

为了解决这一痛点，开发者推出了 Adrafinil。这个名字借用了药物阿德拉非尼（一种促醒药）的概念，意在让 Mac 在 AI Agent 工作时保持清醒，而在工作结束后立即恢复睡眠。它并非让机器永远兴奋，而是仅在必要时介入，实现“按需唤醒”。

核心内容

Adrafinil 是一款 macOS 菜单栏应用，其核心功能是仅在 AI 编程 Agent 拥有活跃会话时，阻止系统进入睡眠状态（包括合盖睡眠）。当没有 Agent 工作时，Mac 的睡眠行为完全不受影响：合上盖子，电脑正常休眠。

工作原理与架构

Adrafinil 采用了一种精细的权限隔离架构，以确保安全性和稳定性：

1. 特权睡眠控制： 覆盖合盖睡眠（Clamshell sleep）需要 root 权限。Adrafinil 将这一操作隔离在一个经过审计的微小辅助程序（Helper）中，该程序仅暴露 setSleepBlocked(Bool) 接口。所有的策略逻辑（如引用计数、温度监控）都运行在无特权的守护进程（Daemon）中。

   • 对于空闲睡眠，它使用标准的 IOPMAssertion。
   • 对于合盖睡眠，它使用 pmset disablesleep，但在应用前会验证设备上的私有 IOPMrootDomain 路径，确保不会导致无显示器的合盖 Mac 意外唤醒。

2. Agent 感知而非始终在线： 睡眠阻止仅在 ≥1 个 Agent 会话持有断言（Assertion）时生效。零会话时，系统正常睡眠，包括合盖。

3. Hook 集成： 提供一键安装程序，将 Adrafinil 接入 9 种主流 AI 编程工具的 Hook 系统，包括：

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

4. 性能优化： CLI 命令（adrafinil acquire / release）从 Agent Hook 调用，往返时间低于 50ms，确保不会阻塞 Agent 的工作流。

5. 安全机制：

   • 引用计数断言：重叠的会话可以干净地堆叠；只有当最后一个会话释放时，睡眠阻止才会解除。
   • 热切断（Thermal Cutout）：如果检测到皮肤或 CPU 温度超过阈值（特别是在合盖状态下），所有断言会被强制释放，防止设备在包中过热。
   • 空闲释放：如果拥有断言的进程已死亡或 CPU 空闲超过 N 分钟，断言会自动丢弃。
   • 进程嗅探（可选）：即使未安装 Hook，守护进程也可以通过检测已知 Agent 二进制文件的运行来自动获取断言。

6. 用户体验细节：

   • 合盖音频提示：当你合上盖子且断言被持有时，会播放提示音（因为屏幕关闭，无法显示通知）。
   • 开盖摘要：重新打开盖子时，会显示你离开期间运行的任务、峰值温度以及是否触发了热切断。
   • 干净卸载：移除所有 Agent 配置中添加的 Hook 条目。

技术实现细节

Adrafinil 由四个产品组成，跨越三个权限层级：

• Adrafinil.app：菜单栏应用，面向用户，负责状态显示、设置、安装 GUI 和开盖摘要。
• AdrafinilDaemon：作为 LaunchAgent 以用户身份运行，始终在线。负责引用计数断言注册表、进程监视器（kqueue NOTE_EXIT + 定期扫描）、温度监控（SMC）、合盖状态监控（IORegistry）、合盖提示音以及 CLI 套接字。
• AdrafinilHelper：作为 LaunchDaemon 以 root 身份运行（通过 SMAppService 安装）。这是唯一接触睡眠阻止 API 的组件，仅持有 setSleepBlocked(Bool) 及只读状态/版本接口，并验证调用者的代码签名要求。
• adrafinil (CLI)：包含在 .app 中，链接到 PATH。连接守护进程套接字，往返时间 <50ms。

Agent 交互流程： Agent 不直接与 Adrafinil 通信，而是通过 Hook 系统调用捆绑的 CLI：

• 当回合开始时：adrafinil acquire <session-key> --tool claude-code --reason "long build"
• 当 Agent 空闲时：adrafinil release <session-key>

断言是基于活动范围（activity-scoped）而非会话范围（session-scoped）。例如，Claude Code 在 UserPromptSubmit 时获取，在 Stop 时释放。这意味着如果会话在提示符处保持打开但空闲，Mac 仍可正常睡眠。

此外，Agent 可以通过 adrafinil hold --for 30m --reason "deploy" 保持 Mac 唤醒以处理超出回复时间的后台任务（如长时间构建或部署），或通过 MCP（Model Context Protocol）工具进行交互。

系统要求与构建

• 操作系统：基于 macOS Tahoe 26.4 构建和测试（可能兼容早期 26.x 版本）。
• 开发环境：需要 Xcode 26+ 及启用严格并发模式的 Swift 6。
• 安装权限：标准安装需要管理员权限（用于注册特权辅助程序）。非管理员安装路径会将 CLI 放置在 ~/.local/bin 而非 /usr/local/bin。
• 代码签名：Xcode 项目中未硬编码 Team ID，XPC 调用者检查在运行时读取签名团队，因此任何 Developer ID 授权的重建均可自行授权其组件，无需更改代码。

关键要点

• 精准唤醒：Adrafinil 与 caffeinate 等“始终在线”工具相反，仅在 AI Agent 实际工作中介入，工作结束立即释放睡眠阻止。
• 合盖睡眠支持：解决了 macOS 在合盖状态下难以保持后台任务运行的痛点，特别适合夜间运行长耗时 AI 任务。
• 安全架构：通过分离特权（Helper）与非特权逻辑（Daemon），最小化攻击面。Helper 仅暴露单一写入端点，所有策略逻辑在 Daemon 中处理。
• 广泛的 Agent 兼容性：原生支持 Claude Code、Cursor、Codex 等 9 种主流 AI 编程工具，并通过 MCP 协议扩展兼容性。
• 智能安全机制：具备热切断功能，防止设备在合盖携带时过热；具备空闲释放机制，防止僵尸进程导致设备无法休眠。
• 高性能：CLI 命令往返时间低于 50ms，确保不干扰 Agent 的工作流。
• 用户友好：提供合盖提示音和开盖任务摘要，让用户清晰了解后台运行状态。

意义与影响

Adrafinil 的出现标志着 macOS 上 AI 辅助开发工作流的精细化演进。随着 AI 编程 Agent 越来越深入地融入开发者的日常流程，它们往往需要执行耗时较长的任务（如代码库索引、复杂重构、测试套件运行），这些任务通常在开发者下班或睡觉后继续执行。

传统的睡眠管理工具要么过于粗暴（始终唤醒，导致电池损耗和过热风险），要么功能不足（无法在合