尋找與探索 Windows 桌面 API。在開發需要平台功能（例如相機、檔案存取、通知、UI 控制項、AI/ML、感測器、網路等）的功能時使用。能為指定任務找出合適的 API，並擷取完整的型別詳細資訊（方法、屬性、事件、列舉值）。
WinMD API Search
這項 Skill 能協助你為任何功能找到合適的 Windows API 并取得其完整詳細資訊。它會搜尋包含下列來源所有 WinMD 元資料（metadata）的本機快取：
- Windows Platform SDK — 所有
Windows.*WinRT API（隨時可用，無需執行還原） - WinAppSDK / WinUI — 已作為基準預先打包於快取產生器中（隨時可用，無需執行還原）
- NuGet 套件 — 已還原專案中任何包含
.winmd檔案的附加套件 - 專案輸出的 WinMD — 建置後會產生
.winmd的類別庫（C++/WinRT、C#）
即使是在剛複製（clone）下來、尚未執行還原或建置的全新專案中，你依然能享有完整的 Platform SDK + WinAppSDK API 涵蓋範圍。
何時使用此 Skill
- 使用者想要開發某項功能，而你需要找出哪一個 API 提供該功能
- 使用者詢問「如何做到 X？」，而 X 涉及平台功能（相機、檔案、通知、感測器、AI 等）
- 在撰寫程式碼之前，你需要特定型別的精確方法、屬性、事件或列舉值
- 你不確定在 UI 或系統工作该使用哪一個控制項、類別或介面
前置需求
- .NET SDK 8.0 或更新版本 — 用於建置快取產生器。若尚未安裝，請至 dotnet.microsoft.com 下載安裝。
快取設定（初次使用前必需）
所有查詢與搜尋命令都是讀取本機的 JSON 快取。在執行任何查詢之前，你必須先建立快取。
# 儲存庫中的所有專案（建議首次執行時使用）
.\.github\skills\winmd-api-search\scripts\Update-WinMdCache.ps1
# 單一專案
.\.github\skills\winmd-api-search\scripts\Update-WinMdCache.ps1 -ProjectDir <project-folder>
若只需要基準涵蓋範圍（Platform SDK + WinAppSDK），無需還原專案或進行建置。若要包含額外的 NuGet 套件，專案需要先執行 dotnet restore（以產生 project.assets.json）或包含 packages.config 檔案。
快取會儲存在 Generated Files\winmd-cache\，並依「套件+版本」進行去重。
索引內容
| 來源 | 可用時機 |
|---|---|
| Windows Platform SDK | 總是可用（直接讀取本機安裝的 SDK） |
| WinAppSDK（最新版） | 總是可用（已作為基準內建於快取產生器） |
| WinAppSDK Runtime | 當系統已安裝時（透過 Get-AppxPackage 偵測） |
| 專案 NuGet 套件 | 執行 dotnet restore 後，或包含 packages.config |
專案輸出的 .winmd |
專案建置後（會產生 WinMD 的類別庫） |
注意： 此快取目錄應加入
.gitignore中——它是自動產生的內容，非原始程式碼。
使用方法
根據你遇到的情境選擇對應的流程：
探索情境 —「我不確定該用哪個 API」
使用者用自己的話描述某項功能，而你需要找到對應的 API。
0. 確保快取已存在
若快取尚未產生，請先執行 Update-WinMdCache.ps1 — 請參閱上方快取設定。
1. 將使用者用語轉換為搜尋關鍵字
將使用者的日常用語對照至程式設計術語，嘗試多種不同的關鍵字組合：
| 使用者說 | 建議嘗試的搜尋關鍵字（按順序） |
|---|---|
| 「拍照」 | camera, capture, photo, MediaCapture |
| 「從磁碟載入」 | file open, picker, FileOpen, StorageFile |
| 「描述圖片內容」 | image description, Vision, Recognition |
| 「顯示快顯視窗/彈窗」 | dialog, flyout, popup, ContentDialog |
| 「拖放」 | drag, drop, DragDrop |
| 「儲存設定」 | settings, ApplicationData, LocalSettings |
先從簡單的日常詞彙開始。如果搜尋結果相關度不高或效果不好，再嘗試更偏技術的詞彙。
2. 執行搜尋
.\.github\skills\winmd-api-search\scripts\Invoke-WinMdQuery.ps1 -Action search -Query "<keyword>"
此命令會回傳排序後的命名空間、最符合的型別，以及 JSON 檔案路徑。
若搜尋結果的 比分過低（低於 60）或不相關，請改為搜尋線上文件：
- 使用 Web 搜尋在 Microsoft Learn 上尋找合適的 API，例如：
- 針對
Windows.*API：site:learn.microsoft.com/uwp/api <功能關鍵字> - 針對
Microsoft.*WinAppSDK API：site:learn.microsoft.com/windows/windows-app-sdk/api/winrt <功能關鍵字>
- 針對
- 閱讀文件頁面以確認哪一個型別符合使用者的需求。
- 一旦得知型別名稱後，返回此處使用
-Action members或-Action enums來取得精確的本機簽章。
3. 讀取 JSON 以選擇合適的 API
讀取最符合結果中的檔案路徑。該 JSON 包含了該命名空間下的所有型別——完整的成員、簽章、參數、回傳型別與列舉值。
研讀內容並判斷哪些型別與成員符合使用者的需求。
4. 查閱官方文件以取得上下文資訊
快取僅包含語法簽章，不包含說明文字或使用指南。若需詳細說明、範例和備註，請在 Microsoft Learn 上查詢該型別：
| 命名空間前綴 | 文件 Base URL |
|---|---|
Windows.* |
https://learn.microsoft.com/uwp/api/{fully.qualified.typename} |
Microsoft.* (WinAppSDK) |
https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/{fully.qualified.typename} |
例如 Microsoft.UI.Xaml.Controls.NavigationView 對應至：
https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.navigationview
5. 運用取得的 API 知識進行回答或撰寫程式碼
查詢情境 —「我知道 API 名稱，請顯示詳細資訊」
若你已知（或推測出）型別或命名空間名稱，可直接查詢：
# 取得已知型別的所有成員
.\.github\skills\winmd-api-search\scripts\Invoke-WinMdQuery.ps1 -Action members -TypeName "Microsoft.UI.Xaml.Controls.NavigationView"
# 取得列舉值
.\.github\skills\winmd-api-search\scripts\Invoke-WinMdQuery.ps1 -Action enums -TypeName "Microsoft.UI.Xaml.Visibility"
# 列出命名空間中的所有型別
.\.github\skills\winmd-api-search\scripts\Invoke-WinMdQuery.ps1 -Action types -Namespace "Microsoft.UI.Xaml.Controls"
# 瀏覽命名空間
.\.github\skills\winmd-api-search\scripts\Invoke-WinMdQuery.ps1 -Action namespaces -Filter "Microsoft.UI"
若你需要超出 -Action members 所顯示的完整細節，請使用 -Action search 取得 JSON 檔案路徑，然後直接讀取該 JSON 檔案。
其他命令
# 列出已建立快取的專案
.\.github\skills\winmd-api-search\scripts\Invoke-WinMdQuery.ps1 -Action projects
# 列出指定專案的套件
.\.github\skills\winmd-api-search\scripts\Invoke-WinMdQuery.ps1 -Action packages
# 顯示統計數據
.\.github\skills\winmd-api-search\scripts\Invoke-WinMdQuery.ps1 -Action stats
若僅有一個專案建立了快取，系統會自動選取
-Project。
若存在多個專案，請加上-Project <name>（可使用-Action projects檢視可用名稱）。
在掃描模式下，清單名稱會包含短雜湊（hash）字尾以避免命名衝突；若無歧義，你可以傳入不帶字尾的基底專案名稱。
搜尋計分機制
搜尋演算法會針對你的查詢字串，對型別名稱與成員名稱進行比分比對與排序：
| 比分 | 比對類型 | 範例 |
|---|---|---|
| 100 | 完全相同 | Button → Button |
| 80 | 開頭符合 | Navigation → NavigationView |
| 60 | 包含字串 | Dialog → ContentDialog |
| 50 | PascalCase 首字母 | ASB → AutoSuggestBox |
| 40 | 多關鍵字 AND 邏輯 | navigation item → NavigationViewItem |
| 20 | 模糊字元比對 | NavVw → NavigationView |
搜尋結果會依命名空間進行分組，得分較高的命名空間會排在前面。
疑難排解
| 問題 | 解法 |
|---|---|
| 「Cache not found」（找不到快取） | 執行 Update-WinMdCache.ps1 |
| 「Multiple projects cached」（存在多個專案快取） | 加上 -Project <name> 參數 |
| 「Namespace not found」（找不到命名空間） | 使用 -Action namespaces 列出所有可用的命名空間 |
| 「Type not found」（找不到型別） | 使用完整修飾名稱（例如 Microsoft.UI.Xaml.Controls.Button） |
| 更新 NuGet 後快取未更新 | 重新執行 Update-WinMdCache.ps1 |
| 快取誤加入 git 歷史紀錄 | 將 Generated Files/ 加入 .gitignore |
參考資料
- Windows Platform SDK API 參考 —
Windows.*命名空間的文件 - Windows App SDK API 參考 —
Microsoft.*WinAppSDK 命名空間的文件
