# HANDOFF.md — UE MCP GUI V6.5 → Codex 工程交接与开发上下文

**交接日期**：2026-10-31  
**当前工程基线**：`source/UE_MCP_GUI_V6_5_Package/`（来自原始 `UE_MCP_GUI_V6_5_COMPLETE_PC1_PC2.zip`）  
**工作模式**：PC1 Python GUI ↔ PC2 UE 5.8 Editor MCP；或 PC1 SMB Job Queue → PC2 本机 Worker → UnrealBuildTool / AutomationTool。  
**决策锁定**：**不使用 SSH**；不要求 PC1 安装 Unreal；保留 V1–V6.5 功能、17/10/9 安全门禁、用户在 PC2 实际运行的项目及已存在场景。

## A. 给接手 Codex 的一句话摘要

用户已经迭代完成一套可远程控制 UE5.8 编辑器的 PC1 Tkinter GUI，建有第三人称中国武侠村庄、Sequencer 视觉动作、V5 任务路标，以及 Unreal Runtime C++ `AWuxiaQuestDirector` 的 E 键/UMG 三阶段任务。随后实现 PC1 通过 SMB 固定动作队列控制 PC2 Worker 编译插件（10/10 预检），并在 V6.5 增加 Windows 游戏 BuildCookRun 打包、9/9 预检、日志归档和 ZIP 输出。用户希望把这一项目的**现有代码、设置与历史决策完整移交给 Codex 继续开发**，而不是重新从零建一个演示工具。

## B. 已知实证、用户反馈和仍需实机核验的内容

| 状态 | 事实/证据 | Codex 处理方式 |
|---|---|---|
| **确认：PC1 ↔ PC2 MCP** | 先后有 curl POST initialize、MCP Inspector CLI 工具发现；用户在 Python GUI 报告 17/17 PASS。 | 保留协议与实现，复测仅在 Editor Mode。 |
| **确认：场景可在 PIE 游玩** | 画面有 Third Person 角色，用户反馈「全部可以玩了」；Blank 旧关卡曾黑屏，Third Person 修复。 | 后续游戏性能和 Gameplay 再在 PC2/PC3 实测。 |
| **确认：V4 一次执行结果** | 用户曾报告「17 Actor、102 个关键帧」。 | Transform Sequencer ≠ 运行时导航。 |
| **确认：PC2 Build 进程** | 2026-10-30 真正 UAT Log 显示 `WuxiaMCPRuntime.cpp`, `WuxiaQuestDirector.cpp`, `WuxiaQuestHUD.cpp` 被编译，`MyProject4.exe` 链接 Success。 | **不要**重新宣称插件不能编译；先验证现有可玩版本的源码和二进制。 |
| **历史失败：Cook** | 同份 UAT Log 最终 `Cook failed`、ExitCode 25；出现 GameFeatureData Asset Manager Error、ZenStore 404。 | 用户后续说已处理；**仍需实际最新 Package report** 判定当前 Shipping/Development 的状态。 |
| **已验证：离线 V6.5 源码** | `python -m compileall -q PC1 PC2 tests` 和 `python tests/test_v65.py` 在交接环境通过。 | 只视为 mocked/offline 测试，不能标记 Windows UE 实机通过。 |
| **未知：PC2 当前配置实值** | 旧日志有 Engine/Project 完整路径，但没有当前真实 `worker_config.json` 内容。 | 运行 Setup / 读取实际文件，禁止擅自覆盖。 |
| **未知：PC3 独立 EXE** | 交接资料未含 PC3 真实验收日志、当前 UAT 结果 JSON、Build ZIP。 | 单独安排 PC3 smoke test。 |
| **未知：DSH/Qwen 全自动连通** | 早期规划有 PC1 DeepSeek Harness + Qwen，GUI 可配置 Agent 启动命令；没有当前端到端自主开发运行报告。 | 不要假装已自动把自然语言转成游戏。 |

## C. 部署环境与冻结常量

```yaml
machines:
  pc1:
    role: remote-controller-and-build-client
    gpu: NVIDIA RTX PRO 4500
    tools: [Python_3, Tkinter, Unreal_MCP_HTTP_Client, SMB_Client, optional_DSH_Qwen]
  pc2:
    role: unreal-editor-and-native-build-worker
    gpu: NVIDIA RTX 5060_Ti
    host: 192.168.0.204
    engine: 'C:\Program Files\Epic Games\UE_5.8'
    project_observed: 'C:\Users\karuv\OneDrive\Documents\Unreal Projects\MyProject4\MyProject4.uproject'
    uproject_name: MyProject4
    release_dir_example: 'C:\UEGameReleases'
    queue_local_example: 'D:\UE_BuildQueue'
  pc3:
    role: original_codex-story-workstation-and-independent-game-test
    gpu: NVIDIA GTX_1060
mcp:
  url: 'http://192.168.0.204:8999/mcp'
  bind_observed: '0.0.0.0'
  protocol_negotiated_observed: '2025-11-25'
smb:
  queue_unc: '\\192.168.0.204\UEBuildQueue'
  release_unc_optional: '\\192.168.0.204\UEGameReleases'
requirements:
  no_ssh: true
  pc1_unreal_install_required: false
  worker_accepts_arbitrary_commands: false
```

**注意**：`*_example` 和 `project_observed` 只是当前文档里的历史/示例，部署时严格以 PC2 本机 `worker_config.json` 的有效值为准。PC1 的真实 DSH Agent 启动命令未取得，不要自行拼造。

## D. 已确认源代码目录结构（可直接进入）

```text
UE_MCP_V6_5_Codex_Handoff/
  README.md                 # 项目完整历史、架构、部署、版本说明
  HANDOFF.md                # 当前文件
  CODEX_PROMPT.md           # 给 Codex 的完整任务说明
  source/
    UE_MCP_GUI_V6_5_Package/
      PC1/
        UE_MCP_GUI_V6_5.py
        ue_shared_build_client.py
        ue_package_client.py
        Start_UE_MCP_GUI.bat
        README_运行说明.txt
      PC2/
        PC2_Worker_Setup_GUI.py
        PC2_Build_Worker.py
        ue_v6_build_manager.py
        ue_game_packager.py
        worker_config.example.json
        Start_PC2_Setup.bat
        Start_PC2_Build_Worker.bat
        Verify_PC2_Worker.bat
        WuxiaMCPRuntime/
          WuxiaMCPRuntime.uplugin
          Source/WuxiaMCPRuntime/
            WuxiaMCPRuntime.Build.cs
            Public/{WuxiaQuestDirector.h,WuxiaQuestHUD.h}
            Private/{WuxiaMCPRuntime.cpp,WuxiaQuestDirector.cpp,WuxiaQuestHUD.cpp}
      tests/test_v65.py
      docs/{test_*.py,README_*.md}
      README_中文_V6_5_完整部署.md
      SHA256SUMS.txt
  legacy/                   # 仅用于查阅历史，不应覆盖当前版本
  examples/worker_config.codex.example.json
  SOURCE_SHA256SUMS.txt
```

**真正的 Unreal 项目未包含在这个交接 ZIP**。Codex 以后若有权访问 PC2 SMB 项目共享，请先以只读方式检查项目；修改必须针对用户明确授权的工作副本，绝不悄悄覆盖 PC2 正在使用的 `MyProject4` 或 C++ 插件。

## E. 模块之间如何通信（以代码为准）

### E1. Editor / MCP 链路

- 主模块 `PC1/UE_MCP_GUI_V6_5.py`：
  - `Target` + `parse_target`：MCP Host/IP、Port、Path。
  - `MCPClient`：`_exchange()`、`_read_sse()`、`initialize()`、`initialized()`、`call()`、`tool()`、`unreal()`。
  - `TestRunner`：17 项真实网络与 Actor CRUD 验证，临时 Cube 并清理。
  - `WuxiaBuilder` / `WuxiaCleanup`：村庄创建/Manifest 定点清理。
  - `WuxiaEnhancer`：V3 材质、低模 NPC、装饰、水纹。
  - `WuxiaV4Sequence` / `V4Playback`：Sequencer 资产、Transform 关键帧、播放暂停。
  - `WuxiaV5QuestSetup` / `WuxiaV5PIE` / `WuxiaV5Cleanup`：任务地标、PIE 控制、截图。
  - `WuxiaV6Runtime`：部署/核对/清理 `AWuxiaQuestDirector`。
  - `UEApp`：Tkinter UI，后台线程→`push_event()`→`drain_events()`；关卡变更需要使 17/17 结果失效。
- 真实 `tools/list` 外层只暴露 `list_toolsets`,`describe_toolset`,`call_tool`；必须先读取各 Toolset Schema 再实际调用，避免误猜 UE 5.8 Experimental API。
- `SCENE = editor_toolset.toolsets.scene.SceneTools`；`ACTOR = editor_toolset.toolsets.actor.ActorTools`。
- `V6_RUNTIME_CLASS = '/Script/WuxiaMCPRuntime.WuxiaQuestDirector'`。
- Editor Mode 要求 PC2 Unreal Editor **开启**。保存资源靠 UE 的 File → Save All；创建 Actor 本身不是把 `.umap` 持久化。

### E2. PC1 → PC2 SMB 编译/打包链路

- `PC1/ue_shared_build_client.py`：`worker_health` 检查 `worker_status.json`（`schema=1`；epoch 允许约 25 秒差）；`_atomic_json` 提交 `requests/<uuid>.json`，`wait_for_result` 读取 `.log`, `.status.json`, `.report.json`。
- `PC1/ue_package_client.py`：`run_package_job()` 验证 `packager_version=6.5*`，提交 `package_preflight` 或 `package`，参数只有 `profile`, `create_zip`。
- `PC2/PC2_Build_Worker.py`：固定读私有 `worker_config.json`；心跳间隔 2s；扫 requests、认领为 `.running`，执行 job、写报告。中断的 `.running` 只报告 interrupted，不自动重复执行；默认轮询 0.8s。
- `PC2/ue_v6_build_manager.py`：C++ 编译 10/10，历史的 Windows WinError206 修复和短 `-File`。
- `PC2/ue_game_packager.py`：`preflight()` 的 9 个 `CHECK_IDS`；`package_game()` 调用固定 `RunUAT BuildCookRun`、验证 EXE+Cook 资源、可选 ZIP。
- 固定四种 action：`preflight`、`build`、`package_preflight`、`package`。**不得新增来自 PC1 的任意 shell、PowerShell 或 UAT 参数传递**，也不得靠 `shell=True` 执行用户提交的字段。
- 请求 schema=1；job_id 为 32 位小写十六进制 UUID；打包 `profile` 仅 `Development` 或 `Shipping`；`create_zip` 必须 bool。收到任何额外字段立即 FAIL。

### E3. 游戏运行时代码

- `.uplugin` 里 `Modules[].Type = Runtime`； `WuxiaMCPRuntime.Build.cs` 声明 UMG / Slate 等依赖。
- `AWuxiaQuestDirector`：BeginPlay 初始化 HUD 与路标；Tick 获取本地 PlayerController/Pawn、与 StageLocation 做 XY 距离及 Z 判定、检测 E 键，只在 450cm 内推进三阶段任务；位置可以通过 Details 修改，且可自动发现 V5 Waypoint Actor。
- `UWuxiaQuestHUD`：动态构建 Widget Tree 文字区域，显示 Title/Dialogue/Hint，不需要外部 Widget Blueprint。但当前文字是英文，用户若下一阶段希望中文、对话选择、持久化存档，应在新需求上独立迭代。
- **未实现**：多人联机、任务持久化存档、真正的 Skeletal NPC 寻路和碰撞避障、AIController/Behavior Tree 完整系统、真正的物理水流、自动翻译、多 GPU 分布式渲染。

## F. 三种 Readiness Gate 不可混用

| Gate | 当前代码权威来源 | 成功要求 | 与 Editor 关系 | GUI 解锁目的 |
|---|---|---|---|---|
| **MCP 17/17** | `TestRunner` | 每项真实 RPC / Cube CRUD PASS；测试新鲜度与 Server 不变 | **必须开启** Editor | AI Agent 与 Editor 场景任务 |
| **C++ Build 10/10** | `ue_v6_build_manager.py` PowerShell 预检 | UE/UBT/UAT/VS/MSVC/SDK/.NET10/NetFxSDK/Source/EditorClosed | **必须关闭** Editor | 只编译 Runtime 插件 |
| **Package 9/9** | `ue_game_packager.py` | Engine/Project/RunUAT/Compiler/WinSDK/GameDefaultMap/RuntimePlugin/EditorClosed/ReleaseSpace | **必须关闭** Editor | BuildCookRun + ZIP |

10/10 与 9/9 GUI 授权**约 5 分钟有效**，Changing Queue、Profile 会使对应授权失效。PC2 Worker 执行前再次预检（不能仅信任 PC1 的按钮状态）。**新开发的测试策略需要保留这一约束。**

## G. 当前配置、运行生成物与应避免提交到 Git 的数据

### G1. PC1 `.unreal_mcp_gui/settings.json`

程序存于 `%USERPROFILE%\.unreal_mcp_gui\settings.json`；按源码 `UEApp.save_settings()`：

```json
{
  "host": "192.168.0.204",
  "port": "8999",
  "path": "/mcp",
  "agent_command": "",
  "workdir": "",
  "village_color": true,
  "last_village_manifest": "",
  "last_enhance_manifest": "",
  "last_v4_manifest": "",
  "last_v5_manifest": "",
  "last_v6_manifest": "",
  "enhance_sunset": false,
  "v5_pie_mode": "PlayMode_InViewPort",
  "v5_pie_warmup": "0",
  "v5_pie_spawn": false,
  "v63_build_share": "\\\\192.168.0.204\\UEBuildQueue",
  "v63_project_share": "",
  "v65_profile": "Development",
  "v65_zip": true,
  "v65_output_share": "\\\\192.168.0.204\\UEGameReleases"
}
```

以上仅作说明，真实 `agent_command`、Manifest、工作目录要来自 PC1 本机。切勿将个人账户密码、Token 写进该设置示例。

### G2. PC2 `worker_config.json`

由 `PC2_Worker_Setup_GUI.py` 持久化在同目录；已有现场配置时保留/备份，**不要直接覆盖为示例**。`examples/worker_config.codex.example.json` 提供填有历史已知项目路径的示例；实际队列、Release、项目前缀要确认。

### G3. Manifest、Queue、Release

- PC1 Manifest：`%USERPROFILE%\.unreal_mcp_gui\villages\Village_*.json` / `Enhance_*.json` / `V4_Sequence_*.json` / `V5_Waypoints_*.json` / `V6_Runtime_*.json`；与原来的 Level/Actor 对应，不能随意更名/合并。
- PC2 Queue：`requests`、`results`、`worker_status.json`；至少保存最近失败/成功 job 的 `.report.json` 和完整 `.log`；日志可含 PC 账户路径，别直接公开。
- PC2 Release：`<Project>_<Development|Shipping>_<jobID12>\Windows\...`；可选同名前缀 `.zip`；**这些文件是打包制品，不是开发源码**。
- Unreal 项目大容量缓存：`Saved/`, `Intermediate/`, `DerivedDataCache/`, `Binaries/` 可能是可再生成物，但别在用户正运行构建时自动删除以“清理环境”。

## H. 历史问题与确定的解决方向（不要重蹈覆辙）

1. **网络连接阶段**：`http://PC2:8999/` 404 是未定义根路由；真正服务在 `/mcp`。MCP Inspector GUI 的 Forbidden 并未阻止 CLI 实际成功。不要为让浏览器根页面显示 HTML 而修改 MCP 服务。
2. **Toolset 参数阶段**：CLI `--tool-args-json` 的 PowerShell 转义曾报 JSON 错；小参数 `--tool-arg` 已验证。`find_actors` 的 `name/tag/collision_channels` 在当时 Schema 都是必填。
3. **V2 重建阶段**：Actor 创建后有独立 Manifest，重建前检查是否已经存在 Actor；失败时从 Manifest 精准回滚，不能全删地图。
4. **V5 PIE 黑屏阶段**：核心是 Blank 项目没有合适的 Third Person GameMode/Pawn/Camera；`warmup=1` 时另有早退，V5.1 允许 0。不要将所有 PIE 问题归咎 MCP。
5. **V6 plugin invalid class**：编译/装载 DLL 后再用 `/Script/WuxiaMCPRuntime.WuxiaQuestDirector`。PC2 项目真正版插件可能已有编译修订，包内只是初始参考。
6. **编译 NetFxSDK**：缺 .NET Framework SDK，与 UE 自带 .NET 10 不同；后来 10/10 日志曾显示 `4.8.1` 通过。
7. **WinError206**：旧 PowerShell `-EncodedCommand` 过长；V6.3.3 用短 `-File`，标记真实 Module 版本/路径 + 简化环境重试。一定关闭 Worker 后重启新版本，不能用源码变了就认为进程也变了。
8. **编辑器未关闭**：当时 9/10 C++ gate 的唯一失败项曾是 `UnrealEditor Closed`。是预期防护。
9. **Cook ExitCode25**：Build 实际成功但 Cook 失败。`GameFeatureData` 缺类型注册是日志明显问题；Zen oplog 404 出现后也重建过，不能只看单句就判定根因。要拿到 Cook 专用日志定位根因并在同一提交记录修复。
10. **显存警告**：PC2 Third Person PIE 曾显示 Video Memory exhausted，PC3 GTX1060 仍需低配图形设置、运行库与硬件兼容性测试。
11. **OneDrive 项目路径**：旧项目位于 OneDrive 下，非本次错误确定根因，但大型 Cook/UBT 缓存及频繁同步存在风险；迁移到本地无同步目录须有完整备份并更新 Worker config、`.uproject` / shortcuts，不能直接 move 后指望 Manifest 不受影响。

## I. 已识别的源码风险与待审核点（**不是已经证实的生产 Bug**）

Codex 在任何新功能前先逐项确认：

- **单 Worker 实例保障**：`PC2_Build_Worker.py` 当前单进程内部 busy 状态，未在已见代码中发现跨进程独占锁；如果用户双击两次 Worker，可能有并发竞态。可增加 PC2 本机文件锁 / 进程排他检查，但不能影响正常独立测试。
- **任务重连和历史任务浏览**：`ue_shared_build_client.wait_for_result` 可等待已有 ID，但 PC1 GUI 重新开启是否拥有浏览/恢复历史 Job 的友好入口需实际核对。多小时打包、GUI 刷新/关闭后的任务恢复是优先改进方向。
- **日志读取与进度**：PC1 当前按块读取，窗口关掉不会停止 PC2 Job；仍需测试大量日志/UTF-8 半行边界、长编译日志和实时进度。不要以控制台字符串匹配直接宣称百分比精确。
- **打包成品验证**：目前判断 `rc=0` + EXE + Pak/IoStore，而这只是基本检测；不能替代首次在干净 PC3 上启动、加载首关、操作 NPC 和关卡退出的自动 Smoke Test。
- **PC2 配置错误隔离**：`PC2_Worker_Setup_GUI` 会在插件缺失时提供复制样板源码的选项；在已有可用插件上必须保证“不覆盖”，并可记录源码散列/差异。
- **安全**：PC2 Worker 设计了请求字段白名单，但共享文件夹的 ACL、JSON 大小限制、任务 ID 校验、单实例锁、用户进程权限及非法符号路径仍需要持续测试。不能为易用性新增执行任意 shell 命令的通路。
- **UE 编辑器版本兼容**：Experimental MCP API可能变化，必须动态 `describe_toolset` 并验证；当前 GUI 超过 200KB，一个大文件维护成本高，建议有兼容性测试的渐进式抽模块，而非大规模重写。
- **Third Person 项目构建目标**：`.uproject` 配置、Game Default Map、World Settings Override、插件二进制等须来自 PC2 当前项目，不能依据安装包单方面修改。

## J. Codex 下一次应该先完成的任务（优先级）

### P0 — 读取/稽核现有项目，不改源码

- 递归列出 `source/UE_MCP_GUI_V6_5_Package` 文件、版本、入口、依赖、配置项，并用代码实际核实而非照抄说明。
- 运行静态 Python 语法与 `tests/test_v65.py`，保存**真实**输出；确认 Windows 测试需保留到 PC1/PC2。
- 对照 PC2 的**实际** `worker_config.json`、实际项目插件文件与包内参考源码；**禁止直接覆盖或悄悄迁移**。
- 确认 PC1 GUI 能识别 PC2 `packager_version=6.5.0`、User Settings、Queue、Release 共享；如连接尚不允许，使用 Offline 模式记录为未验证。
- 产出 `AUDIT_V65.md`、`docs/architecture.md` 与任务矩阵；把「离线通过」「PC2 真实通过」「待测试」分列。

### P1 — 基于已有代码补强稳定性（建议接手后的首个实际开发迭代）

- 新增 Job History / Resume / Retry（Retry 用新 Job ID，不能重复执行旧 `.running`）。
- 增加 PC2 Worker **单实例锁**、过期状态/任务诊断和一键复制精简诊断包，不破坏现有 queue schema。
- PC1 GUI 清楚地区分三种工作模式 Editor / C++ Build / Packaging；三个 Gate 状态互不错误绑定。
- 增加发布包完整性检查：EXE、Pak/IoStore、是否可读取、大小清单、哈希和 Release metadata；ZIP 验证（注意超大文件）。
- 强化日志：标记各阶段 Build/Cook/Stage/Archive 的开始/结束；出现 Cook 失败优先定位第一个实质错误；确保没有成功误报。

### P2 — 建立 Windows / UE5.8 实机验收与发布流程

- 10/10 + Build 插件（Editor 关闭）→ 重开 Editor 做 MCP 17/17 → Save All → 退出 Editor → Package 9/9 → Development BuildCookRun → Shipping BuildCookRun → 完整 ZIP → PC3 独立运行。
- 验证 `WuxiaQuestDirector` 三阶段 E 键互动、PlayerStart、声音、输入、HUD、打包后地图正确加载、必要依赖项。
- 记录结果及所有报告路径；没有访问 PC2 实机时，只能交付可复现的操作脚本/测试列表，不能宣称编译成功。

### P3 — 游戏内容/AI 功能（在 P0–P2 之后）

- PC3 Codex 的剧情/对白/任务数据先落地 JSON Schema，再由 PC1 受限验证转译 Unreal 数据资产/Blueprint，避免任意 RPC 执行。
- NPC 真正移动/巡逻需要 NavMeshBoundsVolume、Pawn/Character、AIController、Behaviour Tree 或其他 UE 原生方案；不能把 Sequencer Transform 滑动当作 AI。
- 为当前三阶段任务引入中文本地化、任务存档、NPC 对话选择、任务脚本和基础菜单；每一个新系统单独测试 PIE + Package。
- 按用户未来意图继续向 **AI-Native Autonomous Software Evolution / AI-Native Game Development** 迭代，但不得牺牲现有用户可玩版本。

## K. 验收标准（Definition of Done）

每次修改必须同时回答：

1. **改了哪些文件，为什么？** 给出路径与 diff 摘要；如果重构主 GUI，不得丢失原 17 项检测、V1–V6 场景能力或 V6.5 Packaging 按钮。
2. **是否经过语法/单元/模拟测试？** 报告具体命令、退出码与结果；失败也要列出。
3. **是否涉及实机 UE/Windows？** 若没有连接 PC2，不得写「PC2 打包通过」；将尚未做的步骤列为明确待测试。
4. **是否保留 PC1/PC2 安全边界？** PC1 不应提交任意命令/路径；SMB ACL 最小授权；Editor 关闭门禁必须仍有效。
5. **是否保护用户资料？** 不覆盖 `.uproject`、Level/Content、用户 Runtime 插件、已有 Release；删除需明确列出精确路径并征得授权。
6. **是否给出新启动与恢复方式？** Windows `.bat` 仍然可双击；Worker 可恢复；错误日志能找到；新版本可并排装或安全回退。
7. **是否能发到 PC3？** 有真实 Release 包、完整目录、必要运行依赖与独立启动验证，而不是仅有 PC2 IDE 中运行成功的画面。

## L. 给 Codex 的首个输出格式

请在第一次扫描后按以下结构输出：

```markdown
# V6.5 Codex 接手审计
## 1. 项目目录与实际入口
## 2. 现有模块依赖与数据流
## 3. 版本与配置读取结果（敏感信息脱敏）
## 4. 17/10/9 Gate 实际代码定位与测试状态
## 5. C++ WuxiaMCPRuntime 结构与当前部署差异
## 6. 已确认问题 / 待确认风险 / 用户明确禁止的方案
## 7. 初步修复清单（P0/P1/P2）
## 8. 可立即执行的最小安全改动及复现测试
```

**总结**：这是**真实长期演进的 Windows+Unreal+Python 工程**。应以最新 V6.5 实际代码和真实 PC2 游戏项目作为最高事实来源；旧版 ZIP、宣传配图、模拟成功输出、历史说明只作为上下文。Codex 的使命是**在不破坏现有可玩版本的前提下继续演进**。