PowerToys 崩溃分诊指南：用 Watson 查询按 Catch-all、EXE 与 DLL 三个维度定位故障

本文基于 PowerToys 仓库内部分诊手册 watson-queries.md，讲解如何在 Microsoft 内部 Watson 崩溃分析门户中，围绕 PowerToys 的发布版本构造三类查询——全量兜底查询（Catch all）、按可执行文件名查询（EXE name）、按模块 DLL 名查询（DLL based）。读完后你能独立完成一次崩溃分诊：给定一个版本号，快速拉出该版本所有相关崩溃、区分安装器/主程序/Run 启动器的进程归属，并将故障收敛到具体的功能模块 DLL。

1. Watson 在 PowerToys 崩溃诊断体系中的位置

PowerToys 项目文档 logging.md 将项目的日志机制归纳为四类，其中第 4 类正是 Watson：

4. Watson reports (crash reports sent to Microsoft)

也就是说，Watson 是独立于本地文本日志、ETW 遥测和 Event Viewer 之外的崩溃报告通道，由崩溃发生时自动产生并上报到 Microsoft 内部系统。这与本地 %LOCALAPPDATA%\Microsoft\PowerToys\Logs 下的应用日志互补：本地日志用于分析用户现场，Watson 则用于聚合全量用户的崩溃数据、按进程与模块维度分诊。

doc/devdocs/watson-queries.md 的标题明确标注为 [msft only]——这是一份仅面向 Microsoft 内部成员的分诊速查表，其中的查询模板指向 watsonportal.microsoft.com 门户，外部访问者无法打开这些页面，但查询的构造方式（查询端点、参数命名、过滤条件）本身就是可学习的方法论。项目贡献指南 guidelines.md 中也提到 "Bug fixes related to Watson errors sometimes don't have corresponding issue links"，说明 Watson 驱动的修复经常不挂在公开 Issue 上，而是直接从崩溃数据出发立项，这凸显了掌握分诊查询的价值。

2. Catch all：按版本做全量崩溃兜底查询

手册第一类查询是 Catch all（全量兜底），使用门户的 CabSearch 端点：

https://watsonportal.microsoft.com/CabSearch?=&DateTimeFormat=UTC&MaxRows=1000&AppScope_AppVersion=0.100.2.0&Process=*powertoys*

各参数含义可以从 URL 结构直接读出：

参数	取值（示例）	作用
端点	CabSearch	崩溃转储（cab）全量检索
DateTimeFormat	UTC	统一以 UTC 时间展示，避免时区干扰
MaxRows	1000	单次最多返回 1000 行，适合分诊期拉全量
AppScope_AppVersion	0.100.2.0	锁定到具体发布版本（注意带 4 段版本号）
Process	*powertoys*	通配匹配所有名称包含 powertoys 的进程

这条查询的特点是不区分具体进程：Process=*powertoys* 会同时覆盖 PowerToys.exe、PowerToys.PowerLauncher.exe、安装器以及以 powertoys 命名的其他进程。分诊启动阶段用它确认"这个版本到底有没有成规模的崩溃"。

手册中的原样提示：分诊时必须把 AppScope_AppVersion（以及下文各安装器文件名）更新为当前发布版本。

关于版本取值有一个重要的仓库内佐证：文档中示例使用的是 0.100.2，而当前 main 分支的 src/Version.props 显示：

<Version>0.0.1</Version>
<VersionChannel>private</VersionChannel>
<!-- Update once when main moves to the next stable release train. -->
<ReleaseTrainVersion>0.101</ReleaseTrainVersion>

Version 字段是构建时填充的占位值，真正反映发布列车的是 ReleaseTrainVersion（当前为 0.101）。因此分诊 0.100.x 系列崩溃时沿用文档中的 0.100.2.0，而分诊更新版本时应按发布管线实际产出的版本号替换，不能假设文档中的快照值长期有效。

3. EXE name：按可执行文件名查询各进程

第二类查询用于按具体 EXE 归属查看崩溃，使用 Application 端点，统一参数为 DateRange=Last 14 Days&MaxRows=100。手册列出了六条查询，覆盖 PowerToys 的三个进程类别：

3.1 安装器（4 条，按架构与安装级别区分）

# Machine installer (x64)
?DateRange=Last%2014%20Days&MaxRows=100&AppScope_AppName=PowerToysSetup-0.100.2-x64.exe
# Machine installer (arm64)
?DateRange=Last%2014%20Days&MaxRows=100&AppScope_AppName=PowerToysSetup-0.100.2-arm64.exe
# User installer (x64)
?DateRange=Last%2014%20Days&MaxRows=100&AppScope_AppName=PowerToysUserSetup-0.100.2-x64.exe
# User installer (arm64)
?DateRange=Last%2014%20Days&MaxRows=100&AppScope_AppName=PowerToysUserSetup-0.100.2-arm64.exe

安装器命名遵循 PowerToys{User}Setup-{version}-{arch}.exe 的规则：PowerToysSetup 是机器级（machine）安装器，PowerToysUserSetup 是用户级安装器，后缀区分 x64 与 arm64 两种架构。这与仓库的安装工程一致：installer/PowerToysSetupVNext/PowerToysInstallerVNext.wixproj 与 PowerToysBootstrapperVNext.wixproj 即为 VNext 安装器的构建工程。安装器崩溃通常指向 WiX 安装阶段问题，与运行时崩溃的排查路径完全不同，所以手册把它单列成 4 条独立查询。

3.2 主进程与 PT Run（2 条）

# Main exe
?DateRange=Last%2014%20Days&MaxRows=100&AppScope_AppVersion=0.100.2&AppScope_AppName=PowerToys.exe
# PT Run / example
?DateRange=Last%2014%20Days&MaxRows=100&AppScope_AppVersion=0.100.2&AppScope_AppName=PowerToys.PowerLauncher.exe

• PowerToys.exe 是宿主主程序，其工程位于 src/runner，可执行文件清单可见 src/runner/PowerToys.exe.manifest；
• PowerToys.PowerLauncher.exe 是 PT Run 启动器的独立进程，工程位于 src/modules/launcher。手册中特意标注 "/ example"，因为 PT Run 是独立 exe 的"典型代表"——PowerToys 的很多功能以独立可执行文件形式从主进程派生，崩溃分诊时需要逐个进程定位。

这两条与 3.1 的差异在于多带了一个 AppScope_AppVersion 参数，即进程名 + 版本号双重过滤；而安装器查询只按文件名过滤（文件名本身已含版本）。

4. DLL based：按模块名查询宿主进程内的故障

第三类查询针对以 DLL 形式被加载的功能模块，使用 Failure/ModuleSearch 端点：

?AppScope_AppVersion=0.100.2.0&FailureSearchText=<模块DLL名>

手册列出的五个模块查询及对应仓库源码位置：

查询项	FailureSearchText	对应模块源码
KBM	keyboardmanager.dll	src/modules/keyboardmanager
Power Preview	powerpreview.dll	src/modules/previewpane
SVG Thumbnail	SvgThumbnailProvider.dll	预览/缩略图提供程序工程组，见 src/modules/previewpane
SVG Preview Pane	SvgPreviewHandler.dll	同上
Markdown Preview Pane	MarkdownPreviewHandler.dll	同上

按 DLL 而非 EXE 查询有其结构性原因。从 logging.md 对低权限日志的说明可以看到："Some components (like preview handlers and thumbnail providers) are started by Explorer and have low privileges"——预览处理器和缩略图提供程序运行在资源管理器进程中、以低权限启动，其崩溃的进程名是 explorer.exe 而非任何 powertoys 前缀的进程，Catch all 里的 Process=*powertoys* 通配根本匹配不到它们。因此必须换用 ModuleSearch，以"崩溃堆栈中出现的模块文件名"为检索键，才能把这类寄生在宿主进程中的故障捞出来。同理，KBM 等模块 DLL 被宿主进程加载时，按模块名检索比按进程名更精准。

该端点同样需要 AppScope_AppVersion 参数（示例为 0.100.2.0），分诊新版时应按 2 节所述方法替换。

5. 分诊实操建议：三类查询如何配合

结合手册内容与仓库结构，一次完整的版本崩溃分诊可以按以下顺序执行：

1. Catch all 摸底：用 CabSearch 拉取该版本全部 powertoys 相关进程崩溃，确认崩溃总量与主要聚合；
2. 按 EXE 拆分：对安装器（4 条）与主程序/PT Run 等独立 exe 分别用 Application 查询，把崩溃归属到"安装阶段"还是"运行时"，以及具体哪个进程；
3. 按 DLL 收口：对运行在宿主进程内、进程名无法体现 PowerToys 归属的模块（KB、预览/缩略图提供程序等），用 Failure/ModuleSearch 按模块 DLL 名精确检索；
4. 版本同步：开始前先核对当前发布版本。文档中的 0.100.2 是其写作时的版本快照，当前 main 分支 src/Version.props 的 ReleaseTrainVersion 已推进到 0.101，说明文档中的具体版本号、安装器文件名与 AppScope_AppVersion 取值都需要按手册提示随版本更新，切勿直接沿用。
5. 交叉印证：拿到崩溃聚合后，可结合用户侧证据进一步分析——本地日志位于 %LOCALAPPDATA%\Microsoft\PowerToys\Logs（低权限组件在 %USERPROFILE%/AppData/LocalLow/Microsoft/PowerToys，详见 logging.md），而 BugReportTool 生成的桌面压缩包则包含日志与系统信息，可作为单个用户的现场补充。

需要强调的适用前提：上述查询模板全部指向 Microsoft 内部 Watson 门户，仅内部成员可用；本文对外部读者呈现的是查询构造方法——端点选择（CabSearch / Application / Failure/ModuleSearch）、参数命名（AppScope_AppVersion、AppScope_AppName、Process、FailureSearchText、DateRange、MaxRows）以及 PowerToys 的进程/DLL 命名规律。理解这套规律后，你可以将其迁移到任何具备类似崩溃数据检索能力的诊断平台上。