fix public work detail not found recovery

.env.example

@@ -173,6 +173,10 @@ VITE_SCENE_IMAGE_REQUEST_TIMEOUT_MS="150000"
 # Keep this off by default for cleaner logs.
 VITE_LLM_DEBUG_LOG="false"
 
+# Optional: global frontend debug mode. When empty, it follows Vite dev mode.
+# Set to "true" to expose local diagnostic panels, or "false" to hide them.
+VITE_DEBUG_MODE=""
+
 # Optional: official VikingDB credentials for regenerating build-tag similarities
 # with the Python embedding script. The script auto-loads `.env.local` and uses
 # the fixed `bge-large-zh` embedding model.

.hermes/shared-memory/decision-log.md

@@ -32,6 +32,14 @@
 - 验证方式：执行 `npm run test -- src\services\input-devices\runtimeDragInputController.test.ts`、`npm run test -- src\components\puzzle-runtime\PuzzleRuntimeShell.test.tsx`、`npm run typecheck` 和编码检查。
 - 关联文档：`docs/technical/RUNTIME_INPUT_DEVICE_ABSTRACTION_2026-05-10.md`、`docs/technical/PUZZLE_RUNTIME_FRONTEND_LOGIC_REHOME_2026-05-02.md`。
 
+## 2026-05-11 前端调试模式统一判断
+
+- 背景：拼图 mocap 调试面板此前在运行态常驻展示，生产构建和正式体验里容易遮挡棋盘内容；后续其它局部诊断 UI 也需要统一的调试模式入口。
+- 决策：前端新增 `src/config/debugMode.ts` 作为全局调试模式判断，默认跟随 Vite 开发态，允许 `VITE_DEBUG_MODE=true/false` 显式覆盖。拼图运行态 mocap 调试面板只在调试模式下渲染，并默认折叠，只保留连接状态行。
+- 影响范围：前端局部调试 UI、拼图运行态 mocap 诊断面板、`.env.example` 和运行态输入技术文档。
+- 验证方式：执行 `npm run test -- src\components\puzzle-runtime\PuzzleRuntimeShell.test.tsx`、`npm run typecheck` 和编码检查。
+- 关联文档：`docs/technical/RUNTIME_INPUT_DEVICE_ABSTRACTION_2026-05-10.md`。
+
 ## 2026-05-10 儿童动作热身关直接消费 mocap 数据源
 
 - 背景：儿童动作 Demo 不能只依赖浏览器摄像头状态和键鼠调试输入，否则真实硬件接入后会出现“mocap 在线但页面提示摄像头不可用”或“能看到画面但动作不推进”的卡点。

.hermes/shared-memory/pitfalls.md

@@ -383,10 +383,10 @@
 
 ## Rust 构建不要让不可用的 sccache 阻断 rustc
 
-- 现象：Cargo 报 `could not execute process sccache ... rustc.exe -vV (never executed)`，或 `sccache: caused by: Failed to send data to or receive data from server / Failed to read response header / failed to fill whole buffer`；真实 `rustc -Vv` 可以执行，但构建在调用包装器时失败。
-- 原因：环境、Jenkinsfile 或 `server-rs/.cargo/config.toml` 启用了 `sccache` wrapper，但当前 agent 没有可执行的 `sccache`、PATH 中 shim 损坏，或本地 sccache server/client 通道状态损坏。
-- 处理：本地临时排障可在 Git Bash 中执行 `RUSTC_WRAPPER= CARGO_BUILD_RUSTC_WRAPPER= cargo build ...`；`npm run dev:rust` 的 SpacetimeDB publish 已在命中 sccache 通信失败时自动清空 wrapper 重试一次；生产流水线必须先实际执行 `sccache --version`，失败时移除 `RUSTC_WRAPPER` 并回退到直接 `rustc`。
-- 验证：`rustc -Vv` 能输出版本；清空 wrapper 后 `cargo check --target=wasm32-unknown-unknown --release` 能通过；Jenkins 日志出现“未找到可用 sccache，改用 rustc 直接构建”后仍继续真实构建。
+- 现象：Cargo 报 `could not execute process sccache ... rustc.exe -vV (never executed)`、`sccache: error: Timed out waiting for server startup`，或 `sccache: caused by: Failed to send data to or receive data from server / Failed to read response header / failed to fill whole buffer`；真实 `rustc -Vv` 可以执行，但构建在调用包装器时失败。
+- 原因：环境、Jenkinsfile 或 `server-rs/.cargo/config.toml` 启用了 `sccache` wrapper，但当前 agent 没有可执行的 `sccache`、PATH 中 shim 损坏，或本地 sccache server/client 通道状态损坏。Windows 本机若配置了 `SCCACHE_OSS_*`，sccache daemon 冷启动会先经 OSS/本机代理完成缓存读写检查，再监听 `127.0.0.1:4226`；代理或 OSS 链路慢时，Cargo 的 `sccache rustc -vV` 可能先超时。
+- 处理：保留 `server-rs/.cargo/config.toml` 的 `rustc-wrapper = "sccache"`；Windows 本机优先在 `%APPDATA%\Mozilla\sccache\config\config` 写入 `server_startup_timeout_ms = 60000`，拉长 client 等待 daemon 完成 OSS 初始化的时间，然后删除 `server-rs/target/.rustc_info.json` 里缓存的失败探测结果并重跑原始 Cargo 命令。冷启动验证优先用 `sccache --stop-server`，不要在另一个 `cargo` / `rustc` 仍在编译时 `taskkill /F /IM sccache.exe /T`，否则 proc-macro crate 可能被打断并表现为 `serde_derive` / `spacetimedb-bindings-macro` 的 `sccache ... exit code: 1`。若只做临时排障，可在 Git Bash 中执行 `RUSTC_WRAPPER= CARGO_BUILD_RUSTC_WRAPPER= cargo build ...`，或在 PowerShell 用 `cargo check -p api-server --config "build.rustc-wrapper=''"` 一次性绕过 wrapper；生产流水线必须先实际执行 `sccache --version`，失败时移除 `RUSTC_WRAPPER` 并回退到直接 `rustc`。
+- 验证：`rustc -Vv` 能输出版本；冷启动后原始 `cargo check -p api-server` 和 `cargo check -p spacetime-module` 能通过；`sccache --show-stats` 显示 `Cache location oss, name: genarrative-sccache`，证明仍在使用 sccache/OSS 缓存；Jenkins 日志出现“未找到可用 sccache，改用 rustc 直接构建”后仍继续真实构建。
 - 关联：`scripts/dev-rust-stack.sh`、`jenkins/Jenkinsfile.production-stdb-module-build`、`docs/technical/SPACETIMEDB_PUBLISH_SCCACHE_FALLBACK_2026-05-09.md`、`docs/technical/PRODUCTION_DEPLOYMENT_PLAN_2026-05-02.md`。
 
 ## 生产发布入口不要沿用旧 Jenkinsfile / 一体化脚本
@@ -460,3 +460,11 @@
 - 处理：compile 成功时把独立物品图片列表序列化写入 `match3d_work_profile.generated_item_assets_json`；`update_match3d_work` / `publish_match3d_work` 保留该字段；API work summary/detail 映射反序列化为 `generatedItemAssets`。前端保持“本次 draft 优先，重进 profile 兜底”的读取顺序。
 - 验证：`cargo test -p spacetime-client match3d --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server match3d --manifest-path server-rs/Cargo.toml`、`npm run test -- src/components/match3d-result/Match3DResultView.test.tsx`。
 - 关联：`server-rs/crates/spacetime-module/src/match3d/*`、`server-rs/crates/spacetime-client/src/mapper.rs`、`server-rs/crates/api-server/src/match3d.rs`、`src/components/match3d-result/Match3DResultView.tsx`、`docs/technical/MATCH3D_DRAFT_ASSET_GENERATION_PIPELINE_2026-05-10.md`。
+
+## 公开作品详情深链找不到作品不能停在空详情页
+
+- 现象：直接访问 `/works/detail?work=PZ-...`，作品不存在或已下架时会弹出“作品不存在或已下架，将返回首页。”；关闭提示后仍可能停在大白屏。
+- 原因：旧恢复逻辑只覆盖 `/runtime/...`，没有覆盖 `/works/detail`。同时 `selectionStage === 'work-detail'` 且 `selectedPublicWorkDetail === null` 时没有兜底渲染，详情数据为空就只剩空页面。
+- 处理：公开详情失效统一走 `resolveWorkNotFoundRecoveryAction(...)`，覆盖 `/works/detail`、`/gallery/puzzle/detail` 和 `/gallery/visual-novel/detail`；搜索失败和拼图详情 404 分支清理详情/运行态临时状态并回首页；`work-detail` 空数据阶段显示轻量读取态，避免异步间隙白屏。
+- 验证：`npm run test -- src/routing/runtimeNotFoundRecovery.test.ts`、`npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "direct missing public work detail alert returns to platform home"`。
+- 关联：`docs/technical/PUBLIC_WORK_DETAIL_NOT_FOUND_RECOVERY_2026-05-11.md`、`src/routing/runtimeNotFoundRecovery.ts`、`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`。

docs/technical/PUBLIC_WORK_DETAIL_NOT_FOUND_RECOVERY_2026-05-11.md

@@ -0,0 +1,27 @@
+# 公开作品详情失效回首页修复
+
+日期：`2026-05-11`
+
+## 背景
+
+直接访问 `/works/detail?work=<公开作品号>` 时，如果作品已经删除、下架或当前公开列表无法命中该作品，统一作品详情会先进入 `work-detail` 阶段。此前该阶段在没有 `selectedPublicWorkDetail` 时不会渲染任何内容；用户关闭“作品不存在或已下架”的提示后，页面可能只剩空白区域。
+
+## 修复
+
+1. `resolveWorkNotFoundRecoveryAction(...)` 覆盖 `/works/detail`、拼图公开详情和视觉小说公开详情，并复用运行态深链失效的回首页策略。
+2. 拼图公开详情、拼图运行态启动和拼图详情页读取的 `404/NOT_FOUND` 分支改为统一走公开作品失效恢复逻辑。
+3. 直接打开 `/works/detail?work=...` 的搜索失败分支会清理详情态、运行态临时数据，切回首页并清掉 URL query。
+4. `work-detail` 阶段在详情数据为空时渲染轻量读取态，避免异步间隙或异常分支出现纯白屏。
+
+## 验证
+
+- `npm run test -- src/routing/runtimeNotFoundRecovery.test.ts`
+- `npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "direct missing public work detail alert returns to platform home"`
+- `npm run typecheck`
+- `npm run check:encoding -- src/routing/runtimeNotFoundRecovery.ts src/routing/runtimeNotFoundRecovery.test.ts src/components/platform-entry/PlatformEntryFlowShellImpl.tsx src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx docs/technical/PUBLIC_WORK_DETAIL_NOT_FOUND_RECOVERY_2026-05-11.md`
+
+## 关联文件
+
+1. `src/routing/runtimeNotFoundRecovery.ts`
+2. `src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`
+3. `src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx`

docs/technical/README.md

@@ -4,6 +4,7 @@
 
 ## 文档列表
 
+- [PUBLIC_WORK_DETAIL_NOT_FOUND_RECOVERY_2026-05-11.md](./PUBLIC_WORK_DETAIL_NOT_FOUND_RECOVERY_2026-05-11.md)：记录直接访问公开作品详情深链时作品不存在或已下架的回首页修复，避免关闭提示后停在 `work-detail` 空状态白屏。
 - [CHILD_MOTION_DEMO_WARMUP_IMPLEMENTATION_SPEC_2026-05-09.md](./CHILD_MOTION_DEMO_WARMUP_IMPLEMENTATION_SPEC_2026-05-09.md)：冻结儿童动作识别互动玩法 Demo 固定热身关的开发落地规格，覆盖横屏展示、摄像头背景虚化、角色剪影、绿色圆环 2 秒保持、动作教学、当前会话内空间边界记录和后续关卡安全暂停规则。
 - [RUNTIME_INPUT_DEVICE_ABSTRACTION_2026-05-10.md](./RUNTIME_INPUT_DEVICE_ABSTRACTION_2026-05-10.md)：记录运行态输入设备抽象层，明确鼠标、触控、mocap 等设备统一归一为通用拖拽语义，玩法组件只负责解释目标和落点。
 - [RUST_WORKSPACE_DEPENDENCY_CONSOLIDATION_2026-05-07.md](./RUST_WORKSPACE_DEPENDENCY_CONSOLIDATION_2026-05-07.md)：记录 `server-rs` Cargo 依赖集中配置口径，第三方版本和 workspace 内部 crate path 统一维护在根 `server-rs/Cargo.toml`，成员 crate 只保留 feature/optional 差异。

docs/technical/RUNTIME_INPUT_DEVICE_ABSTRACTION_2026-05-10.md

@@ -26,6 +26,12 @@
 - mocap 光标按 60Hz 插值更新 UI 位置，并在拖拽中用插值后的当前点持续驱动输入层，避免输入包帧率低或抖动时出现明显跳变。
 - 合并大块由拼图运行态把手部坐标命中到任一成员拼块；本地拼图运行时再按 `mergedGroupId` 执行整组平移。
 
+## 调试模式
+
+前端全局调试模式统一通过 `src/config/debugMode.ts` 判断。默认跟随 Vite 开发态：`import.meta.env.DEV` 为真时开启，生产构建默认关闭；如需显式覆盖，可设置 `VITE_DEBUG_MODE=true` 或 `VITE_DEBUG_MODE=false`。
+
+拼图运行态的 mocap 调试面板只在全局调试模式下渲染。面板默认折叠，只保留一行连接状态，展开后才显示动作、手势、解析告警和原始包预览，避免开发诊断信息遮挡拼图棋盘和底部操作。
+
 ## 接入规则
 
 新玩法或新设备接入时遵循以下边界：

docs/technical/SPACETIMEDB_PUBLISH_SCCACHE_FALLBACK_2026-05-09.md

@@ -7,6 +7,7 @@ Windows 本地执行 `npm run dev:rust` 或 `spacetime publish` 时，`spacetime
 当本机 sccache server 状态损坏、client/server 通信异常或版本残留不一致时，可能出现：
 
 ```text
+sccache: error: Timed out waiting for server startup. Maybe the remote service is unreachable?
 sccache: error: failed to execute compile
 sccache: caused by: Failed to send data to or receive data from server
 sccache: caused by: Failed to read response header
@@ -15,9 +16,24 @@ sccache: caused by: failed to fill whole buffer
 
 这类错误发生在 rustc wrapper 层，不能说明 SpacetimeDB module 代码本身编译失败。
 
+## 2026-05-11 本机根因定位
+
+本机 `cargo check -p api-server` 失败时，Cargo 还没有进入业务 crate 编译，而是在读取 `server-rs/.cargo/config.toml` 后执行 `sccache rustc -vV` 探测编译器版本。失败的 stderr 会被写入 `server-rs/target/.rustc_info.json`，内容为 `Timed out waiting for server startup`。
+
+当前 PowerShell 环境设置了 `SCCACHE_OSS_BUCKET=genarrative-sccache`、`SCCACHE_OSS_ENDPOINT=https://oss-rg-china-mainland.aliyuncs.com` 和 `SCCACHE_OSS_KEY_PREFIX=genarrative`，且没有设置本地 `SCCACHE_DIR`。因此 sccache daemon 冷启动时会先初始化 OSS 远端缓存，并执行 `.sccache_check` 的读写检查；日志中可见 `Init oss cache ...`、`proxy(http://127.0.0.1:7897/) intercepts ...`，随后才出现 `server started, listening on 127.0.0.1:4226`。
+
+本次排查的结论是：冷启动失败主要发生在 sccache client 等待 daemon 启动的握手窗口内，而 daemon 启动又依赖 OSS/本机代理链路先完成缓存可读写检查。代理或 OSS 链路稍慢时，Cargo 调用的 `sccache rustc -vV` 会先超时；daemon 预热后直接执行同一条 `sccache rustc -vV` 又可能成功，所以这是冷启动/通道状态问题，不是 `api-server` 或 Rust 代码错误。
+
+辅助证据：
+
+1. `rustc -vV` 可直接输出版本，说明 Rust 工具链本身可用。
+2. `tasklist` 曾只看到 `sccache --show-stats` 客户端进程，`netstat` 只出现到 `127.0.0.1:4226` 的 `SYN_SENT`，没有真正的 `LISTEN`，说明当时 client 正在等一个尚未成功监听的 daemon。
+3. 在子进程中临时清掉 `SCCACHE_OSS_*` 并设置本地 `SCCACHE_DIR` 后，sccache 退回本地磁盘缓存，日志显示 `Init disk cache ...`，`rustc -vV` 和 `sccache --show-stats` 均能完成。
+4. `C:\Users\DSK\AppData\Roaming\Mozilla\sccache\config\config` 缺失只是非致命 warning，本机实际配置来自环境变量。
+
 ## 本地开发处理
 
-`scripts/dev-rust-stack.sh` 的 publish 阶段继续由 SpacetimeDB CLI 内部调用 Cargo，并通过 `--build-options="--debug"` 使用 debug 构建参数。遇到 sccache 通信或 wrapper 失败时，本地排障仍优先绕过 wrapper 验证 rustc 本身可用。
+`scripts/dev-rust-stack.sh` 的 publish 阶段继续由 SpacetimeDB CLI 内部调用 Cargo，并通过 `--build-options="--debug"` 使用 debug 构建参数。遇到 sccache 冷启动超时时，优先保留 `sccache` wrapper，并修复 sccache daemon 的启动等待时间；只有在排除 sccache 本身问题时，才临时绕过 wrapper 验证 rustc 本身可用。
 
 该处理不修改 `server-rs/.cargo/config.toml`，也不删除本地 target 缓存。
 
@@ -29,13 +45,56 @@ sccache: caused by: failed to fill whole buffer
 rustc -vV
 ```
 
-如果只想绕过本次 Cargo 构建的 sccache wrapper，可在 Git Bash 中执行：
+如果要保留 sccache 并修复冷启动等待时间，在 PowerShell 中创建或更新 sccache 默认配置：
+
+```powershell
+$configDir = Join-Path $env:APPDATA "Mozilla\sccache\config"
+New-Item -ItemType Directory -Force -Path $configDir | Out-Null
+@(
+  "# Windows 本机 sccache 冷启动需要先完成 OSS 缓存读写检查。"
+  "# 拉长 client 等待 daemon 启动的时间，避免 Cargo 在 rustc -vV 阶段误判超时。"
+  "server_startup_timeout_ms = 60000"
+) | Set-Content -Encoding UTF8 -Path (Join-Path $configDir "config")
+```
+
+随后清掉 Cargo 曾缓存的失败探测结果，并从冷启动验证：
+
+```powershell
+cd C:\proj\Genarrative\server-rs
+sccache --stop-server
+Remove-Item -Force target\.rustc_info.json -ErrorAction SilentlyContinue
+cargo check -p api-server
+```
+
+注意：不要在另一个 `cargo` / `rustc` 仍在编译时执行 `taskkill /F /IM sccache.exe /T`。sccache 对 proc-macro crate 会显示 `Server sent UnhandledCompile` 并把请求转交给真实 rustc；如果此时强杀 sccache client/server，可能让 `serde_derive`、`spacetimedb-bindings-macro` 等 proc-macro 编译直接以 `sccache ... exit code: 1` 失败，而 stderr 里看不到真正的 Rust 诊断。这是排障动作打断编译，不是 `spacetime-module` 源码错误。
+
+如果只想临时绕过本次 Cargo 构建的 sccache wrapper，可在 Git Bash 中执行：
 
 ```bash
 cd server-rs/crates/spacetime-module
 RUSTC_WRAPPER= CARGO_BUILD_RUSTC_WRAPPER= cargo check --target=wasm32-unknown-unknown
 ```
 
+PowerShell 原生 Cargo 的一次性 wrapper 绕过命令是：
+
+```powershell
+cd C:\proj\Genarrative\server-rs
+cargo check -p api-server --config "build.rustc-wrapper=''"
+```
+
+如果需要验证是否为 OSS/代理冷启动问题，可只在当前 PowerShell 进程中切到本地缓存做对照：
+
+```powershell
+$env:SCCACHE_LOG = "debug"
+$env:SCCACHE_ERROR_LOG = "C:\proj\Genarrative\logs\sccache-local-start-error.log"
+$env:SCCACHE_DIR = Join-Path $env:TEMP "genarrative-sccache-local-test"
+Remove-Item Env:SCCACHE_OSS_BUCKET -ErrorAction SilentlyContinue
+Remove-Item Env:SCCACHE_OSS_ENDPOINT -ErrorAction SilentlyContinue
+Remove-Item Env:SCCACHE_OSS_KEY_PREFIX -ErrorAction SilentlyContinue
+sccache "C:\Users\DSK\.rustup\toolchains\stable-x86_64-pc-windows-msvc\bin\rustc.exe" -vV
+sccache --show-stats
+```
+
 如果需要排查 sccache server 状态：
 
 ```bash
@@ -44,10 +103,12 @@ sccache --stop-server
 sccache --start-server
 ```
 
-`sccache --stop-server` 本身也可能因为 server 通道已损坏而失败；此时不应阻断本地开发 publish，先使用 wrapper 降级完成验证。
+`sccache --stop-server` 本身也可能因为 server 通道已损坏而失败；只有确认当前没有 `cargo`、`rustc`、`link` 进程后，才用 `taskkill /F /IM sccache.exe /T` 清理残留进程。此时不应阻断本地开发 publish，先使用 wrapper 降级完成验证。
 
 ## 验证
 
 1. `bash -n scripts/dev-rust-stack.sh`
-2. `RUSTC_WRAPPER= CARGO_BUILD_RUSTC_WRAPPER= cargo check --target=wasm32-unknown-unknown`
-3. 重新运行 `npm run dev:rust`，确认 publish 命令带有 `--build-options="--debug"`。
+2. 冷启动后直接执行 `cargo check -p api-server`，确认不再出现 `Timed out waiting for server startup`。
+3. 执行 `cargo check -p spacetime-module`，确认 proc-macro 依赖和 SpacetimeDB module 都能在 sccache wrapper 下通过。
+4. `sccache --show-stats` 显示 `Cache location oss, name: genarrative-sccache`，确认仍在使用 sccache/OSS 缓存。
+5. 重新运行 `npm run dev:rust`，确认 publish 命令带有 `--build-options="--debug"`。

src/components/platform-entry/PlatformEntryFlowShellImpl.tsx

@@ -99,7 +99,10 @@ import {
   buildPublicWorkStagePath,
   pushAppHistoryPath,
 } from '../../routing/appPageRoutes';
-import { resolveRuntimeNotFoundRecoveryAction } from '../../routing/runtimeNotFoundRecovery';
+import {
+  resolveRuntimeNotFoundRecoveryAction,
+  resolveWorkNotFoundRecoveryAction,
+} from '../../routing/runtimeNotFoundRecovery';
 import {
   ApiClientError,
   BACKGROUND_AUTH_REQUEST_OPTIONS,
@@ -907,6 +910,24 @@ function maybeAlertRuntimeNotFoundAndReturnHome() {
   return true;
 }
 
+function maybeAlertWorkNotFoundAndReturnHome() {
+  if (typeof window === 'undefined') {
+    return false;
+  }
+
+  const recoveryAction = resolveWorkNotFoundRecoveryAction(
+    window.location.pathname,
+  );
+  if (!recoveryAction) {
+    return false;
+  }
+
+  // 中文注释：直接打开公开详情或运行态深链失效时，确认提示后必须离开空详情页。
+  window.alert('作品不存在或已下架，将返回首页。');
+  pushAppHistoryPath(recoveryAction.nextPath);
+  return true;
+}
+
 function hasSeenPuzzleOnboarding() {
   if (typeof window === 'undefined') {
     return true;
@@ -4334,7 +4355,7 @@ export function PlatformEntryFlowShellImpl({
           setPublicWorkDetailError(null);
           setPlatformTab('home');
           setSelectionStage('platform');
-          if (!maybeAlertRuntimeNotFoundAndReturnHome()) {
+          if (!maybeAlertWorkNotFoundAndReturnHome()) {
             pushAppHistoryPath('/');
           }
           return false;
@@ -5836,7 +5857,7 @@ export function PlatformEntryFlowShellImpl({
           setPublicWorkDetailError(null);
           setPlatformTab('home');
           setSelectionStage('platform');
-          if (!maybeAlertRuntimeNotFoundAndReturnHome()) {
+          if (!maybeAlertWorkNotFoundAndReturnHome()) {
             pushAppHistoryPath('/');
           }
           return;
@@ -6057,7 +6078,7 @@ export function PlatformEntryFlowShellImpl({
           setPublicWorkDetailError(null);
           setPlatformTab('home');
           setSelectionStage('platform');
-          if (!maybeAlertRuntimeNotFoundAndReturnHome()) {
+          if (!maybeAlertWorkNotFoundAndReturnHome()) {
             pushAppHistoryPath('/');
           }
           return;
@@ -7387,6 +7408,23 @@ export function PlatformEntryFlowShellImpl({
         const user = await getPublicAuthUserByCode(normalizedKeyword);
         setSearchedPublicUser(user);
       } catch (error) {
+        if (selectionStage === 'work-detail') {
+          setSelectedPublicWorkDetail(null);
+          setSelectedDetailEntry(null);
+          setSelectedPuzzleDetail(null);
+          setPuzzleDetailReturnTarget(null);
+          setPuzzleRun(null);
+          setPuzzleRuntimeAuthMode('default');
+          setPuzzleError(null);
+          setPublicWorkDetailError(null);
+          setPlatformTab('home');
+          setSelectionStage('platform');
+          if (!maybeAlertWorkNotFoundAndReturnHome()) {
+            pushAppHistoryPath('/');
+          }
+          return;
+        }
+
         setPublicSearchError(
           resolveRpgCreationErrorMessage(error, '未找到对应的百梦号或作品号。'),
         );
@@ -7407,6 +7445,8 @@ export function PlatformEntryFlowShellImpl({
       refreshSquareHoleGallery,
       refreshVisualNovelGallery,
       squareHoleGalleryEntries,
+      selectionStage,
+      setPlatformTab,
       visualNovelGalleryEntries,
     ],
   );
@@ -8091,6 +8131,20 @@ export function PlatformEntryFlowShellImpl({
           </motion.div>
         )}
 
+        {selectionStage === 'work-detail' && !selectedPublicWorkDetail && (
+          <motion.div
+            key="platform-work-detail-empty"
+            initial={{ opacity: 0, y: 12 }}
+            animate={{ opacity: 1, y: 0 }}
+            exit={{ opacity: 0, y: -12 }}
+            className="flex h-full min-h-0 items-center justify-center"
+          >
+            <div className="platform-subpanel rounded-2xl px-5 py-4 text-sm text-[var(--platform-text-base)]">
+              {publicWorkDetailError || '正在读取作品详情...'}
+            </div>
+          </motion.div>
+        )}
+
         {selectionStage === 'work-detail' && selectedPublicWorkDetail && (
           <motion.div
             key="platform-work-detail"

src/components/puzzle-runtime/PuzzleRuntimeShell.test.tsx

@@ -1,7 +1,7 @@
 /* @vitest-environment jsdom */
 
 import { act, fireEvent, render, screen, within } from '@testing-library/react';
-import { expect, test, vi } from 'vitest';
+import { beforeEach, expect, test, vi } from 'vitest';
 
 import type { PuzzleRunSnapshot } from '../../../packages/shared/src/contracts/puzzleRuntimeSession';
 import { AuthUiContext } from '../auth/AuthUiContext';
@@ -31,6 +31,15 @@ const mocapMock = vi.hoisted(() => ({
   y: 0.58,
 }));
 
+const debugModeMock = vi.hoisted(() => ({
+  enabled: true,
+}));
+
+vi.mock('../../config/debugMode', () => ({
+  IS_DEBUG_MODE: debugModeMock.enabled,
+  isDebugMode: () => debugModeMock.enabled,
+}));
+
 vi.mock('../../services/useMocapInput', () => ({
   useMocapInput: () => ({
     status: 'connected',
@@ -44,6 +53,13 @@ vi.mock('../../services/useMocapInput', () => ({
   }),
 }));
 
+beforeEach(() => {
+  debugModeMock.enabled = true;
+  mocapMock.state = 'grab';
+  mocapMock.x = 0.42;
+  mocapMock.y = 0.58;
+});
+
 function createAuthValue() {
   return {
     user: null,
@@ -157,7 +173,7 @@ const clearedRun: PuzzleRunSnapshot = {
   },
 };
 
-test('拼图界面显示 mocap 连接状态和最近动作调试信息', () => {
+test('调试模式下拼图界面折叠展示 mocap 连接状态，展开后显示最近动作调试信息', () => {
   renderPuzzleRuntime(
     <PuzzleRuntimeShell
       run={{
@@ -176,12 +192,42 @@ test('拼图界面显示 mocap 连接状态和最近动作调试信息', () => {
 
   const debugPanel = screen.getByTestId('puzzle-mocap-debug');
   expect(within(debugPanel).getByText('mocap: connected')).toBeTruthy();
+  const toggleButton = within(debugPanel).getByRole('button', {
+    name: 'mocap: connected',
+  });
+  expect(toggleButton.getAttribute('aria-expanded')).toBe('false');
+  expect(within(debugPanel).queryByText('动作: grab')).toBeNull();
+
+  fireEvent.click(toggleButton);
+
+  expect(toggleButton.getAttribute('aria-expanded')).toBe('true');
   expect(within(debugPanel).getByText('动作: grab')).toBeTruthy();
   expect(within(debugPanel).getByText('手势: grab @ 0.42, 0.58')).toBeTruthy();
   expect(within(debugPanel).getByText('解析: 无')).toBeTruthy();
   expect(within(debugPanel).getByText(/原始:/)).toBeTruthy();
 });
 
+test('非调试模式下拼图界面不渲染 mocap 调试面板', () => {
+  debugModeMock.enabled = false;
+  renderPuzzleRuntime(
+    <PuzzleRuntimeShell
+      run={{
+        ...clearedRun,
+        currentLevel: {
+          ...clearedRun.currentLevel!,
+          status: 'playing',
+        },
+      }}
+      onBack={vi.fn()}
+      onSwapPieces={vi.fn()}
+      onDragPiece={vi.fn()}
+      onAdvanceNextLevel={vi.fn()}
+    />,
+  );
+
+  expect(screen.queryByTestId('puzzle-mocap-debug')).toBeNull();
+});
+
 test('拼图界面在 mocap open_palm 时显示体感光标', () => {
   mocapMock.state = 'open_palm';
   mocapMock.x = 0.42;

src/components/puzzle-runtime/PuzzleRuntimeShell.tsx

@@ -1,6 +1,8 @@
 import {
   ArrowLeft,
   ArrowRight,
+  ChevronDown,
+  ChevronUp,
   Clock,
   Eye,
   Lightbulb,
@@ -22,6 +24,7 @@ import type {
   PuzzleRuntimePropKind,
   SwapPuzzlePiecesRequest,
 } from '../../../packages/shared/src/contracts/puzzleRuntimeSession';
+import { isDebugMode } from '../../config/debugMode';
 import { useResolvedAssetReadUrl } from '../../hooks/useResolvedAssetReadUrl';
 import {
   createRuntimeDragInputController,
@@ -361,6 +364,7 @@ export function PuzzleRuntimeShell({
   const [isFreezeEffectVisible, setIsFreezeEffectVisible] = useState(false);
   const [isPropConfirming, setIsPropConfirming] = useState(false);
   const [propConfirmError, setPropConfirmError] = useState<string | null>(null);
+  const [isMocapDebugExpanded, setIsMocapDebugExpanded] = useState(false);
   const [hintDemo, setHintDemo] = useState<PuzzleHintDemoState | null>(null);
   const [mergeFlash, setMergeFlash] = useState<PuzzleMergeFlashState | null>(
     null,
@@ -462,6 +466,7 @@ export function PuzzleRuntimeShell({
     ? mocapInput.latestCommand.parseWarnings.join('；')
     : '无';
   const mocapRawPacketLabel = mocapInput.rawPacketPreview?.text ?? '未收到';
+  const shouldShowMocapDebugPanel = isDebugMode();
 
   useEffect(() => {
     currentLevelRef.current = currentLevel;
@@ -1744,19 +1749,45 @@ export function PuzzleRuntimeShell({
               已选择
             </div>
           ) : null}
-          <div
-            data-testid="puzzle-mocap-debug"
-            className="w-[min(92vw,34rem)] rounded-[0.9rem] border border-white/20 bg-slate-950/70 px-3 py-2 font-mono text-[10px] leading-4 text-white shadow-[0_12px_32px_rgba(15,23,42,0.25)] backdrop-blur"
-          >
-            <div>mocap: {mocapInput.status}</div>
-            <div>动作: {mocapActionsLabel}</div>
-            <div>手势: {mocapHandLabel}</div>
-            <div>解析: {mocapParseWarningLabel}</div>
-            <div className="max-h-20 overflow-auto break-all text-white/75">
-              原始: {mocapRawPacketLabel}
-            </div>
-            {mocapInput.error ? <div>错误: {mocapInput.error}</div> : null}
-          </div>
+          {shouldShowMocapDebugPanel ? (
+            <section
+              data-testid="puzzle-mocap-debug"
+              className="w-[min(92vw,34rem)] overflow-hidden rounded-[0.9rem] border border-white/20 bg-slate-950/70 font-mono text-[10px] leading-4 text-white shadow-[0_12px_32px_rgba(15,23,42,0.25)] backdrop-blur"
+            >
+              <button
+                type="button"
+                aria-expanded={isMocapDebugExpanded}
+                aria-controls="puzzle-mocap-debug-content"
+                onClick={() => {
+                  setIsMocapDebugExpanded((current) => !current);
+                }}
+                className="flex min-h-9 w-full items-center justify-between gap-3 px-3 py-2 text-left transition hover:bg-white/10"
+              >
+                <span className="min-w-0 truncate">
+                  mocap: {mocapInput.status}
+                </span>
+                {isMocapDebugExpanded ? (
+                  <ChevronDown className="h-3.5 w-3.5 shrink-0" />
+                ) : (
+                  <ChevronUp className="h-3.5 w-3.5 shrink-0" />
+                )}
+              </button>
+              {isMocapDebugExpanded ? (
+                <div
+                  id="puzzle-mocap-debug-content"
+                  className="border-t border-white/10 px-3 pb-2 pt-2"
+                >
+                  <div>动作: {mocapActionsLabel}</div>
+                  <div>手势: {mocapHandLabel}</div>
+                  <div>解析: {mocapParseWarningLabel}</div>
+                  <div className="max-h-20 overflow-auto break-all text-white/75">
+                    原始: {mocapRawPacketLabel}
+                  </div>
+                  {mocapInput.error ? <div>错误: {mocapInput.error}</div> : null}
+                </div>
+              ) : null}
+            </section>
+          ) : null}
           {canShowNextAction ? (
             <button
               type="button"

src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx

@@ -31,6 +31,10 @@ import type {
   CustomWorldLibraryEntry,
 } from '../../../packages/shared/src/contracts/runtime';
 import type { HydratedSavedGameSnapshot } from '../../persistence/runtimeSnapshotTypes';
+import {
+  readPublicWorkCodeFromLocationSearch,
+  resolveSelectionStageFromPath,
+} from '../../routing/appPageRoutes';
 import { ApiClientError } from '../../services/apiClient';
 import type { AuthUser } from '../../services/authService';
 import {
@@ -1423,15 +1427,17 @@ function TestWrapper({
   onSelectWorld?: RpgEntryFlowShellProps['handleCustomWorldSelect'];
 } = {}) {
   const [selectionStage, setSelectionStage] = useState<SelectionStage>(() =>
-    window.location.pathname === '/creation/rpg/agent'
-      ? 'agent-workspace'
-      : 'platform',
+    resolveSelectionStageFromPath(window.location.pathname),
+  );
+  const [initialPublicWorkCode] = useState(() =>
+    readPublicWorkCodeFromLocationSearch(window.location.search),
   );
 
   const content = (
     <RpgEntryFlowShell
       selectionStage={selectionStage}
       setSelectionStage={setSelectionStage}
+      initialPublicWorkCode={initialPublicWorkCode}
       hasSavedGame={false}
       savedSnapshot={null}
       handleContinueGame={onContinueGame ?? (() => {})}
@@ -4392,6 +4398,39 @@ test('missing puzzle public detail returns to platform home', async () => {
   expect(startPuzzleRun).toHaveBeenCalledTimes(0);
 });
 
+test('direct missing public work detail alert returns to platform home', async () => {
+  const alertSpy = vi.spyOn(window, 'alert').mockImplementation(() => {});
+
+  window.history.replaceState(
+    null,
+    '',
+    '/works/detail?work=PZ-7A7B18D9',
+  );
+  vi.mocked(listPuzzleGallery).mockResolvedValue({
+    items: [],
+  });
+
+  render(<TestWrapper withAuth />);
+
+  expect(await screen.findByText('正在读取作品详情...')).toBeTruthy();
+
+  await waitFor(() => {
+    expect(alertSpy).toHaveBeenCalledWith('作品不存在或已下架，将返回首页。');
+  });
+  await waitFor(() => {
+    expect(window.location.pathname).toBe('/');
+  });
+  expect(window.location.search).toBe('');
+  await waitFor(() => {
+    expect(getPlatformTabPanel('home').getAttribute('aria-hidden')).toBe(
+      'false',
+    );
+  });
+  expect(screen.queryByText('详情')).toBeNull();
+  expect(screen.queryByText('未找到拼图作品。')).toBeNull();
+  expect(startPuzzleRun).toHaveBeenCalledTimes(0);
+});
+
 test('public code search opens a published big fish work by BF code', async () => {
   const user = userEvent.setup();
   const bigFishWork: BigFishWorkSummary = {

src/config/debugMode.ts

@@ -0,0 +1,23 @@
+const DEBUG_MODE_TRUE_VALUES = new Set(['1', 'true', 'yes', 'on']);
+const DEBUG_MODE_FALSE_VALUES = new Set(['0', 'false', 'no', 'off']);
+
+function parseOptionalBoolean(value: string | undefined) {
+  const normalizedValue = value?.trim().toLowerCase();
+  if (!normalizedValue) {
+    return null;
+  }
+  if (DEBUG_MODE_TRUE_VALUES.has(normalizedValue)) {
+    return true;
+  }
+  if (DEBUG_MODE_FALSE_VALUES.has(normalizedValue)) {
+    return false;
+  }
+  return null;
+}
+
+export const IS_DEBUG_MODE =
+  parseOptionalBoolean(import.meta.env.VITE_DEBUG_MODE) ?? import.meta.env.DEV;
+
+export function isDebugMode() {
+  return IS_DEBUG_MODE;
+}

src/routing/runtimeNotFoundRecovery.test.ts

@@ -1,6 +1,9 @@
 import { expect, test } from 'vitest';
 
-import { resolveRuntimeNotFoundRecoveryAction } from './runtimeNotFoundRecovery';
+import {
+  resolveRuntimeNotFoundRecoveryAction,
+  resolveWorkNotFoundRecoveryAction,
+} from './runtimeNotFoundRecovery';
 
 test('runtime not found recovery returns home after direct runtime route alert', () => {
   expect(resolveRuntimeNotFoundRecoveryAction('/runtime/puzzle')).toEqual({
@@ -19,3 +22,21 @@ test('runtime not found recovery only handles direct runtime routes', () => {
   expect(resolveRuntimeNotFoundRecoveryAction('/gallery/puzzle/detail')).toBeNull();
   expect(resolveRuntimeNotFoundRecoveryAction('/creation/puzzle/result')).toBeNull();
 });
+
+test('work not found recovery returns home for direct public detail routes', () => {
+  expect(resolveWorkNotFoundRecoveryAction('/works/detail')).toEqual({
+    nextStage: 'platform',
+    nextPath: '/',
+    shouldAlert: true,
+  });
+  expect(resolveWorkNotFoundRecoveryAction('/works/detail/')).toEqual({
+    nextStage: 'platform',
+    nextPath: '/',
+    shouldAlert: true,
+  });
+  expect(resolveWorkNotFoundRecoveryAction('/gallery/puzzle/detail')).toEqual({
+    nextStage: 'platform',
+    nextPath: '/',
+    shouldAlert: true,
+  });
+});

src/routing/runtimeNotFoundRecovery.ts

@@ -28,3 +28,27 @@ export function resolveRuntimeNotFoundRecoveryAction(
 
   return null;
 }
+
+/**
+ * 中文注释：公开作品详情页和运行态深链都可能在作品被删除或下架后失效。
+ * 这类入口没有上一层可回退的详情数据，确认提示后统一回首页，避免空详情页白屏。
+ */
+export function resolveWorkNotFoundRecoveryAction(
+  pathname: string,
+): RuntimeNotFoundRecoveryAction | null {
+  const normalizedPath = pathname.trim().toLowerCase().replace(/\/+$/u, '');
+
+  if (
+    normalizedPath === '/works/detail' ||
+    normalizedPath === '/gallery/puzzle/detail' ||
+    normalizedPath === '/gallery/visual-novel/detail'
+  ) {
+    return {
+      nextStage: 'platform',
+      nextPath: '/',
+      shouldAlert: true,
+    };
+  }
+
+  return resolveRuntimeNotFoundRecoveryAction(pathname);
+}

src/vite-env.d.ts

@@ -1 +1,5 @@
 /// <reference types="vite/client" />
+
+interface ImportMetaEnv {
+  readonly VITE_DEBUG_MODE?: string;
+}