winui-app Skill 深度指南Agent 驱动的 WinUI 3 桌面应用从环境搭建到启动验证全流程【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills本指南以开源仓库中的winui-appAgent Skill即 SKILL.md为主体讲解如何利用该 Skill 在 Codex 等 AI Agent 中完成 WinUI 3 / Windows App SDK 桌面应用的分类、环境审计、脚手架搭建、构建、启动验证与设计实现。读完本文你将掌握 Skill 内嵌的 WinGet 引导流程、dotnet new winui脚手架参数体系、打包与非打包packaged / unpackaged模型选型以及一套可复用的模板优先故障恢复与客观启动验证方法。一、Skill 定位它解决什么问题winui-app是一个面向 WinUI 3 与 Windows App SDK 开发的 curated精选Agent Skill其元数据定义在 SKILL.md 的 frontmatter 中namewinui-appdescription覆盖创建全新应用、准备 WinUI 开发机器、评审、重构、规划、排障、环境检查以及 WinUI 3 XAML、控件、导航、窗口、主题、无障碍、响应式、性能、部署等全部相关设计开发工作且以 Microsoft 官方指引、WinUI Gallery 模式、Windows App SDK 示例与 CommunityToolkit 组件为事实依据。该 Skill 的核心理念是先验证、再动手不猜测机器是否就绪而是通过内置的 WinGet 引导配置与手动审计命令逐项核实不凭空发明工程结构而是始终锚定官方dotnet new winui模板脚手架不以进程被拉起作为成功标志而是要求确认真实的顶层窗口与客观启动信号。Skill 目录中还通过 agents/openai.yaml 暴露为可发现的 Agent 接口显示名WinUI App、默认提示词 Create a new $winui-app desktop app for me.属于写一次、处处可用的 Agent 技能封装。二、必需工作流Required Flow从任务分类到启动验证SKILL.md 将整个工作流划分为 12 条必需步骤核心脉络如下。2.1 先分类再决定走哪条路任务必须首先归类为六类之一环境/搭建environment/setup、新应用引导new-app bootstrap、设计design、实现implementation、评审review、排障troubleshooting。分类决定了后续是进入 Skill 内置的 setup-and-scaffold 流程还是直接读取对应参考文档。2.2 新应用命名与目录约定当任务是创建全新应用时按以下规则确定名称与位置用户已给出且可作为安全文件夹名的名称原样采用用户未给名称时从请求中推导一个简短 PascalCase 名称并向用户说明所选名称项目默认创建在用户当前工作区中除非用户指定其他位置默认不使用--force除非用户明确要求覆盖已有文件。2.3 用内置 WinGet 配置完成环境引导Skill 将机器就绪检查与依赖安装收敛为一个幂等的 WinGet 配置即技能目录下的config.yaml。因为命令在 Skill 目录内执行相对路径恒为config.yamlwinget configure -f config.yaml --accept-configuration-agreements --disable-interactivity这条命令的意图是开启开发者模式Developer Mode、安装或更新 Visual Studio Community 2026并安装 WinUI 开发所需的 Managed Desktop、Universal 与 Windows App SDK C# 组件。执行后的评估策略对应 SKILL.md成功继续后续流程失败检查输出而非猜测若winui模板已可用且工具链可用则记录部分失败并继续若必备前置条件仍缺失停止并明确报告阻塞点。2.4 验证模板可用性脚手架之前必须确认模板存在dotnet new list winui在 foundation-environment-audit-and-remediation.md 中这一步也被列为手动非破坏性审计的核心检查项之一与dotnet --list-sdks、Visual Studio 存在性与版本、Windows SDK 存在性、MSBuild 可用性并列。2.5 仅诊断场景的确认义务若任务只要求环境诊断Skill 要求向用户说明内置引导流程可能会修改机器获得确认后才运行。若用户拒绝改动则改用 foundation-environment-audit-and-remediation.md 中的手动审计指引并按四个标题汇报就绪度present已具备、missing缺失、uncertain不确定、recommended optional tools推荐的可选工具其中不确定项必须如实标注不能暗示成功。2.6 脚手架命令与全部支持选项创建全新应用使用官方模板dotnet new winui -o nameSkill 明确支持的模板选项如下不得发明模板不支持的旗标选项说明-f\|--framework net10.0\|net9.0\|net8.0目标 .NET 框架版本-slnx\|--use-slnx是否使用.slnx解决方案格式-cpm\|--central-pkg-mgmt启用集中包管理Central Package Management-mvvm\|--use-mvvm是否引入 MVVM 结构-imt\|--include-mvvm-toolkit是否包含 MVVM Toolkit-un\|--unpackaged是否为非打包unpackaged应用-nsf\|--no-solution-file是否跳过解决方案文件--force覆盖已有文件需用户明确要求若用户要求打包packaged行为则显式传--unpackaged false否则保持模板默认值。新脚手架的验证闭环对应 SKILL.md确认预期的项目文件.csproj存在对生成的.csproj执行dotnet build按实际打包模型对应的正确路径启动应用并确认出现真实的顶层窗口——不能仅依赖启动器进程的退出码。2.7 启动验证的最低标准Skill 将启动验证视为不完整的直到出现客观成功信号可响应的顶层窗口、预期的窗口标题或其他清晰的启动行为。仅产生了进程不算数。工作完成且启动验证通过后应保留最终验证过的应用实例运行给用户查看除非用户明确要求不运行。2.8 模板优先恢复Template-First Recovery遇到不透明的 XAML 编译器错误如MSB3073、XamlCompiler.exe时不要急于发明自定义恢复结构而应读取 foundation-template-first-recovery.md先回到所选打包模型下的当前dotnet new winui脚手架形态再做增量恢复。三、config.yaml 逐项拆解WinGet 引导配置的底层原理config.yaml 是 Skill 目录中唯一的引导配置文件被 SKILL.md 明确视为内置引导的事实来源source of truth。它基于 WinGet 配置DSCschema 0.2 编写结构如下对应 config.yaml 的properties段1. 系统断言assertions—— OS 版本底线assertions: - resource: Microsoft.Windows.Developer/OsVersion directives: description: Verify min OS version requirement allowPrerelease: true settings: MinVersion: 10.0.17763对应 foundation-setup-and-project-selection.md 中的基线Windows 10 版本 1809build 17763或更高是底线。若系统版本低于此值引导流程直接失败且升级 Windows 是前置条件——引导命令不能替代 OS 要求见 foundation-environment-audit-and-remediation.md 的 Remediation Strategy。2. 开启开发者模式resources: - resource: Microsoft.Windows.Settings/WindowsSettings directives: description: Enable Developer Mode securityContext: elevated allowPrerelease: true settings: DeveloperMode: true需要提权securityContext: elevated执行。参考文档同时提醒开发者模式不是每个任务的硬性要求它主要服务于本地部署与调试deploy debug流程属于通常可选但常被推荐项。3. 安装 Visual Studio Community 2026- resource: Microsoft.WinGet.DSC/WinGetPackage id: Visual Studio directives: description: Install Visual Studio Community 2026 securityContext: elevated settings: id: Microsoft.VisualStudio.Community source: winget通过 WinGet 源安装Microsoft.VisualStudio.Community包被后续工作负载资源以dependsOn方式依赖。4. 安装 WinUI / Windows App SDK 工作负载- resource: Microsoft.VisualStudio.DSC/VSComponents id: Workloads ManagedDesktop dependsOn: - Visual Studio directives: description: Install required VS workloads (ManagedDesktop, Windows App SDK) allowPrerelease: true securityContext: elevated settings: productId: Microsoft.VisualStudio.Product.Community channelId: VisualStudio.18.Release components: - Microsoft.VisualStudio.Workload.ManagedDesktop - Microsoft.VisualStudio.Workload.Universal - Microsoft.VisualStudio.ComponentGroup.WindowsAppSDK.Cs三个组件分别对应 SKILL.md 中描述的 Managed Desktop、Universal 与 Windows App SDK C# 组件其中ComponentGroup.WindowsAppSDK.Cs提供 WinUI 3 的 C# 支持。整体配置版本号为configurationVersion: 0.2.0。补充基线事实来自 foundation-environment-audit-and-remediation.mdC# 常规 WinUI 3 开发必需项受支持的 Windows 版本、带 WinUI C# 支持的 Visual Studio、Windows SDK 10.0.19041 或更高、可用的 MSBuild用于 XAML 编译、.NET SDK 6 或更高通常可选但常推荐开发者模式、WinGet一键修复、Hot Reload / Live Visual Tree 等 VS 调试功能若config.yaml缺失必须明确说明并回退到官方 Microsoft 工作流不得假装内置路径存在见 SKILL.md。四、常见任务路线Common Routes一张表找到正确参考SKILL.md 提供了一张请求 → 首选文档映射表是使用该 Skill 的快速索引完整继承如下请求首选参考检查这台 PC 能否构建 WinUI 应用references/foundation-environment-audit-and-remediation.md安装缺失的 WinUI 前置条件references/foundation-environment-audit-and-remediation.md启动新的打包或非打包应用references/foundation-setup-and-project-selection.md在不透明 XAML 编译/启动失败中恢复并锚定模板脚手架references/foundation-template-first-recovery.md构建、运行或验证 WinUI 应用是否真正启动references/build-run-and-launch-verification.md评审应用结构、页面、资源与绑定references/foundation-winui-app-structure.md选择 Shell、导航、标题栏或多窗口模式references/shell-navigation-and-windowing.md选择控件或响应式布局模式references/controls-layout-and-adaptive-ui.md应用 Mica、主题、排版、图标或 Fluent 样式references/styling-theming-materials-and-icons.md改善无障碍、键盘支持或本地化references/accessibility-input-and-localization.md诊断响应式或 UI 线程性能问题references/performance-diagnostics-and-responsiveness.md决定是否使用 CommunityToolkitreferences/community-toolkit-controls-and-helpers.md处理生命周期、通知或部署references/windows-app-sdk-lifecycle-notifications-and-deployment.md执行评审清单references/testing-debugging-and-review-checklists.md这些参考文件的窄选一索引集中在 references/_sections.md按 Foundations / Shell / Controls / Styling / Accessibility / Performance / SDK Scenarios / CommunityToolkit / Testing 九大分区编排并为每个文件标注了优先级CRITICAL / HIGH / MEDIUM与权威来源。Skill 要求先读_sections.md再只加载与任务匹配的最窄参考文件。五、环境规则Environment RulesAgent 的行为底线SKILL.md 定义了一组硬性环境规则可归纳为四条主线不猜测只验证机器是否就绪必须核实不确定的环境信号如实标为 uncertain而非成功不越权引导全新搭建、修复与首次脚手架必须使用本 Skill 内置的 setup-and-scaffold 流程不委托给其他 Skillconfig.yaml是唯一引导事实来源三件事分开检查环境就绪度、打包模型选择、应用启动验证互不证明对模糊的启动结果关门失败fail closed——应用没有明确打开就继续调试善始善终创建或修改 WinUI 应用后不止步于构建成功必须启动应用、确认客观启动行为并在把控制权交还用户前保留验证过的运行实例。六、参考规则Reference Rules与打包模型选型SKILL.md 的 Reference Rules 奠定了所有实现的基调C# 为主路径仅在差异关键时提及 C / C/WinRT尊重既有代码库约定不强行套用通用示例结构原生 WinUI 为基线不漂移进定制组件体系或应用专属替代控件除非用户明确要求、现有设计系统已要求、或存在已验证的平台空白深浅色模式默认双支持单主题输出属于例外须有明确用户请求或产品约束优先内建控件与系统样式钩子其次才是 CommunityToolkit 依赖、自定义控件或应用专属表面体系。6.1 打包 vs 非打包必须在写代码前定案foundation-setup-and-project-selection.md 给出明确的选型矩阵选打包packaged面向 Store 类产品流程、Visual Studio 部署 / F5 流程应用在正常运行期需要**包标识package identity**或包支持的 API这也是最平滑的首个项目、部署与 Store 兼容路径的默认项选非打包unpackaged用户期望可重复的 CLI 构建-运行循环、每次改动后直接启动.exe、或需要对接既有安装器与外部目录应通过脚手架选项申请而不是事后转换初始项目无论哪种模型都先通过 setup 流程脚手架从生成的项目继续而不是拷贝预置基线文件若启动或共享资源后续可疑用同打包模型新建一个对比应用与dotnet new winui输出做 diff。6.2 打包模型的技术后果build-run-and-launch-verification.md 与 windows-app-sdk-lifecycle-notifications-and-deployment.md 强调了两点关键差异打包应用可依赖包标识与包支持存储如Windows.Storage.ApplicationData.Current非打包应用不得假设包标识存在——ApplicationData.Current这类 API 在非打包运行中即使构建成功也可能运行失败必须守卫或替换同时要处理 bootstrapper 与运行时初始化要求启动路径必须匹配部署模型打包本地开发通常走 Visual Studio 部署或包感知流程非打包本地开发通常直接运行构建产物。七、纵深参考库十五个参考文件的工程价值7.1 环境审计与修复CRITICALfoundation-environment-audit-and-remediation.md 定义了手动非破坏性审计的覆盖范围OS 版本与构建号底线与任务相关的开发者模式状态dotnet --list-sdksdotnet new list winuiVisual Studio 存在性与版本Windows SDK 存在性用于 XAML 编译的 MSBuild 可用性。修复策略按结果分级缺必备前置 → 经确认后走内置引导引导部分失败但工具链可用 → 记录并继续引导失败且前置仍缺 → 停止并报告阻塞点OS 版本不支持 → 先升级 Windows开发者模式关闭 → 说明当前任务是否需要需要则走内置流程或让用户手动开启。7.2 模板优先恢复CRITICALfoundation-template-first-recovery.md 提供了一条可执行的恢复回路确认打包模型与启动路径若启动形态不明用同打包选择脚手架一个临时对比应用dotnet new winui -n RecoveryReference -o RecoveryReference --use-slnx false --no-solution-file false # 目标应用为非打包时追加 --unpackaged true仅对启动与共享资源区域做 diffApp.xaml、App.xaml.cs、MainWindow.xaml(.cs)或实际 Shell 入口、合并资源字典、启动相关项目属性把可疑区域回退到模板形态直到干净构建为具体架构显式构建dotnet build MyApp.sln -c Debug -p:Platformx64用正确路径启动并确认客观启动信号小切片重放自定义改动每次有意义的编辑后都构建并运行。常见检查还包括WinUI 3 启动代码中不得使用Window.Current应显式new Window()确认x:Class、命名空间与 code-behind 名称匹配合并资源字典能干净加载项目内容项与运行时依赖的本地数据/资源文件匹配诊断看似过期时先做一次干净构建。7.3 构建、运行与启动验证CRITICALbuild-run-and-launch-verification.md 的要点明确真实构建目标解决方案/项目文件、配置、平台、打包模型每次有意义编辑后构建任务完成时再构建一次启动验证的客观证据非零主窗口句柄、预期窗口标题、带可见 Shell 的可响应进程、无立即启动异常或崩溃对AnyCPU产生歧义时本地验证优先用x64非打包验证优先启动bin\Debug\...\win-x64\下或项目特定输出路径构建的.exedotnet run抛出 bootstrapper、部署或 COM 激活错误时视为当前启动路径或打包设置与该应用不匹配的信号重建前先停止可能锁定输出文件的旧应用实例启动失败调试时先分离环境问题与应用代码启动崩溃检查顺序为App.xaml→ 合并资源字典 → 转换器 →MainWindow→ 启动期使用的服务。7.4 应用结构HIGHfoundation-winui-app-structure.md 推荐的 C# 优先目录切分App.xaml/App.xaml.cs全局资源、启动、窗口创建、应用级异常MainWindow.xaml/MainWindow.xaml.csShell、标题栏、顶层导航宿主Pages/页面视图与页面逻辑Controls/可复用 WinUI 用户控件ViewModels/状态与命令当应用确实受益于分离时Styles/资源字典、主题令牌、共享控件样式Helpers/或Services/窗口化、导航、持久化、OS 集成辅助。绑定指引页面局部属性、事件处理器与强类型 ViewModel 访问优先x:Bind数据上下文动态或模板需保持灵活时用Binding避免依赖模糊页面生命周期的绑定模式。7.5 Shell、导航与窗口化HIGHshell-navigation-and-windowing.md 的核心建议标准桌面 Shell 优先NavigationView保持小而稳定的顶级目的地集合不把每个命令都塞进导航面导航模式选择多个稳定顶级目的地用左侧导航同级目的地少且宽度充足用顶部导航导航浅、用户主要停留单一工作流时用单页/文档优先布局窄宽度下停止为桌面导航预留固定 pane 宽度改用最小或 overlay 模式、需要时显示 pane 切换、导航后默认关闭 pane标题栏首先是功能件再是品牌面保持非交互空区可拖拽、视觉与应用融合、尊重浅/深/高对比状态窗口化从单主窗口开始仅对文档脱离、检查面板、工具窗等流程添加辅助窗口并优先用 Windows App SDK 窗口化示例而非自造平台抽象。7.6 控件、布局与自适应 UIHIGHcontrols-layout-and-adaptive-ui.md 的关键决策规则命令面优先CommandBar文档操作、格式编辑、视图切换、页面级工具栏等分组命令面先于自造的Grid/StackPanel/Border按钮组合二级操作走其 overflow 模型大集合与滚动所有权GridView只在它拥有集合表面且滚动行为是预期体验时使用竖直滚动页面内的横向海报轨道优先横向ScrollViewer 水平面板的ItemsControl/ItemsRepeater而非嵌套GridView布局自定义且性能敏感时考虑ItemsRepeater标准控件清单TextBox、NumberBox、ComboBox、ListView、GridView、ContentDialog、InfoBar、TeachingTip、TabView、NavigationView对话框与瞬时指引模态决策用ContentDialog持续状态用InfoBar情境引导用TeachingTip自适应布局以有效像素设计而非固定设备假设显式定义断点意图轨道何时变堆叠列表、footer 何时丢弃非必要控件、页面何时从桌面画布变单列手机布局宽度收缩时优先简化/隐藏/移入 Shell 手势而不是处处压缩为桌面横向轨道提供手机宽度的垂直堆叠替代而不是到处裁剪依赖横向滚动不要用额外Border包裹已被卡片、间距、页头自然分组的列表/卡片组避免卡片套卡片。7.7 样式、主题、材料与图标HIGHstyling-theming-materials-and-icons.md 的要点用主题资源与系统画刷而非硬编码颜色居中化画刷、排版与圆角/间距决策到共享资源字典表面系统优先系统资源CardBackgroundFillColorDefaultBrush、CardStrokeColorDefaultBrush、LayerFillColorDefaultBrush材料按表面寿命选Mica 用于主窗口背景、标题栏区等长寿命表面Acrylic 用于 flyout、菜单等瞬时/轻关闭表面在旧版 Windows 或不支持场景验证回退行为排版用 Segoe UI Variable 或平台默认用排版建立层级而非堆边框图标保持 Fluent 一致性与视觉重量一致元数据视觉容器优先小圆角矩形/低调徽章而非亮色椭圆胶囊默认支持浅色、深色与高对比。7.8 无障碍、输入与本地化HIGHaccessibility-input-and-localization.md 的验收标准纯键盘用户能完成主流程图标独占交互必须有无障碍命名避免焦点陷阱、隐藏 Tab 停止位与键盘死胡同XAML / code-behind 中不得硬编码字符串阻塞本地化布局须容忍字符串增长保留可见焦点与逻辑 Tab 顺序菜单、flyout、对话框同时用键盘与鼠标验证尊重文本缩放、对比度变化与 RTL鼠标与触控硬件上都保持可用触控目标与间距。7.9 性能、诊断与响应性HIGHperformance-diagnostics-and-responsiveness.md 的原则UI 线程只做布局、渲染与输入昂贵 I/O 或 CPU 工作不放在 UI 线程大列表用虚拟化友好的控件与布局视觉树保持最简用 WPR WPA 配合XAML Frame Analysis插件做逐帧调查把慢帧结论当作 UI 线程过载的线索而不是盲目微优化的理由性能问题不明显时先测量再优化禁止无剖析就声称定位了性能原因。7.10 Windows App SDK 生命周期、通知与部署HIGHwindows-app-sdk-lifecycle-notifications-and-deployment.md 的规则生命周期/激活/实例化/重启/状态通知场景先从 WindowsAppSDK-Samples 的Samples/AppLifecycle学习再设计抽象通知先看Samples/Notifications不要自造投递逻辑打包应用注意框架依赖部署与运行时包要求非打包应用注意 bootstrapper 与运行时初始化非打包应用默认视包标识为缺失存储、设置与启动服务必须与部署模型对齐否则在非打包本地验证前先重新设计给出构建/发布步骤前先讲清部署模型。7.11 CommunityToolkit 取舍MEDIUMcommunity-toolkit-controls-and-helpers.md 给出的判定框架平台控件优先仅在明确缺口时做定向包增补良好的候选区SettingsControls设置面/卡片、Segmented分段选择比 Tab/单选簇更清晰时、HeaderedControls带标签的分组控件、Animations内建过渡不够时、以及能干净减少重复 WinUI 管线的 helpers/extensions只加最小必要包集并记录为何添加该依赖、拒绝了哪种内建替代禁止为轻微视觉差异拉入多个 Toolkit 包禁止用新依赖掩盖根本 UX 问题。7.12 动效、动画与打磨MEDIUMmotion-animations-and-polish.md 的原则动效用于澄清层级、连续性与状态变化优先主题过渡、连接动画与平台内建行为其次才是自定义动画系统动画短小且服务于任务禁止装饰性动画拖延交互、禁止同一状态变化叠加多个动画、禁止动画遮蔽焦点/选择/无障碍状态。7.13 测试、调试与评审清单HIGHtesting-debugging-and-review-checklists.md 提供四组可执行清单设计评审Shell/导航简单可预测NavigationView仍像标准 WinUI Shell 件布局在多个断点含真实手机宽度可用混合滚动区集合页在运行时验证轨道方向浅/深色与高对比下主题、层级、交互态可见命令放置与层级清晰窄宽下非必要控件简化/隐藏/移入 Shell 手势而非仅压缩代码评审结构连贯可扩展资源字典与样式居中化平台控件优先新依赖有依据打包模型与启动/存储/启动代码匹配从用户实际使用的工作流能干净构建无障碍键盘全流程、焦点可见、自动化属性齐备、高对比与文本缩放不破坏 UI性能交互路径无 UI 线程阻塞、大集合控件与布局恰当、滚动所有权有意识、样式/模板选择有依据、非显然的性能声明有剖析数据。调试工具Hot Reload快速视觉迭代、Live Visual Tree 与 Live Property Explorer布局与属性调试、WPR/WPA帧/响应性问题集合页看起来不对时先检查活树里的嵌套ScrollViewer所有权再重写 ItemTemplate进程在窗口出现前死亡时用启动异常细节、调试器输出或事件查看器。7.14 示例源码映射表MEDIUMsample-source-map.md 提供了任务 → 首选来源 → 备份来源的快速映射其来源偏好次序也是本 Skill 全局的证据层级需求与行为规范先看 Microsoft Learn 文档具体控件用法与 Shell 组合先看 WinUI Gallery场景级 API 与平台集成先看 WindowsAppSDK-Samples只有任务明确需要 Toolkit 功能时才看 CommunityToolkit。八、使用该 Skill 的交付纪律与验收标准综合 SKILL.md 与各参考文件的 Exit Criteria一次合格的 WinUI 交付应同时满足构建成功从用户实际使用的本地工作流含明确平台目标如-p:Platformx64干净构建真实启动从匹配部署模型的路径启动且确认真实顶层窗口或等价预期 UI无未解决的启动异常打包模型一致启动、存储、通知、激活与启动代码均与所选 packaged / unpackaged 模型一致结构锚定模板应用仍根植于dotnet new winui脚手架而非替代基线 Shell主题与无障碍浅色、深色、高对比均正确主流程键盘可达宽/中/手机宽度均已验证性能有据UI 线程无阻塞大集合控件恰当滚动所有权明确非显然性能结论有剖析支撑改动最小且完整对创建或修改的应用做完整但最小的编辑集构建、启动验证通过后把最终验证过的实例留给用户。这套纪律的核心价值在于把机器就绪、打包模型、启动验证三个本会互相掩盖的环节拆开检查用官方模板作为一切恢复与重构的锚点从而让 AI Agent 产出的 WinUI 3 应用可构建、可启动、可交付。【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考