# UPilot

让 Codex、Claude Code、Cursor、OpenCode 等 AI Agent 直接操作 Unity Editor。

UPilot 会在 Unity 中启动本地 MCP 服务，并为常见 Agent 自动写入项目级连接配置。配置完成后，你可以直接让 Agent 查看场景、检查编译错误、读取 Console、修改 GameObject、管理资源、运行测试或构建任务。

> Unity：`2022.3` 或更高
>
> 正式版使用独立 MCP Server，由 UPilot 下载并管理，无需另外安装运行环境。
>
> 默认 MCP 地址：`http://127.0.0.1:8011/mcp`

> 教程截图来自 Windows 上的 Unity 2022.3。不同 Unity 版本或编辑器主题下，界面外观可能略有差异，请以实际界面提示为准。

## 2 分钟上手

安装 Unity 包 → 按向导安装服务并配置 Agent → 验证连接，即可开始使用。首次下载和 Unity 编译的耗时取决于网络与项目规模。

### 1. 安装 Unity 包

在 Unity 中打开：

```text
Window > Package Manager
```

点击左上角 `+`，选择 **Add package from git URL...**，输入：

```text
https://github.com/codingriver/upilot.git#v0.3.44
```

点击 **Add**，等待 Unity 完成包导入和脚本编译。这里以固定发布版本 `v0.3.44` 为例；安装其他正式版本时，将链接末尾的标签替换为对应的 `vMAJOR.MINOR.PATCH`。

![在 Package Manager 中输入 UPilot Git URL](Documentation~/images/upilot-package-manager-git-url.png)

*输入 UPilot Git URL 后点击右侧 Add。*

### 2. 在 Unity 中安装服务并配置 Agent

包导入完成后，Unity 会自动打开 UPilot 设置界面。如果没有自动打开，请选择：

```text
UPilot > 打开 UPilot
```

然后：

1. 在设置向导的 **网络端口** 步骤使用推荐端口，点击 **下一步**。
2. 在 **服务安装** 步骤点击 **下一步**。UPilot 会下载、校验并保存独立服务配置，成功后自动进入 **Agent 配置**。
3. 选择你正在使用的 Agent：`Codex`、`Claude Code`、`Cursor` 或 `OpenCode`，支持多选。
4. 保持启动选项勾选，点击 **写入配置并启动**，等待主界面显示 **已就绪**。

![UPilot 首次配置界面](Documentation~/images/upilot-first-setup.png)

*按设置向导安装服务、选择常用 Agent，再写入配置并启动。*

UPilot 会自动选择可用端口、写入所选 Agent 的 MCP 配置，并同步所需的 Skill/规则。

### 3. 重启 Agent 并验证

首次写入配置后，请重新启动 Agent 客户端，或重新加载当前项目窗口，使 MCP 工具列表刷新。

然后对 Agent 说：

```text
请调用 unity_mcp_status，确认 UPilot 已连接，并检查当前 Unity 工程路径。
```

成功时应满足：

- `connected: true`
- `serverReady: true`
- 返回的 Unity 工程路径与当前项目一致

现在可以开始使用 UPilot。

在 **高级设置 → 常规 → 周期与超时** 中，可配置心跳、Health、Domain Reload 复核、窗口观察、包更新恢复、重连和界面刷新。详见[周期与超时配置及四阶段实施清单](Documentation~/TimingAndTimeouts.md)。Bridge 心跳默认 3 秒，HTTP Health 默认 10 秒；服务验证就绪后，Health 由服务统一持有，所有窗口关闭后仍运行，多开窗口不增加检查器。周期设置调整后续调度，有限观察保留开始时固定的期限；长心跳间隔不会放宽 Editor 主线程新鲜度要求。四阶段实现、规范项目定向验收和服务刷新已完成，证据及未覆盖范围见[2026-10-14 验证记录](Documentation~/TimingAndTimeouts-Validation-20261014.md)。

## UPilot 能做什么

UPilot 是 AI Agent 与 Unity Editor 之间的桥梁：Agent 通过 MCP 工具读取真实的 Unity 状态，并在授权后执行修改，而不只是生成一段代码供你手动粘贴。

| 功能 | 可以让 Agent 做什么 |
|---|---|
| 项目与场景检查 | 读取工程路径、Editor 状态、已打开场景、对象层级和组件信息 |
| 场景与对象编辑 | 创建或修改 GameObject、Transform、Component，管理场景与 Prefab |
| 资源与项目设置 | 查找、导入和管理资源，处理材质、贴图及项目设置 |
| 编译与 Console 诊断 | 查看 Unity 编译结果、定位 Error/Warning，修改脚本后同步并等待编译验证 |
| 测试与构建 | 运行 Unity 测试或构建任务，查询进度并获取最终结果和产物 |
| 截图与日志取证 | 获取编辑器画面、采集 Console 日志，为问题定位和测试保留证据 |
| 自动化步骤（UPilot Step） | 将业务测试组织为完整步骤计划，由执行器统一处理超时、取消、清理和报告 |
| 受控 C# 执行 | 调用已加载方法、验证并执行受限 C# 语句，用会话管理跨调用状态 |
| Agent 自动配置 | 为 Codex、Claude Code、Cursor、OpenCode 配置 MCP 连接，并同步规则和 Skill |
| 多项目连接 | 为不同 Unity 项目分配独立端口，通过返回的工程路径确认操作目标 |
| 可选高级功能 | UPilot Flow 编排 Editor 界面操作；UPilot 追踪器按过滤条件观察对象事件 |

具体工具是否可调用取决于当前 Unity 连接、功能开关与项目授权。Flow 和追踪器默认关闭，入门使用无需启用。修改脚本、资源或项目设置前，请确认目标并按界面提示授权。

## 环境要求

| 项目 | 要求 |
|---|---|
| Unity | 2022.3 或更高版本 |
| 系统 | 当前正式版独立服务提供 Windows x64 可执行程序 |
| Agent | Codex、Claude Code、Cursor、OpenCode，或支持 Streamable HTTP MCP 的客户端 |
| Git | Unity 通过 Git URL 安装包时需能调用 Git |
| 网络 | 首次安装 Unity 包和独立服务时需要访问 GitHub |

UPilot 默认只监听本机地址 `127.0.0.1`。Unity Editor 必须保持打开，Agent 才能操作当前项目。

## 完整安装教程

### 方式一：通过 Unity Package Manager 安装（推荐）

1. 打开 Unity 项目。
2. 选择 `Window > Package Manager`。
3. 点击左上角 `+`。
4. 选择 **Add package from git URL...**。
5. 输入以下地址并点击 **Add**：

![从 Package Manager 打开 Git URL 安装入口](Documentation~/images/upilot-package-manager.png)

*点击左上角加号，然后选择“Add package from git URL...”。*

```text
https://github.com/codingriver/upilot.git#v0.3.44
```

安装完成后，Package Manager 中应显示包名 **UPilot**，包标识为：

```text
io.github.codingriver.upilot
```

### 方式二：手动修改 manifest.json

如果 Package Manager 无法添加 Git URL，可以打开 Unity 项目的 `Packages/manifest.json`，在 `dependencies` 中加入：

```json
{
  "dependencies": {
    "io.github.codingriver.upilot": "https://github.com/codingriver/upilot.git#v0.3.44"
  }
}
```

如果文件中已有其他依赖，请只增加这一项，并注意上一项末尾的逗号。保存后返回 Unity，等待包解析和脚本编译完成。

## 首次配置教程

### 使用设置向导（推荐）

首次导入正式版 UPilot 后，按设置向导完成以下操作：

1. 使用推荐的网络端口，进入下一步。
2. 在 **服务安装** 步骤点击 **下一步**，直接开始下载独立 MCP Server。下载、文件校验与配置保存完成后，自动进入 **Agent 配置**。
3. 选择常用 Agent，保持启动选项勾选，点击 **写入配置并启动**。
4. 等待主界面状态变为 **已就绪**。

如果匹配的服务已就绪，点击 **下一步** 即可继续；也可以通过 **选择本地服务文件** 指定已下载的正式版独立服务，按界面提示完成检查。

服务安装过程中会显示下载与校验进度，主按钮暂时禁用；可以取消下载，取消后留在当前步骤。安装失败时显示具体原因，点击 **重试** 重新安装。服务启动与连接验证在第 3 步点击 **写入配置并启动** 后进行。

![UPilot 首次配置界面](Documentation~/images/upilot-first-setup.png)

*Codex、Claude Code、Cursor 和 OpenCode 可以单选或多选。*

选择多个 Agent 时，UPilot 会同时写入这些 Agent 的项目级 MCP 配置。之后也可以在主界面的 **Agent 配置** 区域单独添加其他 Agent。

### 配置过程中会发生什么

UPilot 会自动处理以下内容：

- 下载、校验并管理独立 MCP Server（首次安装服务时）。
- 为当前 Unity 项目选择可用的本地端口。
- 启动 Unity Bridge 和 MCP 服务。
- 写入所选 Agent 的项目级 MCP 连接。
- 写入或更新 UPilot 管理的 Agent 规则。
- 同步 UPilot Skill：Codex、Cursor 与 OpenCode 使用共享的 `.agents/skills` 安装，Claude Code 使用 `.claude/skills` 安装。

已有配置文件中的其他 MCP 服务和用户内容会尽量保留。UPilot 管理的内容使用独立标记或独立配置项进行更新。

### MCP 地址

默认地址是：

```text
http://127.0.0.1:8011/mcp
```

实际地址会显示在 UPilot 主界面的 **MCP 地址** 区域，点击 **复制** 即可复制。

> 请始终使用界面显示的实际地址。多项目或端口冲突时，UPilot 可能会选择其他 HTTP 端口。

不要把 Unity Bridge 的 WebSocket 地址配置给 Agent。WebSocket 仅供 UPilot 内部连接使用。

## Codex、Claude Code、Cursor 与 OpenCode

推荐通过 Unity 的 UPilot 界面自动配置。以下内容仅用于检查配置或自动配置不可用时手动处理。

### Codex

项目配置文件：

```text
.codex/config.toml
```

配置内容：

```toml
[mcp_servers.upilot]
url = "http://127.0.0.1:8011/mcp"
startup_timeout_sec = 10
tool_timeout_sec = 300
```

Codex 还会使用项目中的 `AGENTS.md` 和 `.agents/skills/upilot-unity-mcp`。因此，除了 MCP 配置外，建议同时在 UPilot 界面更新 **Skill**。

### Claude Code

项目配置文件：

```text
.mcp.json
```

配置内容：

```json
{
  "mcpServers": {
    "upilot": {
      "type": "http",
      "url": "http://127.0.0.1:8011/mcp"
    }
  }
}
```

Claude Code 的 UPilot 使用规则会同步到项目规则文件中，按需工作流安装在：

```text
.claude/skills/upilot-unity-mcp
```

### Cursor

项目配置文件：

```text
.cursor/mcp.json
```

配置内容：

```json
{
  "mcpServers": {
    "upilot": {
      "url": "http://127.0.0.1:8011/mcp"
    }
  }
}
```

Cursor 的 UPilot 规则位于：

```text
.cursor/rules/upilot-unity-mcp.mdc
```

Cursor 官方支持项目级 `.agents/skills`，因此与 Codex 共享：

```text
.agents/skills/upilot-unity-mcp
```

### OpenCode

项目配置文件优先使用：

```text
opencode.json
```

如果项目已经使用 `opencode.jsonc`，UPilot 会保留该文件并只更新其中的 `mcp.upilot`：

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "upilot": {
      "type": "remote",
      "url": "http://127.0.0.1:8011/mcp",
      "enabled": true,
      "timeout": 30000
    }
  }
}
```

OpenCode 原生读取项目根目录 `AGENTS.md`，并与 Codex、Cursor 共享：

```text
.agents/skills/upilot-unity-mcp
```

OpenCode 还会发现 `.claude/skills` 和 `.opencode/skills`。如果多个目录存在同名 `upilot-unity-mcp`，UPilot 会比较内容哈希；内容不同会显示为 Skill 冲突，不能标记为已就绪。

手动修改配置后，请重启或刷新 Agent 客户端。

## 如何确认安装成功

### 在 Unity 中确认

打开 `UPilot > 打开 UPilot`，检查：

- 顶部状态为 **已就绪**。
- 主界面显示 MCP 地址。
- 常用 Agent 显示 **MCP 已配置**。
- Codex、Claude Code、Cursor 和 OpenCode 都显示独立的规则、MCP 配置与 Skill 状态。

### 在浏览器中检查服务

打开：

```text
http://127.0.0.1:8011/health
```

如果 UPilot 使用了其他端口，请把 `8011` 替换成主界面显示的端口。

直接用浏览器打开 `/mcp` 可能返回 `406 Not Acceptable`，这是正常现象，因为 `/mcp` 是 MCP 通信端点，不是普通网页。健康检查应使用 `/health`。

### 在 Agent 中确认

发送：

```text
请调用 unity_mcp_status，并告诉我：
1. connected 和 serverReady 是否为 true；
2. 当前连接的 Unity 工程路径；
3. Unity 是否正在编译或进入 Play Mode。
```

如果返回的工程路径不是你正在处理的项目，请先停止操作，切换到正确的 MCP 地址后再继续。

## 第一次使用 UPilot

建议先从只读任务开始，确认连接和项目识别都正确。

### 查看项目与场景

```text
请使用 UPilot 检查当前 Unity 项目、已打开场景和场景层级，只做分析，不修改任何内容。
```

### 检查编译错误

```text
请使用 UPilot 检查当前 Unity 编译状态和编译错误，说明错误原因，暂时不要修改代码。
```

### 检查 Console

```text
请使用 UPilot 读取最近的 Unity Console Error 和 Warning，并按优先级汇总。
```

### 修改场景对象

```text
请使用 UPilot 在当前场景创建一个名为 TestRoot 的空 GameObject，创建前先确认当前场景，完成后再次读取对象验证结果。
```

### 修复代码并编译

```text
请分析当前编译错误，修复相关 C# 代码，然后让 Unity 同步并编译，最后确认没有新的编译错误。
```

### 运行测试或长任务

```text
请使用 UPilot 运行项目的 EditMode 测试，持续查询任务状态，直到成功、失败或取消，并汇总最终结果。
```

对于测试、构建和其他异步任务，仅“开始执行”不代表完成。应要求 Agent 持续查询，直到得到最终结果。

## 主界面说明

通过 `UPilot > 打开 UPilot` 打开主界面。

![UPilot 已就绪主界面](Documentation~/images/upilot-main-window.png)

*主界面优先显示整体状态、Agent 是否可用和 MCP 地址；版本、端口与内部连接信息收纳在“运行详情”中。*

### 服务状态

- **已就绪**：可以直接让 Agent 操作 Unity。
- **正在启动/正在重启**：等待几秒钟，不需要重复点击。
- **需要修复**：点击 **自动修复**，UPilot 会尝试修复服务路径、端口或连接。
- **已停止**：点击 **启动 UPilot**。

### 重启 UPilot

服务已就绪时，点击右上角 **⋮ > 重新启动**。重启会同时重建 MCP 服务和 Unity 连接，常用于：

- Agent 突然无法调用工具。
- Unity 重新加载脚本后连接未恢复。
- 修改端口或服务设置后重新连接。
- MCP 工具调用持续超时。

重启 UPilot 后，如果 Agent 的工具列表仍未刷新，再重启或重新加载 Agent 客户端。

### Agent 配置

主界面会列出 Codex、Claude Code、Cursor 和 OpenCode，默认只显示“已就绪”“需更新”“未配置”或“异常”等最终状态。展开任意 Agent 后，都会以相同顺序和相同视觉权重显示三项：**Agent 规则**、**MCP 配置**、**Skill 技能**。

每一项都提供 Tooltip：鼠标悬停时会显示可用的绝对文件/目录路径、当前版本与目标版本、MCP 当前/目标 URL、内容哈希、错误或适用性说明。状态检查与更新入口彼此独立，不再把 Agent 规则和 Skill 合并成一个状态。

**MCP 配置** Tooltip 会区分已注册、当前可用和当前可调用的 MCP 工具数量，并显示工具注册表版本及主要分类。可调用数量会受到 Unity 连接、功能开关和项目写入授权影响。

**Skill 技能** Tooltip 显示该 Agent 项目级 Skill 根目录、已安装 Skill 数量和名称、UPilot Skill 数量、能力覆盖，以及 Skill 文档实际引用的 MCP 工具数量和主要关联工具。Skill 数量与 MCP 工具数量是两个不同维度，不应共用同一个数字。

- **配置**：当前 Agent 还没有 UPilot MCP 配置，点击后新增配置。
- **更新配置**：当前 Agent 已有 UPilot 配置。点击后会二次确认，只更新该 Agent 的 UPilot MCP 配置项。
- **更新规则**：为当前 Agent 更新对应的 UPilot Agent 规则。
- **更新 Skill**：权威同步所有 UPilot Skill 目标；Codex、Cursor 与 OpenCode 共用 `.agents/skills`，Claude 使用独立的 `.claude/skills`。
- **更新全部**：更新已启用 Agent 的现有 UPilot MCP 连接条目，并权威同步全部 UPilot Skill/Agent 规则；若已启用 Agent 缺少 MCP 配置，会先提示选择“补齐并更新”或“仅更新现有”。
- **检查配置**：位于“更新全部”右侧的下拉菜单中，只刷新状态，不修改文件。
- **强制重新配置全部已启用 Agent**：只为用户已启用的 Agent 创建或更新 MCP 配置，并重新生成共享的 UPilot Skill/Agent 规则；不会自动启用或写入未使用的客户端。

首次设置会保存用户勾选的 Agent；旧项目会从已有、可识别的 `mcp.upilot` 条目迁移启用状态，没有既有条目的全新项目默认只启用 Codex。未启用的客户端以中性 **未启用** 显示，不计入配置问题；在对应行点击 **启用并配置** 后才会写入其 MCP 配置。

Claude Code、Codex、Cursor 和 OpenCode 都支持 UPilot Skill。Claude Code 使用 `.claude/skills`；Codex、Cursor 和 OpenCode 默认共享 `.agents/skills`，避免重复维护。Cursor 与 OpenCode 的 Tooltip 会列出其可发现的项目级 Skill 目录，按 Skill 名称去重统计，并在同名副本内容哈希不一致时显示冲突。

UPilot 的规则 managed block 与固定目标下的 `upilot-unity-mcp` Skill 和包版本深度绑定，因此首次安装、重复安装、UPM 升级与自动刷新都会权威同步。检测到本地修改、无元数据或无法验证的旧副本时，会先备份到 `.upilot/backups/agent-integrations/`，再覆盖受管内容；自动流程和普通更新不再弹出本地定制二次确认。Agent managed block 外的项目业务规则以及非 UPilot MCP 配置保持不变。

### 授权与运行详情

已授权时，主界面不再常驻显示授权状态、授权时间或撤销按钮。未授权时，状态卡下方会显示“需要授权”提示和 **允许授权** 按钮；Agent 仍可执行只读检查，但修改脚本、资源和项目设置前需要授权。

授权时间、撤销授权和完整项目路径位于 **高级设置 > Agent > Agent 操作授权**。

展开主界面的 **运行详情** 可以查看运行状态、UPM/服务版本、运行方式、发布通道、**MCP 端口**、**Unity Bridge 端口**和 Bridge 连接状态。Unity Bridge 端口仅用于 MCP Server 与 Unity Editor 的内部连接，不能配置为 Agent 的 MCP 地址。

### 自定义项目规则

项目自己的业务约束应写在 `AGENTS.md` 等规则文件的 UPilot 管理块之外。UPilot 生成的规则和 Skill 会随包更新同步；本地修改会先备份到 `.upilot/backups/agent-integrations/`，不要直接维护生成文件。

需要开发或维护 UPilot 规则模板时，请查看 [Agent/Skill 安装与同步指南](skills/upilot-unity-mcp/references/installation.md)，普通使用无需执行模板生成命令。

## 高级设置、停止与诊断

普通使用不需要进入高级设置。需要停止服务、修改端口或查看详细诊断时，点击主界面的 **高级设置…**，或选择：

```text
UPilot > 高级设置
```

![UPilot 高级设置界面](Documentation~/images/upilot-advanced-settings.png)

*高级设置提供运行检查、重启、停止、端口和诊断功能。*

### 停止 UPilot

停止按钮只在高级设置中提供，并以红色显示。点击 **停止** 后还需要二次确认。

停止后，Agent 将暂时无法操作 Unity。界面会显示“正在停止”或“已停止”，需要恢复时点击 **启动 UPilot**。

### 高级设置可以做什么

- 查看 Unity Bridge、MCP 服务和 Agent 连接状态。
- 启动、重启或停止 UPilot。
- 开启或关闭自动启动。
- 修改 HTTP 和内部 WS 端口。
- 查看操作日志、通信日志和完整诊断结果。
- 在普通停止无效时，按诊断提示处理残留的 UPilot 服务进程。

结束所有疑似 MCP 服务进程属于故障恢复操作，只应在普通停止无效、端口持续被占用时使用。

### Python 开发环境

源码开发安装默认使用 Python 配置。正式版需要调试或自定义环境时，可从 **UPilot > 高级设置 > 服务运行方式** 选择 Python；日常使用保持默认的独立服务方式即可。

Python 方式需要 Python 3.11 或更高版本，可选择：

- **自动配置环境**：检测到可用的基础解释器后，点击 **配置并继续**，创建环境、安装依赖并验证。目标环境已存在时先验证，验证失败会显示原因并保留现有文件，修复后重新检测。
- **使用已有环境**：选择解释器的完整路径，点击 **验证并继续**。UPilot 严格验证该解释器的版本与运行依赖，失败时显示具体原因和路径，不使用其他 Python 环境代替，也不覆盖已有环境。

缺少基础解释器时，请先安装 Python 3.11 或更高版本，再点击 **重新检测**。配置过程中可以取消；失败或取消会留在当前步骤，不会报告配置成功。

首次配置在验证并保存成功后自动进入 **Agent 配置**；已配置项目从高级设置切换运行方式时，仍通过 **应用并重启服务** 生效。

## 同时打开多个 Unity 项目

每个 Unity 项目必须使用不同的 HTTP 和内部 WS 端口。

UPilot 首次配置或自动修复时会优先寻找空闲端口。多项目同时运行时：

1. 分别打开每个项目的 `UPilot > 打开 UPilot`。
2. 确认每个项目显示的 MCP 地址不同。
3. 在每个项目中更新对应 Agent 配置。
4. 在 Agent 中调用 `unity_mcp_status`，核对 Unity 工程路径。

不要仅根据端口判断项目，实际操作前始终核对 `unityProjectAbsolute` 返回的工程路径。

## 更新 UPilot

### 更新 Unity 包

使用固定版本 Git URL 时，把 `Packages/manifest.json` 中的版本标签改为目标正式版本。例如，升级到 `v0.3.44` 时使用：

```text
https://github.com/codingriver/upilot.git#v0.3.44
```

保存后等待 Unity 完成包更新和脚本编译。

### 更新独立 MCP Server

按照 UPilot 界面的服务更新提示更新独立 MCP Server，等待下载和校验完成后再启动服务。如果手动选择本地服务文件，请使用与目标发布版本匹配的独立程序。

### 同步 Agent 配置

更新完成后：

1. 打开 `UPilot > 打开 UPilot`。
2. 点击 **更新全部**。
3. 确认提示“将更新已有的 UPilot MCP 连接条目，重新同步全部 UPilot Skill/AGENT规则”。
4. 重启 UPilot。
5. 重启或刷新 Agent 客户端。
6. 再次调用 `unity_mcp_status` 验证连接和项目路径。

## 常见问题

### Unity 中没有出现 UPilot 菜单

1. 在 Package Manager 中确认 `io.github.codingriver.upilot` 已安装。
2. 等待 Unity 完成脚本编译。
3. 检查 Console 是否有其他 C# 编译错误；项目中任何编译错误都可能阻止 Editor 菜单加载。
4. 关闭并重新打开 Unity 项目。

### 安装服务失败，或写入配置后一直停留在启动中

1. 确认安装的是固定发布标签版本，并已在 **服务安装** 步骤点击 **下一步**，完成独立服务安装。
2. 下载失败时，检查是否能访问 GitHub、下载目录是否可写，以及安全软件是否拦截独立服务。
3. 点击 **自动修复**，根据界面显示的错误处理。
4. 仍未恢复时打开 **高级设置**，检查服务文件路径、HTTP/WS 端口和诊断日志。

如果使用 **选择本地服务文件**，请确认文件存在，并且与当前系统和目标发布版本匹配。

### Agent 看不到 UPilot 工具

1. 确认 Unity 中 UPilot 显示 **已就绪**。
2. 确认 Agent 对应行显示 MCP 已配置。
3. 复制主界面的 MCP 地址，确认配置文件中的 URL 一致。
4. 重启或刷新 Agent 客户端，使工具列表重新加载。
5. 让 Agent 调用 `unity_mcp_status`；如果该工具也不可见，说明客户端尚未加载 UPilot MCP 配置。

### 健康检查正常，但 Agent 仍然无法操作 Unity

健康检查正常只表示 HTTP 服务可访问，不代表 Unity 已完成连接。请在 Agent 中调用 `unity_mcp_status`，确认：

- `connected` 为 `true`
- `serverReady` 为 `true`
- 工程路径正确

### Agent 连接到了错误的 Unity 项目

停止当前操作，打开目标项目的 UPilot 主界面，复制它显示的 MCP 地址，然后更新当前 Agent 配置。重启 Agent 后再次检查工程路径。

### 端口被占用

在主界面点击 **自动修复**。UPilot 会尝试选择空闲端口并重新启动。端口变化后，还需要更新 Agent 配置并刷新 Agent 客户端。

### 修改了 Skill/规则，更新后内容被恢复

UPilot 会权威同步固定目标下的 Skill 和 Agent managed block，以保证它们与当前 UPM 包版本一致。覆盖前会自动备份本地修改到 `.upilot/backups/agent-integrations/<UTC时间>-<随机ID>/`；备份失败时对应目标不会被修改。项目业务规则应写在 Agent managed block 外，不要直接维护生成的 Skill 文件。

### 浏览器访问 /mcp 返回 406

这是正常现象。`/mcp` 只用于 MCP 客户端通信，浏览器检查请访问：

```text
http://127.0.0.1:8011/health
```

## 卸载

1. 在 `UPilot > 高级设置` 中点击红色 **停止**，并确认停止。
2. 在 Unity Package Manager 中选择 **UPilot**，点击 **Remove**。
3. 如需清理项目连接，只删除各配置文件中的 `upilot` MCP 项，不要删除包含其他服务的整个配置文件。
4. 可选清理 UPilot 管理的规则和 Skill：

```text
.agents/skills/upilot-unity-mcp
.claude/skills/upilot-unity-mcp
.cursor/rules/upilot-unity-mcp.mdc
```

`AGENTS.md`、`CLAUDE.md` 等文件可能包含项目自己的规则。清理时只移除 `<!-- upilot:start -->` 与 `<!-- upilot:end -->` 之间的 UPilot 管理块。

通过 Package Manager 正常卸载时，UPilot 会清理自己写入的 `UPILOT` 编译宏；直接删除包目录或手工删除包引用后，如有残留，需要在 PlayerSettings 中手动移除该宏。独立服务文件可能供多个项目共用，不要在仍有项目使用时删除。

## 自动化与高级执行

### UPilot Step

UPilot Step 是默认的业务自动化测试方式。项目提供业务步骤、断言、测试数据和清理逻辑，UPilot 执行器负责完整计划的验证、执行、超时、取消、Finally 清理、日志采集与报告。

内置步骤支持打开场景、切换运行模式、等待、启动 Console 采集和截图。可以通过 `unity_operation_*` 提交完整计划、查询状态并获取产物；只有执行结束并验证结果，才代表测试完成。

- [Step 编写与执行指南](skills/upilot-unity-mcp/references/automation-steps.md)
- [Automation 公共支撑 API 与集成说明](Documentation~/Automation-Integration-Plan.md)

### 受控执行工具

| 工具 | 用途 |
|---|---|
| `unity_reflection_call` | 调用一个已加载方法或一条受限表达式 |
| `csharp_validate` | 只读预检语法、绑定和后端支持，不执行目标代码 |
| `csharp_eval` | 执行有预算限制的 UPilot C# 子集语句 |
| `reflection_emit_type` | 从结构化描述创建临时 CLR 类型 |
| `execution_session` | 管理跨调用变量、对象、类型和 delegate 句柄 |

除只读验证外，执行可能产生副作用，需要项目写入授权。取消不会回滚已发生的修改，不应自动重试；优先使用专用 Unity 工具，仅在确有需要时使用这些高级入口。

详细边界见 [受控 C# 执行设计](Documentation~/CSharpEvalAndEmitDesign.md) 和 [执行工具指南](skills/upilot-unity-mcp/references/execution-tools.md)。

## UPilot Flow

UPilot Flow 是可选的 Unity Editor 界面自动化功能，普通用户不需要启用。

- 默认关闭，不影响 UPilot 核心功能。
- 仅支持 Unity 6 或更高版本。
- 适合需要通过 YAML 编排复杂 EditorWindow 操作的高级场景。

需要使用时请查看 [UPilot Flow 文档](Documentation~/UPilot-Flow.md)。

## UPilot 追踪器

UPilot 追踪器是默认不启用任何点位的手动 Editor 诊断模块，可按列表选择生命周期、GameObject、Component 和 Transform 点位，并按对象来源、类型、名称、Hierarchy、Scene、Layer/Tag、Prefab、点位/方法/阶段和运行模式过滤后查看或导出事件。

需要使用时请查看 [UPilot 追踪器文档](Documentation~/MonoHook-Tracing.md)。

## 使用建议

- 第一次连接先执行只读检查，再进行场景或资源修改。
- 让 Agent 在修改前确认目标场景、对象或资源。
- 对删除、覆盖、批量修改、构建发布等操作明确要求二次确认。
- 使用版本控制，并在重要操作前保存 Unity 场景和项目改动。
- 同时打开多个 Unity 项目时，每次操作前检查连接的工程路径。

## 获取帮助

- 项目主页：[https://github.com/codingriver/upilot](https://github.com/codingriver/upilot)
- 版本记录：[CHANGELOG.md](CHANGELOG.md)
- 问题反馈：[GitHub Issues](https://github.com/codingriver/upilot/issues)
- License：[MIT](LICENSE.md)