PowerToys CLI 规范详解：从 PATH 可见的 Shim 命令到 System.CommandLine 参数解析

本文基于 PowerToys 仓库中的 CLI 开发规范文档，系统讲解 PowerToys 各模块命令行界面（CLI）的实现约定：如何让用户在任意终端直接输入 PowerToys.ImageResizer.CLI 这类命令、shim（垫片）程序如何解析目标并转发参数、参数解析库 System.CommandLine 的用法与命名约定、退出码与日志规范，以及新增一条 CLI 命令的完整步骤与构建期防漂移校验机制。读完本文，你可以在 PowerToys 中新增一个符合仓库规范、可被 PATH 直接调用的 CLI 模块，并理解其安装与部署细节。

PATH 可见的命令命名与安装位置

PowerToys 对模块 CLI 命令的命名和安装位置有统一约定：

• 模块 CLI 命令垫片统一命名为 PowerToys.<ModuleName>.CLI.exe，例如 PowerToys.ImageResizer.CLI.exe；
• 这些垫片安装在 PowerToys 安装目录下的 bin 子文件夹中，安装器会把这个目录加入 PATH，因此用户在任意终端输入命令名即可调用。

关键在于：每一个命令实际上都是同一个 PowerToys.CliShim.exe 载荷（位于 tools/CliShim/）以不同文件名安装。shim 通过自身的文件名解析出要启动哪条 CLI，把原始参数尾部原样转发，共享调用方的控制台，并返回目标 CLI 的退出码。CLI 运行在由 shim 持有的作业对象（job object）中，因此杀掉 shim 会连带杀掉 CLI；而 CLI 自身启动的子进程（例如设置窗口）会脱离作业存活下来。

当前仓库中已注册的 shim 命令定义在 tools/CliShim/CliShimManifest.props，它是"运行时映射与已安装命令名的单一事实来源"，现有四条映射：

命令名（安装后的文件名）	RelativeTarget（相对安装后的 bin 目录）
PowerToys.FancyZones.CLI	../FancyZonesCLI.exe
PowerToys.ImageResizer.CLI	../WinUI3Apps/PowerToys.ImageResizerCLI.exe
PowerToys.FileLocksmith.CLI	../FileLocksmithCLI.exe
PowerToys.PowerDisplay.CLI	../WinUI3Apps/PowerToys.PowerDisplay.Cli.exe

注意 RelativeTarget 是相对安装后的布局（CLI 最终落盘位置）解析的，而不是相对源码树或构建输出位置；路径分隔符必须使用 /。

bin 目录的受保护 DACL

对于按机器（per-machine）安装，bin 文件夹会带有受保护的 DACL——即 installer/PowerToysSetupVNext/Common.wxi 中定义的 MachinePathFolderSddl（SDDL 字符串为 D:PAI(A;OICI;GA;;;SY)(A;OICI;GA;;;BA)(A;OICI;GRGX;;;BU)(A;OICIIO;GA;;;CO)，即仅系统、管理员与计算机账户可写，普通用户只读）。这样自定义安装根目录时，也不会把处于机器级 PATH 中的文件夹留给普通用户可写。

从 installer/PowerToysSetupVNext/CliShims.wxs 可以看到这一约定如何落地：<CreateFolder> 中的 <PermissionEx Sddl="$(var.MachinePathFolderSddl)" /> 被刻意编写在与该文件夹的 <Environment> PATH 条目相同的 Component 上，两者无法发生漂移；同时因为 CreateFolders 在 InstallFiles 写入 shim 之前就应用了 DACL，shim 文件自然继承该 ACL，无需各自声明 <PermissionEx>。

Shim 的内部工作机制（源码级解析）

tools/CliShim/main.cpp 是理解整套约定的最佳入口，wmain() 的执行流程为：

1. 注册控制台控制处理器：SetConsoleCtrlHandler 让 shim 拦截 Ctrl+C/Break。注释说明了原因——子进程会收到 Ctrl+C/Break，而 shim 必须保持存活才能把 CLI 的退出码传回调用方（见 main.cpp）。
2. 以自身文件名解析命令名：wil::GetModuleFileNameW 取得自身路径后取 stem()（去掉扩展名的文件名）作为 commandName，在 ShimTargets 表中用 CompareStringOrdinal(..., TRUE) 做大小写不敏感匹配（见 ResolveTarget）。
3. 校验目标存在性：目标路径为 selfPath.parent_path() / relativeTarget 经 lexically_normal() 规范化后的结果；若目标可执行文件缺失，向 stderr 输出错误并返回 9010。
4. 原样转发参数：CommandLine::StripArgumentZero(GetCommandLineW()) 按 CRT 分词规则移除 argv[0]，保留其余命令行文本逐字不变，确保调用方的引号语义不受影响。关于为什么不用 CommandLineToArgvW，tools/CliShim/CommandLine.h 的注释给出了解释：CRT 的分词规则（引号翻转 in-quotes 标志、反斜杠转义不终止 argv[0]）才是目标 CLI 实际解析参数所用的规则。
5. 启动目标并共享控制台：CreateProcessW 时继承句柄（TRUE），使 CLI 与调用方共享 stdin/stdout/stderr 并停留在同一控制台；命令行为 "目标路径" 原始参数尾部，其中 lpApplicationName 指定真实目标。
6. 作业对象生命周期管理：CreateShimJob() 创建带 JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE | JOB_OBJECT_LIMIT_SILENT_BREAKAWAY_OK 标志的作业对象（见 CreateShimJob）：
   • KILL_ON_JOB_CLOSE 保证无论 shim 以何种方式死亡（taskkill 不带 /T、Process.Kill() 不带整棵进程树、脚本自身的超时、调试器停止），内核都会关闭作业句柄并连带终止 CLI。注释举了真实场景：PowerToys.FileLocksmith.CLI --wait 会轮询直到被打断，若残留则长时间无输出；
   • SILENT_BREAKAWAY_OK 刻意把 CLI 自身的子进程排除在作业之外——例如 PowerToys.FancyZones.CLI open-settings 会启动长寿命的 PowerToys.exe 设置窗口后立即返回，没有此标志该窗口会在 shim 退出瞬间被杀。注释也指出普通 BREAKAWAY_OK 无法替代它（那要求创建者显式传 CREATE_BREAKAWAY_FROM_JOB，而 Process.Start 无法表达这一点）。
7. 透传退出码：WaitForSingleObject(INFINITE) 等待目标结束后，GetExitCodeProcess 取得退出码并原样返回。

ShimTargets 表本身不是手写维护的：CliShimManifest.props 中的 MSBuild 目标 GenerateCliShimTargets 在 ClCompile 前把清单里的每一项生成 C++ 初始化列表 CliShimTargets.g.inc，供 main.cpp 以 #include 方式并入。目标内还有一道前置校验：若 RelativeTarget 含有反斜杠会直接报构建错误，因为反斜杠会被原样放进 C++ 宽字符串字面量——..\WinUI3Apps\x.exe 会以 C4129 编译失败（在 TreatWarningAsError 下升级为错误），而 ..\bin\x.exe 则会静默编译成控制字符；两类诊断都会指向生成文件而非真正的出错清单，所以在清单处尽早拒绝。

Shim 退出码

shim 原样返回目标 CLI 的退出码；只有当 CLI 根本没有运行时才替换为它自己的一组退出码，这些值刻意落在 CLI 自身使用的退出码范围（0/1/2）之外，让调用方能区分"shim 没能运行 CLI"与"CLI 运行了但失败"：

退出码	含义
9009	被调用的命令名没有映射到任何 CLI（与 cmd.exe 的"command not found"一致，见 main.cpp）
9010	映射的目标可执行文件在安装中缺失
9011	shim 无法启动目标，包括无法解析自身路径的情况

新增一个 shim 的完整步骤

新增一条 PATH 可见命令只需要两处改动，且不需要维护第三张列表：

1. 在 tools/CliShim/CliShimManifest.props 中添加一个 <CliShim> 项，写明命令名和相对 bin 的目标路径。路径必须用 / 分隔，并且面向安装后布局（见下文"签名与部署"）——那是 CLI 的落盘位置，而不是它的构建位置；
2. 在 installer/PowerToysSetupVNext/CliShims.wxs 中添加对应的 <Component> 和 <ComponentRef>，以命令名作为 File/@Name。现有组件均遵循同一模式：固定 GUID、Bitness="always64"、指向 Software\Classes\powertoys\components 的注册表 KeyPath 值，以及 <File Source="$(var.BinDir)CliShim\PowerToys.CliShim.exe" Name="PowerToys.<Module>.CLI.exe" ... />——同一个源码文件以不同 Name 安装。

防漂移由三层机制保证：

• shim 项目自身：tools/CliShim/CliShim.vcxproj 的 ValidateCliShimInstallerManifest 目标在普通构建（而非仅构建安装器时）校验 CliShims.wxs 中 <File ... Name="*.exe"> 的数量与清单中的 CliShim 项一一对应，任何一侧漂移都会直接报"installer drift"构建错误。注释解释了为什么放在产品项目而非 wixproj：漂移会在任何普通构建时暴露，而不是等到有人构建安装器才被发现；
• 安装器构建：build-installer.ps1 会校验 RelativeTarget 能解析到一个真实可执行文件，否则构建失败；
• 单元测试：CliShim.UnitTests（tools/CliShim.UnitTests/，含 CommandLineTests.cpp 与 LauncherIntegrationTests.cpp）的期望值由同一份清单生成——测试断言的表就是构建 shim 所用的表，新命令不可能只出现在一侧。

参数解析：System.CommandLine 库约定

规范指定使用 System.CommandLine 做 CLI 参数解析，版本已在 Directory.Packages.props 中集中锁定：

<PackageVersion Include="System.CommandLine" Version="2.0.0-beta4.22272.1" />

在模块项目中以中央包管理方式引用（不带版本号）：

<PackageReference Include="System.CommandLine" />

选项命名与定义

• 长形式使用 --kebab-case（如 --shrink-only）；
• 短形式使用单字符 -x（如 -s、-w）；
• 别名定义为 static readonly 数组，例如 ["--silent", "-s"]；
• 使用 Option<T> 创建选项并附带描述性帮助文本；
• 对需要范围或格式校验的选项添加 validator。

这一约定在 ImageResizer CLI 中有完整体现：src/modules/imageresizer/ui/Cli/Options/ 目录下每个选项一个文件——ShrinkOnlyOption.cs、WidthOption.cs、HeightOption.cs、QualityOption.cs、ReplaceOption.cs、IgnoreOrientationOption.cs 等，并配有 DimensionOptionValidator.cs 这类范围/格式校验器。

RootCommand 设置与解析

• 创建一个带简明描述的 RootCommand，把所有选项和参数添加进去。参考实现：src/modules/imageresizer/ui/Cli/Commands/ImageResizerRootCommand.cs；
• 使用 Parser(rootCommand).Parse(args) 解析参数，通过 parseResult.GetValueForOption() 提取选项值；
• 版本注意：直接使用 Parser 入口；在仓库锁定的 System.CommandLine 版本下，RootCommand.Parse() 可能不可用；
• 参考实现还包括 Awake 的 src/modules/awake/Awake/Program.cs 与 src/modules/imageresizer/ui/Cli/。

解析与校验错误处理

出现解析/校验错误时，打印错误信息和使用说明，然后以非零退出码退出。ImageResizerCliExecutor.cs 给出了规范的落地示例：遍历 ParseErrors 逐条写入 Console.Error 并调用 CliLogger.Error，再调用 CliOptions.PrintUsage()，return 1；--help 打印用法后返回 0；没有任何输入文件且未重定向 stdin 时同样打印 CLI_NoInputFiles 提示与用法并返回 1。

帮助输出、日志与错误处理

帮助输出

如需自定义帮助格式，提供 PrintUsage() 方法。ImageResizer 的 CliOptions.PrintUsage() 同时服务于 --help 与错误路径，是"错误时打印 usage"约定的具体实现。

日志要求

• 使用 ManagedCommon.Logger 保持一致的日志；
• 在 Main() 早期初始化日志；
• 错误与警告使用双路输出（控制台 + 日志文件）以确保可见性。

参考实现 src/modules/imageresizer/ui/Cli/CliLogger.cs 是一个薄封装：Initialize(string logSubFolder) 用 _initialized 布尔量保证只调用一次 Logger.InitializeLogger，随后 Info/Warn/Error 分别委托给 Logger.LogInfo/LogWarning/LogError，底层即 src/common/ManagedCommon/Logger.cs。

退出码

• 0：成功；
• 1：一般错误（解析、校验、运行时）；
• 2：无效参数（可选）。

异常处理

• 始终用 try-catch 包裹 Main() 以捕获未处理异常；
• 以非零退出码退出前先记录异常；
• 向 stderr 输出用户友好的错误信息；
• 详细堆栈跟踪仅保留在日志文件中，不输出给用户。

测试要求

• 为参数解析、校验与边界情况编写测试；
• CLI 测试放在模块专属测试项目中，例如 src/modules/[module]/tests/*CliTests.cs；
• shim 层的测试则位于 CliShim.UnitTests，其期望值由 CliShimManifest.props 同一份清单生成，天然与生产代码同步。

签名与部署

• CLI 可执行文件在 CI/CD 中自动签名；新增 CLI 工具时，需把自己的 exe 与 dll 加入 .pipelines/ESRPSigning_core.json 的签名列表；
• 部署位置分两类：安装根目录（例如 C:\Program Files\PowerToys\FancyZonesCLI.exe），或 WinUI 3 模块随模块一起放在 WinUI3Apps\ 下（例如 C:\Program Files\PowerToys\WinUI3Apps\PowerToys.ImageResizerCLI.exe）；PATH 可见的 shim 则统一部署到 C:\Program Files\PowerToys\bin\；
• shim 的 RelativeTarget 从 bin 目录出发、按安装后布局解析，而不是按源码树解析——这就是为什么新增 shim 时必须以最终落盘位置书写相对路径；
• 使用自包含（self-contained）部署，导入 Common.SelfContained.props（对应文件为 src/Common.SelfContained.props）。

最佳实践

规范文档最后给出六条协作层面的实践要求：

1. 一致性：遵循现有模块的既有模式；
2. 文档：为每个选项始终提供帮助文本；
3. 校验：校验输入并给出清晰的错误信息；
4. 原子性：每个 PR 只做一项逻辑变更，避免顺手重构（drive-by refactors）；
5. 构建/测试纪律：同步执行构建与测试，一个操作一个终端；
6. 风格：遵循仓库分析器（.editorconfig、StyleCop）与格式化规则。

小结

PowerToys 的 CLI 体系可以概括为一条链路：CliShimManifest.props 作为命令名到安装后目标的单一事实来源，编译期生成 shim 内的目标表并驱动单元测试，CliShim.vcxproj 与 CliShims.wxs 在构建期互检防漂移；运行时由同一个 shim 载荷按文件名解析目标、原样转发参数、共享控制台、用作业对象管理生命周期、透传退出码；模块侧则以 System.CommandLine（锁定版本 2.0.0-beta4.22272.1）解析参数，遵循 --kebab-case/单字符短选项命名、0/1/2 退出码约定与 ManagedCommon.Logger 双路日志。新增一条命令时只需改两个文件，其余校验由构建系统自动完成。