# 7. 真机试玩验证与 bug 修复

## 输入与适用时机

读取模拟器候选、测试记录、资产清单、导出警告和已有真机回传。直接复用用户已提供的索引、画面和日志，只询问缺项。

## 执行动作

### 准备交付说明

整理 Lua、完整存档/GIA、目标素材 ID、测试结果和已知限制。在 `docs/device-handoff.md` 或项目已有交付说明中写清本项目的操作：交付文件及版本、资产导入顺序、入口脚本和挂载对象、需要核对的控件/模板、脚本路径、试玩步骤与预期。仅列出当前项目实际需要的事项；不能把导出文件路径当作真机已完成导入的证据。

GIA 不保存脚本挂载关系；交付时单列需要在千星沙箱建立或复核的脚本映射和挂载。已有工程复用确认过的配置，只说明本次变更与仍待完成的操作。

### 用户导入时需要完成什么

按实际工程生成简短交接清单，用用户看到的控件/脚本名称和路径说明，不要求用户理解工具字段：

| 环节 | 用户操作 / 回传 | AI 配合 |
|---|---|---|
| 导入与挂载 | 导入本次所需资产，核对脚本映射路径，将入口脚本挂到指定客户端控件/容器节点或模板。已有正确映射和挂载可复用。 | 给出“哪个文件 → 哪个资产/挂载对象”的对应关系，以及本轮新增或变化项。 |
| 核对真实索引 | 检查导入后目标控件/模板的实际索引；有变化时提供资产/控件名、原值（若已知）和新值，文字或截图均可。 | 按控件身份校准工程与脚本；复用已有回传，不重复索取。 |
| 绑定后续更新位置 | 若希望复用本机脚本同步，确认正确的账号、关卡及导入脚本目录；可选择发现的候选目录或粘贴真实路径。 | 准备工作区源码与实机脚本的路径对应关系，保存配置并预览差异。 |
| 更新脚本 | 在 Web/DSH 的“Lua 脚本 → 实机脚本同步”检查源文件、目标路径和差异，选择本次文件并确认复制；也可按交付说明手动更新。 | 完成源码与索引修复、保存工程，指出新增脚本还需要建立的映射/挂载。 |
| 保存与试玩 | 在千星沙箱保存并重新试玩，按清单走开局、成功/失败、重开及本轮变更；回传异常步骤、实际结果和相关画面/日志。 | 对照预期定位问题、修复并提供下一轮更新与回归步骤。 |

绑定同步目录是便于后续更新的选项；没有本机目录访问能力时仍可交付 Lua 和明确的手动更新路径，不以绑定目录作为真机验证的强制前提。

### 导入后的索引校准

用户可以通过以下方式处理导入后的索引变化，AI 应结合实际修改检查一致性：

- **通过对话交给 AI：** 告知目标资产/控件和真实新索引，AI 同步修改模拟器索引与相关 Lua 引用。
- **在模拟器中校准：** 用户选中对应客户端控件/模板，修改“索引”，再让 AI 根据变更记录更新脚本。
- **直接修改脚本：** 用户按交付说明修改索引常量或相关引用，并告知改动文件；AI 读取实际差异，将实机/外部文件的有效修改同步回工作区源码、存档源码和控件索引。不能仅因脚本能运行就认为三者已经一致。

真实编辑器的索引是依据。按当前模拟器接口的 `setControlGuid` / `controlGuidChanges` 流程处理；手工修改没有生成记录时，仍要按控件身份核对，不能只看记录是否为空：

1. 按资产和控件身份读取变更，将连续 A→B→C 解析为最终索引；不能把模板索引和运行时控件 `Id` 混用。
2. 检查存档 `scripts[].source`、路径源码、常量、配置表、别名和身份校验，同步相关语义引用到最终索引。非空内联源码优先执行，不能只改外部 `.lua`。
3. 复核旧值残留，保留同值但无关的图片 ID 等数值。无法读取的源码或无法判定的引用保留待处理。
4. 仅在相关引用全部同步，或确认无引用后，用最新 revision 调 `acknowledgeControlGuidChanges` 确认对应记录；不清空未处理项。
5. 显式保存完整存档，重启试玩并回归创建、身份检查和受影响流程，再做真机验证。

`qxqy-simulator` 操作说明提供完整校准流程；MCP 工程操作另需 `handle`，以当前 schema 为准。修改控件索引本身不会自动修复 Lua。

### 绑定导入后的脚本存储位置

先读取存档已有同步配置；缺少时，由 AI 发现候选并请用户确认目标账号/关卡，或使用用户已明确提供的路径。多个候选不能仅按最近修改时间猜选。

| 配置项 | 含义 |
|---|---|
| 项目脚本文件夹 `workspaceDir` | 本项目在工作区内的相对目录，例如 `workspace/my-game` |
| 千星沙箱脚本文件夹 `clientImportRoot` | 当前账号/关卡实际的 `external_lua_file/default_import_file` 绝对路径 |
| 游戏里的项目子文件夹 `clientSubdir` | 保留导入后脚本映射的相对路径，通常与工作区项目目录对应 |

例如源码 `workspace/my-game/src/view.lua`，配置工作区目录和实机子目录均为 `workspace/my-game`，目标就是 `<实机导入根目录>/workspace/my-game/src/view.lua`。保留目录层级，不按文件名平铺；变更路径后核对真实编辑器的映射是否仍指向它。

这些路径属于运行模拟器服务的机器；远程 Web/MCP 不能把浏览器所在电脑的路径当作服务端可访问路径。目录绑定随完整存档保存，不写入 GIA，不会建立实时或双向同步。

### 后续让 AI 配合更新脚本

AI 可调用当前可用的 `qxqy_script_sync` 的 `discover/status/configure/preview` 发现目录、读取/保存配置和预览差异；MCP 工程操作带 `handle`，配置操作用最新 revision。调用前以当前工具 schema 为准。

1. **对齐当前版本。** 先核对索引变更、工作区源码、存档内联源码及已知的实机手改。非空白内联 `source` 优先，否则读取 `path`；不能只改磁盘文件后默认同步的是新内容。发现实机独有修改先比较并合并回项目，有真实冲突再请用户判断。
2. **保存并准备差异。** 完成引用修复和已核验变更的确认，保存完整存档，再预览每个脚本的来源、目标和新增/覆盖内容。AI 报告“已准备更新”，不能在复制前说“已同步到真机”。
3. **用户确认复制。** 当前工具只向 AI 开放配置与预览。请用户在 Web/DSH 编辑器“Lua 脚本 → 实机脚本同步”执行“保存存档并查看更新”，选择文件并点击“确认复制”。MCP 与 Web 各有会话：先在 Web `/editor` 加载 AI 保存的同一存档，再重新预览；只读预览页不能执行复制，MCP 的预览计划不能跨进程使用。AI 不调用人工复制端点或用 shell、目录联接绕过本次确认。
4. **核对结果再试玩。** 记录实际复制回执中的成功/失败和备份位置。只同步存档登记的 Lua 脚本（含未挂载的 require 模块），不是整个目录镜像；新增脚本仍须在真实编辑器建立映射和必要挂载，UI/模板结构变更另按实际情况重新交付资产。用户在千星沙箱保存并试玩，才能验证是否加载本轮源码。

用户选择手动更新时，提供本次改动文件和准确目标路径，提醒保留实机已有修改；手改后将最终版本同步回项目，以免下一轮被旧存档覆盖。复制到磁盘、编辑器保存/重新加载、真机验证分别记录，不承诺“绑定一次以后自动生效”。

### 缺陷修复与回归

请用户按交付清单实际试玩，记录真机环境、操作步骤、期望/实际、截图/日志与可复现性；证据标 `runtime=device` 并注明执行者/来源。没有真机结果的行为保持未验证，模拟器截图不能充当真机结果。

为每个真机缺陷建立最小复现，区分 Lua、素材、布局、模拟器差异与平台未知。先更新用例或明确人工检查，再修复，并重复模拟器和真机验证；保留修复前后证据。

## 产物与完成条件

产物为游戏资产、导入/挂载与实际索引记录、脚本路径和选定的更新方式、同步/手动更新结果、真机记录及修复记录。未完成的导入、挂载、引用修复、复制或真机检查分别列为待办。只有真机证据覆盖的目标行为可标通过；未回传或未覆盖的项目明确列出，交付状态保持“模拟器候选”。

## 下一步与回退

已覆盖目标且缺陷闭环时完成本轮交付。规则或代码缺陷回 [步骤 2](02-test-cases.md)、[步骤 5](05-lua-implementation.md)和 [步骤 6](06-simulator-testing.md)，素材问题回 [步骤 4](04-art-assets.md)。按项目知识维护规范沉淀证据，区分官方文档、真机观察、模拟器策略与假设。