GenarrativeAI/Genarrative
5
0
Fork 0
Code Issues Pull Requests Actions 5 Packages Projects Releases Wiki Activity

1
Some checks failed
CI / verify (push) Has been cancelled
Details

Browse Source
This commit is contained in:
高物
2026-04-20 15:45:14 +08:00
parent 8a7bd90458
commit 1c72066bab
73 changed files with 7814 additions and 1018 deletions
Download Patch File Download Diff File Expand all files Collapse all files

379
docs/audits/CHARACTER_ASSET_PROMPT_CHAIN_AUDIT_2026-04-20.md Normal file
View File

@@ -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 主链只用了前者，导致出现明显的冗余和认知混乱。**

1
docs/audits/README.md
View File

@@ -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)：未引用垃圾、旧入口残留、前后端双份真相与后端迁移项的专项审计。

8
docs/design/COMPANION_FIRST_CONTACT_RELATIONSHIP_AND_PRIVATE_CHAT_DESIGN_2026-04-04.md
View File

@@ -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 生成
也就是说：

24
docs/design/LEVEL_PROGRESS_AND_CHAPTER_NPC_AUTO_SCALING_DESIGN_2026-04-20.md
View File

@@ -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. 目标

6
docs/design/PLATFORM_HOME_PUBLIC_BROWSE_AND_LOGIN_MODAL_GATING_DESIGN_2026-04-19.md
View File

@@ -127,6 +127,12 @@
- 未登录：弹出登录弹窗，并缓存 `action`
- 登录成功：自动执行缓存的 `action`
账号入口补充约束：
- 不再提供 `AuthGate` 层右上角固定悬浮的全局登录 / 账号信息入口
- 登录触发统一来自页面内受保护动作、个人页、存档页等明确入口
- 账号信息面板只通过页面内按钮打开，不在平台右上角常驻悬浮
## 4.2 平台首页数据加载
`PreGameSelectionFlow` 在未登录时只读取：

83
docs/experience/AGENT_UI_CHANGELOG.md
View File

@@ -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`。_

2
docs/experience/MOBILE_UI_DEV_EXPERIENCE.md
View File

@@ -94,6 +94,8 @@
- 全局账号信息条挂在这里，会直接压住场景、敌人血条或顶部提示，手机端尤其明显。
- 结论：
账号入口应收回平台首页、个人页或设置面板，不要在实际冒险主场景常驻悬浮显示。
- 当前仓库已进一步收口为：
不再提供右上角全局账号悬浮条，统一只保留页面内入口与独立账号面板。
## 5. 队伍面板经验

4
docs/prd/AI_CHARACTER_VISUAL_ANIMATION_MVP_PRD_2026-04-04.md
View File

@@ -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` | 可选 | 缺失时默认走主图向后倒地过渡动画，最终停在翻转倒地姿态 |
这里“必生成”指的是：

2
docs/prd/AI_NATIVE_AGENT_FIRST_CUSTOM_WORLD_CREATOR_PHASE5_IMPLEMENTATION_PLAN_2026-04-14.md
View File

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

4
docs/prd/AI_NATIVE_AGENT_FIRST_CUSTOM_WORLD_CREATOR_PRD_2026-04-12.md
View File

@@ -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` 缺失时运行时默认播放主图向后倒地过渡动画，并通过轻微过冲回落让动作更自然，最终停在翻转倒地姿态
说明：

152
docs/prd/AI_NATIVE_SCENE_MULTI_ACT_CREATOR_AND_GAMEPLAY_FLOW_PRD_2026-04-20.md
View File

@@ -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 列表，第一位自动成为主角色。

5
docs/prd/AI_NATIVE_UNIFIED_ROLE_ATTRIBUTE_SYSTEM_PRD_2026-04-02.md
View File

@@ -963,6 +963,11 @@ behaviorVectors: Array<{
3. 一句解释文本
4. 怪物的“敌意关系状态”
补一条 UI 落地约束：
- 包括选角流、角色面板、详情弹窗在内，所有属性展示入口都必须直接读取当前世界的 `WorldAttributeSchema.slots`。
- 禁止回退显示 `力量 / 敏捷 / 智力 / 精神` 这类旧四维占位文案，除非该入口明确处于旧数据迁移调试模式。
## 11.3 对玩家的信息揭示分层
不是所有 NPC 初见时都展示完整属性。

21
docs/prd/MY_TAB_SETTINGS_AND_SECURITY_PRD_2026-04-16.md
View File

@@ -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

4
docs/technical/AI_CHARACTER_ANIMATION_TECHNICAL_SOLUTION_2026-04-04.md
View File

@@ -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` | 可选 | 模板生成；缺失时默认主图向后倒地过渡动画，带轻微过冲回落，最终停在翻转倒地姿态 |
这里“必填”指的是：

66
docs/technical/SCENE_MULTI_ACT_CREATOR_IMPLEMENTATION_PROGRESS_2026-04-20.md
View File

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