千星沙箱模拟器

面向千星奇域 2D + Lua 脚本驱动的游戏开发的独立模拟器：在游戏之外执行客户端 Lua 脚本、显示 UI、响应操作，并让 AI 直接试玩游戏。

提供 Web 编辑器、MCP 服务和 DeepSeek Harness 插件三种接入方式，共用同一套模拟器核心。可以独立在浏览器中使用，也可以通过 MCP 接入 OpenCode、WorkBuddy、Codex 等 AI 工具，配合 Web 查看和试玩。

你可以在浏览器中编辑界面、调试脚本，也可以让 AI 读取工程、修改控件、点击按钮、发送按键、查看截图与日志，完成“编写 → 试玩 → 检查 → 修改”的开发循环。日常调试无需反复打开游戏和官方编辑器，完成后再导出资产进行真机验证。

包含什么

能力	你可以做什么
可视化 UI 编辑器	查看控件树，调整位置、尺寸、锚点和属性；创建 11 类客户端控件，其中图片、文本框和预设按钮提供较完整的编辑能力。
Lua 脚本模拟运行	管理多个脚本并挂载到客户端控件或模板，检查脚本生命周期、UI 操作、输入响应和动画效果。
独立试玩窗口	启动、暂停、继续和单步运行，通过鼠标、触摸或按键测试交互，查看运行状态、日志和错误。
多设备与多玩家模拟	在 5 种 PC / 手机画布上检查布局；在本地模拟 1–8 名玩家，切换视角检查变量与信号交互。
AI 试玩与自动测试	通过工具直接编辑工程、驱动操作、获取截图；记录操作时间线，回放用例并检查控件、变量和日志。
七步游戏制作工作流	从策划案与测试用例出发，展示 HTML 效果、准备千星美术素材，再完成 Lua 编码、测试与真机反馈修复。
存档与资产交换	用完整 JSON 存档保存工程，导入导出 UI、Lua 脚本及已支持的 GIA 内容，衔接后续编辑与交付。

11 类控件的实际运行能力和缺口见 客户端控件支持矩阵。文本视窗、网格视窗现支持基础滚轮/拖拽/触摸与滚动条；编辑、字段存取与完整仿真程度分别说明。

集成方式

按你的开发环境选择接入方式。Web 可以独立使用；让 AI 直接编辑和测试工程时使用 MCP；需要边对话边看画面时组合 MCP + Web：

方式	适合谁	使用体验
Web 编辑器	在浏览器中编辑、调试，或配合外部 AI 工具查看结果	独立运行 UI/Lua 编辑器与试玩窗口，预览磁盘中的工程存档。
MCP 服务	使用 OpenCode、WorkBuddy、Codex 等支持本地 MCP stdio 的 AI 工具	向 AI 提供工程编辑、试玩、截图和保存工具，可独立使用或配合 Web。
DeepSeek Harness 插件	使用 DeepSeek Harness	在 Harness 内嵌编辑器、注册模拟器工具，并提供 Skill 与 Agent 预设。

三个包已发布到 npm，也可从 GitHub 源码或本地构建的 .tgz 安装。Web 包名和启动命令均为 beyond-simulator-web。本地安装包路径以仓库根目录为基准；当前版本及文件名见 release/manifest.json。

Web 部署

准备 Node.js 22+，从 npm 安装后即可启动完整前后端：

npm install -g beyond-simulator-web
mkdir ../my-game
beyond-simulator-web --workspace ../my-game --open

也可以从源码启动。准备 pnpm 10.15.0，在本仓库根目录执行：

pnpm install --frozen-lockfile
mkdir ../my-game
pnpm dev:web --workspace ../my-game

这里的 my-game 是保存游戏文件的工作区。已有项目时，跳过创建目录，将参数换成现有目录，例如 --workspace E:/my-game。

启动后打开：

• 编辑器：编辑 UI、Lua 和服务端逻辑，保存存档并试玩。
• 存档预览：查看工作区中已保存的存档，文件更新后自动刷新，适合配合 AI 或外部编辑器使用。

Web 也支持安装预构建包运行，仓库提供了 Docker 部署配置。对外部署时需配置访问口令和 HTTPS；当前面向单个可信操作者，不提供网站用户之间的项目权限隔离。安装包、Docker 和部署参数见 Web 使用与部署指南。

MCP 接入

在 OpenCode、WorkBuddy、Codex 等支持本地 MCP stdio 服务的 AI 工具中配置模拟器，指定游戏工作区后，AI 即可打开、编辑和保存工程，控制试玩并获取画面。各客户端的配置入口和格式不同，共用以下服务命令与参数：

从 npm 安装：

npm install -g beyond-simulator-mcp

然后在客户端中添加本地 stdio 服务：

配置项	值
服务名（自定）	qxqy-simulator
命令	beyond-simulator-mcp
参数	--workspace、已有游戏目录的绝对路径，例如 E:/my-game

客户端配置可参考 OpenCode MCP 文档、WorkBuddy MCP 连接器文档及本仓库的 Codex 配置示例。接入后先检查 qxqy_project_open、qxqy_studio_play 等工具是否可见；安装 MCP 包不会自动安装游戏制作 Skill。

MCP 可以独立使用。组合 Web 时，让两者的 --workspace 指向同一个本地目录：AI 用 MCP 修改工程并显式保存 JSON，Web 的“存档预览”重新加载当前文件，用户在浏览器中查看和试玩。切换到另一份存档时可调用 qxqy_preview_open。Web 编辑器中的未保存草稿不会被自动覆盖。

只使用 Web 时，AI 也可以在工作区编辑 Lua 和工程文件，由用户在 Web 中加载检查；能否直接操作网页取决于 AI 客户端实际提供的浏览器工具。Web 服务本身不注册 MCP 工具。

安装方式、客户端配置和工具示例见 MCP 接入指南。

DeepSeek Harness 插件

准备 Node.js 22+ 和 DeepSeek Harness，选择下面一种安装方式。GitHub 安装还需要 Git，会自动从源码构建；本地安装包路径以仓库根目录为基准，可按文末的构建说明生成，文件名以 release/manifest.json 为准。

插件 2.0.7 起将 Harness 0.2 系列（含 0.2.0-rc.1 起的候选版本）纳入安装范围，保留 0.1 系列支持；已验收 0.2.0-rc.2。版本检查、预设资源路径及验证范围见 Harness 0.2 兼容说明。

# 从 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-2.0.8.tgz

dsh --profile web --dump-config
dsh web

为会话绑定游戏项目工作区，打开“模拟器”视图，即可编辑 UI 和 Lua 并启动试玩。插件同时提供模拟器操作 Skill，以及“千星 2D+Lua 游戏制作”Agent 预设；新建会话时可以选择该预设。

更新已有插件时，执行同一条安装命令，再重启 Harness。已有的用户 Agent 预设会保留，不会随插件升级自动覆盖。

安装配置与工具说明见 Harness 插件指南。

GitHub 安装使用仓库默认分支，安装时由 prepare 自动构建。首次安装若 pnpm 提示需要批准构建，请按提示允许该插件的构建脚本，再重新执行安装命令。安装入口是整个仓库，不需要指定子目录。详见 分发说明。

用 Agent 七步制作游戏

仓库提供可供 AI 按需读取的七步制作 Skill。提供游戏想法、参考图或已有工程后，AI 按当前步骤读取对应 Markdown，逐步完成制作。

在 OpenCode、WorkBuddy、Codex 等工具中，可让 AI 读取该 Skill 和随附的 references/，并通过 MCP 操作模拟器；在 Harness 中，可直接选择插件附带的“千星 2D+Lua 游戏制作”Agent 预设。工作流内容和 Harness 注册配置分开维护，接入方法见 Agent / Skill 使用说明。

启动制作时，AI 先检查工作区和当前 AI 工具配置中的 miliastra-toolbox 系列、其他知识库服务或本地资料，确认能否读取所需的官方 2D/Lua API 文档与使用指南。已有资料直接复用，只在缺项时提示补充；具体规则见启动前知识库检查。模拟器安装包不捆绑官方知识库。

步骤	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. 准备工程

一个存档集中管理三类资产：服务端 UI、客户端 UI 模板和 Lua 脚本。它们共同组成试玩所需的界面与逻辑。

• 从零开始：在编辑器中添加控件、创建客户端模板，再编写 Lua 脚本。
• 继续已有工程：从顶栏“工作区存档”选择已保存的项目，或点击“导入”打开本地文件。
• 迁入现有资产：导入支持的 UI JSON、GIA 或 Lua，再检查布局和脚本挂载关系。

编写 Lua 时，AI 使用启动前已经核验的知识来源，按当前需求读取官方 API、指南和实战经验；“已配置知识库”还需核实当前会话能否读取所需资料。需要从参考图制作美术时，也可以配合工作区已有的像素画、图元拟合、UI 制作或帧动画 Skill。

2. 编辑并试玩

1. 在“UI 编辑”页添加控件，调整属性，并切换 PC / 手机画布检查适配。
2. 在“Lua 脚本”页创建或导入脚本，将入口脚本挂载到客户端控件或客户端模板；模板脚本在模板实例化时运行。
3. 如果玩法需要服务端响应，在“服务端逻辑”页配置监听信号、设置变量和向玩家发送信号。
4. 点击“试玩 ↗”，在独立窗口中操作游戏；Desktop 等宿主拒绝新窗口时自动进入应用内全屏试玩。遇到问题时暂停、单步推进，并查看“日志”页中的脚本输出与运行状态。内嵌时通过“返回编辑”“关闭试玩”或 Escape 停止并返回。
5. 返回编辑器修改，再次试玩；需要检查多人交互时，调整试玩人数并切换玩家视角。

3. 让 AI 帮你测试

通过 Harness 插件或 MCP 接入后，可以直接描述要检查的行为，例如：

打开我的游戏存档，在手机 16:9 画布上试玩。点击开始按钮，检查得分是否变化，截取操作后的画面，并告诉我日志里有没有报错。

也可以把操作整理成可重复执行的测试：

把“开始游戏 → 点击目标 → 得分增加”记录成测试用例。修改脚本后重新回放，检查得分和界面状态是否符合预期。

AI 可以直接获取工程状态、发送输入、读取日志和截图，无需你手动切换到试玩窗口。涉及玩法规则时，请提供预期结果，例如“每次点击加 1 分”“玩家 1 的操作不应改变玩家 2 的分数”。

4. 保存与导出

继续开发时，优先保存完整存档；需要与外部编辑链路交换资产时，再选择相应导出格式。

目的	推荐方式
保存进度、备份或交给 AI 继续修改	导出“资产包 JSON（三类合一）”，保留 UI、脚本和挂载关系。
保存到 Web 服务的工作区	点击“保存存档”，填写工作区内的相对路径，例如 my-game.save.json。
与官方编辑器交换已支持的资产	导出对应的 GIA，并检查导出提示及导入后的实际效果。
单独交换 UI 或脚本	导出当前界面 Authoring JSON、脚本包或单个 Lua 脚本。

编辑和试玩不会自动把完整存档写入磁盘。Web 用户请显式保存，Harness 用户可导出 JSON，MCP 用户可让 AI 调用保存工具；关闭服务前先保存未完成的工作。

5. 导入真机并持续更新

首次交付时，AI 会根据工程给出需要导入的文件、脚本映射与挂载位置，以及试玩步骤。你需要在千星沙箱完成导入，核对实际控件/模板索引；索引变化可通过对话告知 AI，或在模拟器中修改后让 AI 同步脚本。直接手改脚本时也应将最终修改同步回工程。

后续更新可以在 Web/DSH 的“Lua 脚本 → 实机脚本同步”绑定该关卡导入后的脚本目录。AI 准备修改并预览差异，你检查目标路径、选择文件并确认复制，然后在千星沙箱保存并重新试玩。目录绑定随完整存档保存，便于下次复用；新增脚本仍需建立映射和必要挂载。

如果模拟器服务无法访问游戏所在电脑的目录，可按交付说明手动更新。完整分工见 真机交付与验证，目录配置与复制说明见 实机脚本同步。

当前支持边界

• 模拟器通过不等于真机通过。 它用于提前发现脚本、布局和交互问题，最终仍需在千星奇域中验证。
• 服务端模拟覆盖变量与信号。 1–8 人试玩是本地多客户端模拟，不包含完整官方服务端节点图或真实网络联机。
• 图片预览以基础图元为主。 当前用代理图形显示图片 ID 100001–100006，其他素材显示缺失提示；安装包不包含完整官方图片和动效资源。
• GIA 支持已验证的内容子集。 部分控件属性与脚本挂载关系无法完整交换，导出时请关注提示，并保留原始文件及完整 JSON 存档。

从源码构建

开发环境为 Node.js 22+、pnpm 10.15.0。首次安装依赖后，可以在仓库根目录构建和测试：

pnpm install --frozen-lockfile
pnpm build
pnpm test

生成可交付的 Web、Harness 和 MCP 安装包：

pnpm pack:release
pnpm test:packages

安装包生成在 release/，本次产物的名称、版本与校验值见 release/manifest.json。包中已包含模拟器核心及所需界面资源，使用者无需构建源码；安装时仍会下载第三方运行依赖。

测试套件完全自包含，只依赖仓库内源码与合成数据，独立检出即可运行。模块分工见 开发入口，构建、验收与发布设计见 分发说明。

自动发布通过 npm-* Git tag 触发；需要先在 npm 为三个包绑定同一份 GitHub Actions Trusted Publisher。配置项和版本规则见 自动发布说明。

开源协议

本项目采用 GNU GPL v3.0（GPL-3.0-only）。源码仓库：1475505/miliastra-beyond-simulator。