> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 搭配 GDK 使用 AI 程式碼撰寫代理程式

> 為 AI 程式碼撰寫代理程式提供正確且與版本相符的 Microsoft Game Development Kit (GDK) 內容：文件 MCP 伺服器、離線 Markdown 文件、已安裝的標頭、命令列工具，以及專案指示檔案。

當 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 內容

| 來源 | 代理程式取得的內容 | 版本 | 存取權 |
| - | - | - | - |
| XBOX 文件 MCP 伺服器 | 對已發佈 XBOX 文件的搜尋和擷取 | 目前的線上文件 | 公開 |
| `llms.txt`、`llms-full.txt` 和 Markdown 頁面 | 所有頁面的索引、文件全文，或單一頁面的 Markdown | 目前的線上文件 | 公開 |
| 離線 Markdown 文件 | Markdown 檔案形式的 GDK 文件 | 與已安裝的 GDK 相符 | 公開和機密頁面 |
| 已安裝的標頭 | 確切的宣告，部分標頭還包含文件註解 | 與已安裝的 GDK 相符 | 與您安裝的 GDK 相符 |
| 命令列工具 | 工具本身提供的使用說明文字和錯誤描述 | 與已安裝的 GDK 相符 | 與您安裝的 GDK 相符 |
| [XBOX GDK 範例](https://github.com/microsoft/Xbox-GDK-Samples) | 完整且可建置的範例 | 依 GDK 版本加上標記 | 公開 |

線上來源說明的是目前的 GDK。當您使用較早的 GDK 建置時，也請將已安裝的標頭和離線文件提供給代理程式，以免它使用您的 GDK 中沒有的 API。

## 連線 XBOX 文件 MCP 伺服器

位於 `https://docs.xbox.com/mcp` 的 XBOX 文件 MCP 伺服器可讓代理程式搜尋並引用已發佈的文件。它不需要 API 金鑰或登入。例如，在 Visual Studio Code 中，將伺服器新增至專案中的 `.vscode/mcp.json` 檔案：

```json .vscode/mcp.json theme={null}
{
  "servers": {
    "xbox-docs": {
      "type": "http",
      "url": "https://docs.xbox.com/mcp"
    }
  }
}
```

如需 Claude Code、GitHub Copilot CLI、Cursor、Codex 和 Claude 的設定步驟，請參閱首頁上的[搭配 AI 工具使用這些文件](https://docs.xbox.com/zh-TW.md#xbox-home-ai-title)。

無法使用 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` 檔案會列出這些頁面。

> [!WARNING]
>
> 封存檔包含機密頁面。請只搭配您的組織核准可處理機密 GDKX 內容的 AI 工具使用完整封存檔。請勿將解壓縮的檔案新增至公用存放庫，或組織外部人員可讀取的任何位置。

1. 將封存檔解壓縮至來源存放庫以外的資料夾。在 PowerShell 中，執行下列命令。

   ```powershell theme={null}
   $edition = '261000'
   $zip  = Join-Path $env:GameDK "$edition\xbox\documentation\GDKDocumentationMarkdown.zip"
   $dest = "$env:USERPROFILE\gdk-docs\$edition"
   Expand-Archive -Path $zip -DestinationPath $dest
   ```

2. 如果您的 AI 工具未獲核准可處理機密內容，請只保留公開頁面。下列命令會刪除 `permissioned-type` 不是 `public` 的每個 Markdown 檔案，包括沒有此欄位的檔案。

   ```powershell theme={null}
   Get-ChildItem $dest -Recurse -Filter *.md |
     Where-Object { -not (Get-Content $_.FullName -TotalCount 25 |
       Select-String -Quiet '^permissioned-type:\s*public\s*$') } |
     Remove-Item
   ```

3. 讓代理程式存取該資料夾。例如，將資料夾新增至編輯器的工作區，或在專案指示檔案中指定它。

針對您安裝的每個 GDK 版本，重新將封存檔解壓縮至以該版本命名的資料夾。

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

GDK 安裝程式會設定環境變數，讓代理程式得知已安裝 GDK 的位置：

* `GameDK` 是 GDK 根資料夾。它包含命令列工具的 `bin` 資料夾，以及每個已安裝版本的資料夾，例如 `%GameDK%261000\`。
* `GameDKCoreLatest` 和 `GameDKXboxLatest` 指向最新安裝的版本。

當並存安裝多個版本時，最新的版本可能不是您遊戲建置所使用的版本。請將遊戲使用的版本資料夾 (例如 `%GameDK%261000\`) 提供給代理程式，而不是這些變數。

如需每個版本底下的資料夾，請參閱 [GDK 標頭和程式庫目錄結構](https://docs.xbox.com/zh-TW/build/gdk-and-engines/guides/gdk-directory-structure.md)。告訴代理程式在使用 API 之前，先檢查該版本 `windows\include` 資料夾 (適用於 PC) 或 `xbox\include` 資料夾 (適用於 XBOX 主機) 底下標頭中的宣告。部分標頭 (例如 XBOX 服務 API (XSAPI)、libHttpClient 和 PlayFab 標頭) 也包含說明每個 API 的文件註解。

`%GameDK%bin` 中的命令列工具在搭配 `/?` 執行時，會列印其使用方式。代理程式可以在使用工具之前執行該工具的 `/?`，而不是猜測其選項。若要將 `HRESULT` 轉譯為描述，請使用 `xberror.exe`：

```cmd theme={null}
"%GameDK%bin\xberror.exe" 0x8015DC12
```

## 為代理程式提供與版本相符的範例程式碼

使用 [XBOX GDK 範例清單](https://github.com/microsoft/Xbox-GDK-Samples/blob/main/gdk-samples-list.md)尋找您正在實作之功能的範例。查看存放庫和範例的 README，了解 GDK 版本、目錄配置和平台需求。如果 main 分支與您的專案不相符，請選擇相容的[範例版本](https://github.com/microsoft/Xbox-GDK-Samples/releases)。

複製或下載相容的版本，並將相關範例的原始程式碼和 README 的本機路徑提供給代理程式。要求它遵循範例的初始化、錯誤處理、非同步存留期和清除模式。讓代理程式根據您已安裝的標頭驗證 API，而不是從不同的 GDK 配置複製專案設定。

## 讓代理程式從命令列建置

若要建置，代理程式需要與 Gaming Command Prompt 相同的環境。使用「開始」功能表捷徑所使用的引數執行 `GamingDesktopVars.cmd`，然後在同一個 `cmd` 處理序中執行建置：

```cmd theme={null}
cmd /c ""%GameDK%Command Prompts\GamingDesktopVars.cmd" GamingDesktopVS2026 261000 && msbuild MyGame.sln /p:Configuration=Debug /p:Platform=Gaming.Desktop.x64"
```

針對 Visual Studio 2022，請使用 `GamingDesktopVS2022`。環境不會在個別命令之間延續，因此代理程式必須一起執行指令碼和建置。

## 新增專案指示檔案

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

```markdown AGENTS.md theme={null}
# GDK project instructions

- This game uses the Microsoft Game Development Kit (GDK) <edition, for example 261000 (October 2026)>.
  Target platforms: <Gaming.Desktop.x64, Gaming.Xbox.Scarlett.x64>.
- Before you use a GDK API, check its declaration in the headers of this edition:
  %GameDK%<edition>\windows\include for PC and %GameDK%<edition>\xbox\include for XBOX consoles.
  Don't use an API that the headers for the target platform don't declare.
- Search the XBOX docs with the xbox-docs MCP server. For the documentation of this GDK
  edition, read the Markdown files in <%USERPROFILE%\gdk-docs\261000>.
- Use the sample source and README in <local path to a compatible XBOX GDK sample>.
  Check its GDK version, directory layout, and platform requirements before adapting code.
- Build: cmd /c ""%GameDK%Command Prompts\GamingDesktopVars.cmd" GamingDesktopVS2026 <edition> && msbuild <solution> /p:Platform=Gaming.Desktop.x64"
- Run a GDK tool with /? before you use it. Translate HRESULT values with xberror.
- Before handing back a change, review the diff for correctness and unintended changes.
  Run the build and relevant tests. Report the commands, results, and anything you couldn't verify.
- Don't copy confidential GDKX content into public files or into tools that aren't approved for it.
```

## 檢閱代理程式的工作

在您檢閱變更之前，請要求代理程式自我檢閱其工作。例如，提供下列提示：

```text theme={null}
Review your diff against the task and project instructions before handing it back.
Check HRESULT handling, asynchronous completion or cancellation, resource cleanup,
and API availability in the installed GDK edition for each target platform.
Look for unintended behavior changes and missing tests for the changed behavior.
Fix the issues you find, then run the build and relevant tests for the affected targets.
Report remaining concerns, the exact commands and results, and anything you couldn't verify.
Don't claim a build, test, or platform check passed unless you ran it successfully.
```

自我檢閱無法取代您的檢閱。請像處理任何其他程式碼一樣，檢閱並測試代理程式撰寫的程式碼。請在文件中驗證有關平台支援、原則和認證需求的說法，而不是依據代理程式的回答。

## 另請參閱

* [GDK 標頭和程式庫目錄結構](https://docs.xbox.com/zh-TW/build/gdk-and-engines/guides/gdk-directory-structure.md)
* [使用 GDK 專案範本開始開發新遊戲](https://docs.xbox.com/zh-TW/build/gdk-and-engines/guides/gdk-project-templates.md)
* [GitHub 上的 XBOX GDK 範例](https://github.com/microsoft/Xbox-GDK-Samples)


## Related topics

- [從代理程式使用 XBOX CLI](https://docs.xbox.com/zh-TW/tools/xbox-cli/cli-for-agents.md)
- [GDK 標頭和程式庫目錄結構](https://docs.xbox.com/zh-TW/build/gdk-and-engines/guides/gdk-directory-structure.md)
- [搭配 Microsoft Game Development Kit (GDK) 使用 Clang](https://docs.xbox.com/zh-TW/tools/tools-pc/visualstudio/gr-vs-clang.md)
- [GDKX 標頭和程式庫目錄結構](https://docs.xbox.com/zh-TW/build/console-features/console-workflows/gdkx-new-layout.md)
- [使用 Visual Studio 與 AI 最佳化遊戲開發工作流程](https://docs.xbox.com/zh-TW/build/core-features/graphics/overviews/presentations/xdd2024/gc-graphics-xdd-2024-gr12.md)
