beyond-simulator-web 0.2.2 → 0.3.0

package/README.md

@@ -42,7 +42,19 @@ beyond-simulator-web --workspace /absolute/path/to/workspace --open
 
 ## 与 MCP 配合
 
-MCP 显式调用 `qxqy_project_save` 保存工作区 JSON 后，`/` 每 700ms 检查当前文件，停止旧试玩、加载新存档并通过 SSE 刷新浏览器。该预览不写文件。`/editor` 不自动用磁盘内容覆盖正在编辑的草稿，需要手动“从工作区拉取存档”。
+MCP 显式调用 `qxqy_project_save` 保存工作区 JSON 后，`/` 每 700ms 检查当前文件。还没有打开存档时，每 5 秒重新发现存档并自动打开最新的 `qxqy-simulator-save`；已经打开时，只在该文件变化后停止旧试玩、重新加载，并通过 SSE 刷新浏览器。不会自动改看另一个路径。顶部刷新按钮可立即扫描。该预览不写文件。`/editor` 不自动用磁盘内容覆盖正在编辑的草稿，需要手动“从工作区拉取存档”。
+
+MCP 0.3.0 起提供 `qxqy_preview_status()` 和 `qxqy_preview_open({ path: "game.save.json" })`：前者查询 Web 实际版本、工作区、当前存档和加载错误，后者直接让预览服务读取指定存档，无需重新保存。MCP 默认连接 `http://127.0.0.1:4173`，其他端口使用 MCP 的 `--web-url` 或 `QXQY_WEB_URL`；Web 启用口令时，在 MCP 环境中配置相同的 `QXQY_WEB_PASSWORD`。两边必须使用同一工作区，桥接会在读取和打开时校验。工具回执确认服务端已加载，浏览器通过 SSE 或定期状态同步刷新。
+
+页面“预览连接”显示 Web 版本、工作区、加载错误与扫描警告。发现列表只读取 JSON 的前 4 KiB，不再排除超过 8 MiB 的合法存档；在扫描预算内按修改时间取最新 50 项。自动扫描跳过隐藏条目及依赖/生成目录，最多 8 层、10,000 条目和 1,000 目录；达到限制或读取失败会显示汇总警告。明确指定的 `--file` / 预览工具路径不受列表筛选限制，但仍受工作区边界保护。损坏 JSON 会显示加载错误并继续重试；初始文件缺失不会导致整个 Web 服务无法启动。
+
+源码更新后需运行 `pnpm build` 并重启 Web/MCP；`pnpm start:web` 直接运行已有 `web/dist`，不会自动构建。npm 安装用户更新包后也需重启进程。
+
+### 2026-09-26 预览同步修复记录
+
+Web/MCP 0.3.0、共享宿主所在 DSH 2.0.3：修复空工作区启动后跳过新文件发现、默认保存路径与打开路径脱节、大文件不出现在列表及前 50 项截断遗漏最新文件。补充显式预览桥接、加载错误与版本信息。证据为仓库内 `web/test/preview-state.test.mjs`、`studio/test/workspace.test.mjs`、`studio/test/controller-archive.test.mjs` 与实际启动两个进程的 `mcp/test/web-integration.test.mjs`；`evidence_source: observed`，运行端 `simulator`，`device_status: not_required`。包公开状态以 npm 审核结果为准。
+
+同日浏览器实测：启动试玩后将临时存档替换为损坏 JSON，页面显示加载错误并停止旧试玩；恢复原文件（保留原大小与时间戳）后错误清除并自动回到编辑预览。轮询不得因旧试玩状态屏蔽错误事件；存在加载错误时，即使文件时间戳与上次成功加载相同也需要重试。
 
 试玩使用固定 30 FPS Worker、增量场景和 Pixi/WebGL；刷新试玩页会接回已有 Worker，保留暂停和当前玩家。截图仍由 Host 根据统一场景输出 PNG。
 

package/dist/public/app.js

@@ -39,6 +39,9 @@ const elements = {
   runtimeLogs: byId('runtime-logs'),
   clearLogs: byId('clear-logs'),
   toast: byId('toast'),
+  serverVersion: byId('server-version'),
+  workspacePath: byId('workspace-path'),
+  diagnostics: byId('preview-diagnostics'),
 }
 
 const kindIcons = {
@@ -110,7 +113,7 @@ function renderArchives() {
   const previous = elements.archive.value
   elements.archive.replaceChildren()
   const archives = model?.archives || []
-  if (!archives.length) {
+  if (!archives.length && !model?.activePath) {
     const empty = option('', '未发现 qxqy-simulator-save')
     empty.disabled = true
     elements.archive.append(empty)
@@ -119,6 +122,9 @@ function renderArchives() {
   for (const archive of archives) {
     elements.archive.append(option(archive.path, `${archive.name} · ${archive.path}`))
   }
+  if (model.activePath && !archives.some(archive => archive.path === model.activePath)) {
+    elements.archive.prepend(option(model.activePath, `${model.snapshot?.save?.name || '当前存档'} · ${model.activePath}`))
+  }
   elements.archive.value = model.activePath || previous || archives[0].path
 }
 
@@ -133,7 +139,7 @@ function renderDevices() {
 }
 
 function renderTree() {
-  const rows = model?.snapshot?.tree || []
+  const rows = model?.activePath ? (model?.snapshot?.tree || []) : []
   elements.tree.replaceChildren()
   elements.treeCount.textContent = String(rows.length)
   elements.treeTitle.textContent = model?.snapshot?.asset?.type === 'client-control-template' ? '模板与子控件' : '控件树'
@@ -178,7 +184,7 @@ function addDetail(label, value) {
 }
 
 function renderNodeDetails() {
-  const row = model?.snapshot?.tree?.find((item) => item.id === selectedId)
+  const row = model?.activePath && model?.snapshot?.tree?.find((item) => item.id === selectedId)
   elements.nodeDetails.replaceChildren()
   elements.nodeName.textContent = row?.name || '未选择'
   if (!row) return
@@ -209,17 +215,20 @@ function renderStage() {
   elements.stageEmpty.hidden = showEditor || showPlay
   elements.stageShell.classList.toggle('playing', mode === 'play' && Boolean(model?.play?.running))
   if (!hasArchive) {
-    elements.stageEmpty.querySelector('strong').textContent = '等待工作区存档'
-    elements.stageEmpty.querySelector('p').textContent = 'Codex 保存 qxqy-simulator-save JSON 后会自动出现在这里。'
+    elements.stageEmpty.querySelector('strong').textContent = model?.lastError ? '存档加载失败' : '等待工作区存档'
+    const watched = model?.workspace ? `正在监听 ${model.workspace}。` : ''
+    elements.stageEmpty.querySelector('p').textContent = model?.lastError
+      ? model.lastError
+      : `${watched}Codex 保存 qxqy-simulator-save JSON 后会自动出现在这里。`
   } else if (mode === 'play' && !model.play.running) {
     elements.stageEmpty.querySelector('strong').textContent = '试玩尚未启动'
     elements.stageEmpty.querySelector('p').textContent = '选择设备并点击“启动”，即可运行 Lua 和交互逻辑。'
   }
   if (showEditor) refreshEditorImage()
-  elements.assetLabel.textContent = snapshot?.asset?.label || '等待存档'
-  elements.saveName.textContent = snapshot?.save?.name || '未命名存档'
-  elements.canvasLabel.textContent = snapshot?.canvas ? `${snapshot.canvas.label} · ${snapshot.canvas.width}×${snapshot.canvas.height}` : '—'
-  elements.revisionLabel.textContent = `Revision ${snapshot?.version ?? '—'}`
+  elements.assetLabel.textContent = hasArchive ? (snapshot?.asset?.label || '等待存档') : '等待存档'
+  elements.saveName.textContent = hasArchive ? (snapshot?.save?.name || '未命名存档') : '未命名存档'
+  elements.canvasLabel.textContent = hasArchive && snapshot?.canvas ? `${snapshot.canvas.label} · ${snapshot.canvas.width}×${snapshot.canvas.height}` : '—'
+  elements.revisionLabel.textContent = hasArchive ? `Revision ${snapshot?.version ?? '—'}` : 'Revision —'
   elements.activePath.textContent = model?.activePath || '尚未打开存档'
   elements.playReadout.textContent = mode === 'play'
     ? model?.play?.running
@@ -309,7 +318,7 @@ function renderControls() {
   elements.playStop.disabled = busy || !running
   elements.asset.disabled = busy || mode === 'play'
   elements.device.disabled = busy || !hasArchive
-  elements.archive.disabled = busy || !(model?.archives?.length)
+  elements.archive.disabled = busy || !(model?.archives?.length || model?.activePath)
   elements.reload.disabled = busy
 }
 
@@ -319,20 +328,27 @@ function render() {
   renderTree()
   renderNodeDetails()
   const snapshot = model?.snapshot
+  const hasArchive = Boolean(model?.activePath)
   elements.asset.value = snapshot?.asset?.type || 'server-control-template'
-  elements.metricControls.textContent = String(snapshot?.tree?.length || 0)
-  elements.metricScripts.textContent = String(snapshot?.scriptCount || 0)
-  elements.metricCanvas.textContent = snapshot?.canvas ? `${snapshot.canvas.width}×${snapshot.canvas.height}` : '—'
+  elements.metricControls.textContent = hasArchive ? String(snapshot?.tree?.length || 0) : '0'
+  elements.metricScripts.textContent = hasArchive ? String(snapshot?.scriptCount || 0) : '0'
+  elements.metricCanvas.textContent = hasArchive && snapshot?.canvas ? `${snapshot.canvas.width}×${snapshot.canvas.height}` : '—'
   elements.runtimeLogs.textContent = formatLogs(model?.play?.logs)
+  elements.serverVersion.textContent = model?.version ? `Web ${model.version}` : '服务版本未知，请更新 Web'
+  elements.workspacePath.textContent = model?.workspace ? `工作区：${model.workspace}` : ''
+  elements.diagnostics.textContent = [model?.lastError, ...(model?.discovery?.warnings || [])].filter(Boolean).join('\n')
+  elements.diagnostics.hidden = !elements.diagnostics.textContent
+  elements.diagnostics.classList.toggle('error', Boolean(model?.lastError))
   renderControls()
   renderStage()
   syncPlayPolling()
 }
 
-async function refreshState({ quiet = false } = {}) {
-  if (mode === 'play' && model?.play?.running && quiet) return
+async function refreshState({ quiet = false, force = false, forceDiscovery = false } = {}) {
+  if (mode === 'play' && model?.play?.running && play.running && quiet && !force) return
   try {
-    model = await requestJson('/api/state')
+    model = await requestJson(forceDiscovery ? '/api/state?refresh=1' : '/api/state')
+    if (!model?.play?.running && play.running) play.reset()
     if (!quiet && model?.play?.running && !play.running) {
       mode = 'play'
       await play.attach()
@@ -389,7 +405,15 @@ elements.reload.addEventListener('click', () => run(async () => {
     render()
     notify('已重新读取磁盘存档')
   } else {
-    await refreshState()
+    await refreshState({ forceDiscovery: true })
+    const newest = model?.archives?.[0]?.path
+    if (newest && !model?.activePath) {
+      model = await requestJson('/api/open', { method: 'POST', body: JSON.stringify({ path: newest }) })
+      mode = 'editor'
+      selectedId = ''
+      render()
+      notify('已打开存档')
+    }
   }
 }))
 
@@ -447,13 +471,14 @@ events.addEventListener('error', () => setConnection('error', '正在重连'))
 events.addEventListener('state', (event) => {
   let change = {}
   try { change = JSON.parse(event.data) } catch {}
-  if (change.reason === 'external-change') {
+  if (change.type === 'archive') {
     mode = 'editor'
+    selectedId = ''
     play.reset()
-    notify('检测到 Codex/MCP 保存，预览已更新')
+    notify(change.reason === 'external-change' ? '检测到存档变化，预览已更新' : '预览存档已打开')
   }
   // 试玩画面有独立的轻量状态轮询；忽略 play 事件，避免重复刷新。
-  if (change.type !== 'play') void refreshState({ quiet: true })
+  if (change.type !== 'play') void refreshState({ quiet: true, force: true })
 })
 
 setInterval(() => { void refreshState({ quiet: true }) }, 5000)

package/dist/public/index.html

@@ -115,7 +115,13 @@
           <div class="log-heading"><span>Runtime Logs</span><button id="clear-logs">清空</button></div>
           <pre id="runtime-logs">试玩启动后显示 Lua 日志。</pre>
         </section>
-        <p class="watch-note"><span>●</span> 正在监听磁盘。MCP 保存当前 JSON 后，预览会自动重新加载。</p>
+        <section class="info-card connection-details">
+          <span class="info-label">预览连接</span>
+          <div id="server-version">正在连接服务…</div>
+          <div id="workspace-path"></div>
+          <div id="preview-diagnostics" role="status" aria-live="polite" hidden></div>
+        </section>
+        <p class="watch-note"><span>●</span> 当前存档保存后自动刷新；首次存档会自动发现。切换其他存档请使用顶部列表或 MCP 预览工具。</p>
       </aside>
     </main>
 

package/dist/public/styles.css

@@ -256,6 +256,10 @@ button:focus-visible, select:focus-visible, .stage-shell:focus-visible, .tree-ro
 .log-card pre { min-height: 130px; max-height: 34vh; margin: 0; padding: 9px; overflow: auto; color: var(--muted); background: var(--input); white-space: pre-wrap; word-break: break-word; font: 10px/1.55 ui-monospace, SFMono-Regular, Consolas, monospace; }
 .watch-note { margin: 10px 11px 16px; padding: 7px 8px; border-left: 2px solid #477cf0; background: color-mix(in srgb, var(--blue) 8%, var(--panel-2)); color: var(--muted); font-size: 9px; line-height: 1.5; }
 .watch-note span { color: #62d398; }
+.connection-details { font-size: 10px; line-height: 1.6; overflow-wrap: anywhere; }
+#workspace-path { color: var(--muted); }
+#preview-diagnostics { margin-top: 7px; white-space: pre-wrap; }
+#preview-diagnostics.error { color: var(--danger); }
 
 .toast { position: fixed; left: 50%; bottom: 18px; z-index: 20; max-width: min(520px, calc(100vw - 32px)); padding: 8px 11px; border: 1px solid var(--line); border-radius: 6px; background: var(--panel-2); box-shadow: 0 12px 32px var(--shadow); color: var(--text); font-size: 10px; opacity: 0; pointer-events: none; transform: translate(-50%, 8px); transition: 160ms ease; }
 .toast.visible { opacity: 1; transform: translate(-50%, 0); }