開始之前
- 安裝 GDK。範例使用 2026 年 10 月 GDK (版本
261000)。請將261000取代為您遊戲建置所使用的版本。 - 使用可連線至 Model Context Protocol (MCP) 伺服器、讀取電腦上的檔案或執行命令的代理程式。大多數程式碼撰寫代理程式這三項都能做到。
- 了解您的組織核准哪些 AI 工具可處理機密內容。GDKX 文件、標頭和工具均屬機密。
選擇要提供給代理程式的 GDK 內容
線上來源說明的是目前的 GDK。當您使用較早的 GDK 建置時,也請將已安裝的標頭和離線文件提供給代理程式,以免它使用您的 GDK 中沒有的 API。
連線 XBOX 文件 MCP 伺服器
位於https://docs.xbox.com/mcp 的 XBOX 文件 MCP 伺服器可讓代理程式搜尋並引用已發佈的文件。它不需要 API 金鑰或登入。例如,在 Visual Studio Code 中,將伺服器新增至專案中的 .vscode/mcp.json 檔案:
.vscode/mcp.json
https://docs.xbox.com/llms.txt會列出每個頁面及其簡短描述。https://docs.xbox.com/llms-full.txt在單一檔案中包含文件全文。- 在任何頁面 URL 結尾加上
.md,即可取得該頁面的 Markdown。
為代理程式提供離線文件
GDKX 會將 GDK 文件以 Markdown 檔案的形式安裝在 GDK 版本xbox\documentation 資料夾中的 GDKDocumentationMarkdown.zip 內。由於這些檔案與您安裝的 GDK 相符,因此是該版本最正確的文件來源。
每個頁面都以 YAML frontmatter 開頭。permissioned-type 值會提供頁面的存取分類:public、private 或 secret。封存檔根目錄的 site-map.md 檔案會列出這些頁面。
-
將封存檔解壓縮至來源存放庫以外的資料夾。在 PowerShell 中,執行下列命令。
-
如果您的 AI 工具未獲核准可處理機密內容,請只保留公開頁面。下列命令會刪除
permissioned-type不是public的每個 Markdown 檔案,包括沒有此欄位的檔案。 - 讓代理程式存取該資料夾。例如,將資料夾新增至編輯器的工作區,或在專案指示檔案中指定它。
將代理程式指向已安裝的標頭和工具
GDK 安裝程式會設定環境變數,讓代理程式得知已安裝 GDK 的位置:GameDK是 GDK 根資料夾。它包含命令列工具的bin資料夾,以及每個已安裝版本的資料夾,例如%GameDK%261000\。GameDKCoreLatest和GameDKXboxLatest指向最新安裝的版本。
%GameDK%261000\) 提供給代理程式,而不是這些變數。
如需每個版本底下的資料夾,請參閱 GDK 標頭和程式庫目錄結構。告訴代理程式在使用 API 之前,先檢查該版本 windows\include 資料夾 (適用於 PC) 或 xbox\include 資料夾 (適用於 XBOX 主機) 底下標頭中的宣告。部分標頭 (例如 XBOX 服務 API (XSAPI)、libHttpClient 和 PlayFab 標頭) 也包含說明每個 API 的文件註解。
%GameDK%bin 中的命令列工具在搭配 /? 執行時,會列印其使用方式。代理程式可以在使用工具之前執行該工具的 /?,而不是猜測其選項。若要將 HRESULT 轉譯為描述,請使用 xberror.exe:
為代理程式提供與版本相符的範例程式碼
使用 XBOX GDK 範例清單尋找您正在實作之功能的範例。查看存放庫和範例的 README,了解 GDK 版本、目錄配置和平台需求。如果 main 分支與您的專案不相符,請選擇相容的範例版本。 複製或下載相容的版本,並將相關範例的原始程式碼和 README 的本機路徑提供給代理程式。要求它遵循範例的初始化、錯誤處理、非同步存留期和清除模式。讓代理程式根據您已安裝的標頭驗證 API,而不是從不同的 GDK 配置複製專案設定。讓代理程式從命令列建置
若要建置,代理程式需要與 Gaming Command Prompt 相同的環境。使用「開始」功能表捷徑所使用的引數執行GamingDesktopVars.cmd,然後在同一個 cmd 處理序中執行建置:
GamingDesktopVS2022。環境不會在個別命令之間延續,因此代理程式必須一起執行指令碼和建置。
新增專案指示檔案
大多數程式碼撰寫代理程式都會讀取存放庫根目錄中的專案指示檔案,例如AGENTS.md 或 .github/copilot-instructions.md。使用它為每個代理程式工作階段提供相同的 GDK 內容。從下列範例開始,並取代角括弧中的值。
AGENTS.md
