跳轉到主要內容
當 AI 程式碼撰寫代理程式 (例如 GitHub Copilot、Claude Code、Codex 和 Cursor) 依據您用來建置的 GDK 所提供的 API 和文件運作,而不是依賴其模型的記憶時,就能撰寫出更好的 GDK 程式碼。本文說明您可以提供給代理程式的 GDK 內容,以及如何設定每個來源。 本指引適用於 Windows PC 開發電腦上的 Microsoft Game Development Kit (GDK) 和 Microsoft GDK with XBOX Extensions (GDKX)。

開始之前

  • 安裝 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
如需 Claude Code、GitHub Copilot CLI、Cursor、Codex 和 Claude 的設定步驟,請參閱首頁上的搭配 AI 工具使用這些文件。 無法使用 MCP 的代理程式可以讀取其他格式的文件:
  • 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 檔案會列出這些頁面。
封存檔包含機密頁面。請只搭配您的組織核准可處理機密 GDKX 內容的 AI 工具使用完整封存檔。請勿將解壓縮的檔案新增至公用存放庫,或組織外部人員可讀取的任何位置。
  1. 將封存檔解壓縮至來源存放庫以外的資料夾。在 PowerShell 中,執行下列命令。
  2. 如果您的 AI 工具未獲核准可處理機密內容,請只保留公開頁面。下列命令會刪除 permissioned-type 不是 public 的每個 Markdown 檔案,包括沒有此欄位的檔案。
  3. 讓代理程式存取該資料夾。例如,將資料夾新增至編輯器的工作區,或在專案指示檔案中指定它。
針對您安裝的每個 GDK 版本,重新將封存檔解壓縮至以該版本命名的資料夾。

將代理程式指向已安裝的標頭和工具

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 處理序中執行建置:
針對 Visual Studio 2022,請使用 GamingDesktopVS2022。環境不會在個別命令之間延續,因此代理程式必須一起執行指令碼和建置。

新增專案指示檔案

大多數程式碼撰寫代理程式都會讀取存放庫根目錄中的專案指示檔案,例如 AGENTS.md 或 .github/copilot-instructions.md。使用它為每個代理程式工作階段提供相同的 GDK 內容。從下列範例開始,並取代角括弧中的值。
AGENTS.md

檢閱代理程式的工作

在您檢閱變更之前,請要求代理程式自我檢閱其工作。例如,提供下列提示:
自我檢閱無法取代您的檢閱。請像處理任何其他程式碼一樣,檢閱並測試代理程式撰寫的程式碼。請在文件中驗證有關平台支援、原則和認證需求的說法,而不是依據代理程式的回答。

另請參閱

最後修改於 2026年11月19日