# UE MCP GUI V6.5 — 完整项目 README / 从零开始的开发与部署记录

> **项目定位**：PC1 使用 Python GUI / MCP 控制 PC2 的 Unreal Engine 5.8，利用 SMB 任务队列让 PC2 本机执行 C++ 编译与 Windows 游戏打包；最终在 PC3 等其他电脑独立运行游戏。  
> **当前交接基线**：`UE_MCP_GUI_V6_5_COMPLETE_PC1_PC2.zip`，PC1 GUI V6.5、PC2 Packaging Engine V6.5.0、原 C++ Build Manager V6.3.3。  
> **资料整理日期**：2026-10-31；交接目标为 Codex。  
> **务必先读**：同目录的 [HANDOFF.md](HANDOFF.md) 与 [CODEX_PROMPT.md](CODEX_PROMPT.md)。

## 0. 证据范围与最重要的注意事项

本文依据现有对话记录、历次源代码压缩包、V1–V6.5 的中文说明、MCP 测试总结，以及用户提供的 UE 打包日志整理；并检查了 **V6.5 ZIP 中实际存在的源文件与函数**。

- **已由用户实际演示/反馈**：PC1 ↔ PC2 MCP 成功；17 项 GUI 测试全通过；武侠村庄能够创建与 PIE 游玩；V4 曾显示 17 Actor / 102 Key；PC2 网络 Worker 能回传实际编译日志；曾在实机 UAT 日志中看到 `WuxiaMCPRuntime.cpp`、`WuxiaQuestDirector.cpp`、`WuxiaQuestHUD.cpp` 编译及 `MyProject4.exe` 链接成功。
- **实际留存的 2026-10-30 UAT 日志**：C++ Build 成功，但当时 `Cook` 失败（ExitCode 25）；随后用户表示修复完毕并继续 V6.5。**目前交接资料中没有 PC2 最新的 V6.5 `.report.json`、真实 Shipping/Development EXE 截图及在 PC3 的独立运行报告**。Codex 不应凭 ZIP 里的模拟测试认定成品已通过全部实机测试。
- **V6.5 包是开发工具源码快照，不是 Unreal 项目完整备份**；不含 PC2 真正的 `MyProject4.uproject`、Content 资产和用户已改动的插件代码。必须另外从 PC2 取得真实项目与最新配置/Manifest。
- 不要拿安装包内的示例 `WuxiaMCPRuntime/` 覆盖 PC2 项目中已经验证过的插件源码。任何合并先比较 diff 并备份。
- 默认不使用 SSH；**MCP 操作编辑器；SMB 传任务；PC2 本机 UBT/UAT 真正执行编译**。只复制网络文件不能让 PC1 自动执行 PC2 的本地程序。

## 1. 最初的构想与三台电脑的定位

| 机器 | 硬件 / 软件 | 任务 | 是否需要 Unreal 安装 |
|---|---|---|---|
| **PC1：开发控制台** | RTX PRO 4500；Windows；Python 3 + Tkinter；曾计划搭配 DeepSeek Harness (DSH) / Qwen3.8 FN | MCP 场景控制、17 项诊断、V1–V6 场景/任务工具、10 项 C++ 和 9 项 Packaging 检测、提交 SMB 任务、日志与结果显示 | **不需要** |
| **PC2：Unreal 工作站** | RTX 5060 Ti；Windows；UE 5.8、MCP Experimental、Visual Studio Build Tools、Windows SDK；IP `192.168.0.204` | 编辑/保存 `MyProject4`、运行 MCP Server；原生编译 `WuxiaMCPRuntime`；运行 UAT BuildCookRun；生成 Windows 发布包 | **需要** |
| **PC3：游戏/内容工作站** | GTX 1060；Codex | 最初定位为剧情、NPC、对白和游戏设计；亦可用作打包游戏独立测试机。未来可负责继续开发 | **单纯试玩不需要** |

最初目标是：**PC3 用 Codex 创作内容 → PC1 AI / Python GUI 编排 → PC2 Unreal 实际建造和运行 → Windows EXE 发布**。项目先把 PC1–PC2 的遥控与编译打通，再逐步实现游戏逻辑。AI Agent 尚不是运行 GUI 的前置条件。

```text
                       场景编辑模式（PC2 Unreal Editor 开启）
 PC1  UE_MCP_GUI_V6_5.py  ──HTTP MCP /mcp:8999──▶ PC2 Unreal Engine 5.8
   │                                                         │
   │  编译/打包模式（PC2 Unreal Editor 关闭）                   │
   └─JSON request─▶ SMB \\192.168.0.204\UEBuildQueue ◀──────┤
                          │                                   │
                          ▼                                   │
                     PC2_Build_Worker.py ──▶ UBT / UAT ───────┘
                          │
                          ├─ results/<job>.log / .status.json / .report.json
                          └─ C:\UEGameReleases\MyProject4_<profile>_<job>\Windows\...
                                                         │
                                                         ▼
                                                PC3 运行 MyProject4.exe
```

**模式互斥**：MCP 17/17 要求 Editor 正在运行；C++ Build 10/10 和 Packaging 9/9 要求 **Editor 已关闭**。不要强行设计一个必须同时满足 17+10+9 的总锁。

## 2. 从第一天至 V6.5 的完整时间线与设计演进

| 版本/阶段 | 实际工作、关键决策与限制 | 主要源码/输出 |
|---|---|---|
| **阶段 0：网络 / MCP 验证** | PC2 UE Experimental MCP 监听 `0.0.0.0:8999`；浏览器打开根 `/` 返回 `route_handler_not_found` 是正常的；Inspector Web UI 曾提示 Forbidden，但通过 `curl.exe` POST `initialize` 与 MCP Inspector CLI 真正连通 `/mcp`。协商 MCP `2025-11-25`，`tools/list` 对外暴露 3 个元工具。 | `UE_MCP_完整测试总结.md`、`UE_MCP_Create_Cube.ps1` |
| **V1：17/17 MCP GUI** | PC1 GUI 验证 TCP、MCP Session、Toolset、临时 Cube 创建→修改→读回→删除。用青色 PASS/红色 FAIL；AI Agent 在 17/17 之前锁定。验证不意味着能自动制作完整游戏。 | `UE_MCP_GUI.py` |
| **V2：武侠村庄灰盒** | 用引擎 BasicShapes 在 Level 建 10 间民居、主街、河流、石桥、门楼、树木、灯笼、PlayerStart；每个 Run 写 Manifest；会创建许多 Actor，但不会自动保存关卡。重复建造/旧 Manifest 曾导致冲突，因此后续改为分次独立 Manifest。 | `UE_MCP_Build_Wuxia_Village.py/.ps1`、`UE_MCP_GUI_Wuxia_Integrated_v2.zip` |
| **V3：材质与场景增强** | 原村庄不重建；装饰、屋脊、摊位、石板路、水纹、6 名静态 NPC；根据资产可用性选 SkeletalMesh 或几何占位；新增 `Enhance_*.json`。材质/灯光可修改旧对象，撤销新增 Actor 不等于撤销所有材质改动。 | `UE_MCP_GUI_V3.py` |
| **V4：Sequencer 动画** | 创建 Level Sequence，尝试两个 NPC 的 Transform 路线及河流平移水纹；用关键帧读回；曾报告 **17 Actor、102 Key**。不能将此理解为运行时导航、骨骼步行或真实水动力。PC1 可预览 NPC 对话 JSON，但不是游戏内对白。 | `UE_MCP_GUI_V4.py` |
| **V5：PIE + 任务地标** | 开始/停止 PIE、查询运行状态、截图；新增茶摊/石桥/守卫三处任务地标（合计 6 个 Actor）。Blank 项目曾出现无 Third Person Pawn、画面黑；更换为 Third Person 模板后可正常游玩。 | `UE_MCP_GUI_V5.py` |
| **V5.1：PIE 故障诊断** | 初次 `StartPIE` 有 `PIE ended before warmup completed`；修正 warmup、避免强制不适当的 spawn；诊断后确认真正的 GameMode / Pawn 是关键。 | `UE_MCP_GUI_V5_1.py`、`PIE_Diagnostics_20261028_174915.json` |
| **V6：运行时游戏互动** | 新增 C++ `WuxiaMCPRuntime` 插件和 `AWuxiaQuestDirector`、`UWuxiaQuestHUD`：E 键近距离互动、HUD、三阶段 **石桥寻笛**。插件需编译、加载后才能经 `/Script/WuxiaMCPRuntime.WuxiaQuestDirector` 生成 Actor；未加载时曾报 invalid Class。 | `UE_MCP_GUI_V6.py`、`WuxiaMCPRuntime/` |
| **V6.2：编译管理** | 曾考虑从 PC1 SSH 连接 PC2 编译；**用户明确不希望引入 SSH**。 | `UE_MCP_GUI_V6_2_Integrated_Builder.zip` |
| **V6.3：SMB 自动编译** | 固定项目路径存在 PC2 `worker_config.json`；PC1 只提交允许的请求 JSON；PC2 Worker 在本机执行工具，写回状态和编译日志。 | `ue_shared_build_client.py`、`PC2_Build_Worker.py`、`ue_v6_build_manager.py` |
| **V6.3.1：C++ 10/10 Readiness** | 增加 Unreal/UBT/UAT/VS/MSVC/Windows SDK/.NET10/NetFxSDK/插件源码/Editor Closed 十项预检。曾发现 `.NET Framework SDK 4.8+`（后检测到 **4.8.1**）。 | `UE_MCP_GUI_V6_3_1_Build_Readiness_10of10.zip` |
| **V6.3.2：WinError 206** | PowerShell `-EncodedCommand` 长度超过 Windows 命令行限制；改用临时 `.ps1` 与 `-File` 短参数。 | `ue_v6_build_manager.py` |
| **V6.3.3：Worker 二次诊断** | 曾仍出现 `[WORKER] preflight ... [WinError 206]`；增加进程启动命令/环境变量长度诊断、精简继承环境重试、Worker 模块版本/路径验证。 | `UE_MCP_GUI_V6_3_3_COMPLETE_PC1_PC2.zip` |
| **首次打包探索** | UE Editor 的 Windows Development `BuildCookRun` 成功编译并链接游戏本体/运行时插件，但一次 Cook 失败：`GameFeatureData` Asset Manager 错误、Cook ExitCode 25；曾有 ZenStore 404 / Cook 阶段长时间 shader/保存等待，不可在无完整日志时断言唯一根因。 | `粘贴的文本 (1)(20261030-013144).txt` |
| **V6.5：一键 Windows 打包** | 增加独立 Packaging 9/9 预检、Development/Shipping、RunUAT BuildCookRun、Build→Cook→Stage→Package→Archive、可选 ZIP、每 Job 独立日志与发布目录。PC1 仍无须 UE/SSH。 | `UE_MCP_GUI_V6_5_COMPLETE_PC1_PC2.zip` |

**特别强调**：版本表描述目标、源码与用户反馈；哪些是“离线模拟”、哪些来自“真实 PC2 日志”，需继续在报告中区分。早期 V1 的测试总结写于用户 17/17 成功反馈**之前**，因此其“尚未实测创建 Cube”属于当时的历史状态，不可把它当作当前状态。

## 3. MCP：从失败现象到实际连通

### 3.1 PC2 设置

- UE 5.8 编辑器项目：`MyProject4`（用户从 Blank 迁移到可控的 Third Person 项目）。
- Unreal MCP 插件：Experimental，允许对应 Toolsets；监听：`0.0.0.0:8999`；实际请求：`http://192.168.0.204:8999/mcp`。
- PC2 端口检查：

```powershell
Get-NetTCPConnection -LocalPort 8999 -State Listen |
  Select-Object LocalAddress, LocalPort, OwningProcess
```

- 仅向可信局域网 PC1 放行 Windows Firewall 端口 8999，**绝不直接暴露到公网**。MCP 实验接口不应假定有认证。
- 编辑器开启时才能使用 MCP；Cook / 编译时关闭编辑器，意味着原先 17 项测试不会保持在线。

### 3.2 PC1 直接诊断

```powershell
Test-NetConnection 192.168.0.204 -Port 8999

# 可用 MCP Inspector CLI（依赖 Node.js / npm）：
npx @modelcontextprotocol/inspector --cli http://192.168.0.204:8999/mcp --transport http --method tools/list
npx @modelcontextprotocol/inspector --cli http://192.168.0.204:8999/mcp --transport http --method tools/call --tool-name list_toolsets --tool-args-json '{}'
npx @modelcontextprotocol/inspector --cli http://192.168.0.204:8999/mcp --transport http --method tools/call --tool-name describe_toolset --tool-arg toolset_name=editor_toolset.toolsets.scene.SceneTools
```

注意：Windows PowerShell 给 `--tool-args-json '{"..."}'` 时曾发生引号传递错误，单个参数优先使用 `--tool-arg toolset_name=...`。浏览器 GET `/` 返回 HTTP Server 的找不到 Route 不是服务故障；Inspector Web UI Forbidden 也曾被 CLI 的真实成功排除为必要阻塞。

### 3.3 MCP 工具结构

外层 `tools/list` 的三个元工具：`list_toolsets`、`describe_toolset`、`call_tool`；内层工具集包括：

- `editor_toolset.toolsets.scene.SceneTools`：`get_current_level`、`find_actors`、`add_to_scene_from_asset`、`add_to_scene_from_class`、`remove_from_scene`、`save_actor` 等。
- `editor_toolset.toolsets.actor.ActorTools`：`get_actor_transform`、`set_actor_transform`、`set_label`、`get_label` 等。
- 资产 / 材质 / Object / Blueprint / Sequencer / Keyframing / EditorAppToolset / Logs 等可扩展工具。
- Actor 引用使用 `{"refPath":"..."}`；`SceneTools.find_actors` 曾要求同时提供 `name`、`tag`、`collision_channels`；应以 **实时 describe_toolset Schema** 为准，而非写死凭记忆猜工具参数。

## 4. PC1：17 项 MCP 检查的真实内容

使用 V6.5 PC1 GUI `TEST_LABELS`，依次为：

| # | 检测 | 判定标准/目的 |
|---|---|---|
| 01 | TCP 到 PC2:8999 | socket 真正可连通 |
| 02 | HTTP MCP initialize | JSON-RPC 握手与 capabilities |
| 03 | Session ID | 收到 `Mcp-Session-Id` |
| 04 | initialized | 发送 `notifications/initialized` |
| 05 | tools/list | 3 个核心 MCP Tools 可用 |
| 06 | list_toolsets | 找到 SceneTools 与 ActorTools |
| 07 | SceneTools Schema | 必需工具和 inputSchema 可见 |
| 08 | ActorTools Schema | 必需工具和 inputSchema 可见 |
| 09 | get_current_level | 当前关卡真实可读 |
| 10 | find_actors | 唯一临时 Actor 尚不存在 |
| 11 | add_to_scene_from_asset | 创建 `/Engine/BasicShapes/Cube`，取得 Actor `refPath` |
| 12 | set_actor_transform | 更新坐标、旋转与 Scale |
| 13 | get_actor_transform | 读回变换并比较数值 |
| 14 | set_label / get_label | 改名并读回 |
| 15 | find_actors | 再次找到测试 Actor |
| 16 | remove_from_scene | 删除测试 Cube |
| 17 | find_actors | 确认测试 Actor 不再存在 |

**测试会实际创建和删除临时 Actor**。通过 17/17 才解锁 AI Agent / 相关编辑器操作；场景修改会使验证失效，重新运行测试。若测试中途失败，先检查是否有残留临时 Actor；不要全局清空 Level。

## 5. 构建武侠村庄：逐版操作与输出

### 5.1 开发关卡预备

1. PC2 使用 Third Person 模板打开可玩项目；在 Level 中配置 PlayerStart、GameMode、Pawn/Input；不要把一个 Blank 模板中的默认 Spectator 当作 Third Person 游戏。
2. 先备份 / Save Level As（例如 `/Game/Maps/WuxiaVillage`），确保使用同一张含村庄的关卡；后续所有 Manifest 对关卡及 Actor 有关联。
3. PC1 启动 GUI，MCP 17/17 PASS 后开始建造；创建 Actor 不会自动持久保存到 `.umap`，完成时 **PC2 File → Save All**。

### 5.2 V2 原村庄

- 创建 10 间民居、道路、石桥、河流、树木、门楼、灯笼、PlayerStart，默认使用引擎基础 Shape；可尝试材质工具。
- 执行 `UE_MCP_Build_Wuxia_Village.py` 或 PC1 GUI 的「创建武侠村庄」。
- 基础对象类似 `WUXIA_DEMO_House_01_*`、`WUXIA_DEMO_StoneBridgeDeck`；失败或停止后可能有部分对象已创建。
- 记录文件包括早期 `WUXIA_Village_Manifest.json` 和后期 `~\.unreal_mcp_gui\villages\Village_<run_id>.json`。**Manifest 是清理的依据，不是 UE 资产格式**。

### 5.3 V3 美化

- 选择正确的 `Village_*.json` → 应用美化/6 NPC/屋檐/路砖/水纹 → 获得 `Enhance_*.json`。
- 只有新增美化 Actor 才会被该 Manifest 清理；对旧 Actor 直接修改的材质、光照、资产可能需要额外手动回退。
- 有 SkeletalMesh 则尝试引用项目已有角色；没有则降级为基础几何 NPC，占位 NPC ≠ 真实角色骨骼/AI。

### 5.4 V4 Sequencer

- 选择 `Enhance_*.json` → 创建 Level Sequence / NPC 位移和河流水纹位移 → 回读 Keyframes。
- `V4_Sequence_*.json` 跟踪资产与 Actor。动画 0、150、299 帧（实际秒数与帧率有关）。
- 保存 Sequencer Asset 与 Level；这是预览用 Transform 动画，**不保证打包后 NPC 自主巡逻**。

### 5.5 V5 / V5.1 PIE 与路标

- 在茶摊、桥、守卫三个地点创建共 6 个 Quest 路标 Actor，并写 `V5_Waypoints_*.json`。
- 进入 PIE 时，若遇 `PIE ended before warmup completed`，检查 `warmupSeconds`、spawn 参数、地图/World Settings/GameMode/Pawn；已在 V5.1 允许 warmup=0 和不强制 spawn。
- PIE 中先点游戏视口让其获取键盘焦点，测试 WASD/鼠标/空格。编辑器截图/运行时截图的实现需以实际 API 为准。

### 5.6 V6 Runtime 三阶段「石桥寻笛」

- 插件：`Plugins/WuxiaMCPRuntime`，模块必须 `Type=Runtime`；C++ 类 `AWuxiaQuestDirector`、`UWuxiaQuestHUD`。
- MCP 类路径：`/Script/WuxiaMCPRuntime.WuxiaQuestDirector`；只有插件成功编译、启用并被 Editor 加载后才能 `add_to_scene_from_class`。`invalid Class` 提示通常代表未加载/未编译/引用错误，不是 8999 断线。
- 任务三阶段：**茶摊（`-1650,-520`）→ 石桥（`770,-430`）→ 村口守卫（`-2250,510`）**，默认互动半径 450 cm。`AWuxiaQuestDirector` 在 BeginPlay 搜索 `WUXIA_V5_` 路标，找不到时使用默认位置。
- E 键在邻近当前目标时推进任务；HUD 为 C++ 动态创建的 UMG 文本。没有跨场次存档，停止 PIE 并重启会重置；没有 AIController、Behavior Tree、复杂对话选择、自动路径规划。
- PC1 的 V6 部署前需要 MCP 17/17；**创建 Actor 后 PC2 一定执行 Save All**，否则打包关卡可能没有 Director。

## 6. PC2 C++ 10/10：Build Readiness（编辑器关闭）

实际 V6.5 `ue_v6_build_manager.py`（版本字符串 V6.3.3）检查：

1. Unreal Engine 5.8 `Build.bat` + `.uproject` / `Build.version`；
2. `UnrealBuildTool.dll`；
3. `AutomationTool / RunUAT.bat`；
4. VS Build Tools + vswhere；
5. 实际 MSVC x64 `cl.exe`；
6. Windows SDK headers + `rc.exe`；
7. UE 内置或系统 `.NET 10 SDK`；
8. .NET Framework `4.8+` NetFxSDK（历史上 PC2 安装/检测为 4.8.1）；
9. `WuxiaMCPRuntime` 源代码与描述文件；
10. `UnrealEditor.exe` 已关闭。

**强制 10/10**；PC1 GUI 的批准有效期 **5 分钟**，PC2 Worker 在实际执行编译前重新检查。旧 `-EncodedCommand` 导致 WinError 206 的问题已经在 V6.3.2/3 改为短 PowerShell `-File`；若重现必须确认正在运行的 Worker 文件与实际加载的 `ue_v6_build_manager.py` 版本，不是仅覆盖磁盘文件。

常见历史错误：

- `Could not find NetFxSDK install dir` → PC2 安装对应 .NET Framework SDK（不是 .NET 10 Runtime）。
- `MyProject4 could not be compiled` → 看完整 UBT / UAT 错误，别仅凭错误弹窗判断。
- `WinError 206` → 检查是否旧 Worker、命令行超过 32767 字符、继承环境变量块过大、`-File` 是否实际生效；V6.3.3 记录 Launch 诊断。
- `UnrealEditor Closed: Found 1` → File → Save All 后正常退出 Editor；不要强制结束未保存进程。

## 7. PC2 Windows 游戏打包 9/9：V6.5

| 检测 ID | 条件 |
|---|---|
| `engine_version` | UE `Build.version` 是 5.8 |
| `project` | 固定 `.uproject` 真实存在 |
| `uat` | `RunUAT.bat` 存在 |
| `compiler` | MSVC C++ `cl.exe` 存在 |
| `windows_sdk` | Windows SDK `Windows.h` + `rc.exe` 存在 |
| `default_map` | `Config/DefaultEngine.ini` 或 `DefaultGame.ini` 中 `GameDefaultMap` 指向实际 `Content/.../*.umap` |
| `runtime_plugin` | `WuxiaMCPRuntime.uplugin` 中 Runtime 模块存在 |
| `editor_closed` | 没有 `UnrealEditor.exe` 进程 |
| `output_root` | PC2 Release 路径不在 Engine / Project 内、可写且最少 **12 GiB** 空间 |

**9/9 PASS 才开放 GUI 一键打包，PC2 实际执行时再做一轮预检。** 9/9 不涵盖全部 Cook 错误，不能等价为“UE 可以成功构建所有资源”。

PC2 `ue_game_packager.py` 构建 UAT 命令的关键参数：

```text
RunUAT.bat BuildCookRun -nop4 -utf8output -project=<PC2固定uproject>
  -platform=Win64 -clientconfig=Development|Shipping
  -build -cook -stage -package -archive -archivedirectory=<PC2固定Release下独立Job目录>
  -pak -iostore -compressed -prereqs -unattended -nocompileuat
```

成功标准：**UAT return code = 0，且发行目录检测到 `MyProject4.exe`，且有有效 `.pak` 或 `.utoc`+`.ucas` 文件**；可选 ZIP 使用 Zip64，压缩完整目录而非只有 EXE。每次新 Job ID 创建新目录，不覆盖旧版本。

真实打包的已知历史失败（2026-10-30）：C++ 成功，`Cook` ExitCode=25；日志中有 GameFeatureData Asset Manager 配置报错，也出现 ZenStore 404 和等待资源保存/Shader。重新打包时应看完整 Cook log 中**最早的实质性错误**；不能依赖仅含 `UnknownCookFailure` 的最终结论。

## 8. PC1/PC2 的完整安装与每日操作

### 8.1 PC2（先完成）

实际用户项目路径（当时日志）：

```text
Engine:  C:\Program Files\Epic Games\UE_5.8
Project: C:\Users\karuv\OneDrive\Documents\Unreal Projects\MyProject4\MyProject4.uproject
MCP:     http://192.168.0.204:8999/mcp
Queue:   D:\UE_BuildQueue       # 示例；应以 PC2 worker_config.json 实值为准
Release: C:\UEGameReleases       # 示例/默认；应以 PC2 worker_config.json 实值为准
```

1. PC2 安装 Python 3（命令 `py -3` 可用）、UE 5.8、Visual Studio Build Tools + MSVC C++、Windows SDK、.NET Framework SDK；MCP 插件在编辑器内可启用。
2. **备份真实 MyProject4 项目、已修正的 C++ 插件、Level/Content**。初次搭建项目时用 Third Person 模板，不要错误选 Blank 模板作为可游玩场景。
3. 从 `source/UE_MCP_GUI_V6_5_Package/PC2`（本交接包）将脚本放至本机 PC2 工具目录；`PC2_Worker_Setup_GUI.py` 可选择真正的 Engine / `.uproject` / Queue / Release 路径。
4. 运行 `Start_PC2_Setup.bat`，点击「保存配置并建立队列」；**不要将旧 `worker_config.json` 覆盖成示例**。如果项目插件已存在，绝不要将打包演示源码覆盖进去。
5. 将 PC2 实际 queue 目录通过 SMB 共享为 `UEBuildQueue`，授权 PC1 的指定 Windows 帐户对队列有读写/修改权限；共享与 NTFS 权限都要设置。Release 可选只读共享为 `UEGameReleases`。
6. 双击 `Start_PC2_Build_Worker.bat`，确认 `[READY] Packaging Engine V6.5.0`。只运行一个 Worker 进程。
7. 场景开发时打开 Editor，并在 UE 中确认 MCP 8999；要编译 / 打包时，先 **File → Save All → Exit**，Worker 保持运行。

**PC2 `worker_config.json` 示例**（这是模板，不是实机已读取到的私有配置）：

```json
{
  "engine_root": "C:\\Program Files\\Epic Games\\UE_5.8",
  "project_uproject": "C:\\Users\\karuv\\OneDrive\\Documents\\Unreal Projects\\MyProject4\\MyProject4.uproject",
  "queue_dir": "D:\\UE_BuildQueue",
  "release_dir": "C:\\UEGameReleases",
  "poll_seconds": 0.8
}
```

**提醒**：`PC2/worker_config.example.json` 的原始文件只列出 `engine_root / project_uproject / queue_dir / poll_seconds`；V6.5 Setup GUI 会新增 `release_dir`。不允许 PC1 提交 `project`、`engine`、`output` 或自定义 Shell/UAT 参数覆盖 PC2 固定路径。

### 8.2 PC1

1. PC1 安装 Python 3（Tkinter 在 Windows 通常随 Python 安装）；将 `source/UE_MCP_GUI_V6_5_Package/PC1/` 放在本地目录，例如 `D:\UE_MCP_GUI_V6_5`。
2. 双击 `Start_UE_MCP_GUI.bat`（内部 `py -3 UE_MCP_GUI_V6_5.py`），不需要 `pip install`，也不需要 Unreal/Visual Studio。
3. GUI 设定：`192.168.0.204`、`8999`、`/mcp`；Build Share 填 `\\192.168.0.204\UEBuildQueue`；Output Share 可选 `\\192.168.0.204\UEGameReleases`（用于浏览）。
4. **Editor Mode**：PC2 打开 UE，PC1 运行 17/17 检测，再建造 / 修改 / 部署交互；保存关卡后才退出。
5. **Build Mode**：PC2 Editor 关闭，PC1 先检查 Worker 再做 10/10，之后「一键编译 V6 插件」；编译成功后打开 UE 重新加载 C++，再执行 17/17 检测。
6. **Package Mode**：PC2 Editor 关闭，PC1 选择 Development（优先）或 Shipping、可选 ZIP；点击 9/9；通过后点击 ONE-CLICK PACKAGE WINDOWS；查看日志和 `.report.json`。
7. **Release/Play**：PC2 产生 Release 文件夹，将其中**整个** `Windows` 目录复制到 PC3；运行 `MyProject4.exe`。PC3 不需要 UE/MCP/Python，但需合适显卡能力和 VC++ 运行库。

PC1 用户配置保存在：

```text
%USERPROFILE%\.unreal_mcp_gui\settings.json
%USERPROFILE%\.unreal_mcp_gui\villages\Village_*.json
%USERPROFILE%\.unreal_mcp_gui\villages\Enhance_*.json
%USERPROFILE%\.unreal_mcp_gui\villages\V4_Sequence_*.json
%USERPROFILE%\.unreal_mcp_gui\villages\V5_Waypoints_*.json
%USERPROFILE%\.unreal_mcp_gui\villages\V6_Runtime_*.json
%USERPROFILE%\.unreal_mcp_gui\screenshots\
```

配置键（**按 V6.5 GUI `save_settings()` 实际实现**）：`host`, `port`, `path`, `agent_command`, `workdir`, `village_color`, `last_village_manifest`, `last_enhance_manifest`, `last_v4_manifest`, `last_v5_manifest`, `last_v6_manifest`, `enhance_sunset`, `v5_pie_mode`, `v5_pie_warmup`, `v5_pie_spawn`, `v63_build_share`, `v63_project_share`, `v65_profile`, `v65_zip`, `v65_output_share`。避免把含个人凭证的其他配置文件、Agent 命令令牌直接提交到 Git。

### 8.3 验证 Worker 心跳 / 队列

```powershell
# PC1
Test-Path "\\192.168.0.204\UEBuildQueue\worker_status.json"
Get-Content "\\192.168.0.204\UEBuildQueue\worker_status.json" -Raw
```

```text
D:\UE_BuildQueue\
  worker_status.json                  # 心跳（每约 2 秒更新）
  requests\<job_id>.json             # PC1 原子写入
  requests\<job_id>.running          # PC2 认领并执行
  results\<job_id>.status.json        # accepted / running / completed / failed
  results\<job_id>.log                # 真实流式日志
  results\<job_id>.report.json        # 最终结构化结果
  results\pc2_native_reports\        # 部分底层编译日志 / 报告
```

版本与心跳：`worker_status.json` 的 `schema=1`、`epoch`（客户端 25 秒内有效）、`busy`、`current_job`、`builder_version`、`builder_file`、`packager_version` 等可用于诊断。客户端使用 32 字节十六进制 UUID Job ID；状态文件有持久化结果，PC1 关闭并不会立即停止 PC2 正在编译的任务。

**协议示例（允许的打包请求，不要任意添加字段）**：

```json
{
  "schema": 1,
  "job_id": "0123456789abcdef0123456789abcdef",
  "action": "package",
  "created_epoch": 1793000000.0,
  "profile": "Development",
  "create_zip": true
}
```

允许动作仅 `preflight`, `build`, `package_preflight`, `package`；仅打包动作接受 `profile` / `create_zip`。PC1 **不可以**在 JSON 里指定自定义 Windows 命令、项目路径、引擎路径或输出目录。失败后检查 `.report.json.errors` 和完整 `.log`，原任务不应盲目重试造成重建覆盖。

## 9. 源文件与配置文件全清单（V6.5 ZIP 已核对）

该交接 ZIP 的主源码目录为 `source/UE_MCP_GUI_V6_5_Package/`。

### PC1

| 路径 | 具体角色 / 重要 API |
|---|---|
| `PC1/UE_MCP_GUI_V6_5.py` | **主 UI**，`MCPClient`（MCP Session/HTTP/SSE）、`TestRunner`（17 项）、`WuxiaBuilder`（V2）、`WuxiaEnhancer`（V3）、`WuxiaV4Sequence`/`V4Playback`、`WuxiaV5QuestSetup`/`WuxiaV5PIE`、`WuxiaV6Runtime`、`UEApp`（所有操作界面、锁和任务线程）。文件目前规模约 213 KB，后续重构需保留行为而非盲目重写。 |
| `PC1/ue_shared_build_client.py` | SMB 任务客户端：`queue_root`、`worker_health`、`_atomic_json`、`submit`、`wait_for_result`、`run_shared_build`；检查心跳、轮询日志/报告，C++ 任务允许 `build/preflight`。 |
| `PC1/ue_package_client.py` | 包装客户端：`run_package_job(share, profile, create_zip, check_only, emit)`；只能提交 `Development/Shipping`、ZIP bool；Worker 版本需 `6.5*`。 |
| `PC1/Start_UE_MCP_GUI.bat` | 双击入口：`py -3 UE_MCP_GUI_V6_5.py`。 |
| `PC1/README_运行说明.txt` | PC1 运行提示。 |

### PC2

| 路径 | 具体角色 / 重要 API |
|---|---|
| `PC2/PC2_Worker_Setup_GUI.py` | Tkinter 首次部署；设 Engine、Project、Queue、Release；保存 `worker_config.json`；插件不存在时可以**非覆盖**复制源码。 |
| `PC2/PC2_Build_Worker.py` | 本机守护程序：`Worker.heartbeat()`、`_process()`、`recover()`、`serve()`；轮询原子队列，**严格动作/字段白名单**、生成日志和报告；不开放任意 Shell API。 |
| `PC2/ue_v6_build_manager.py` | V6.3.3 C++ 编译器调度器；生成短临时 `.ps1`、执行 10/10 检测、调用 UBT/RunUAT、收集错误与诊断。 |
| `PC2/ue_game_packager.py` | **V6.5 核心打包模块**：`CHECK_IDS`、`preflight()`、`_run_uat()`、`_detect_distribution()`、`package_game()`；调用固定 BuildCookRun 并 ZIP 完整发行目录。 |
| `PC2/worker_config.example.json` | 安装包模板：Engine、Project、Queue、Poll；真正 PC2 本地通过 Setup 产生 `worker_config.json`，额外包含 `release_dir`。 |
| `PC2/Start_PC2_Setup.bat` | 启动 PC2 初始化 GUI。 |
| `PC2/Start_PC2_Build_Worker.bat` | 启动后台 Worker（本地控制台）。 |
| `PC2/Verify_PC2_Worker.bat` | 输出实际 Builder 版本、导入文件路径、短命令示例；用于排除“覆盖新文件但运行老进程”。 |
| `PC2/README_运行说明.txt` | PC2 运行提示。 |

### Unreal C++ Runtime 插件（随安装包提供的是**参考源码**）

| 路径 | 作用 |
|---|---|
| `PC2/WuxiaMCPRuntime/WuxiaMCPRuntime.uplugin` | 插件描述，`Modules: [{Name: WuxiaMCPRuntime, Type: Runtime, LoadingPhase: Default}]`，`CanContainContent=false`。 |
| `.../WuxiaMCPRuntime.Build.cs` | `Core`、`CoreUObject`、`Engine`、`InputCore`、`UMG`、`Slate`、`SlateCore` 模块依赖。 |
| `.../Public/WuxiaQuestDirector.h` | `AWuxiaQuestDirector` 属性：茶摊/石桥/守卫位置、半径、QuestStage、V5 路标自动发现。 |
| `.../Private/WuxiaQuestDirector.cpp` | BeginPlay 创建 HUD；Tick 检查 Pawn 距离与 `EKeys::E`，推进任务状态。 |
| `.../Public/WuxiaQuestHUD.h` 和 `.../Private/WuxiaQuestHUD.cpp` | 基于 UUserWidget / Slate Widget Tree 动态创建文本 UI。 |
| `.../Private/WuxiaMCPRuntime.cpp` | 插件模块的定义/实现。 |

### 检测、说明和历史文件

- `tests/test_v65.py`：**Fake UAT** 离线冒烟测试——打包成功/缺素材仍 FAIL/ZIP/Worker JSON 字段白名单/本地文件队列端到端。**不是** PC2 真实 Unreal 构建。
- `docs/test_readiness_gate.py`、`docs/test_builder_report.py`、`docs/test_windows_206_fix.py`、`docs/test_queue_simulation.py`：旧版模拟/测试与诊断参考。
- `docs/README_*.md`、包内 `README_中文_V6_5_完整部署.md`、`SHA256SUMS.txt`：早期版本升级记录和源包校验文件。
- `legacy/`（在交接大 ZIP 内）：若需追溯初期 Python/PowerShell 脚本、各版 ZIP/中文说明，从旧版复制出来的只读参考；**新的开发基线始终是 V6.5**，不要把 v3/v4 文件覆盖 PC1 当前 GUI。

### 不在安装包中、必须从 PC2 / PC1 另行备份的实际数据

- `MyProject4.uproject`、真实 `Config/DefaultEngine.ini`、`Config/DefaultGame.ini`、`Content/**/*.umap/.uasset`、`Source/`（如有）、已编译用户实际插件 `Plugins/WuxiaMCPRuntime/`。
- PC2 **实际** `worker_config.json`、PC1 **实际** `~\.unreal_mcp_gui\settings.json` 与 `villages/` Manifest。
- 成功或失败的真实 `D:\UE_BuildQueue\results\*.report.json/.log`、真实发行成品 `C:\UEGameReleases\...`。
- 本 README **不会**推断这些运行数据已经自动存在于交接 ZIP 中。

## 10. 本地验证（交接包制作时已执行）

在交接包中的 `source/UE_MCP_GUI_V6_5_Package/`：

```powershell
py -3 -m compileall -q PC1 PC2 tests
py -3 tests\test_v65.py
```

**本次文件快照的离线结果**：`compileall` 通过；`test_v65.py` 输出 `PASS: fake UAT success, ZIP, missing assets rejected, worker allowlist, SMB end-to-end`。Linux 上执行这些检查不代表 Windows Tkinter/MCP、真实 MSVC/UE、PC2 发布或 PC3 独立测试通过。

## 11. 公开发布与安全边界

- Unreal MCP Experimental：限制在可信 LAN，PC2 Firewall 不应让公网访问 `8999`；不要为解决 Inspector GUI 的 Forbidden 无条件关防火墙。
- 共享队列 `UEBuildQueue` 仅授权必要的 PC1 用户；共享权限和 NTFS 权限**都需控制**。Release 目录最好只读共享。
- Worker 只有固定的四种允许动作；不接受来自 PC1 的任意 Python/PowerShell 脚本、项目路径、UAT 参数；Codex 继续开发时不能破坏这条安全边界。
- 真正的 Unreal 项目和源代码应纳入 Git；忽略 `Binaries/`, `Intermediate/`, `Saved/`, `DerivedDataCache/`、临时队列、日志、游戏发布包；谨慎处理 `.env`、凭证、真实身份与内部网络信息。
- 复制游戏给玩家时复制**完整 Windows 目录或完整 ZIP**，不是只复制 `MyProject4.exe`。游戏的需求可能包括 VC++ Redistributable、DX12 支持或降低画质（PC3 GTX 1060）。

## 12. 故障排查一览

| 现象 | 先查什么 | 不应该做的事 |
|---|---|---|
| 浏览器 `/` 返回 `route_handler_not_found` | 真正的 `http://PC2:8999/mcp`、CLI、initialize | 误以为 8999 没启动 |
| MCP Inspector Web GUI Forbidden | CLI / curl 是否成功、Origin/代理/Session | 未验证就重装 UE |
| 17/17 测试失败 | 编辑器是否开启、当前 Level、工具 Schema、临时 Cube | 全删地图 Actor |
| PIE 黑屏/角色不可控 | Third Person GameMode、Pawn、PlayerStart、Camera、PIE 设置 | 一味调防火墙或 MCP |
| `WuxiaQuestDirector invalid Class` | C++ Runtime 插件编译/Enabled/Editor restart | 修改 `/Script` 类名来掩盖缺模块 |
| `Could not find NetFxSDK` | Visual Studio Installer 的 .NET Framework 4.8 SDK 或更新 | 误以为 .NET 10 SDK 可取代 NetFxSDK |
| Worker `WinError 206` | `Verify_PC2_Worker.bat`、`BUILD_MANAGER_VERSION`、短 `-File`、继承 env | 只替换文件却不重启 Worker |
| 10/10 显示 9/10 | `UnrealEditor.exe` 是否真的退出；真实 FAIL 项 | 强杀未保存 Editor |
| 9/9 显示 8/9 | GameDefaultMap、Release 空间、MSVC/Windows SDK、Editor 进程 | 跳过 preflight 门禁 |
| C++ 成功但 Cook ExitCode 25 | **Cook 完整日志** 最早实质错误、GameFeatureData / 内容引用 / Shader / Zen | 把已链接 `MyProject4.exe` 当作成品 |
| EXE 在 PC3 黑屏 | 配置、Cook 地图、GameMode、运行时插件及 GPU/VC++ | 只复制一个 EXE |

## 13. Codex 接手顺序

1. 先读本 README，随后读 [HANDOFF.md](HANDOFF.md) 和 [CODEX_PROMPT.md](CODEX_PROMPT.md)。
2. **只在本地源码副本操作**：先解压 `source/`，执行 AST/测试/版本核验，建立 Git 基线；不要碰 PC2 运行中的项目或发行目录。
3. 从用户控制的 PC2 获取真实 `.uproject` 及所需 `Content`、插件、实际 `worker_config.json`，从 PC1 获取 settings/manifest；对路径、私有信息进行本机管理，不提交密码到仓库。
4. 制作 PC1→PC2→PC3 的实机验收记录；将失败诊断和改动准确记录在 HANDOFF / CHANGELOG。
5. 然后按 [CODEX_PROMPT.md](CODEX_PROMPT.md) 的实施任务推进；任何 AI 自主扩展都必须保护已有 17/10/9 门禁与已建村庄。

---

**交接版本来源**：本包内 `source/UE_MCP_GUI_V6_5_Package` 为实际检查的 V6.5 快照。`legacy/` 仅用于追溯，不是自动部署输入；最可信的运行状态仍以 PC2 实际项目、PC1 实际设置、PC2 的 `results/*.report.json` 与当前实机测试为准。

> **对话记录性质**：本文是依据留存交流、源码、测试记录及用户反馈进行的工程化重建，不是逐字逐句的完整聊天转录；历史各阶段未获实机验证的内容已单独标识。