dsh-plugin-beyond-simulator 2.0.4 → 2.0.5

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

@@ -0,0 +1,52 @@
+# 2. TDD 制定测试用例
+
+## 输入与适用时机
+
+读取策划案中的 `CONTRACT`、状态机、不变量和目标画布。新游戏在 HTML 展示与生产 Lua 之前制定用例；已有缺陷只补充相关回归用例。
+
+## 执行动作
+
+建立 `requirement → rule/invariant → 模拟器场景 → case → oracle → evidence` 追踪表。每条用例明确前置条件、玩家动作、可观察结果、画布与失败边界。
+
+- 状态、胜负、计分、冷却、碰撞边界、暂停/重开、稳定输入语义、服务端变量/信号和已复现缺陷，进入 Red→Green→Regress。
+- 手感、反馈节奏、UI 层级和尚未稳定的语义先通过原型和观察试玩判断，形成稳定规则后再固化。
+- 未文档化 API、imageId、GIA 字段、生命周期和真机行为先查文档或探针，缺证据标 `UNKNOWN`。
+- `HYPOTHESIS` 关联体验检查；`CONTRACT` 关联可观察断言；`UNKNOWN` 关联资料、探针或真机验证。视觉、手感和真机项目另列人工检查。
+
+### 确定性与 oracle
+
+- 运动、冷却和计时显式消费 `dt`；随机玩法由配置、变量、首事件或测试入口注入可复现 seed/序列；
+- 每个用例独立启动，切画布是新生命周期；不依赖墙钟、机器速度或偶然帧；
+- 稳定日志使用 `game_start`、`score <n>`、`fail <reason>`、`restart` 等领域事件；
+- 优先断言玩家可见控件/状态，其次稳定事件，最后才是 `query.*` 诊断；测试不得复制生产算法；
+- 覆盖顺序按高风险、高频、最近缺陷和复杂状态转换，而非虚假的百分比。
+
+### 用例格式与 P0 覆盖
+
+使用模拟器支持的 `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 画布只做放大/留边，不裁掉手机上看得到的内容。缩放容器不要再加全屏不透明兄弟节点。
+
+## 产物与完成条件
+
+产物为追踪表与 `tests/*.json`。步骤 2 只做静态/schema 检查，不启动模拟器、不修改存档、不运行 `runCase`；此时只记录“用例已制定”。
+
+有效 Red 要等步骤 5 的骨架可运行后，由目标生产行为缺失产生。坏 JSON、路径错误、事件到不了控件、模拟器未启动或工具故障都不算 Red。已有完整行为的工程不为制造 Red 而删除生产代码。
+
+## 下一步与回退
+
+新游戏进入 [3. HTML 效果展示](03-html-prototype.md)，用例留给 [5. Lua 编码实现](05-lua-implementation.md)执行。规则不清回 [1. 策划案](01-game-design.md)；规则变化先改契约与用例。

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

@@ -0,0 +1,28 @@
+# 3. HTML 效果展示
+
+## 输入与适用时机
+
+读取策划案和步骤 2 已制定的用例。网页用于确认画面、操作与节奏；已有工程的窄修复可以跳过并记录理由。
+
+## 执行动作
+
+制作可打开试玩的 `prototype/`，覆盖开局、第一次成功、失败和重开：
+
+```text
+prototype/index.html
+prototype/README.md    启动、操作、不可移植项、坐标差异
+```
+
+请用户体验目标是否易懂、成功/失败反馈和节奏。只按实际使用的工具记录试玩来源；没有浏览器操作工具时标 `browser-run: user`，不能声称 Agent 已亲自试玩。记录为 `runtime=html`。
+
+将网页画面与动画分为 `must-reproduce`、`can-degrade`、`concept-only`，说明哪些效果需要在千星重新实现。网页新增或变更规则时回写策划案和用例。
+
+HTML 通常原点左上、Y 向下；千星原点左下、Y 向上。不可直接复制 DOM/CSS 坐标，也不逐行翻译 JavaScript 为 Lua。此步骤不操作模拟器。
+
+## 产物与完成条件
+
+产物为可打开的 HTML 演示、启动操作说明，以及 `records/playtest.md` 中的体验反馈和不可移植项。用户已确认核心画面、操作与节奏；网页可玩只证明 HTML 演示的结果。
+
+## 下一步与回退
+
+进入 [4. 准备千星美术参考图和素材](04-art-assets.md)。体验暴露规则问题时回 [1. 策划案](01-game-design.md)和 [2. 测试用例](02-test-cases.md)，再调整演示。

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

@@ -0,0 +1,35 @@
+# 4. 准备千星美术参考图和素材
+
+## 输入与适用时机
+
+读取已经确认的 HTML 效果、策划案中的美术意图和用户提供的参考。正式素材准备位于 HTML 体验确认之后，步骤 4 不打开模拟器或修改存档。
+
+## 执行动作
+
+在 `docs/art-bible.md` 记录体验形容词、主/辅/警示色、轮廓、UI 层级、角色/道具识别特征、素材来源与用途、目标官方 `imageId` 和模拟器占位。准备参考图、素材清单与千星控件还原方案。
+
+有真正视觉分歧时，在同一布局和玩法状态下提供少量可比较方向，请用户选择；没有分歧则采用推荐方向。按当前工作区和会话实际可用能力，使用像素画、图元拟合、UI 制作或帧动画 Skill。
+
+官方原神/千星素材可以使用。模拟器只预览 `100001–100006` 六种基础图元；其他官方图片显示缺失框，这是预览限制，记录真实目标 ID 并留待真机核验。高成本拼图或帧动画先准备关键样本，批量制作随步骤 5 的实现需要推进。
+
+### UI 还原规格
+
+布局字段使用千星坐标：原点左下、Y 向上，锚点取值 0–1；不写 DOM 选择器、CSS 类或 JS/Lua 函数名。
+
+| 字段 | 含义 |
+|---|---|
+| `id` / `kind` | 稳定控件名与 `container/image/text/button/progress` 等目标类型 |
+| `parent` / `anchor` / `offset` / `size` | 控件树与跨画布布局 |
+| `styleToken` / `assetId` | 色板、字号、间距与资产清单引用 |
+| `visibleWhen` / `action` | 可见状态与抽象玩家动作 |
+| `motionIntent` | 触发、时长、曲线和可降级方式 |
+
+HTML（若存在）与 Lua 可以有不同适配层；稳定的状态、动作、控件和资产 id 必须可追踪。网页坐标不得进入 Lua。
+
+## 产物与完成条件
+
+产物为 `docs/art-bible.md`、参考图、素材清单和 UI 还原规格。每项关键视觉元素已有目标素材/图元、使用位置与还原方式；未知 ID 和模拟器占位已明确标注。
+
+## 下一步与回退
+
+进入 [5. Lua 编码实现](05-lua-implementation.md)。还原方案改变体验时回 [3. HTML 效果展示](03-html-prototype.md)确认；仅涉及素材取舍时留在本步骤。

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

@@ -0,0 +1,50 @@
+# 5. Lua 编码实现
+
+## 输入与适用时机
+
+读取策划案、`tests/*.json`、美术清单与 UI 还原方案；已有工程同时读取存档、源码和最近结果。从本步骤开始操作模拟器。
+
+写依赖编辑器 API 的 Lua 前，复用 [PREFLIGHT 已核验的知识来源](workflow.md#知识库发现与可用性核验)，定向核对当前所需的官方 2D/Lua 文档，遵守 `AGENTS.md`。新增 API 的资料缺失时先检查已配置来源，仅请用户补齐仍缺少的内容；不从普通 Lua/UI 框架或 3D 节点图经验猜接口。未知语义先查文档或做单问题探针。
+
+## 执行动作
+
+### 接入模拟器与搭建骨架
+
+使用当前宿主的模拟器工具说明和实际 schema。有 `qxqy-simulator` 操作 Skill 时按需加载；MCP 不自动附带该 Skill，可读取仓库中的 MCP 指南和共享操作说明。
+
+- MCP 先用 `qxqy_project_open` 获取工程 `handle`，工程操作带该句柄；不要照搬 Harness 示例而遗漏参数。
+- 写操作使用最新 `expectedRevision`；修改后显式保存。内存修改和试玩不会自动写盘。
+- 三类资产为服务端 UI 容器、客户端 UI 模板、Lua 脚本。脚本仅挂客户端控件/模板；模板脚本随实例化运行。
+- 保存为 `workspace/<slug>/<slug>.save.json`，文件头附近含 `"format": "qxqy-simulator-save"`；记录脚本挂载点。按需导出 GIA，GIA 不保存脚本挂载关系。
+- 如果 `scripts[].source` 非空，试玩优先使用内联源码；否则读 `path`。修改外部 Lua 时同步实际使用的源码，避免存档仍运行旧版本。
+
+### Red→Green→Regress
+
+1. 建立可加载的最小控件和 Lua 骨架，先排除 JSON、路径、挂载、事件路由和工具故障。
+2. 运行步骤 2 的用例，确认目标生产行为缺失导致有效 Red。新游戏的 `first-success`、`first-fail`、`restart` 至少各有一次有效 Red。
+3. 一次实现一条规则，执行目标 Green 与相关 Regress；已有规则缺陷先补最小失败用例。纯文案等窄改动按风险检查，不人为破坏已有行为制造 Red。
+4. 记录证据：
+
+```text
+case / red reason / failedAt / frame
+minimal change / target result / full regression
+screenshot or snapshot / remaining risk
+```
+
+纯规则与 UI 副作用分离；计时显式使用 `dt`，随机 seed/序列可复现。根据策划契约实现玩法，不逐行翻译 HTML DOM/CSS/JavaScript。测试设计细节需要时读 [步骤 2](02-test-cases.md)。
+
+### 布局、素材与维护
+
+接入步骤 4 的素材；缺失框记录真实目标 ID。千星原点左下、Y 向上，布局使用父矩形、锚点和偏移，以手机 16:9 完整可见为基准，PC 等比放大/留边。缩放容器不要再加全屏不透明兄弟节点。
+
+建议文本框开启 `adaptiveFontSize = true`，按可读性设置最小字号；`fontSize` 与 `minimumFontSize` 仍须为整数。固定字号按设计使用，检查手机、PC 与真机文字是否完整可读。
+
+维护 `docs/tech-architecture.md`：Lua 文件、控件/容器、服务端变量/信号的职责，关键数据流和脚本挂载点。结构变化同步更新，供后续维护使用。
+
+## 产物与完成条件
+
+产物为可加载的 Lua、完整存档、挂载与架构说明，以及 Red→Green→Regress 记录。P0 已形成完整一局，已实现规则的目标用例通过；模拟器未知能力、素材占位与待验证项有记录。
+
+## 下一步与回退
+
+进入 [6. 测试](06-simulator-testing.md)。规则变化回 [步骤 1](01-game-design.md)和 [步骤 2](02-test-cases.md)，素材问题回 [步骤 4](04-art-assets.md)。GIA 导入造成索引变化时读 [步骤 7 的索引校准](07-device-validation.md#导入后的索引校准)。

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

@@ -0,0 +1,47 @@
+# 6. 测试
+
+## 输入与适用时机
+
+读取可运行存档、源码、P0 与高风险用例、最近缺陷和美术占位清单。工具接入与显式保存遵守 [步骤 5](05-lua-implementation.md)；按当前会话 schema 操作。
+
+## 执行动作
+
+运行 P0 与高风险边界用例。新增缺陷先留最小复现，再修复和回归。Agent 实际走开局、首次成功、失败和重开：
+
+| 目的 | 工具 |
+|---|---|
+| 点击、按键、时间与用例断言 | `qxqy_studio_play` |
+| 静态布局截图 | `qxqy_studio_ui_screenshot` |
+| 运行画面截图 | 先 `play start`，再 `qxqy_studio_play_screenshot` |
+
+### 五层证据
+
+| 层 | 验证 | 证据 |
+|---|---|---|
+| L0 | JSON、路径、挂载、控件树 | 静态检查、`qxqy_studio_get` |
+| L1 | 纯状态、计分、碰撞、生成、边界 | 纯函数/窄接口回放 |
+| L2 | 输入→状态/日志/控件/变量/信号 | `qxqy-autotest` + `runCase` |
+| L3 | 布局、层级、裁切、反馈、动画 | `qxqy_studio_ui_screenshot` / `qxqy_studio_play_screenshot` |
+| L4 | 易懂、公平、节奏、触控、真机 | 观察式试玩、用户反馈、真机 |
+
+HTML 展示用于提前沟通体验，不能替代本阶段的规则回归、画面检查与后续真机验证。模拟器看不见的官方图不算视觉回归失败，记目标 ID，真机看效果。
+
+### 布局与边界
+
+以 `mobile-16-9`（1280×720）整屏可见为基准，PC 使用同一设计板等比放大或留边。检查层级、裁切、反馈、文字与热区；不要把 HTML 截图或搜索结果当作模拟器试玩。
+
+按玩法扩展 `edge-contact`、`input-spam`、`pause-resume`、`restart-twice`、`large-dt`、触控、服务端变量/信号和其余四画布 smoke。每个用例独立启动，切画布会重建生命周期，不能串联状态。发布候选检查五画布、截图矩阵、控件/Lua/资源预算、资产清单和导出警告。
+
+### 观察试玩与反馈
+
+让用户在模拟器页观察或盲玩，检查目标是否易懂、失败是否公平、操作节奏是否合适。每轮验证少量问题、调整少量变量，随后回归已稳定规则。
+
+反馈分类为 `bug / design / art-content / platform / not-now`。缺失的官方图片保留 `targetId` 并进入真机检查；缺失框本身不能证明资源不可用。
+
+## 产物与完成条件
+
+保留用例结果、截图、日志、缺陷处理结果、已知限制和导出警告。在 `records/playtest.md` 标 `runtime=simulator`。P0 与相关边界已回归，未通过项明确列出；模拟器通过后只能称“模拟器候选”。
+
+## 下一步与回退
+
+进入 [7. 真机试玩验证与 bug 修复](07-device-validation.md)。设计问题回步骤 1–3；素材问题回步骤 4；规则/实现问题回步骤 2、5；平台未知建立探针或交给步骤 7。按需读取对应文档，不把全部阶段重新执行一遍。

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,70 +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/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. 策划案
-
-将创意写为 `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。
-
-模拟器对非 `100001–100006` 官方素材显示缺失框，这不等于素材不能在千星使用。记下目标 ID，留待真机核验。高成本拼图/动画可先准备方案和关键样本，批量制作随步骤 5 的实现需要推进。详见 [prototype-art-playtest.md](prototype-art-playtest.md)。
-
-## 5. Lua 编码实现
+1. 盘点用户想法、参考图、已有 Lua、GIA、存档和反馈，检查工作区 `AGENTS.md`。
+2. 按下方[知识库发现与可用性核验](#知识库发现与可用性核验)，先检查工作区和当前 AI 宿主已配置的资料来源，再判断缺项；不要一开始就要求安装插件或提供文档。
+3. 检查会话实际提供的模拟器、浏览器和美术能力；目录存在或安装成功不等于工具可见。MCP、Web 和 Harness 的接入形式不同，使用当前宿主说明与 schema。
+4. 已有工程先读策划案、production-plan、测试、最近试玩记录、存档与源码；找出本轮目标和最早缺失的证据，确定一个当前步骤。
+5. 在 `docs/production-plan.md` 记当前步骤、目标、退出证据、阻塞项。只创建当前任务需要的文件，不为空阶段建占位产物。
 
-从此步开始使用模拟器。核对知识库插件或工作区提供的官方 2D API，建立服务端 UI、客户端控件/模板和 Lua 脚本的最小骨架，保存为 `workspace/<slug>/<slug>.save.json`。先运行步骤 2 的用例，确认目标生产行为缺失导致有效 Red；随后一次实现一条规则，执行目标 Green 与相关 Regress。将纯规则与 UI 副作用分离，计时显式使用 `dt`，随机行为可复现。
+PREFLIGHT 不计入七步。新游戏按策划案 → TDD 用例 → HTML → 美术 → Lua → 测试 → 真机推进；已有工程和窄修复按证据选择步骤。
 
-根据策划案重新实现玩法，不逐行翻译 HTML DOM/CSS/JavaScript。接入步骤 4 的目标素材；模拟器缺失框要记录真实目标 ID。交付物是可加载的 Lua 与存档，按需导出 GIA；记录脚本挂载点。未知 API 先查文档或做单问题探针，不猜字段。
+## 知识库发现与可用性核验
 
-建议打开文本框的字号自适应（`adaptiveFontSize = true`），并按可读性设置最小字号，以适应不同文本长度和显示空间。`fontSize` 与 `minimumFontSize` 仍须使用整数；开启自适应不能代替整数校验。需要固定字号时可按设计关闭，但应检查手机、PC 和真机上的文字是否完整可读。
+启动制作前完成一次有范围的检查；恢复会话时复用已记录来源，工具、资料版本或任务涉及的 API 变化时再定向复核。
 
-## 6. 测试
+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 实现须等资料补齐。
 
-运行 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)。
+## 产物位置与恢复
 
-## 7. 真机试玩验证与 bug 修复
+`workspace/<slug>/` 是项目产物位置，下列路径相对该目录：
 
-整理 Lua、完整存档/GIA、挂载说明、目标素材 ID、测试结果和已知限制，提供真机操作步骤。请用户在千星奇域实际试玩并回传画面、日志、步骤和期望/实际结果。Agent 不在真机上执行过的步骤必须标未验证。
+| 产物 | 用途 |
+|---|---|
+| `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/` | 试玩/修复证据与交付资产 |
 
-若 GIA 导入后客户端控件索引变化，复用已回传的真实索引，按 `qxqy-simulator` 的 `setControlGuid` / `controlGuidChanges` 流程同步模拟器和 Lua。检查内联源码、路径源码、常量/表/别名和身份校验；仅在相关引用全部处理或明确无引用后确认记录，保存并重新启动试玩回归。未读到的源码或未判定的引用保留待处理，不把模板索引与运行时 `Id` 混用。
+试玩记录按 `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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-beyond-simulator",
-  "version": "2.0.4",
+  "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。体验反馈只有形成稳定规则后才转自动化测试。