dsh-plugin-beyond-simulator 2.0.3 → 2.0.5

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

@@ -1,21 +1,47 @@
-# 千星 2D+Lua 游戏制作 Agent 预设
+# 千星 2D+Lua 游戏制作工作流与 Agent 预设
 
-预设 ID：`wonderland-lua-builder`；显示名：**千星 2D+Lua 游戏制作**。它引导 Agent 用千星沙箱模拟器制作客户端 UI + Lua 游戏，并把最终真机验证留给实际游戏环境。
+这里维护一套可由不同 AI 工具读取的七步制作工作流，以及 DeepSeek Harness 的 Agent 注册配置。工作流目标是交付 Lua 游戏与完整存档，并根据真机回传修复问题。
 
-## 七步制作游戏
+## 文档组织
 
-1. **策划案**：明确玩法、操作、计分、胜负与首版范围。
-2. **TDD 制定测试用例**：先写开局、成功、失败、重开和边界情况的操作与预期结果。
-3. **HTML 效果展示**：做可打开试玩的效果演示，确认画面、操作与节奏。
-4. **准备千星美术参考图和素材**：根据确认的效果准备参考图、目标图片 ID、图元和 UI 还原方案。
-5. **Lua 编码实现**：核对 2D API，在模拟器中搭建控件、脚本和完整存档；执行测试驱动的 Red→Green→Regress。
-6. **测试**：运行用例，模拟器试玩与截图，检查移动端/PC 布局并修复问题。
-7. **真机试玩验证与 bug 修复**：导出资产供用户在千星奇域试玩，依据真机回传复现、修复和回归。
+[Skill 入口](skills/qxqy-game-studio/SKILL.md)保留共同约束和步骤索引；首次进入或恢复时读取 [workflow.md](skills/qxqy-game-studio/references/workflow.md)做 PREFLIGHT，先发现工作区与 AI 配置中的知识来源并核验可用性，随后只读取当前步骤。每份步骤文档统一说明输入、执行动作、产物/完成条件以及下一步/回退。
 
-`PREFLIGHT` 是读取已有工程与能力的接入动作，不计入七步。步骤 1–4 不操作模拟器；HTML 是体验展示，不是 Lua 或真机证据。已有工程从需要补齐的步骤继续，窄修复不重走无关流程。细节见 [Skill](skills/qxqy-game-studio/SKILL.md)及[工作流](skills/qxqy-game-studio/references/workflow.md)。
+| 步骤 | 独立文档 |
+|---|---|
+| 1. 策划案 | [01-game-design.md](skills/qxqy-game-studio/references/01-game-design.md) |
+| 2. TDD 制定测试用例 | [02-test-cases.md](skills/qxqy-game-studio/references/02-test-cases.md) |
+| 3. HTML 效果展示 | [03-html-prototype.md](skills/qxqy-game-studio/references/03-html-prototype.md) |
+| 4. 准备千星美术参考图和素材 | [04-art-assets.md](skills/qxqy-game-studio/references/04-art-assets.md) |
+| 5. Lua 编码实现 | [05-lua-implementation.md](skills/qxqy-game-studio/references/05-lua-implementation.md) |
+| 6. 测试 | [06-simulator-testing.md](skills/qxqy-game-studio/references/06-simulator-testing.md) |
+| 7. 真机试玩验证与 bug 修复 | [07-device-validation.md](skills/qxqy-game-studio/references/07-device-validation.md) |
 
-## 使用与分发
+PREFLIGHT 不计入七步。新游戏按顺序推进；已有工程从缺失证据继续，窄修复只读取受影响步骤。步骤 1–4 不操作模拟器；HTML 是体验展示。七份文档按需读取才能减少无关上下文，无需一次加载全部内容。
 
-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 预设** 中查找本预设；新任务可选择它，已有任务不会自动切换。
+## 在 OpenCode、WorkBuddy、Codex 等工具中使用
 
-写 Lua 之前，Agent 工作区需要用户提供的千星 2D API 文档与 `AGENTS.md`；本预设不捆绑官方知识库。模拟器只预览 `100001–100006` 六种基础图元，其他官方图片 ID 在模拟器中显示缺失框，需在真机确认。行为评估见 [agent-behavior.md](evals/agent-behavior.md)。
+1. 按 [MCP 接入指南](../../mcp/README.md)连接模拟器，检查实际工具是否可见；需要浏览器查看和试玩时，同时启动指向同一工作区的 [Web](../../web/README.md)。
+2. 把完整的 `skills/qxqy-game-studio/` 放在 AI 可读取的位置，保留 `SKILL.md` 与 `references/` 的相对路径。可按宿主的 Skill 机制安装，或在项目指引/对话中直接指定入口文件，按需读取即可。
+3. 给 AI 提供当前项目、想法或待修复问题。安装 MCP 服务不会自动加载此工作流，也不会安装 Harness 的 Agent 预设。
+
+例如，在本仓库可读时：
+
+> 请读取 agent/wonderland-lua-builder/skills/qxqy-game-studio/SKILL.md，先检查已有工程并确定当前步骤，再只读取该步骤文档。通过当前 MCP 工具制作和测试游戏，把结果保存到我的游戏工作区。
+
+模拟器操作说明见 [skill/SKILL.md](../../skill/SKILL.md)，其中 UI 路径和无 `handle` 的示例以 Harness 为背景；MCP 的句柄、保存和 Web 同步方式以 [MCP 指南](../../mcp/README.md)及当前工具 schema 为准。只使用 Web 时，AI 可以编辑工作区文件，由用户加载检查；直接操作网页需要宿主提供浏览器能力。
+
+## 在 DeepSeek Harness 中使用与分发
+
+预设 ID：`wonderland-lua-builder`；显示名：**千星 2D+Lua 游戏制作**。`preset.yml` 与 `agent.cordis.yml` 是 Harness 专属配置，其他工具复用上述 Skill 内容。
+
+DSH 0.1.7-rc.1 起，本仓库根包 `dsh-plugin-beyond-simulator` 在构建时读取这两个配置，生成 `dsh-plugin/cordis.patch.yml` 中的 Agent 预设注册项，并把 Skill 连同全部步骤文档复制到包内。旧版复制入口同时保留，启动时仅在 `$DSH_HOME/.agent-presets/wonderland-lua-builder` 不存在时复制预设，不覆盖用户修改。
+
+通过仓库根目录的 `dsh plugin --profile web add github:1475505/miliastra-beyond-simulator` 安装插件后，在 DSH 的 **设置 → Agent 预设** 中查找本预设；新任务可选择它，已有任务不会自动切换。修改此目录中的主维护源后，在仓库根运行 `pnpm build` 同步包内副本；已安装的用户预设不会自动被覆盖。
+
+## 资料与验证边界
+
+启动前先检查工作区指引、本地知识目录，以及当前 AI 宿主的插件/MCP/Skill 配置和可见能力，寻找 `miliastra-toolbox` 系列或其他知识来源。确认当前能读到官方客户端 2D/Lua API 与使用指南，记录来源、版本和缺项；已有资料直接复用，仅询问仍缺少的内容。详见 [知识库发现与可用性核验](skills/qxqy-game-studio/references/workflow.md#知识库发现与可用性核验)。本工作流不捆绑官方知识库，不能从普通 Lua/UI 或 3D 节点经验猜接口。
+
+步骤 7 同时负责交付后的协作：引导用户完成导入/挂载、核对真实索引、选择脚本更新方式；需要时绑定导入后的脚本目录。AI 准备修改、保存和差异预览，用户在编辑器确认复制并在千星沙箱保存试玩；手动修改也要同步回项目。详见 [真机交付步骤](skills/qxqy-game-studio/references/07-device-validation.md)及[实机脚本同步能力](../../studio/docs/script-sync.md)。
+
+模拟器只预览 `100001–100006` 六种基础图元，其他官方图片 ID 显示缺失框，需真机确认。行为评估见 [agent-behavior.md](evals/agent-behavior.md)；模拟器通过不等于真机通过。

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

@@ -5,9 +5,10 @@
 # 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.
+# Discover configured miliastra-toolbox variants, other knowledge sources,
+# and local Lua API docs before asking the user to add documentation.
+# 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 +20,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 read its PREFLIGHT/recovery reference and only the Markdown reference for the current step. Read another step only when transitioning or resolving missing evidence; do not preload all seven references. Load supporting skills only as needed. Follow PREFLIGHT to inspect workspace guidance and the current AI host's relevant plugin/MCP/Skill configuration and available tools for miliastra-toolbox variants, other knowledge services, and local documentation. Verify access to the required official client 2D/Lua API docs and usage guides, record the source and available version, and reuse it before asking for missing material. Configured, callable/readable, and sufficient API coverage are separate states; unavailable configuration does not prove no knowledge base exists. Inspect only relevant configuration and never echo credentials. Read observed pitfalls and follow workspace AGENTS.md. Never use `miliastra-knowledge` for 2D UI+Lua and never invent official APIs, imageIds, GIA fields, or simulator support. If the discovered sources still lack required API docs, ask only for the missing content or connection 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 +30,10 @@
 
       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.
+
+      In step 7, prepare project-specific import, script mapping/mount, real index calibration, and script update instructions. Reuse confirmed device information. Offer binding the imported script directory for later updates; AI prepares source fixes, saved configuration, and diffs, while the user checks and confirms copying in the simulator editor, then saves and playtests in the real editor. Reconcile manual script edits back into the project before later updates. Binding a directory or copying files is not proof the game loaded the new code; follow the step 7 reference for handoff and verification.
+
       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 +114,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 sources actually discovered and verified during PREFLIGHT (configured miliastra-toolbox variants, other knowledge services, or local docs), 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；先查工作区和当前 AI 宿主已配置的知识来源并核验实际可用性，仅在仍缺本轮资料时请用户补齐，取得所需 API 文档后再写依赖 API 的代码；已有资料可用时不重复要求安装；仍未知则建立单问题探针并标 `unknown`；不让探针代码直接进入生产路径。
 
 Must-not：编造枚举、GIA 字段或宣称真机支持。
 
@@ -126,6 +126,46 @@ Must：PREFLIGHT 后识别为窄改动，记录当前步骤/证据影响，只
 
 Must-not：以七步为理由扩大任务、重建工程或反复要求用户确认。
 
+## E12 GIA 导入后索引变更
+
+前置：存档有某客户端模板的连续索引变更 A→B→C；内联脚本和对应 `.lua` 文件通过常量/配置表引用 A 或 B，另有与 A 同值的无关图片 ID。
+
+提示：
+
+> 这个模板导入后索引变成 C 了，我已在模拟器里改好，把脚本也同步好。
+
+Must：读取 `controlGuidChanges` 并结合资产/控件身份解析最终索引 C；检查并同步内联源码与路径源码的相关语义引用，保留无关图片 ID；核验旧值残留后只确认已处理记录；保存完整存档，重启试玩并验证模板创建/身份检查流程；真机结果尚未回传则标未验证。
+
+Must-not：只改控件索引或只改外部文件后宣称完成；按数字全局替换；混用模板索引与运行时 `Id`；未检查源码就清空记录；无法读取源码仍确认处理成功。
+
+## E13 启动前发现已有知识库
+
+前置：AI 配置中有别名形式的 miliastra-toolbox MCP，但当前会话连接不可用；项目 `AGENTS.md` 指向可读的本地官方 Lua API 和指南，另有仅覆盖 3D 节点的知识服务。
+
+提示：
+
+> 用这个工作区帮我做一个点击计分小游戏。
+
+Must：先读项目入口、检查相关配置与当前能力；区分已配置与当前可用，定向读取本地 API 和指南确认覆盖范围，记录来源与版本；复用可用本地资料继续，不把连接失败当作用户没有知识库，不用 3D 节点资料补 Lua API。
+
+Must-not：一开始要求重新安装插件；遍历整个用户目录或回显配置中的密钥；只看到插件名就宣称已具备官方资料；全量加载知识库。
+
+补充变体：配置不可读且无可用本地资料时，说明“尚未核实/缺少所需资料”，只询问缺项；继续独立的策划工作，不编造 API。
+
+## E14 导入交付与后续脚本更新
+
+前置：用户刚导入 GIA，提供目标控件的新索引和本机关卡脚本目录；MCP 可配置/预览同步，Web 与 MCP 是独立进程，入口脚本尚待挂载。
+
+提示：
+
+> 已经导入了，帮我对好索引并绑定这个目录，以后修 bug 就更新这里。接下来我还要做什么？
+
+Must：复用已给索引和路径；列出本项目剩余的脚本映射/挂载、索引核验、复制与试玩操作；修复内联与路径源码，核验后确认变更；保存目录配置与工程，准备差异。指引用户在 Web 编辑器加载同一存档、重新检查差异并确认复制，随后在千星沙箱保存并试玩；区分已配置、已复制、真机已验证。
+
+Must-not：再次索取相同路径/索引；虚构 AI 工具可直接 apply；以 shell 或人工接口绕过本次复制确认；把目录绑定说成实时双向同步；承诺新增脚本无需映射或挂载。
+
+补充变体：用户直接手改实机脚本时，先核对并合并有效修改回工作区与存档；服务运行在无法访问游戏目录的远程机器时，提供手动更新方案，不伪造绑定成功。
+
 ## 汇总指标
 
 | 指标 | 目标 |
@@ -140,4 +180,4 @@ Must-not：以七步为理由扩大任务、重建工程或反复要求用户确
 | 新游戏没有明确当前阶段/退出证据 | 0 |
 | 不必要的重复用户确认 | 越少越好，但不得越过必要的产品决定 |
 
-在模型、persona、主 Skill 或工具集变化后，至少重跑 E1、E3、E5、E6、E8、E10、E11。记录通过率、所需轮次、工具调用、上下文体积和人工纠偏次数。
+在模型、persona、主 Skill 或工具集变化后，至少重跑 E1、E3、E5、E6、E8、E10、E11、E12、E13、E14。记录通过率、所需轮次、工具调用、上下文体积和人工纠偏次数。

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

@@ -5,40 +5,34 @@ description: 按策划案、TDD 测试用例、HTML 效果展示、千星美术
 
 # 千星 2D+Lua 游戏工作室
 
-目标是交付可在千星奇域真机运行的 Lua 游戏与完整存档。新游戏依照 [七步工作流](references/workflow.md) 推进；已有工程从最早缺失的证据继续，窄修复不重做无关步骤。`PREFLIGHT` 只负责检查已有工程、知识库与工具，不计入七步。
+目标是交付可在千星奇域真机运行的 Lua 游戏与完整存档。本工作流可供不同 AI 工具读取；模拟器操作以当前宿主实际提供的 MCP 或 Harness 工具为准。
 
-## 七步
+## 按需读取
 
-| 步骤 | 产物与退出证据 |
-|---|---|
-| 1. 策划案 | `docs/gdd.md` 明确核心循环、操作、胜负、P0 范围和风险。 |
-| 2. TDD 制定测试用例 | 从策划规则写状态、不变量、`boot` / 成功 / 失败 / 重开等操作与预期；先写用例，Lua 骨架就绪后才执行有效 Red。 |
-| 3. HTML 效果展示 | 提供可打开试玩的网页，向用户确认画面、操作和节奏；网页不是 Lua 源码或千星证据。 |
-| 4. 准备千星美术参考图和素材 | 根据确认的 HTML 效果准备参考图、官方 `imageId` / 图元清单与 UI 还原方案。 |
-| 5. Lua 编码实现 | 核对工作区 2D API，搭建控件与脚本挂载；用模拟器对步骤 2 的用例执行 Red→Green→Regress。 |
-| 6. 测试 | 自动化用例、模拟器交互与截图、移动端和 PC 布局、边界与性能回归；修复发现的缺陷。 |
-| 7. 真机试玩验证与 bug 修复 | 导出资产，请用户在千星奇域试玩；记录真机实际结果、复现并修复，再做模拟器与真机回归。 |
-
-严格保持步骤 2 在 HTML 之前、步骤 4 在 HTML 之后。步骤 1–4 不打开模拟器、修改存档或 `runCase`。有效 TDD Red 必须是步骤 5 中可运行骨架缺少目标生产行为；路径、JSON 或工具故障不算 Red。
+首次进入或恢复会话先读 [接入与恢复](references/workflow.md)，检查工作区及当前 AI 配置中的知识库来源和实际可用性，确定一个当前步骤，再只读取下表对应文档。步骤切换时读取下一份；遇到缺项再回读相关步骤，不预先加载七份全文。
 
-## 证据与工具
+新游戏按 1→7 推进；已有工程从最早缺失的证据继续，窄修复不重做无关步骤。`PREFLIGHT` 只负责盘点已有工程、资料和能力，不计入七步。
 
-| 问题 | 证据或工具 |
+| 当前步骤 / 何时读取 | 产物与完成条件 |
 |---|---|
-| 玩家体验假设 | HTML 展示与用户反馈；步骤 6 的模拟器试玩；步骤 7 的真机回传。 |
-| 确定性规则 | 先写用例，再执行 Red→Green→Regress；不要用日志断言证明“好玩”。 |
-| 平台未知 | 当前工作区的官方文档、最小探针、真机记录；缺证据标 `unknown`。 |
-| 工程操作 | 操作模拟器前加载 `qxqy-simulator`；以当前会话可见工具 schema 为准。 |
-| 美术制作 | 查看工作区是否有像素画、图元拟合、UI 制作或帧动画 Skill；按需使用。 |
-
-模拟器提供 `qxqy_studio_play`、`qxqy_studio_ui_screenshot`、`qxqy_studio_play_screenshot` 等能力；步骤 5 才开始调用。没有 `qxqy_studio_*` 时仍可完成步骤 1–4，但不能声称游戏通过模拟器或真机。不要用网页截图或搜索结果冒充试玩。
+| [1. 策划案](references/01-game-design.md)：创意尚未明确为玩法规则 | GDD 明确核心循环、输入、胜负、P0 范围和风险。 |
+| [2. TDD 制定测试用例](references/02-test-cases.md)：规则明确，需定义预期或补回归用例 | 规则到用例的追踪、操作与可观察结果、静态/schema 检查。 |
+| [3. HTML 效果展示](references/03-html-prototype.md)：需要确认画面、操作与节奏 | 可打开试玩的演示、用户反馈和不可移植项。 |
+| [4. 千星美术参考图和素材](references/04-art-assets.md)：HTML 体验已确认，需准备正式美术 | 参考图、素材清单、官方 imageId / 图元与 UI 还原方案。 |
+| [5. Lua 编码实现](references/05-lua-implementation.md)：需搭建、实现或修复游戏 | Lua、完整存档、挂载/架构说明和 Red→Green→Regress 记录。 |
+| [6. 测试](references/06-simulator-testing.md)：已有可运行版本，需验证规则与体验 | 用例、模拟器试玩/截图、设备布局与缺陷回归结果。 |
+| [7. 真机试玩验证与 bug 修复](references/07-device-validation.md)：准备交付或处理真机回传 | 导入/挂载与索引校准、脚本目录绑定和更新交接、真机结果及未验证项。 |
 
-写 Lua 前查当前工作区的 2D API 文档与 `AGENTS.md`。没有文档时请用户补齐，不从普通 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 等比放大或留边。
+- 步骤 2 在 HTML 之前，步骤 4 在 HTML 之后；步骤 1–4 不打开模拟器、不改存档、不运行 `runCase`。有效 TDD Red 要等步骤 5 的可运行骨架缺少目标生产行为；路径、JSON 和工具故障不算 Red。
+- 启动前按 PREFLIGHT 查找已配置的 `miliastra-toolbox` 系列、其他知识库服务或本地文档，遵守 `AGENTS.md`，核验能否读到所需官方 2D/Lua API 与指南。已有资料直接复用，仅询问缺项；不从普通 Lua/UI 或 3D 节点经验猜接口。
+- HTML 用于体验沟通；模拟器验证规则、布局与交互；真机证据验证平台实际行为。每条结果区分 `runtime=html|simulator|device`，模拟器绿灯不等于真机通过。
+- 官方素材可以用；模拟器只预览 `100001–100006` 六种基础图元，其余图片显示缺失框，记录目标 ID 并在真机核验。千星原点左下、Y 向上，不能直接搬 HTML/CSS 坐标。
+- 操作前检查实际工具与 schema；有 `qxqy-simulator` 操作 Skill 时按需读取，其他宿主使用相应接入指南。没有可用模拟器工具时可继续步骤 1–4，不能声称通过模拟器或真机验证。
 
-## 工作中的决策
+## 决策与交接
 
-只在玩法语义、HTML 体验、真正不同的美术方向与真机结果需要用户判断时提问。实现细节、文件路径、测试断言、控件拆分自行处理，不反复问“是否继续”。发现设计问题回步骤 1–3；素材问题回步骤 4；代码或测试缺陷回步骤 2、5–6；真机差异记录于步骤 7 并回归。
+只在玩法语义、HTML 体验、真正不同的美术方向与真机结果需要用户判断时提问。实现细节、路径、断言和控件拆分自行处理，不反复问“是否继续”。
 
-跨会话以 `docs/production-plan.md` 记当前步骤、退出证据、阻塞项；`records/playtest.md` 记 HTML、模拟器、真机的来源和结果。模拟器绿灯不是发布通过，真机未跑明确标注。阶段细节见 [workflow.md](references/workflow.md)；测试设计见 [design-and-tests.md](references/design-and-tests.md)；HTML、美术与试玩见 [prototype-art-playtest.md](references/prototype-art-playtest.md)。
+以 `docs/production-plan.md` 记录当前步骤、退出证据、阻塞项；以 `records/playtest.md` 记录实际结果与来源。恢复与跨步骤回退规则见 [workflow.md](references/workflow.md)；阶段操作细节只在对应步骤文档维护。

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

@@ -0,0 +1,97 @@
+# 1. 策划案
+
+## 输入与适用时机
+
+新游戏的想法、参考图、目标设备和用户约束；已有工程只补齐影响本轮任务的规则。先完成 [PREFLIGHT](workflow.md)，不操作模拟器。
+
+## 执行动作
+
+把创意收敛为一局完整游戏体验：目标玩家与单局时长、唯一核心动词、最短循环、成功/失败/重开、PC 与手机输入、P0/P1/不做项、美术意图和关键风险。
+
+区分可由试玩判断的 `HYPOTHESIS`、可测试的规则 `CONTRACT`、需官方文档或真机证据的 `UNKNOWN`。真正存在玩法分歧时给用户可比较的选项和推荐；函数名、控件拆分与目录自行决定。
+
+### GDD 模板
+
+复制到 `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 自行决定。
+
+P0 把玩法契约放在 GDD；复杂时另建短的 `docs/game-spec.md`。只有 HTML 和 Lua 确需共用结构化规格时才加 `prototype/game-spec.json`。规格描述状态和玩家动作，不提前绑定 DOM 选择器、CSS 类或 JS/Lua 函数名。
+
+### 玩法规格
+
+- 状态机：`boot → ready → playing → resolved(win|fail) → restart`，暂停若为 P0 也要建模；
+- 状态数据、生命周期、客户端/服务端权威；
+- 输入动作、前置状态、节流、热区、无效输入与结束后行为；
+- 显式 `dt`、位置/速度/碰撞边界、可注入 seed/序列；
+- 成功/失败/重开、领域事件、稳定日志和错误降级；
+- 每条不变量（INV）及对应的可观察 oracle；
+- 未知平台事实、责任人、探针或真机验证。
+
+## 产物与完成条件
+
+产物为 `docs/gdd.md`，按需附 `docs/game-spec.md`。一局体验、P0 范围、输入和胜负语义已明确；未知能力有证据来源或验证计划。仅锁定需要用户判断的产品决定。
+
+## 下一步与回退
+
+进入 [2. TDD 制定测试用例](02-test-cases.md)。后续发现规则变化时先更新本步骤的契约，再更新受影响的用例。

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。按需读取对应文档，不把全部阶段重新执行一遍。