Merge remote-tracking branch 'origin/master' into stdb

2026-04-20 07:56:15 +00:00
parent ef72fd156b 1c72066bab
commit 69fc2428a2
73 changed files with 7814 additions and 1018 deletions
--- a/docs/audits/CHARACTER_ASSET_PROMPT_CHAIN_AUDIT_2026-04-20.md
+++ b/docs/audits/CHARACTER_ASSET_PROMPT_CHAIN_AUDIT_2026-04-20.md
@@ -0,0 +1,379 @@
+# 角色资产 Prompt 链路审计（2026-04-20）
+
+更新时间：`2026-04-20`
+
+## 0. 本次审计回答什么问题
+
+本次只回答角色资产相关的 4 个问题：
+
+1. `characterAssetPrompts.ts` 里的 `visualPromptText` 和 `animationPromptText`，是不是“生成角色形象 / 动作形象的默认描述”。
+2. 生成角色形象的系统提示词在哪个文件，生成默认角色形象描述文本的提示词在哪个文件。
+3. 生成角色动作的系统提示词在哪个文件，生成默认角色动作描述文本的提示词在哪个文件。
+4. 当前链路里是否存在冗余流程、保留接口或无效代码。
+
+---
+
+## 1. 先说结论
+
+结论不是“只有一套 prompt”，而是：
+
+**当前角色资产链路至少有两层 prompt，且这两层在仓库里被不同文件承担。**
+
+### 1.1 默认描述文本层
+
+这层的目标是：
+
+**先给资产工坊里的输入框一个默认可编辑文本。**
+
+这层不直接拿去生成图片或动作视频。
+
+当前实际主链来源：
+
+- `src/prompts/customWorldRolePromptDefaults.ts`
+
+它会把角色已有字段映射成：
+
+- `visualPromptText`
+- `animationPromptText`
+- `scenePromptText`
+
+其中：
+
+- `visualPromptText` 优先取 `visualDescription`
+- `animationPromptText` 优先取 `actionDescription`
+- `scenePromptText` 优先取 `sceneVisualDescription`
+
+这层是**默认描述文本**，不是正式图像模型 prompt。
+
+### 1.2 正式模型 prompt 层
+
+这层的目标是：
+
+**把“默认描述文本”进一步编译成正式给图像模型 / 动作模型的完整 prompt。**
+
+当前主链来源：
+
+- `server-node/src/prompts/characterAssetPrompts.ts`
+- `packages/shared/src/prompts/qwenSprite.ts`
+
+也就是说：
+
+1. 前端先有一段短文本
+2. 后端再用正式 prompt builder 把它扩成模型真正使用的完整 prompt
+
+---
+
+## 2. 角色形象生成链路
+
+## 2.1 生成角色形象的系统提示词在哪
+
+如果这里问的是“正式生成角色主图时，真正控制模型输出方向的 prompt 主源在哪”，答案是：
+
+- `server-node/src/prompts/characterAssetPrompts.ts`
+- `packages/shared/src/prompts/qwenSprite.ts`
+
+更准确说：
+
+1. `buildNpcVisualPrompt`
+   - 文件：`server-node/src/prompts/characterAssetPrompts.ts`
+   - 作用：把短描述文本和角色摘要合并
+2. `buildMasterPrompt`
+   - 文件：`packages/shared/src/prompts/qwenSprite.ts`
+   - 作用：提供正式的角色主图 prompt 骨架
+
+最终角色形象正式生成请求使用的是：
+
+- `buildNpcVisualPrompt(...)`
+
+调用位置：
+
+- `server-node/src/modules/assets/characterAssetRoutes.ts`
+
+即：
+
+**角色主图正式生成的系统提示词主链，不在前端默认值文件，而在后端 `characterAssetPrompts.ts` + 共享 `qwenSprite.ts`。**
+
+## 2.2 生成默认角色形象描述文本的提示词在哪
+
+当前仓库需要分两种情况：
+
+### 情况 A：当前自定义世界资产工坊真实主链
+
+当前资产工坊默认输入框实际使用：
+
+- `src/prompts/customWorldRolePromptDefaults.ts`
+
+这不是 LLM system prompt，而是本地字段映射规则。
+
+换句话说，当前页面上的默认“形象描述”主要来自：
+
+- `role.visualDescription`
+- 或回退到 `role.description`
+
+### 情况 B：仓库里保留的“默认 bundle 编译接口”
+
+仓库里仍保留一条后端接口：
+
+- `/api/assets/character-prompts/generate`
+
+对应文件：
+
+- `server-node/src/prompts/characterAssetPrompts.ts`
+
+这条链使用：
+
+- `CHARACTER_PROMPT_BUNDLE_SYSTEM_PROMPT`
+- `buildCharacterPromptBundleUserPrompt`
+
+它的职责是：
+
+**让 LLM 从角色卡摘要里编译出一组默认文本 bundle。**
+
+但当前实际问题是：
+
+**自定义世界角色资产工坊初始化默认值，并没有走这条接口。**
+
+因此当前状态更准确地说是：
+
+- 仓库里有一条“LLM 编译默认文本 bundle”的保留链
+- 但当前资产工坊真实初始默认值主链，走的是前端本地映射
+
+---
+
+## 3. 角色动作生成链路
+
+## 3.1 生成角色动作的系统提示词在哪
+
+当前正式动作生成主链在：
+
+- `server-node/src/prompts/characterAssetPrompts.ts`
+- `packages/shared/src/prompts/qwenSprite.ts`
+
+其中分两类：
+
+1. `buildArkCharacterAnimationPrompt`
+   - 当前图生视频动作链路主入口
+2. `buildNpcAnimationPrompt`
+   - 通用动作视频 prompt builder
+3. `buildImageSequencePrompt`
+   - 连续帧方案动作 prompt builder
+4. `buildVideoActionPrompt`
+   - 共享动作模板骨架，在 `packages/shared/src/prompts/qwenSprite.ts`
+
+当前主动作链路更偏向：
+
+- `buildArkCharacterAnimationPrompt`
+
+调用位置：
+
+- `server-node/src/modules/assets/characterAssetRoutes.ts`
+
+## 3.2 生成默认角色动作描述文本的提示词在哪
+
+当前资产工坊真实默认“动作描述”来源：
+
+- `src/prompts/customWorldRolePromptDefaults.ts`
+
+规则是：
+
+- 优先 `actionDescription`
+- 回退 `combatStyle`
+
+这仍然是**默认描述文本层**，不是最终动作模型 prompt。
+
+仓库里也保留了 LLM 编译 bundle 的接口链：
+
+- `CHARACTER_PROMPT_BUNDLE_SYSTEM_PROMPT`
+- `buildCharacterPromptBundleUserPrompt`
+
+这条链也会生成：
+
+- `animationPromptText`
+
+但当前资产工坊真实初始默认值并没有实际调用它。
+
+---
+
+## 4. `characterAssetPrompts.ts` 里的 `visualPromptText` / `animationPromptText` 到底是什么
+
+这两个字段容易混淆，因为它们名字里带 `Prompt`。
+
+但当前工程里它们更准确的定位是：
+
+**“默认描述文本 bundle 字段名”，不是最终图像模型请求体里的最终 prompt 名称。**
+
+也就是：
+
+- `visualPromptText`
+  - 在 UI 里更像“角色形象描述默认文本”
+  - 之后会再被编译进正式图像 prompt
+- `animationPromptText`
+  - 在 UI 里更像“角色动作描述默认文本”
+  - 之后会再被编译进正式动作 prompt
+
+所以对你的问题可以直接回答为：
+
+**是，它们在当前语义上确实可以看作“默认角色形象 / 动作描述文本”。**
+
+但需要补一句：
+
+**它们不是最终一步的正式模型系统提示词，而是正式模型 prompt 的上游输入。**
+
+---
+
+## 5. 当前真实调用链
+
+## 5.1 当前资产工坊页面初始默认值主链
+
+当前真实主链：
+
+1. 角色对象已有字段进入前端
+2. `src/prompts/customWorldRolePromptDefaults.ts`
+3. `CustomWorldRoleAssetStudioModal.tsx`
+4. 输入框初始值：
+   - `visualPromptText`
+   - `animationPromptText`
+
+这条链：
+
+- 快
+- 本地可控
+- 不依赖额外一次 LLM 调用
+
+## 5.2 当前正式角色主图生成主链
+
+1. 前端把输入框里的 `visualPromptText` 提交到后端
+2. `server-node/src/prompts/characterAssetPrompts.ts`
+   - `buildNpcVisualPrompt`
+3. `packages/shared/src/prompts/qwenSprite.ts`
+   - `buildMasterPrompt`
+4. 图像模型正式生成
+
+## 5.3 当前正式角色动作生成主链
+
+1. 前端把输入框里的 `animationPromptText` 提交到后端
+2. `server-node/src/prompts/characterAssetPrompts.ts`
+   - `buildArkCharacterAnimationPrompt`
+   - 或 `buildNpcAnimationPrompt`
+   - 或 `buildImageSequencePrompt`
+3. `packages/shared/src/prompts/qwenSprite.ts`
+   - `buildVideoActionPrompt`
+4. 动作模型正式生成
+
+---
+
+## 6. 冗余流程与当前问题
+
+## 6.1 明确存在的冗余点：默认 bundle 双链并存
+
+当前仓库里“默认描述文本”其实有两套来源：
+
+### 第一套：前端本地字段映射
+
+- `src/prompts/customWorldRolePromptDefaults.ts`
+
+### 第二套：后端 LLM bundle 编译接口
+
+- `server-node/src/prompts/characterAssetPrompts.ts`
+- `/api/assets/character-prompts/generate`
+
+问题不在于“两套都存在”，而在于：
+
+**当前自定义世界资产工坊真实默认值只走第一套，第二套保留但没有进入当前主 UI 链。**
+
+这意味着：
+
+1. 从业务视角看，默认描述文本存在双份真相。
+2. 从维护视角看，两个地方都在描述 `visualPromptText / animationPromptText / scenePromptText` 的生成语义。
+3. 从测试视角看，后端 bundle 接口仍有测试，但 UI 主链没有使用它。
+
+判断：
+
+**这是当前最明显的冗余流程。**
+
+## 6.2 `scenePromptText` 结构存在，但当前资产工坊没有完整承接
+
+当前这套链路里：
+
+- `customWorldRolePromptDefaults.ts` 会返回 `scenePromptText`
+- `characterAssetPrompts.ts` 也会返回 `scenePromptText`
+
+但当前资产工坊 UI 里并没有完整对应输入框链路。
+
+这说明：
+
+**场景描述文本在结构层存在，但在当前角色资产工坊里没有形成完整的用户可编辑闭环。**
+
+## 6.3 共享模板与工具模板存在相似实现，但职责不同
+
+仓库里同时有：
+
+- `packages/shared/src/prompts/qwenSprite.ts`
+- `src/prompts/qwenSpriteSheetToolPrompts.ts`
+
+它们都提供类似的主图 / 动作模板能力。
+
+但当前定位不同：
+
+- `packages/shared/src/prompts/qwenSprite.ts`
+  - 正式角色资产主链共享模板
+- `src/prompts/qwenSpriteSheetToolPrompts.ts`
+  - Qwen 工具链 prompt
+
+它们不是同一条业务主链里的重复实现，但确实容易让人误读为“双份正式模板”。
+
+判断：
+
+**这是“职责上可解释，但认知上高混淆”的并行模板，不建议现在直接删，但需要文档明确边界。**
+
+## 6.4 当前没有证据说明正式主图 / 动作 prompt builder 是无效代码
+
+以下 builder 当前都有正式调用点：
+
+- `buildNpcVisualPrompt`
+- `buildNpcVisualNegativePrompt`
+- `buildArkCharacterAnimationPrompt`
+- `buildNpcAnimationPrompt`
+- `buildImageSequencePrompt`
+
+因此它们不能算“无效代码”。
+
+真正更接近“保留接口但未进入当前 UI 主链”的，是：
+
+- `CHARACTER_PROMPT_BUNDLE_SYSTEM_PROMPT`
+- `buildCharacterPromptBundleUserPrompt`
+- `/api/assets/character-prompts/generate`
+
+这套链路仍有测试、仍可工作，但当前不属于自定义世界资产工坊的真实默认值主链。
+
+---
+
+## 7. 本次建议
+
+如果后续要继续收口，建议按顺序处理：
+
+1. 先明确“资产工坊默认值唯一主源”到底选前端本地映射还是后端 LLM bundle 接口。
+2. 如果继续保留前端本地映射为主链，则把后端 bundle 接口标注为备用 / 实验 / 非主链能力。
+3. 如果准备切回后端 bundle 接口为主链，则要把当前 UI 初始化逻辑真正接上，并补场景描述输入框闭环。
+4. 对 `scenePromptText` 做完整承接，不要继续停留在结构存在但 UI 不消费的状态。
+5. 继续保留 `packages/shared/src/prompts/qwenSprite.ts` 与工具链 prompt 分层，但在文档里强制写清“正式主链 / 工具链”边界。
+
+---
+
+## 8. 本次审计覆盖文件
+
+- `server-node/src/prompts/characterAssetPrompts.ts`
+- `packages/shared/src/prompts/qwenSprite.ts`
+- `server-node/src/modules/assets/characterAssetRoutes.ts`
+- `src/prompts/customWorldRolePromptDefaults.ts`
+- `src/components/CustomWorldRoleAssetStudioModal.tsx`
+- `src/components/asset-studio/characterAssetWorkflowPersistence.ts`
+- `src/prompts/qwenSpriteSheetToolPrompts.ts`
+
+---
+
+## 9. 一句话版结论
+
+一句话总结就是：
+
+**当前角色资产系统把“默认描述文本”和“正式模型 prompt”拆成了两层，这是合理的；真正的问题不是有两层，而是“默认描述文本层”现在同时保留了前端本地映射和后端 LLM 编译两条链，而当前 UI 主链只用了前者，导致出现明显的冗余和认知混乱。**
--- a/docs/audits/README.md
+++ b/docs/audits/README.md
@@ -15,6 +15,7 @@
 - [FUNCTION_RUNTIME_FULL_TEST_AUDIT_2026-04-16.md](./FUNCTION_RUNTIME_FULL_TEST_AUDIT_2026-04-16.md)：Function 运行时完整测试、服务端承接验证与当前门禁缺口。
 - [ITEM_AND_BUILD_PRD_AUDIT_2026-04-05.md](./ITEM_AND_BUILD_PRD_AUDIT_2026-04-05.md)：物品生成与 Build 标签系统对 PRD 的落地情况。
 - [CUSTOM_WORLD_CREATOR_TOOL_AUDIT_2026-04-08.md](./CUSTOM_WORLD_CREATOR_TOOL_AUDIT_2026-04-08.md)：自定义世界创作工具当前问题、体验断层和优化优先级审计。
+- [CHARACTER_ASSET_PROMPT_CHAIN_AUDIT_2026-04-20.md](./CHARACTER_ASSET_PROMPT_CHAIN_AUDIT_2026-04-20.md)：角色资产默认描述文本、正式图像/动作 prompt、共享模板与保留接口的分层与冗余审计。
 - [engineering/ENGINEERING_CLEANUP_AND_BACKEND_BOUNDARY_AUDIT_2026-04-20.md](./engineering/ENGINEERING_CLEANUP_AND_BACKEND_BOUNDARY_AUDIT_2026-04-20.md)：对 `2026-04-19` 工程清理审计的当前仓库复核，区分已完成项、仍存边界问题和新的热点迁移。
 - [engineering/ENGINEERING_CLEANUP_AND_BACKEND_BOUNDARY_AUDIT_2026-04-19.md](./engineering/ENGINEERING_CLEANUP_AND_BACKEND_BOUNDARY_AUDIT_2026-04-19.md)：未引用垃圾、旧入口残留、前后端双份真相与后端迁移项的专项审计。

--- a/docs/design/COMPANION_FIRST_CONTACT_RELATIONSHIP_AND_PRIVATE_CHAT_DESIGN_2026-04-04.md
+++ b/docs/design/COMPANION_FIRST_CONTACT_RELATIONSHIP_AND_PRIVATE_CHAT_DESIGN_2026-04-04.md
@@ -233,6 +233,13 @@ function buildNpcFirstContactOptionCatalog(
   - `npc_quest_accept`
   - `npc_recruit`

+补一条实现约束：
+
+- 首次进入 `npc_chat` 时，前端聊天状态里不允许直接塞预设对白充当首句。
+- 角色第一次真正对玩家开口时说什么，必须由 `npc_chat` 对应的 prompt 约束来生成，并要求首句是自然招呼或开场判断。
+- 不能再用“某人看着你，像是在等你把话接下去”这类第三人称占位旁白充当可见对话历史首句，也不能在聊天 state 里本地硬编码一条替代台词。
+- 当玩家在场景中第一次真正撞上角色型 NPC 并进入聊天时，应直接触发一轮由 NPC 主动开口的模型回复；这一轮只生成 NPC 自己的首句与后续可选回应，不得代替玩家补写未说过的话。
+
 4. 首遇状态下，不允许前两项直接变成：
   - 深背景追问
   - 直接招募
@@ -329,6 +336,7 @@ firstContactRelationStance?: 'guarded' | 'neutral' | 'cooperative' | 'bonded' |

 - 它们只能作为“某个具体场景下调用通用首遇规则”的薄包装
 - 不应继续承担独立的开场规则系统
+- 更不能把本地预设对白直接写进 `npc_chat` 的可见对话历史里，`npc_chat` 首个角色台词必须由 prompt 生成

 也就是说：

--- a/docs/design/LEVEL_PROGRESS_AND_CHAPTER_NPC_AUTO_SCALING_DESIGN_2026-04-20.md
+++ b/docs/design/LEVEL_PROGRESS_AND_CHAPTER_NPC_AUTO_SCALING_DESIGN_2026-04-20.md
@@ -13,11 +13,29 @@
 5. 已在冒险主面板补充最小等级展示：`Lv.` 与细经验条；任务奖励面板可看到经验数值。
 6. 已收回任务日志里的直接领奖入口，任务奖励结算当前以 NPC 交付链路为准。

+## 实现进度（2026-04-20 第二批）
+
+当前仓库已继续落地第二批成长能力：
+
+1. 已给运行时敌对 NPC / 战斗遭遇补上 `levelProfile` 与 `experienceReward`，前后端快照、战斗态和恢复链路会保留这组元数据。
+2. 已新增敌对成长解析服务，当前先以玩家当前等级为 fallback，为 `npc_fight` / 敌对战斗入口自动生成等级、参考强度、战斗生命值与击杀经验。
+3. 已将 Express 后端战斗胜利结算接入 `hostile_npc` 经验发放，击败敌对 NPC 后会直接更新 `playerProgression`，并写回 `hostileNpcsDefeated` 统计。
+4. 已在战斗画布中补上敌对 NPC 的最小 `Lv.` 徽标展示，保持 UI 极简表达。
+
+## 实现进度（2026-04-20 第三批）
+
+当前仓库已继续落地第三批“章节预算 / 自动定级”能力：
+
+1. 已新增服务端 `chapterProgressionPlanner`，会基于 `sceneChapterBlueprints` 编译每章的 `entry / exit pseudo level`、总经验预算、任务经验份额、敌对经验份额与预计击杀数。
+2. 已新增 `npcLevelResolver`，会根据当前章节阶段和当前 act 的 `primaryNpcId` 自动区分 `hostile_standard / hostile_elite / hostile_boss / rival`，并输出 `source = chapter_auto` 的等级档案。
+3. 已将 `npc_fight` / `npc_spar` 开战入口接入章节上下文解析；当运行时存在章节蓝图、当前章和当前 act 信息时，敌对 NPC 不再只跟随玩家当前等级，而会按章节自动定级并生成更贴合本章预算的经验奖励。
+4. 已补上规划器、定级器与路由级验证，确认同一玩家在不同章节和不同阶段触发敌对战斗时，会得到不同的等级与经验结果。
+
 本轮仍未落地的部分：

-1. 击败敌对 NPC 经验。
-2. 章节经验预算 / ledger 统计。
-3. 按章节自动定级 NPC 与运行时敌对经验掉落。
+1. `ChapterExperienceLedger` 的正式持久化、按章实际经验记账与偏差回看还未接入。
+2. 同章重复刷敌的 `repeatPenalty` 与超预算衰减还未落地，当前仍是“预算规划 + 单次掉落”版本。
+3. 当前自动定级已优先接入敌对战斗入口，友方 / 环境 NPC 的更广泛等级消费链路仍待继续铺开。

 ## 0. 目标

--- a/docs/design/PLATFORM_HOME_PUBLIC_BROWSE_AND_LOGIN_MODAL_GATING_DESIGN_2026-04-19.md
+++ b/docs/design/PLATFORM_HOME_PUBLIC_BROWSE_AND_LOGIN_MODAL_GATING_DESIGN_2026-04-19.md
@@ -127,6 +127,12 @@
 - 未登录：弹出登录弹窗，并缓存 `action`
 - 登录成功：自动执行缓存的 `action`

+账号入口补充约束：
+
+- 不再提供 `AuthGate` 层右上角固定悬浮的全局登录 / 账号信息入口
+- 登录触发统一来自页面内受保护动作、个人页、存档页等明确入口
+- 账号信息面板只通过页面内按钮打开，不在平台右上角常驻悬浮
+
 ## 4.2 平台首页数据加载

 `PreGameSelectionFlow` 在未登录时只读取：
--- a/docs/experience/AGENT_UI_CHANGELOG.md
+++ b/docs/experience/AGENT_UI_CHANGELOG.md
@@ -6,16 +6,16 @@

 ## 1. 相关文件一览

-| 路径 | 作用 |
-|------|------|
-| `UI_CODING_STANDARD.md` | 资源目录约定、9-slice 规则、图标语义、`Icons`/`UI` 命名解读、已知问题（含世界按钮切片） |
-| `src/uiAssets.ts` | **唯一推荐** 的 UI 资源映射：`UI_CHROME`（9-slice 配置）、`TAB_ICONS`、`WORLD_SELECT_ICONS`、`getNineSliceStyle()` |
-| `src/components/PixelIcon.tsx` | 小图标 `<img>`，`image-rendering: pixelated` |
-| `src/index.css` | `.pixel-nine-slice`、`.pixel-root-shell` / `.pixel-app-shell`、tab/按钮布局类、`--ui-scale` |
-| `src/App.tsx` | 世界选择、角色卡、底部 tab、剧情/背包面板、地图弹窗、`MudMapRoom` |
-| `src/components/GameCanvas.tsx` | 场景名按钮（9-slice `Title_frame_m`） |
-| `vite.config.ts` | `root` / `envDir` 指向 `__dirname`，保证 `.env.local` 从项目根加载 |
-| `public/UI/`、`public/Icons/` | 静态资源（路径以 `/UI/...`、`/Icons/...` 引用） |
+| 路径                            | 作用                                                                                                               |
+| ------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `UI_CODING_STANDARD.md`         | 资源目录约定、9-slice 规则、图标语义、`Icons`/`UI` 命名解读、已知问题（含世界按钮切片）                            |
+| `src/uiAssets.ts`               | **唯一推荐** 的 UI 资源映射：`UI_CHROME`（9-slice 配置）、`TAB_ICONS`、`WORLD_SELECT_ICONS`、`getNineSliceStyle()` |
+| `src/components/PixelIcon.tsx`  | 小图标 `<img>`，`image-rendering: pixelated`                                                                       |
+| `src/index.css`                 | `.pixel-nine-slice`、`.pixel-root-shell` / `.pixel-app-shell`、tab/按钮布局类、`--ui-scale`                        |
+| `src/App.tsx`                   | 世界选择、角色卡、底部 tab、剧情/背包面板、地图弹窗、`MudMapRoom`                                                  |
+| `src/components/GameCanvas.tsx` | 场景名按钮（9-slice `Title_frame_m`）                                                                              |
+| `vite.config.ts`                | `root` / `envDir` 指向 `__dirname`，保证 `.env.local` 从项目根加载                                                 |
+| `public/UI/`、`public/Icons/`   | 静态资源（路径以 `/UI/...`、`/Icons/...` 引用）                                                                    |

 ---

@@ -48,22 +48,22 @@

 以下为 `src/uiAssets.ts` 中主要键与界面位置的对应关系（切片数值以文件内为准）：

-| Key | 资源（示例） | 用途 |
-|-----|----------------|------|
-| `appBackground` | `Background_fill.png` | 根壳 + 下半屏平铺底 |
+| Key                                       | 资源（示例）                          | 用途                                       |
+| ----------------------------------------- | ------------------------------------- | ------------------------------------------ |
+| `appBackground`                           | `Background_fill.png`                 | 根壳 + 下半屏平铺底                        |
 | `worldButtonWuxia` / `worldButtonXianxia` | `1_orange_button` / `1_violet_button` | 开局武侠/仙侠（**条高 28px**，切片见下文） |
-| `characterCardFrame` | `pick_hero_frame` | 选角卡片 |
-| `tabActive` / `tabInactive` | `Shop_tab_picked` / `Shop_tab` | 底部「角色 / 冒险 / 背包」 |
-| `panel` | `Frame_bg_big_2` | 装备区等通用面板 |
-| `storyPanel` | `Dialogue_frame` | 剧情正文区 |
-| `inventoryPanel` | `Inventory_bg` | 背包条目 |
-| `statsPanel` | `Stats_bar` | 角色数值面板 |
-| `choiceButton` | `Options_bar` | 剧情选项按钮 |
-| `modalPanel` | `Popup_window` | 地图弹窗外壳 |
-| `infoPanel` | `Dialogue_frame` | 地图弹窗内「当前地点 / 可前往」信息块 |
-| `sceneTitle` | `Title_frame_m` | 战斗画布顶部场景名按钮 |
-| `mapRoomCell` | `Map_frame` | 地图节点卡片（`MudMapRoom`） |
-| `mapDiagramPanel` | `Frame_bg_big_2` | 地图关系图整体衬底 |
+| `characterCardFrame`                      | `pick_hero_frame`                     | 选角卡片                                   |
+| `tabActive` / `tabInactive`               | `Shop_tab_picked` / `Shop_tab`        | 底部「角色 / 冒险 / 背包」                 |
+| `panel`                                   | `Frame_bg_big_2`                      | 装备区等通用面板                           |
+| `storyPanel`                              | `Dialogue_frame`                      | 剧情正文区                                 |
+| `inventoryPanel`                          | `Inventory_bg`                        | 背包条目                                   |
+| `statsPanel`                              | `Stats_bar`                           | 角色数值面板                               |
+| `choiceButton`                            | `Options_bar`                         | 剧情选项按钮                               |
+| `modalPanel`                              | `Popup_window`                        | 地图弹窗外壳                               |
+| `infoPanel`                               | `Dialogue_frame`                      | 地图弹窗内「当前地点 / 可前往」信息块      |
+| `sceneTitle`                              | `Title_frame_m`                       | 战斗画布顶部场景名按钮                     |
+| `mapRoomCell`                             | `Map_frame`                           | 地图节点卡片（`MudMapRoom`）               |
+| `mapDiagramPanel`                         | `Frame_bg_big_2`                      | 地图关系图整体衬底                         |

 图标路径：`TAB_ICONS`、`WORLD_SELECT_ICONS`、`CHROME_ICONS`；装备槽与背包分类见 `getEquipmentSlotIcon` / `getInventoryCategoryIcon`。

@@ -113,12 +113,35 @@

 ---

-## 8. 2026-04-18 补充记录
+## 8. 2026-04-18 / 2026-04-20 账号入口补充记录

- `GameShellRuntime` 进入游戏壳时，会主动隐藏认证层提供的右上角全局账号信息条。
- 原因不是账号功能下线，而是这个悬浮条会遮挡冒险主场景内容，移动端更明显。
- 账号相关入口保留在平台首页 / 个人页内部按钮与账号弹窗，不再占用游戏 HUD 区域。
+- 早期方案曾在 `AuthGate` 层提供右上角全局账号信息条，并在 `GameShellRuntime` 中临时隐藏。
+- 2026-04-20 起，这个全局悬浮入口已整体下线，不再区分“平台显示 / 冒险隐藏”。
+- 原因是右上角高频观察区不适合承载账号入口，且平台内已经有更明确的页面内入口。
+- 当前账号相关入口统一保留在平台首页受保护动作、个人页、存档页与账号弹窗，不再占用全局悬浮层。

 ---

-*文档目的：交接给下一个 Agent 时，优先读本文件 + `UI_CODING_STANDARD.md`，再改 `uiAssets.ts` / `App.tsx` / `index.css`。*
+## 9. 2026-04-20 等级 HUD / 冒险布局补充
+
+- 当前运行中的等级 UI 已从 `AdventurePanel` 底部移出，改为放在 `GameShellRuntime` 左上角固定 HUD，避免把主对话区挤短。
+- 左上角 HUD 复用 `CharacterInfoShared.tsx` 里的 `PlayerLevelProgress`，角色面板、实体详情、游戏 HUD 使用同一套等级进度表现。
+- `AdventurePanel` 不再承担等级条展示，底部交互区只保留队伍 / 背包 / 刷新 / 退出聊天 / 选项 / 自定义输入，并压缩了底部留白与面板间距。
+- 角色信息不只在总 HUD 里显示：`CharacterPanel` 的队伍成员卡、角色详情面板，以及 `AdventureEntityModal` 的实体详情头部都会展示角色身份与等级信息。
+- 队长展示正式 `Lv.`；同行角色展示“参考 Lv.”；NPC 优先展示运行时 `levelProfile.level`，这样 UI 只负责表现，不在前端虚构额外成长逻辑。
+- 左上角等级 HUD 不使用背景框体，仅保留 `Lv`、等级数字与极细经验线，避免遮挡场景背景与移动端视野。
+
+---
+
+## 10. 2026-04-20 平台亮色主题主 Tab 修正
+
+- `PlatformHomeView.tsx` 的四个主 Tab（首页 / 创作 / 存档 / 我的）现在统一挂在 `platform-remap-surface` 下，让亮色主题能接管历史遗留的 `text-zinc-*`、`bg-black/*`、`border-white/*` 组合。
+- 平台首页卡片覆层不要在组件里继续写死深色 `rgba(8,10,14,...)` 渐变；这次已收口为 `--platform-card-overlay-soft`、`--platform-card-overlay-strong`、`--platform-card-overlay-deep`，明暗主题都从 token 走。
+- 平台桌面顶栏里的账号头像、移动端底部主 Tab 分隔线，也不要保留暗色主题时留下的固定蓝色渐变和深色边线，应直接使用平台主题变量（如 `--platform-profile-avatar-fill`、`--platform-line-soft`）。
+- 后续如果继续调整平台主 Tab 视觉，优先改 `src/index.css` 的平台主题 token 和 remap 规则；只有 token 无法表达时，再做局部组件样式补丁，避免亮色主题再次出现“页面整体是亮的，但局部卡片仍是暗的”。
+- 参考图方向已明确：平台亮色主题应以白色为主底色，粉红只承担背景气氛和重点 CTA，不应让整页主壳继续像深粉底板。
+- 移动端底部 `platform-bottom-nav` 的 Tab 激活态必须与默认态使用同一套盒模型；边框要预占位，不能在 onPress / active 时临时增加边框导致按钮尺寸和留白跳变。
+
+---
+
+_文档目的：交接给下一个 Agent 时，优先读本文件 + `UI_CODING_STANDARD.md`，再改 `uiAssets.ts` / `App.tsx` / `index.css`。_
--- a/docs/experience/MOBILE_UI_DEV_EXPERIENCE.md
+++ b/docs/experience/MOBILE_UI_DEV_EXPERIENCE.md
@@ -94,6 +94,8 @@
 - 全局账号信息条挂在这里，会直接压住场景、敌人血条或顶部提示，手机端尤其明显。
 - 结论：
  账号入口应收回平台首页、个人页或设置面板，不要在实际冒险主场景常驻悬浮显示。
+- 当前仓库已进一步收口为：
+  不再提供右上角全局账号悬浮条，统一只保留页面内入口与独立账号面板。

 ## 5. 队伍面板经验

--- a/docs/prd/AI_CHARACTER_VISUAL_ANIMATION_MVP_PRD_2026-04-04.md
+++ b/docs/prd/AI_CHARACTER_VISUAL_ANIMATION_MVP_PRD_2026-04-04.md
@@ -260,7 +260,7 @@ MVP 必须与当前项目可扮演角色动作槽位对齐。
 - `run / attack` 是固定基础必生成动作
 - `idle / die` 改为固定可选动作，不再作为发布硬门槛
 - `idle` 未生成时默认直接使用主图静止显示
- `die` 未生成时默认播放一段基于主图的倒地过渡动画，并最终停在翻转倒地姿态
+- `die` 未生成时默认播放一段基于主图的向后倒地过渡动画，并最终停在翻转倒地姿态
 - 角色已配置的每个技能，都必须在技能编辑面板里补出对应动作预览
 - 图生视频默认走火山方舟 `Seedance` 首尾帧方案
 - 接口请求体中的两张参考图分别固定为 `first_frame / last_frame`
@@ -275,7 +275,7 @@ MVP 必须与当前项目可扮演角色动作槽位对齐。
 | 基础动作 | `attack`                        | 必填     | 角色普通攻击主动作                                 |
 | 技能动作 | `skills[*].actionPreviewConfig` | 必填     | 当前角色每个已配置技能都要有独立动作资源           |
 | 可选动作 | `idle`                          | 可选     | 缺失时默认走主图静止待机                           |
-| 可选动作 | `die`                           | 可选     | 缺失时默认走主图倒地过渡动画，最终停在翻转倒地姿态 |
+| 可选动作 | `die`                           | 可选     | 缺失时默认走主图向后倒地过渡动画，最终停在翻转倒地姿态 |

 这里“必生成”指的是：

--- a/docs/prd/AI_NATIVE_AGENT_FIRST_CUSTOM_WORLD_CREATOR_PHASE5_IMPLEMENTATION_PLAN_2026-04-14.md
+++ b/docs/prd/AI_NATIVE_AGENT_FIRST_CUSTOM_WORLD_CREATOR_PHASE5_IMPLEMENTATION_PLAN_2026-04-14.md
@@ -251,7 +251,7 @@ kind === 'character';

 1. `run / attack` 为固定必生成动作
 2. 角色已配置技能时，对应技能动作也属于必生成动作
-3. `idle / die` 只作为可选增强，缺失时分别走主图静止 / 主图倒地过渡动画兜底，死亡动画最终停在翻转倒地姿态
+3. `idle / die` 只作为可选增强，缺失时分别走主图静止 / 主图向后倒地过渡动画兜底，死亡动画带轻微过冲回落，最终停在翻转倒地姿态

 ### 阶段 D：动作发布

--- a/docs/prd/AI_NATIVE_AGENT_FIRST_CUSTOM_WORLD_CREATOR_PRD_2026-04-12.md
+++ b/docs/prd/AI_NATIVE_AGENT_FIRST_CUSTOM_WORLD_CREATOR_PRD_2026-04-12.md
@@ -583,7 +583,7 @@ type CustomWorldScenePriorityTier = 'key' | 'supporting';
 默认兜底：

 1. `idle` 缺失时使用主图静止
-2. `die` 缺失时使用主图倒地过渡动画，最终停在翻转倒地姿态
+2. `die` 缺失时使用主图向后倒地过渡动画，最终停在翻转倒地姿态

 ### 场景图抽卡策略

@@ -663,7 +663,7 @@ type CustomWorldScenePriorityTier = 'key' | 'supporting';

 1. `idle / die` 不再是发布硬门槛
 2. `idle` 缺失时运行时默认使用主图静止
-3. `die` 缺失时运行时默认播放主图倒地过渡动画，最终停在翻转倒地姿态
+3. `die` 缺失时运行时默认播放主图向后倒地过渡动画，并通过轻微过冲回落让动作更自然，最终停在翻转倒地姿态

 说明：

--- a/docs/prd/AI_NATIVE_SCENE_MULTI_ACT_CREATOR_AND_GAMEPLAY_FLOW_PRD_2026-04-20.md
+++ b/docs/prd/AI_NATIVE_SCENE_MULTI_ACT_CREATOR_AND_GAMEPLAY_FLOW_PRD_2026-04-20.md
@@ -24,6 +24,17 @@

 **每个场景由创作者在工具中配置为 `2~5` 幕；每一幕都绑定独立背景图和相遇 NPC 顺序；每一幕的第一个 NPC 视为主角色；运行时按幕切换背景和可遇对象，并根据主角色当前好感度裁决聊天轮数与第 5 轮收束方式。**

+补充口径修正：
+
+1. `scene_chapter` 在本期继续保留为数据层 / 编译层 / 运行时层概念。
+2. `scene_chapter` 不作为创作者可见的独立 Tab、独立卡片或独立导航入口。
+3. 创作者配置多幕的唯一入口，是现有“场景”列表里的场景编辑弹层。
+4. 每一幕的 NPC 配置区必须直接叠在当前幕背景预览上，以“对面角色站位”的方式呈现；三个站位既是预览，也是编辑入口。
+5. 幕编辑站位中每个角色只显示角色形象与名称，不展示额外信息块、规则说明或说明性标签。
+6. 幕内小预览的构图固定为左侧玩家、右侧当前幕角色；右侧三个站位采用一前两后。
+7. 新建幕默认仅预置 1 个主角色槽位内容，其余槽位留空，等待创作者补充。
+8. 角色名称显示在角色形象上方，角色渲染不附带方形 UI 底板。
+
 这份文档必须能直接指导后续创作工具和游戏流程改造，避免需求落地漂移。

 ---
@@ -72,14 +83,14 @@

 当前仓库已经具备下面这些基础：

-1. `packages/shared/src/contracts/customWorldAgent.ts`
-   - 已存在 `scene_chapter` 草稿卡 kind。
+1. `src/types/customWorld.ts`
+   - 已有 `SceneChapterBlueprint / SceneActBlueprint / sceneChapterBlueprints` 数据结构。

 2. `server-node/src/services/customWorldAgentDraftCompiler.ts`
-   - 已经能编译世界、第一幕、线程、势力、角色、地点等草稿卡。
+   - 已经能把草稿阶段生成的场景章节数据编译成正式多幕蓝图。

-3. `src/components/custom-world-agent/CustomWorldAgentDraftDrawer.tsx`
-   - 已有草稿抽屉，但还没有把 `scene_chapter` 正式纳入抽屉分组。
+3. `src/components/CustomWorldEntityEditorModal.tsx`
+   - 已有现成的 `LandmarkEditor`，这是本期多幕配置的正确承载位置。

 4. 现有场景背景图生成与发布链已存在。

@@ -324,62 +335,61 @@ type NpcChatTurnResult = {

 本次必须继续复用现有：

-1. `src/components/custom-world-agent/CustomWorldAgentDraftDrawer.tsx`
-2. `src/components/custom-world-agent/CustomWorldDraftCardDetailModal.tsx`
-3. `src/components/custom-world-agent/CustomWorldDraftEditPanel.tsx`
+1. `src/components/CustomWorldResultView.tsx`
+2. `src/components/CustomWorldEntityCatalog.tsx`
+3. `src/components/CustomWorldEntityEditorModal.tsx` 内的 `LandmarkEditor`

-不新建独立页面。
+不新建独立页面，也不新增独立 `scene_chapter` Tab。

 新增规则：

-1. 草稿抽屉必须正式支持 `scene_chapter` 分组。
-2. `scene_chapter` 分组应位于 `chapter` 后、`thread` 前。
-3. 点开 `scene_chapter` 草稿卡后，进入现有详情弹层和编辑面板体系。
-4. 创作页面卡片摘要后续可增加 `sceneChapterCount`，但第一版不是阻塞项。
+1. 创作者从现有“场景”列表点击任一场景卡，进入对应场景编辑弹层。
+2. 多幕配置必须作为场景编辑弹层内的一个区块出现，归属于该场景。
+3. `scene_chapter` 仅作为保存层和运行时蓝图存在，不单独暴露在创作者导航里。
+4. 场景卡片可增加“幕数量”轻量摘要，但第一版不是阻塞项。

-## 7.2 场景章节卡展示要求
+## 7.2 场景编辑弹层展示要求

-每张 `scene_chapter` 草稿卡至少展示：
+场景编辑弹层至少展示：

-1. 场景名称
-2. 章节标题
-3. 幕数量
-4. 已就绪背景图数量
-5. 关联 NPC 数量
-6. 关联线程数量
-7. 当前风险数
+1. 场景名称与描述
+2. 场景主图
+3. 场景内 NPC
+4. 多幕配置区块
+5. 场景连接关系

-详情页必须至少展示：
+多幕区块至少展示：

-1. 场景摘要
-2. 幕结构总览
-3. 每幕的背景缩略图
-4. 每幕的主角色
-5. 每幕的辅助 NPC
-6. 每幕目标
-7. 每幕过渡钩子
+1. 幕列表
+2. 每幕与场景主图同规格的背景预览
+3. 每幕对面角色的 `3` 个固定槽位
+4. 每幕主角色标记
+5. 每幕背景配置入口
+6. 每幕预览入口

 ## 7.3 幕编辑交互

-每个场景章节卡的编辑区必须支持下面这些操作：
+每个场景编辑弹层里的多幕区块必须支持下面这些操作：

 1. 新增幕
 2. 删除幕
 3. 调整幕顺序
-4. 编辑幕标题
-5. 编辑幕摘要
-6. 绑定幕背景图
-7. 配置幕相遇 NPC 顺序
-8. 编辑幕目标
-9. 编辑幕过渡钩子
+4. 绑定幕背景图
+5. 在幕背景预览上点击角色槽位，为该槽位配置角色
+6. 移除某个已配置槽位的角色
+7. 开始当前幕预览

 交互要求：

 1. 幕列表在桌面端纵向堆叠，在移动端同样保持纵向，不做复杂双列。
 2. 每幕是独立卡片，不把所有字段一次性铺满。
-3. 点击“配置背景图”时必须打开独立面板或独立弹层，不允许在当前卡片下方内联展开。
-4. 点击“配置相遇 NPC”时必须打开独立面板或独立弹层，不允许在当前卡片下方内联展开。
-5. 默认不展示大段规则说明文字。
+3. 三个角色槽位必须直接叠在幕背景图上，作为当前幕预览的一部分。
+4. 每个槽位只显示角色形象与名称，不展开为信息块。
+5. 空槽位以虚线站位展示，点击后进入角色选择弹层。
+6. 点击“配置背景图”时必须打开独立面板或独立弹层，不允许在当前卡片下方内联展开。
+7. 点击角色槽位时必须打开独立面板或独立弹层，不允许在当前卡片下方内联展开。
+8. 单幕手工编辑区不再暴露“幕标题 / 幕摘要 / 幕目标 / 过渡铺垫”字段，这些内容继续留在 Agent 草稿生成与编译层维护。
+9. 默认不展示大段规则说明文字。

 ## 7.4 幕背景图配置

@@ -392,6 +402,7 @@ type NpcChatTurnResult = {
 3. 幕背景图和场景总背景图不是同一个概念，允许不同幕使用不同图。
 4. 发布前如果存在未绑定背景图的幕，必须阻止发布。
 5. 幕切换时运行时优先使用幕背景图，而不是地点默认图。
+6. 幕背景预览窗口长宽比与场景主图预览保持一致。

 ## 7.5 幕相遇 NPC 配置

@@ -399,18 +410,32 @@ NPC 配置面板必须支持：

 1. 从当前世界的 `playableNpcs + storyNpcs` 中选择角色
 2. 只展示与当前场景相关的优先推荐角色
-3. 支持排序
-4. 第一位角色明确标记为“主角色”
+3. 以 `3` 个固定槽位进行配置，而不是长列表表单
+4. 第一槽位明确标记为“主角色”
 5. 允许同一角色出现在多个不同幕
+6. 同一幕内不允许同一角色重复占用多个槽位

 硬约束：

 1. 每幕至少 `1` 名 NPC。
-2. 第一位 NPC 不能为空。
+2. 第一槽位不能为空，后续槽位才能继续配置。
 3. 不允许把不存在于当前世界角色池中的 id 写入幕配置。
 4. 若主角色未与当前场景或线程建立任何关联，给出发布警告。
+5. 存储时继续落到 `encounterNpcIds` 有序数组，槽位从左到右按顺序压缩写入。

-## 7.6 创作校验
+## 7.6 幕预览
+
+创作者在场景编辑弹层里点击“幕预览”后，必须直接进入当前幕的运行时预览。
+
+要求如下：
+
+1. 预览必须复用正常游戏运行时，而不是单独写一个静态演示页。
+2. 预览启动时要把当前幕设为活跃幕，并带上当前幕背景与当前幕主角色。
+3. 若当前幕主角色好感度小于 `0`，预览中必须直接进入最多 `5` 轮的有限聊天态。
+4. 若当前幕主角色好感度大于 `0`，预览中必须沿用无限轮聊天规则。
+5. 预览面板使用独立全屏层，不挤压原场景编辑弹层布局。
+
+## 7.7 创作校验

 `CustomWorldQualityFinding` 至少新增下面这些检查项：

@@ -589,10 +614,11 @@ interface SceneActRuntimeState {

 必须做到：

-1. `scene_chapter` 卡片可见
+1. 在“场景”列表点击场景卡后，可以看到多幕配置区块
 2. 幕列表可编辑
-3. 背景图选择和 NPC 选择都走独立面板
-4. 移动端仍能完成幕排序、背景选择、NPC 排序
+3. 每幕以大图预览 + 角色槽位的方式编辑
+4. 背景图选择、角色槽位选择、幕预览都走独立面板
+5. 移动端仍能完成幕排序、背景选择、槽位换角与幕预览

 ## 10.2 游戏主面板

@@ -617,11 +643,12 @@ Adventure 主面板在本次迭代中至少增加下面这些表现：

 前端只负责：

-1. 渲染 `scene_chapter` 草稿卡与幕编辑 UI
+1. 在现有场景编辑弹层中渲染多幕编辑 UI
 2. 发起背景图配置和 NPC 配置请求
 3. 渲染当前幕背景和幕标题
 4. 渲染负好感聊天剩余轮数
-5. 根据后端返回切换幕、退出聊天、展示后续 options
+5. 启动当前幕预览并承载正常游戏运行时
+6. 根据后端返回切换幕、退出聊天、展示后续 options

 前端不负责：

@@ -657,7 +684,7 @@ Adventure 主面板在本次迭代中至少增加下面这些表现：
   - 新增发布态 `sceneChapterBlueprints`

 3. `server-node/src/services/customWorldAgentDraftCompiler.ts`
-   - 编译 `scene_chapter` 草稿卡
+   - 编译 `scene_chapter` 草稿数据

 4. `server-node/src/services/customWorldAgentDraftEditService.ts`
   - 支持场景幕的增删改排序
@@ -665,31 +692,28 @@ Adventure 主面板在本次迭代中至少增加下面这些表现：
 5. `server-node/src/services/customWorldAgentQualityService.ts`
   - 增加幕背景和幕 NPC 校验

-6. `src/components/custom-world-agent/CustomWorldAgentDraftDrawer.tsx`
-   - 展示 `scene_chapter` 分组
+6. `src/components/CustomWorldEntityCatalog.tsx`
+   - 继续承载场景列表入口

-7. `src/components/custom-world-agent/CustomWorldDraftCardDetailModal.tsx`
-   - 展示幕详情
+7. `src/components/CustomWorldEntityEditorModal.tsx`
+   - 在 `LandmarkEditor` 中新增幕编辑 UI

-8. `src/components/custom-world-agent/CustomWorldDraftEditPanel.tsx`
-   - 新增幕编辑 UI
-
-9. `src/data/questFlow.ts`
+8. `src/data/questFlow.ts`
   - 让 scene chapter quest 感知当前幕

-10. `src/services/storyEngine/chapterDirector.ts`
+9. `src/services/storyEngine/chapterDirector.ts`
    - 用当前幕映射章节阶段和摘要

-11. `src/hooks/story/npcEncounterActions.ts`
+10. `src/hooks/story/npcEncounterActions.ts`
    - 新增主角色有限聊天与第 5 轮收束逻辑

-12. `packages/shared/src/contracts/story.ts`
+11. `packages/shared/src/contracts/story.ts`
    - 扩展 `NpcChatTurnResult`

-13. `src/services/aiService.ts`
+12. `src/services/aiService.ts`
    - 透传有限聊天新字段

-14. `server-node/src/modules/ai/chatOrchestrator.ts`
+13. `server-node/src/modules/ai/chatOrchestrator.ts`
    - 生成第 `5` 轮铺垫式收束结果

 ---
@@ -698,7 +722,7 @@ Adventure 主面板在本次迭代中至少增加下面这些表现：

 当下面这些结果都成立时，视为本次 PRD 已被正确落地：

-1. 创作者可以在现有创作工作区中创建并编辑 `scene_chapter`。
+1. 创作者可以在现有场景编辑弹层中配置每个场景的多幕。
 2. 每个场景章节都可以配置 `2~5` 幕。
 3. 每一幕都可以绑定独立背景图。
 4. 每一幕都可以配置有序 NPC 列表，第一位自动成为主角色。
--- a/docs/prd/AI_NATIVE_UNIFIED_ROLE_ATTRIBUTE_SYSTEM_PRD_2026-04-02.md
+++ b/docs/prd/AI_NATIVE_UNIFIED_ROLE_ATTRIBUTE_SYSTEM_PRD_2026-04-02.md
@@ -963,6 +963,11 @@ behaviorVectors: Array<{
 3. 一句解释文本
 4. 怪物的“敌意关系状态”

+补一条 UI 落地约束：
+
+- 包括选角流、角色面板、详情弹窗在内，所有属性展示入口都必须直接读取当前世界的 `WorldAttributeSchema.slots`。
+- 禁止回退显示 `力量 / 敏捷 / 智力 / 精神` 这类旧四维占位文案，除非该入口明确处于旧数据迁移调试模式。
+
 ## 11.3 对玩家的信息揭示分层

 不是所有 NPC 初见时都展示完整属性。
--- a/docs/prd/MY_TAB_SETTINGS_AND_SECURITY_PRD_2026-04-16.md
+++ b/docs/prd/MY_TAB_SETTINGS_AND_SECURITY_PRD_2026-04-16.md
@@ -68,22 +68,21 @@
 3. 登录设备
 4. 更换手机号
 5. 账号操作记录
+6. 退出登录
+7. 退出全部设备

 交互层级要求补充为：

-1. 设置首页只展示“主题外观”“账号信息”两个分区入口与危险操作，不在首页内联展开具体详情
+1. 设置首页只展示“主题外观”“账号信息”两个分区入口，不在首页内联展开具体详情
 2. 点击任一分区入口后，必须进入独立二级面板
 3. 安全状态、登录设备、操作记录不再作为首页独立入口，统一归入“账号信息”二级面板
 4. 更换手机号属于独立操作面板，不允许在账号信息面板内直接展开表单
-5. 设置首页头部只保留一套主标题，不允许在内容区再重复放置“设置首页”“选择要管理的内容”这类二次标题块
-6. 子面板导航动作必须单一明确；同一层面板内有“返回”时，不再同时展示“关闭”
-7. 设置首页与各级子面板都必须定义单一滚动容器，列表内容必须可稳定滚动，禁止外层与内层同时争夺滚动
-8. 二级或三级面板打开后，下层内容必须进入不可交互状态，并把焦点主动转移到当前面板内；禁止对仍保留焦点的祖先节点使用 `aria-hidden`
-
-底部保留两个危险操作按钮：
-
-1. 退出登录
-2. 退出全部设备
+5. 退出登录与退出全部设备统一归入“账号信息”二级面板，不再在设置首页单独占位
+6. 设置首页头部只保留一套主标题，不允许在内容区再重复放置“设置首页”“选择要管理的内容”这类二次标题块
+7. 子面板导航动作必须单一明确；同一层面板内有“返回”时，不再同时展示“关闭”
+8. 子面板返回按钮固定摆在面板右上角
+9. 设置首页与各级子面板都必须定义单一滚动容器，列表内容必须可稳定滚动，禁止外层与内层同时争夺滚动
+10. 二级或三级面板打开后，下层内容必须进入不可交互状态，并把焦点主动转移到当前面板内；禁止对仍保留焦点的祖先节点使用 `aria-hidden`

 ---

@@ -210,7 +209,7 @@
 1. 设置继续采用当前账号弹窗基础形态即可
 2. 移动端优先底部弹层，桌面端可居中弹窗
 3. 设置首页只保留“主题外观”“账号信息”两个入口，不再单独展示安全状态、登录设备、操作记录入口
-4. “账号信息”二级面板直接承载账号概况、安全状态、登录设备、操作记录四块内容，移动端优先纵向滚动，桌面端保持同一面板内稳定扫读
+4. “账号信息”二级面板直接承载账号概况、安全状态、登录设备、操作记录与退出动作，移动端优先纵向滚动，桌面端保持同一面板内稳定扫读
 5. 更换手机号必须通过独立操作面板完成，不再使用当前面板内联展开表单
 6. 危险操作按钮与普通按钮必须明显区分
 7. 设置首页标题处禁止展示手机号、脱敏手机号或手机号形态的 displayName
--- a/docs/technical/AI_CHARACTER_ANIMATION_TECHNICAL_SOLUTION_2026-04-04.md
+++ b/docs/technical/AI_CHARACTER_ANIMATION_TECHNICAL_SOLUTION_2026-04-04.md
@@ -279,7 +279,7 @@
 - `run / attack` 是当前固定动作入口里的基础必生成动作
 - `idle / die` 改为可选增强动作，不再作为资产完成度硬门槛
 - `idle` 缺失时运行时默认使用主图静止
- `die` 缺失时运行时默认播放一段基于主图的倒地过渡动画，并最终停在翻转倒地姿态
+- `die` 缺失时运行时默认播放一段基于主图的向后倒地过渡动画，并通过轻微过冲回落让动作更自然，最终停在翻转倒地姿态
 - 技能动作不走固定按钮，但对当前角色 `skills` 中的每个技能都属于必生成动作

 ## 5.3 补充路线：腾讯云相关能力
@@ -968,7 +968,7 @@ draft
 | `attack`                        | 必填     | 模板生成                                                   |
 | `skills[*].actionPreviewConfig` | 必填     | 技能编辑面板逐个生成                                       |
 | `idle`                          | 可选     | 模板生成；缺失时默认主图静止                               |
-| `die`                           | 可选     | 模板生成；缺失时默认主图倒地过渡动画，最终停在翻转倒地姿态 |
+| `die`                           | 可选     | 模板生成；缺失时默认主图向后倒地过渡动画，带轻微过冲回落，最终停在翻转倒地姿态 |

 这里“必填”指的是：

--- a/docs/technical/SCENE_MULTI_ACT_CREATOR_IMPLEMENTATION_PROGRESS_2026-04-20.md
+++ b/docs/technical/SCENE_MULTI_ACT_CREATOR_IMPLEMENTATION_PROGRESS_2026-04-20.md
@@ -4,15 +4,16 @@

 ## 1. 本轮落地范围

-本轮先完成 `scene_chapter` 的第一批基础链路，让“场景章节 -> 多幕 -> 主角色 -> 幕背景/相遇 NPC”真正进入现有创作工具和草稿系统。
+本轮先完成场景多幕的第一批基础链路，让“场景章节 -> 多幕 -> 主角色 -> 幕背景/相遇 NPC”真正进入现有创作工具与运行时。

-本轮目标不是一次性做完 PRD 全量能力，而是先把下面这条主干打通：
+本轮目标不是一次性做完 PRD 全量能力，而是先把下面两条主干打通：

 1. 草稿层可以承载 `scene chapter / scene act`
-2. 草稿编译器可以把 `scene_chapter` 编译成正式卡片
-3. 创作页可以看到、打开、编辑 `scene_chapter`
-4. 编辑后的幕信息可以正确写回草稿
+2. 后端可以把 `scene_chapter` 编译成正式蓝图
+3. 创作者可以在现有场景编辑弹层里看到并编辑多幕配置
+4. 编辑后的幕信息可以正确写回 `sceneChapterBlueprints`
 5. 运行时共享层先具备读取幕背景、主角色、相遇 NPC 池的基础能力
+6. 当前幕主角色的负好感 `5` 轮聊天限制先形成首个可运行闭环

 ## 2. 本轮已落地

@@ -55,43 +56,62 @@

 `server-node/src/services/customWorldAgentChangeSummaryService.ts` 也已支持解析 `scene_chapter` 标题。

-## 2.4 创作页展示
+## 2.4 场景编辑器接入

 前端已完成第一批接入：

-1. 草稿抽屉正式加入 `scene_chapter` 分组
-2. `scene_chapter` 分组顺序位于 `chapter` 后、`thread` 前
-3. 详情面板已支持 `场景章节` 类型标签
-4. 幕背景 section 在详情面板里会直接渲染图片预览
-5. 编辑面板已支持幕摘要 / 相遇 NPC / 幕目标 / 过渡钩子等动态多行字段
+1. `scene_chapter` 不再作为独立 Tab / 独立卡片暴露给创作者
+2. 多幕配置已内嵌到 `CustomWorldEntityEditorModal.tsx` 的 `LandmarkEditor`
+3. 单幕编辑已从文本表单切成“背景大图预览 + 3 个角色槽位”的轻量交互
+4. “幕标题 / 幕摘要 / 幕目标 / 过渡钩子”已从场景手工编辑区移除，继续留在草稿生成与编译层
+5. 角色槽位已改成直接叠在幕背景图上的站位式预览，每个角色只显示形象与名称
+6. 每幕背景图与角色槽位都走独立弹窗，不做卡片内联展开
+7. 角色槽位会把第一槽位写回 `primaryNpcId`，其余槽位顺序压缩写回 `encounterNpcIds`
+8. 每幕已补上“幕预览”入口，点击后会以独立全屏层启动当前幕运行时预览
+9. 保存场景时会把幕配置同步写回 `CustomWorldProfile.sceneChapterBlueprints`

 ## 2.5 运行时基础层

-本轮同步补齐了幕运行的基础读取能力，便于下一轮继续接游戏流程：
+本轮同步补齐了幕运行的基础读取能力：

 1. 当前幕背景图优先覆盖场景默认背景
 2. 当前幕相遇 NPC 池可参与场景相遇过滤
 3. 当前幕主角色与负好感有限聊天的判定 helper 已建立
 4. 场景预览层已能识别“负好感主角色不直接自动开战”的基础分支
+5. 编辑器内幕预览会把当前幕直接装配进真实游戏壳，而不是走静态假页面
+6. 幕编辑中的 3 个角色槽位已进一步收敛成贴在背景图上的站位式角色预览，交互与幕预览保持同一位置语义，只显示角色形象与名称
+7. 幕预览运行时已补 custom world NPC 的视觉兜底链路，优先使用 `visual / imageSrc` 渲染，避免角色形象或动画空白
+8. 当前幕小预览已调整为左侧玩家、右侧敌对/相遇角色的构图，NPC 站位采用一前两后
+9. 新增幕默认只带 1 个主角色，后续槽位由创作者按需补充
+10. 小预览里的名字已移动到角色头顶，角色渲染不再带方形底板，避免遮挡场景背景
+
+## 2.6 负好感主角色有限聊天闭环
+
+本轮已把 PRD 里的第一版运行时闭环接到现有游戏流程：
+
+1. `StoryEngineMemoryState.currentSceneActState` 会在进入场景章节时初始化到首幕
+2. 当前幕主角色若好感度小于 `0`，相遇后不再直接进入敌对宣言，而是进入有限聊天态
+3. 有限聊天态会把 `turnLimit / remainingTurns / limitReason` 透传到前后端聊天链路
+4. 第 `5` 轮会由后端 prompt 强约束生成“铺垫式收束”回复，不再继续生成下一轮聊天建议
+5. 第 `5` 轮返回后，前端会自动清掉 `npcChatState`，隐藏输入框，并给出 `继续` 的后续推进入口
+6. Adventure 面板会显示当前幕标题与有限聊天剩余轮数

 ## 3. 当前仍未完成

 下面这些仍属于 PRD 未完项，需要下一轮继续：

-1. 创作页里的“新增幕 / 删除幕 / 调整幕顺序”交互
-2. 背景图配置与 NPC 配置的独立面板化交互
-3. 发布期 `qualityFindings` / blocker 的正式接入
-4. `SceneActRuntimeState` 的完整推进与持久化
-5. 当前幕主角色负好感 `5` 轮聊天限制的前后端完整闭环
-6. 第 `5` 轮“铺垫式收束”提示与强制退出聊天态
-7. 幕切换后的系统提示与 Adventure 面板状态展示
+1. 发布期 `qualityFindings` / blocker 的正式接入
+2. `SceneActRuntimeState` 的完整推进、跨幕推进规则与持久化
+3. 幕切换后的系统提示、切幕触发条件与背景/相遇对象的完整联动
+4. 高好感主角色“无限轮聊天”与更多委托触发细则的专项验证
+5. Agent 聊八锚点 -> 生成草稿 -> 场景内多幕配置的整条创作闭环仍需继续打磨

 ## 4. 下一轮建议顺序

 建议下一轮按下面顺序继续：

-1. 先补 `SceneActRuntimeState` 初始化与幕推进
-2. 再接 `npcEncounterActions / aiService / chatOrchestrator` 的负好感有限聊天闭环
-3. 最后补创作页的幕增删改序和独立配置面板
+1. 先补 `SceneActRuntimeState` 的跨幕推进规则与持久化
+2. 再补发布期 blocker / quality findings
+3. 最后补高好感委托验证与 Agent 创作闭环

-这样可以先把“能跑”补齐，再把“编辑体验”补完整。
+这样可以先把“能跑”继续扩成“能切幕”，再把“发布质量门槛”和“完整创作闭环”补完整。