dsh-plugin-beyond-simulator 2.0.3 → 2.0.5

package/dsh-plugin/presets/wonderland-lua-builder/skills/qxqy-game-studio/references/07-device-validation.md

@@ -0,0 +1,84 @@
+# 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)。按项目知识维护规范沉淀证据，区分官方文档、真机观察、模拟器策略与假设。

package/dsh-plugin/presets/wonderland-lua-builder/skills/qxqy-game-studio/references/workflow.md

@@ -1,66 +1,52 @@
-# 七步制作工作流
+# 接入、跨步骤决策与恢复
 
-这是 Agent 预设的主流程，顺序与仓库根 README 一致：
-
-```text
-PREFLIGHT（检查已有工程，不计入步骤）
-  → 1 策划案
-  → 2 TDD 制定测试用例
-  → 3 HTML 效果展示
-  → 4 准备千星美术参考图和素材
-  → 5 Lua 编码实现
-  → 6 测试
-  → 7 真机试玩验证与 bug 修复
-```
-
-按退出证据推进，可因新发现回退。已有工程从最早缺失证据继续；窄修复不强迫重做前面的步骤。步骤 1–4 不启动模拟器、不改存档、不运行 `runCase`。HTML 是体验展示，不是 Lua 源码或交付物。
+首次进入或恢复会话时读取本文件，再按 [Skill 的步骤索引](../SKILL.md#按需读取)读取当前一步。七个步骤各自维护操作细节，本文件只负责共同的接入与交接。
 
 ## PREFLIGHT — 接入与基线
 
-先盘点用户想法、参考图、已有 Lua、GIA、存档和反馈。检查当前工作区 `AGENTS.md`、2D API 文档、可用工具与相关 Skill。已有项目先读策划案、测试、最近试玩记录、存档与源码；只创建当前步骤需要的文件。在 `docs/production-plan.md` 记当前步骤、目标、退出证据、阻塞项。缺官方 API 文档时可以推进步骤 1–4，但写依赖编辑器 API 的 Lua 前须请用户补齐。
-
-## 1. 策划案
-
-将创意写为 `docs/gdd.md`：目标玩家与单局时长、唯一核心动词、最短循环、成功/失败/重开、PC 与手机输入、P0/P1/不做项、美术意图和关键风险。区分可由用户试玩判断的 `HYPOTHESIS`、可测试的规则 `CONTRACT`、需官方文档或真机验证的 `UNKNOWN`。把状态机、输入动作和不变量写在 GDD，复杂时另开短的 `docs/game-spec.md`；不要提前引入 DOM 选择器或 Lua 函数名。
-
-有真正玩法分歧时给用户可比较的选项和推荐。退出证据是明确的一局游戏体验、范围与规则语义。执行方法见 [design-and-tests.md](design-and-tests.md)。
-
-## 2. TDD 制定测试用例
-
-在生产 Lua 之前，根据步骤 1 的每条关键 `CONTRACT` 写 `requirement → rule/invariant → case → oracle → evidence` 追踪表。先覆盖 `boot`、`first-success`、`first-fail`、`restart`、`mobile-smoke`，每条写玩家动作、前置条件、可观察结果、画布与失败边界。用模拟器支持的 `qxqy-autotest` schema 落盘 `tests/*.json`，只做静态/schema 检查，不在此步运行模拟器。
-
-随机和计时给出确定性入口；视觉、手感、未知 API 与真机项目另列人工检查。此时只称“用例已制定”。有效 Red 要等步骤 5 的最小存档和脚本骨架可运行后产生；坏路径、坏 JSON、工具故障不算 Red。规则变化先改策划案与用例。详见 [design-and-tests.md](design-and-tests.md)。
-
-## 3. HTML 效果展示
-
-根据已定义的规则制作可打开试玩的 `prototype/`，覆盖开局、第一次成功、失败与重开。请用户体验画面、操作和节奏；没有浏览器操作工具时标 `browser-run: user`，不声称 Agent 已亲自试玩。将网页特有的动画/效果标为 `must-reproduce`、`can-degrade` 或 `concept-only`。网页新增规则必须回写策划案与用例。
-
-用户确认体验后再准备正式素材。HTML 通常原点左上、Y 向下；千星原点左下、Y 向上，禁止直接复制 CSS 像素。窄修复可跳过此步并记理由。详见 [prototype-art-playtest.md](prototype-art-playtest.md)。
-
-## 4. 准备千星美术参考图和素材
-
-以确认的 HTML 体验为依据，在 `docs/art-bible.md` 记录配色、轮廓、UI 层级、角色/道具识别特征、目标官方 `imageId`、素材来源与用途。准备参考图和素材清单，说明在千星控件中怎样还原；有真实视觉分歧时只做少量可比较方向请用户选择。使用工作区实际可见的像素画、图元拟合、UI 或帧动画 Skill。
+1. 盘点用户想法、参考图、已有 Lua、GIA、存档和反馈，检查工作区 `AGENTS.md`。
+2. 按下方[知识库发现与可用性核验](#知识库发现与可用性核验)，先检查工作区和当前 AI 宿主已配置的资料来源，再判断缺项；不要一开始就要求安装插件或提供文档。
+3. 检查会话实际提供的模拟器、浏览器和美术能力；目录存在或安装成功不等于工具可见。MCP、Web 和 Harness 的接入形式不同，使用当前宿主说明与 schema。
+4. 已有工程先读策划案、production-plan、测试、最近试玩记录、存档与源码；找出本轮目标和最早缺失的证据，确定一个当前步骤。
+5. 在 `docs/production-plan.md` 记当前步骤、目标、退出证据、阻塞项。只创建当前任务需要的文件，不为空阶段建占位产物。
 
-模拟器对非 `100001–100006` 官方素材显示缺失框，这不等于素材不能在千星使用。记下目标 ID，留待真机核验。高成本拼图/动画可先准备方案和关键样本，批量制作随步骤 5 的实现需要推进。详见 [prototype-art-playtest.md](prototype-art-playtest.md)。
+PREFLIGHT 不计入七步。新游戏按策划案 → TDD 用例 → HTML → 美术 → Lua → 测试 → 真机推进；已有工程和窄修复按证据选择步骤。
 
-## 5. Lua 编码实现
+## 知识库发现与可用性核验
 
-从此步开始使用模拟器。核对工作区官方 2D API，建立服务端 UI、客户端控件/模板和 Lua 脚本的最小骨架，保存为 `workspace/<slug>/<slug>.save.json`。先运行步骤 2 的用例，确认目标生产行为缺失导致有效 Red；随后一次实现一条规则，执行目标 Green 与相关 Regress。将纯规则与 UI 副作用分离，计时显式使用 `dt`，随机行为可复现。
+启动制作前完成一次有范围的检查；恢复会话时复用已记录来源，工具、资料版本或任务涉及的 API 变化时再定向复核。
 
-根据策划案重新实现玩法，不逐行翻译 HTML DOM/CSS/JavaScript。接入步骤 4 的目标素材；模拟器缺失框要记录真实目标 ID。交付物是可加载的 Lua 与存档，按需导出 GIA；记录脚本挂载点。未知 API 先查文档或做单问题探针，不猜字段。
+1. **先查工作区入口。** 从 `AGENTS.md`、README、项目索引及其引用位置寻找官方 Lua API、客户端脚本使用指南、控件/模板与脚本挂载说明、已知问题和真机记录。检查项目内的 Skill、MCP 或插件配置；本地知识库可能位于被 Git 忽略的目录，按已发现的目录定向检索，不扫描整块磁盘。
+2. **再查当前 AI 宿主的配置与能力目录。** 优先使用宿主提供的插件、MCP、Skill 列表；必要时只读其已知项目级/用户级配置中相关的名称、启用状态、资源入口和本地路径。寻找 `miliastra-toolbox` 系列（如 `dsh-plugin-miliastra-toolbox`）、其他知识库服务及本地文件知识库。名称可能是别名，不能只凭插件名认定资料覆盖范围；不改配置、不回显令牌或无关配置内容。
+3. **核验实际内容。** 对候选来源检查当前会话是否能调用/读取，再定向取一段官方 Lua API 和相关使用指南，确认属于千星客户端 2D UI + Lua，并能读取函数签名、参数/枚举和操作说明。不要为检查可用性加载整套文档。仅提供 3D 节点图资料、只有检索摘要或接口表缺失的来源，不算已取得所需 Lua 官方资料。
+4. **记录来源和缺项。** 在 `docs/production-plan.md` 记录来源名称、工具/路径、文档标题与可得的版本/日期、适用范围、当前读取结果。区分“已配置”“本会话可调用/读取”“已取得所需官方资料”；配置不可读或工具未加载时记“尚未核实/当前不可用”，不推断用户没有配置。官方文档、实战经验、真机观察和模拟器策略分别标注；不同版本冲突先核对来源，不拼凑签名。
+5. **优先复用，再补缺项。** 已有资料够用就继续，不重复要求安装；连接不可用但本地资料够用时使用本地资料并记录来源。只有缺少本轮所需内容时，才简短说明缺哪份资料或哪个能力，请用户启用已有连接、提供可读路径或补充相应文档。可继续步骤 1–4，依赖缺失 API 的 Lua 实现须等资料补齐。
 
-## 6. 测试
+向用户简述找到的可用来源与实际缺项即可，无需报告全部配置清单。模拟器工具可用与知识库可用分别检查，不能互相替代。
 
-运行 P0 与高风险边界用例，复现并修复实现缺陷。使用 `qxqy_studio_play` 走开局、首次成功、失败、重开，用 `qxqy_studio_ui_screenshot` 和 `qxqy_studio_play_screenshot` 检查静态/运行画面。手机 16:9 整屏可见，PC 等比放大/留边；必要时扩展五画布、触控、重复输入、暂停恢复、服务端信号与性能预算。
+## 产物位置与恢复
 
-让用户在模拟器页观察试玩手感，分清规则失败、视觉问题和体验假设；一次调整少量变量，随后回归。模拟器结果标 `runtime=simulator`，不能写作真机通过。保留用例结果、截图、已知限制与导出警告。详见 [prototype-art-playtest.md](prototype-art-playtest.md)。
+`workspace/<slug>/` 是项目产物位置，下列路径相对该目录：
 
-## 7. 真机试玩验证与 bug 修复
+| 产物 | 用途 |
+|---|---|
+| `docs/gdd.md`、按需 `docs/game-spec.md` | 玩法语义、范围与契约 |
+| `docs/production-plan.md` | 当前步骤、知识来源与可用性、证据位置、未完成项和下一步 |
+| `tests/` | 规则用例；测试 JSON 不是存档 |
+| `prototype/` | HTML 展示与操作说明 |
+| `docs/art-bible.md` | 参考图、目标素材和 UI 还原方案 |
+| `main.lua`、`<slug>.save.json` | 源码与完整工程，存档头部附近有 `"format": "qxqy-simulator-save"` |
+| `docs/tech-architecture.md` | 文件/控件职责、变量/信号、数据流和脚本挂载 |
+| `docs/device-handoff.md` | 真机导入、真实索引、脚本路径/挂载、同步方式与待办；可合并进已有交付说明 |
+| `records/playtest.md`、`export/` | 试玩/修复证据与交付资产 |
 
-整理 Lua、完整存档/GIA、挂载说明、目标素材 ID、测试结果和已知限制，提供真机操作步骤。请用户在千星奇域实际试玩并回传画面、日志、步骤和期望/实际结果。Agent 不在真机上执行过的步骤必须标未验证。
+试玩记录按 `runtime=html|simulator|device` 标来源、执行者、步骤、期望/实际、未知项和修复后回归。恢复时先读实际产物与证据，避免仅凭聊天摘要重做项目；用户已提供的信息直接复用。
 
-对每个真机缺陷建立最小复现，判断是 Lua、素材、布局、模拟器差异还是平台未知；先更新用例或人工检查，再修复并重复模拟器与真机验证。只有真机证据覆盖目标行为，才能标记该行为通过；尚未回传则交付状态为“模拟器候选”。
+## 回退与完成
 
-## 产物与跨会话恢复
+- 设计问题：回步骤 1–3，更新契约和用例。
+- 素材问题：回步骤 4，记录目标 ID 与还原方案。
+- 规则或代码缺陷：补步骤 2 的最小用例，再到步骤 5–6 修复和回归。
+- 真机差异：在步骤 7 留存证据，回到受影响步骤修复，再验证真机结果。
 
-`workspace/<slug>/` 是项目产物位置。按需创建 `docs/gdd.md`、`docs/production-plan.md`、`tests/`、`prototype/`、`docs/art-bible.md`、`main.lua`、`<slug>.save.json`、`records/playtest.md`、`export/`。存档头部附近含 `"format": "qxqy-simulator-save"`，测试 JSON 不是存档。`docs/production-plan.md` 记录当前步骤和退出证据；`records/playtest.md` 按 `runtime=html|simulator|device` 记来源、结果、未知和修复后回归。恢复时先读这些实际产物，不凭聊天摘要重做项目。
+只加载受影响步骤，不把回退理解为整套重跑。真机未验证时交付状态为“模拟器候选”；只有目标行为有真机证据时才标记该行为通过。

package/dsh-plugin/skill.md

@@ -77,6 +77,34 @@ qxqy_studio_play { "action": "view",  "args": { "playerIndex": 2 } }     ← 切
 - 未知 protobuf 字段不保证往返回写。
 - 若当前工作区就是模拟器源码仓库，可先运行 `cd simulator/studio && npm run generate:client-template` 生成探针文件 `probes/client-template-import/qxqy-lua-instantiable-panel.gia`，再导入验证 Lua 动态实例化（预期模板索引 `1073742100`；真实编辑器若重映射，以导入后检视器显示值为准）。
 
+### 5. 导入后校准客户端控件索引并同步 Lua
+
+真实编辑器导入 GIA 后可能重新分配客户端控件索引。以用户回传的实际索引为准，在模拟器选中对应客户端控件后修改「索引」，或对当前资产调用：
+
+```json
+{ "op": { "op": "setControlGuid", "id": "对应控件的内部 id", "guid": 1073742200, "expectedRevision": 12 } }
+```
+
+`guid` 是编辑器控件/模板索引，须为 `1–2147483647` 的整数，且不能与工程中其他控件或脚本索引重复。服务端「客户端控件容器」不能用此操作修改；其下的客户端节点和客户端模板均可修改。操作保留内部 `id`、层级和脚本挂载，不会自动改写 Lua。
+
+**AI 必须把索引变更与 Lua 引用同步作为同一项修复完成：**
+
+1. 先 `get` 读取当前控件资产、全部脚本和 `controlGuidChanges`；需要查看另一类资产时，用 `selectAsset` 的 `assetType` 切换后再读取。变更记录按时间排列，含 `id`、`controlAsset`、`controlId`、`controlName`、`oldGuid`、`newGuid`；用资产和内部控件身份确认目标。连续变更应沿记录追到该控件的最终索引，不能逐条盲替换数字。
+2. 检查全部相关脚本的索引引用，包括直接调用、常量、配置表、别名和 `prefabIndex` 身份校验，按语义修改为最终索引。`game.InstantiateClientUIControl` 的首参是模板索引；`game.GetClientUIControl` 的参数与控件 `Id` 是运行时实例 ID，不能当作模板索引替换。图片 ID、脚本映射 ID、同级顺序和无关数值也不能随之改动。
+3. 同步存档 `scripts[].source` 与对应的工作区 `.lua` 源文件。试玩优先使用非空 `source`，仅当它为空时读取 `path`；只改外部文件可能仍会运行旧源码。路径脚本没有内联内容时保持该存储方式，但必须检查实际文件。找不到相关源码或无法判定引用时，保留未处理记录并说明缺项。
+4. 复核旧索引残留及受影响的创建、身份检查流程；全部引用已同步，或确认该变更没有 Lua 引用后，才用最新 revision 调 `acknowledgeControlGuidChanges`，仅清理已核验记录：`{ "op": { "op": "acknowledgeControlGuidChanges", "changeIds": ["变更记录 id"], "expectedRevision": 15 } }`。这个操作只确认 AI 已处理，不会修改源码。
+5. 保存完整存档，重新启动试玩并执行受影响用例；报告实际的旧→新索引、同步脚本及验证结果。模拟器通过不代表真机通过；不能只修改控件索引就宣称修复完成。
+
+未处理记录会保存在完整存档中，导出时也会提醒同步引用。MCP 调用另需 `handle`，示例见 [`mcp/README.md`](../mcp/README.md#客户端控件索引校准)。
+
+### 6. 已导入 GIA 后，显式复制脚本更改到实机
+
+使用 `qxqy_script_sync` 的 `discover/status/configure/preview` 配置或检查实机脚本目录。configure 的 args 为 `{ config: { version: 1, workspaceDir, clientImportRoot, clientSubdir }, expectedRevision }`；MCP 另带 handle。路径位于宿主机器，配置随完整存档保存。`workspaceDir` 与 `clientSubdir` 通常同值，以保留 GIA 映射的相对路径；不要按文件名平铺。
+
+先完成 `controlGuidChanges` 的语义引用修复和确认，再准备复制。内容沿用非空白内联 source 优先、否则 path 文件；两者不同须核对，不能只改磁盘后默认复制新内容。保存完整存档后，请用户在 Web/DSH「Lua 脚本 → 实机脚本同步」检查差异并点击「确认复制」。MCP 与 Web 各有会话，需先在 Web 编辑器加载 AI 保存的存档。AI 不调用人工复制端点或用 shell 绕过本次确认；不得建立目录联接替代复制。
+
+已有脚本内容变更复制后，在千星沙箱保存并重新试玩；新增脚本仍需建立映射和必要挂载。工具成功只表示复制到磁盘，不能声称真机通过。覆盖前备份、过期计划拒绝、文件选择等见 [脚本同步](../studio/docs/script-sync.md)。
+
 ## 工作流二：自定义交互测试队列（自动化测试用例）
 
 试玩会把指针、按键、点击和服务端写变量/发信号记进时间线（`t` 为引擎时钟，不是墙钟）。可用 `qxqy_studio_play` 保存、回放并断言。
@@ -141,7 +169,7 @@ qxqy_studio_play { "action": "serverSend", "args": { "target": "PlayerSelf", "na
 
 play 动作：`start`（重建运行时；可带 `canvasId` 指定设备画布、`playerCount` 指定 1–8 人）、`device`（按 `args.canvasId` 切换设备画布并重建运行时）、`view`（按 `args.playerIndex` 切换当前玩家视角，不重建运行时）、`get`、`step`（`dt` 秒）、`pointer`（`type` = move/down/up/click，click = down+up；`x`/`y` 为当前画布像素）、`key`（按脚本注册监听的键名）、`click`（按控件名直接触发）、`pause`/`resume`、`stop`、`serverGet`/`serverSet`/`serverSend`、`history`/`saveCase`/`runCase`（可带 `canvasId` 钉住用例设备，可带 `playerCount`）。未 start 时 `pointer` / `key` / `click` 都会报 `play session has not started`。
 
-常用 patch op：`select`（id）、`pick`（x/y 命中）、`setCanvas`（canvasId）、`addScript` / `updateScript` / `removeScript`（脚本由存档统一管理；服务端容器会被拒绝）、`setServerLogic`（规则定义）、`newAsset`（assetType）、`addTemplate`、`add`（parentId/kind/name）、`reparent`、`moveSibling`（direction=up/down）、`remove`、`set`（id/key/value）、`replace`（project）。数据写操作必须带 `expectedRevision`。
+常用 patch op：`select`（id）、`pick`（x/y 命中）、`setCanvas`（canvasId）、`addScript` / `updateScript` / `removeScript`（脚本由存档统一管理；服务端容器会被拒绝）、`setServerLogic`（规则定义）、`newAsset`（assetType）、`addTemplate`、`add`（parentId/kind/name）、`reparent`、`moveSibling`（direction=up/down）、`remove`、`set`（id/key/value）、`setControlGuid`（id/guid，改当前资产的客户端控件索引）、`acknowledgeControlGuidChanges`（changeIds，核验 Lua 同步后清理指定变更记录）、`replace`（project）。数据写操作必须带 `expectedRevision`。
 
 `set` 常用 key：变换类 `posX/posY/width/height`、`rotationZ`、`anchorType`、`anchorMinX/Y`、`anchorMaxX/Y`、`pivotX/Y`；业务类 `text`、`fontSize`、`imageId`、`enableMask`、`enableFill`、`fillType`、`fillAmount`(0–1)、按钮四状态 `unavailableChildId/hoverChildId/pressedChildId/selectedChildId`、`syncAllDevices`；颜色接受 `#AARRGGBB`。以上是常用子集，未列出的字段不要猜——`set` 对不认识的 key 会直接报错，以报错为准。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-beyond-simulator",
-  "version": "2.0.3",
+  "version": "2.0.5",
   "description": "千星奇域客户端 UI 编辑与试玩模拟器 for DeepSeek Harness",
   "type": "module",
   "packageManager": "pnpm@10.15.0",

package/dsh-plugin/presets/wonderland-lua-builder/skills/qxqy-game-studio/references/design-and-tests.md

@@ -1,167 +0,0 @@
-# 设计、共享规格与测试
-
-本 reference 用于步骤 1（策划案与玩法契约）、步骤 2（TDD 测试用例）和步骤 5（Lua 实现中的 Red→Green→Regress）。只读取当前步骤需要的章节。
-
-```text
-策划案 requirement → HYPOTHESIS / CONTRACT / UNKNOWN
-                 → 玩法契约与 TDD 测试用例（步骤 2）
-                 → HTML 效果展示（步骤 3，不碰模拟器）
-                 → Lua 实现与模拟器测试（步骤 5–6）
-                 → 真机试玩与修复（步骤 7）
-```
-
-## 1. GDD：把创意压缩为 P0
-
-复制到 `workspace/<game>/docs/gdd.md`。未知项写 `TBD`/`UNKNOWN`，每条陈述标为 `HYPOTHESIS`、`CONTRACT` 或 `UNKNOWN`。
-
-```markdown
-# <游戏名> GDD
-
-- slug / 当前里程碑：P0 完整一局游戏体验
-- 当前步骤：1 策划案
-- 策划状态：draft / locked；用户确认摘要：
-- 更新日期 / 本轮砍项及理由：
-
-## 玩家与幻想
-- 目标玩家、熟练度、典型场景、单局时长：
-- 一句话幻想：玩家在 ______，通过 ______，获得 ______ 的感觉。
-- 题材、角色/物件与边界：
-
-## 体验支柱
-| HYPOTHESIS | 玩家可感知表现 | 反例 | 验证方式 |
-|---|---|---|---|
-| | | | HTML 演示（前期）/ 模拟器试玩（交付） |
-
-## P0 核心循环
-- 唯一核心动词 / 键鼠与触屏输入：
-- 开局看到什么 / 第一次有效操作：
-- 成功、失败、反馈、重开和最短上手路径：
-- 目标：`目标 → 操作 → 即时反馈 → 局势变化 → 成功/失败 → 重开`
-
-## 范围
-| 优先级 | 包含 | 成功标准 |
-|---|---|---|
-| P0 | | |
-| P1 | | |
-| P2 / 不做 | | |
-
-## 体验与约束
-- 可访问性：颜色之外的反馈、文字/语言、闪烁、音频依赖：
-- PC/手机画布、触控热区、单手/双手假设：
-- 美术意图、素材用途（参考/原型/发布候选）与权利假设：
-
-## HTML 效果展示（步骤 3，不碰模拟器）
-- 必须可玩的场景：boot / first-success / first-fail / restart
-- `must-reproduce` / `can-degrade` / `concept-only`：
-- 坐标：千星左下 Y 上；HTML 左上 Y 下；禁止从网页抄像素
-
-## P0 用例与试玩
-| 用例 | 关联 CONTRACT | 玩家动作 | 期望结果 | 画布 |
-|---|---|---|---|---|
-| boot | | | HUD/`game_start` | mobile-16-9 |
-| first-success | | | | mobile-16-9 |
-| first-fail | | | | mobile-16-9 |
-| restart | | | | mobile-16-9 |
-| mobile-smoke | | 最短成功路径 | 整屏可见+不崩溃+关键状态 | mobile-16-9 |
-
-| HYPOTHESIS | 任务（不泄题） | HTML 展示（步骤 3） | 模拟器测试（步骤 6） |
-|---|---|---|---|
-| | 请直接开始玩 | | |
-
-## 风险与未知
-| 风险/UNKNOWN | 影响 | 当前证据 | 验证方式/负责人 | 最晚阶段 |
-|---|---|---|---|---|
-| API / GIA / 资产 / 真机 | | | knowledge/probe/device | |
-```
-
-策划确认只锁产品语义、P0、砍项和关键规则歧义；函数名、控件拆分和目录由 Agent 自行决定。
-
-## 2. 共享 game-spec / ui-spec
-
-P0 把契约写在 GDD 或短的 `docs/game-spec.md`。仅当选择 HTML 轨且两边共同消费时，才加 `prototype/game-spec.json`。不得写 DOM 选择器、CSS 类、JS/Lua 函数名。布局字段使用千星坐标：原点左下，Y 向上，锚点 0–1。
-
-### game-spec 必须回答
-
-- 状态机：`boot → ready → playing → resolved(win|fail) → restart`，暂停若为 P0 也要建模；
-- 状态数据、生命周期、客户端/服务端权威；
-- 输入动作、前置状态、节流、热区、无效输入与结束后行为；
-- 显式 `dt`、位置/速度/碰撞边界、可注入 seed/序列；
-- 成功/失败/重开、领域事件、稳定日志和错误降级；
-- 每条不变量（INV）及对应的可观察 oracle；
-- 未知平台事实、责任人、探针或真机验证。
-
-### ui-spec 必须回答
-
-| 字段 | 含义 |
-|---|---|
-| `id` / `kind` | 稳定控件名与 `container/image/text/button/progress` 等目标类型 |
-| `parent` / `anchor` / `offset` / `size` | 控件树与跨画布布局 |
-| `styleToken` / `assetId` | 色板、字号、间距与资产清单引用 |
-| `visibleWhen` / `action` | 可见状态与抽象玩家动作 |
-| `motionIntent` | 触发、时长、曲线和可降级方式 |
-
-HTML（若存在）与 Lua 可以有不同适配层；稳定的状态、动作、控件和资产 id 必须可追踪。网页坐标不得进入 Lua。
-
-## 3. 测试设计与追踪
-
-在步骤 2 建立 `requirement → rule/invariant → 模拟器场景 → qxqy case → oracle → evidence` 表。`HYPOTHESIS` 指向 HTML、模拟器与用户试玩，`CONTRACT` 指向自动化 oracle，`UNKNOWN` 指向知识、探针或真机。
-
-### 五层证据
-
-| 层 | 验证 | 证据 |
-|---|---|---|
-| L0 | JSON、路径、挂载、控件树 | 静态检查、`qxqy_studio_get` |
-| L1 | 纯状态、计分、碰撞、生成、边界 | 纯函数/窄接口回放 |
-| L2 | 输入→状态/日志/控件/变量/信号 | `qxqy-autotest` + `runCase` |
-| L3 | 布局、层级、裁切、反馈、动画 | `qxqy_studio_ui_screenshot` / `qxqy_studio_play_screenshot` |
-| L4 | 易懂、公平、节奏、触控、真机 | 观察式试玩、用户反馈、真机 |
-
-可选 HTML 只能提前沟通体验；不能替代 L2–L4。模拟器看不见的官方图不算视觉回归失败，记目标 ID，真机看效果。
-
-### TDD 边界
-
-必须 Red→Green→Regress：状态、胜负、计分、冷却、碰撞边界、暂停/重开、稳定输入语义、服务端变量/信号和已复现缺陷。
-
-先原型后固化：跳跃/速度手感、反馈节奏、UI 层级和尚未确定的玩法语义。
-
-先探针后规格：未文档化 API、imageId、GIA 字段、生命周期和真机行为。
-
-有效 Red 必须是“目标生产行为缺失”。坏 JSON、路径错误、事件到不了控件、模拟器未启动和 schema 错误是基础设施失败，不算 TDD Red。
-
-### 确定性与 oracle
-
-- 运动、冷却和计时显式消费 `dt`；随机玩法由配置、变量、首事件或测试入口注入可复现 seed/序列；
-- 每个用例独立启动，切画布是新生命周期；不依赖墙钟、机器速度或偶然帧；
-- 稳定日志使用 `game_start`、`score <n>`、`fail <reason>`、`restart` 等领域事件；
-- 优先断言玩家可见控件/状态，其次稳定事件，最后才是 `query.*` 诊断；测试不得复制生产算法；
-- 覆盖顺序按高风险、高频、最近缺陷和复杂状态转换，而非虚假的百分比。
-
-## 4. P0 qxqy-autotest
-
-使用模拟器支持的 `qxqy-autotest` / `version: 1`，不要自创 schema。每个用例独立保存到 `workspace/<slug>/tests/`：
-
-```json
-{
-  "format": "qxqy-autotest",
-  "version": 1,
-  "name": "boot",
-  "dt": 0.03333333333333333,
-  "events": [],
-  "asserts": [
-    { "kind": "log", "contains": "game_start", "source": "client" },
-    { "kind": "tree", "name": "ScoreText", "exists": true }
-  ]
-}
-```
-
-最小 P0：`boot`、`first-success`、`first-fail`、`restart`、`mobile-smoke`。稳定控件优先用 `click`，只有坐标本身是规则时才用 `pointer`；`mobile-smoke` 使用独立 `args.canvasId`，不要与 PC 串联。布局与 HUD 以 `mobile-16-9` 为完整可见基准，PC 画布只做放大/留边，不裁掉手机上看得到的内容。缩放容器不要再加全屏不透明兄弟节点。
-
-步骤 2 完成用例和静态/schema 校验；步骤 5 运行最小存档后，`first-success`、`first-fail`、`restart` 至少一次因生产行为缺失而 Red。每次实现记录：
-
-```text
-case / red reason / failedAt / frame
-minimal change / target result / full regression
-screenshot or snapshot / remaining risk
-```
-
-P0 后按玩法增加 `edge-contact`、`input-spam`、`pause-resume`、`restart-twice`、`large-dt` 和其余四画布 smoke。体验反馈只有形成稳定规则后才转自动化测试。

package/dsh-plugin/presets/wonderland-lua-builder/skills/qxqy-game-studio/references/prototype-art-playtest.md

@@ -1,38 +0,0 @@
-# HTML 效果展示、美术素材与试玩
-
-本 reference 用于步骤 3（HTML 效果展示）、步骤 4（千星美术参考图和素材）、步骤 6（模拟器测试）与步骤 7（真机试玩）。每条证据标 `runtime=html|simulator|device`。
-
-## 步骤 3：HTML 效果展示
-
-网页用于对齐「看起来、玩起来像什么」，依据步骤 2 已写的规则做 boot / first-success / first-fail / restart。最小产物：
-
-```text
-prototype/index.html
-prototype/README.md    启动、操作、不可移植项、坐标差异
-```
-
-请用户打开网页试玩；本预设没有浏览器试玩工具时，证据标 `browser-run: user`。网页新增规则回写策划案与测试用例。将画面/动画分成 `must-reproduce`、`can-degrade`、`concept-only`；HTML 不是 Lua 或真机证明。千星原点左下、Y 向上，HTML 通常左上、Y 向下，禁止直接搬运 DOM/CSS 坐标。用户确认效果后进入美术素材准备；窄修复可跳过并记理由。
-
-## 步骤 4：准备千星美术参考图和素材
-
-根据确认的 HTML 效果，在 `docs/art-bible.md` 记录体验形容词、主/辅/警示色、轮廓、层级、角色/道具特征、目标官方 `imageId` 和模拟器占位。准备参考图、素材清单与千星控件还原方案。需要比较时，在同一 HTML 布局与玩法状态中做少量不同方向；没有真正分歧时采用推荐方向。
-
-官方原神/千星素材可以用。模拟器只预览 `100001–100006` 六种基础图元，其余图片 ID 显示缺失框；这不是禁用，真机才可验证最终画面。高成本像素重建与帧动画先做关键样本，按 Lua 实现需求批量生产。当前会话若有像素画、图元拟合、UI 制作或帧动画 Skill，可按需调用。
-
-## 步骤 6：模拟器测试与观察试玩
-
-加载 `qxqy-simulator`，运行步骤 2 的用例；对新增缺陷先留最小复现，再修复和回归。Agent 可用：
-
-| 目的 | 工具 |
-|---|---|
-| 点击、按键、时间和断言 | `qxqy_studio_play` |
-| 静态布局截图 | `qxqy_studio_ui_screenshot` |
-| 运行画面截图 | 先 `play start`，再 `qxqy_studio_play_screenshot` |
-
-画布原点左下、Y 向上。布局以 `mobile-16-9`（1280×720）完整可见为基准；PC 用同一设计板等比放大或留边，不裁掉手机内容。每轮只验证少量问题：规则回归、截图层级/裁切/反馈、用户能否理解目标与失败、控件/Lua/资源预算。用户可在模拟器页盲玩；Agent 不得把 HTML 截图或搜索结果充当模拟器试玩。
-
-反馈分类为 `bug / design / art-content / platform / not-now`。设计问题回步骤 1–3，素材问题回步骤 4，规则/实现问题回步骤 2、5–6，平台未知建探针或交给步骤 7。一次调整少量变量以便归因。模拟器看不见官方图时保留 `targetId`，不能把缺失框当作禁用资源。
-
-## 步骤 7：真机试玩验证与 bug 修复
-
-把完整存档、Lua/GIA、操作说明、挂载关系、官方图片 ID 和已知警告交给用户在千星奇域验证。记录真机环境、步骤、期望/实际、截图/日志与可复现性。真机问题先形成用例或明确的人工检查，再修复并回归模拟器和真机；用户尚未完成真机试玩时标“模拟器候选”，不称发布通过。GIA 不保存脚本挂载关系，交付说明必须单列挂载步骤。