> 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 Editor 的 AI Coding 部分，接受 Unity MCP 条款，安装编码代理的说明，并验证 Convai 工具。

Convai 扩展了 Unity 的 MCP 服务器，添加了了解 SDK 的工具，让 Codex、Claude Code 或 Cursor 等编码代理可以直接在你的项目中配置 Convai 组件。首次将代理连接到已安装 Convai Unity SDK 的项目时，请使用本快速入门。完成后，代理将安装好托管指令，并且 AI Coding 部分会显示所有 Convai 工具均已注册。

### 前提条件

* <code class="expression">space.vars.unity\_recommended\_version</code> 或更高版本 — Convai 的 AI 编码工具要求 Unity 6000 或更高版本。
* 项目中已安装 Convai Unity SDK。请参阅 [安装 Convai Unity SDK](https://docs.convai.com/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` 或更高版本才视为兼容；严格介于 `2.13.0` 和 `3.0.0` 之间的任何版本，无论预发布标签为何，均可接受；而 `3.0.0` 本身只有在预发布状态下才可接受，正式发行版则不行。你可以手动安装，也可以在此操作指南中安装。
* 机器上已安装受支持的编码代理，例如 Codex CLI、Claude Code 或 Cursor。完整列表请参阅 [受支持的编码代理](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/ai-coding-assistant/supported-coding-agents.md) 。

### 打开 AI Coding 部分

{% stepper %}
{% step %}

#### 在 Convai Editor 中选择 AI Coding

在 Unity Editor 菜单栏中，选择 **Convai > Convai Editor**。在窗口的导航栏中，选择 **AI Coding**.

该部分的 **设置状态** 卡片会显示四项准备状态： **Unity 6000+**, **Unity AI Assistant**, **已打包的 Convai Skill**以及 **Convai MCP 工具**。每项状态显示为 **就绪** 或 **需要处理**.
{% endstep %}

{% step %}

#### 接受 Unity MCP 条款

首次在此项目中启用该功能时，Unity 可能会提示你接受 Unity AI Assistant 和 MCP 服务器的服务条款。接受提示，以便 Unity 的 MCP 服务器和 Convai 工具可以注册。如果没有出现提示，请直接打开 **Project Settings > AI > Unity MCP Server** 以接受条款，并确认已连接到项目的 MCP 客户端。
{% endstep %}

{% step %}

#### 处理显示警告的项目

每个未就绪的项目都会显示一个 **修复** 按钮。点击 **修复** 旁边的 **Unity AI Assistant** 以通过 Package Manager 安装 `com.unity.ai.assistant@2.14.0-pre.1` ——Unity 会重新编译，随后该项目的状态会自动更新。点击 **修复** 旁边的 **已打包的 Convai Skill** 或 **Convai MCP 工具** ，即可刷新包资源并重新注册 Convai 的工具，无需重新安装 Assistant 包。
{% endstep %}
{% endstepper %}

{% hint style="warning" %}
单击 **修复** 时，如果 Unity 正在编译、更新包或处于运行模式，系统会显示警告且不会开始修复。请先退出运行模式，因为修复过程不会自动退出运行模式。只有在该 **修复** 按钮启动的修复正在进行时，该按钮才会被完全禁用。
{% endhint %}

### 安装编码代理的托管指令

{% stepper %}
{% step %}

#### 选择编码代理

滚动到 **托管项目指令** 卡片。Convai 会列出每个受支持的代理及其管理的文件，例如 Codex 对应 `AGENTS.md` ，Claude Code 对应 `CLAUDE.md` ，Cursor 对应 `.cursor/rules/convai-unity-sdk.mdc` 。完整列表和各代理的说明请参阅 [受支持的编码代理](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/ai-coding-assistant/supported-coding-agents.md) 。
{% endstep %}

{% step %}

#### 安装托管指令

单击代理旁边的 **安装** 。Convai 会将一个由 `<!-- BEGIN CONVAI UNITY SDK -->` 和 `<!-- END CONVAI UNITY SDK -->`标记界定的内容块写入该代理的文件，而不会影响现有内容。内容块创建后，按钮会变为 **更新** ，并且可以使用 **移除** 按钮在以后将其删除。
{% endstep %}
{% endstepper %}

托管指令会引导代理读取 `Packages/com.convai.convai-sdk-for-unity/AIAssistantSkills/convai-unity-sdk/SKILL.md` 及其链接的参考资料，使用 Unity 的通用 MCP 工具处理 GameObject、脚本和场景，并使用 Convai 的工具进行 SDK 配置和诊断。

### 验证工具数量

当 Unity 的 MCP 注册表按照工具契约版本 7 注册了全部 44 个 Convai 工具后， **Convai MCP 工具** 一行会显示 `44/44 registered` 。如果数量较少，或该行列出了缺失或意外的工具名称，请单击旁边的 **修复** 按钮， **Convai MCP 工具** 以刷新注册表并重新编译。

{% hint style="success" %}
当四行均显示 **就绪** ，且 **Convai MCP 工具** 显示为 `44/44 registered 时，设置即告完成。`.
{% endhint %}

### 提示代理构建场景

安装托管指令并确认工具数量后，用自然语言向代理发出提示。Convai 工具负责 SDK 特定的配置；代理的 Unity MCP 工具负责通用的 GameObject、脚本和场景操作。

| 任务           | 提示词示例                                                                 |
| ------------ | --------------------------------------------------------------------- |
| 构建场景         | “设置一间训练模拟室，其中包含一个 Convai Player 和一个名为 Instructor 的 Convai Character。” |
| 添加聊天 UI      | “将随附的聊天 UI 添加到场景中，以便在对话期间查看聊天记录。”                                     |
| 切换为按键通话或免提模式 | “将房间切换到按键通话输入模式。”                                                     |
| 添加对象         | “在工作台旁添加一个红色的灭火器 GameObject。”                                         |
| 启用视觉功能       | “为 Instructor 角色开启视觉功能，让它能够看到工作台。”                                    |
| 添加第二个角色      | “添加第二个名为 Trainee 的 Convai Character，并将对话目标切换为 Proximity。”             |

视觉功能设置不属于 Convai 的 44 个工具之一，因此代理会通过编辑 `ConvaiRoomManager` 并直接添加 `ConvaiVisionPublisher` 来进行配置。具体设置的字段请参阅 [视觉功能快速入门](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features/vision/quick-start.md) 。

### 接下来可以尝试

在自己的项目中，让代理执行上面两到三项任务，并在进入播放模式前，在层级视图中检查生成的场景。

{% content-ref url="/pages/d8c18409ae9c4e08b59f112c685f31eedd8cba20" %}
[AI 编码助手](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/ai-coding-assistant.md)
{% endcontent-ref %}

{% content-ref url="/pages/ec47f18f1ec454c3afecbec3a73f8ab46981f55c" %}
[受支持的编码代理](https://docs.convai.com/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 工具参考](https://docs.convai.com/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 编码助手设置问题](https://docs.convai.com/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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/ai-coding-assistant/quick-start.md?ask=<question>&goal=<user_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.
