文章摘要
Adrafinil是一款macOS菜单栏工具，专为解决AI代理后台运行时系统睡眠问题设计。它按需唤醒，仅在AI代理有任务时阻止睡眠，任务完成即恢复默认。具备智能感知、多代理集成等功能，支持快速安装和自行编译，采用MIT开源协议。

Adrafinil是一款轻量化的macOS菜单栏工具，专为解决AI代理后台运行时的系统睡眠问题设计。不同于传统的持续唤醒工具，它只会在有实际工作任务时保持设备唤醒状态，完全遵循系统默认的睡眠策略，真正做到按需唤醒。

使用场景说明

当你在凌晨三点合上Mac盖子，却还有AI编码代理在后台运行未完成的任务时，传统的唤醒工具会让设备始终保持通电状态，无论是否有人使用。Adrafinil则会默默守护你的工作进程：它不会主动触发任何操作，直到被AI代理调用，仅在任务运行期间保持合盖状态下的唤醒，当最后一个会话结束时自动解除阻止，实现“为工作而醒，工作完成即安眠”的智能控制。

这款工具与caffeinate、Amphetamine等传统持续唤醒工具的核心区别在于：它仅在AI编码代理处于活跃任务中时阻止系统睡眠，任务完成后立即恢复默认睡眠行为，不会无谓地消耗设备电量。

⚠️ 权限说明

覆盖合盖睡眠模式需要root权限，Adrafinil将这部分权限隔离在一个经过审核的小型助手工具中，仅暴露setSleepBlocked(Bool)接口，所有策略逻辑都运行在无特权的守护进程中。它通过标准的IOPMAssertion处理常规空闲睡眠阻止，使用pmset disablesleep处理合盖睡眠，并在设备上验证了私有IOPMrootDomain路径的有效性，避免无屏幕的合盖设备出现异常唤醒。

核心功能特性

  • 智能感知工作状态：仅当至少有一个AI代理会话持有唤醒请求时才阻止系统睡眠，没有任务时完全遵循默认睡眠策略，合上盖子即可正常休眠。
  • 多代理一键集成：通过一键安装脚本，可以快速将Adrafinil接入9款主流AI编码工具的钩子系统，包括Claude Code、Codex、Cursor、Gemini CLI、Aider、Hermes、OpenCode、Cline和Pi。
  • 超低延迟命令行接口：代理钩子调用的acquire和release命令往返守护进程的时间低于50毫秒，不会拖慢代理的工作流程。
  • 引用计数式唤醒管理：多个重叠的会话可以整洁地堆叠管理，只有当最后一个会话释放请求时，才会解除睡眠阻止。
  • 过热保护机制：当合上盖子时，如果机身或CPU温度超过阈值，所有唤醒请求都会被强制释放，避免Mac在包中过热损坏。
  • 空闲自动释放：如果持有唤醒请求的进程已经终止，或者连续N分钟处于CPU空闲状态，系统会自动解除睡眠阻止。
  • 可选进程自动检测：守护进程可以自动识别已安装的AI代理二进制文件，即使没有安装钩子，也能自动触发唤醒控制。
  • 合盖音效与开盖总结：合上盖子时会播放提示音，此时屏幕已关闭无法收到普通通知，重新开盖后会显示这段时间内的运行情况、峰值温度以及是否触发了过热保护。
  • 干净卸载机制：会自动移除所有代理配置中添加的钩子条目，不会留下残留文件。

运行与开发要求

  • 系统支持：仅支持macOS Tahoe 26.4及以上版本，官方构建和测试基于该版本，理论兼容早期的26.x版本但未经过测试。
  • 开发环境：如需自行编译，需要Xcode 26及以上版本，并启用Swift 6严格并发模式。
  • 安装权限：标准安装需要管理员权限，特权助手将通过SMAppService安装；非管理员安装则会将CLI安装到~/.local/bin目录而非/usr/local/bin。

快速安装

你可以从开源项目的最新发布页面下载已签名并公证的磁盘镜像，打开后将Adrafinil拖入应用文件夹即可运行。首次启动时会请求一次管理员权限以注册特权助手，后续使用无需重复授权。如果希望自行编译项目，可以参考下方的构建指南。

自行编译

你可以通过以下命令克隆项目并打开Xcode项目：

git clone https://相关开源仓库地址/adrafinil.git
cd adrafinil
open Adrafinil.xcodeproj

在Xcode中选择Adrafinil方案并运行，你需要设置一个开发团队用于代码签名——守护进程和助手工具会嵌入应用包中，并在应用启动时自动注册到系统中。项目源码中没有内置团队ID，XPC调用检查会在运行时读取你自己的签名团队信息，因此任何开发者ID下的重建都可以自动授权自身组件，无需修改代码。

如果需要在没有本地签名身份的情况下进行无界面编译检查，可以使用以下命令：

xcodebuild -project Adrafinil.xcodeproj -scheme Adrafinil -configuration Debug \
  -destination 'generic/platform=macOS' \
  CODE_SIGNING_ALLOWED=NO CODE_SIGNING_REQUIRED=NO CODE_SIGN_IDENTITY='' build

项目的共享逻辑可以作为Swift包独立构建和测试：

cd AdrafinilShared
swift test

工作原理

AI代理并不会直接与Adrafinil通信，而是通过各自的钩子系统调用内置的CLI工具：

adrafinil acquire <session-key> --tool claude-code --reason "long build"   # 任务启动时调用
adrafinil release <session-key>                                            # 代理空闲时调用

唤醒请求是活动范围限定而非会话范围限定：以Claude Code为例，它会在提交用户提示时获取唤醒请求，在任务停止时释放，因此Mac仅在代理实际工作时保持唤醒——如果会话处于打开但空闲的状态，系统会正常进入睡眠。

守护进程会通过会话键进行引用计数，并在计数大于0时请求助手工具阻止系统睡眠。

AI代理还可以通过带时限的hold命令，为超出回复周期的后台任务保持设备唤醒：既可以直接调用adrafinil hold，对于支持MCP的代理，也可以通过adrafinil mcp提供的内置MCP工具来实现：

adrafinil hold --for 30m --reason "deploy"   # 保持唤醒最多30分钟，之后自动释放
adrafinil mcp                                 # 在标准输出上实现模型上下文协议

其他可用的子命令包括：status、install-hooks、uninstall-hooks、daemon-status和version。

架构设计

项目包含四个产品模块，分为三个权限层级：

┌──────────────────────────────────────────────────────────────┐
│  Adrafinil.app   (菜单栏应用，面向用户)                     │
│  • 状态图标、设置、安装界面、开盖总结面板                    │
└─────────────────────────────┬────────────────────────────────┘
                              │ XPC 通信
                              ▼
┌──────────────────────────────────────────────────────────────┐
│  AdrafinilDaemon  (用户级LaunchAgent，常驻运行)             │
│  • 引用计数式唤醒请求注册表                                │
│  • 进程监视器（kqueue NOTE_EXIT + 定期扫描）                │
│  • 温度监视器（SMC）  • 合盖状态监视器（IORegistry）       │
│  • 合盖提示音  • CLI套接字位于…/Adrafinil/cli.sock           │
└─────────────────────────────┬────────────────────────────────┘
                              │ XPC（特权Mach服务）
                              ▼
┌──────────────────────────────────────────────────────────────┐
│  AdrafinilHelper  (root权限LaunchDaemon，SMAppService)        │
│  • 唯一接触睡眠阻止API的组件                                │
│  • setSleepBlocked(Bool) + 只读状态/版本查询                │
│  • 验证调用者的代码签名要求                                  │
└──────────────────────────────────────────────────────────────┘

adrafinil  (CLI工具，内置在.app中，可链接到PATH)

• acquire / release / hold / mcp / status / install-hooks / uninstall-hooks

• 连接到守护进程套接字；往返时间低于50ms

  • AdrafinilShared：跨所有目标共享的Swift包，包含数据模型、IPC通信格式、唤醒请求注册表、调用验证器、钩子安装规范和CLI参数解析器，单元测试也都位于此模块中。
  • 助手工具极简可审计：不包含任何策略逻辑，引用计数、温度保护、空闲释放和合盖逻辑都运行在守护进程中，特权接口仅包含一个可修改的端点和只读自省功能。
  • 守护进程为唯一可信源：菜单栏应用仅作为视图层，可以随时退出或重启，不会影响已持有的唤醒请求。

使用注意事项

  • 公共IOPM断言无法阻止合盖睡眠：使用公共类型的断言创建接口无法让合盖状态下的Mac保持唤醒。Adrafinil的首个版本使用pmset disablesleep 1，该命令会同时禁用空闲睡眠，且必须在关机时清除否则会出现残留，助手工具会在重启时先重置为默认状态，再重新应用当前配置。
  • 守护进程处理程序运行在任意队列：XPC和套接字回调可能在任意调度队列上到达，因此唤醒请求注册表和共享状态都需要进行同步处理，修改守护进程代码时需要谨慎处理并发问题。
  • CLI工具严格控制延迟：acquire/release命令位于每个代理会话的关键路径上，因此使用了静态查找和轻量级套接字协议而非完整的XPC来实现CLI与守护进程的通信，以降低延迟。

开源协议

本项目采用MIT开源协议，你可以自由使用、修改和分发，本软件不提供任何形式的担保。

项目说明

本项目由开源社区开发者构建，项目名称源自一款促醒药物，寓意仅当设备有未完成的工作时才保持唤醒状态。

塔猴是一个专注于为用户提供系统学习、内容创作与商业连接的AIGC综合服务平台，致力于为每一位AI探索者打造理想的创作、成长家园。在塔猴，你不仅可以学习众多AIGC类实战课程，获得与时俱进的AIGC技能和视野，还有机会获得长期商业合作和接单机会！点击进入：https://www.tahou.com/

AI生成内容提示：本文由人工智能辅助创作，内容仅供参考，不代表平台观点。请注意核实信息的准确性，并理性判断。

以上内容不代表本平台立场，仅供读者参考