> 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 编码助手

查找通过 Convai SDK 感知型 MCP 工具将 AI 编码代理连接到 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 编码助手快速入门](https://docs.convai.com/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 的 Undo 系统，而不会自动保存场景。

### 支持的编码代理

此集成支持五种编码代理：Codex、Claude Code、Cursor、Gemini 和 VS Code Copilot。为某个代理安装支持后，会将由集成管理的 Convai 指令块写入该代理自己的指令文件——Codex 使用 `AGENTS.md` ，Claude Code 使用 `CLAUDE.md` ，Cursor 使用 `.cursor/rules/convai-unity-sdk.mdc` ，Gemini 使用 `GEMINI.md` ，VS Code Copilot 使用 `.github/copilot-instructions.md` ——以便将代理指向随包提供的 `convai-unity-sdk` 技能。请参阅 [支持的编码代理](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/ai-coding-assistant/supported-coding-agents.md) ，了解确切的文件路径以及每种代理的安装行为。

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

在 Unity Editor 菜单中打开 **Convai > Convai Editor** ，然后在窗口的导航栏中选择 **AI 编码** 以开始操作。该部分中的 **设置健康状况** 卡片会检查 <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 编码助手快速入门](https://docs.convai.com/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。完整的 Convai 工具列表请参阅 [MCP 工具参考](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/ai-coding-assistant/mcp-tools-reference.md) 。

### 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="https://docs.convai.com/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="https://docs.convai.com/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="https://docs.convai.com/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="https://docs.convai.com/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 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.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.
