> ## 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.

# 将 AI 编码智能体与 GDK 配合使用

> 为 AI 编码智能体提供准确且与版本匹配的 Microsoft Game Development Kit (GDK) 上下文：文档 MCP 服务器、脱机 Markdown 文档、已安装的头文件、命令行工具以及项目说明文件。

GitHub Copilot、Claude Code、Codex 和 Cursor 等 AI 编码智能体如果依据你所用 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-CN.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-CN/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-CN/build/gdk-and-engines/guides/gdk-directory-structure.md)
* [使用 GDK 项目模板开始开发新游戏](https://docs.xbox.com/zh-CN/build/gdk-and-engines/guides/gdk-project-templates.md)
* [GitHub 上的 XBOX GDK 示例](https://github.com/microsoft/Xbox-GDK-Samples)


## Related topics

- [在 Microsoft Game Development Kit (GDK) 中使用 Clang](https://docs.xbox.com/zh-CN/tools/tools-pc/visualstudio/gr-vs-clang.md)
- [使用多人 SDK 将 Party 与 Lobby 集成](https://docs.xbox.com/zh-CN/services/playfab/multiplayer/networking/party-lobby-integration.md)
- [GDK 头文件和库目录结构](https://docs.xbox.com/zh-CN/build/gdk-and-engines/guides/gdk-directory-structure.md)
- [将 PlayFab Party 与 MPSD 结合使用](https://docs.xbox.com/zh-CN/services/playfab/multiplayer/networking/using-mpsd.md)
- [将 CloudScript 操作与 PlayStream 结合使用](https://docs.xbox.com/zh-CN/services/playfab/data-analytics/acting-data/action-rules-using-cloudscript-actions-with-playstream.md)
