dsh-plugin-beyond-simulator 2.0.4 → 2.0.5

package/README.md

@@ -1,32 +1,10 @@
 # 千星沙箱模拟器
 
-面向千星奇域 **2D + Lua 脚本驱动的游戏开发**，提供一套在游戏之外运行的模拟工具：执行客户端 Lua 脚本、显示 UI、响应操作，并让 AI 直接试玩游戏。
+面向千星奇域 **2D + Lua 脚本驱动的游戏开发**的独立模拟器：在游戏之外执行客户端 Lua 脚本、显示 UI、响应操作，并让 AI 直接试玩游戏。
 
-你可以在浏览器中编辑界面、调试脚本，也可以让 AI 读取工程、修改控件、点击按钮、发送按键、查看截图与日志，完成“编写 → 试玩 → 检查 → 修改”的开发循环。日常调试无需反复打开游戏和官方编辑器，完成后再导出资产进行真机验证。
-
-## 用 Agent 七步制作游戏
-
-Harness 插件附带“千星 2D+Lua 游戏制作”Agent 预设。新建会话时选择它，提供游戏想法、参考图或已有工程，按下面七步与 Agent 协作完成游戏。
+提供 **Web 编辑器、MCP 服务和 DeepSeek Harness 插件**三种接入方式，共用同一套模拟器核心。可以独立在浏览器中使用，也可以通过 MCP 接入 OpenCode、WorkBuddy、Codex 等 AI 工具，配合 Web 查看和试玩。
 
-建议提前安装 [dsh-plugin-miliastra-toolbox 插件](https://github.com/1475505/dsh-plugin-miliastra-toolbox)，或在本地工作区提供千星奇域 Lua 编程相关知识库和实战经验，以优化模型对千星奇域 Lua 的理解。
-
-| 步骤 | Agent 会做什么 | 你会得到什么 |
-|---|---|---|
-| **1. 策划案** | 明确核心玩法、操作方式、计分与胜负规则，以及首版功能范围。 | 指导后续制作的游戏策划案。 |
-| **2. TDD 制定测试用例** | 制定测试用例，测试驱动开发；先写清开局、成功、失败、重开及边界情况的操作与预期结果。 | 与策划规则对应、用于驱动实现的测试用例。 |
-| **3. HTML 效果展示** | 制作可以打开试玩的 HTML 演示，与你确认画面、操作和节奏。 | 在正式编码前可以体验和调整的效果展示。 |
-| **4. 准备千星美术参考图和素材** | 根据确认的效果整理或制作参考图，核对可用的千星图片资源与图元，规划素材的使用方式。 | 美术参考图、素材清单和 UI 还原方案。 |
-| **5. Lua 编码实现** | 按策划案和测试用例编写 Lua，搭建 UI、接入素材，在模拟器中逐项实现功能并验证。 | 可以在模拟器运行的 Lua 游戏与完整存档。 |
-| **6. 测试** | 执行测试用例，让 AI 实际操作游戏，检查画面、日志、交互和设备适配，修复问题并回归。 | 测试结果、问题记录与通过模拟器验证的游戏版本。 |
-| **7. 真机试玩验证与 bug 修复** | 导出资产供你在千星奇域中试玩，根据真机回传复现并修复 bug，再验证修复结果。 | 经真机验证的游戏资产、修复记录及尚待处理的问题说明。 |
-
-先用策划案和测试用例明确目标，再用 HTML 展示确认体验，随后准备千星美术参考图和素材，进入 Lua 编码与测试。最终交付的是 Lua、完整存档和可导出的游戏资产；真机试玩发现的问题继续进入修复与回归。
-
-可以这样开始：
-
-> 我想做一个适合手机操作的 2D 小游戏：点击躲避障碍，连续成功会加分。请先写策划案并制定 TDD 测试用例，再做 HTML 效果展示。确认后准备千星美术参考图和素材，完成 Lua 编码与测试，最后配合我真机试玩并修复 bug。
-
-已有工程可以从需要补齐的环节继续；玩法变化时同步更新策划案与测试用例，修复 bug 后重新执行相关测试。
+你可以在浏览器中编辑界面、调试脚本，也可以让 AI 读取工程、修改控件、点击按钮、发送按键、查看截图与日志，完成“编写 → 试玩 → 检查 → 修改”的开发循环。日常调试无需反复打开游戏和官方编辑器，完成后再导出资产进行真机验证。
 
 ## 包含什么
 
@@ -37,45 +15,21 @@ Harness 插件附带“千星 2D+Lua 游戏制作”Agent 预设。新建会话
 | **独立试玩窗口** | 启动、暂停、继续和单步运行，通过鼠标、触摸或按键测试交互，查看运行状态、日志和错误。 |
 | **多设备与多玩家模拟** | 在 5 种 PC / 手机画布上检查布局；在本地模拟 1–8 名玩家，切换视角检查变量与信号交互。 |
 | **AI 试玩与自动测试** | 通过工具直接编辑工程、驱动操作、获取截图；记录操作时间线，回放用例并检查控件、变量和日志。 |
-| **游戏制作 Agent** | 从策划案与测试用例出发，展示 HTML 效果、准备千星美术素材，再完成 Lua 编码、测试与真机反馈修复。 |
+| **七步游戏制作工作流** | 从策划案与测试用例出发，展示 HTML 效果、准备千星美术素材，再完成 Lua 编码、测试与真机反馈修复。 |
 | **存档与资产交换** | 用完整 JSON 存档保存工程，导入导出 UI、Lua 脚本及已支持的 GIA 内容，衔接后续编辑与交付。 |
 
 ## 集成方式
 
-按你的开发环境选择一种接入方式，也可以组合使用：
+按你的开发环境选择接入方式。Web 可以独立使用；让 AI 直接编辑和测试工程时使用 MCP；需要边对话边看画面时组合 MCP + Web：
 
 | 方式 | 适合谁 | 使用体验 |
 |---|---|---|
-| **DeepSeek Harness 插件** | 希望在 AI 对话中完成游戏开发的人 | 在 Harness 内打开编辑器，让 Agent 操作同一份工程并试玩。 |
-| **Web 部署** | 希望直接在浏览器中编辑、调试的人 | 启动一个包含前后端的服务，通过浏览器编辑和试玩，无需 Harness。 |
-| **MCP 接入** | 使用其他支持 MCP 的 AI 客户端的人 | 向 AI 提供工程编辑、试玩、截图和保存工具，可配合 Web 查看结果。 |
+| **[Web 编辑器](#web-部署)** | 在浏览器中编辑、调试，或配合外部 AI 工具查看结果 | 独立运行 UI/Lua 编辑器与试玩窗口，预览磁盘中的工程存档。 |
+| **[MCP 服务](#mcp-接入)** | 使用 OpenCode、WorkBuddy、Codex 等支持本地 MCP stdio 的 AI 工具 | 向 AI 提供工程编辑、试玩、截图和保存工具，可独立使用或配合 Web。 |
+| **[DeepSeek Harness 插件](#deepseek-harness-插件)** | 使用 DeepSeek Harness | 在 Harness 内嵌编辑器、注册模拟器工具，并提供 Skill 与 Agent 预设。 |
 
 三个包已发布到 npm，也可从 GitHub 源码或本地构建的 `.tgz` 安装。Web 包名和启动命令均为 `beyond-simulator-web`。本地安装包路径以仓库根目录为基准；当前版本及文件名见 `release/manifest.json`。
 
-### DeepSeek Harness 插件
-
-准备 Node.js 22+ 和 DeepSeek Harness，选择下面一种安装方式。GitHub 安装还需要 Git，会自动从源码构建；本地安装包路径以仓库根目录为基准，可按文末的[构建说明](#从源码构建)生成，文件名以 `release/manifest.json` 为准。
-
-```sh
-# 从 npm 安装
-dsh plugin --profile web add dsh-plugin-beyond-simulator
-# 或，从 GitHub 默认分支源码安装
-dsh plugin --profile web add github:1475505/miliastra-beyond-simulator
-# 或，从本地安装包安装
-dsh plugin --profile web add ./release/dsh-plugin-beyond-simulator-1.0.10.tgz
-
-dsh --profile web --dump-config
-dsh web
-```
-
-为会话绑定游戏项目工作区，打开“模拟器”视图，即可编辑 UI 和 Lua 并启动试玩。插件同时提供模拟器操作 Skill，以及“千星 2D+Lua 游戏制作”Agent 预设；新建会话时可以选择该预设。
-
-更新已有插件时，执行同一条安装命令，再重启 Harness。已有的用户 Agent 预设会保留，不会随插件升级自动覆盖。
-
-安装配置与工具说明见 [Harness 插件指南](dsh-plugin/README.md)。
-
-GitHub 安装使用仓库默认分支，安装时由 `prepare` 自动构建。首次安装若 pnpm 提示需要批准构建，请按提示允许该插件的构建脚本，再重新执行安装命令。安装入口是整个仓库，不需要指定子目录。详见 [分发说明](DISTRIBUTION.md#harness-安装入口)。
-
 ### Web 部署
 
 准备 **Node.js 22+**，从 npm 安装后即可启动完整前后端：
@@ -105,7 +59,7 @@ Web 也支持安装预构建包运行，仓库提供了 Docker 部署配置。
 
 ### MCP 接入
 
-在支持本地 MCP stdio 服务的 AI 客户端中配置模拟器，指定游戏工作区后，AI 即可打开、编辑和保存工程，控制试玩并获取画面。
+在 OpenCode、WorkBuddy、Codex 等支持本地 MCP stdio 服务的 AI 工具中配置模拟器，指定游戏工作区后，AI 即可打开、编辑和保存工程，控制试玩并获取画面。各客户端的配置入口和格式不同，共用以下服务命令与参数：
 
 从 npm 安装：
 
@@ -113,12 +67,72 @@ Web 也支持安装预构建包运行，仓库提供了 Docker 部署配置。
 npm install -g beyond-simulator-mcp
 ```
 
-然后在客户端中将服务命令设为 `beyond-simulator-mcp`，参数设为 `--workspace` 和已有游戏目录的绝对路径。
+然后在客户端中添加本地 stdio 服务：
+
+| 配置项 | 值 |
+|---|---|
+| 服务名（自定） | `qxqy-simulator` |
+| 命令 | `beyond-simulator-mcp` |
+| 参数 | `--workspace`、已有游戏目录的绝对路径，例如 `E:/my-game` |
+
+客户端配置可参考 [OpenCode MCP 文档](https://opencode.ai/docs/mcp-servers/)、[WorkBuddy MCP 连接器文档](https://open.workbuddy.cn/docs/connector)及本仓库的 [Codex 配置示例](mcp/README.md#codex-接入)。接入后先检查 `qxqy_project_open`、`qxqy_studio_play` 等工具是否可见；安装 MCP 包不会自动安装游戏制作 Skill。
+
+MCP 可以独立使用。组合 Web 时，让两者的 `--workspace` 指向同一个本地目录：AI 用 MCP 修改工程并显式保存 JSON，Web 的“存档预览”重新加载当前文件，用户在浏览器中查看和试玩。切换到另一份存档时可调用 `qxqy_preview_open`。Web 编辑器中的未保存草稿不会被自动覆盖。
 
-MCP 可以独立使用。需要同时看画面时，让 Web 指向同一个工作区，打开“存档预览”；AI 保存 JSON 后，预览会自动更新。Web 编辑器中的未保存草稿不会被自动覆盖。
+只使用 Web 时，AI 也可以在工作区编辑 Lua 和工程文件，由用户在 Web 中加载检查；能否直接操作网页取决于 AI 客户端实际提供的浏览器工具。Web 服务本身不注册 MCP 工具。
 
 安装方式、客户端配置和工具示例见 [MCP 接入指南](mcp/README.md)。
 
+### DeepSeek Harness 插件
+
+准备 Node.js 22+ 和 DeepSeek Harness，选择下面一种安装方式。GitHub 安装还需要 Git，会自动从源码构建；本地安装包路径以仓库根目录为基准，可按文末的[构建说明](#从源码构建)生成，文件名以 `release/manifest.json` 为准。
+
+```sh
+# 从 npm 安装
+dsh plugin --profile web add dsh-plugin-beyond-simulator
+# 或，从 GitHub 默认分支源码安装
+dsh plugin --profile web add github:1475505/miliastra-beyond-simulator
+# 或，从本地安装包安装
+dsh plugin --profile web add ./release/dsh-plugin-beyond-simulator-1.0.10.tgz
+
+dsh --profile web --dump-config
+dsh web
+```
+
+为会话绑定游戏项目工作区，打开“模拟器”视图，即可编辑 UI 和 Lua 并启动试玩。插件同时提供模拟器操作 Skill，以及“千星 2D+Lua 游戏制作”Agent 预设；新建会话时可以选择该预设。
+
+更新已有插件时，执行同一条安装命令，再重启 Harness。已有的用户 Agent 预设会保留，不会随插件升级自动覆盖。
+
+安装配置与工具说明见 [Harness 插件指南](dsh-plugin/README.md)。
+
+GitHub 安装使用仓库默认分支，安装时由 `prepare` 自动构建。首次安装若 pnpm 提示需要批准构建，请按提示允许该插件的构建脚本，再重新执行安装命令。安装入口是整个仓库，不需要指定子目录。详见 [分发说明](DISTRIBUTION.md#harness-安装入口)。
+
+## 用 Agent 七步制作游戏
+
+仓库提供可供 AI 按需读取的[七步制作 Skill](agent/wonderland-lua-builder/skills/qxqy-game-studio/SKILL.md)。提供游戏想法、参考图或已有工程后，AI 按当前步骤读取对应 Markdown，逐步完成制作。
+
+在 OpenCode、WorkBuddy、Codex 等工具中，可让 AI 读取该 Skill 和随附的 `references/`，并通过 MCP 操作模拟器；在 Harness 中，可直接选择插件附带的“千星 2D+Lua 游戏制作”Agent 预设。工作流内容和 Harness 注册配置分开维护，接入方法见 [Agent / Skill 使用说明](agent/wonderland-lua-builder/README.md)。
+
+启动制作时，AI 先检查工作区和当前 AI 工具配置中的 `miliastra-toolbox` 系列、其他知识库服务或本地资料，确认能否读取所需的官方 2D/Lua API 文档与使用指南。已有资料直接复用，只在缺项时提示补充；具体规则见[启动前知识库检查](agent/wonderland-lua-builder/skills/qxqy-game-studio/references/workflow.md#知识库发现与可用性核验)。模拟器安装包不捆绑官方知识库。
+
+| 步骤 | Agent 会做什么 | 你会得到什么 |
+|---|---|---|
+| **1. 策划案** | 明确核心玩法、操作方式、计分与胜负规则，以及首版功能范围。 | 指导后续制作的游戏策划案。 |
+| **2. TDD 制定测试用例** | 制定测试用例，测试驱动开发；先写清开局、成功、失败、重开及边界情况的操作与预期结果。 | 与策划规则对应、用于驱动实现的测试用例。 |
+| **3. HTML 效果展示** | 制作可以打开试玩的 HTML 演示，与你确认画面、操作和节奏。 | 在正式编码前可以体验和调整的效果展示。 |
+| **4. 准备千星美术参考图和素材** | 根据确认的效果整理或制作参考图，核对可用的千星图片资源与图元，规划素材的使用方式。 | 美术参考图、素材清单和 UI 还原方案。 |
+| **5. Lua 编码实现** | 按策划案和测试用例编写 Lua，搭建 UI、接入素材，在模拟器中逐项实现功能并验证。 | 可以在模拟器运行的 Lua 游戏与完整存档。 |
+| **6. 测试** | 执行测试用例，让 AI 实际操作游戏，检查画面、日志、交互和设备适配，修复问题并回归。 | 测试结果、问题记录与通过模拟器验证的游戏版本。 |
+| **7. 真机试玩验证与 bug 修复** | 交接导入与脚本挂载，协助校准真实索引、绑定脚本更新目录，再根据真机回传修复和回归。 | 游戏资产、导入与后续更新说明、真机结果及待处理项。 |
+
+先用策划案和测试用例明确目标，再用 HTML 展示确认体验，随后准备千星美术参考图和素材，进入 Lua 编码与测试。最终交付的是 Lua、完整存档和可导出的游戏资产；真机试玩发现的问题继续进入修复与回归。
+
+可以这样开始：
+
+> 我想做一个适合手机操作的 2D 小游戏：点击躲避障碍，连续成功会加分。请先写策划案并制定 TDD 测试用例，再做 HTML 效果展示。确认后准备千星美术参考图和素材，完成 Lua 编码与测试，最后配合我真机试玩并修复 bug。
+
+已有工程可以从需要补齐的环节继续；玩法变化时同步更新策划案与测试用例，修复 bug 后重新执行相关测试。
+
 ## 使用指南
 
 ### 1. 准备工程
@@ -129,7 +143,7 @@ MCP 可以独立使用。需要同时看画面时，让 Web 指向同一个工
 - 继续已有工程：从顶栏“工作区存档”选择已保存的项目，或点击“导入”打开本地文件。
 - 迁入现有资产：导入支持的 UI JSON、GIA 或 Lua，再检查布局和脚本挂载关系。
 
-编写 Lua 时，请让 AI 参考知识库插件实际提供的千星 2D/Lua 资料，或工作区中的 API 文档与实战经验；模拟器安装包不包含官方知识库。需要从参考图制作美术时，也可以配合工作区已有的像素画、图元拟合、UI 制作或帧动画 Skill。
+编写 Lua 时，AI 使用启动前已经核验的知识来源，按当前需求读取官方 API、指南和实战经验；“已配置知识库”还需核实当前会话能否读取所需资料。需要从参考图制作美术时，也可以配合工作区已有的像素画、图元拟合、UI 制作或帧动画 Skill。
 
 ### 2. 编辑并试玩
 
@@ -164,6 +178,14 @@ AI 可以直接获取工程状态、发送输入、读取日志和截图，无
 
 编辑和试玩不会自动把完整存档写入磁盘。Web 用户请显式保存，Harness 用户可导出 JSON，MCP 用户可让 AI 调用保存工具；关闭服务前先保存未完成的工作。
 
+### 5. 导入真机并持续更新
+
+首次交付时，AI 会根据工程给出需要导入的文件、脚本映射与挂载位置，以及试玩步骤。你需要在千星沙箱完成导入，核对实际控件/模板索引；索引变化可通过对话告知 AI，或在模拟器中修改后让 AI 同步脚本。直接手改脚本时也应将最终修改同步回工程。
+
+后续更新可以在 Web/DSH 的“Lua 脚本 → 实机脚本同步”绑定该关卡导入后的脚本目录。AI 准备修改并预览差异，你检查目标路径、选择文件并确认复制，然后在千星沙箱保存并重新试玩。目录绑定随完整存档保存，便于下次复用；新增脚本仍需建立映射和必要挂载。
+
+如果模拟器服务无法访问游戏所在电脑的目录，可按交付说明手动更新。完整分工见 [真机交付与验证](agent/wonderland-lua-builder/skills/qxqy-game-studio/references/07-device-validation.md)，目录配置与复制说明见 [实机脚本同步](studio/docs/script-sync.md)。
+
 ## 当前支持边界
 
 - **模拟器通过不等于真机通过。** 它用于提前发现脚本、布局和交互问题，最终仍需在千星奇域中验证。

package/dsh-plugin/cordis.patch.yml

@@ -21,7 +21,8 @@
           # composition keeps the registries, sandbox, approval stack, persistence, and
           # the model route. Simulator Tools come from `dsh-plugin-beyond-simulator`.
           # 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.
+          # 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.
@@ -34,7 +35,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. 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.
+                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.
 
@@ -46,6 +47,8 @@
 
                 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
@@ -126,7 +129,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 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.
+                        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/README.md

@@ -1,23 +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 等工具中使用
 
-建议用户提前安装 [dsh-plugin-miliastra-toolbox 插件](https://github.com/1475505/dsh-plugin-miliastra-toolbox)，或在本地工作区提供千星奇域 Lua 编程相关知识库和实战经验，以优化模型对千星奇域 Lua 的理解。写 Lua 之前，Agent 会检查插件实际可用的 2D/Lua 资料或本地 API 文档，并遵守工作区 `AGENTS.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 预设。
 
-模拟器只预览 `100001–100006` 六种基础图元，其他官方图片 ID 在模拟器中显示缺失框，需在真机确认。行为评估见 [agent-behavior.md](evals/agent-behavior.md)。
+例如，在本仓库可读时：
+
+> 请读取 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

@@ -6,7 +6,8 @@
 # composition keeps the registries, sandbox, approval stack, persistence, and
 # the model route. Simulator Tools come from `dsh-plugin-beyond-simulator`.
 # 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.
+# 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. 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.
+      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.
 
@@ -31,6 +32,8 @@
 
       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
@@ -111,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 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.
+              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：在知识库插件实际提供的 2D/Lua 资料或工作区知识库 / `AGENTS.md` 指向的文档中查 API；缺少资料时建议安装 `dsh-plugin-miliastra-toolbox` 或提供本地 Lua 知识库和实战经验，补齐所需 API 文档后再写依赖 API 的代码；已有资料可用时不重复要求安装；仍未知则建立单问题探针并标 `unknown`；不让探针代码直接进入生产路径。
+Must：在知识库插件实际提供的 2D/Lua 资料或工作区知识库 / `AGENTS.md` 指向的文档中查 API；先查工作区和当前 AI 宿主已配置的知识来源并核验实际可用性，仅在仍缺本轮资料时请用户补齐，取得所需 API 文档后再写依赖 API 的代码；已有资料可用时不重复要求安装；仍未知则建立单问题探针并标 `unknown`；不让探针代码直接进入生产路径。
 
 Must-not：编造枚举、GIA 字段或宣称真机支持。
 
@@ -138,6 +138,34 @@ Must：读取 `controlGuidChanges` 并结合资产/控件身份解析最终索
 
 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 或人工接口绕过本次复制确认；把目录绑定说成实时双向同步；承诺新增脚本无需映射或挂载。
+
+补充变体：用户直接手改实机脚本时，先核对并合并有效修改回工作区与存档；服务运行在无法访问游戏目录的远程机器时，提供手动更新方案，不伪造绑定成功。
+
 ## 汇总指标
 
 | 指标 | 目标 |
@@ -152,4 +180,4 @@ Must-not：只改控件索引或只改外部文件后宣称完成；按数字全
 | 新游戏没有明确当前阶段/退出证据 | 0 |
 | 不必要的重复用户确认 | 越少越好，但不得越过必要的产品决定 |
 
-在模型、persona、主 Skill 或工具集变化后，至少重跑 E1、E3、E5、E6、E8、E10、E11、E12。记录通过率、所需轮次、工具调用、上下文体积和人工纠偏次数。
+在模型、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,44 +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；不要用日志断言证明“好玩”。 |
-| 平台未知 | 知识库插件或当前工作区提供的官方 2D/Lua 文档、最小探针、真机记录；缺证据标 `unknown`。 |
-| 工程操作 | 操作模拟器前加载 `qxqy-simulator`；以当前会话可见工具 schema 为准。 |
-| 美术制作 | 查看工作区是否有像素画、图元拟合、UI 制作或帧动画 Skill；按需使用。 |
-
-模拟器提供 `qxqy_studio_play`、`qxqy_studio_ui_screenshot`、`qxqy_studio_play_screenshot` 等能力；步骤 5 才开始调用。没有 `qxqy_studio_*` 时仍可完成步骤 1–4，但不能声称游戏通过模拟器或真机。不要用网页截图或搜索结果冒充试玩。
-
-建议用户提前安装 [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 坐标。
+| [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)：准备交付或处理真机回传 | 导入/挂载与索引校准、脚本目录绑定和更新交接、真机结果及未验证项。 |
 
-存档为 `workspace/<slug>/<slug>.save.json`，文件头附近有 `"format": "qxqy-simulator-save"`。资产包含服务端 UI 容器、客户端 UI 模板与 Lua 脚本；脚本只挂客户端控件/模板，GIA 不保存挂载关系。布局以手机 16:9 完整可见为基准，PC 等比放大或留边。
+## 贯穿各步骤的约束
 
-真实编辑器重映射客户端控件索引时，按 `qxqy-simulator` 的索引校准流程处理：修改控件索引后，必须检查 `controlGuidChanges`，同步存档脚本与对应 `.lua` 文件中的相关语义引用，核验后才确认记录、保存并重启试玩。不能仅修改控件索引或盲替换同值数字；连续变更按控件身份追到最终索引。
+- 步骤 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)。后续发现规则变化时先更新本步骤的契约，再更新受影响的用例。