winui-setup

用途

安装并验证其他所有 winui-* 技能所依赖的先决条件。WinApp CLI 0.7 通过 winapp new 负责发现和安装 WinUI 模板；请勿单独安装模板包。项目的目标框架可能需要比 CLI 最低要求更新的 .NET SDK。

重要

无需询问即可为当前用户安装先决条件（WinApp CLI），并告知用户进行了哪些更改。凡是需要管理员权限（UAC）或大型工具链的操作，都要先询问——包括 .NET SDK、开发人员模式和 Native AOT 构建工具。Windows Sandbox 的启用由用户自行操作。

此技能具有幂等性：先检测所有项目，只安装或升级必要的内容，并打印一份最终摘要。

步骤

检测所有项目

一起运行这些检查，让用户在发生任何更改前看到完整状态：

$minimumDotNet = [version]'8.0.100'
$minimumWinApp = [version]'0.7.0'

# .NET SDK — project-mode winapp run requires SDK 8.0.100+
$dotnetSdks = @(& dotnet --list-sdks 2>$null) | ForEach-Object {
    $text = ($_ -replace ' \[.*$','').Trim()
    $parsed = $null
    if ([version]::TryParse(($text -split '-')[0], [ref]$parsed)) { $parsed }
}
$dotnetVersion = $dotnetSdks |
    Where-Object { $_ -ge $minimumDotNet } |
    Sort-Object -Descending |
    Select-Object -First 1
$dotnetOk = $null -ne $dotnetVersion

# WinApp CLI — require released 0.7+ for the migrated workflows
$winappCmd = Get-Command winapp -ErrorAction SilentlyContinue
$winappVersion = $null
$winappPrerelease = $false
if ($winappCmd) {
    foreach ($line in @(& winapp --version 2>$null)) {
        $match = [regex]::Match(
            [string]$line,
            '^\s*v?(?<version>\d+\.\d+\.\d+)(?:-(?<prerelease>[0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?\s*$'
        )
        if ($match.Success) {
            $parsed = $null
            if ([version]::TryParse($match.Groups['version'].Value, [ref]$parsed)) {
                $winappVersion = $parsed
                $winappPrerelease = $match.Groups['prerelease'].Success
            }
        }
    }
}
$winappOk = ($winappVersion -ge $minimumWinApp) -and -not $winappPrerelease

# Developer Mode
$devModeOk = ((Get-ItemProperty `
    -Path 'HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\AppModelUnlock' `
    -Name AllowDevelopmentWithoutDevLicense -ErrorAction SilentlyContinue
).AllowDevelopmentWithoutDevLicense) -eq 1

打印一次性的状态表：

.NET SDK >= 8.0.100     [OK] found 10.0.100
WinApp CLI >= 0.7.0     [!] found 0.6.0 — will upgrade
Developer Mode          [X] disabled — needs admin to enable

安装缺少的项目

.NET SDK（先询问）

SDK 安装程序会在整台计算机上安装 SDK，并触发 UAC。**请先询问用户。**用户同意后，如果未检测到版本为 8.0.100 或更高的 SDK，则安装推荐的 SDK：

winget install --id Microsoft.DotNet.SDK.10 --exact --silent --accept-package-agreements --accept-source-agreements

如果已有 SDK 同时满足 CLI 的最低要求以及所请求项目的目标框架 / global.json，则不要安装其他 SDK。CLI 的最低要求并不意味着 8.x SDK 可以构建 net10.0-windows 应用。 如果基本检查已通过，但所请求的项目需要其他 SDK，则报告该要求，并询问用户是否安装对应的 SDK，而不是宣称项目已就绪。如果用户拒绝，则打印供日后使用的命令。

WinApp CLI（无需管理员权限）

WinApp CLI 是当前用户专属的 MSIX 包，因此无需询问即可安装或升级，并告知用户进行了哪些更改。如果缺少 winapp，则安装它。如果其版本低于已发布的 0.7.0，则升级它。如果已安装的版本满足最低要求，则跳过这两项操作：

# When winapp is missing
winget install --id Microsoft.WinAppCli --exact --silent --accept-package-agreements --accept-source-agreements

# When winapp does not meet the released 0.7.0 minimum
winget upgrade --id Microsoft.WinAppCli --exact --silent --accept-package-agreements --accept-source-agreements

任何 winget 安装或升级后，都要刷新 PATH：

$env:Path = [Environment]::GetEnvironmentVariable('Path','Machine') + ';' +
            [Environment]::GetEnvironmentVariable('Path','User')

再次运行版本检测。如果仍无法使用已发布的 0.7.0 或更高版本，则报告实际版本，并将设置标记为受阻；不要回退到旧命令。除非用户要求验证预览版，否则预发行版不符合要求。

开发人员模式（先询问）

开发人员模式需要提升管理员权限。**触发 UAC 前请先询问用户。**仅在用户同意后，才提升权限执行这一项操作：

Start-Process powershell -Verb RunAs -ArgumentList @(
    '-NoProfile','-Command',
    "New-Item -Path 'HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\AppModelUnlock' -Force | Out-Null; " +
    "Set-ItemProperty -Path 'HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\AppModelUnlock' " +
    "-Name AllowDevelopmentWithoutDevLicense -Type DWord -Value 1"
) -Wait

如果用户拒绝或关闭 UAC，则继续输出摘要，并打印供日后使用的命令。

所请求工作流的其他要求

工作流	其他要求
发布/运行 Native AOT	Windows 原生编译器/链接器工具链：Visual Studio 或 Build Tools，包含 使用 C++ 的桌面开发、目标架构所需的工具和 Windows SDK。请参阅 Native AOT prerequisites。正常的 JIT 迭代不需要这些工具。
Windows Sandbox 应用运行和 UI 自动化（条件允许时优先）	WinApp 集成需要 Windows 11 24H2 或更高版本、硬件虚拟化，以及可正常运行的 Windows Sandbox 功能/客户端。支持的版本包括 Pro、Enterprise 和 Education；不包括 Home。输入/捕获需要主机处于解锁状态，且客户端已连接并未最小化。请参阅 WinApp Sandbox prerequisites。

请将这些要求与基础工具链分开报告。winapp target snapshot sandbox --json 会检查现有来宾系统，而不会启动或修复它；仅显示“没有正在运行的目标”并不意味着 Windows 功能不可用。winui-ui-testing 第 1 步说明了 Windows Sandbox 不可用时该怎么做。

启用 Windows Sandbox 是一项用户操作（需要管理员权限并重启）：请用户打开启用或关闭 Windows 功能，选中 Windows Sandbox，并在提示时重启。必须启用硬件虚拟化；虚拟机可能还需要嵌套虚拟化。请参阅 Microsoft 的支持的版本 和安装步骤。

最终摘要

始终打印一份摘要：

==== winui-setup summary ====
.NET SDK >= 8.0.100     [>] already present (10.0.100)
WinApp CLI >= 0.7.0     [OK] upgraded to 0.7.0
Developer Mode          [OK] enabled

仅报告要求已通过的工作流是否就绪。如果当前 harness 提供 winui-dev orchestrator agent， 请启动一个新会话并让该 agent 构建 WinUI 应用。否则， 请在当前 harness 中启动一个新会话并让它执行 WinUI 任务； 它会按需加载相关的 winui-* skills。

例如，对于 GitHub Copilot CLI：

copilot --agent winui:winui-dev -p "build me a WinUI 3 markdown editor"

请勿执行以下操作

• 不要安装 Visual Studio；它是可选的。Native AOT 只需要 MSVC C++ build tools，这是一项单独且须明确批准的设置操作。
• 不要安装或升级用户的 AI 编码 harness；此 skill 只管理 Windows/WinUI 开发前置条件。
• 不要提升整个会话的权限；仅针对获批的特定设置操作请求提升权限。
• 不要在安装失败后悄悄重试。