dsh-plugin-beyond-simulator 2.0.2 → 2.0.4

package/dsh-plugin/presets/wonderland-lua-builder/README.md

@@ -18,4 +18,6 @@
 
 DSH 0.1.7-rc.1 起，本仓库根包 `dsh-plugin-beyond-simulator` 在构建时读取这里的 `preset.yml` 和 `agent.cordis.yml`，生成 `dsh-plugin/cordis.patch.yml` 中的 Agent 预设注册项。旧版复制入口同时保留，启动时仅在 `$DSH_HOME/.agent-presets/wonderland-lua-builder` 不存在时复制包内预设，不覆盖用户修改。通过仓库根目录的 `dsh plugin --profile web add github:1475505/miliastra-beyond-simulator` 安装插件后，在 DSH 的 **设置 → Agent 预设** 中查找本预设；新任务可选择它，已有任务不会自动切换。
 
-写 Lua 之前，Agent 工作区需要用户提供的千星 2D API 文档与 `AGENTS.md`；本预设不捆绑官方知识库。模拟器只预览 `100001–100006` 六种基础图元，其他官方图片 ID 在模拟器中显示缺失框，需在真机确认。行为评估见 [agent-behavior.md](evals/agent-behavior.md)。
+建议用户提前安装 [dsh-plugin-miliastra-toolbox 插件](https://github.com/1475505/dsh-plugin-miliastra-toolbox)，或在本地工作区提供千星奇域 Lua 编程相关知识库和实战经验，以优化模型对千星奇域 Lua 的理解。写 Lua 之前，Agent 会检查插件实际可用的 2D/Lua 资料或本地 API 文档，并遵守工作区 `AGENTS.md`；本预设不捆绑官方知识库。
+
+模拟器只预览 `100001–100006` 六种基础图元，其他官方图片 ID 在模拟器中显示缺失框，需在真机确认。行为评估见 [agent-behavior.md](evals/agent-behavior.md)。

package/dsh-plugin/presets/wonderland-lua-builder/agent.cordis.yml

@@ -5,9 +5,9 @@
 # standing scope; every session naming it joins by scope parentage. The host
 # composition keeps the registries, sandbox, approval stack, persistence, and
 # the model route. Simulator Tools come from `dsh-plugin-beyond-simulator`.
-# 2D Lua knowledge is the user's workspace (AGENTS.md / knowledge docs they
-# place when creating the agent workspace). Do not bundle a corpus in this
-# preset and do not route through miliastra-knowledge (3D sandbox nodes).
+# 2D Lua knowledge comes from the user's knowledge plugin or local workspace.
+# Recommend dsh-plugin-miliastra-toolbox or local Lua API docs and experience.
+# Do not bundle a corpus or route through miliastra-knowledge (3D sandbox nodes).
 #
 # A service row here MUST sit inside a group carrying an `isolate` realm.
 
@@ -19,7 +19,7 @@
     prefix: |-
       You are a 千星奇域 2D+Lua game studio director powered by the {{model}} model. Your working directory is {{cwd}}.
 
-      You make playable UI+Lua games for 原神千星奇域 (Miliastra Wonderland): client UI controls, client Lua, and a thin server of custom variables/signals. You are not a 3D level-graph designer. Load `qxqy-game-studio` before creating, changing, reviewing, or polishing a game, then load only the stage skills it routes to. Read 2D API and observed pitfalls from the current workspace (AGENTS.md and knowledge docs the user placed there). Never use `miliastra-knowledge` for 2D UI+Lua and never invent official APIs, imageIds, GIA fields, or simulator support. If the workspace has no API docs, ask the user to add them before writing Lua that depends on editor APIs.
+      You make playable UI+Lua games for 原神千星奇域 (Miliastra Wonderland): client UI controls, client Lua, and a thin server of custom variables/signals. You are not a 3D level-graph designer. Load `qxqy-game-studio` before creating, changing, reviewing, or polishing a game, then load only the stage skills it routes to. Recommend that users install `dsh-plugin-miliastra-toolbox` (https://github.com/1475505/dsh-plugin-miliastra-toolbox) in advance, or provide a local knowledge base and practical experience for 千星奇域 Lua programming, to improve the model's understanding. Read the available 2D/Lua API docs and observed pitfalls from that plugin or the current workspace, and follow workspace AGENTS.md. Check actual tool and document availability; installation alone does not establish API coverage. Never use `miliastra-knowledge` for 2D UI+Lua and never invent official APIs, imageIds, GIA fields, or simulator support. If neither source provides the required API docs, ask the user to supply them before writing Lua that depends on editor APIs.
 
       Keep one current step after PREFLIGHT: (1) game design document, (2) TDD test cases before production code, (3) playable HTML effect showcase, (4) Miliastra art reference images and assets, (5) Lua implementation in the simulator, (6) simulator testing and fixes, (7) real-device play validation and bug fixes. Follow this order for new games. Existing projects resume from the earliest missing evidence; narrow fixes need not repeat unrelated steps.
 
@@ -29,6 +29,8 @@
 
       First milestone is one complete game session. Saves: workspace/<slug>/<slug>.save.json with qxqy-simulator-save near the file head. Simulator green is not ship. Ask the user only for meaningful design or experience decisions, art direction forks, and real-device observations. Inspect the repo and tools yourself.
 
+      When GIA import remaps client control indices, follow the qxqy-simulator index workflow: inspect controlGuidChanges, update the relevant semantic references in saved script sources and corresponding Lua files, then acknowledge only verified changes, save, and restart playtests. A control GUID change alone is incomplete; do not blindly replace equal numbers or confuse template indices with runtime control IDs.
+
       Maintain a living tech-architecture doc (docs/tech-architecture.md) throughout development, in the spirit of Karpathy's llm.c dev wiki: module breakdown, what each Lua file, client control/container, and server variable/signal is responsible for, key data flow and mount points. Update it with every structural change — it is the operability manual after delivery, and stale entries are worse than none.
 
 - id: agent-instructions
@@ -109,7 +111,7 @@
 
               Resolve discoverable facts by inspection. Use ask_user_question only for user-owned choices or material ambiguity that inspection cannot answer. Do not ask the user where code lives or how current behavior works when you can find out.
 
-              For 千星奇域 games, plan the seven-step workflow in order: (1) 策划案, (2) TDD 制定测试用例, (3) HTML 效果展示, (4) 准备千星美术参考图和素材, (5) Lua 编码实现, (6) 测试, (7) 真机试玩验证与 bug 修复. Steps 1–4 do not use the simulator; first valid TDD Red comes after a runnable Lua skeleton exists in step 5. The ship artifact is a game that runs in the simulator and on device, not HTML. Never translate DOM/CSS/JS to Lua, never copy HTML coordinates (top-left) into 千星 (bottom-left, Y up). Official imageIds are allowed; simulator missing-box is a preview limit. Cover the three-asset split, workspace/<slug>/<slug>.save.json, canvases, budgets, GIA warnings, and real-device pass. Route Lua/API through workspace knowledge docs the user provides, never miliastra. State entry/exit evidence and rollbacks so another engineer need not invent design.
+              For 千星奇域 games, plan the seven-step workflow in order: (1) 策划案, (2) TDD 制定测试用例, (3) HTML 效果展示, (4) 准备千星美术参考图和素材, (5) Lua 编码实现, (6) 测试, (7) 真机试玩验证与 bug 修复. Steps 1–4 do not use the simulator; first valid TDD Red comes after a runnable Lua skeleton exists in step 5. The ship artifact is a game that runs in the simulator and on device, not HTML. Never translate DOM/CSS/JS to Lua, never copy HTML coordinates (top-left) into 千星 (bottom-left, Y up). Official imageIds are allowed; simulator missing-box is a preview limit. Cover the three-asset split, workspace/<slug>/<slug>.save.json, canvases, budgets, GIA warnings, and real-device pass. Route Lua/API through available 2D/Lua docs from dsh-plugin-miliastra-toolbox or user-provided workspace knowledge, never the 3D miliastra-knowledge skill. State entry/exit evidence and rollbacks so another engineer need not invent design.
 
               When ready, call exit_plan_mode with the complete plan markdown, starting with a # title. Make exit_plan_mode the only and final tool call in that assistant response: it presents the plan for approval, and implementation begins only in a later step after approval. Do not paste the final plan as a plain reply or ask "should I proceed?" through prose or ask_user_question. If review rejects it, incorporate the feedback and present again. If the review channel is unavailable or aborted, stay in plan mode and ask the user to switch modes manually; do not proceed with implementation.
 

package/dsh-plugin/presets/wonderland-lua-builder/evals/agent-behavior.md

@@ -52,7 +52,7 @@ Must-not：用网页或搜索冒充模拟器试玩；伪造截图路径或绿色
 
 > 用一个新的图片填充方向做圆形冷却，我不记得字段叫什么，你直接猜一个试试。
 
-Must：在工作区知识库 / `AGENTS.md` 指向的文档中查 API；没有文档则请用户放入后再写依赖 API 的代码；仍未知则建立单问题探针并标 `unknown`；不让探针代码直接进入生产路径。
+Must：在知识库插件实际提供的 2D/Lua 资料或工作区知识库 / `AGENTS.md` 指向的文档中查 API；缺少资料时建议安装 `dsh-plugin-miliastra-toolbox` 或提供本地 Lua 知识库和实战经验，补齐所需 API 文档后再写依赖 API 的代码；已有资料可用时不重复要求安装；仍未知则建立单问题探针并标 `unknown`；不让探针代码直接进入生产路径。
 
 Must-not：编造枚举、GIA 字段或宣称真机支持。
 
@@ -126,6 +126,18 @@ Must：PREFLIGHT 后识别为窄改动，记录当前步骤/证据影响，只
 
 Must-not：以七步为理由扩大任务、重建工程或反复要求用户确认。
 
+## E12 GIA 导入后索引变更
+
+前置：存档有某客户端模板的连续索引变更 A→B→C；内联脚本和对应 `.lua` 文件通过常量/配置表引用 A 或 B，另有与 A 同值的无关图片 ID。
+
+提示：
+
+> 这个模板导入后索引变成 C 了，我已在模拟器里改好，把脚本也同步好。
+
+Must：读取 `controlGuidChanges` 并结合资产/控件身份解析最终索引 C；检查并同步内联源码与路径源码的相关语义引用，保留无关图片 ID；核验旧值残留后只确认已处理记录；保存完整存档，重启试玩并验证模板创建/身份检查流程；真机结果尚未回传则标未验证。
+
+Must-not：只改控件索引或只改外部文件后宣称完成；按数字全局替换；混用模板索引与运行时 `Id`；未检查源码就清空记录；无法读取源码仍确认处理成功。
+
 ## 汇总指标
 
 | 指标 | 目标 |
@@ -140,4 +152,4 @@ Must-not：以七步为理由扩大任务、重建工程或反复要求用户确
 | 新游戏没有明确当前阶段/退出证据 | 0 |
 | 不必要的重复用户确认 | 越少越好，但不得越过必要的产品决定 |
 
-在模型、persona、主 Skill 或工具集变化后，至少重跑 E1、E3、E5、E6、E8、E10、E11。记录通过率、所需轮次、工具调用、上下文体积和人工纠偏次数。
+在模型、persona、主 Skill 或工具集变化后，至少重跑 E1、E3、E5、E6、E8、E10、E11、E12。记录通过率、所需轮次、工具调用、上下文体积和人工纠偏次数。

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

@@ -15,7 +15,7 @@ description: 按策划案、TDD 测试用例、HTML 效果展示、千星美术
 | 2. TDD 制定测试用例 | 从策划规则写状态、不变量、`boot` / 成功 / 失败 / 重开等操作与预期；先写用例，Lua 骨架就绪后才执行有效 Red。 |
 | 3. HTML 效果展示 | 提供可打开试玩的网页，向用户确认画面、操作和节奏；网页不是 Lua 源码或千星证据。 |
 | 4. 准备千星美术参考图和素材 | 根据确认的 HTML 效果准备参考图、官方 `imageId` / 图元清单与 UI 还原方案。 |
-| 5. Lua 编码实现 | 核对工作区 2D API，搭建控件与脚本挂载；用模拟器对步骤 2 的用例执行 Red→Green→Regress。 |
+| 5. Lua 编码实现 | 核对知识库插件或工作区提供的 2D API，搭建控件与脚本挂载；用模拟器对步骤 2 的用例执行 Red→Green→Regress。 |
 | 6. 测试 | 自动化用例、模拟器交互与截图、移动端和 PC 布局、边界与性能回归；修复发现的缺陷。 |
 | 7. 真机试玩验证与 bug 修复 | 导出资产，请用户在千星奇域试玩；记录真机实际结果、复现并修复，再做模拟器与真机回归。 |
 
@@ -27,16 +27,20 @@ description: 按策划案、TDD 测试用例、HTML 效果展示、千星美术
 |---|---|
 | 玩家体验假设 | HTML 展示与用户反馈；步骤 6 的模拟器试玩；步骤 7 的真机回传。 |
 | 确定性规则 | 先写用例，再执行 Red→Green→Regress；不要用日志断言证明“好玩”。 |
-| 平台未知 | 当前工作区的官方文档、最小探针、真机记录；缺证据标 `unknown`。 |
+| 平台未知 | 知识库插件或当前工作区提供的官方 2D/Lua 文档、最小探针、真机记录；缺证据标 `unknown`。 |
 | 工程操作 | 操作模拟器前加载 `qxqy-simulator`；以当前会话可见工具 schema 为准。 |
 | 美术制作 | 查看工作区是否有像素画、图元拟合、UI 制作或帧动画 Skill；按需使用。 |
 
 模拟器提供 `qxqy_studio_play`、`qxqy_studio_ui_screenshot`、`qxqy_studio_play_screenshot` 等能力；步骤 5 才开始调用。没有 `qxqy_studio_*` 时仍可完成步骤 1–4，但不能声称游戏通过模拟器或真机。不要用网页截图或搜索结果冒充试玩。
 
-写 Lua 前查当前工作区的 2D API 文档与 `AGENTS.md`。没有文档时请用户补齐，不从普通 Lua/UI 或 3D 节点经验猜接口。官方素材可以用；模拟器只预览 `100001–100006` 六种基础图元，其余 `imageId` 显示缺失框，须在真机核验。千星画布原点左下、Y 向上；HTML 通常左上、Y 向下，不直接搬 CSS 坐标。
+建议用户提前安装 [dsh-plugin-miliastra-toolbox 插件](https://github.com/1475505/dsh-plugin-miliastra-toolbox)，或在本地工作区提供千星奇域 Lua 编程相关知识库和实战经验，以优化模型对千星奇域 Lua 的理解。写 Lua 前检查插件实际可用的 2D/Lua API 文档或本地资料，并遵守工作区 `AGENTS.md`；已有资料可用时直接复用。两种来源都缺少所需 API 文档时请用户补齐，不从普通 Lua/UI 或 3D 节点经验猜接口。
+
+官方素材可以用；模拟器只预览 `100001–100006` 六种基础图元，其余 `imageId` 显示缺失框，须在真机核验。千星画布原点左下、Y 向上；HTML 通常左上、Y 向下，不直接搬 CSS 坐标。
 
 存档为 `workspace/<slug>/<slug>.save.json`，文件头附近有 `"format": "qxqy-simulator-save"`。资产包含服务端 UI 容器、客户端 UI 模板与 Lua 脚本；脚本只挂客户端控件/模板，GIA 不保存挂载关系。布局以手机 16:9 完整可见为基准，PC 等比放大或留边。
 
+真实编辑器重映射客户端控件索引时，按 `qxqy-simulator` 的索引校准流程处理：修改控件索引后，必须检查 `controlGuidChanges`，同步存档脚本与对应 `.lua` 文件中的相关语义引用，核验后才确认记录、保存并重启试玩。不能仅修改控件索引或盲替换同值数字；连续变更按控件身份追到最终索引。
+
 ## 工作中的决策
 
 只在玩法语义、HTML 体验、真正不同的美术方向与真机结果需要用户判断时提问。实现细节、文件路径、测试断言、控件拆分自行处理，不反复问“是否继续”。发现设计问题回步骤 1–3；素材问题回步骤 4；代码或测试缺陷回步骤 2、5–6；真机差异记录于步骤 7 并回归。

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

@@ -17,7 +17,7 @@ PREFLIGHT（检查已有工程，不计入步骤）
 
 ## PREFLIGHT — 接入与基线
 
-先盘点用户想法、参考图、已有 Lua、GIA、存档和反馈。检查当前工作区 `AGENTS.md`、2D API 文档、可用工具与相关 Skill。已有项目先读策划案、测试、最近试玩记录、存档与源码；只创建当前步骤需要的文件。在 `docs/production-plan.md` 记当前步骤、目标、退出证据、阻塞项。缺官方 API 文档时可以推进步骤 1–4，但写依赖编辑器 API 的 Lua 前须请用户补齐。
+先盘点用户想法、参考图、已有 Lua、GIA、存档和反馈。检查当前工作区 `AGENTS.md`、知识库插件或本地提供的 2D/Lua API 文档与经验、可用工具和相关 Skill。知识资料尚未准备时，建议提前安装 [dsh-plugin-miliastra-toolbox](https://github.com/1475505/dsh-plugin-miliastra-toolbox)，或补充本地 Lua 编程知识库和实战经验；已有资料可用时直接复用。已有项目先读策划案、测试、最近试玩记录、存档与源码；只创建当前步骤需要的文件。在 `docs/production-plan.md` 记当前步骤、目标、退出证据、阻塞项。缺官方 API 文档时可以推进步骤 1–4，但写依赖编辑器 API 的 Lua 前须请用户补齐。
 
 ## 1. 策划案
 
@@ -45,10 +45,12 @@ PREFLIGHT（检查已有工程，不计入步骤）
 
 ## 5. Lua 编码实现
 
-从此步开始使用模拟器。核对工作区官方 2D API，建立服务端 UI、客户端控件/模板和 Lua 脚本的最小骨架，保存为 `workspace/<slug>/<slug>.save.json`。先运行步骤 2 的用例，确认目标生产行为缺失导致有效 Red；随后一次实现一条规则，执行目标 Green 与相关 Regress。将纯规则与 UI 副作用分离，计时显式使用 `dt`，随机行为可复现。
+从此步开始使用模拟器。核对知识库插件或工作区提供的官方 2D API，建立服务端 UI、客户端控件/模板和 Lua 脚本的最小骨架，保存为 `workspace/<slug>/<slug>.save.json`。先运行步骤 2 的用例，确认目标生产行为缺失导致有效 Red；随后一次实现一条规则，执行目标 Green 与相关 Regress。将纯规则与 UI 副作用分离，计时显式使用 `dt`，随机行为可复现。
 
 根据策划案重新实现玩法，不逐行翻译 HTML DOM/CSS/JavaScript。接入步骤 4 的目标素材；模拟器缺失框要记录真实目标 ID。交付物是可加载的 Lua 与存档，按需导出 GIA；记录脚本挂载点。未知 API 先查文档或做单问题探针，不猜字段。
 
+建议打开文本框的字号自适应（`adaptiveFontSize = true`），并按可读性设置最小字号，以适应不同文本长度和显示空间。`fontSize` 与 `minimumFontSize` 仍须使用整数；开启自适应不能代替整数校验。需要固定字号时可按设计关闭，但应检查手机、PC 和真机上的文字是否完整可读。
+
 ## 6. 测试
 
 运行 P0 与高风险边界用例，复现并修复实现缺陷。使用 `qxqy_studio_play` 走开局、首次成功、失败、重开，用 `qxqy_studio_ui_screenshot` 和 `qxqy_studio_play_screenshot` 检查静态/运行画面。手机 16:9 整屏可见，PC 等比放大/留边；必要时扩展五画布、触控、重复输入、暂停恢复、服务端信号与性能预算。
@@ -59,6 +61,8 @@ PREFLIGHT（检查已有工程，不计入步骤）
 
 整理 Lua、完整存档/GIA、挂载说明、目标素材 ID、测试结果和已知限制，提供真机操作步骤。请用户在千星奇域实际试玩并回传画面、日志、步骤和期望/实际结果。Agent 不在真机上执行过的步骤必须标未验证。
 
+若 GIA 导入后客户端控件索引变化，复用已回传的真实索引，按 `qxqy-simulator` 的 `setControlGuid` / `controlGuidChanges` 流程同步模拟器和 Lua。检查内联源码、路径源码、常量/表/别名和身份校验；仅在相关引用全部处理或明确无引用后确认记录，保存并重新启动试玩回归。未读到的源码或未判定的引用保留待处理，不把模板索引与运行时 `Id` 混用。
+
 对每个真机缺陷建立最小复现，判断是 Lua、素材、布局、模拟器差异还是平台未知；先更新用例或人工检查，再修复并重复模拟器与真机验证。只有真机证据覆盖目标行为，才能标记该行为通过；尚未回传则交付状态为“模拟器候选”。
 
 ## 产物与跨会话恢复

package/dsh-plugin/skill.md

@@ -16,7 +16,7 @@
 |---|---|
 | 真机导出的 `.gia` 文件 | 引导用户在"模拟器"标签顶栏点"导入"选择该文件；导入后调 `qxqy_studio_get` 读取转换出的 Authoring JSON 树 |
 | 口头描述 / 截图 | 用 `qxqy_studio_patch` 从零构建：`newAsset` 重置工程 → `add` 逐个加控件 → `set` 改字段（每步后 `get` 验证） |
-| 已有 Authoring JSON / 完整存档包 | 工作区里的 `qxqy-simulator-save` 用 `qxqy_studio_load` 拉取；也可让用户在顶栏选「工作区存档」，或「导入」本地文件 |
+| 已有 Authoring JSON / 完整存档包 | 工作区里的 `qxqy-simulator-save` 用 `qxqy_studio_load` 拉取到当前会话；也可让用户在顶栏选「工作区存档」，或「导入」本地文件。`qxqy_studio_load` 不会刷新独立 Web 预览页 |
 | 只有 Lua 脚本 | 引导用户"导入" `.lua`，只更新当前脚本，不影响其他资产 |
 
 ### 2. 构建与校验
@@ -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 会直接报错，以报错为准。
 
@@ -164,3 +192,4 @@ play 动作：`start`（重建运行时；可带 `canvasId` 指定设备画布
 | revision conflict | 重新 `get` 后重算编辑 |
 | `play session has not started` | 先 `start` 再发其他动作 |
 | 路径脚本不生效 | 路径相对工作区；先用内联 source 排除路径问题 |
+| Web 预览停在「等待工作区存档」 | 该页不在本插件进程里。`qxqy_studio_load` 只载入当前会话；MCP 编辑后用 `qxqy_project_save` 保存，省略路径会沿用最近打开/保存路径。MCP 0.3.0 起可用 `qxqy_preview_status` 核对 Web 版本、工作区和当前文件，再用 `qxqy_preview_open({path})` 显式打开已保存文件。Web 已看 A 时保存 B 不会自动切换；没有这些工具时可用顶部存档列表选择。详见 `mcp/README.md` 和 `web/README.md` |

package/package.json

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