# CODEX_PROMPT.md — 可直接复制给 Codex 的完整接手与继续开发提示词

> **复制方法**：将本 Markdown 文件的「开始」至「结束」之间内容完整复制到 Codex，或让 Codex 在当前工作目录读取 `README.md`、`HANDOFF.md`、`CODEX_PROMPT.md`。  
> 若 Codex 在 PC3 或其他工作站上运行，先解压本交接 ZIP；若可访问 PC2 项目共享，请**先只读核对**，不要直接覆盖生产项目。  
> Codex 可以先完成本地审计和低风险代码改进，不必为已在这里明确的 IP/路径/架构重复询问。

---

## 🔽 提示词开始（完整交给 Codex）

你现在是我的长期工程开发代理（Lead Software Engineer + Unreal Engine Technical Director + Windows Build/Release Engineer + QA Engineer）。

请**接手我已经开发到 V6.5 的真实工程**：

**项目名称：UE MCP GUI V6.5 — One-Click Game Packaging / AI-Native Unreal Game Development**。

这不是从零开始的练习项目，也不是只生成方案、流程图或伪代码的任务。我已经完成 PC1→PC2 的 Unreal MCP 控制、武侠村庄创建、Third Person 游玩、NPC E 键交互、C++ Runtime Plugin、SMB 自动编译 Worker、一键 Windows 游戏打包工具。你的职责是在**保留、审核、测试、渐进改进**现有代码的前提下继续开发。

### 0. 立即读取的项目文件（必须先做）

当前目录应含：

```text
README.md
HANDOFF.md
CODEX_PROMPT.md
source/UE_MCP_GUI_V6_5_Package/
legacy/
examples/worker_config.codex.example.json
```

**先完整阅读 `README.md`、`HANDOFF.md`，然后检查 `source` 内的真实代码与说明。**

如果用户已经把真实 UE 项目和实际 PC1/PC2 配置另外挂载在工作区，也要读取它们，但先用只读方式检查、比对与列出差异。绝不能把本安装包里附带的示例 `WuxiaMCPRuntime` C++ 源码直接覆盖已在 PC2 成功编译的真实插件版本。

不要只凭 README 断言功能存在。实际源码和最新实机日志是最终依据。

### 1. 我确定的三电脑架构

| 主机 | 工作职责 |
|---|---|
| **PC1：RTX PRO 4500** | Windows Python 3 / Tkinter GUI；MCP 操作场景；管理编译、打包任务与日志；可继续集成 DeepSeek Harness + 本地 Qwen 作为 AI Agent。**PC1 不需要安装 Unreal Engine**。 |
| **PC2：RTX 5060 Ti；192.168.0.204** | Unreal Engine 5.8 Editor、Experimental MCP Server、MyProject4 Third Person 武侠村庄、C++ Runtime Plugin、PC2 Build Worker、MSVC/SDK、BuildCookRun。实际编译和打包在 PC2 本机执行。 |
| **PC3：GTX 1060** | 我原本计划让 Codex 负责故事、角色、对白与任务；也可用于独立运行 Windows 打包游戏作验收。 |

**网络和服务**：

```text
MCP URL:    http://192.168.0.204:8999/mcp
MCP bind:   0.0.0.0:8999 （仅可信局域网；防火墙限制来源）
SMB Queue:  \\192.168.0.204\UEBuildQueue
Release:    \\192.168.0.204\UEGameReleases  （可选只读共享）
Engine:     C:\Program Files\Epic Games\UE_5.8
Project (历史实机路径):
 C:\Users\karuv\OneDrive\Documents\Unreal Projects\MyProject4\MyProject4.uproject
```

`Queue` 的 PC2 本地路径可以是 `D:\UE_BuildQueue`，`Release` 可以是 `C:\UEGameReleases`；这两个仅是示例，必须以 PC2 `worker_config.json` 实值为准。

**我明确不想使用 SSH。** 严禁未经我要求改用 SSH/RDP、要求在 PC1 安装整套 Unreal Engine、使用公网裸露 MCP、或设计一个从 PC1 向 PC2 任意执行 Shell 命令的系统。

### 2. 必须保留的现有功能（Regression Contract）

**17/17 MCP Editor Tests**：TCP、MCP initialize、Session、initialized、tools/list、toolsets、Scene/Actor Schema、Level、临时 Cube 建立/改 Transform/读回/改 Label/搜索/移除/确认删除。它们必须真实通过才允许 AI Agent/编辑器高风险修改。原有 `TestRunner` 的 17 个名称可在 `UE_MCP_GUI_V6_5.py:TEST_LABELS` 找到。

**V2**：完整灰盒中国古代武侠村庄，10 间民居、街道、河流、石桥、入口、树木、灯笼、PlayerStart；必须保留 Manifest 和精准清理。

**V3**：原村庄视觉增强、材质、摊位、石砖、水纹、6 名 NPC（可为低模占位），不得默认重建原有房子。

**V4**：Sequencer NPC 移动与水纹 Transform 动画；新 Sequence 资产与 Manifest；不得把 Transform 动画写成真正 NavMesh AI。

**V5 / V5.1**：任务地标、PIE 启动/停止/状态、诊断和截图。PIE 默认 warmup 可为 0，不强制无效的 spawn；游戏角色由 Third Person GameMode、Pawn 和输入控制。

**V6**：`WuxiaMCPRuntime` 模块、`AWuxiaQuestDirector`、`UWuxiaQuestHUD`、E 键三阶段“石桥寻笛”；游戏运行态 HUD、目标地点和任务状态不许在重构中消失。未实现真正 NPC 寻路或跨场次存档，不能宣称已实现。

**V6.3.3 C++ Build Worker**：PC1 通过 SMB 提交固定 `preflight/build`，PC2 执行 Unreal 原生编译。10/10 Check（包括 NetFxSDK、Editor Closed），短 `-File` 修复 WinError206，保留运行日志。不得再回到过长 `-EncodedCommand`。

**V6.5 Game Packager**：独立 9/9 Packaging Check、Development/Shipping、`RunUAT.bat BuildCookRun`、Build/Cook/Stage/Package/Archive、可选 ZIP、EXE + Pak/IoStore 校验、独立 Job ID 不覆盖历史目录。

**三套门禁独立**：

- MCP 17/17：**Unreal Editor 开启**；真实 RPC 验证；未通过不能进行编辑器修改。
- C++ Build 10/10：**Unreal Editor 关闭**；SDK、工具链、插件源码等就绪；PC2 执行前再检查。
- Game Package 9/9：**Unreal Editor 关闭**；Game Default Map、Runtime Plugin、目录/磁盘空间等就绪；PC2 执行前再检查。

**绝对不允许**做一个同时要求 17+10+9 PASS 的全局阻塞条件，因为 Editor 的运行需求互斥。允许 GUI 有明确的 Editor / Compile / Package 模式。

### 3. 请先检查这些实际文件和函数

```text
source/UE_MCP_GUI_V6_5_Package/PC1/UE_MCP_GUI_V6_5.py
    MCPClient, TestRunner, WuxiaBuilder, WuxiaEnhancer,
    WuxiaV4Sequence, WuxiaV5PIE, WuxiaV6Runtime, UEApp

source/UE_MCP_GUI_V6_5_Package/PC1/ue_shared_build_client.py
    worker_health, submit, wait_for_result, run_shared_build

source/UE_MCP_GUI_V6_5_Package/PC1/ue_package_client.py
    run_package_job

source/UE_MCP_GUI_V6_5_Package/PC2/PC2_Build_Worker.py
    Worker._process, Worker.heartbeat, Worker.recover, Worker.serve

source/UE_MCP_GUI_V6_5_Package/PC2/PC2_Worker_Setup_GUI.py

source/UE_MCP_GUI_V6_5_Package/PC2/ue_v6_build_manager.py
    BUILD_MANAGER_VERSION = '6.3.3', 10/10 preflight,
    PowerShell script-file subprocess, diagnostic logs

source/UE_MCP_GUI_V6_5_Package/PC2/ue_game_packager.py
    VERSION = '6.5.0', CHECK_IDS, preflight,
    _run_uat, _detect_distribution, package_game

source/UE_MCP_GUI_V6_5_Package/PC2/WuxiaMCPRuntime/
    WuxiaMCPRuntime.uplugin, WuxiaMCPRuntime.Build.cs,
    WuxiaQuestDirector.h/.cpp, WuxiaQuestHUD.h/.cpp

source/UE_MCP_GUI_V6_5_Package/tests/test_v65.py
```

其它历史版本都放在 `legacy/`。**请把 V6.5 作为唯一开发基线**，不要选 V6.3.1、V6.3.3 或 V4 覆盖更高版本。历史文档有一些在当时尚未实测的描述，理解它们的时间顺序。

### 4. 编译与打包 Worker 的通信协议不可擅改

PC1 生成 UTF-8 JSON 请求（原子写入），PC2 读取 `requests/<32hex>.json` 后认领为 `.running`，依次写入：

```text
worker_status.json
results/<job>.status.json
results/<job>.log
results/<job>.report.json
```

合法动作只有：

```text
preflight
build
package_preflight
package
```

合法打包请求：

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

PC2 必须拒绝额外的任意命令、未批准的项目路径、UE/UAT 参数、Release 输出路径、任意命令行。PC2 的 Engine/Project/Queue/Release 固定在自己的配置。不要泄露 Windows 凭证或 Agent Key。

PC1 UI 10/10/9/9 授权都有新鲜度约 300 秒的限制，且 PC2 的构建/打包函数会在执行前再做预检。保留双重检查。Worker 意外退出时，未完成 `.running` 默认应安全标记为 interrupted，不能自动重复触发一个 C++/Cook Job。

### 5. 你必须理解并处理的历史问题

- 浏览器访问 `http://192.168.0.204:8999/` 返回 `route_handler_not_found`，但 `/mcp` 用 POST/Session 可用；MCP Inspector Web GUI 曾 Forbidden，CLI 成功，没必要阻碍开发。
- PowerShell `--tool-args-json` 转义失败，单值建议 `--tool-arg key=value`；每次以实际 `describe_toolset` 参数为准。
- Blank 模板黑屏没有 Pawn / Third Person GameMode；后来新 Third Person 项目已经能在 PIE 游玩。
- V6 `WuxiaQuestDirector` 之前因 C++ plugin 未加载提示 invalid Class，需确保 Runtime 代码真正编译和 Enabled。
- 编译最初因为缺 .NET Framework NetFxSDK 失败，后来 PC2 检测 `.NET Framework 4.8.1 SDK` 已 PASS。
- V6.3.1 曾把完整 PowerShell 放进超过 32k 的 EncodedCommand 引发 WinError206；V6.3.3 已改短 `.ps1 -File` 并加入环境变量/版本诊断。
- C++ 编译和 Packaging 都必须关 UnrealEditor，之前 9/10 唯一失败项曾是 Editor 仍运行。
- 2026-10-30 UAT `MyProject4.exe` 实际链接成功，但 Cook 曾因 Error_UnknownCookFailure (ExitCode25) 失败；出现 `GameFeatureData` Asset Manager error 和 ZenStore 404，后来用户说已处理，仍应验证最新 Release 报告。
- 用户项目以前在 OneDrive 目录内，且一度出现显存预算警告；不要把这些未证明的风险当作某次错误的确定根因。

### 6. 当前接手阶段要交付的东西：先审计，再做最小可靠改进

**任务 A — 只读扫描与可重复测试（必须第一个执行）**

1. `pwd`、列出目录结构、所有 Python / C++ / `.uplugin` / `.json` / `.bat` / Markdown 文件；验证 README 声称的版本、实际 GUI 启动文件、Worker 版本与 Queue schema。
2. 读取 `worker_config.example.json`，列出真实配置应有键与默认值。若 PC2 真实 `worker_config.json` 可用，只读比对；不要显示或保存密码。
3. 在本机运行：

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

   若开发机不是 Windows，则以 `python3` 运行标准 Python 离线测试，并明确标注当前环境。测试预期输出 `PASS: fake UAT success, ZIP, missing assets rejected, worker allowlist, SMB end-to-end`。这使用 **fake UAT**，不是 UE 实机测试。
4. 检查打包报告的真实状态条件（必须 `ExitCode=0` + EXE + Cook 资源，而不是仅看到 `MyProject4.exe` 编译成功）。
5. 创建文件 `AUDIT_V65.md`，包括完整系统结构、模拟 vs 实机的验证证据、缺口、风险及修复优先级；创建 `docs/architecture.md` 并画文本架构图。

**任务 B — 实现 V6.5.1 稳定性增强（在扫描确认后，用最小改动）**

建议优先实现下面四项，但必须基于实际源码确认需求，不得凭空重写：

- **B1. Job History / Resume**：PC1 GUI 新增一个简洁的构建/打包历史查看区；能按 Job ID 查询当前 Worker 状态、既往报告和日志；GUI 关闭再打开时可重新附着到正在执行的 Job。Resume 只恢复**查看/监控**，不要启动第二个重复构建。
- **B2. PC2 Worker Single Instance Guard**：防止在 PC2 同一 Queue 上同时启动多个 Worker 造成竞态，失败时给出明确错误与原 Worker PID/启动位置，不强杀其他 Python 进程。
- **B3. Release Manifest**：每个成功打包目录创建一个包含 `version/profile/job_id/project/exe/asset-count/timestamp/size/SHA256` 等信息的非敏感 manifest（注意大文件性能与策略可配置）；ZIP 生成后验证可打开并含预期运行文件，而不只是测试 ZIP 大小 > 0。
- **B4. Cook / Packaging Failure Diagnostics**：使 PC1 GUI 能快速定位 Job 的 UAT Log、Cook Log、错误首因、ExitCode 与失败阶段；不能把所有 `Error:` 都误判为根因。提供可导出的、已脱敏的诊断摘要。

对于上述每项，先写对应单元/集成测试，再做尽量小的代码改动，不要破坏既有 Tkinter 布局和批处理入口。保留旧 JSON schema 兼容；如确需升级 schema，要支持读取旧 Job。

**任务 C — 实机验证（需真实 PC2 可用并获得授权）**

制定并执行能执行的部分：

1. `Unreal Editor OFF` → PC2 Worker 心跳有效 → C++ 10/10 PASS → BuildPlugin 或项目编译成功。
2. `Unreal Editor ON` → MCP 17/17 PASS → 当前村庄 Level、`AWuxiaQuestDirector` 实际在关卡中 → Third Person PIE 与三阶段 E 键交互通过 → File / Save All。
3. `Unreal Editor OFF` → Packaging 9/9 PASS → BuildCookRun Development 成功 → 验证 `MyProject4.exe` + 完整 `.pak`/`.utoc/.ucas` + ZIP。
4. PC3 独立解压/运行 → 验证首关不是黑屏、角色 WASD、NPC E 键对话/任务、退出不崩溃。对 GTX 1060 记录画质配置和 DX/驱动要求。
5. 然后再测试 Shipping。未取得真实 PC2/PC3 权限时，给我准确可执行的测试命令、GUI 点击步骤和验收模板，状态标注 **NOT RUN**，绝不能虚构结果。

**任务 D — 下一阶段 AI-Native Gameplay（规划阶段，可在稳定发布之后开始）**

构思可扩展的 PC3 Codex 剧情 JSON → PC1 校验/AI 编排 → PC2 Unreal 资产/Blueprint 的受控管线。下一阶段可规划 NPC 路线/Behavior Tree、对白选择、中文任务 HUD、存档加载、主菜单与选项、资源性能优化。但请在稳定性工作完成前不要未经批准大面积替换现有 C++ Quest Runtime 或原有 Level。

### 7. 开发时必须遵守的操作规范

1. **不要重新设计成别的框架**。保留 Python/Tkinter GUI、原 HTTP MCP Client、SMB File Queue、Windows `.bat`、PC2 Unreal 原生 UBT/UAT。
2. **不要以伪代码、几张界面截图或纯计划代替实际修复**。有源码的任务应提供真正可运行的变更及测试。
3. **修改前先备份 / Git commit；最好建立 `v6.5-codex-baseline` 标签**。不要在未确认权限下修改 PC2 生产 `MyProject4`、删除 `Content/`、重建 Level、停止 Worker 或清理 UE Cache。
4. **全部 UI 仍以 17/10/9 青色通过、红色失败为主要可视化方式**；每个阶段有清晰日志和失败原因。不要删掉已有按钮。
5. **不可虚构 UE5.8 MCP API / C++ 类路径 / 运行时数据**。调用前动态发现工具及 Schema。实际工程与当前代码不符时展示差异，并给出兼容处理建议。
6. **保留 Source 的完整可追溯历史**：本次修改代码应留在清晰的工作目录，不要用旧版 ZIP 覆盖 V6.5。
7. **安全必须优先**：不得接收未经白名单验证的 Shell/PowerShell/RunUAT 参数，不得把 SMB 共享开放给 Everyone 完全控制或把 MCP 8999 暴露公网。
8. **不要把本交接包里的“模拟操作图片”当作真实产品截图**。真实性只能由用户当前 Windows PC2/PC3 日志、真实屏幕或报告证明。
9. **不要未经我授权要求配置 SSH**。有权限不足时先给 SMB/本机替代流程，不要默认让我重复此前所有配置。
10. **使用正确的时态**：`V6.5 offline test PASS` ≠ `UE real packaging PASS`；如果缺乏真实验证数据明确说待验收。

### 8. 你的第一次回复/第一次代码改动必须包含

完成实际文件扫描后，给我：

- **A. 已识别的当前版本/真实文件清单**（包含 PC1、PC2、Runtime Plugin、Test、Config）。
- **B. V1–V6.5 能力保持清单**（指出函数/代码中的实际位置）。
- **C. 17/10/9 Gate 源码定位和仿真/实机状态**。
- **D. 一份简明但真实的 Audit 报告**，将 P0/P1/P2 风险按优先级排序。
- **E. 最小安全改动的实施结果或第一项可以落地的修复**，附完整 diff 变更说明。
- **F. 已执行的测试命令与结果**（列出成功/失败/未执行）。
- **G. 下一阶段可执行步骤**，不要只回复“可以开始”。

如果代码已通过审计并具备本地可执行环境，请直接实现 B1–B4 中最适合作为第一次小版本变更的项目，提供可运行文件；若关键的 PC2 真实项目或配置不在工作区，先完成不依赖生产机器的静态审计和离线测试，把无法验证的部分明示为外部依赖，不要假造访问权限。

我的最终愿景是：**我只需提出 Idea，AI 能理解已有系统、设计场景和玩法、编写/修正代码、管理差异、自动编译、验证并打包可发布的 Unreal 游戏**。但是请以当前 V6.5 已完成的现实代码为基础，逐步向 AI-Native Autonomous Software Evolution 扩展。

## 🔼 提示词结束

---

## 给用户的使用提醒（不必复制给 Codex）

- 首次让 Codex 工作时，**优先上传或在 Codex 工作目录解压本交接 ZIP**，让它有源代码而不只是 3 份 Markdown。`source/` 已附主程序与 C++ 插件参考源码，`legacy/` 保留旧版供比对。
- PC2 实际 UE 项目（`MyProject4` 的 `Content`、`.uproject`、`Config` 和最新已修改 Runtime 插件）需要单独备份并提供给 Codex，交接 ZIP 不含这些大型 Unreal 资产；若 Codex 在 PC3 上运行，可以只授予受控项目共享的只读权限用于审计。
- 若打算让 Codex 修改真实 UE 项目，请先建立 Git commit 或离线备份，再在独立工作副本测试，确认后部署回 PC2。
- 本提示词故意不要求 SSH；C++ 10/10 和 Packaging 9/9 与 MCP 17/17 属于不同运行模式，不能同时强制通过。