PowerSwitch (电源快切)

Windows 本地电源与锁屏快速切换工具
一键切换“Agent 后台”、“Agent 亮屏”、“恢复日常”与“离开并锁定”，租约管理，零残留可靠恢复。

English | 中文说明

---

1. 用户痛点与第一性原则

在使用 Antigravity、Claude Code、Codex、长耗时训练、数据分析或大文件下载时，Windows 默认的节能休眠策略经常会中断正在运行的任务。而每次手动进入 Windows 控制面板分别修改熄屏与睡眠不仅层级繁琐，而且任务结束后极易忘记切回，造成电力浪费与屏幕老化。

PowerSwitch 把繁琐的系统设置压缩为一次点击：

• 手动意图优先：不随意猜测进程，用户点击即代表确定意图；
• 场景优先于参数：提供场景化卡片，无需反复设置多个下拉框；
• 临时状态租约机制：通过复制独立临时方案生效，从不直接修改污染用户现有方案；
• 真实验证：所有应用状态均基于重新读取 Windows 实际生效值验证；
• 三重恢复兜底：正常到期、Watchdog 崩溃守护、RunOnce 重启自愈三重恢复保障。

---

2. 四大核心场景动作

1. 🌙 Agent 后台模式：
   • 阻止系统休眠，允许显示器按设定（如 5 分钟）熄灭；
   • 适用于 Agent 长任务、模型训练、后台批处理、大型编译或离线下载。
2. ☀️ Agent 亮屏模式：
   • 阻止系统休眠，同时保持屏幕长亮；
   • 到期时自动采用两级缓冲：先降级为后台模式 30 分钟并提示，无操作后再恢复日常，防止任务猝死。
3. 🔄 恢复日常：
   • 一键切回开启临时模式前的原电源方案，并自动销毁临时方案。
4. 🔒 离开并锁定：
   • 先自动恢复日常电源方案并验证，随后立即调用 Windows LockWorkStation 锁定电脑。

---

3. 运行与安装

便携运行 (绿色无依赖)

1. 下载发布产物 PowerSwitch-win-x64.zip 并解压；
2. 双击 PowerSwitch.exe 即可启动，程序内置图标与单文件运行时，无需预装额外环境。

桌面快捷方式安装

在主窗口点击“📌 桌面快捷”或在终端运行：

PowerSwitch.exe install-shortcuts

即在桌面生成 5 个一键快捷方式：

• 电源快切 (打开主界面)
• Agent 后台 4 小时
• Agent 亮屏 4 小时
• 恢复日常设置
• 离开并锁定

---

4. 命令行 CLI 指南

PowerSwitch 完全支持自动化脚本调用与单实例转发：

# 打开或激活主窗口
PowerSwitch.exe show

# 应用指定模式与持续时间
PowerSwitch.exe apply agent-background --for 4h
PowerSwitch.exe apply agent-background --for 30m
PowerSwitch.exe apply agent-display --for 2h
PowerSwitch.exe apply agent-display --until-manual
PowerSwitch.exe apply agent-display --for 4h --include-battery

# 恢复日常电源设置
PowerSwitch.exe restore

# 恢复日常并锁定工作站
PowerSwitch.exe lock --restore-first

# 查询当前状态 (支持 JSON 输出，适合第三方工具集成)
PowerSwitch.exe status
PowerSwitch.exe status --json

# 诊断与异常恢复
PowerSwitch.exe diagnose
PowerSwitch.exe recover

JSON 状态输出示例

{
  "active": true,
  "mode": "agent-background",
  "sessionId": "a1b2c3d4e5f6...",
  "originalSchemeId": "381b4222-f694-41f0-9685-ff5bb260df2e",
  "temporarySchemeId": "5d83f8e1-dd39-4006-8f61-8f238d046806",
  "powerSource": "ac",
  "includeBattery": false,
  "startedAtUtc": "2026-09-04T07:00:00.0000000+00:00",
  "expiresAtUtc": "2026-09-04T11:00:00.0000000+00:00",
  "remainingSeconds": 14399,
  "displayTimeoutAcSeconds": 300,
  "sleepTimeoutAcSeconds": 0,
  "lockedDisplayTimeoutAcSeconds": 60,
  "verified": true
}

---

5. 供电策略：AC 与电池

• 默认策略：临时模式默认仅作用于交流电供电 (AC)。
• 当笔记本拔下电源插头切换为电池供电时，临时模式保持原电池策略，并弹出系统通知提示耗电，避免电量无限放空。
• 如确需在电池供电下保持运行，可在主界面勾选“同时应用到电池”或附加 --include-battery。

---

6. 恢复保障与安全

• 非管理员运行：默认无需管理员权限；
• 零注入、零模拟：绝不注入虚拟鼠标键盘按键，不干扰打字与正常工作；
• 保护用户选择：若在临时模式期间用户手动在系统设置中切换了其他方案，恢复时自动尊重用户当前选择；
• 隐私承诺：绝不联网、绝无任何遥测、绝不读取任何进程或聊天内容；
• 已知限制：保持系统不休眠无法阻止网络物理断开、云端服务波动或用户主动物理关机。

---

7. 文档索引

• 架构设计文档
• Windows 电源行为深度解析
• 恢复机制与异常处理指南
• 测试与验证指南
• 故障排查

---

8. 开源协议

本项目基于 MIT 协议 开源。