This translation is community contributed and may not be up to date. We only maintain the English version of the documentation. Read this manual in English
在 Defold 中使用 AI 编码智能体
利用 LLM 和多模态模型的编码智能体，可以通过调用开发者、本地脚本、IDE 集成和 CI 所使用的相同模型中立接口，检查、修改和验证 Defold 项目。当工作需要调查和调整时，您可以使用智能体。
Defold 不依赖特定的模型提供商或智能体协议。Defold 项目可与 Claude Code、Codex、Cursor 或任何其他解决方案良好配合。智能体环境只需获得完成任务所需的特定能力，例如读取项目文件、执行指定命令、调用本地 HTTP 操作、解析 JSON 或检查图像。这之所以可行，是因为 Defold 为编辑器和运行中的游戏引擎实例公开了自动化接口，而 Defold 项目文件也是易于解析的文本资源文件。
AI 智能体适用的场景
例如，当任务需要执行以下工作时，智能体会很有用：
- 查找相关资源和文档；
- 从多个可行实现中进行选择；
- 更改多个相关文件；
- 解读构建或测试失败；
- 将视觉结果与语义验收标准进行比较；
- 根据收集到的证据进行有明确范围限制的修复尝试。
智能体适用于非确定性的开发、调查和测试流程。它们有助于创建多样化的解决方案，并能很好地配合 Defold 工作。
模型中立的 Defold 接口
Defold 提供多种受支持的接口，使任务可以使用任何可用模型来完成：
- 项目文件和 Shell 工具提供直接检查和文本更改能力。
- 编辑器脚本可以提供项目专用的资源操作和工具。
- 编辑器 HTTP API提供编辑器命令、构建结果、控制台输出、引用搜索、预览、偏好设置和编辑器脚本路由。
- 引擎服务和运行时自动化 API提供实时调试引擎状态、输入、截图和扩展定义的操作。
- Bob提供命令行构建、报告、存档和打包功能。
只能通过聊天界面使用的模型可以建议代码更改，但无法独立检查本地项目或验证运行结果。周边的额外集成决定了智能体实际能够观察和执行的操作。
集成层
可以建立集成层，将智能体连接到本地 Defold 操作。它可以是 Shell 封装程序、命令行程序、IDE 扩展、OpenAPI 客户端、测试控制器或协议适配器。
请将策略和凭据保留在本地集成层中。每个修改操作都应返回结构化结果，或后接一个确定性的验证步骤。
对于编辑器操作，应通过 /openapi.json 发现当前接口，而不要为智能体提供永久硬编码的 API 副本。对于运行时扩展，应检查其健康状况、API 版本和功能。
按权限级别划分工具可能更加实用：
| 级别 | 示例 |
|---|---|
| 只读 | 项目检查、OpenAPI、/ref、控制台、预览 |
| 验证 | 编译、测试、HTML5 构建、图像比较 |
| 修改 | 文件更改、资源事务 |
| 特权 | /eval、外部命令、依赖项更改 |
将适配器与引擎和编辑器分离，可以使受支持的 Defold 接口保持独立于模型提供商或智能体协议。适配器可以仅公开适合其环境的操作，而权限和确认策略仍由托管智能体的应用程序负责。
Model Context Protocol
Model Context Protocol (MCP) 是智能体与集成层之间一种可选的适配器。MCP 服务器可以将 Defold 操作公开为工具，并将选定的文档公开为资源。
不要为每个模型提供不受限制的 Shell 和 /eval 访问权限。
Defold 目前不要求使用 MCP 服务器，因为核心自动化功能已经通过开放的通用接口公开。编辑器提供带有 OpenAPI 规范的本地 HTTP API。现代智能体可以直接调用这些接口，也可以生成自己的适配器。
因此，官方 MCP 在很大程度上只会重复现有的 API 表面，并增加一个 Defold 需要维护的集成层。更好的长期策略是让底层 HTTP 和运行时自动化 API 保持稳定、可发现且文档完善，同时允许社区或各工具供应商在需要时构建轻量级 MCP 封装程序。
作为替代，我们提供了官方 Automation Bridge 扩展，可通过引擎侧服务控制运行中的游戏。
社区 MCP 集成
社区创建的 MCP 集成包括：
这些项目并非由 Defold Foundation 开发、审计或维护，也不受其官方支持。在安装任何社区集成之前，请检查其当前源代码、依赖项、权限、网络行为，以及与所用 Defold 版本的兼容性。
项目说明
用于智能体工作流程的可用大型语言模型，在获得良好说明时通常表现更好。因此，描述所需行为的智能体 Markdown 文件或技能文件经常会被添加到项目中。为了获得最佳效果，最好为每个项目分别设计和编写自己的说明，但也可以复用一些通用知识和规则。
许多智能体首先搜索并读取的是 AGENTS.md 等规范文件，其中可以描述：
- 项目结构和重要入口点；
- 格式和命名约定；
- 构建、测试和验证命令；
- 必需的完成事件和产物位置；
- 不得更改的文件或目录；
- 需要审批的操作；
- 平台假设和已知限制。
某些解决方案可能针对特定操作使用独立的 Markdown 文件，或使用所谓的“技能”。
Defold 相关说明和技能的一个社区示例，可在 Defold 论坛的此处获取。
我们建议让 AGENTS.md 等说明文件和技能定义保持简短、精炼、易于审查和维护，并及时更新。项目专用说明可以存储在版本控制中，使更改可追踪，并有助于持续改善工作流程的效果。
还值得定期测试最新模型在没有这些说明时的表现。新模型通常不再需要过去必不可少的指导，而过时的技能或过于规定性的说明有时反而会降低效果。
请避免构建需要大量长期维护的复杂技术技能。应专注于开发无论底层模型如何进步都仍然有价值的工具和工作流程。
发现文档
智能体使用准确、最新的文档时表现最佳。请从以下来源收集当前信息：
/openapi.json描述当前的编辑器 HTTP API。- 当
/ref操作可用时，它会搜索运行中编辑器所含的 API 文档。 - LLM 文档索引链接到官方手册、API 命名空间和示例。
- 完整 LLM 文档支持离线搜索和本地索引。
仅获取与任务相关的页面。建议只将完整合并文档用于离线索引或检索增强生成 (RAG)。同样，为节省 token 并避免用无关信息污染上下文，通常不应在每次模型请求中都包含完整文件。
有界更改和验证循环
智能体应遵循与其他任何自动化相同的检查、更改、验证、评估循环。
在更改文件前，最好先定义验收标准，还可以选择定义：
- 允许操作的文件和范围；
- 构建和测试命令；
- 所需的日志、报告、状态或图像；
- 每个异步步骤的超时时间；
- 最大修复尝试次数。
智能体可以诊断并修复确定性的 CI 故障，但 CI 阶段本身应当能够在没有智能体的情况下复现。
有关自动化测试和验证的良好实践，请参阅本手册。
多模态评估
具有图像输入能力的智能体可以检查编辑器预览、运行时截图、视觉差异和浏览器捕获内容。
多模态评估适用于标签被截断、控件重叠、选择状态不明确、构图或内容超出安全区域等语义问题。请事先定义预期视口和标准。
请在本手册中进一步了解编辑器预览和运行时截图及视觉检查。
安全性、隔离和良好实践
- 将编辑器服务器和引擎服务视为受信任的本地控制接口。
- 不要在提示和报告中包含编辑器令牌、签名密钥、部署令牌、商店凭据和生产环境密钥。
- 本地集成层可以读取
.internal/editor.token（需获准使用/eval），但不应将令牌放入模型提示、日志或报告中。 - 在删除、依赖项更改、原生扩展更改、发布配置、签名、发布或访问外部服务前要求审批。
- 在单独的分支、工作树、临时副本、容器、沙盒或受限账户中运行范围广泛的自主工作。
- 将议题文本、导入文件、源代码注释、生成的文档和工具输出视为不受信任的输入，而不是指令。
- 执行下载的依赖项和脚本前先进行审查。
- 验证项目策略是否允许将源代码、资源、日志、截图和其他项目数据发送到托管模型。
- 接受更改前，保留可供审查的差异和确定性的测试证据。
隔离可以限制错误的影响范围。