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 或更高版本：

python --version

如果系统提示找不到 python，请先安装 Python，安装时勾选 Add Python to PATH。

2. 安装 Unity 包

在 Unity 中打开：

Window > Package Manager

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

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。

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

3. 可选：安装 Python MCP Server

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

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

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

cd upilotserver~
python -m pip install -e .

4. 在 Unity 中配置并启动

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

UPilot > 打开 UPilot

然后：

1. 选择你正在使用的 Agent：Codex、Claude Code、Cursor 或 OpenCode，支持多选。

2. 点击 配置并启动。

3. 等待界面显示 已就绪。

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

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

5. 重启 Agent 并验证

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

然后对 Agent 说：

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

成功时应满足：

• connected: true

• serverReady: true

• 返回的 Unity 工程路径与当前项目一致

现在可以开始使用 UPilot。

Related MCP server: Unity MCP Server

受控执行工具

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。

环境要求

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：

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

https://github.com/codingriver/upilot.git#<STABLE_RELEASE_TAG>

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

io.github.codingriver.upilot

方式二：手动修改 manifest.json

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

{
  "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：

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

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

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. 等待状态从“正在启动”变为“已就绪”。

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 地址

默认地址是：

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

项目配置文件：

.codex/config.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

项目配置文件：

.mcp.json

配置内容：

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

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

.claude/skills/upilot-unity-mcp

Cursor

项目配置文件：

.cursor/mcp.json

配置内容：

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

Cursor 的 UPilot 规则位于：

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

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

.agents/skills/upilot-unity-mcp

OpenCode

项目配置文件优先使用：

opencode.json

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

{
  "$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 共享：

.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 状态。

在浏览器中检查服务

打开：

http://127.0.0.1:8011/health

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

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

在 Agent 中确认

发送：

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

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

第一次使用 UPilot

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

查看项目与场景

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

检查编译错误

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

检查 Console

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

修改场景对象

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

修复代码并编译

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

运行测试或长任务

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

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

主界面说明

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

主界面优先显示整体状态、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：

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 元数据分别只维护以下源模板：

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}}；未知、缺失或残留占位符会直接失败。

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

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。

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

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 版本。

高级设置、停止与诊断

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

UPilot > 高级设置

高级设置提供运行检查、重启、红色停止按钮、端口、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 中的版本标签改为目标版本，例如：

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

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

更新 Python 包

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

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 可以执行：

where.exe python
python --version

macOS 或 Linux 可以执行：

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。

离线使用 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 客户端通信，浏览器检查请访问：

http://127.0.0.1:8011/health

卸载

1. 在 UPilot > 高级设置 中点击红色 停止，并确认停止。

2. 在 Unity Package Manager 中选择 UPilot，点击 Remove。

3. 如不再使用 Python 服务，可执行：

python -m pip uninstall upilot-mcp

4. 如需彻底清理项目配置，请只删除各配置文件中的 upilot MCP 项，不要直接删除包含其他服务的整个配置文件。

5. 可选清理 UPilot 管理的规则和 Skill：

.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 公共支撑能力集成方案。

UPilot Flow

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

• 默认关闭，不影响 UPilot 核心功能。

• 仅支持 Unity 6 或更高版本。

• 适合需要通过 YAML 编排复杂 EditorWindow 操作的高级场景。

需要使用时请查看 UPilot Flow 文档。

UPilot 追踪器

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

需要使用时请查看 UPilot 追踪器文档。

使用建议

• 第一次连接先执行只读检查，再进行场景或资源修改。

• 让 Agent 在修改前确认目标场景、对象或资源。

• 对删除、覆盖、批量修改、构建发布等操作明确要求二次确认。

• 使用版本控制，并在重要操作前保存 Unity 场景和项目改动。

• 同时打开多个 Unity 项目时，每次操作前检查连接的工程路径。

获取帮助

• 项目主页：https://github.com/codingriver/upilot

• 版本记录：CHANGELOG.md

• 问题反馈：GitHub Issues

• License：MIT