> For the complete documentation index, see [llms.txt](https://docs.decentraland.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.decentraland.org/creator/content-creator-zh/chang-jing-bian-ji-qi/shi-yong-dai-ma-kuo-zhan/ai-assistant.md). # AI 助手 在 Creator Hub 中与 AI 助手聊天，构建并修改你的场景。 Creator Hub 可以运行一个 AI 助手，它能看到你打开的场景并为你编辑。你可以让它放置物品、连接行为、编写脚本，或者运行预览并检查结果。 {% hint style="warning" %} **📔 注意**：助手运行的是一个你安装并登录的编码 CLI，拥有对你机器的完全访问权限，权限范围与它在你的终端中相同。只有在你信任它要执行的操作时才启用它。 {% endhint %} ## 设置位于何处 助手默认已开启。它的设置有单独的选项卡： 1. 点击左上角的 Creator Hub 标志并选择 **设置**. 2. 前往 **AI** 选项卡。 该选项卡包含 **启用 AI 助手** 开关、 **改为记到 API 密钥** 选项、 **连接** 编码 CLI 列表，以及 **公开 AI 助手 MCP 服务器** 设置。 当助手开启时， **AI 助手** 按钮（闪光图标）会出现在编辑器顶部栏中，位于 **代码** 按钮左侧。点击它即可在你的场景旁打开聊天面板。 ![编辑器顶部栏，左侧是场景名称，右侧是闪光 AI 助手图标、代码、预览和发布按钮。](https://2460066822-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-7db0716b3d034ba09084bf784488209d7d77caad%2Feditor-top-bar.png?alt=media\&token=e00db1c0-c8c4-42c2-bd13-d5c2ab00f63e) ![首次打开时的 AI 助手面板：顶部有“新聊天”下拉菜单和一个显示 Claude 的 CLI 下拉菜单，下面有欢迎消息、关于 AI 使用情况卡片、一个标明所选实体的选择标签，以及底部的“询问助手”输入框。](https://2460066822-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-078c9e0dec3b2886d4216fad423c9fddd492bf0c%2Fai-assistant-panel.png?alt=media\&token=b4720826-136f-4743-9a1f-db5663cbd47f) ## 连接编码 CLI 助手不使用自己的 API 密钥。它运行的是一个你安装并登录的编码 CLI，因此费用记在该工具自己的订阅上。 支持四种。大多数都通过终端进行设置：设置界面会显示适用于你操作系统的安装命令、登录命令，以及供应商安装指南的链接，方便你依次复制。 | CLI | 在 macOS 和 Linux 上安装 | 在 Windows 上安装 | 登录 | | ------ | ------------------------------------------------------- | -------------------------------------------------------------------------------------------- | -------------------- | | Claude | `curl -fsSL https://claude.ai/install.sh \| bash` | `winget install Anthropic.ClaudeCode` | `claude auth login` | | Codex | `curl -fsSL https://chatgpt.com/codex/install.sh \| sh` | `powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 \| iex"` | `codex login` | | Cursor | `curl https://cursor.com/install -fsS \| bash` | `powershell -ExecutionPolicy ByPass -c "irm 'https://cursor.com/install?win32=true' \| iex"` | `cursor-agent login` | | Gemini | `npm install -g @google/gemini-cli` | `npm install -g @google/gemini-cli` | 运行 `gemini` | Codex 是个例外：它还提供一个 **使用 Codex 登录** 按钮，它会替你执行登录并打开浏览器。Claude、Cursor 和 Gemini 只能通过终端进行安装和登录。 安装 CLI 后，点击 **重新检查** 在设置界面中。它会立即识别新安装，无需重启 Creator Hub。 {% hint style="warning" %} **📔 注意**：Claude Desktop 并不等同于 Claude Code。助手需要的是 Claude Code 这个终端工具，登录桌面应用不会让你登录到它。如果 Creator Hub 发现了 Claude Desktop 但没有 Claude Code，它会明确提示，并显示安装命令。 Gemini CLI 需要付费的 Gemini API 密钥，或 Gemini Code Assist Standard 或 Enterprise 许可证。 {% endhint %} 在首次打开且未连接任何 CLI 时，聊天面板本身也会显示相同的设置界面，以及设置中的 **AI** 选项卡下的 **连接**. 如果某个 CLI 保存的登录状态过期，其状态会变为 **需要登录** 并且面板会逐条显示需要执行的退出登录和登录命令。请执行它们，然后重新发送你的消息。 {% hint style="info" %} **💡 提示**：如果你登录了多个 CLI，聊天面板中的下拉菜单可让你在它们之间切换。 {% endhint %} ### 改为记到 API 密钥 如果你宁愿按 token 付费而不是使用 CLI 订阅，请在 **改为记到 API 密钥** 在 **AI** 设置的选项卡中开启它。它会从你的环境中读取提供商的 API 密钥： `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `CURSOR_API_KEY` 或 `GEMINI_API_KEY`。默认关闭。 ## 它能做什么 助手会在你当前打开的场景上工作。它可以： * **编辑场景**：创建和删除实体、修改组件、放置 [智能物品](/creator/content-creator-zh/chang-jing-bian-ji-qi/jiao-hu-xing/smart-items.md)，附加 [脚本](/creator/content-creator-zh/chang-jing-bian-ji-qi/shi-yong-dai-ma-kuo-zhan/script-component.md)，以及读取和写入 `scene.json`. * **编写代码** 到你的场景文件中。 * **运行预览** 并操控它：截屏、四处走动、点击物体、读取日志并检查性能。 * **读取你的选择内容**，这样你就可以选中一个实体并说“让这个更高一点”。 更改会在发生时保存，并进入正常的撤销历史记录。若要一次撤销整轮对话，请使用 **撤销 AI 更改** 在助手回复中的按钮。 ![在请求重命名某个实体并添加一个网格渲染器后，停靠在编辑器右侧的 AI 助手面板：回复列出了它运行的工具，描述了结果，并在下方显示一个“撤销 AI 更改”按钮。](https://2460066822-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-06054ee50124b89ef317fcecd4f797d7c71896a2%2Fai-assistant-reply.png?alt=media\&token=a107e7b4-4862-4630-9591-1bca87e32b17) 在助手工作时，它的更改会实时显示在实体树和画布中。 ![完整的场景编辑器，右侧停靠着 AI 助手面板，实体树中可见重命名后的 Stage 实体，助手回复末尾有“撤销 AI 更改”。](https://2460066822-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-5867011b5b777986587d4cce33d0554e24101b69%2Fai-assistant-docked.png?alt=media\&token=2caa43b5-acc6-4e1b-a90e-85ccddd5bc0f) ## 使用聊天 * **新聊天** 开始一段新的对话。 * **聊天记录** 列出更早的对话及其运行于多久之前。对话会按项目保存，因此重新打开某个场景时会恢复其聊天记录。 * **在独立窗口中打开** 将助手弹出到独立窗口中，在第二块显示器上很方便。 **重新停靠回编辑器** 将其返回。 * 面板可以拖宽或拖窄。 一个 **关于 AI 使用情况** 卡片会提醒你，助手会消耗你所连接账户的 token。请留意该账户的用量。 ### 向提示附加文件 有时展示给助手看比描述更容易。你可以通过三种方式向任何消息附加文件： * 点击消息框左侧标有 **附加文件**的回形针图标，然后选择一个或多个文件。 * 从文件管理器中将文件拖到消息框上。 **松开以附加文件** 提示会在拖动时出现。 * 直接从剪贴板粘贴图片，例如你刚截的屏幕截图。 每个附加文件都会以标签的形式显示在消息框上方，并带有表示其类型的图标：图片、3D 模型（`.glb`, `.gltf`）、音频（`.mp3`, `.wav`, `.ogg`, `.m4a`, `.flac`），或者其他类型的通用文件。点击 **移除** 标签上的叉号即可在发送前将其移除。单条消息最多可附加 8 个文件，而且你也可以只发送附件而不附带任何文字。 你拖入或从磁盘中选择的文件会通过其真实路径交给助手，因此不会复制，也没有大小限制。助手可以直接查看图片，并且在编写场景代码时可以通过路径引用模型或音频文件。粘贴的图片在磁盘上没有文件，因此 Creator Hub 会先将它们保存为临时文件；这些文件每个上限为 8 MB。 如果你的 Claude CLI 版本过旧，面板会显示警告。请运行 `claude update` 在终端中修复它。 ### 在提示中指向某个资源 附加文件会发送其内容。提及资源更轻量：它只是告诉助手你指的是项目中的哪个资源，因此你可以说“用这个”而不必输入路径。 在助手打开时，双击 **本地资源** 选项卡中的任意资源。它会以标签形式显示在消息框上方，内容为 **资源： *****文件名***，或 **内置动画： *****名称*** ，表示某个内置的头像动画。 * 你可以提及任意多个资源。每个资源都会有自己的标签和自己的 **移除** 叉号。 * 提及内容会显示在 **选择** 标签旁边，这样你就可以同时指向场景中的一个实体和一个资源：“把这个动画放到那个 NPC 上”。 * 提及内容只对你的下一条消息生效。发送后就会清除。 {% hint style="info" %} **💡 提示**：选中 Scene 根节点等同于未选择任何内容，因此它绝不会发送给助手。若要让助手对某个实体操作，请选中一个真实实体。 {% endhint %} ## Decentraland 技能会自动为你安装 当助手运行时，Creator Hub 会下载官方的 [Decentraland SDK 技能](/creator/content-creator-zh/chang-jing-sdk7/ru-men/vibe-coding.md) 并将其链接到你的项目中，这样助手会遵循经过验证的 SDK7 模式，而不是凭猜测行事。 它们链接在 `.claude/skills` 和 `.agents/skills` 位于你的项目文件夹中，并且二者都会被添加到 `.gitignore` 中，因此它们不会进入你的仓库。 ## 助手会在你的场景文件夹中留下的文件 助手可以通过本地 MCP 服务器读取和编辑你打开的场景。每个 CLI 对该服务器的了解方式都不同，因此根据你使用的工具不同，你可能会在项目中看到新的文件： | CLI | 场景文件夹中会出现什么 | | ------ | ----------------------------------------------------- | | Cursor | `.cursor/mcp.json`，以及 `.cursor/rules/creator-hub.mdc` | | Gemini | `.gemini/settings.json` | | Claude | 没有。配置会放在项目外部的临时文件中。 | | Codex | 没有。配置会通过命令行传递。 | 如果你已经有这些配置文件中的某一个，Creator Hub 会将其条目合并进去，而不是覆盖你自己的服务器。 {% hint style="warning" %} **📔 注意**: `.cursor/mcp.json` 是唯一包含访问令牌本身的文件，因为 Cursor 的配置格式无法从环境中读取它。Creator Hub 会在写入前将其添加到你的 `.gitignore` 中，所以不要提交它，也不要删除那一行。Gemini 文件通过一个 `$CREATOR_HUB_MCP_TOKEN` 环境变量来引用令牌，因此它不包含机密信息，也不会被忽略。 {% endhint %} ## 改用你自己的 AI 工具 如果你已经在 Claude Code、Cursor、Codex 或其他支持 MCP 的工具中工作，你可以让它指向打开的场景，而不是使用内置面板。MCP（Model Context Protocol，模型上下文协议）是 AI 工具调用另一个程序的一种标准方式。 1. 从 Creator Hub 标志打开主菜单，选择 **设置**，然后在 **AI** 选项卡中展开 **公开 AI 助手 MCP 服务器**. 2. 点击 **复制配置**. 3. 将其粘贴到你的工具的 MCP 配置中。 复制的配置如下，已填入真实的端口和令牌： ```json { "mcpServers": { "creator-hub": { "type": "http", "url": "http://127.0.0.1:/mcp", "headers": { "Authorization": "Bearer " } } } } ``` 对于 Claude Code，你也可以从场景文件夹中的终端将其添加： ```bash claude mcp add --transport http --scope local creator-hub http://127.0.0.1:/mcp \\ --header "Authorization: Bearer " ``` {% hint style="warning" %} **📔 注意**：每次 Creator Hub 启动时，端口和令牌都会不同。如果你的工具突然出现 `401` 错误，请重新复制配置。服务器只监听你自己的机器，并且只会作用于你当前打开的场景。 {% endhint %} ## 相关页面 * [AI 氛围编程](/creator/content-creator-zh/chang-jing-sdk7/ru-men/vibe-coding.md)：关于 SDK 技能和高质量提示的完整指南。 * [与代码结合](/creator/content-creator-zh/chang-jing-bian-ji-qi/shi-yong-dai-ma-kuo-zhan/overview.md)：在代码编辑器中打开你的场景。 * [使用脚本组件](/creator/content-creator-zh/chang-jing-bian-ji-qi/shi-yong-dai-ma-kuo-zhan/script-component.md)：从文件中为实体附加行为。 --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.decentraland.org/creator/content-creator-zh/chang-jing-bian-ji-qi/shi-yong-dai-ma-kuo-zhan/ai-assistant.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.