在 Windows 上用 WinUI 3 和…

在 Windows 上使用 C#、WinUI 3 和 Windows App SDK 新建、审查、重构、排障或验证现代桌面应用时，按官方模板和可验证启动流程推进。

适用场景

解决思路

1. 将任务分类为环境/安装、新应用脚手架、设计、实现、评审或故障排除。
2. 如果任务是为 WinUI 准备机器、审计就绪状态或创建全新应用，先执行本技能内置的安装与脚手架流程，再开展更广泛的设计、实现或排障。
3. 如果是新应用请求，先选择应用名。
4. 如果用户已给出且名称是安全文件夹名，直接使用该名称。
5. 如果用户未给名称，从请求中派生一个简短的 PascalCase 名称，并说明你选择了什么。
6. 除非用户要求其他位置，把项目创建在用户当前工作区。
7. 除非用户明确要求覆盖现有文件，否则不要使用 `--force`。
8. 在技能目录中运行内置 WinGet 配置，确保相对路径正好是 `config.yaml`：`winget configure -f config.yaml --accept-configuration-agreements --disable-interactivity`。
9. 将该配置视为用于启用开发者模式、安装或更新 Visual Studio Community 2026、安装 WinUI 开发所需的 Managed Desktop、Universal 和 Windows App SDK C# 组件。
10. 继续前评估配置结果；成功则继续；失败则检查输出而不是猜测；如果 `winui` 模板已可用且工具链可用，记录部分失败并继续；如果前置条件仍缺失，停止并清楚报告阻塞项。
11. 脚手架前验证模板可用：`dotnet new list winui`。
12. 对于仅诊断环境请求，先解释内置 bootstrap 可能更改机器，并在运行前获得确认；如果用户拒绝更改，使用 `references/foundation-environment-audit-and-remediation.md` 中的手动验证指导，并按 `present`、`missing`、`uncertain`、`recommended optional tools` 总结就绪状态。
13. 对于全新应用，用 `dotnet new winui -o <name>` 脚手架；仅当用户要求时添加模板选项；支持选项：`-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`，否则保留模板默认值。
14. 通过确认预期项目文件存在并对生成的 `.csproj` 运行 `dotnet build` 来验证新脚手架。
15. 通过其实际打包模型的正确路径启动新脚手架应用，并确认真实的顶级窗口，而不是只依赖启动器进程退出码。
16. 读取 `references/_sections.md`，然后只加载与任务匹配的参考文件。
17. 在创建或重构应用前明确打包模型；对类似 Store 的产品工作流和 Visual Studio 部署/F5 流程默认使用 packaged；当用户期望可重复的 CLI 构建运行循环或每次更改后直接启动 `.exe` 时默认使用 unpackaged。
18. 当出现不透明的 XAML 编译器失败（如 `MSB3073` 或 `XamlCompiler.exe`）时，读取 `references/foundation-template-first-recovery.md`，并先简化回所选打包模型当前的 `dotnet new winui` 脚手架，再发明自定义恢复结构。
19. 对任何创建或更改 WinUI 应用的工作，先做完整但最小的编辑集，然后在回复用户前构建并运行应用；即使用户未明确要求验证也默认这样做；如果运行中的应用实例在还有工作时锁住输出，停止它、重新构建、重新启动并继续验证；工作完成且启动验证成功后，保留最终已验证的应用实例运行，除非用户明确要求不要。
20. 启动验证在应用显示客观成功信号（如可响应的顶级窗口、预期窗口标题或其他明确启动行为）前视为未完成；仅有衍生的进程不够。
21. 对于需求、API 预期和平台指导，优先使用 Microsoft Learn。
22. 对于具体控件用法、外壳组合和设计细节，优先使用 WinUI Gallery。
23. 对于场景级 API（如窗口化、生命周期、通知、部署和自定义控件），优先使用 WindowsAppSDK-Samples。
24. 优先按 WinUI 和 Fluent 指导构建；将原生 WinUI 外壳、控件、交互和控件 chrome 作为默认实现路径。
25. 对于分组命令界面（如文档操作、编辑器格式、视图切换或页面级工具栏），优先使用原生 `CommandBar` 或其他现成 WinUI 命令界面，再考虑用 `Grid`、`StackPanel`、`Border` 或临时按钮分组构建自定义行。
26. 不要发明应用专用控件、定制组件库或自定义 chrome 来替代现成 WinUI 行为，除非用户明确要求该定制、现有产品设计系统已要求，或已验证平台缺口没有干净的原生选项。
27. 当需要定制时，先组合、模板化或重新样式化内置 WinUI 控件和系统资源，再添加 CommunityToolkit 依赖或编写新自定义控件。
28. 仅当内置 WinUI 控件或辅助程序无法干净覆盖需求时，才使用 CommunityToolkit。
29. 默认支持浅色和深色模式；将单主题输出视为例外，需要用户明确要求或现有产品约束。
30. 在构建或修改 UI 时，使用主题感知资源、系统画笔和 WinUI 样式挂钩，而不是硬编码仅浅色或仅深色颜色。
31. 对集合布局明确滚动所有权；当页面已经垂直滚动时，不要假设嵌套的 `GridView` 或其他拥有滚动的集合仍能正确渲染水平海报轨道。
32. 不要为分区、列表或卡片添加额外 `Border` 包装，除非该边框执行包含控件或父表面尚未提供的独特工作；避免「双卡片」组合，即分区 `Border` 包裹已经渲染为卡片的子项。
33. 将响应式视为外壳加页面的问题，而不只是控件缩放问题；为导航、内边距、内容密度和页脚/工具区域规划明确的宽、中、手机宽度行为，并随着宽度缩小简化或隐藏非必要 UI。
34. 检查此 PC 是否能构建 WinUI 应用时，先读取 `references/foundation-environment-audit-and-remediation.md`。
35. 安装缺失的 WinUI 前置条件时，先读取 `references/foundation-environment-audit-and-remediation.md`。
36. 启动新的 packaged 或 unpackaged 应用时，先读取 `references/foundation-setup-and-project-selection.md`。
37. 从 opaque XAML 编译器或启动失败恢复且保持锚定在模板脚手架时，先读取 `references/foundation-template-first-recovery.md`。
38. 构建、运行或验证 WinUI 应用确实启动时，先读取 `references/build-run-and-launch-verification.md`。
39. 评审应用结构、页面、资源和绑定时，先读取 `references/foundation-winui-app-structure.md`。
40. 选择外壳、导航、标题栏或多窗口模式时，先读取 `references/shell-navigation-and-windowing.md`。
41. 选择控件或响应式布局模式时，先读取 `references/controls-layout-and-adaptive-ui.md`。
42. 应用 Mica、主题、排版、图标或 Fluent 样式时，先读取 `references/styling-theming-materials-and-icons.md`。
43. 改善可访问性、键盘操作或本地化时，先读取 `references/accessibility-input-and-localization.md`。
44. 诊断响应式或 UI 线程性能时，先读取 `references/performance-diagnostics-and-responsiveness.md`。
45. 决定是否使用 CommunityToolkit 时，先读取 `references/community-toolkit-controls-and-helpers.md`。
46. 处理生命周期、通知或部署时，先读取 `references/windows-app-sdk-lifecycle-notifications-and-deployment.md`。
47. 运行评审清单时，先读取 `references/testing-debugging-and-review-checklists.md`。
48. 不要猜测机器是否已准备好进行 WinUI 开发；要验证。
49. 对于全新安装、修复和首次项目脚手架，使用本技能内置的安装与脚手架流程，而不是委托给另一个技能。
50. 将本技能目录中的 `config.yaml` 视为内置 bootstrap 的事实来源。
51. 将不确定的环境信号视为不确定，而不是成功。
52. 如果任务仅做审计且用户拒绝机器更改，使用 `references/foundation-environment-audit-and-remediation.md` 中的手动验证指导，并保持不确定信号明确，而不是暗示成功。
53. 如果 `config.yaml` 缺失，清楚说明，并回退到官方 Microsoft 工作流，而不是假装内置路径存在。
54. 将环境就绪状态、打包选择和应用启动验证保持为独立检查；通过其中一项不能证明其他项。
55. 对模糊的启动结果采取失败关闭策略；如果应用没有清楚打开，继续调试。
56. 创建或编辑 WinUI 应用后，不要停在构建成功；启动应用、确认客观启动行为，并在把控制权交回用户前保留最终已验证的应用实例运行，除非用户明确说不要运行。
57. 保持 C# 为主路径；仅当差异重要时才提及 C++ 或 C++/WinRT。
58. 保留现有代码库的约定，而不是把通用示例结构强加到它上面。
59. 将 WinUI 设计指导和原生控件视为基线；不要漂移到定制组件系统或应用专用替代标准控件，除非用户明确要求或现有代码库已依赖它们。
60. 默认支持浅色和深色模式进行应用 UI 工作，除非用户明确要求单主题结果或产品已强制单主题。
61. 在添加 CommunityToolkit 依赖、自定义控件或应用专用表面系统前，优先使用内置 WinUI 控件和系统样式挂钩。
62. 将详细控件、主题、外壳、滚动、响应式、打包和恢复指导放在匹配的参考文件中，而不是在此处重复这些规则。

适用边界 · 注意事项

• 非 Windows 或非 WinUI 3 / Windows App SDK 的桌面应用开发，不要套用此技能。
• 只做只读审计且用户拒绝机器变更时，不应直接运行会改环境的 bundled bootstrap。
• 用户明确不要运行应用、不要使用原生 WinUI 控件或不要定制主题时，不要强行套用默认实现与启动验证流程。