让屏幕在该亮的时候
保持清醒

01概览

两个版本的核心理念相同：只在真正播放媒体时保持屏幕常亮，没有播放时完全交还系统电源管理；不联网、无账号、无遥测。

跳转：Mac 版说明 · Windows 版说明

M1功能

M2安装

把 App 放进“应用程序”文件夹并打开即可。第一次打开时，菜单栏会出现一个显示器图标。

1. 双击 DMG，把 ScreenStay 拖入 Applications。
2. 打开 ScreenStay，允许它出现在菜单栏。
3. 需要开机启动时，右键图标并勾选“开机自启”。

如果 Gatekeeper 拦截，请在“系统设置 → 隐私与安全性”中选择“仍要打开”，或执行 xattr -dr com.apple.quarantine /Applications/ScreenStay.app。

M3使用

开启保护且媒体正在播放时，图标右侧会出现绿点；关闭开关后图标变暗，不再干预屏幕休眠。

M4检测原理

严格模式使用两层只读查询，避免只凭播放速率或静音音频流误判：

1. 系统 Perl 辅助器：通过 /usr/bin/perl 加载内置的极小 dylib，调用 MRMediaRemoteGetNowPlayingApplicationIsPlaying，取得真实的播放/暂停状态。
2. JXA 辅助脚本：通过 MRNowPlayingRequest 读取应用名、标题、PID 和 Bundle ID，用于菜单展示。
3. 电源断言：确认播放后创建 PreventUserIdleDisplaySleep 和 PreventUserIdleSystemSleep。
4. 回退检测：Perl 不可用时，使用 PlaybackRate、播放器进程音频输出和 isCurrentlyPlaying 组合判断。

M5诊断

App 内置命令行诊断，不需要打开菜单：

# 观察 10 秒检测状态与电源断言
/Applications/ScreenStay.app/Contents/MacOS/ScreenStay --diagnose 10

# 查看当前影响熄屏的其他应用
/Applications/ScreenStay.app/Contents/MacOS/ScreenStay --blockers

# 查看系统 Now Playing 状态
/Applications/ScreenStay.app/Contents/MacOS/ScreenStay --nowplaying

# 查看 / 开启 / 关闭登录项
/Applications/ScreenStay.app/Contents/MacOS/ScreenStay --login-status
/Applications/ScreenStay.app/Contents/MacOS/ScreenStay --enable-login
/Applications/ScreenStay.app/Contents/MacOS/ScreenStay --disable-login

播放音乐时，--nowplaying 应显示 perlIsPlaying=true；暂停后变为 false，同时电源断言释放。

M6隐私与权限

• 不联网、不上传播放记录或设备信息。
• 不需要辅助功能、屏幕录制或麦克风权限。
• 只读访问 macOS 的播放状态与进程音频状态。
• 菜单栏中的“影响熄屏的应用”只在本机读取电源断言。
• 偏好设置保存在本机 UserDefaults 中。

M7从源码构建

需要 macOS 13+ 与 Command Line Tools：

cd ScreenStay
./build.sh
open ScreenStay.app

构建脚本会编译 arm64 与 x86_64、合并通用二进制、打包内置 Perl 辅助器，并在临时目录完成 ad-hoc 签名。

重新生成安装包：

./package.sh

M8卸载

1. 右键菜单栏图标，取消“开机自启”。
2. 选择“退出 ScreenStay”。
3. 删除 /Applications/ScreenStay.app。
4. 可选：执行 defaults delete com.zzerfu.ScreenStay 清理偏好设置。

W1功能

W2安装与卸载

1. 安装版（推荐）：双击 ScreenStay-Setup-1.5.3.exe，按向导安装（默认 %LOCALAPPDATA%\Programs\ScreenStay）；可选创建桌面快捷方式、开机自动启动、安装后启动。
2. 便携版：解压 ScreenStay-v1.5.3.zip，直接运行 ScreenStay.exe。依赖 Windows 10/11 自带的 .NET Framework 4.x，无需安装 .NET SDK。
3. 卸载：在「设置 → 应用 → 已安装的应用」（或控制面板「程序和功能」）中卸载；安装目录和便携包内的 Uninstall.exe 也可以卸载。

安装包未签名；如果 Windows SmartScreen 提示，请选择「更多信息 → 仍要运行」。

手动彻底清理：主界面「常规」关闭开机自启 → 托盘右键「退出」→ 删除程序文件夹；如需清除配置，删除注册表 HKEY_CURRENT_USER\Software\ScreenStay。

W3托盘操作

启动后程序出现在右下角托盘区，默认智能模式已开启。

托盘图标被折叠时，点击任务栏右下角的「^」展开，把 ScreenStay 图标拖到任务栏上固定。

W4主界面（WinUI 3）

主界面与托盘菜单双向同步，修改后主程序约 3 秒内应用；主界面只允许一个窗口，大小会按 DPI 与屏幕自动适配。

W5智能模式与实现原理

判定依据是 Windows 音频会话（与音量合成器中显示的应用相同）：默认音频设备上存在 Active 会话即视为正在播放。浏览器（YouTube / B 站 / 网易云 / QQ 音乐）、VLC、PotPlayer、Windows Media Player、Spotify 等都能识别。

// 检测到音视频播放：阻止屏幕关闭 + 系统空闲睡眠
SetThreadExecutionState(ES_CONTINUOUS | ES_SYSTEM_REQUIRED | ES_DISPLAY_REQUIRED);

// 没有播放（或关闭 / 退出）：撤销请求，交还电源管理
SetThreadExecutionState(ES_CONTINUOUS);

• 媒体检测：WASAPI IAudioSessionManager2 枚举会话，读取 IAudioSessionControl::GetState。
• 持续播放时每 3 秒重新申请一次，停止播放 10 秒后释放。
• 检测到播放时广播 WM_SYSCOMMAND / SC_MONITORPOWER，点亮已关闭的屏幕。
• 限制：使用 ASIO 或独占直通、不经过 Windows 音频引擎的极少数播放器可能检测不到。

W6开机自启与弹窗提醒

• 开机自启写入 HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Run → 值名 ScreenStay，内容 "exe完整路径" --startup，无需管理员。
• 建议先把程序放到固定位置（如 %LOCALAPPDATA%\Programs\ScreenStay\）再开启；移动 exe 后需在「常规」页重新开关一次。
• 「关闭 Windows 弹窗提醒」后不再显示启动、开关、自启等气泡通知；设置保存在 HKEY_CURRENT_USER\Software\ScreenStay\Notifications。

W7查看阻止休眠的程序

主界面「阻止休眠的程序」→「获取电源请求（需要管理员权限）」，确认 UAC 后分两类显示：

• 屏幕显示（阻止屏幕关闭）：例如正在播放视频的浏览器、全屏游戏；
• 系统睡眠（阻止系统睡眠）：例如下载工具、会议软件、后台服务。

默认只显示程序名（如 chrome.exe）；点「显示详细信息」查看原始 powercfg /requests 输出，「复制到剪贴板」会复制摘要与原始输出。Windows 只允许管理员读取电源请求，所以每次都会弹出 UAC；点「否」只取消本次查看。

W8自动切换日间 / 夜间主题

• 修改后自动保存，开启后约 10–15 秒生效；同时切换应用主题与系统主题（任务栏 / 开始菜单）。
• 日出日落采用 NOAA 简化算法，精度约 1–2 分钟；极昼 / 极夜或坐标无效时回退固定时间。
• 只在切换点切换一次，手动改过的主题会保持到下一个切换点；目前不切换壁纸。
• 与 Auto Dark Mode / PowerToys Light Switch 同时运行会互相覆盖，请只保留一个。
• 自动定位需在「设置 → 隐私和安全性 → 位置」中允许桌面应用访问位置。

W9常见问题与注意

• 停止播放后为什么过几秒才恢复？ 保留 10 秒缓冲，避免切歌、缓冲时反复申请 / 释放。
• 屏幕保护程序仍会触发？ 本工具阻止的是系统空闲熄屏 / 睡眠，屏保仍可能按用户空闲触发，可在「设置 → 个性化 → 锁屏界面 → 屏幕保护程序」设为「无」。
• 手动关显示器、合盖、Win+L 仍按系统策略执行。
• 托盘看不到图标？ 点「^」展开，或在任务管理器里确认 ScreenStay.exe 进程。
• 32 / 64 位？ AnyCPU 编译，64 位系统上以 64 位运行。
• 杀毒软件误报？ 程序没有数字签名，可选择「仍要运行」/ 加入信任；源码在 src/ScreenStay.cs。

W10自检与从源码编译

# 自检（退出码 0 = 全部通过）
ScreenStay.exe --selftest 报告.txt

# 编译主程序（只需系统自带 .NET Framework 4.x 的 csc.exe），或双击 build.cmd
powershell -NoProfile -ExecutionPolicy Bypass -File .\build.ps1

# 编译 WinUI 3 主界面（需要 .NET 8 SDK），或双击 viewer\build-viewer.cmd
powershell -NoProfile -ExecutionPolicy Bypass -File .\viewer\build-viewer.ps1

主界面产物输出到 viewer-dist\（约 37 MB），复制为安装目录下的 ScreenStay.Viewer\ 即可。

W11兼容性

• 主程序：Windows 7 / 8 / 8.1 / 10 / 11（x64 / ARM64），需系统自带 .NET Framework 4.x。
• WinUI 3 主界面：Windows 10 1809+ / Windows 11（x64），需要 Windows App Runtime 2.6.5。
• 自动主题依赖 Windows 10 / 11 个性化设置；跟随夜间模式依赖未公开的 CloudStore 数据结构，失败时回退自定义时间。

02相关链接