跳转到主要内容
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 上下文

在线来源描述的是当前 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日