1

docs/experience/ADVENTURE_RUNTIME_DEV_EXPERIENCE.md

@@ -253,3 +253,40 @@ AI 可以解释世界，但不能私自改世界。
 这类 AI 冒险 RPG 的开发，最难的不是“把功能做出来”，而是：
 
 **让 function 边界、世界状态、视觉演绎、移动端面板和大模型文本在同一套规则下稳定协作。**
+
+## 7. 聊天输入区布局补充经验
+
+### 7.1 聊天框变大时，要优先增加“消息展示区”而不是只放大输入框
+
+- 玩家感知里的“聊天框高度”主要来自消息气泡和剧情滚动区，不是输入栏本身。
+- 如果只把输入框做高，实际会压缩选项区和底部按钮区，移动端反而更挤。
+- 更稳妥的做法是：
+  先让剧情/聊天滚动区在剩余空间里拿到更高的伸缩优先级，再微调输入条高度和底部留白。
+- 移动端不要随意给聊天区写死过大的最小高度，否则很容易把选项按钮和自定义输入一起挤出首屏。
+
+### 7.2 底部输入区要向安全区贴近，但不能直接贴死
+
+- 自定义输入要更贴近屏幕底部，应该缩小底部控制区的额外 padding，而不是去掉安全区。
+- `env(safe-area-inset-bottom)` 仍然要保留，否则刘海屏、手势条机型会出现输入框被顶起或遮挡的问题。
+- 正确方向是：
+  保留安全区补偿，只减少设计层自己额外加上的底部留白。
+
+### 7.3 底部操作区下沉时，要同步增加和聊天区之间的呼吸感
+
+- 当“队伍 / 背包 / 换一换 / 退出聊天 / 自定义输入”整体下移后，上下区块更容易挤在一起。
+- 这时要略微增加聊天区和操作区之间的垂直间距，保证视觉层级仍然清楚。
+- 目标不是做出更厚的面板，而是让用户一眼分清：
+  上面是正在发生的对话，下面是马上可点的操作。
+
+## 8. 战斗态底部面板布局经验
+
+### 8.1 战斗态不应继续保留剧情框占位
+
+- 战斗画面里玩家关注的是敌我状态与可执行动作，剧情文本框如果继续占据底部高度，会直接挤压操作按钮。
+- 战斗态应隐藏剧情框组件，只保留操作区；战斗结果叙事可放到结算或下一次非战斗剧情里展示。
+
+### 8.2 战斗选项数量要由剩余高度决定
+
+- 不要固定渲染全部战斗选项，否则移动端低高度屏幕会把按钮挤出可点击区域。
+- 更稳妥的做法是测量底部操作区可用高度，用单个按钮的最小高度和间距计算本帧可显示数量。
+- 至少保留 1 个操作，避免极端高度下玩家看不到任何战斗入口。

docs/experience/RPG_NEXT_SCENE_SERVER_RUNTIME_BRIDGE_FIX_2026-04-27.md

@@ -0,0 +1,35 @@
+# RPG 下一场景服务端桥接修复（2026-04-27）
+
+## 问题现象
+
+- 在 RPG 运行时点击“继续前往下一场景”后，玩家角色离场动画已经正常播放。
+- 但下一幕背景没有切过来，场景内 NPC / 敌对实体没有刷新出来。
+- 任务推进也没有跟着进入下一场景后的状态继续展示。
+
+## 根因
+
+- 这条链路当前走的是服务端 runtime action：`idle_travel_next_scene`。
+- 服务端 compat 返回的快照只表达“当前遭遇已经结束”，没有像前端本地旅行链路那样自动补齐：
+  - `currentScenePreset` 切换后的真实目标场景
+  - 新场景的 `currentEncounter / sceneHostileNpcs`
+  - 新场景到达后触发的 quest / scene chapter 进度
+- 前端此前对服务端返回快照只做了 battle hydration，没有对“场景旅行”做二次桥接。
+
+## 修复口径
+
+- 在 [src/hooks/rpg-runtime-story/rpgRuntimeStoryGateway.ts](/C:/Genarrative/src/hooks/rpg-runtime-story/rpgRuntimeStoryGateway.ts) 中新增服务端场景旅行桥接：
+  - 当 functionId 为 `idle_travel_next_scene` 时，优先读取服务端返回的新场景 id。
+  - 如果服务端仍未给出新场景 id，则回退到当前场景的 `forwardSceneId`。
+  - 统一复用 `buildMapTravelResolution`，把前端现有的场景切换真相态补齐到服务端快照上。
+- 这样可以继续复用现有的：
+  - 场景背景切换
+  - NPC / 敌对实体预览与入场
+  - quest 与 scene chapter 的场景到达推进
+
+## 后续约束
+
+- 后续所有服务端 runtime 的“旅行 / 切场景 / 回营地”动作，如果返回的是最小快照，前端必须明确判断是否需要桥接到现有真相态工具。
+- 不要只把“动画播放结束”当成场景切换完成；真正完成的标准必须是：
+  - 新 `currentScenePreset` 已落地
+  - 新场景 encounter / hostile NPC 已进入可渲染状态
+  - 场景到达后的 quest / chapter 推进结果可见