PowerToys Advanced PasteAI 粘贴预览机制与稀疏包身份调试实战指南【免费下载链接】PowerToysMicrosoft PowerToys is a collection of utilities that supercharge productivity and customization on Windows项目地址: https://gitcode.com/GitHub_Trending/po/PowerToys本文基于 PowerToys 官方开发文档 advancedpaste.md系统讲解 Advanced Paste 模块的两个核心技术点其AI 粘贴预览功能的实现流程ShowCustomPreview设置如何复用已生成的 AI 响应而不消耗额外调用以及作为非打包 WinUI 3 应用的PowerToys.AdvancedPaste.exe如何通过共享稀疏 MSIX 包Microsoft.PowerToys.SparseApp获得包身份以解锁 Windows AI 受限功能Phi Silica /LanguageModel。读完后你将掌握本地调试 Advanced Paste 的完整流程、稀疏包一键注册与验证命令、常见故障的定位方法以及 Settings UI 通过子进程探测 AI 可用性的机制。模块概览Advanced Paste 是 PowerToys 中提供增强剪贴板粘贴的模块在标准粘贴之外提供带格式化选项与 AI 处理能力的粘贴动作如修正拼写与语法、自定义 AI 粘贴等。源码位于 src/modules/AdvancedPaste核心 C# 项目在 src/modules/AdvancedPaste/AdvancedPaste模块接口层负责进程管理与命名管道 IPC位于 src/modules/AdvancedPaste/AdvancedPasteModuleInterface。从源码结构看该模块是一个非打包unpackaged、自包含的 WinUI 3 应用PowerToys.AdvancedPaste.exe。要调用 Phi Silica 的Microsoft.Windows.AI.Text.LanguageModelAPI进程必须具备匹配的包身份——这正是后文稀疏包身份机制要解决的问题。模块入口在 Program.cs其中还能看到 GPO 策略检查管理员可通过组策略禁用该工具、AppInstance.FindOrRegisterForKey单实例保护等启动逻辑。AI 粘贴预览ShowCustomPreview与生成结果缓存官方文档中最关键的实现说明是Show preview 设置ShowCustomPreview控制 AI 生成结果是否在粘贴前于预览窗口中展示且预览功能不额外消耗 AI 调用额度——预览展示的是同一次 API 调用已经生成、并在本地缓存的结果。文档给出的实现流程为用户发起 Paste with AI 动作通过ExecutePasteFormatAsync发起单次AI API 调用结果缓存在GeneratedResponses集合中若预览已启用缓存结果展示在预览 UI 中用户粘贴缓存结果时不再产生任何额外 API 调用。这一流程在源码中可以得到逐条印证。核心方法ExecutePasteFormatAsync(PasteFormat, PasteActionSource)位于 OptionsViewModel.cs第 746 行调用_pasteFormatExecutor.ExecutePasteFormatAsync(...)执行实际的格式转换对 AI 动作即一次 AI 调用执行器接口见 IPasteFormatExecutor.cs 与实现 PasteFormatExecutor.cs第 753 行是预览判定条件pasteFormat.Metadata.CanPreview _userSettings.ShowCustomPreview !string.IsNullOrEmpty(outputText) source ! PasteActionSource.GlobalKeyboardShortcut——即格式元数据允许预览、用户开启ShowCustomPreview、输出非空、且来源不是全局快捷键时才走预览拼写/语法修正的引导coaching模式则会强制预览第 763 行GeneratedResponses.Add(outputText)将结果写入ObservableCollectionstring GeneratedResponses定义于第 583 行并更新CurrentResponseIndex指向最新一条随后触发PreviewRequested事件展示预览界面。也就是说AI 调用只发生一次预览与最终粘贴消费的都是同一个dataPackage/ 缓存文本这与文档中预览不消耗额外 AI 额度的结论一致。设置项设置说明ShowCustomPreview启用后粘贴前在预览窗口中展示 AI 生成的结果。不影响 AI 额度消耗。ShowCustomPreview作为用户设置字段在 UserSettings.cs 中定义模块接口层dllmain.cpp也引用了该字段进行设置序列化。调试运行与附加调试器由于 Advanced Paste 由 Runner 在模块启用后于后台拉起官方文档给出的标准调试步骤是在 Visual Studio 中将Runner项目src/runner设为启动项目启动 RunnerF5拉起 PowerToys 托盘图标并加载所有模块接口打开设置右键托盘图标 → Settings确认已启用Advanced Paste模块。启用后模块会立即在后台启动PowerToys.AdvancedPaste.exe在 Visual Studio 中选择Debug → Attach to ProcessCtrlAltP附加到PowerToys.AdvancedPaste.exe调试器类型选择Managed (.NET Core)。替代方案使用 VS Code 的启动配置Run AdvancedPaste位于 .vscode/launch.json直接拉起 exe——但文档明确提示没有 Runner 时IPC 与全局快捷键均不可用因为管道服务器与快捷键注册都由模块接口层Runner 进程内负责。稀疏包身份非打包 WinUI 3 应用的包身份问题为什么需要稀疏包身份LanguageModelAPI 需要 Limited Access FeatureLAF解锁而解锁只有调用进程具备匹配包身份时才会成功Advanced Paste 是非打包、自包含的 WinUI 3 应用。稀疏包在不将其转换为完整 MSIX的前提下授予其身份csproj 使用ProjectPriFileNamePowerToys.AdvancedPaste.pri/ProjectPriFileName与 ImageResizer 等其他 WinUI3 应用相同的自定义 PRI 命名约定。这一点可在 AdvancedPaste.csproj 第 24 行确认。该约定要求 WindowsAppSDK Foundation ≥ 2.0.22对应 WindowsAppSDK 的 PR #6376该版本修复了 MRT 在稀疏身份下查找自定义命名 PRI 文件的问题使Application.LoadComponent能解析自定义 PRI 名而不是硬编码resources.pri。一键开发环境搭建完整的稀疏包文档位于 src/PackageIdentity/readme.md。Advanced Paste 文档给出的一键开发注册命令为pwsh src/PackageIdentity/BuildSparsePackage.ps1 -Platform ARM64 -Configuration Debug -DevRegister-DevRegister的行为对应脚本 BuildSparsePackage.ps1在src/PackageIdentity/.user/下生成开发证书仅首次运行自动将该证书导入CurrentUser\TrustedPeople与CurrentUser\Root使系统愿意把稀疏身份授予 AP没有信任关系时GetPackageFamilyName会返回APPMODEL_ERROR_NO_PACKAGELAF 解锁静默失败移除此前的注册在AppxManifest.xml的临时副本中重写 publisher使其匹配开发证书主题通过Add-AppxPackage -Register … -ExternalLocation X:\…\Platform\Config\WinUI3Apps完成注册。关于-ExternalLocation指向WinUI3Apps子目录的原因src/PackageIdentity/readme.md 有进一步说明MSIX 本身只含元数据将其指向 Win32 可执行文件所在子目录可以把 MSIX 注册在 Windows 23H2/24H2 上引发的 DACL 变更隔离在WinUI3Apps文件夹内保持安装根目录干净预览处理器 DLL 仍从根目录加载。BuildSparsePackage.ps1还支持的其他开关-Clean清理此前bin/obj输出并卸载已有安装-ForceCert重新生成本地开发证书.pfx/.cer/.pwd/.thumbprint-NoSign跳过签名MSIX 仍能构建但部署前必须签名-CIBuild或$env:CIBuild true保留 manifest 中的 publisher 原样、跳过本地证书替换供 CI 使用。注册后验证$pkg Get-AppxPackage -Name *SparseApp* $pkg.PackageFamilyName # Microsoft.PowerToys.SparseApp_PublisherId $pkg.PublisherId $pkg.IsDevelopmentMode # True然后确认 AP 在运行时确实获得了稀疏身份 ARM64\Debug\WinUI3Apps\PowerToys.AdvancedPaste.exe --check-phi-silica # Exit 0 Available, 1 NotReady, 2 NotSupported重新构建 AP、修改 AppxManifest.xml 或切换平台/配置后需重新运行同一命令以完成重新注册使用-Unregister可注销身份。此外打包完成后脚本还会输出src/PackageIdentity/.user/PowerToysSparse.publisher.txt镜像注册后 Windows 可见的 publisher 字符串供其他组件在生成自身 manifest 时保持同步。故障排查表官方文档给出的排查表完整继承问题原因解决方案运行时GetPackageFamilyName返回APPMODEL_ERROR_NO_PACKAGE(15700)LAF 解锁返回Unavailable开发证书未被信任或稀疏包未注册重新运行BuildSparsePackage.ps1 -DevRegister——会自动把证书导入TrustedPeople与Root。AP 或 Settings 启动时Microsoft.UI.Xaml.dll崩溃错误0xC000027Bclass-not-registeredAppxManifest.xml中Application的Executable路径无法在已注册的ExternalLocationConfig\WinUI3Apps\下解析确认每个Executable相对于WinUI3Apps\见 issue #47177且文件存在于构建输出中。通过快捷键触发时 AP 启动但始终不显示窗口Runner 的管道服务器等待在 AP 冷启动完成 WinAppSDK DI 宿主引导之前超时AdvancedPasteProcessManager.cpp中 15 秒管道超时已缓解该问题热启动连接远低于 1 秒。对应源码见 AdvancedPasteProcessManager.cppXamlParseException/ 找不到ms-appx:///Microsoft.UI.Xaml/Themes/…WindowsAppSDK Foundation 2.0.22MRT 无法在稀疏身份下解析自定义 PRI 名确保Directory.Packages.props中Microsoft.WindowsAppSDK.Foundation≥ 2.0.22。Settings UI 如何检查 Phi Silica 可用性Settings UI 本身没有稀疏包身份无法直接探测 Phi Silica。它的做法是把 Advanced Paste 作为短命子进程启动PowerToys.AdvancedPaste.exe --check-phi-silicaProgram.cs 中Program.Main识别该参数并进入CheckPhiSilicaAvailability()先调用PhiSilicaLafHelper.TryUnlock()再调用LanguageModel.GetReadyState()向 stdout 输出Available/NotReady/NotSupported之一并以相应退出码结束0 Available1 NotReady2 NotSupported 或错误。Settings 端读取 stdout 并等待最多 10 秒。由于每次检查都是全新进程瞬时的Unavailable结果不会跨检查缓存。LAF 解锁逻辑在 PhiSilicaLafHelper.cs 中特性 ID 为com.microsoft.windows.ai.languagemodel只缓存成功的解锁结果——失败Unavailable、未知状态、异常往往是瞬时的例如登录前 AI 特性栈尚未初始化、或稀疏身份尚未完全应用到刚启动的进程下次调用时重试即可恢复。LastUnlockStatus属性暴露最近一次解锁状态便于诊断真实的 LAF 结果而不是下游模型调用那句笼统的 Access is denied。源码中还有一个文档未展开的兄弟参数--prepare-phi-silicaProgram.cs它在不启动 WinUI 应用的情况下触发 Phi Silica 模型准备下载通过EnsureReadyAsync()把模型从NotReady推进到Ready退出码为 0 ready、1 准备失败、2 不受支持。注释还说明了一个细节EnsureReadyAsync这类 WinRT 异步操作若从[STAThread]入口点阻塞等待无法正确编组因此代码将其放到线程池线程上执行。延伸资料advancedpaste-phisilica-local-testing.mdPhi Silica 可用性的分层诊断与本地测试/故障排查指南src/PackageIdentity/readme.md稀疏包的完整文档包括构建、签名、注册/注销、CI 指引以及其他组件如何消费稀疏身份的六步流程在AppxManifest.xml中新增Application条目、在 Win32 二进制中嵌入带msix元素的 sparse identity manifest、使用shell:AppsFolder\...激活形式启动等Advanced Paste 的设置界面与 DSC 资源分别见 Settings UI 与 doc/dsc/modules/AdvancedPaste.md 中的说明。适用前提与限制上述调试与稀疏包注册流程面向 Windows 本地开发环境PowerShell Visual Studio / VS Code--check-phi-silica的可用性结果取决于系统 AI 特性栈、硬件与授权状态Phi Silica 相关 API 仅在有 Windows AI 能力的系统上返回Ready其他系统会以NotReady或NotSupported状态呈现属预期行为。【免费下载链接】PowerToysMicrosoft PowerToys is a collection of utilities that supercharge productivity and customization on Windows项目地址: https://gitcode.com/GitHub_Trending/po/PowerToys创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 PowerToys Advanced Paste：AI 粘贴预览机制与稀疏包身份调试实战指南
PowerToys Advanced PasteAI 粘贴预览机制与稀疏包身份调试实战指南【免费下载链接】PowerToysMicrosoft PowerToys is a collection of utilities that supercharge productivity and customization on Windows项目地址: https://gitcode.com/GitHub_Trending/po/PowerToys本文基于 PowerToys 官方开发文档 advancedpaste.md系统讲解 Advanced Paste 模块的两个核心技术点其AI 粘贴预览功能的实现流程ShowCustomPreview设置如何复用已生成的 AI 响应而不消耗额外调用以及作为非打包 WinUI 3 应用的PowerToys.AdvancedPaste.exe如何通过共享稀疏 MSIX 包Microsoft.PowerToys.SparseApp获得包身份以解锁 Windows AI 受限功能Phi Silica /LanguageModel。读完后你将掌握本地调试 Advanced Paste 的完整流程、稀疏包一键注册与验证命令、常见故障的定位方法以及 Settings UI 通过子进程探测 AI 可用性的机制。模块概览Advanced Paste 是 PowerToys 中提供增强剪贴板粘贴的模块在标准粘贴之外提供带格式化选项与 AI 处理能力的粘贴动作如修正拼写与语法、自定义 AI 粘贴等。源码位于 src/modules/AdvancedPaste核心 C# 项目在 src/modules/AdvancedPaste/AdvancedPaste模块接口层负责进程管理与命名管道 IPC位于 src/modules/AdvancedPaste/AdvancedPasteModuleInterface。从源码结构看该模块是一个非打包unpackaged、自包含的 WinUI 3 应用PowerToys.AdvancedPaste.exe。要调用 Phi Silica 的Microsoft.Windows.AI.Text.LanguageModelAPI进程必须具备匹配的包身份——这正是后文稀疏包身份机制要解决的问题。模块入口在 Program.cs其中还能看到 GPO 策略检查管理员可通过组策略禁用该工具、AppInstance.FindOrRegisterForKey单实例保护等启动逻辑。AI 粘贴预览ShowCustomPreview与生成结果缓存官方文档中最关键的实现说明是Show preview 设置ShowCustomPreview控制 AI 生成结果是否在粘贴前于预览窗口中展示且预览功能不额外消耗 AI 调用额度——预览展示的是同一次 API 调用已经生成、并在本地缓存的结果。文档给出的实现流程为用户发起 Paste with AI 动作通过ExecutePasteFormatAsync发起单次AI API 调用结果缓存在GeneratedResponses集合中若预览已启用缓存结果展示在预览 UI 中用户粘贴缓存结果时不再产生任何额外 API 调用。这一流程在源码中可以得到逐条印证。核心方法ExecutePasteFormatAsync(PasteFormat, PasteActionSource)位于 OptionsViewModel.cs第 746 行调用_pasteFormatExecutor.ExecutePasteFormatAsync(...)执行实际的格式转换对 AI 动作即一次 AI 调用执行器接口见 IPasteFormatExecutor.cs 与实现 PasteFormatExecutor.cs第 753 行是预览判定条件pasteFormat.Metadata.CanPreview _userSettings.ShowCustomPreview !string.IsNullOrEmpty(outputText) source ! PasteActionSource.GlobalKeyboardShortcut——即格式元数据允许预览、用户开启ShowCustomPreview、输出非空、且来源不是全局快捷键时才走预览拼写/语法修正的引导coaching模式则会强制预览第 763 行GeneratedResponses.Add(outputText)将结果写入ObservableCollectionstring GeneratedResponses定义于第 583 行并更新CurrentResponseIndex指向最新一条随后触发PreviewRequested事件展示预览界面。也就是说AI 调用只发生一次预览与最终粘贴消费的都是同一个dataPackage/ 缓存文本这与文档中预览不消耗额外 AI 额度的结论一致。设置项设置说明ShowCustomPreview启用后粘贴前在预览窗口中展示 AI 生成的结果。不影响 AI 额度消耗。ShowCustomPreview作为用户设置字段在 UserSettings.cs 中定义模块接口层dllmain.cpp也引用了该字段进行设置序列化。调试运行与附加调试器由于 Advanced Paste 由 Runner 在模块启用后于后台拉起官方文档给出的标准调试步骤是在 Visual Studio 中将Runner项目src/runner设为启动项目启动 RunnerF5拉起 PowerToys 托盘图标并加载所有模块接口打开设置右键托盘图标 → Settings确认已启用Advanced Paste模块。启用后模块会立即在后台启动PowerToys.AdvancedPaste.exe在 Visual Studio 中选择Debug → Attach to ProcessCtrlAltP附加到PowerToys.AdvancedPaste.exe调试器类型选择Managed (.NET Core)。替代方案使用 VS Code 的启动配置Run AdvancedPaste位于 .vscode/launch.json直接拉起 exe——但文档明确提示没有 Runner 时IPC 与全局快捷键均不可用因为管道服务器与快捷键注册都由模块接口层Runner 进程内负责。稀疏包身份非打包 WinUI 3 应用的包身份问题为什么需要稀疏包身份LanguageModelAPI 需要 Limited Access FeatureLAF解锁而解锁只有调用进程具备匹配包身份时才会成功Advanced Paste 是非打包、自包含的 WinUI 3 应用。稀疏包在不将其转换为完整 MSIX的前提下授予其身份csproj 使用ProjectPriFileNamePowerToys.AdvancedPaste.pri/ProjectPriFileName与 ImageResizer 等其他 WinUI3 应用相同的自定义 PRI 命名约定。这一点可在 AdvancedPaste.csproj 第 24 行确认。该约定要求 WindowsAppSDK Foundation ≥ 2.0.22对应 WindowsAppSDK 的 PR #6376该版本修复了 MRT 在稀疏身份下查找自定义命名 PRI 文件的问题使Application.LoadComponent能解析自定义 PRI 名而不是硬编码resources.pri。一键开发环境搭建完整的稀疏包文档位于 src/PackageIdentity/readme.md。Advanced Paste 文档给出的一键开发注册命令为pwsh src/PackageIdentity/BuildSparsePackage.ps1 -Platform ARM64 -Configuration Debug -DevRegister-DevRegister的行为对应脚本 BuildSparsePackage.ps1在src/PackageIdentity/.user/下生成开发证书仅首次运行自动将该证书导入CurrentUser\TrustedPeople与CurrentUser\Root使系统愿意把稀疏身份授予 AP没有信任关系时GetPackageFamilyName会返回APPMODEL_ERROR_NO_PACKAGELAF 解锁静默失败移除此前的注册在AppxManifest.xml的临时副本中重写 publisher使其匹配开发证书主题通过Add-AppxPackage -Register … -ExternalLocation X:\…\Platform\Config\WinUI3Apps完成注册。关于-ExternalLocation指向WinUI3Apps子目录的原因src/PackageIdentity/readme.md 有进一步说明MSIX 本身只含元数据将其指向 Win32 可执行文件所在子目录可以把 MSIX 注册在 Windows 23H2/24H2 上引发的 DACL 变更隔离在WinUI3Apps文件夹内保持安装根目录干净预览处理器 DLL 仍从根目录加载。BuildSparsePackage.ps1还支持的其他开关-Clean清理此前bin/obj输出并卸载已有安装-ForceCert重新生成本地开发证书.pfx/.cer/.pwd/.thumbprint-NoSign跳过签名MSIX 仍能构建但部署前必须签名-CIBuild或$env:CIBuild true保留 manifest 中的 publisher 原样、跳过本地证书替换供 CI 使用。注册后验证$pkg Get-AppxPackage -Name *SparseApp* $pkg.PackageFamilyName # Microsoft.PowerToys.SparseApp_PublisherId $pkg.PublisherId $pkg.IsDevelopmentMode # True然后确认 AP 在运行时确实获得了稀疏身份 ARM64\Debug\WinUI3Apps\PowerToys.AdvancedPaste.exe --check-phi-silica # Exit 0 Available, 1 NotReady, 2 NotSupported重新构建 AP、修改 AppxManifest.xml 或切换平台/配置后需重新运行同一命令以完成重新注册使用-Unregister可注销身份。此外打包完成后脚本还会输出src/PackageIdentity/.user/PowerToysSparse.publisher.txt镜像注册后 Windows 可见的 publisher 字符串供其他组件在生成自身 manifest 时保持同步。故障排查表官方文档给出的排查表完整继承问题原因解决方案运行时GetPackageFamilyName返回APPMODEL_ERROR_NO_PACKAGE(15700)LAF 解锁返回Unavailable开发证书未被信任或稀疏包未注册重新运行BuildSparsePackage.ps1 -DevRegister——会自动把证书导入TrustedPeople与Root。AP 或 Settings 启动时Microsoft.UI.Xaml.dll崩溃错误0xC000027Bclass-not-registeredAppxManifest.xml中Application的Executable路径无法在已注册的ExternalLocationConfig\WinUI3Apps\下解析确认每个Executable相对于WinUI3Apps\见 issue #47177且文件存在于构建输出中。通过快捷键触发时 AP 启动但始终不显示窗口Runner 的管道服务器等待在 AP 冷启动完成 WinAppSDK DI 宿主引导之前超时AdvancedPasteProcessManager.cpp中 15 秒管道超时已缓解该问题热启动连接远低于 1 秒。对应源码见 AdvancedPasteProcessManager.cppXamlParseException/ 找不到ms-appx:///Microsoft.UI.Xaml/Themes/…WindowsAppSDK Foundation 2.0.22MRT 无法在稀疏身份下解析自定义 PRI 名确保Directory.Packages.props中Microsoft.WindowsAppSDK.Foundation≥ 2.0.22。Settings UI 如何检查 Phi Silica 可用性Settings UI 本身没有稀疏包身份无法直接探测 Phi Silica。它的做法是把 Advanced Paste 作为短命子进程启动PowerToys.AdvancedPaste.exe --check-phi-silicaProgram.cs 中Program.Main识别该参数并进入CheckPhiSilicaAvailability()先调用PhiSilicaLafHelper.TryUnlock()再调用LanguageModel.GetReadyState()向 stdout 输出Available/NotReady/NotSupported之一并以相应退出码结束0 Available1 NotReady2 NotSupported 或错误。Settings 端读取 stdout 并等待最多 10 秒。由于每次检查都是全新进程瞬时的Unavailable结果不会跨检查缓存。LAF 解锁逻辑在 PhiSilicaLafHelper.cs 中特性 ID 为com.microsoft.windows.ai.languagemodel只缓存成功的解锁结果——失败Unavailable、未知状态、异常往往是瞬时的例如登录前 AI 特性栈尚未初始化、或稀疏身份尚未完全应用到刚启动的进程下次调用时重试即可恢复。LastUnlockStatus属性暴露最近一次解锁状态便于诊断真实的 LAF 结果而不是下游模型调用那句笼统的 Access is denied。源码中还有一个文档未展开的兄弟参数--prepare-phi-silicaProgram.cs它在不启动 WinUI 应用的情况下触发 Phi Silica 模型准备下载通过EnsureReadyAsync()把模型从NotReady推进到Ready退出码为 0 ready、1 准备失败、2 不受支持。注释还说明了一个细节EnsureReadyAsync这类 WinRT 异步操作若从[STAThread]入口点阻塞等待无法正确编组因此代码将其放到线程池线程上执行。延伸资料advancedpaste-phisilica-local-testing.mdPhi Silica 可用性的分层诊断与本地测试/故障排查指南src/PackageIdentity/readme.md稀疏包的完整文档包括构建、签名、注册/注销、CI 指引以及其他组件如何消费稀疏身份的六步流程在AppxManifest.xml中新增Application条目、在 Win32 二进制中嵌入带msix元素的 sparse identity manifest、使用shell:AppsFolder\...激活形式启动等Advanced Paste 的设置界面与 DSC 资源分别见 Settings UI 与 doc/dsc/modules/AdvancedPaste.md 中的说明。适用前提与限制上述调试与稀疏包注册流程面向 Windows 本地开发环境PowerShell Visual Studio / VS Code--check-phi-silica的可用性结果取决于系统 AI 特性栈、硬件与授权状态Phi Silica 相关 API 仅在有 Windows AI 能力的系统上返回Ready其他系统会以NotReady或NotSupported状态呈现属预期行为。【免费下载链接】PowerToysMicrosoft PowerToys is a collection of utilities that supercharge productivity and customization on Windows项目地址: https://gitcode.com/GitHub_Trending/po/PowerToys创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考