2026-05-25 22:48:40 +08:00
13 changed files with 206 additions and 83 deletions
--- a/.hermes/shared-memory/decision-log.md
+++ b/.hermes/shared-memory/decision-log.md
@@ -19,7 +19,7 @@
 ## 2026-05-25 平台首页推荐按桌面与移动断点分流

 - 背景：平台首页的推荐页在桌面与移动端之间原先共用同一套推荐运行态逻辑，容易让桌面和移动两套内容同时启动，也让首页的推荐卡与桌面发现壳互相抢状态。
- 决策：`RpgEntryHomeView` 只接受同一个 `isDesktopLayout` 断点判断；桌面端首页渲染桌面发现壳（`今日游戏`、`推荐`、`作品分类` 等），不挂移动推荐嵌入运行态；移动端 `home` 才渲染推荐卡与嵌入运行态。平台壳和首页视图都必须共用 `usePlatformDesktopLayout()`，不能在不同文件里各自判断断点。
+- 决策：`RpgEntryHomeView` 只接受同一个 `isDesktopLayout` 断点判断；桌面端首页渲染桌面发现壳（`今日游戏`、`推荐`、`作品分类` 等），不挂移动推荐嵌入运行态；移动端 `home` 才渲染推荐卡与嵌入运行态。平台壳和首页视图都必须共用 `usePlatformDesktopLayout()`，不能在不同文件里各自判断断点。推荐嵌入运行态不是登录门禁：未登录可直达匿名运行态；已登录或已有 access token 时继续使用账号 Bearer，但必须用 local auth impact 防止推荐卡 401 清空全局登录态。
 - 影响范围：`src/components/platform-entry/platformEntryResponsive.ts`、`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`src/components/rpg-entry/RpgEntryHomeView.tsx`、首页推荐相关测试与 `docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
 - 验证方式：桌面宽度下首页应只看到桌面发现壳，窄屏下首页应只看到移动推荐流；`npm run test -- src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx -t "recommend"`、`npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "home recommendation"`、`npm run typecheck`、`npm run check:encoding` 通过。
 - 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
--- a/.hermes/shared-memory/pitfalls.md
+++ b/.hermes/shared-memory/pitfalls.md
@@ -856,6 +856,7 @@
 - 现象：前端登录成功后进入推荐页，推荐页自动加载出一个作品，随后瞬间回到未登录；停留在其他页面或推荐页没加载出作品时不复现。
 - 原因：推荐页 embedded 运行态会自动发起受保护写请求。若这些卡片级后台请求遇到 `401` 或 refresh 失败，默认请求层曾清空 access token 并广播全局 auth 事件，导致 `AuthGate` 重新 hydrate 成未登录态。更隐蔽的是，`refreshAccessToken()` 自身曾在 refresh 失败时静默清 token，即便调用方关闭了 `clearAuthOnUnauthorized`，也可能让后续 hydrate 变成未登录。
 - 处理：请求层统一使用 `authImpact: 'global' | 'local'` 区分账号权威请求与局部后台请求；推荐页自动运行态、图片换签、公开拼图运行态和平台 bootstrap 私有投影刷新统一使用 `BACKGROUND_AUTH_REQUEST_OPTIONS` / `RUNTIME_BACKGROUND_AUTH_OPTIONS`，并等 `canReadProtectedData` 为 true 后再启动；用户主动点击的账号动作仍保留默认全局鉴权失败处理。
+- 追加处理：推荐页嵌入运行态要按真实身份分流，已登录或已有 access token 时继续走账号 Bearer + local auth impact，不能误带 runtime guest token；只有匿名访客才申请并透传 runtime guest token。
 - 追加处理：generated 私有图片换签 `/api/assets/read-url` 也属于展示层后台请求；推荐页拼图运行态挂载后会立即解析封面图，若换签 401 触发全局鉴权事件，也会表现成“进入拼图作品后瞬间未登录”。资源换签失败只应让当前图片为空，不应清 token、广播 auth 事件或主动 refresh。
 - 追加处理：从推荐页点进公开拼图作品并启动完整运行态后，`startPuzzleRun`、通关自动 `submitPuzzleLeaderboard`、下一关 `advancePuzzleNextLevel` 和重开同样属于当前玩法局部同步；这些请求失败时只应留在拼图错误态，不应清 token 或广播 auth 事件。
 - 追加处理：通关后 `refreshSaveArchives()`、首屏 bootstrap 的个人看板/作品架/浏览历史读写也只是平台投影刷新，失败应显示局部错误，不能充当全局登录态判定。
@@ -872,9 +873,9 @@

 ## 推荐页未登录入口误打开公开详情

- 现象：新用户默认在发现页，但点击推荐页或推荐封面后，如果复用公开作品详情入口，可能绕过推荐页“登录后游玩”的产品门禁。
+- 现象：新用户默认在发现页，但点击推荐页或推荐封面后，如果复用公开作品详情入口，可能绕过推荐页沉浸运行态，打开普通公开详情页。
 - 原因：`RpgEntryHomeView` 曾只有 `onOpenGalleryDetail` 一个回调，同时服务发现页公开详情和推荐页作品入口；一旦为发现页保留公开浏览能力，推荐页也会跟着打开详情。
- 处理：公开详情与推荐页入口分离为 `onOpenGalleryDetail` 和 `onOpenRecommendGalleryDetail`。发现页、搜索和排行榜保留公开详情；推荐 Tab、推荐封面、推荐运行态错误重试和桌面推荐模块统一走登录门禁。未登录推荐页只显示封面，点击封面只弹登录窗，不携带登录后自动打开详情的回调。
+- 处理：公开详情与推荐页入口分离为 `onOpenGalleryDetail` 和 `onOpenRecommendGalleryDetail`。发现页、搜索和排行榜保留公开详情；推荐 Tab、推荐封面、推荐运行态错误重试和桌面推荐模块走推荐运行态入口，不再主动弹登录窗。登录门禁只保留给创作、个人作品、删除、发布、Remix 等账号或所有权动作。
 - 验证：`npm run test -- src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx -t "logged out recommend"`。
 - 关联：`src/components/rpg-entry/RpgEntryHomeView.tsx`、`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`docs/technical/AUTH_RESTORE_AND_RECOMMEND_LOADING_FIX_2026-05-09.md`。

--- a/docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md
+++ b/docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md
@@ -98,6 +98,8 @@ npm run check:server-rs-ddd

 该拆分只改变 `api-server` 文件组织，不改变 `/api/runtime/puzzle/*` route、DTO、error envelope、SpacetimeDB schema、公开 gallery cache 语义或计费语义；后续继续细分时也必须先保持行为不变，再单独讨论领域规则下沉。

+`/api/runtime/puzzle/runs*` 当前接受 `RuntimePrincipal`，可同时识别登录用户 Bearer 和 runtime guest token。推荐页嵌入运行态的正式开局、交换、拖拽、下一关、暂停、道具与排行榜请求，应由前端在登录态下继续携带账号 access token；匿名游客仅在确认为未登录时走 runtime guest token。不要再把拼图 runtime 当成只认普通 Bearer 的纯账号接口。
+
 抓大鹅 Match3D `api-server` 内部拆分：

 - `server-rs/crates/api-server/src/modules/match3d.rs` 继续负责路由装配和 body limit；对外 handler 名称保持不变。
--- a/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md
+++ b/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md
@@ -155,7 +155,7 @@ Codex 项目级 hook 已放在 `.codex/config.toml` 与 `.codex/hooks/`：

 ```bash
 cargo check -p api-server --manifest-path server-rs/Cargo.toml
-npm run test -- src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx -t "logged out recommend page can enter runtime without login gate|logged out desktop recommend page renders runtime directly without login gate"
+npm run test -- src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx -t "logged out recommend tab enters runtime without login modal|logged out desktop recommend page renders runtime directly|logged out desktop recommend rail enters runtime without login modal"
 ```

 涉及 SpacetimeDB schema 时必须补：
--- a/docs/【玩法创作】平台入口与玩法链路-2026-05-15.md
+++ b/docs/【玩法创作】平台入口与玩法链路-2026-05-15.md
@@ -96,6 +96,7 @@ RPG / 拼图等运行态存档选择入口统一在个人中心 `次级入口 >
 - 结果页单关测试只能把完整草稿持久化，并通过 `levelId` 指定运行态起始关卡；不得把单关快照作为整份草稿调用 `updatePuzzleWork`，否则 source session 和作品 profile 的 `levels` 会被覆盖成单关，退出重进后其它关卡会丢失。
 - 结果页生成关卡图时若关卡名为空，前端必须传 `shouldAutoNameLevel=true`，后端复用首关命名契约先按画面描述生成关卡名，再在图片生成后用视觉命名结果精修，并把生成名和 UI 背景提示词随本次关卡快照写回。
 - 拼图运行态背景优先读取当前关卡 `levelBackgroundImageSrc/levelBackgroundImageObjectKey`，旧数据才兼容 `uiBackgroundImageSrc/uiBackgroundImageObjectKey`；本地试玩、直达指定关卡和正式 `next-level` 推进时，目标关卡缺关卡背景时必须继承同作品首个可用关卡背景，仍缺失时才沿用当前运行态快照背景或默认 UI。运行态按钮视觉优先读取当前关卡 `uiSpritesheetImageSrc/uiSpritesheetImageObjectKey`，先按透明 alpha 自动边界检测识别 spritesheet 中的独立按钮展示矩形，再按原图位置从左到右、从上到下映射到返回、设置、下一关、提示、原图、冻结；同一组件还要按较高 alpha 阈值派生紧致点击热区，透明留白和柔边低 alpha 区域尽量不响应点击。检测失败时回退旧固定六格裁切，缺失时才用现有图标按钮兜底。有 spritesheet 时，返回和设置按钮的点击容器只提供透明点击区，不再叠加默认白色圆形底；底部提示、原图、冻结三枚素材按检测矩形的原始宽高比显示，不能强行拉伸成正圆或铺满整列。底部道具区不再使用连片胶囊背景，提示、原图、冻结三个按钮均匀分布；运行态只展示按钮素材本身，不额外叠加“提示 / 原图 / 冻结”文字。
+- 推荐页本身不是登录门禁入口，未登录用户点击底部或侧边栏的推荐 Tab 应直接进入嵌入运行态，不主动打开登录弹窗。推荐页嵌入运行态必须按真实身份分流：已登录用户或本地已有 access token 时，启动拼图和后续排行榜 / 下一关等正式请求继续走账号 Bearer；只有确认为匿名访客时才申请并透传 runtime guest token。`/api/runtime/puzzle/runs*` 后端统一接受 `RuntimePrincipal`，可识别账号用户和匿名 runtime guest；推荐卡片的后台读写请求仍使用 local auth impact，避免单卡 401 清空整站登录态。创作、个人作品、删除、发布、Remix 等账号或所有权动作仍保持普通用户鉴权。
 - 拼图运行态棋盘不叠加分块蒙版、描边、阴影、选中底色或合并块 SVG 轮廓；拼图片本体需要裁切为圆角形状，单块使用独立圆角裁切，合并块使用 SVG 原生 `clipPath` 裁切整体外轮廓，外凸角和内凹角分别计算半径，内凹角半径要比外凸角更明显以避免手机 WebView 中看起来仍是直角。原图道具只在用户主动确认后打开独立原图查看层，不在当前拼图棋盘上叠加原图。
 - 拼图运行态拖拽必须完全跟随手指或鼠标位置，`pointermove` 期间即时写入可见拼块的 transform，不依赖等待后端回包、React 重渲染或下一帧动画队列；进入拖动后不展示拼块选中态或“已选择”提示，松手后再提交目标格同步规则真相。
 - 拼图运行态的提示、设置等点击弹层跟随当前运行态主色主题，使用普通圆角主题面板，不复用像素九宫格素材框。
@@ -132,7 +133,7 @@ RPG / 拼图等运行态存档选择入口统一在个人中心 `次级入口 >

 删除等破坏性动作当前未接入 jump-hop 删除 API；如果后续要在作品架提供删除入口，必须先补齐后端/SpacetimeDB/前端整条删除链路，再开放按钮。

-推荐页匿名游玩不再限定为跳一跳。移动端一级 `推荐` Tab 是内嵌运行态刷卡流，会自动选择推荐作品并启动对应玩法；桌面端首页不启动这套移动推荐运行态，而是渲染桌面发现壳，展示 `今日游戏`、`推荐`、`作品分类` 等桌面内容。断点事实统一走 `platformEntryResponsive.ts` 的 `usePlatformDesktopLayout()`，平台壳和首页视图必须共用同一个判断，避免桌面发现页与移动推荐页同时挂载、重复触发请求或启动运行态。推荐页嵌入运行态启动时统一先申请短期 Runtime Guest Token，并只把它作为局部请求头传给运行态客户端，不写入全局登录态、不触发 refresh，也不把匿名流量伪装成普通用户。当前覆盖矩阵为：跳一跳、视觉小说、抓大鹅 Match3D、方洞挑战、拼图、敲木鱼、大鱼吃小鱼、汪汪声浪。每个模板的启动请求、推荐页内后续运行态动作以及需要上报的 play/finish/leaderboard/next-level 类请求，都必须继续透传 runtime guest token；公开读取入口仍可匿名读取，创作、个人作品、删除、发布、Remix 等账号/所有权动作仍保持普通用户鉴权。
+推荐页匿名游玩不再限定为跳一跳。移动端一级 `推荐` Tab 是内嵌运行态刷卡流，会自动选择推荐作品并启动对应玩法；桌面端首页不启动这套移动推荐运行态，而是渲染桌面发现壳，展示 `今日游戏`、`推荐`、`作品分类` 等桌面内容。断点事实统一走 `platformEntryResponsive.ts` 的 `usePlatformDesktopLayout()`，平台壳和首页视图必须共用同一个判断，避免桌面发现页与移动推荐页同时挂载、重复触发请求或启动运行态。推荐页嵌入运行态启动时按真实身份分流：已登录用户或本地已有 access token 时继续使用账号 Bearer，但请求选项必须是 local auth impact，避免单卡 401 清空整站登录态；只有确认为匿名访客时才申请短期 Runtime Guest Token，并只把它作为局部请求头传给运行态客户端，不写入全局登录态、不触发 refresh，也不把匿名流量伪装成普通用户。当前覆盖矩阵为：跳一跳、视觉小说、抓大鹅 Match3D、方洞挑战、拼图、敲木鱼、大鱼吃小鱼、汪汪声浪。每个模板的启动请求、推荐页内后续运行态动作以及需要上报的 play/finish/leaderboard/next-level 类请求，都必须继续按该身份分流；公开读取入口仍可匿名读取，创作、个人作品、删除、发布、Remix 等账号/所有权动作仍保持普通用户鉴权。

 ## 敲木鱼

--- a/server-rs/crates/api-server/src/modules/puzzle.rs
+++ b/server-rs/crates/api-server/src/modules/puzzle.rs
@@ -6,7 +6,7 @@ use axum::{
 };

 use crate::{
-    auth::require_bearer_auth,
+    auth::{require_bearer_auth, require_runtime_principal_auth},
    puzzle::{
        advance_puzzle_next_level, claim_puzzle_work_point_incentive, create_puzzle_agent_session,
        delete_puzzle_work, drag_puzzle_piece_or_group, execute_puzzle_agent_action,
@@ -130,56 +130,56 @@ pub fn router(state: AppState) -> Router<AppState> {
            "/api/runtime/puzzle/runs",
            post(start_puzzle_run).route_layer(middleware::from_fn_with_state(
                state.clone(),
-                require_bearer_auth,
+                require_runtime_principal_auth,
            )),
        )
        .route(
            "/api/runtime/puzzle/runs/{run_id}",
            get(get_puzzle_run).route_layer(middleware::from_fn_with_state(
                state.clone(),
-                require_bearer_auth,
+                require_runtime_principal_auth,
            )),
        )
        .route(
            "/api/runtime/puzzle/runs/{run_id}/swap",
            post(swap_puzzle_pieces).route_layer(middleware::from_fn_with_state(
                state.clone(),
-                require_bearer_auth,
+                require_runtime_principal_auth,
            )),
        )
        .route(
            "/api/runtime/puzzle/runs/{run_id}/drag",
            post(drag_puzzle_piece_or_group).route_layer(middleware::from_fn_with_state(
                state.clone(),
-                require_bearer_auth,
+                require_runtime_principal_auth,
            )),
        )
        .route(
            "/api/runtime/puzzle/runs/{run_id}/next-level",
            post(advance_puzzle_next_level).route_layer(middleware::from_fn_with_state(
                state.clone(),
-                require_bearer_auth,
+                require_runtime_principal_auth,
            )),
        )
        .route(
            "/api/runtime/puzzle/runs/{run_id}/pause",
            post(update_puzzle_run_pause).route_layer(middleware::from_fn_with_state(
                state.clone(),
-                require_bearer_auth,
+                require_runtime_principal_auth,
            )),
        )
        .route(
            "/api/runtime/puzzle/runs/{run_id}/props",
            post(use_puzzle_runtime_prop).route_layer(middleware::from_fn_with_state(
                state.clone(),
-                require_bearer_auth,
+                require_runtime_principal_auth,
            )),
        )
        .route(
            "/api/runtime/puzzle/runs/{run_id}/leaderboard",
            post(submit_puzzle_leaderboard).route_layer(middleware::from_fn_with_state(
                state.clone(),
-                require_bearer_auth,
+                require_runtime_principal_auth,
            )),
        )
        .with_state(PuzzleApiState::from_ref(&state))
--- a/server-rs/crates/api-server/src/puzzle.rs
+++ b/server-rs/crates/api-server/src/puzzle.rs
@@ -76,7 +76,7 @@ use crate::{
        execute_billable_asset_operation, execute_billable_asset_operation_with_cost,
        should_skip_asset_operation_billing_for_connectivity,
    },
-    auth::AuthenticatedAccessToken,
+    auth::{AuthenticatedAccessToken, RuntimePrincipal},
    generated_asset_sheets::apply_generated_asset_sheet_green_screen_alpha,
    http_error::AppError,
    llm_model_routing::{CREATION_TEMPLATE_LLM_MODEL, PUZZLE_LEVEL_NAME_VISION_LLM_MODEL},
--- a/server-rs/crates/api-server/src/puzzle/handlers.rs
+++ b/server-rs/crates/api-server/src/puzzle/handlers.rs
@@ -1666,7 +1666,7 @@ pub async fn remix_puzzle_gallery_work(
 pub async fn start_puzzle_run(
    State(state): State<PuzzleApiState>,
    Extension(request_context): Extension<RequestContext>,
-    Extension(authenticated): Extension<AuthenticatedAccessToken>,
+    Extension(principal): Extension<RuntimePrincipal>,
    payload: Result<Json<StartPuzzleRunRequest>, JsonRejection>,
 ) -> Result<Json<Value>, Response> {
    let Json(payload) = payload.map_err(|error| {
@@ -1690,7 +1690,7 @@ pub async fn start_puzzle_run(
        .spacetime_client()
        .start_puzzle_run(PuzzleRunStartRecordInput {
            run_id: build_prefixed_uuid_id("puzzle-run-"),
-            owner_user_id: authenticated.claims().user_id().to_string(),
+            owner_user_id: principal.subject().to_string(),
            profile_id: payload.profile_id.clone(),
            level_id: payload.level_id.clone(),
            started_at_micros: current_utc_micros(),
@@ -1707,16 +1707,18 @@ pub async fn start_puzzle_run(
    record_puzzle_work_play_start_after_success(
        &state,
        &request_context,
-        WorkPlayTrackingDraft::new(
+        WorkPlayTrackingDraft::runtime_principal(
            "puzzle",
            payload.profile_id.clone(),
-            &authenticated,
+            &principal,
            "/api/runtime/puzzle/...",
        )
        .profile_id(payload.profile_id.clone())
+        .owner_user_id(principal.subject().to_string())
        .extra(json!({
            "levelId": payload.level_id,
            "runId": run.run_id,
+            "principalKind": principal.kind().as_str(),
        })),
    )
    .await;
@@ -1733,13 +1735,13 @@ pub async fn get_puzzle_run(
    State(state): State<PuzzleApiState>,
    AxumPath(run_id): AxumPath<String>,
    Extension(request_context): Extension<RequestContext>,
-    Extension(authenticated): Extension<AuthenticatedAccessToken>,
+    Extension(principal): Extension<RuntimePrincipal>,
 ) -> Result<Json<Value>, Response> {
    ensure_non_empty(&request_context, PUZZLE_RUNTIME_PROVIDER, &run_id, "runId")?;

    let run = state
        .spacetime_client()
-        .get_puzzle_run(run_id, authenticated.claims().user_id().to_string())
+        .get_puzzle_run(run_id, principal.subject().to_string())
        .await
        .map_err(|error| {
            puzzle_error_response(
@@ -1761,7 +1763,7 @@ pub async fn swap_puzzle_pieces(
    State(state): State<PuzzleApiState>,
    AxumPath(run_id): AxumPath<String>,
    Extension(request_context): Extension<RequestContext>,
-    Extension(authenticated): Extension<AuthenticatedAccessToken>,
+    Extension(principal): Extension<RuntimePrincipal>,
    payload: Result<Json<SwapPuzzlePiecesRequest>, JsonRejection>,
 ) -> Result<Json<Value>, Response> {
    let Json(payload) = payload.map_err(|error| {
@@ -1792,7 +1794,7 @@ pub async fn swap_puzzle_pieces(
        .spacetime_client()
        .swap_puzzle_pieces(PuzzleRunSwapRecordInput {
            run_id,
-            owner_user_id: authenticated.claims().user_id().to_string(),
+            owner_user_id: principal.subject().to_string(),
            first_piece_id: payload.first_piece_id,
            second_piece_id: payload.second_piece_id,
            swapped_at_micros: current_utc_micros(),
@@ -1818,7 +1820,7 @@ pub async fn drag_puzzle_piece_or_group(
    State(state): State<PuzzleApiState>,
    AxumPath(run_id): AxumPath<String>,
    Extension(request_context): Extension<RequestContext>,
-    Extension(authenticated): Extension<AuthenticatedAccessToken>,
+    Extension(principal): Extension<RuntimePrincipal>,
    payload: Result<Json<DragPuzzlePieceRequest>, JsonRejection>,
 ) -> Result<Json<Value>, Response> {
    let Json(payload) = payload.map_err(|error| {
@@ -1843,7 +1845,7 @@ pub async fn drag_puzzle_piece_or_group(
        .spacetime_client()
        .drag_puzzle_piece_or_group(PuzzleRunDragRecordInput {
            run_id,
-            owner_user_id: authenticated.claims().user_id().to_string(),
+            owner_user_id: principal.subject().to_string(),
            piece_id: payload.piece_id,
            target_row: payload.target_row,
            target_col: payload.target_col,
@@ -1870,7 +1872,7 @@ pub async fn advance_puzzle_next_level(
    State(state): State<PuzzleApiState>,
    AxumPath(run_id): AxumPath<String>,
    Extension(request_context): Extension<RequestContext>,
-    Extension(authenticated): Extension<AuthenticatedAccessToken>,
+    Extension(principal): Extension<RuntimePrincipal>,
    payload: Result<Json<AdvancePuzzleNextLevelRequest>, JsonRejection>,
 ) -> Result<Json<Value>, Response> {
    ensure_non_empty(&request_context, PUZZLE_RUNTIME_PROVIDER, &run_id, "runId")?;
@@ -1897,7 +1899,7 @@ pub async fn advance_puzzle_next_level(
        .spacetime_client()
        .advance_puzzle_next_level(spacetime_client::PuzzleRunNextLevelRecordInput {
            run_id,
-            owner_user_id: authenticated.claims().user_id().to_string(),
+            owner_user_id: principal.subject().to_string(),
            target_profile_id: payload.target_profile_id,
            advanced_at_micros: current_utc_micros(),
        })
@@ -1922,7 +1924,7 @@ pub async fn update_puzzle_run_pause(
    State(state): State<PuzzleApiState>,
    AxumPath(run_id): AxumPath<String>,
    Extension(request_context): Extension<RequestContext>,
-    Extension(authenticated): Extension<AuthenticatedAccessToken>,
+    Extension(principal): Extension<RuntimePrincipal>,
    payload: Result<Json<UpdatePuzzleRuntimePauseRequest>, JsonRejection>,
 ) -> Result<Json<Value>, Response> {
    let Json(payload) = payload.map_err(|error| {
@@ -1941,7 +1943,7 @@ pub async fn update_puzzle_run_pause(
        .spacetime_client()
        .update_puzzle_run_pause(PuzzleRunPauseRecordInput {
            run_id,
-            owner_user_id: authenticated.claims().user_id().to_string(),
+            owner_user_id: principal.subject().to_string(),
            paused: payload.paused,
            updated_at_micros: current_utc_micros(),
        })
@@ -1966,7 +1968,7 @@ pub async fn use_puzzle_runtime_prop(
    State(state): State<PuzzleApiState>,
    AxumPath(run_id): AxumPath<String>,
    Extension(request_context): Extension<RequestContext>,
-    Extension(authenticated): Extension<AuthenticatedAccessToken>,
+    Extension(principal): Extension<RuntimePrincipal>,
    payload: Result<Json<UsePuzzleRuntimePropRequest>, JsonRejection>,
 ) -> Result<Json<Value>, Response> {
    let Json(payload) = payload.map_err(|error| {
@@ -1987,7 +1989,7 @@ pub async fn use_puzzle_runtime_prop(
        "propKind",
    )?;

-    let owner_user_id = authenticated.claims().user_id().to_string();
+    let owner_user_id = principal.subject().to_string();
    let prop_kind = payload.prop_kind.trim().to_string();
    let billing_asset_kind = match prop_kind.as_str() {
        "hint" => "puzzle_prop_hint",
@@ -2064,7 +2066,7 @@ pub async fn submit_puzzle_leaderboard(
    State(state): State<PuzzleApiState>,
    AxumPath(run_id): AxumPath<String>,
    Extension(request_context): Extension<RequestContext>,
-    Extension(authenticated): Extension<AuthenticatedAccessToken>,
+    Extension(principal): Extension<RuntimePrincipal>,
    payload: Result<Json<SubmitPuzzleLeaderboardRequest>, JsonRejection>,
 ) -> Result<Json<Value>, Response> {
    let Json(payload) = payload.map_err(|error| {
@@ -2084,7 +2086,7 @@ pub async fn submit_puzzle_leaderboard(
        .spacetime_client()
        .submit_puzzle_leaderboard_entry(PuzzleLeaderboardSubmitRecordInput {
            run_id,
-            owner_user_id: authenticated.claims().user_id().to_string(),
+            owner_user_id: principal.subject().to_string(),
            profile_id: payload.profile_id,
            grid_size: payload.grid_size,
            elapsed_ms: payload.elapsed_ms.max(1_000),
--- a/src/components/platform-entry/PlatformEntryFlowShellImpl.tsx
+++ b/src/components/platform-entry/PlatformEntryFlowShellImpl.tsx
@@ -115,6 +115,7 @@ import { resolveWorkNotFoundRecoveryAction } from '../../routing/runtimeNotFound
 import {
  ApiClientError,
  BACKGROUND_AUTH_REQUEST_OPTIONS,
+  getStoredAccessToken,
 } from '../../services/apiClient';
 import {
  ensureRuntimeGuestToken,
@@ -553,6 +554,8 @@ const AGENT_RESULT_STRUCTURAL_BLOCKER_CODES = new Set([
 ]);
 const RECOMMEND_RUNTIME_BACKGROUND_AUTH_OPTIONS =
  BACKGROUND_AUTH_REQUEST_OPTIONS;
+const RECOMMEND_PUZZLE_BACKGROUND_AUTH_OPTIONS =
+  RECOMMEND_RUNTIME_BACKGROUND_AUTH_OPTIONS;
 async function buildRecommendRuntimeGuestOptions() {
  const { token } = await ensureRuntimeGuestToken();
  return {
@@ -560,6 +563,25 @@ async function buildRecommendRuntimeGuestOptions() {
    runtimeGuestToken: token,
  };
 }
+function shouldUseRecommendRuntimeGuestAuth(
+  authUi: { user?: { id?: string } | null } | null | undefined,
+) {
+  return !authUi?.user?.id?.trim() && !getStoredAccessToken();
+}
+async function buildRecommendRuntimeAuthOptions(
+  authUi: { user?: { id?: string } | null } | null | undefined,
+  embedded?: boolean,
+) {
+  if (!embedded) {
+    return {};
+  }
+
+  if (shouldUseRecommendRuntimeGuestAuth(authUi)) {
+    return buildRecommendRuntimeGuestOptions();
+  }
+
+  return RECOMMEND_RUNTIME_BACKGROUND_AUTH_OPTIONS;
+}
 const PUZZLE_DRAFT_GENERATION_POINT_COST = 2;
 const MATCH3D_DRAFT_GENERATION_POINT_COST = 10;
 const BARK_BATTLE_DRAFT_GENERATION_POINT_COST = 3;
@@ -7390,9 +7412,10 @@ export function PlatformEntryFlowShellImpl({
          profileId: targetProfileId,
          mode: 'play' as const,
        };
-        const runtimeGuestOptions = options.embedded
-          ? await buildRecommendRuntimeGuestOptions()
-          : {};
+        const runtimeGuestOptions = await buildRecommendRuntimeAuthOptions(
+          authUi,
+          options.embedded,
+        );
        const { run } = options.embedded
          ? await startVisualNovelRun(
              targetProfileId,
@@ -7423,6 +7446,7 @@ export function PlatformEntryFlowShellImpl({
      }
    },
    [
+      authUi,
      resolvePuzzleErrorMessage,
      setIsVisualNovelBusy,
      setSelectionStage,
@@ -7446,7 +7470,7 @@ export function PlatformEntryFlowShellImpl({
      try {
        const runtimeGuestOptions =
          activeRecommendRuntimeKind === 'visual-novel'
-            ? await buildRecommendRuntimeGuestOptions()
+            ? await buildRecommendRuntimeAuthOptions(authUi, true)
            : {};
        const nextRun = await streamVisualNovelRuntimeAction(
          visualNovelRun.runId,
@@ -7464,6 +7488,7 @@ export function PlatformEntryFlowShellImpl({
    },
    [
      activeRecommendRuntimeKind,
+      authUi,
      isVisualNovelBusy,
      resolvePuzzleErrorMessage,
      setIsVisualNovelBusy,
@@ -7872,9 +7897,10 @@ export function PlatformEntryFlowShellImpl({
      setJumpHopError(null);
      setJumpHopRuntimeReturnStage(options.returnStage ?? 'work-detail');
      try {
-        const runtimeGuestOptions = options.embedded
-          ? await buildRecommendRuntimeGuestOptions()
-          : {};
+        const runtimeGuestOptions = await buildRecommendRuntimeAuthOptions(
+          authUi,
+          options.embedded,
+        );
        const [detail, runResponse] = await Promise.all([
          jumpHopClient.getWorkDetail(normalizedProfileId).catch(() => null),
          jumpHopClient.startRun(normalizedProfileId, runtimeGuestOptions),
@@ -7902,7 +7928,7 @@ export function PlatformEntryFlowShellImpl({
        setIsJumpHopBusy(false);
      }
    },
-    [setSelectionStage],
+    [authUi, setSelectionStage],
  );

  const restartJumpHopRuntimeRun = useCallback(async () => {
@@ -8209,9 +8235,10 @@ export function PlatformEntryFlowShellImpl({
      setWoodenFishError(null);
      setWoodenFishRuntimeReturnStage(options.returnStage ?? 'work-detail');
      try {
-        const runtimeGuestOptions = options.embedded
-          ? await buildRecommendRuntimeGuestOptions()
-          : {};
+        const runtimeGuestOptions = await buildRecommendRuntimeAuthOptions(
+          authUi,
+          options.embedded,
+        );
        const [detail, runResponse] = await Promise.all([
          woodenFishClient.getWorkDetail(normalizedProfileId).catch(() => null),
          options.embedded
@@ -8241,7 +8268,7 @@ export function PlatformEntryFlowShellImpl({
        setIsWoodenFishBusy(false);
      }
    },
-    [setSelectionStage],
+    [authUi, setSelectionStage],
  );

  const checkpointWoodenFishRuntimeRun = useCallback(
@@ -8644,16 +8671,23 @@ export function PlatformEntryFlowShellImpl({
          profileId: item.profileId,
          levelId: levelId ?? null,
        };
-        const runtimeGuestOptions = options.embedded
+        const canUseRuntimeGuestAuth =
+          options.embedded || options.authMode === 'isolated';
+        const useRuntimeGuestAuth =
+          canUseRuntimeGuestAuth && shouldUseRecommendRuntimeGuestAuth(authUi);
+        const runtimeGuestOptions = useRuntimeGuestAuth
          ? await buildRecommendRuntimeGuestOptions()
          : {};
-        const authMode = options.embedded
-          ? 'isolated'
-          : (options.authMode ?? 'default');
+        const authMode = useRuntimeGuestAuth ? 'isolated' : 'default';
+        const runtimeAuthOptions = useRuntimeGuestAuth
+          ? runtimeGuestOptions
+          : canUseRuntimeGuestAuth
+            ? RECOMMEND_PUZZLE_BACKGROUND_AUTH_OPTIONS
+            : {};
        const { run } =
          authMode === 'isolated'
            ? await startPuzzleRun(startRunPayload, runtimeGuestOptions)
-            : await startPuzzleRun(startRunPayload);
+            : await startPuzzleRun(startRunPayload, runtimeAuthOptions);
        setSelectedPuzzleDetail(item);
        setPuzzleRun(run);
        setPuzzleRuntimeAuthMode(authMode);
@@ -8696,6 +8730,7 @@ export function PlatformEntryFlowShellImpl({
    },
    [
      isPuzzleBusy,
+      authUi,
      resolvePuzzleErrorMessage,
      setIsPuzzleBusy,
      setPuzzleError,
@@ -8748,9 +8783,10 @@ export function PlatformEntryFlowShellImpl({
          runtimeProfile.generatedBackgroundAsset,
          { expireSeconds: 300 },
        );
-        const runtimeGuestOptions = options.embedded
-          ? await buildRecommendRuntimeGuestOptions()
-          : {};
+        const runtimeGuestOptions = await buildRecommendRuntimeAuthOptions(
+          authUi,
+          options.embedded,
+        );
        const runtimeOptions = {
          ...runtimeGuestOptions,
          ...(typeof options.itemTypeCountOverride === 'number'
@@ -8797,6 +8833,7 @@ export function PlatformEntryFlowShellImpl({
    },
    [
      isMatch3DBusy,
+      authUi,
      match3dFlow,
      match3dRuntimeAdapter,
      resolveMatch3DErrorMessage,
@@ -8820,9 +8857,10 @@ export function PlatformEntryFlowShellImpl({
      setSquareHoleError(null);

      try {
-        const runtimeGuestOptions = options.embedded
-          ? await buildRecommendRuntimeGuestOptions()
-          : {};
+        const runtimeGuestOptions = await buildRecommendRuntimeAuthOptions(
+          authUi,
+          options.embedded,
+        );
        const { run } = options.embedded
          ? await startSquareHoleRun(profile.profileId, runtimeGuestOptions)
          : await startSquareHoleRun(profile.profileId);
@@ -8856,6 +8894,7 @@ export function PlatformEntryFlowShellImpl({
    },
    [
      isSquareHoleBusy,
+      authUi,
      resolveSquareHoleErrorMessage,
      setSelectionStage,
      setSquareHoleError,
@@ -8978,7 +9017,7 @@ export function PlatformEntryFlowShellImpl({
      try {
        const runtimeGuestOptions =
          activeRecommendRuntimeKind === 'big-fish'
-            ? await buildRecommendRuntimeGuestOptions()
+            ? await buildRecommendRuntimeAuthOptions(authUi, true)
            : {};
        const { run } = await submitBigFishRuntimeInput(
          bigFishRun.runId,
@@ -8996,6 +9035,7 @@ export function PlatformEntryFlowShellImpl({
    },
    [
      activeRecommendRuntimeKind,
+      authUi,
      bigFishRun,
      resolveBigFishErrorMessage,
      setBigFishError,
@@ -9012,10 +9052,9 @@ export function PlatformEntryFlowShellImpl({
    setBigFishRuntimeStartedAt(null);
    const reportPromise =
      activeRecommendRuntimeKind === 'big-fish'
-        ? recordBigFishPlay(
-            sessionId,
-            { elapsedMs },
-            RECOMMEND_RUNTIME_BACKGROUND_AUTH_OPTIONS,
+        ? buildRecommendRuntimeAuthOptions(authUi, true).then(
+            (runtimeAuthOptions) =>
+              recordBigFishPlay(sessionId, { elapsedMs }, runtimeAuthOptions),
          )
        : recordBigFishPlay(sessionId, { elapsedMs });
    void reportPromise.catch((error) => {
@@ -9025,6 +9064,7 @@ export function PlatformEntryFlowShellImpl({
    });
  }, [
    activeRecommendRuntimeKind,
+    authUi,
    bigFishRun?.sessionId,
    bigFishRuntimeStartedAt,
    resolveBigFishErrorMessage,
@@ -11319,9 +11359,10 @@ export function PlatformEntryFlowShellImpl({
      setBigFishRuntimeReturnStage(returnStage);
      setBigFishRun(null);
      try {
-        const runtimeGuestOptions = options.embedded
-          ? await buildRecommendRuntimeGuestOptions()
-          : {};
+        const runtimeGuestOptions = await buildRecommendRuntimeAuthOptions(
+          authUi,
+          options.embedded,
+        );
        const { run } = options.embedded
          ? await startBigFishRuntimeRun(sessionId, runtimeGuestOptions)
          : await startBigFishRuntimeRun(sessionId);
@@ -11349,7 +11390,7 @@ export function PlatformEntryFlowShellImpl({
        return false;
      }
    },
-    [bigFishFlow, resolveBigFishErrorMessage, setBigFishError, setSelectionStage],
+    [authUi, bigFishFlow, resolveBigFishErrorMessage, setBigFishError, setSelectionStage],
  );

  const startBarkBattleRunFromWork = useCallback(
@@ -11369,9 +11410,10 @@ export function PlatformEntryFlowShellImpl({
      setBarkBattlePublishedConfig(mapBarkBattleWorkToPublishedConfig(item));
      setBarkBattleRuntimeReturnStage(returnStage);
      try {
-        const runtimeGuestOptions = options.embedded
-          ? await buildRecommendRuntimeGuestOptions()
-          : {};
+        const runtimeGuestOptions = await buildRecommendRuntimeAuthOptions(
+          authUi,
+          options.embedded,
+        );
        const runResponse = options.embedded
          ? await startBarkBattleRun(item.workId, {}, runtimeGuestOptions)
          : await startBarkBattleRun(item.workId);
@@ -11394,7 +11436,7 @@ export function PlatformEntryFlowShellImpl({
        return false;
      }
    },
-    [resolveBarkBattleErrorMessage, setSelectionStage],
+    [authUi, resolveBarkBattleErrorMessage, setSelectionStage],
  );

  const startSelectedPublicWork = useCallback(() => {
--- a/src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx
+++ b/src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx
@@ -310,6 +310,7 @@ const RECOMMEND_RUNTIME_AUTH_OPTIONS = {
  ...ISOLATED_RUNTIME_AUTH_OPTIONS,
  runtimeGuestToken: 'runtime-guest-token',
 };
+const LOGGED_IN_RECOMMEND_RUNTIME_AUTH_OPTIONS = ISOLATED_RUNTIME_AUTH_OPTIONS;

 function getPlatformTabPanel(tab: string) {
  const panel = document.getElementById(`platform-tab-panel-${tab}`);
@@ -6179,11 +6180,59 @@ test('home recommendation starts embedded puzzle without global auth reset on lo
        profileId: 'puzzle-profile-public-1',
        levelId: null,
      },
-      RECOMMEND_RUNTIME_AUTH_OPTIONS,
+      LOGGED_IN_RECOMMEND_RUNTIME_AUTH_OPTIONS,
    );
  });
 });

+test('home recommendation keeps logged-in puzzle start on default auth instead of guest token', async () => {
+  const publishedPuzzleWork = {
+    workId: 'puzzle-work-public-2',
+    profileId: 'puzzle-profile-public-2',
+    ownerUserId: 'user-2',
+    sourceSessionId: 'puzzle-session-public-2',
+    authorDisplayName: '拼图作者',
+    levelName: '星桥机关',
+    summary: '旋转碎片并接通星桥机关。',
+    themeTags: ['机关', '星桥'],
+    coverImageSrc: null,
+    coverAssetId: null,
+    publicationStatus: 'published',
+    updatedAt: '2026-04-25T09:00:00.000Z',
+    publishedAt: '2026-04-25T09:00:00.000Z',
+    playCount: 3,
+    likeCount: 0,
+    publishReady: true,
+  } satisfies PuzzleWorkSummary;
+
+  vi.mocked(listPuzzleGallery).mockResolvedValue({
+    items: [publishedPuzzleWork],
+  });
+  vi.mocked(getPuzzleGalleryDetail).mockResolvedValue({
+    item: publishedPuzzleWork,
+  });
+
+  render(<TestWrapper withAuth />);
+
+  await waitFor(() => {
+    expect(startPuzzleRun).toHaveBeenCalledWith(
+      {
+        profileId: 'puzzle-profile-public-2',
+        levelId: null,
+      },
+      expect.objectContaining({
+        authImpact: 'local',
+        skipRefresh: true,
+        notifyAuthStateChange: false,
+        clearAuthOnUnauthorized: false,
+      }),
+    );
+  });
+  expect(vi.mocked(startPuzzleRun).mock.calls[0]?.[1]).not.toHaveProperty(
+    'runtimeGuestToken',
+  );
+});
+
 test('home recommendation Match3D runtime keeps profile generated models when card summary is stale', async () => {
  const match3dCard: Match3DWorkSummary = {
    workId: 'match3d-work-card-1',
@@ -6242,7 +6291,7 @@ test('home recommendation Match3D runtime keeps profile generated models when ca
  await waitFor(() => {
    expect(match3dServerRuntimeAdapterMock.startRun).toHaveBeenCalledWith(
      'match3d-profile-card-1',
-      RECOMMEND_RUNTIME_AUTH_OPTIONS,
+      LOGGED_IN_RECOMMEND_RUNTIME_AUTH_OPTIONS,
    );
  });
  await waitFor(() => {
@@ -6561,11 +6610,13 @@ test('home recommendation surfaces start failure instead of staying in loading s
  expect(
    await screen.findByText('作品暂时无法进入，请稍后再试。'),
  ).toBeTruthy();
-  expect(
-    within(getPlatformTabPanel('home'))
-      .queryByText('加载中...')
-      ?.closest('.platform-recommend-runtime-panel'),
-  ).toBeFalsy();
+  await waitFor(() => {
+    expect(
+      within(getPlatformTabPanel('home'))
+        .queryByText('加载中...')
+        ?.closest('.platform-recommend-runtime-panel'),
+    ).toBeFalsy();
+  });
 });

 test('published big fish works stay hidden from platform home and game category channel', async () => {
@@ -7197,7 +7248,6 @@ test('formal puzzle runtime uses frontend move merge logic and backend leaderboa
      profileId: 'puzzle-profile-public-1',
      levelId: null,
    },
-    ISOLATED_RUNTIME_AUTH_OPTIONS,
  );
  vi.mocked(listProfileSaveArchives).mockClear();
  vi.mocked(listProfileSaveArchives).mockRejectedValueOnce(
@@ -7221,7 +7271,6 @@ test('formal puzzle runtime uses frontend move merge logic and backend leaderboa
        elapsedMs: 18_000,
        nickname: '测试玩家',
      },
-      ISOLATED_RUNTIME_AUTH_OPTIONS,
    );
  });

@@ -7242,7 +7291,6 @@ test('formal puzzle runtime uses frontend move merge logic and backend leaderboa
    expect(advancePuzzleNextLevel).toHaveBeenCalledWith(
      clearedFirstLevel.runId,
      {},
-      ISOLATED_RUNTIME_AUTH_OPTIONS,
    );
  });
  expect(
@@ -7405,7 +7453,6 @@ test('formal puzzle similar work keeps current run level progression', async ()
    expect(advancePuzzleNextLevel).toHaveBeenCalledWith(
      clearedThirdLevel.runId,
      { targetProfileId: 'puzzle-profile-similar-2' },
-      ISOLATED_RUNTIME_AUTH_OPTIONS,
    );
  });
  expect(startPuzzleRun).not.toHaveBeenCalled();
@@ -7589,7 +7636,6 @@ test('recommend puzzle remix return restarts recommendation instead of stale loa
        profileId: 'puzzle-profile-public-1',
        levelId: null,
      },
-      ISOLATED_RUNTIME_AUTH_OPTIONS,
    );
  });
  expect(screen.queryByText('正在进入拼图关卡')).toBeNull();
--- a/src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx
+++ b/src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx
@@ -2778,6 +2778,35 @@ test('logged out recommend page can enter runtime without login gate', () => {
  expect(onOpenGalleryDetail).not.toHaveBeenCalled();
 });

+test('logged out desktop recommend rail enters runtime without login modal', async () => {
+  mockDesktopLayout();
+  const user = userEvent.setup();
+  const openLoginModal = vi.fn();
+
+  const { container } = renderLoggedOutHomeView(
+    openLoginModal,
+    {
+      latestEntries: [puzzlePublicEntry],
+      activeRecommendEntryKey: 'puzzle:user-2:puzzle-profile-public-1',
+    },
+    'category',
+    true,
+  );
+
+  const desktopRail = container.querySelector('.platform-desktop-rail');
+  if (!desktopRail) {
+    throw new Error('缺少桌面侧边栏');
+  }
+
+  await user.click(
+    within(desktopRail as HTMLElement).getByRole('button', { name: '推荐' }),
+  );
+
+  expect(openLoginModal).not.toHaveBeenCalled();
+  expect(screen.queryByTestId('recommend-runtime')).toBeNull();
+  expect(container.querySelector('.platform-desktop-shell')).toBeTruthy();
+});
+
 test('logged in recommend page uses gated recommend detail callback', async () => {
  const user = userEvent.setup();
  const onOpenGalleryDetail = vi.fn();
--- a/src/components/rpg-entry/RpgEntryHomeView.tsx
+++ b/src/components/rpg-entry/RpgEntryHomeView.tsx
@@ -5335,7 +5335,7 @@ export function RpgEntryHomeView({
            {recommendRuntimeError}
          </button>
        </section>
-      ) : isStartingRecommendEntry || !recommendRuntimeContent ? (
+      ) : isStartingRecommendEntry ? (
        <section className="platform-recommend-runtime-panel">
          <div className="platform-recommend-runtime-state">加载中...</div>
        </section>
--- a/src/components/rpg-entry/useRpgEntryBootstrap.ts
+++ b/src/components/rpg-entry/useRpgEntryBootstrap.ts
@@ -351,7 +351,7 @@ export function useRpgEntryBootstrap(
          !hasInitialAgentSession &&
          !hasExplicitPlatformTabSelectionRef.current
        ) {
-          // 中文注释：新用户先进入发现页；推荐页只在用户主动点击后作为登录门禁入口。
+          // 中文注释：新用户先进入发现页；推荐页可直接进入，真正受保护的动作再单独做登录门禁。
          setPlatformTabState(isAuthenticated ? 'home' : 'category');
        }
      } finally {