> 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.md).

# AI 编码助手

查找将 AI 编码代理通过 Convai 的 SDK 感知 MCP 工具连接到 Unity 的指南，包括设置、受支持的代理和故障排除。

Convai AI 编码助手集成会将 Convai 专用工具添加到 Unity 官方 MCP 服务器中，因此编码代理可以检查、配置并诊断你项目中的 Convai 组件，而不是由你手动接线。如果你已经在使用受支持的编码代理，并希望它理解 Convai 房间、角色、动作、口型同步、具身模块（如凝视和情绪）、转录以及视觉功能，就可以使用它。连接后，你可以用自然语言向代理发出指令，并在 Unity Editor 中审查生成的更改。

{% hint style="info" %}
**开始之前：** 该集成需要 <code class="expression">space.vars.unity\_recommended\_version</code> 或更高版本，以及兼容的 `com.unity.ai.assistant` 包。参见 [AI 编码助手快速入门](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/ai-coding-assistant/quick-start.md) 以获取完整的前置条件检查和设置流程。
{% endhint %}

### 该集成新增了什么

Unity 的官方 MCP 服务器，由 `com.unity.ai.assistant` 包提供，为编码代理提供用于 GameObject、脚本、资源和场景操作的通用工具，但对 Convai 组件并不了解。Convai Unity SDK 额外添加了 44 个具备 SDK 感知的工具，并带有一个 `Convai.*` 名称前缀——例如 `Convai.ConfigureCharacter`, `Convai.ConfigureLipSync`, `Convai.ConfigureGaze`, `Convai.DiagnoseConversation`以及 `Convai.ConfigureConversationTargeting` ——它们只会读取和修改 Convai 组件，例如 `ConvaiManager`、角色、动作、口型同步、具身模块（凝视、身体动画、肢体语言、情绪）、转录、叙事章节，以及在多角色房间中玩家正在与哪个角色对话。Unity MCP 工具仍然负责通用的 GameObject、脚本和场景操作。Convai 工具绝不会接收或返回 API 密钥，而修改型 Convai 工具使用 Unity 的撤销系统，而不是自动保存场景。

### 受支持的编码代理

该集成支持五种编码代理：Codex、Claude Code、Cursor、Gemini 和 VS Code Copilot。为某个代理安装支持会将受管理的 Convai 指令块写入该代理自己的指令文件中—— `AGENTS.md` 适用于 Codex， `CLAUDE.md` 适用于 Claude Code， `.cursor/rules/convai-unity-sdk.mdc` 适用于 Cursor， `GEMINI.md` 适用于 Gemini， `.github/copilot-instructions.md` 适用于 VS Code Copilot——并将代理指向打包的 `convai-unity-sdk` 技能。参见 [受支持的编码代理](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/ai-coding-assistant/supported-coding-agents.md) 以了解每个代理的准确文件路径和安装行为。

### 将编码代理连接到你的项目

打开 **Convai > Convai Editor** 在 Unity Editor 菜单中，然后选择 **AI 编码** 在窗口的导航栏中开始。该部分的 **Setup Health** 卡片会检查 <code class="expression">space.vars.unity\_recommended\_version</code> 或更高版本、兼容的 `com.unity.ai.assistant` 包、打包的 Convai 技能以及 44 工具契约，并为任何未通过的检查提供内联 **修复方法** 按钮。打开 **Project Settings > AI > Unity MCP Server** ——可直接，或者通过 **Open Unity MCP Server Settings** 按钮——在同一部分中——以接受 Unity 关于 MCP Server 功能的条款，并确认哪些 MCP 客户端已连接到你的项目。然后点击 **安装** 旁边的受支持编码代理，在 **已管理的项目说明** 卡片中写入其受管理的指令块。参见 [AI 编码助手快速入门](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/ai-coding-assistant/quick-start.md) 以获取完整流程。

### 你可以要求已连接代理执行什么

连接编码代理后，你可以直接用自然语言向它发出指令，而不是手动接线组件。典型请求包括：

* 构建一个包含玩家和角色的对话场景
* 添加聊天 UI 以显示对话转录
* 在按键通话和免提对话输入之间切换
* 向场景中添加供角色引用的对象
* 启用视觉功能，使角色可以看到场景
* 为角色配置凝视、身体动画、肢体语言或情绪
* 向房间中添加第二个角色，并配置 SDK 如何决定玩家正在与哪个角色对话

代理会使用 Convai 工具处理 Convai 组件，并使用 Unity 自己的 MCP 工具处理通用的 GameObject、脚本和场景操作，然后报告它更改了哪些实例 ID。参见 [MCP 工具参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/ai-coding-assistant/mcp-tools-reference.md) 以查看代理可用的完整 Convai 工具列表。

### AI 编码助手页面

<table data-view="cards"><thead><tr><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>AI 编码助手快速入门</strong><br>将编码代理连接到你的 Unity 项目，并端到端验证设置。</td><td><a href="/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/ai-coding-assistant/quick-start.md">AI 编码助手快速入门</a></td></tr><tr><td><strong>受支持的编码代理</strong><br>查找五个受支持代理中每个代理的确切指令文件路径和安装行为。</td><td><a href="/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/ai-coding-assistant/supported-coding-agents.md">受支持的编码代理</a></td></tr><tr><td><strong>MCP 工具参考</strong><br>参考暴露给编码代理的每个 Convai 工具，包括其用途和默认启用状态。</td><td><a href="/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/ai-coding-assistant/mcp-tools-reference.md">MCP 工具参考</a></td></tr><tr><td><strong>排查 AI 编码助手设置问题</strong><br>修复设置、工具注册和代理连接失败。</td><td><a href="/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/ai-coding-assistant/troubleshooting.md">排查 AI 编码助手设置问题</a></td></tr></tbody></table>


---

# 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.md?ask=<question>&goal=<endgoal>
```

`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.