kageroumado/adrafinil 来源：https://github.com/kageroumado/adrafinil adrafinil (https://kagerou.glass) # adrafinil 处方编号 006 ・ ad·raf·i·nil /əˈdræfɪnɪl/ ・ 针对机器的清醒剂 ♡ kagerou.glass (https://kagerou.glass/adrafinil/) @kageroumado (https://x.com/kageroumado) macOS Tahoe 系统要求 清醒 ・ 某个代理正在工作 睡眠 ・ 无代理，正常睡眠 > 服用注意 ・ 用于在你入睡后仍值守的机器。 > > 凌晨3点。你已入睡。但代理没有——它仍然在你几小时前发起的会话中思考，你合上了盖子，就像一只无法完全闭合的眼睑。caffeinate 和 Amphetamine 是兴奋剂：它们让机器永远保持连线状态，无论是否有人在使用。Adrafinil 则不同，它是一种清醒剂。在代理获取它之前什么也不做，仅在需要工作时让你的 Mac 在合盖后保持唤醒，一旦最后一个会话释放便立即解除。它只为工作而醒——然后你们一起入眠。♡ — 让你的 Mac 仅在 AI 代理工作时保持唤醒。Adrafinil 是一个 macOS 菜单栏应用，它仅在 AI 编码代理拥有活跃会话期间阻止系统休眠——包括合盖（盒盖）休眠。当没有代理工作时，休眠行为不受影响：合上盖子，Mac 正常休眠。这与 caffeinate 或 Amphetamine 这类始终开启的唤醒工具相反。Adrafinil 只在代理（Claude Code、Codex、Cursor 等）处于任务中时介入，并在工作完成后立即退出。 > ⚠️ 特权休眠控制。 覆盖合盖休眠需要 root 权限。Adrafinil 将这一功能隔离在一个小巧且可审计的帮助进程中，该进程仅暴露 setSleepBlocked(Bool)——所有策略决策都位于一个非特权守护进程中。它使用标准的 IOPMAssertion 控制空闲休眠，并在验证设备上较新的私有 IOPMrootDomain 路径无法让无显示器的合盖 Mac 保持唤醒后，使用 pmset disablesleep 控制合盖休眠。详见 Docs/ARCHITECTURE.md §2。 ## 功能特性 - 感知代理，而非始终开启。 仅当至少一个代理会话持有断言时才阻止休眠。零个会话→正常休眠，包括合盖。 - 支持 9 种代理的 Hook 集成。 一键安装器可将 Adrafinil 接入 Claude Code、Codex、Cursor、Gemini CLI、Aider、Hermes、OpenCode、Cline 和 Pi 的 hook 系统。 - 亚 50ms CLI。 adrafinil acquire / release 由代理 hook 调用，往返守护进程的时间小于 50ms，因此不会延迟代理的工作流。 - 引用计数的断言。 重叠的会话会干净地堆叠；仅当最后一个会话释放时才会解除休眠。 - 温度切断。 如果合盖状态下外壳/CPU 温度超过阈值，所有断言将被强制释放，以防止包中的 Mac 过热。 - 空闲释放。 如果拥有断言进程已死亡或 CPU 空闲超过 N 分钟，断言会自动丢弃。 - 进程嗅探（可选）。 即使未安装 hook，守护进程在看到已知的代理二进制文件运行时也可自动获取断言。 - 合盖音频提示 + 开盖摘要。 合盖时（屏幕已关闭，因此无通知）会播放提示音以确认断言已持有；重新开盖时显示你离开期间运行的内容、峰值温度以及是否触发了温度切断。 - 干净卸载。 移除它在所有代理配置中添加的每个 hook 条目。 ## 系统要求 - macOS Tahoe 26.4。 这是我构建和测试的版本；可能在更早的 26.x 上也能运行，但我未在该环境中测试。 - Xcode 26+ 用于构建，需启用 Swift 6 严格并发。 - 标准安装需要管理员权限（特权帮助进程通过 SMAppService 安装）。非管理员安装路径会将 CLI 放入 ~/.local/bin 而非 /usr/local/bin。 ## 下载 下载 Adrafinil (https://github.com/kageroumado/adrafinil/releases/latest) —— 一个已签名并公证的磁盘映像。打开它，将 Adrafinil 拖入应用程序文件夹，然后启动。首次启动会请求一次管理员权限以注册特权帮助进程。需要 macOS 26.4 或更高版本。更倾向于自行构建？请参阅 构建。 ## 构建 sh git clone https://github.com/kageroumado/adrafinil.git cd adrafinil open Adrafinil.xcodeproj 在 Xcode 中，选择 Adrafinil scheme 并运行。你需要设置一个开发团队用于代码签名——守护进程（LaunchAgent）和帮助进程（LaunchDaemon）内嵌在应用 bundle 中，并在应用启动时向系统注册。（源码中未内嵌任何 Team ID；XPC 调用者检查在运行时读取你自己的签名团队，因此使用任何开发者 ID 重新构建后，其自身组件无需修改代码即可获得授权。） 如需无本地签名身份的无头编译检查： sh 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 包独立构建和测试： sh cd AdrafinilShared swift test ## 工作原理 代理不直接与 Adrafinil 通信。每个代理的 hook 系统调用捆绑的 CLI： sh adrafinil acquire --tool claude-code --reason "long build" # 当一轮交互开始时 adrafinil release # 当代理进入空闲状态 持有是活动范围而非会话范围：Claude Code 在 UserPromptSubmit 时获取，在 Stop 时释放，因此 Mac 仅在代理实际工作时保持唤醒——打开的但空闲的会话会让它正常休眠。守护进程按会话键进行引用计数，并在计数非零时请求帮助进程阻止休眠。代理还可以通过一个有时限的持有来让 Mac 保持唤醒以执行超出回复时长的后台任务（如长时间构建或部署）——可以直接调用 adrafinil hold，或者对于支持 MCP 的代理，通过捆绑的 MCP 工具（由 adrafinil mcp 提供）： sh adrafinil hold --for 30m --reason "deploy" # 最多保持唤醒 30 分钟，然后自动释放 adrafinil mcp # 通过 stdio 提供 Model Context Protocol（供代理使用） 其他子命令：status、install-hooks、uninstall-hooks、daemon-status、version。 ## 架构 四个产品，三个特权层级（完整细节，包括 Xcode 项目布局，请参阅 Docs/ARCHITECTURE.md）： ┌──────────────────────────────────────────────────────────────┐ │ Adrafinil.app（菜单栏应用，面向用户） │ │ • 状态项、设置、安装程序 GUI、开盖摘要 │ └─────────────────────────────┬────────────────────────────────┘ │ XPC ▼ ┌──────────────────────────────────────────────────────────────┐ │ AdrafinilDaemon（LaunchAgent，以用户身份运行，常驻） │ │ • 引用计数的断言注册表 │ │ • 进程监视器（kqueue NOTE_EXIT + 定期扫描） │ │ • 温度监控（SMC） • 盖子状态监控（IORegistry） │ │ • 合盖提示音 • CLI 套接字位于 .../Adrafinil/cli.sock │ └─────────────────────────────┬────────────────────────────────┘ │ XPC（特权 Mach 服务） ▼ ┌──────────────────────────────────────────────────────────────┐ │ AdrafinilHelper（SMAppService LaunchDaemon，root 权限） │ │ • 唯一接触休眠阻止 API 的组件 │ │ • setSleepBlocked(Bool) + 只读状态/版本 │ │ • 验证调用者的代码签名要求 │ └──────────────────────────────────────────────────────────────┘ adrafinil（CLI，内嵌于 .app 中，符号链接到 PATH） • acquire / release / hold / mcp / status / install-hooks / uninstall-hooks • 连接到守护进程套接字；往返时间 <50ms - AdrafinilShared —— 一个跨所有目标共享的 Swift 包：数据模型（AgentKind、Assertion）、IPC 线格式、AssertionRegistry、CallerVerifier、hook 安装规范以及 CLI 参数解析器。单元测试针对此包。 - 帮助进程保持极简，便于审计。 它不包含任何策略——引用计数、温度、空闲和盖子逻辑全部位于守护进程中。特权界面只有一个可变端点加上只读内省功能。 - 守护进程是真理之源。 应用是一个纯视图层；它可以自由退出和重新启动，而不影响已持有的断言。 ## 已知的怪异之处 - 公开的 IOPM 断言无法击败合盖休眠。 使用公开类型（以及 caffeinate）的 IOPMAssertionCreateWithName 无法让合盖的 Mac 保持唤醒。Adrafinil v1 使用 pmset disablesleep 1，这种做法的副作用是它也会禁用空闲休眠，并且必须在关机时清除，否则会泄漏——帮助进程在重新生成后，会在重新应用状态之前重置为 disablesleep 0。 - 守护进程处理程序在任意队列上运行。 XPC 和套接字回调可能在任何 dispatch 队列上到达，因此断言注册表和共享状态会相应地进行同步。修改守护进程时请小心处理并发。 - CLI 有延迟预算。 acquire/release 处于每个代理会话的热路径中，因此使用静态查找（例如 AgentKind.allBinaryNames）和轻量套接字协议，而非完整的 XPC 用于 CLI ↔ 守护进程的通信。 ## 许可 MIT。随心所欲，不提供担保。 ## 致谢 由 @kageroumado (https://x.com/kageroumado) 构建，在 kagerou.glass (https://kagerou.glass) 分发。名称灵感来源于 adrafinil (https://en.wikipedia.org/wiki/Adrafinil) —— 一种促进清醒的前体药物——因为该应用仅在机器实际有工作时才让其保持唤醒。