# UPilot

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

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

> 当前版本：`0.2.0`
>
> Unity：`2022.3` 或更高
>
> Python：`3.11` 或更高
>
> 默认 MCP 地址：`http://127.0.0.1:8011/mcp`

> 教程截图来自 Windows 上的 Unity 2022.3。不同 Unity 版本、操作系统或编辑器主题下，界面外观可能略有差异，但按钮名称和操作流程一致。

## 5 分钟快速上手

### 1. 确认环境

只有从源码运行 MCP Server 时才需要 Python。若使用 UPilot 管理的独立 MCP Server 可执行程序，可跳过本步骤。源码模式请确认已安装 Python 3.11 或更高版本：

```powershell
python --version
```

如果系统提示找不到 `python`，请先安装 [Python](https://www.python.org/downloads/)，安装时勾选 **Add Python to PATH**。

### 2. 安装 Unity 包

在 Unity 中打开：

```text
Window > Package Manager
```

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

```text
https://github.com/codingriver/upilot.git#<STABLE_RELEASE_TAG>
#开发模式
https://github.com/codingriver/upilot.git#main
```

点击 **Add**，等待 Unity 完成包导入和脚本编译。

安装完成后，UPilot 会为当前构建目标在 PlayerSettings 的 Scripting Define Symbols 中追加公共宏 `UPILOT`。项目内仅供 UPilot 使用的 Editor/测试代码可以用 `#if UPILOT` 隔离；切换构建目标时，新目标会自动补充该宏。通过 Unity Package Manager 正常卸载时，UPilot 会删除自己写入过的 `UPILOT`，并保留其他宏及其顺序。直接删除包目录或手工删除 manifest 引用时，包代码无法执行卸载清理，需要在 PlayerSettings 中手动移除残留的 `UPILOT`。

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

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

### 3. 可选：安装 Python MCP Server

仅在不使用独立 MCP Server 可执行程序、需要从 Python 源码运行时执行。显式选择所需的 Server ref；它不从 Unity 包的 `package.json` 自动推断，也可以独立版本化：

```powershell
python -m pip install "git+https://github.com/codingriver/upilot.git@<SERVER_REF>#subdirectory=upilotserver~"
```

如果你已经下载或克隆了 UPilot 仓库，也可以在仓库中执行：

```powershell
cd upilotserver~
python -m pip install -e .
```

### 4. 在 Unity 中配置并启动

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

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

然后：

1. 选择你正在使用的 Agent：`Codex`、`Claude Code`、`Cursor` 或 `OpenCode`，支持多选。
2. 点击 **配置并启动**。
3. 等待界面显示 **已就绪**。

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

*选择常用 Agent 后点击“配置并启动”。*

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

### 5. 重启 Agent 并验证

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

然后对 Agent 说：

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

成功时应满足：

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

现在可以开始使用 UPilot。

## 受控执行工具

UPilot 提供五个分工明确的执行入口：`unity_reflection_call` 调用一个已加载方法或一条受限表达式；只读 `csharp_validate` 预检语法或后端支持；`csharp_eval` 执行有预算的 UPilot C# 子集语句；`reflection_emit_type` 从结构化 spec 创建临时 CLR 类型；`execution_session` 管理跨调用变量、对象、类型和 delegate 句柄。它们不使用 Roslyn、Unity Eval/Compilation API、CodeDom 或 mcs。

`csharp_validate` 只解析/绑定/编译，不执行目标代码、getter 或构造器；其余执行工具可能产生副作用，需要项目写入授权，且不会被安全地自动重试。`csharp_eval` 的 `upilot-csharp-subset-v2` 支持 try/catch/finally/throw、引用语义 closure、typed/block/async lambda、Task/ValueTask await、实用级确定性泛型推断、`??`/`??=`/`typeof`/`nameof`/`default(T)`、隐式/交错及 rank 1–4 多维数组，以及由 persistent session 管理的事件和逃逸 delegate；明确禁止 async void。跨调用 closure 使用当前调用预算和取消上下文，独立的外部 delegate 调用由 session token 管理，不会引用已经释放的单次调用资源。取消和超时不会回滚已经发生的状态，基础设施错误不可被用户 catch，finally 使用独立有界清理预算。执行错误通过结构化 `stage/sourceSpan/diagnostics/candidates/cleanupDiagnostics/nextAction` 提供定位和恢复建议。

`csharp_eval` 的 `emit` 是兼容的 AST `DynamicMethod` 入口缓存；显式 `compiled` 才会把受支持的同步 AST lowering 为 Expression Tree delegate，并在不支持时于执行前失败且不回退。`reflection_emit_type` 创建真实 CLR Type，body 可选 `bodyBackend=interpret|compiled`。Emit callback 可配置次数、重入和 `isolate|propagate` 异常策略；相同 spec 的缓存只复用 CLR Type，callback guard、诊断和清理 lease 仍按 session 与实例隔离。动态类型仅支持 Unity Editor/JIT，其程序集使用 `Run`，只能在 Domain Reload 时真正释放。当前阶段不支持 DLL 动态加载或替换已有程序集方法；完整边界见 `Documentation~/CSharpEvalAndEmitDesign.md` 和 `skills/upilot-unity-mcp/references/execution-tools.md`。

## 环境要求

| 项目 | 要求 |
|---|---|
| Unity | 2022.3 或更高版本 |
| Python | 3.11 或更高版本 |
| Agent | Codex、Claude Code、Cursor、OpenCode，或支持 Streamable HTTP MCP 的客户端 |
| 网络 | 首次通过 Git 和 pip 安装时需要访问 GitHub 与 Python 包源 |

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#<STABLE_RELEASE_TAG>
```

安装完成后，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#<STABLE_RELEASE_TAG>"
  }
}
```

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

### 可选：安装 Python MCP Server

UPilot 可使用独立 MCP Server 可执行程序，因此 Python 版本号不是 Unity UPM 安装所必需的。只有源码运行 Server 时才安装 Python 包，并显式选择兼容的 Server ref：

```powershell
python -m pip install "git+https://github.com/codingriver/upilot.git@<SERVER_REF>#subdirectory=upilotserver~"
```

安装完成后可以执行以下命令进行检查：

```powershell
python -c "import mcp, websockets, yaml, PIL; print('UPilot Python dependencies OK')"
```

看到 `UPilot Python dependencies OK` 即表示依赖可用。

如果电脑安装了多个 Python，请确保执行安装命令的 Python 版本为 3.11 或更高，并且可以从系统 PATH 中找到。

## 首次配置教程

### 使用简化设置（推荐）

首次导入 UPilot 后，主界面会提示“完成一次简单设置”。

1. 选择常用 Agent。
2. 点击 **配置并启动**。
3. 等待状态从“正在启动”变为“已就绪”。

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

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

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

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

UPilot 会自动处理以下内容：

- 为当前 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 地址。

### Skill/规则模板维护

#### 随包分发的源文件

通用 Agent 规则、Skill 和新增 Step 指南均保存在 UPilot 仓库内，不依赖开发者机器上的全局 Skill：

```text
skills/upilot-unity-mcp/
|-- AGENTS.md.template             Agent 规则权威源
|-- SKILL.md.template              Skill 指令权威源
|-- SKILL.md                       生成的可读 Skill 入口
|-- template-manifest.json         规则及 Skill 版本
|-- agents/openai.yaml.template    Skill 元数据权威源
|-- agents/openai.yaml             生成的元数据
|-- references/automation-steps.md Step 新增、生命周期、注册与验收指南
|-- references/installation.md     安装与同步流程
`-- scripts/                      生成、校验和安装工具
Documentation~/AgentRules/AGENTS.upilot.md  生成的规则阅读版
```

UPM/Git 分发保留仓库内整份 `skills/upilot-unity-mcp/`，不是只复制 `SKILL.md`。
独立 Server EXE 也内嵌该目录的模板、Skill、参考文件和脚本，排除 Unity `.meta`、
Python 缓存和项目安装标记；这不代表独立 EXE 会自动向项目安装文件。
项目安装仍以当前 UPM 包的模板为准，通过既有五目标同步流程写入规则和两份 Skill。
新增 Step 指南纳入 Skill 必需文件检查，缺失时校验失败。

维护只改上述权威源；不把用户目录的安装副本反向覆盖进包，也不复制含本机路径/端口的项目
`AGENTS.md` 作为默认规则。`ksb-smoke-runner`、关卡/英雄及战场日志规则属于项目业务技能，
不作为 UPilot 的通用默认分发内容。发布前完成源生成/校验，提交后随正常发布流程交付；
本地文件修改不等于已发布。

UPilot 的 Agent 规则、Skill 指令和 OpenAI Skill 元数据分别只维护以下源模板：

```text
skills/upilot-unity-mcp/AGENTS.md.template
skills/upilot-unity-mcp/SKILL.md.template
skills/upilot-unity-mcp/agents/openai.yaml.template
```

三份模板及版本统一由 `skills/upilot-unity-mcp/template-manifest.json` 描述。安装或更新时，UPilot 会渲染工程路径、MCP 地址、健康检查地址、规则版本、Skill 包版本、UPilot 包版本和生成时间等上下文。模板引擎仅支持简单的 `{{token}}`；未知、缺失或残留占位符会直接失败。

模板会部署到这些目标位置：

```text
AGENTS.md
CLAUDE.md
.cursor/rules/upilot-unity-mcp.mdc
.agents/skills/upilot-unity-mcp/AGENTS.md.template
.claude/skills/upilot-unity-mcp/AGENTS.md.template
```

`CLAUDE.md` 默认引用 `@AGENTS.md`；Cursor 规则会在同一模板内容外包一层 Cursor frontmatter；OpenCode 原生复用 `AGENTS.md`。仓库中的 `SKILL.md`、`agents/openai.yaml` 以及 `Documentation~/AgentRules/AGENTS.upilot.md` 是提交到版本库的受管生成产物；安装时再按项目实际端口生成 `.agents/skills` 和 `.claude/skills` 副本，Cursor 与 OpenCode 直接复用 `.agents/skills`。

可使用以下命令检查或重新生成受管产物：

```powershell
python skills/upilot-unity-mcp/scripts/render_skill_pack.py --check
python skills/upilot-unity-mcp/scripts/render_skill_pack.py --write
```

main 分支维护规则：

- 只编辑 `AGENTS.md.template`、`SKILL.md.template` 和 `agents/openai.yaml.template`，不要直接编辑生成的 `SKILL.md`、`agents/openai.yaml` 或 Agent 规则参考产物。
- Agent 行为发生语义变化时，递增 manifest 中的 `agentRulesVersion`。
- 任意已安装 Skill 文件或模板发生变化时，递增 manifest 中的 `skillPackVersion`。
- 纯重构、读取方式变化或文案不影响 Agent 行为时，不需要递增 `agentRulesVersion`。
- `.upilot-install.json` schema v2 同时记录模板哈希、最终内容哈希和渲染上下文；清洁旧版本直接升级，本地定制、无元数据或无法验证的副本自动备份后权威重建。`--force` 仅为兼容旧调用保留，不再决定是否覆盖 UPilot 自有目标。
- `main` / source 安装仍按 source 通道运行本机 Python，不使用自动管理 EXE；正式 tag 发布时由 Action 写入 tag 版本。

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

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

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

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

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

### 停止 UPilot

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

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

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

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

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

## 同时打开多个 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` 中的版本标签改为目标版本，例如：

```text
https://github.com/codingriver/upilot.git#<TARGET_RELEASE_TAG>
```

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

### 更新 Python 包

源码安装 MCP Server 时，显式选择需要升级到的兼容 Server ref。MCP Server 可以作为独立程序版本化，不要求从 Unity 包版本自动推断：

```powershell
python -m pip install --upgrade "git+https://github.com/codingriver/upilot.git@<TARGET_SERVER_REF>#subdirectory=upilotserver~"
```

### 同步 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. 确认 `python --version` 为 3.11 或更高。
2. 重新执行 Python 依赖安装命令。
3. 点击 **自动修复**。
4. 仍未恢复时打开 **高级设置**，检查 Python 入口、HTTP/WS 端口和诊断日志。

### 提示找不到 Python

安装 Python 3.11 或更高版本，并确保 Python 已加入 PATH。重新打开 Unity 后再次启动 UPilot。

Windows 可以执行：

```powershell
where.exe python
python --version
```

macOS 或 Linux 可以执行：

```bash
which python3
python3 --version
```

### 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 文件。

### 统一模板生成与同步

维护顺序固定为：修改 `skills/upilot-unity-mcp/` 的权威模板/资源 → 递增
`template-manifest.json` 版本 → `scripts/render_skill_pack.py --write` →
`--check` 和 `scripts/check_skill_pack.py --mode source` → 项目同步 → 两份 installed 校验。
Agent 行为变化递增 `agentRulesVersion`，任意分发 Skill 文件变化递增 `skillPackVersion`；
不直接维护生成的 `SKILL.md`、`agents/openai.yaml` 或 Agent 参考文档。

`unity_agent_integrations_check()` 只读检查全部五个目标；
`unity_agent_integrations_sync(apply=false)` 预览，`apply=true` 使用项目写入授权同步。
在线模板源是当前 Unity 安装的 UPM 包，不是 Server EXE 内置副本。
旧 `unity_agent_rules_check/install` 仍只处理项目 `AGENTS.md`。

| 权威源 | 项目目标 | 管理边界 |
|---|---|---|
| `AGENTS.md.template` | `AGENTS.md`、`.cursor/rules/upilot-unity-mcp.mdc` | 仅 UPilot 区块，保留外部字节/BOM |
| 安装器固定引用 | `CLAUDE.md` | 仅 `@AGENTS.md` 受管区块 |
| `SKILL.md.template`、`agents/openai.yaml.template`、资源 | `.agents/skills/upilot-unity-mcp/` | 全目录，Codex/Cursor/OpenCode 共用 |
| 同上 | `.claude/skills/upilot-unity-mcp/` | 全目录，Claude 独立 |

离线使用 `scripts/install_upilot.py --integrations-only --unity-project <项目> --upilot-dir <源码> --dry-run --json`，
移除 `--dry-run` 后执行；不修改依赖、Python 环境或 MCP 配置。
项目端口取显式参数、项目配置、manifest 默认值的首个有效来源。
保存模板不代表已同步项目，不新增后台文件监听。当前测试项目仍继承 `../../AGENTS.md`，
父规则与 `AGENT_Distill.md` 不纳入 UPilot 模板覆盖。

同步使用 C#/Python 共用项目文件锁，暂存和回滚位于 `.upilot`、Skill 发现路径之外。
受管区块标记损坏、路径越界或锁占用会明确失败；备份失败不覆盖原目标，
替换/最终验证失败会回滚该目标，其余独立目标继续并汇总结果。
无内容/上下文差异则不改文件时间戳。历史备份不自动清理。

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

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

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

## 卸载

1. 在 `UPilot > 高级设置` 中点击红色 **停止**，并确认停止。
2. 在 Unity Package Manager 中选择 **UPilot**，点击 **Remove**。
3. 如不再使用 Python 服务，可执行：

```powershell
python -m pip uninstall upilot-mcp
```

4. 如需彻底清理项目配置，请只删除各配置文件中的 `upilot` MCP 项，不要直接删除包含其他服务的整个配置文件。
5. 可选清理 UPilot 管理的规则和 Skill：

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

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

## Automation 公共支撑 API

UPilot 提供 Editor-only、业务无关的 Automation API：`AutomationCatalog` / `AutomationSelection`、`UPilotConsoleCaptureApi`、`AutomationLogPolicy`、`AutomationReportWriter` 和顺序 Step 执行器。所有 Automation 类型、方法和脚本名称不带版本后缀；JSON 的 `version/apiVersion` 与历史数据契约保留。

步骤显式使用 `[AutomationStep("id")]` 并实现 `IAutomationStep`，推荐继承 `AutomationStepBase`。七个生命周期方法只接收字符串，统一为 `runId, instanceId, contextJson, arguments`；`GetError` 在最后一个 `arguments` 前增加 `errorCode`。校验、轮询、错误、清理和恢复返回严格校验的 JSON，项目无需引用 Context、Result、Status 或 Error DTO。

UPilot 在程序集加载后维护同一注册快照，持有全量预检、执行状态及持久化；Skill 查询 Catalog、选择固定流程模板与 Case 后提交 `jobSpec.stepPlan`，继续使用 `unity_operation_*`。业务 Step 只实现业务动作与恢复，不再维护另一个执行器。状态查询不推进步骤；域恢复只调用 Restore，不重放 Execute。检查点与共享值通过基类或服务的 `SaveCheckpoint/SaveSharedValue` 在可写生命周期回调中同步持久化，`arguments` 始终原样传递。

域初始化尚未完成时，Step 查询返回 `STEP_SERVICE_INITIALIZING`，Operation 继续只读观察原 run。初始化完成后仍找不到身份才返回 `STEP_RUN_IDENTITY_MISMATCH`；Editor 重启则保留 `STEP_EDITOR_RESTARTED/RecoveryRequired`。查询不会触发 Initialize、Restore 或 Execute，也不会自动解除已有恢复门禁。

业务附件通过基类或服务的 `RegisterArtifact(runId, instanceId, kind, path)` 在当前可写生命周期回调中登记。文件必须已完成且位于工程内；框架保存身份、大小和 SHA256，收尾再次校验并放入统一 `attachments` 索引。Finally 可在前序清理失败后登记恢复证据，但不能因此消除 `RecoveryRequired`；项目不需要引用报告 DTO。

Console 收尾摘要保留至多10条阻断样本、精确序号/步骤/规则及截断标记，完整分类写入不可变的 `console-policy.json` 哈希产物。状态中的 `domain.logSummary` 不读取文件或推进执行；Policy 失败不覆盖此前业务首错。更新 Server 后须验证公开 Operation 附件收集，不能以磁盘源码或 Bridge 编译通过代替部署验证。

新报告从同一冻结 summary 导出 `report.txt` 和 `timing.csv`，先写导出文件，再由 `summary.json` 提交整组产物；数据字段 `exportVersion=1`，旧报告不补写。时序区分执行与 Cleanup，未开始项不伪造耗时。Finalizing 域恢复沿用持久报告快照及完成时间，重新校验附件哈希；文件缺失或变化保留首错并要求恢复，不重放步骤或修复冻结文件。业务指标仍是项目附件，报告提交不代表 Operation-owned Capture 已停止。导出与冻结恢复已有规范工程定向证据，当前覆盖和未执行矩阵见集成方案。

重开报告以单次读取的原始 summary 字节作为校验基线，兼容历史 UTF-8 BOM，不重写文件。打开后删除、改写或仅增删 BOM 都会阻止发布产物和重复完成；不能通过文本重新编码或忽略 BOM 放宽不可变证据检查。相关回归已在规范工程定向通过。

通过既有 `unity_operation_*` 的 `jobSpec.stepPlan` 提交列表，执行前检查完整注册与参数，执行器统一负责轮询、超时、取消、Finally、域恢复和证据收尾。内置`upilot.open_scene/enter_play_mode/enter_edit_mode/wait_seconds/console_capture_start/capture_snapshot`六个业务无关步骤；项目只负责业务Step、断言和恢复，固定组合由Skill维护。项目可选适配使用`#if UNITY_EDITOR && UPILOT`，不新增运行时依赖或平行MCP start/status工具。

计划自有Capture必须第一项且只启动一次，Operation明确`consoleCapture.enabled=false`，禁止双重所有权。启动Step清理不提前停采；全部Finally之后包确认停止及原始文件，再处理最终日志区间、Policy和报告。私有凭据不进入公开状态，未知身份或未确认释放保持RecoveryRequired。其它不含Capture Step的计划仍可借用Operation Capture。

截图Step及基类字符串接口`BeginSnapshotJson/PollSnapshotJson/CancelSnapshotJson/SnapshotErrorJson`共用包内生命周期。默认可信GameView1280x720、3秒等待、2秒取消确认；保存启动意图后再调用Snapshot，域恢复不重放。验真绑定原文件大小/哈希及run目录，即使项目未轮询，执行器也确认资源完成后才推进。业务只决定取证时机和画面能否证明断言。

接口、边界、接入时序和验收证据见 [Automation 公共支撑能力集成方案](Documentation~/Automation-Integration-Plan.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)