> 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 编辑器中查看生成的更改。

{% 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 编辑器菜单中，然后选择 **AI 编码** 以开始。该部分的 **设置健康状态** 卡片会检查 <code class="expression">space.vars.unity\_recommended\_version</code> 或更高版本、兼容的 `com.unity.ai.assistant` 包、打包的 Convai 技能以及 44 工具契约，并为任何失败的检查提供内联 **修复** 按钮。打开 **项目设置 > AI > Unity MCP 服务器** ——可直接打开，或通过 **打开 Unity MCP 服务器设置** 按钮——来接受 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 工具，并为通用的 GameObject、脚本和场景操作使用 Unity 自己的 MCP 工具，然后报告它更改了哪些实例 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 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.