前言¶
在 Windows 上做原生桌面 UI，常见路径是 C# 加 Windows App SDK 与 WinUI 3。官方文档、WinUI Gallery、SDK 示例分散在不同站点；环境要开开发者模式、装 Visual Studio 与工作负载；打包模式（packaged / unpackaged）还会影响 dotnet new 选项和 F5 与命令行跑法。新人容易在「能不能编译」和「窗口是否真的起来」之间卡住。
下面介绍 OpenAI 在 skills 仓库 中维护的 winui-app Skill：把环境引导、脚手架、设计取舍和排错流程写进 Agent 可执行的说明里，让编码助手按任务类型加载对应参考，并在改代码后默认 build 与启动验证。
这是什么¶
winui-app 面向 WinUI 3 与 Windows App SDK 相关工作，提供有依据的安装引导、应用脚手架、现代 Windows UX 决策和具体实现模式。Skill 描述中写明：结合 Microsoft 官方指引、WinUI Gallery 模式、Windows App SDK 示例，以及 CommunityToolkit 组件，用于新建应用、准备机器、评审、重构、规划、排错、环境检查，以及 WinUI 3 XAML、控件、导航、窗口、主题、无障碍、响应式、性能、部署等场景。
出品方为 OpenAI（位于 openai/skills 仓库的 .curated 目录）。在 officialskills.sh 上的简介与之一致：脚手架、开发并维护 WinUI 3 桌面应用，覆盖环境搭建、项目创建、控件、导航、主题、无障碍与部署，并遵循 Microsoft 与 Fluent 设计指引。
核心功能¶
以下能力均来自 Skill 自带的 SKILL.md 与公开说明，不做外延推断。
任务分类与参考加载¶
Agent 先将任务归为：环境/安装、新应用脚手架、设计、实现、评审或排错。随后阅读 references/_sections.md，只加载与当前任务匹配的 reference 文件，避免一次性灌入无关文档。
环境准备与新项目脚手架（Required Flow）¶
当任务是准备 WinUI 机器、审计就绪状态或创建全新应用时，Skill 要求优先走捆绑的 setup-and-scaffold 流程：
- 新应用时确定应用名：用户已给出且可作为安全文件夹名则沿用；未给出则从请求推导短 PascalCase 名称并说明选择。
- 默认在用户当前工作区创建项目（除非指定其他路径）；除非用户明确要求覆盖，不使用
--force。 - 在 Skill 目录下执行 WinGet 配置（相对路径须为
config.yaml）：
winget configure -f config.yaml --accept-configuration-agreements --disable-interactivity
配置意图包括：启用开发者模式，安装或更新 Visual Studio Community 2026，并安装 Managed Desktop、Universal 以及 Windows App SDK 的 C# 组件。执行后根据输出判断是否继续；若 winui 模板已可用且工具链可用，可记录部分失败并继续；若前置条件仍缺失，应明确阻塞项并停止。
- 脚手架前确认模板可用：
dotnet new list winui
- 新建应用使用：
dotnet new winui -o <name>
仅在用户要求时附加模板选项。Skill 列出的支持项包括：-f|--framework net10.0|net9.0|net8.0、-slnx|--use-slnx、-cpm|--central-pkg-mgmt、-mvvm|--use-mvvm、-imt|--include-mvvm-toolkit、-un|--unpackaged、-nsf|--no-solution-file、--force。用户需要打包行为时传 --unpackaged false；否则保持模板默认。
- 验证脚手架：确认预期项目文件存在，对生成的
.csproj执行dotnet build。
仅做环境诊断时，Skill 要求先说明捆绑引导可能改变本机并征得确认；用户拒绝变更时，改用手动核对路径 references/foundation-environment-audit-and-remediation.md，并按 present、missing、uncertain、recommended optional tools 汇总就绪情况。
打包模型¶
创建或重构应用前须明确打包模型：面向 Store 类产品流程与 Visual Studio 部署/F5 时，默认 packaged；用户期望可重复的 CLI 构建运行循环或直接启动 .exe 时，默认 unpackaged。
构建、运行与验证¶
对创建或修改 WinUI 应用的作业，Skill 默认要求：完成最小必要编辑后 build 并运行，再回复用户（即使用户未明确要求验证）。启动验证须看到客观成功信号（例如可响应的顶层窗口、预期窗口标题），仅进程 spawn 不算完成。工作结束且验证通过后，除非用户要求关闭，可保留最终应用实例运行。
排错与设计原则¶
- 遇到不透明的 XAML 编译失败（如
MSB3073、XamlCompiler.exe）时，先读references/foundation-template-first-recovery.md，向当前dotnet new winui脚手架回退对齐，再考虑自定义恢复结构。 - 优先 Microsoft Learn 查需求与 API；控件与外壳细节优先 WinUI Gallery；窗口、生命周期、通知、部署等场景优先 WindowsAppSDK-Samples。
- UI 默认走原生 WinUI 外壳与控件；成组命令面（文档操作、格式化、视图切换、页面工具栏）优先
CommandBar等库存命令面，而非用Grid/StackPanel等拼自定义按钮行。 - 需要定制时，先组合、模板或重样式内置控件与系统资源，再引入 CommunityToolkit 或自写控件；CommunityToolkit 仅在内置能力不足时使用。
- 默认支持浅色与深色主题，使用主题感知资源与系统画刷，避免硬编码单色。
- 集合布局须明确滚动归属；响应式按外壳加页面规划宽/中/窄行为。
常见任务与参考入口¶
| 请求 | 优先阅读 |
|---|---|
| 检查本机能否构建 WinUI | references/foundation-environment-audit-and-remediation.md |
| 安装缺失前置条件 | 同上 |
| 新建 packaged 或 unpackaged 应用 | references/foundation-setup-and-project-selection.md |
| XAML 编译或启动失败且需锚定模板脚手架 | references/foundation-template-first-recovery.md |
| 构建、运行或验证应用行为 | （资料中表格在此截断，完整表见仓库内 SKILL.md） |
安装与启用¶
在支持 Agent Skills 的助手环境中，可通过 skills CLI 从官方仓库安装单个 Skill：
npx skills add https://github.com/openai/skills --skill winui-app
亦可向助手提供目录链接，请求安装：
https://github.com/openai/skills/tree/main/skills/.curated/winui-app
资料未区分 Cursor、Codex CLI、Claude Code 的安装差异；以各产品当前对 Skills 的文档为准。Skill 本体为通用 SKILL.md 格式及同目录下的 config.yaml、references/ 等捆绑文件。
典型用法¶
下列场景来自官方 Skill 描述与 officialskills.sh 的「When to use it」，对应 Agent 在对话中的典型触发方式。
新建 WinUI 3 项目（含打包选择）
说明要桌面应用名称、目标框架（如 net10.0）以及是否需要 unpackaged。Agent 应按 Required Flow 检查环境、dotnet new list winui，再 dotnet new winui -o <name> 及可选参数，最后 dotnet build 并按打包模型启动验证窗口。
审计 Windows 开发机
请求「检查这台 PC 能否编译 WinUI」。若用户同意机器变更，可运行 Skill 目录下的 winget configure；若仅诊断，Agent 应走 foundation-environment-audit-and-remediation.md 的手动核对并输出四类就绪摘要。
主题与命令面
例如「为设置页加浅色深色切换」或「用原生方式做页面顶部操作按钮」。Skill 会约束使用系统画刷与主题资源，并优先 CommandBar 等库存面，而不是默认堆自定义控件库。
从 MSB3073 / XamlCompiler 恢复
描述编译错误关键词。Agent 应先加载 foundation-template-first-recovery.md，将项目结构与当前官方 winui 模板对齐后再做小步修改。
适用场景与注意¶
适合谁
- 已在 Windows 上用 C# 做桌面或准备切入 WinUI 3 的开发者。
- 希望 Agent 按 Microsoft / Fluent 路径选型，而不是每次从零拼文档链接的人。
- 需要环境一键引导（WinGet + VS 工作负载）或严格「改完必跑窗口」验证流程的团队。
限制与注意
- Required Flow 中的
winget configure会改变本机（开发者模式、Visual Studio 等）；纯审计场景须先确认，避免误触。 - Skill 强调不臆造模板 flag、不默认替换库存 WinUI 控件；深度定制需用户明确要求或确有平台缺口。
- 开发与验证默认在 Windows 与对应工具链上进行；Skill 不能替代对 Windows App SDK 版本与目标框架的实际安装状态。
- 捆绑配置写明 Visual Studio Community 2026；若本机策略不同，需以
winget configure输出与实际安装结果为准，不能假设一次配置必然成功。
结尾¶
winui-app 把 WinUI 3 桌面开发里分散的官方资料、环境脚手架、打包取舍和「编译通过但窗口未证」的缺口，收成 Agent 可执行的 Required Flow 与分主题 reference。若你正在用 C# 与 Windows App SDK 做现代 Windows 桌面应用，可从官方目录安装或引用该 Skill：
https://github.com/openai/skills/tree/main/skills/.curated/winui-app
