> For the complete documentation index, see [llms.txt](https://docs.convai.com/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/ai-coding-assistant/quick-start.md).
# AI 编码助手快速上手
Convai 为 Unity 的 MCP 服务器扩展了支持 SDK 的工具，因此像 Codex、Claude Code 或 Cursor 这样的编码代理可以直接在你的项目中配置 Convai 组件。第一次将代理连接到已安装 Convai Unity SDK 的项目时，请使用此快速入门。完成后，你的代理会安装托管指令，且 AI Coding 部分会显示每个 Convai 工具都已注册。
### 前提条件
* space.vars.unity\_recommended\_version 或更高版本——Convai 的 AI 编码工具需要 Unity 6000 或更新版本。
* 项目中已安装 Convai Unity SDK。参见 [安装 Convai Unity SDK](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/getting-started/installation.md).
* 一个兼容的 Unity AI Assistant 包（`com.unity.ai.assistant`，版本 `2.13.0` 或更高且低于 `3.0.0` ——一个 `2.13.0` 构建版本必须带有预发布标签 `pre.2` 或更高版本，且 `3.0.0` 构建版本仅接受为预发布版，绝非最终发布版）。请手动安装，或在本指南中直接安装。
* 在你的机器上安装了受支持的编码代理，例如 Codex CLI、Claude Code 或 Cursor。参见 [受支持的代码代理](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/ai-coding-assistant/supported-coding-agents.md) 完整列表。
### 打开 AI Coding 部分
{% stepper %}
{% step %}
#### 在 Convai 编辑器中选择 AI Coding
在 Unity 编辑器菜单栏中，选择 **Convai > Convai 编辑器**。在窗口的导航栏中，选择 **AI 编码**.
该部分的 **设置健康状态** 卡片显示四个就绪状态行： **Unity 6000+**, **Unity AI Assistant**, **打包的 Convai Skill**，以及 **Convai MCP 工具**。每一行显示 **Ready** 或 **需要关注**.
{% endstep %}
{% step %}
#### 接受 Unity MCP 条款
Unity 可能会在此项目中该功能首次激活时提示你接受 Unity AI Assistant 和 MCP 服务器服务条款。接受提示，以便 Unity 的 MCP 服务器和 Convai 的工具能够注册。如果没有出现提示，请打开 **项目设置 > AI > Unity MCP 服务器** 直接接受条款，并确认哪些 MCP 客户端已连接到你的项目。
{% endstep %}
{% step %}
#### 解决任何显示警告的行
每个未就绪的行都会显示一个 **修复方法** 按钮。点击 **修复方法** 旁边的 **Unity AI Assistant** 以安装 `com.unity.ai.assistant@2.14.0-pre.1` 通过 Package Manager 安装——Unity 会重新编译，且该行会自动更新。点击 **修复方法** 旁边的 **打包的 Convai Skill** 或 **Convai MCP 工具** 以刷新包资源并重新注册 Convai 的工具，而无需重新安装 Assistant 包。
{% endstep %}
{% endstepper %}
{% hint style="warning" %}
点击 **修复方法** 当 Unity 正在编译、更新包或处于 Play 模式时，会显示警告且不会开始修复——请先退出 Play 模式，因为修复不会替你退出 Play 模式。 **修复方法** 按钮只有在其发起的修复已在运行时才会被完全禁用。
{% endhint %}
### 安装你的编码代理的托管指令
{% stepper %}
{% step %}
#### 选择你的编码代理
滚动到 **受管理的项目说明** 卡片。Convai 会列出每个受支持的代理及其所管理的文件——例如 `AGENTS.md` 用于 Codex， `CLAUDE.md` Claude Code 对应为 `.cursor/rules/convai-unity-sdk.mdc` ，Cursor 对应为。参见 [受支持的代码代理](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/ai-coding-assistant/supported-coding-agents.md) 完整列表和各代理说明。
{% endstep %}
{% step %}
#### 安装托管指令
点击 **安装** 位于你的代理旁边。Convai 会写入一个由标记分隔的区块，其标记为 `` 和 ``，并将其写入该代理的文件中，同时不会影响任何现有内容。按钮会变为 **Update** 当该区块存在时，且 **移除** 随后可用于将其删除。
{% endstep %}
{% endstepper %}
托管指令会引导你的代理读取 `Packages/com.convai.convai-sdk-for-unity/AIAssistantSkills/convai-unity-sdk/SKILL.md` 及其链接的引用，使用 Unity 的通用 MCP 工具来处理 GameObject、脚本和场景，并使用 Convai 的工具进行 SDK 配置和诊断。
### 验证工具数量
该 **Convai MCP 工具** 该行显示 `37/37 已注册` 一旦 Unity 的 MCP 注册表已在工具契约版本 4 下注册全部 37 个 Convai 工具。如果数量更少，或该行列出了缺失或意外的工具名称，请点击 **修复方法** 旁边的 **Convai MCP 工具** 以刷新注册表并重新编译。
{% hint style="success" %}
当四行都显示以下内容时，设置即完成： **Ready** 和 **Convai MCP 工具** 显示为 `37/37 已注册`.
{% endhint %}
### 提示代理构建你的场景
在安装托管指令并验证工具数量后，用自然语言提示你的代理。Convai 的工具负责处理 SDK 特定配置；你的代理的 Unity MCP 工具负责处理通用 GameObject、脚本和场景操作。
| Task | 示例提示 |
| ---------- | -------------------------------------------------------------------- |
| 构建一个场景 | "设置一个训练模拟房间，包含一个 Convai Player 和一个名为 Instructor 的 Convai Character。" |
| 添加聊天 UI | "将随附的聊天 UI 添加到场景中，以便在对话期间可见转录内容。" |
| 切换为按键说话或免提 | "将房间切换为按键说话输入模式。" |
| 添加对象 | "在工作台旁边添加一个红色灭火器 GameObject。" |
| 启用视觉 | "为 Instructor 角色开启视觉，使其能够看到工作台。" |
视觉设置不在 Convai 的 37 个工具之中，因此你的代理会通过编辑 `ConvaiRoomManager` 并添加 `ConvaiVisionPublisher` 直接进行配置。参见 [视觉快速入门](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/vision/quick-start.md) 其设置的确切字段。
### 接下来可以尝试什么
在你自己的项目中，让代理执行上面两到三个任务，并在进入 Play 模式之前在 Hierarchy 中检查生成的场景。
{% content-ref url="/pages/d8c18409ae9c4e08b59f112c685f31eedd8cba20" %}
[AI 编码助手](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/ai-coding-assistant.md)
{% endcontent-ref %}
{% content-ref url="/pages/ec47f18f1ec454c3afecbec3a73f8ab46981f55c" %}
[受支持的编码代理](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/ai-coding-assistant/supported-coding-agents.md)
{% endcontent-ref %}
{% content-ref url="/pages/2556d68ab00a9475a0e5c6ca8c0541b3d69dc561" %}
[MCP 工具参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/ai-coding-assistant/mcp-tools-reference.md)
{% endcontent-ref %}
{% content-ref url="/pages/19bff3d08fa0ba480410597a8a790b68a4f73b14" %}
[排查 AI 编码助手设置](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/ai-coding-assistant/troubleshooting.md)
{% endcontent-ref %}
---
# 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 dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/ai-coding-assistant/quick-start.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
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.