dsh-plugin-beyond-simulator 2.2.0 → 2.2.2

package/README.md

@@ -1,40 +1,36 @@
 # 千星沙箱模拟器
 
-面向千星奇域 **2D + Lua 脚本驱动的游戏开发**的独立模拟器：在游戏之外执行客户端 Lua 脚本、显示 UI、响应操作，并让 AI 直接试玩游戏。
+简体中文 | [English](README.en.md) | [Quick Guide](https://ppt.070077.xyz/beyond-ai/index.html)
 
-提供 **Web 编辑器、MCP 服务和 DeepSeek Harness 插件**三种接入方式，共用同一套模拟器核心。可以独立在浏览器中使用，也可以通过 MCP 接入 OpenCode、WorkBuddy、Codex 等 AI 工具，配合 Web 查看和试玩。
+面向千星奇域 **2D + Lua 游戏开发**的独立模拟器。在浏览器中编辑 UI、运行脚本、试玩调试，也可以让 AI 直接操作、截图和测试，完成后导出资产到游戏中验证。
 
-你可以在浏览器中编辑界面、调试脚本，也可以让 AI 读取工程、修改控件、点击按钮、发送按键、查看截图与日志，完成“编写 → 试玩 → 检查 → 修改”的开发循环。日常调试无需反复打开游戏和官方编辑器，完成后再导出资产进行真机验证。
+提供 **Web 编辑器、MCP 服务和 DeepSeek Harness 插件**，支持 OpenCode、WorkBuddy、Codex 等 AI 工具。
 
 ## 包含什么
 
-| 能力 | 你可以做什么 |
+| 能力 | 说明 |
 |---|---|
-| **可视化 UI 编辑器** | 查看控件树，调整位置、尺寸、锚点和属性；创建 11 类客户端控件，其中图片、文本框和预设按钮提供较完整的编辑能力。 |
-| **Lua 脚本模拟运行** | 管理多个脚本并挂载到客户端控件或模板，检查脚本生命周期、UI 操作、输入响应和动画效果。 |
-| **独立试玩窗口** | 启动、暂停、继续和单步运行，通过鼠标、触摸或按键测试交互，查看运行状态、日志和错误。 |
-| **多设备与多玩家模拟** | 在 5 种 PC / 手机画布上检查布局；在本地模拟 1–8 名玩家，切换视角检查变量与信号交互。 |
-| **AI 试玩与自动测试** | 通过工具直接编辑工程、驱动操作、获取截图；记录操作时间线，回放用例并检查控件、变量和日志。 |
-| **七步游戏制作工作流** | 从策划案与测试用例出发，展示 HTML 效果、准备千星美术素材，再完成 Lua 编码、测试与真机反馈修复。 |
-| **存档与资产交换** | 用完整 JSON 存档保存工程，导入导出 UI、Lua 脚本及已支持的 GIA 内容，衔接后续编辑与交付。 |
+| **可视化 UI 编辑** | 创建 11 类客户端控件，调整层级、位置、尺寸、锚点和属性。 |
+| **Lua 脚本运行** | 管理多个脚本，挂载到客户端控件或模板，调试输入与动画。 |
+| **独立试玩** | 支持鼠标、触摸和按键，可暂停、单步并查看日志。 |
+| **设备与多人模拟** | 提供 5 种 PC / 手机画布，支持本地 1–8 人试玩与视角切换。 |
+| **AI 自动测试** | 编辑工程、发送输入、截图，录制和回放测试用例。 |
+| **七步制作工作流** | 从策划、TDD、HTML 演示到美术、Lua 实现、测试与真机验证。 |
+| **存档与资产交换** | 保存完整 JSON 工程，导入导出 UI、Lua 和已支持的 GIA 内容。 |
 
-11 类控件的实际运行能力和缺口见 [客户端控件支持矩阵](studio/docs/control-support.md)。文本视窗、网格视窗现支持基础滚轮/拖拽/触摸与滚动条；编辑、字段存取与完整仿真程度分别说明。
+控件能力详见 [客户端控件支持矩阵](studio/docs/control-support.md)。
 
 ## 集成方式
 
-按你的开发环境选择接入方式。Web 可以独立使用；让 AI 直接编辑和测试工程时使用 MCP；需要边对话边看画面时组合 MCP + 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`。
+| 方式 | 适用场景 |
+|---|---|
+| **[Web 编辑器](#web-部署)** | 在浏览器中独立编辑和试玩，或查看 AI 修改后的工程。 |
+| **[MCP 服务](#mcp-接入)** | 让 OpenCode、WorkBuddy、Codex 等 AI 工具直接编辑和测试。 |
+| **[DeepSeek Harness 插件](#deepseek-harness-插件)** | 在 Harness 内使用编辑器、模拟器工具和游戏制作 Agent。 |
 
 ### Web 部署
 
-准备 **Node.js 22+**，从 npm 安装后即可启动完整前后端：
+需要 **Node.js 22+**：
 
 ```sh
 npm install -g beyond-simulator-web
@@ -42,34 +38,22 @@ mkdir ../my-game
 beyond-simulator-web --workspace ../my-game --open
 ```
 
-也可以从源码启动。准备 **pnpm 10.15.0**，在本仓库根目录执行：
-
-```sh
-pnpm install --frozen-lockfile
-mkdir ../my-game
-pnpm dev:web --workspace ../my-game
-```
-
-这里的 `my-game` 是保存游戏文件的工作区。已有项目时，跳过创建目录，将参数换成现有目录，例如 `--workspace E:/my-game`。
-
-启动后打开：
+`my-game` 用于保存游戏文件；已有工程可直接指定目录，例如 `--workspace E:/my-game`。
 
-- [编辑器](http://127.0.0.1:4173/editor)：编辑 UI、Lua 和服务端逻辑，保存存档并试玩。
-- [存档预览](http://127.0.0.1:4173/)：查看工作区中已保存的存档，文件更新后自动刷新，适合配合 AI 或外部编辑器使用。
+- [编辑器](http://127.0.0.1:4173/editor)：编辑、保存和试玩。
+- [存档预览](http://127.0.0.1:4173/)：查看已保存的工程，文件更新后自动刷新。
 
-Web 也支持安装预构建包运行，仓库提供了 Docker 部署配置。对外部署时需配置访问口令和 HTTPS；当前面向单个可信操作者，不提供网站用户之间的项目权限隔离。安装包、Docker 和部署参数见 [Web 使用与部署指南](web/README.md)。
+支持 Docker 部署。对外提供服务时需配置访问口令和 HTTPS，适合单个可信操作者使用。详见 [Web 指南](web/README.md)。
 
 ### MCP 接入
 
-在 OpenCode、WorkBuddy、Codex 等支持本地 MCP stdio 服务的 AI 工具中配置模拟器，指定游戏工作区后，AI 即可打开、编辑和保存工程，控制试玩并获取画面。各客户端的配置入口和格式不同，共用以下服务命令与参数：
-
-从 npm 安装：
+需要 Node.js 22+，以及支持本地 MCP stdio 的 AI 客户端：
 
 ```sh
 npm install -g beyond-simulator-mcp
 ```
 
-然后在客户端中添加本地 stdio 服务：
+在客户端添加本地 stdio 服务：
 
 | 配置项 | 值 |
 |---|---|
@@ -77,130 +61,89 @@ npm install -g beyond-simulator-mcp
 | 命令 | `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 编辑器中的未保存草稿不会被自动覆盖。
+配置参考：[OpenCode](https://opencode.ai/docs/mcp-servers/)、[WorkBuddy](https://open.workbuddy.cn/docs/connector)、[Codex](mcp/README.md#codex-接入)。接入后应能看到 `qxqy_project_open`、`qxqy_studio_play` 等工具。
 
-只使用 Web 时，AI 也可以在工作区编辑 Lua 和工程文件，由用户在 Web 中加载检查；能否直接操作网页取决于 AI 客户端实际提供的浏览器工具。Web 服务本身不注册 MCP 工具。
-
-安装方式、客户端配置和工具示例见 [MCP 接入指南](mcp/README.md)。
+MCP 可独立使用，也可与 Web 指向同一工作区：AI 保存工程后，即可在 Web 存档预览中查看。完整配置见 [MCP 指南](mcp/README.md)。
 
 ### 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 兼容说明](dsh-plugin/README.md#harness-02-兼容性)。
+需要 Node.js 22+ 和 DeepSeek Harness：
 
 ```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-2.2.0.tgz
-
-dsh --profile web --dump-config
 dsh web
 ```
 
-为会话绑定游戏项目工作区，打开“模拟器”视图，即可编辑 UI 和 Lua 并启动试玩。插件同时提供模拟器操作 Skill，以及“千星 2D+Lua 游戏制作”Agent 预设；新建会话时可以选择该预设。
-
-更新已有插件时，执行同一条安装命令，再重启 Harness。已有的用户 Agent 预设会保留，不会随插件升级自动覆盖。
+为会话绑定游戏工作区，打开「模拟器」视图。新建会话时可选择「千星 2D+Lua 游戏制作」Agent 预设。
 
-安装配置与工具说明见 [Harness 插件指南](dsh-plugin/README.md)。
-
-GitHub 安装使用仓库默认分支，安装时由 `prepare` 自动构建。首次安装若 pnpm 提示需要批准构建，请按提示允许该插件的构建脚本，再重新执行安装命令。安装入口是整个仓库，不需要指定子目录。详见 [分发说明](DISTRIBUTION.md#harness-安装入口)。
+更新时重新执行安装命令并重启 Harness；已有用户 Agent 预设会保留。GitHub / 本地包安装及版本兼容说明见 [Harness 插件指南](dsh-plugin/README.md)。
 
 ## 用 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 修复** | 交接导入与脚本挂载，协助校准真实索引、绑定脚本更新目录，再根据真机回传修复和回归。 | 游戏资产、导入与后续更新说明、真机结果及待处理项。 |
+提供游戏想法、参考图或已有工程，在 Harness 中选择游戏制作 Agent，或让其他 AI 工具读取 [七步制作 Skill](agent/wonderland-lua-builder/skills/qxqy-game-studio/SKILL.md)，通过 MCP 开始制作。
 
-先用策划案和测试用例明确目标，再用 HTML 展示确认体验，随后准备千星美术参考图和素材，进入 Lua 编码与测试。最终交付的是 Lua、完整存档和可导出的游戏资产；真机试玩发现的问题继续进入修复与回归。
-
-可以这样开始：
-
-> 我想做一个适合手机操作的 2D 小游戏：点击躲避障碍，连续成功会加分。请先写策划案并制定 TDD 测试用例，再做 HTML 效果展示。确认后准备千星美术参考图和素材，完成 Lua 编码与测试，最后配合我真机试玩并修复 bug。
+| 步骤 | 产出 |
+|---|---|
+| **1. 策划案** | 核心玩法、操作、计分与胜负规则。 |
+| **2. TDD 测试用例** | 开局、成功、失败、重开及边界情况的操作与预期。 |
+| **3. HTML 演示** | 可试玩的效果展示，用于确认画面、操作和节奏。 |
+| **4. 千星美术素材** | 参考图、素材清单与 UI 还原方案。 |
+| **5. Lua 实现** | 可运行的游戏脚本与完整存档。 |
+| **6. 测试** | AI 试玩、问题修复与回归结果。 |
+| **7. 真机验证** | 导入、脚本挂载与更新说明，以及真机反馈修复。 |
 
-已有工程可以从需要补齐的环节继续；玩法变化时同步更新策划案与测试用例，修复 bug 后重新执行相关测试。
+开始前需连接可用的官方 2D/Lua 知识来源，例如 `miliastra-toolbox` 或本地文档；安装包不含官方知识库。配置与流程见 [Agent / Skill 指南](agent/wonderland-lua-builder/README.md)。
 
 ## 使用指南
 
 ### 1. 准备工程
 
-一个存档集中管理三类资产：**服务端 UI、客户端 UI 模板和 Lua 脚本**。它们共同组成试玩所需的界面与逻辑。
-
-- 从零开始：在编辑器中添加控件、创建客户端模板，再编写 Lua 脚本。
-- 继续已有工程：从顶栏“工作区存档”选择已保存的项目，或点击“导入”打开本地文件。
-- 迁入现有资产：导入支持的 UI JSON、GIA 或 Lua，再检查布局和脚本挂载关系。
-
-编写 Lua 时，AI 使用启动前已经核验的知识来源，按当前需求读取官方 API、指南和实战经验；“已配置知识库”还需核实当前会话能否读取所需资料。需要从参考图制作美术时，也可以配合工作区已有的像素画、图元拟合、UI 制作或帧动画 Skill。
+一个存档包含 **服务端 UI、客户端控件模板和 Lua 脚本**。可从零创建，也可通过顶栏「工作区存档」打开已有工程，或用「导入」载入 JSON、GIA 和 Lua。
 
 ### 2. 编辑并试玩
 
-1. 在“UI 编辑”页添加控件，调整属性，并切换 PC / 手机画布检查适配。
-2. 在“Lua 脚本”页创建或导入脚本，将入口脚本挂载到客户端控件或客户端模板；模板脚本在模板实例化时运行。
-3. 如果玩法需要服务端响应，在“服务端逻辑”页配置监听信号、设置变量和向玩家发送信号。
-4. 点击“试玩 ↗”，在独立窗口中操作游戏；Desktop 等宿主拒绝新窗口时自动进入应用内全屏试玩。遇到问题时暂停、单步推进，并查看“日志”页中的脚本输出与运行状态。内嵌时通过“返回编辑”“关闭试玩”或 Escape 停止并返回。
-5. 返回编辑器修改，再次试玩；需要检查多人交互时，调整试玩人数并切换玩家视角。
+1. 在「UI 编辑」中添加控件，切换 PC / 手机画布检查布局。
+2. 在「Lua 脚本」中创建或导入脚本，挂载到客户端控件或模板；模板脚本在实例化时运行。
+3. 按需在「服务端逻辑」中配置变量和信号。
+4. 点击「试玩 ↗」，使用暂停、单步和「日志」排查问题，也可调整人数并切换玩家视角。宿主不支持新窗口时会进入内嵌试玩，通过「返回编辑」「关闭试玩」或 Escape 返回。
 
 ### 3. 让 AI 帮你测试
 
-通过 Harness 插件或 MCP 接入后，可以直接描述要检查的行为，例如：
-
-> 打开我的游戏存档，在手机 16:9 画布上试玩。点击开始按钮，检查得分是否变化，截取操作后的画面，并告诉我日志里有没有报错。
-
-也可以把操作整理成可重复执行的测试：
-
-> 把“开始游戏 → 点击目标 → 得分增加”记录成测试用例。修改脚本后重新回放，检查得分和界面状态是否符合预期。
+接入 MCP 或 Harness 后，可直接说明操作与预期，例如：
 
-AI 可以直接获取工程状态、发送输入、读取日志和截图，无需你手动切换到试玩窗口。涉及玩法规则时，请提供预期结果，例如“每次点击加 1 分”“玩家 1 的操作不应改变玩家 2 的分数”。
+> 打开我的存档，在手机 16:9 画布试玩。点击开始，再点击目标，检查得分是否增加 1，截图并查看日志。把这组操作记录成测试用例，修改后重新回放。
 
 ### 4. 保存与导出
 
-继续开发时，优先保存完整存档；需要与外部编辑链路交换资产时，再选择相应导出格式。
-
-| 目的 | 推荐方式 |
+| 目的 | 操作 |
 |---|---|
-| 保存进度、备份或交给 AI 继续修改 | 导出“资产包 JSON（三类合一）”，保留 UI、脚本和挂载关系。 |
-| 保存到 Web 服务的工作区 | 点击“保存存档”，填写工作区内的相对路径，例如 `my-game.save.json`。 |
-| 与官方编辑器交换已支持的资产 | 导出对应的 GIA，并检查导出提示及导入后的实际效果。 |
-| 单独交换 UI 或脚本 | 导出当前界面 Authoring JSON、脚本包或单个 Lua 脚本。 |
+| 继续开发或备份 | 导出「资产包 JSON（三类合一）」，保留 UI、脚本和挂载关系。 |
+| 保存到工作区 | 点击「保存存档」，填写相对路径，例如 `my-game.save.json`。 |
+| 导入官方编辑器 | 导出对应 GIA，检查导出提示及导入效果。 |
+| 单独交换 UI 或脚本 | 导出当前界面 Authoring JSON、脚本包或单个 Lua。 |
 
-编辑和试玩不会自动把完整存档写入磁盘。Web 用户请显式保存，Harness 用户可导出 JSON，MCP 用户可让 AI 调用保存工具；关闭服务前先保存未完成的工作。
+编辑和试玩不会自动把完整存档写入磁盘，请在退出前保存；使用 MCP 时可让 AI 调用保存工具。
 
 ### 5. 导入真机并持续更新
 
-首次交付时，AI 会根据工程给出需要导入的文件、脚本映射与挂载位置，以及试玩步骤。你需要在千星沙箱完成导入，核对实际控件/模板索引；索引变化可通过对话告知 AI，或在模拟器中修改后让 AI 同步脚本。直接手改脚本时也应将最终修改同步回工程。
+将资产和脚本导入千星沙箱后，核对实际控件 / 模板索引，并同步 Lua 引用。
 
-后续更新可以在 Web/DSH 的“Lua 脚本 → 实机脚本同步”绑定该关卡导入后的脚本目录。AI 准备修改并预览差异，你检查目标路径、选择文件并确认复制，然后在千星沙箱保存并重新试玩。目录绑定随完整存档保存，便于下次复用；新增脚本仍需建立映射和必要挂载。
+后续可让 AI 更新已绑定的脚本目录，也可通过「Lua 脚本 → 实机脚本同步」绑定目录、预览差异并确认复制，再到千星沙箱保存并重新试玩。新增脚本仍需建立映射和挂载；无法直接访问游戏目录时可手动更新。
 
-如果模拟器服务无法访问游戏所在电脑的目录，可按交付说明手动更新。完整分工见 [真机交付与验证](agent/wonderland-lua-builder/skills/qxqy-game-studio/references/07-device-validation.md)，目录配置与复制说明见 [实机脚本同步](studio/docs/script-sync.md)。
+详见 [真机交付与验证](agent/wonderland-lua-builder/skills/qxqy-game-studio/references/07-device-validation.md)和 [实机脚本同步](studio/docs/script-sync.md)。
 
 ## 当前支持边界
 
-- **模拟器通过不等于真机通过。** 它用于提前发现脚本、布局和交互问题，最终仍需在千星奇域中验证。
-- **服务端模拟覆盖变量与信号。** 1–8 人试玩是本地多客户端模拟，不包含完整官方服务端节点图或真实网络联机。
-- **图片预览支持基础图元、静态素材和元件图标。** 静态来源 `100001–100006` 使用代理图形，另有 1,516 个静态图片及 2,720 个元件图标 ID 可按需下载。图片类型支持「基础／拉伸」：基础整图缩放，拉伸按素材边界三切片／九切片；全零边界按基础显示。编辑器、试玩及 AI 截图共用按来源隔离的本地缓存，浏览器复用 HTTP 缓存。属性面板可「重新下载此素材」。未知来源/ID 或加载失败显示缺失提示；动效及 3D 模型不在此预览范围。详见 [素材缓存与预览](studio/docs/image-assets.md)。
-- **Lua 2D 音效可在试玩页播放。** 支持 `game.PlayAudio2D`、`game.StopAudio`、`game.IsAudioAlive`，固定 1,997 个音频 ID，按需下载 MP3 并复用磁盘/浏览器缓存。首次可点击「开启声音」解锁；时长及暂停采用明确的模拟器策略。详见 [音频缓存与接口](studio/docs/audio-assets.md)。
-- **GIA 支持已验证的内容子集。** 部分控件属性与脚本挂载关系无法完整交换，导出时请关注提示，并保留原始文件及完整 JSON 存档。
+- **模拟器通过不等于真机通过**，最终需在千星奇域中验证。
+- **多人试玩为本地模拟**，服务端覆盖变量与信号，不包含完整官方节点图或网络联机。
+- **图片**支持基础图元、静态素材、元件图标及「基础／拉伸」模式；3D 模型不在预览范围。详见 [素材说明](studio/docs/image-assets.md)。
+- **界面／全屏动效**支持浏览器预览与 Lua 试玩，资源失败仅跳过对应动效；无头 PNG 省略视频帧，非空动效 GIA 配置待核实。详见 [动效播放](studio/docs/ui-vfx-playback.md)。
+- **Lua 2D 音效**支持试玩播放，素材按需下载。详见 [音频说明](studio/docs/audio-assets.md)。
+- **GIA 支持已验证的内容子集**，请关注导出提示，保留原始文件和完整 JSON 存档。
 
 ## 从源码构建
 
-开发环境为 Node.js 22+、pnpm 10.15.0。首次安装依赖后，可以在仓库根目录构建和测试：
+需要 Node.js 22+、pnpm 10.15.0，在仓库根目录运行：
 
 ```sh
 pnpm install --frozen-lockfile
@@ -208,27 +151,35 @@ pnpm build
 pnpm test
 ```
 
-生成可交付的 Web、Harness 和 MCP 安装包：
-
-```sh
-pnpm pack:release
-pnpm test:packages
-```
+自行打包和发布见 [分发说明](DISTRIBUTION.md)。
 
-安装包生成在 `release/`，本次产物的名称、版本与校验值见 `release/manifest.json`。包中已包含模拟器核心及所需界面资源，使用者无需构建源码；安装时仍会下载第三方运行依赖。
+## 文档树
 
-测试套件完全自包含，只依赖仓库内源码与合成数据，独立检出即可运行。模块分工见 [开发入口](AGENTS.md)，构建、验收与发布设计见 [分发说明](DISTRIBUTION.md)。
+按任务逐层阅读；模块 README 管理自己的专题入口。
 
-自动发布通过 `npm-*` Git tag 触发；需要先在 npm 为三个包绑定同一份 GitHub Actions Trusted Publisher。配置项和版本规则见 [自动发布说明](DISTRIBUTION.md#自动发布到-npm)。
+- **使用与接入**
+  - [Web](web/README.md)：编辑器、磁盘预览与部署。
+  - [MCP](mcp/README.md)：工程句柄、工具协议与时钟。
+  - [Harness 插件](dsh-plugin/README.md)：安装、宿主兼容与排障。
+    - [版本公告](dsh-plugin/CHANGELOG.md)
+    - [模拟器操作 Skill](skill/SKILL.md)
+  - [游戏制作预设](agent/wonderland-lua-builder/README.md)：七步流程、参考资料与行为评估。
+- **实现与维护**
+  - [Studio](studio/README.md)：存档、布局、GIA、素材与渲染专题。
+  - [共用编辑器](editor-ui/README.md)：界面集成、语言、字体与试玩窗口。
+  - [Lua Runtime](client/lua-runtime/README.md)：架构与观察契约。
+  - [Server](server/README.md)：变量与信号。
+  - [分发](DISTRIBUTION.md)：构建、安装验收与发布。
+  - [贡献约束](AGENTS.md)：模块分工、文档与测试维护规则。
 
 ## 开源协议
 
-本项目采用 [GNU GPL v3.0（GPL-3.0-only）](LICENSE)。源码仓库：[1475505/miliastra-beyond-simulator](https://github.com/1475505/miliastra-beyond-simulator)。
+[GNU GPL v3.0（GPL-3.0-only）](LICENSE) · [源码仓库](https://github.com/1475505/miliastra-beyond-simulator)
 
 ## 界面语言与更新
 
-顶部导航栏「字体设置」旁提供界面语言切换，底栏提供「检查更新」和「联系作者」；非中文运行环境默认英文，项目内容保持原文。使用和术语来源见 [界面说明](studio/docs/interface.md)。
+顶部「字体设置」旁可切换语言；自动模式跟随系统语言，非中文环境默认英文。底栏提供「检查更新」和「联系作者」。详见 [界面说明](studio/docs/interface.md)。
 
 ## 本地自定义字体
 
-在编辑器上方「字体设置」中可指定本地 TTF/OTF，或选择系统字体；默认尝试 Windows 原神的常见安装位置，未找到则使用系统字体。设置仅保存在本机，保存后重启宿主并刷新页面生效；原有环境变量 `QXQY_FONT_PATH` 仍优先。整个模拟器界面、编辑画布、试玩、PNG 和换行测量使用同一自定义字体，不附带字体文件、不写入项目存档。配置与分发边界见 [本地字体说明](studio/docs/local-fonts.md)。
+在「字体设置」中选择本地 TTF/OTF 或系统字体，也可自动查找 Windows 原神安装目录。保存后重启宿主并刷新页面，设置仅保存在本机。详见 [字体说明](studio/docs/local-fonts.md)。