| name | onezion-caffeinate |
| description | "一键控制 Mac 睡眠行为。防止合盖睡眠、保持屏幕常亮、阻止系统空闲。触发词：caffeinate、防睡眠、合盖不睡、保持唤醒、屏幕常亮、prevent sleep、keep awake、clamshell、合盖". |
onezion-caffeinate — Mac 睡眠控制
macOS 原生 caffeinate 命令的易用封装。无需安装任何东西。
常见场景速查
| 场景 | 命令 |
|---|
| 阻止系统睡眠（下载/渲染中） | caffeinate -i |
| 阻止屏幕熄灭 | caffeinate -d |
| 合盖不睡眠（需外接电源） | caffeinate -s |
| 完全不睡（屏幕+系统） | caffeinate -dims |
| 限制时间（如 2 小时） | caffeinate -dims -t 7200 |
| 后台长期运行 | caffeinate -dims & |
| 停止 | kill %1 或 killall caffeinate |
caffeinate 参数说明
| Flag | 作用 |
|---|
-d | 防止 display sleep（屏幕常亮） |
-i | 防止 system idle sleep（系统空闲不睡） |
-m | 防止 disk sleep（磁盘不停转） |
-s | 阻止系统休眠（包括合盖） |
-t N | 超时秒数，N 秒后自动恢复 |
& | 后台运行 |
使用流程
1. 判断用户需求
根据用户描述，选择合适的组合：
- "下载文件怕合盖中断" →
caffeinate -dims
- "合盖后继续跑任务" →
caffeinate -s 或 caffeinate -dims
- "屏幕一直亮着" →
caffeinate -d
- "跑个长任务别睡" →
caffeinate -i
- "跑 30 分钟别睡" →
caffeinate -dims -t 1800
⚠️ 强制规则：必须设置时限
每次调用 caffeinate 必须加上 -t 时间限制。 不允许无期限运行。
如果用户没有指定时长，必须使用 AskUserQuestion 询问：
{
"questions": [{
"question": "防睡眠要持续多久？",
"header": "时长",
"options": [
{"label": "15 分钟", "description": "适合快速下载/渲染"},
{"label": "30 分钟", "description": "适合中等任务"},
{"label": "1 小时", "description": "适合较长的任务"},
{"label": "2 小时", "description": "适合长任务"}
],
"multiSelect": false
}]
}
时间选择规则：
- 用户说具体时间 → 直接使用（如 "一个小时" →
-t 3600）
- 用户说模糊时间 → 问清楚（如 "一会儿" → 让用户选具体时长）
- 用户说"一直" → 告知重启后自动恢复，但仍建议设置时限
- 所有
-t 参数单位为秒
安全说明（告知用户）：
caffeinate -t N：N 秒后自动恢复睡眠，重启后也会自动恢复（因为 caffeinate 本身不持久化）- 无需用户手动取消，到期自动失效
- 如果系统重启， caffeinate 自然消失，恢复默认睡眠行为
2. 执行
caffeinate -dims -t <秒数>
caffeinate -dims -t <秒数>
caffeinate -dims -t <秒数> &
3. 停止 caffeinate
安全提示
caffeinate -s（合盖不睡）只在接电源时有效，电池模式下 macOS 会强制睡眠- 合盖运行注意散热，尤其放包里
- 任务完成后记得停止 caffeinate，否则一直不睡
- 建议配合
-t 设置超时，避免忘记
进阶：pmset 设置
电池模式合盖不睡
caffeinate 在电池模式下无法阻止合盖睡眠（macOS 硬限制）。如果需要电池模式也合盖不睡，必须用 pmset：
osascript -e 'do shell script "pmset -a disablesleep 1" with administrator privileges'
osascript -e 'do shell script "pmset -a disablesleep 0" with administrator privileges'
pmset -g
⚠️ 固定用 osascript GUI 弹窗获取管理员权限，不要直接用 sudo（命令行需要终端交互）。 除非用户明确要求，否则优先用临时的 caffeinate。
定时恢复（推荐 ⭐）—— 两步法
用户最常担心的：改了设置忘记改回来。
⚠️ 关键：必须拆成两步，不能合在一条 osascript 里。
osascript do shell script 会等待内部所有子进程结束才返回，即使加了 & 也不行。把 sleep 1800 放在 osascript 里面 = 卡死 30 分钟。
正确做法：分两步执行
第一步：立刻禁用睡眠（需要密码）
osascript -e 'do shell script "pmset -a disablesleep 1" with administrator privileges'
→ 弹窗填密码后立刻返回，不阻塞。
第二步：后台倒计时自动恢复（run_in_background）
(sleep <秒数> && osascript -e 'do shell script "pmset -a disablesleep 0" with administrator privileges') &
→ sleep 在 osascript 外面，普通 bash 后台进程，不锁任何东西。到期后弹窗要求密码恢复。
具体示例
| 时长 | 第一步（立即执行） | 第二步（后台） |
|---|
| 30 分钟 | osascript -e 'do shell script "pmset -a disablesleep 1" with administrator privileges' | (sleep 1800 && osascript -e 'do shell script "pmset -a disablesleep 0" with administrator privileges') & |
| 1 小时 | 同上 | (sleep 3600 && osascript -e 'do shell script "pmset -a disablesleep 0" with administrator privileges') & |
| 2 小时 | 同上 | (sleep 7200 && osascript -e 'do shell script "pmset -a disablesleep 0" with administrator privileges') & |
第二步必须用 run_in_background: true，否则 WorkBuddy 会等 sleep 结束。
工作原理：
- Step 1:
pmset -a disablesleep 1 → 立刻禁用睡眠，弹窗后秒返
- Step 2: bash 后台进程
sleep N → N 秒后触发 osascript 弹窗 → 填密码恢复
- Step 2 是独立 bash 进程，不依附于 osascript，即使 WorkBuddy 会话结束也会跑完
⚠️ 注意事项：
- 第一步弹窗填密码（系统级安全弹窗，密码不经过 WorkBuddy）
- 第二步到期后会再弹一次窗要求密码恢复——这是有意设计：作为提醒，不想恢复就点取消
- 电池模式合盖跑注意散热
- 如果系统重启，pmset 设置会保留，需手动恢复：
osascript -e 'do shell script "pmset -a disablesleep 0" with administrator privileges'
触发条件： 用户说"电池模式合盖不睡"、"插不插电都要合盖不睡"、"设了怕忘记改回来"、"自动恢复"时使用此方案。
常见问题
Q: 合盖后蓝牙鼠标/键盘断连？
A: M 系列芯片常见问题。用有线键鼠，或者在合盖前先把蓝牙设备连上再合盖。
Q: caffeinate -s 不起作用？
A: 检查是否接了电源。电池模式下 macOS 不允许合盖不睡。
Q: 怎么知道 caffeinate 在跑？
A: ps aux | grep caffeinate 查看。
