PowerToys Awake DSC 配置指南：用 Microsoft.PowerToys/AwakeSettings 实现声明式"保持唤醒"管理

2026-09-06 17:00:01作者：龚格成

本文以 PowerToys 官方 DSC（Desired State Configuration，期望状态配置）文档中 Awake 模块的参考页为核心，完整讲解 Microsoft.PowerToys/AwakeSettings DSC 资源的属性定义、九种可复制的配置示例与典型使用场景，并结合仓库源码说明每个配置项在 Awake 模块内部的真实映射关系与实现原理。读完本文，你将能够通过 dsc config set、winget configure 或 PowerToys.DSC.exe 三种入口，以声明式方式精确控制 Windows 的睡眠与显示行为，并能理解配置项落到 AwakeMode、SetThreadExecutionState 的底层链路。

一、模块概览：Awake 的 DSC 资源

PowerToys Awake 是一个防止计算机进入睡眠或关闭显示器的工具，适用于安装程序长时间运行、演示汇报、计划内维护等需要"临时覆盖电源设置但不永久修改"的场景。doc/dsc/modules/Awake.md 对该模块的定义是：

Manages configuration for the Awake utility, which keeps your computer awake without changing power settings.

与通过设置界面手动点击不同，DSC 模块把 Awake 的配置抽象为一个可声明、可验证、可审计的资源。该资源类型为 Microsoft.PowerToys/AwakeSettings，核心特性包括：

多种运行模式：支持无限期保持唤醒、定时时长、指定到期时间三种模式，且可随时关闭；
显示器独立控制：keepDisplayOn 允许"只防系统睡眠、允许显示器按电源设置关闭"；
三种配置入口（原文档示例覆盖）：
1. dsc config set --file <file>.dsc.yaml —— 使用 DSC v3 配置文件；
2. winget configure <file>.yaml —— 通过 WinGet 执行 DSC 文档（processor: dscv3）；
3. PowerToys.DSC.exe set/get/test/schema --resource 'settings' --module Awake —— PowerToys 自带的 DSC 命令行直接执行。

关于 DSC 资源体系的整体背景（资源注册方式、settings-resource 的通用结构），可参阅 DSC 总览与 Settings Resource。

二、可配置属性详解

Awake 模块支持的属性如下，参数说明以 doc/dsc/modules/Awake.md 为准。

keepDisplayOn

控制 Awake 激活期间显示器是否保持点亮。

类型：boolean
文档默认值：true
说明：为 true 时阻止显示器关闭；为 false 时仅阻止系统睡眠，显示器按电源设置正常关闭。

实现佐证：从源码结构看，AwakeProperties 构造函数将 KeepDisplayOn 初始化为 false。也就是说，代码层的出厂默认是"不强制点亮显示器"，DSC 文档中列出的 true 更接近"演示/前台场景下的推荐取值"。配置时请显式指定该属性，不要依赖默认值。

mode

指定 Awake 的运行模式，是决定整套配置语义的核心字段。

类型：integer
默认值：0
允许值：

值	模式	含义
`0`	Off	Awake 关闭（被动模式，恢复系统正常电源行为）
`1`	无限期保持唤醒	直到手动停止
`2`	定时保持唤醒	保持 `intervalHours` + `intervalMinutes` 指定的时长
`3`	到期自动关闭	保持到 `expirationDateTime` 指定的日期时间

实现佐证：这组数值与源码中的 AwakeStateMode 枚举完全一一对应：Passive = 0、Indefinite = 1、Timed = 2、Expirable = 3。DSC 写入的属性会经 AwakeService.CreateState 中的 switch 映射到 AwakeMode.PASSIVE/INDEFINITE/TIMED/EXPIRABLE，因此 mode 取值之外的数字会被归一化为 Passive。

intervalHours

定时模式（mode = 2）下保持唤醒的小时数。

类型：integer
范围：0 ~ 999
默认值：0

intervalMinutes

定时模式（mode = 2）下保持唤醒的分钟数。

类型：integer
范围：0 ~ 59
默认值：1（与源码 AwakeProperties 构造函数中 IntervalMinutes = 1 的初始化一致）

实现佐证：时长在内部是"小时 + 分钟"两字段的合成。AwakeService.CreateState 中 duration = TimeSpan.FromHours(IntervalHours) + TimeSpan.FromMinutes(IntervalMinutes)；而程序化的定时入口 SetTimedAsync 也按 minutes / 60 与 minutes % 60 拆分回填这两个字段，并校验分钟数必须大于零。因此 DSC 配置中 2 小时应写为 intervalHours: 2、intervalMinutes: 0。

expirationDateTime

到期自动关闭模式（mode = 3）下，Awake 自动失效的日期时间。

类型：string（ISO 8601 日期时间格式）
格式："YYYY-MM-DDTHH:mm:ss.fffffffzzz"（含 7 位小数秒与时区偏移）
示例："2025-12-31T23:59:59.0000000-08:00"

实现佐证：AwakeSettings.Clone 中含有一段兼容性处理——若已持久化的 ExpirationDateTime 年份小于 2（即 DateTimeOffset.MinValue 这类历史脏数据），克隆时会回退为 DateTimeOffset.Now，注释明确这是修复早期版本保存的缺陷默认值。使用 mode: 3 时务必提供带时区偏移的合法时间戳，避免落入该回退逻辑。

customTrayTimes

显示在系统托盘右键菜单中的自定义时间快捷项，便于快速激活。

类型：object
说明：一个字典，键为显示名称，值为时间规格。

实现佐证：其内部类型为 Dictionary<string, uint>，见 AwakeProperties。单元测试 SettingsResourceAwakeModuleTest 中的样例值为 { "08:00": 1, "12:00": 2, "16:00": 3 }，可用作该字典结构的书写参考。

三、九个可复制的配置示例

以下示例完整继承自 doc/dsc/modules/Awake.md，覆盖三种入口与 get/test/schema 等全部操作动词。

示例 1 —— 无限期保持唤醒且显示器常亮（直接执行）

$config = @{
    settings = @{
        properties = @{
            keepDisplayOn = $true
            mode = 1
        }
        name = "Awake"
        version = "0.0.1"
    }
} | ConvertTo-Json -Depth 10 -Compress

PowerToys.DSC.exe set --resource 'settings' --module Awake --input $config

示例 2 —— 保持唤醒 2 小时（dsc 命令）

dsc config set --file awake-timed.dsc.yaml

# awake-timed.dsc.yaml
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
resources:
  - name: Configure Awake for 2 hours
    type: Microsoft.PowerToys/AwakeSettings
    properties:
      settings:
        properties:
          keepDisplayOn: true
          mode: 2
          intervalHours: 2
          intervalMinutes: 0
        name: Awake
        version: 0.0.1

示例 3 —— 保持唤醒到指定时间（winget configure）

winget configure winget-awake-scheduled.yaml

# winget-awake-scheduled.yaml
$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json
metadata:
  winget:
    processor: dscv3
resources:
  - name: Install PowerToys
    type: Microsoft.WinGet.DSC/WinGetPackage
    properties:
      id: Microsoft.PowerToys
      source: winget

  - name: Keep awake until end of workday
    type: Microsoft.PowerToys/AwakeSettings
    properties:
      settings:
        properties:
          keepDisplayOn: true
          mode: 3
          expirationDateTime: "2025-10-18T17:00:00.0000000-07:00"
        name: Awake
        version: 0.0.1

示例 4 —— 关闭 Awake（直接执行）

$config = @{
    settings = @{
        properties = @{
            mode = 0
        }
        name = "Awake"
        version = "0.0.1"
    }
} | ConvertTo-Json -Depth 10 -Compress

PowerToys.DSC.exe set --resource 'settings' --module Awake --input $config

示例 5 —— 只防系统睡眠、允许显示器关闭

dsc config set --file awake-system-only.dsc.yaml

# awake-system-only.dsc.yaml
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
resources:
  - name: Keep system awake only
    type: Microsoft.PowerToys/AwakeSettings
    properties:
      settings:
        properties:
          keepDisplayOn: false
          mode: 1
        name: Awake
        version: 0.0.1

示例 6 —— 演示场景：保持 4 小时（winget configure）

winget configure presentation-mode.yaml

# presentation-mode.yaml
$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json
metadata:
  winget:
    processor: dscv3
resources:
  - name: Enable Awake for presentation
    type: Microsoft.PowerToys/AwakeSettings
    properties:
      settings:
        properties:
          keepDisplayOn: true
          mode: 2
          intervalHours: 4
          intervalMinutes: 0
        name: Awake
        version: 0.0.1

示例 7 —— 测试当前配置是否符合期望（test 动词）

$desired = @{
    settings = @{
        properties = @{
            keepDisplayOn = $true
            mode = 1
        }
        name = "Awake"
        version = "0.0.1"
    }
} | ConvertTo-Json -Depth 10 -Compress

$result = PowerToys.DSC.exe test --resource 'settings' --module Awake --input $desired | ConvertFrom-Json

if ($result._inDesiredState) {
    Write-Host "Awake is configured for indefinite keep-awake"
} else {
    Write-Host "Awake configuration differs from desired state"
}

test 动词返回的 _inDesiredState 布尔字段是判断"实际状态是否已达期望状态"的依据，适合放进 CI/巡检脚本做合规检查。

示例 8 —— 获取当前 Awake 配置（get 动词）

PowerToys.DSC.exe get --resource 'settings' --module Awake | ConvertFrom-Json | ConvertTo-Json -Depth 10

示例 9 —— 获取 Awake 属性 JSON Schema（schema 动词）

PowerToys.DSC.exe schema --resource 'settings' --module Awake | ConvertFrom-Json | ConvertTo-Json -Depth 10

schema 动词可直接产出该模块的机器可读约束（类型、范围、默认值），是编写自动化配置前的可靠"参数字典"。上述命令动词在 PowerToys.DSC 命令行实现中一一对应（SetCommand.cs、GetCommand.cs、TestCommand.cs、SchemaCommand.cs），其中 --resource 'settings' 对应 SettingsResource。

四、典型使用场景（Use Cases）

原文档给出三类生产场景，均使用纯 resources 片段（可并入任意 DSC v3 文档的 resources 节点）：

开发构建：长时间编译/安装期间保持系统清醒

屏幕关闭可接受，关键是阻止睡眠：

resources:
  - name: Keep awake during build
    type: Microsoft.PowerToys/AwakeSettings
    properties:
      settings:
        properties:
          mode: 2
          intervalHours: 8
          intervalMinutes: 0
          keepDisplayOn: false
        name: Awake
        version: 0.0.1

演示与汇报：系统 + 显示器双保持

resources:
  - name: Presentation mode
    type: Microsoft.PowerToys/AwakeSettings
    properties:
      settings:
        properties:
          mode: 1
          keepDisplayOn: true
        name: Awake
        version: 0.0.1

计划维护窗口：到点自动失效

resources:
  - name: Maintenance window
    type: Microsoft.PowerToys/AwakeSettings
    properties:
      settings:
        properties:
          mode: 3
          expirationDateTime: "2025-10-19T02:00:00.0000000-07:00"
          keepDisplayOn: false
        name: Awake
        version: 0.0.1

五、底层机制：配置如何变成"防睡眠"信号

理解配置项的实际作用边界，需要看到 Awake 的运行时实现（详见 src/modules/awake/README.md）：

Win32 执行状态标志：Awake 通过 SetThreadExecutionState() 向系统声明唤醒意图，涉及三个标志：
- ES_SYSTEM_REQUIRED —— 阻止系统睡眠（对应 mode != 0 的基础行为）；
- ES_DISPLAY_REQUIRED —— 阻止显示器关闭（对应 keepDisplayOn: true）;
- ES_CONTINUOUS —— 状态持续生效，直到显式变更（这正是 mode: 0 关闭 Awake 后行为恢复正常的机制）。
配置文件的读写位置：Awake 以 PowerToys 集成模式（--use-pt-config）运行时，设置持久化在 %LOCALAPPDATA%\Microsoft\PowerToys\Awake\settings.json。DSC 的 set 动词本质上就是改写该文件（经 AwakeService.UpdateSettingsAsync 读取-修改-保存），而 Awake 主进程通过文件监听感知变更，模块 README 指出文件观察使用了 25ms 节流以去抖快速变更。
状态模型：模块对外暴露的 AwakeState 记录结构为 (IsRunning, Mode, KeepDisplayOn, Duration?, Expiration?)，与 DSC 属性集一一对应——Duration 仅在 Timed 模式下有值，Expiration 仅在 Expirable 模式下有值，这解释了为何 DSC 属性中 intervalHours/intervalMinutes 只对 mode: 2 有意义、expirationDateTime 只对 mode: 3 有意义。
注意事项（Task Scheduler 空闲检测）：模块 README 明确指出，当 keepDisplayOn 为 true 时使用的 ES_DISPLAY_REQUIRED 标志会阻止 Windows 任务计划程序把系统判定为空闲，从而可能延迟 TRIM、磁盘整理等空闲触发的维护任务。若你的机器依赖计划任务做定期维护，优先选择 keepDisplayOn: false（此时仅 ES_SYSTEM_REQUIRED 生效，不影响空闲检测），这正是示例 5 与"开发构建"场景默认 keepDisplayOn: false 的原因。

六、测试与验证

Awake 的 DSC 资源行为由专用单元测试覆盖：SettingsResourceAwakeModuleTest 继承自泛型基类 SettingsResourceModuleTest<AwakeSettings>，其 GetSettingsModifier 会同时变更 Mode（PASSIVE 与 TIMED 互切）、KeepDisplayOn 取反、IntervalHours/IntervalMinutes 加一、并写入三项 CustomTrayTimes（"08:00"/"12:00"/"16:00"），用于验证 get/set/test 三个动词对全部属性的往返一致性。若你基于本文编写自己的 DSC 配置，用示例 7 的 test 流程即可对等验证。

七、参考与延伸阅读

DSC 模块参考文档（本文主体）：doc/dsc/modules/Awake.md
Settings 资源通用说明：doc/dsc/settings-resource.md
PowerToys DSC 总览：doc/dsc/overview.md
其他 DSC 模块参考（同目录结构）：doc/dsc/modules/PowerRename.md
Awake 模块源码说明（模式表、CLI 参数、构建方式、已知限制）：src/modules/awake/README.md
服务层实现（状态映射与配置更新）：src/modules/awake/Awake.ModuleServices/AwakeService.cs
属性模型：src/settings-ui/Settings.UI.Library/AwakeSettings.cs、src/settings-ui/Settings.UI.Library/AwakeProperties.cs

适用前提：以上 DSC 配置方式要求系统已安装带 DSC 资源的 PowerToys 版本，PowerToys.DSC.exe 直接执行方式要求 PowerToys 正在运行且 Awake 模块已启用；dsc config set 与 winget configure 方式则依赖系统侧的 DSC v3 工具链与 WinGet。配置写入的是 PowerToys 的模块设置文件，不会修改 Windows 全局电源方案。

PowerToys

Microsoft PowerToys is a collection of utilities that supercharge productivity and customization on Windows

项目地址：https://gitcode.com/GitHub_Trending/po/PowerToys

登录后查看全文