前言¶
在 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
