Simplify custom world result editing controls

2026-04-08 19:07:46 +08:00
parent bd9fdcbe31
commit a02f7b6414
125 changed files with 8804 additions and 1462 deletions
--- a/docs/reference/CUSTOM_WORLD_TEMPLATE_DEPENDENCY_INVENTORY_2026-04-08.md
+++ b/docs/reference/CUSTOM_WORLD_TEMPLATE_DEPENDENCY_INVENTORY_2026-04-08.md
@@ -0,0 +1,398 @@
+# 自定义世界依赖的模板设定清单
+
+更新时间：`2026-04-08`
+
+## 0. 这份清单回答什么
+
+这份文档只回答一个问题：
+
+**当前仓库里，自定义世界仍然依赖哪些“模板世界设定”。**
+
+这里的“模板世界设定”不是指玩家还能进入的 `武侠 / 仙侠` 预设世界流程，而是指：
+
+1. 自定义世界在生成时仍借用哪些模板锚点。
+2. 自定义世界在运行时仍复用哪些模板 schema、词库、怪物池、角色模板、图片参考池。
+3. 哪些引用是“必须保留”，否则会直接伤到自定义世界。
+4. 哪些引用只是编辑器 / 审计 / 测试残留，不属于自定义世界主链硬依赖。
+
+一句话结论先说：
+
+**当前主流程虽然已经不再让玩家进入武侠 / 仙侠预设世界，但自定义世界底层仍明确依赖“模板世界锚点层”。**
+
+---
+
+## 1. 依赖总览
+
+自定义世界当前仍依赖的模板设定，主要分成 7 类：
+
+1. 模板世界锚点类型
+2. 主题判定与规则回退
+3. 属性 schema 与术语体系
+4. 角色模板与技能骨架
+5. 场景图参考池与营地图像逻辑
+6. 怪物 / 敌对实体模板池
+7. 叙事 ThemePack 与生成 prompt 兼容字段
+
+除此之外，还有一类是：
+
+8. 编辑器 / 审计 / 测试中的残留模板引用
+
+这类不一定属于自定义世界正式运行时硬依赖，但当前仓库里仍然存在。
+
+---
+
+## 2. 核心硬依赖
+
+## 2.1 模板世界锚点类型
+
+这是最底层、也是目前最不能直接删的部分。
+
+相关文件：
+
+- `src/types/core.ts`
+- `src/types/customWorld.ts`
+- `src/services/customWorld.ts`
+- `src/data/customWorldLibrary.ts`
+
+当前依赖点：
+
+1. `WorldType.WUXIA / WorldType.XIANXIA / WorldType.CUSTOM`
+   - 自定义世界虽然运行时是 `CUSTOM`，但其模板锚点仍通过 `WUXIA / XIANXIA` 表达。
+
+2. `WorldTemplateType = Exclude<WorldType, WorldType.CUSTOM>`
+   - 这就是“自定义世界挂靠哪个模板锚”的类型定义。
+
+3. `CustomWorldProfile.templateWorldType`
+   - 当前自定义世界 profile 里明确保存这个字段。
+   - 它是兼容字段，但目前仍被多个系统直接消费。
+
+4. `buildCustomWorldFrameworkPrompt(...)`
+   - 生成框架 prompt 仍要求模型输出：
+     - `"templateWorldType": "WUXIA|XIANXIA"`
+
+5. `customWorldLibrary.normalizeProfile(...)`
+   - 本地读取自定义世界时，也会把 `templateWorldType` 归一化到：
+     - `WUXIA`
+     - `XIANXIA`
+
+结论：
+
+**如果直接删掉 `WUXIA / XIANXIA / WorldTemplateType / templateWorldType` 这层，自定义世界的生成、存档归一化和多处运行时回退都会直接断。**
+
+---
+
+## 2.2 主题判定与规则回退
+
+相关文件：
+
+- `src/services/customWorldTheme.ts`
+- `src/data/customWorldRuntime.ts`
+- `src/services/storyEngine/themePack.ts`
+
+当前依赖点：
+
+1. `detectCustomWorldThemeMode(profile)`
+   - 先把自定义世界识别成：
+     - `martial`
+     - `arcane`
+     - `machina`
+     - `tide`
+     - `rift`
+     - `mythic`
+
+2. `resolveCustomWorldAnchorWorldType(profile)`
+   - 再把主题模式压回模板锚点：
+     - `arcane -> XIANXIA`
+     - 其它默认回到 `WUXIA`
+
+3. `resolveRuleWorldType(worldType, customWorldProfile)`
+   - 这是当前运行时非常关键的桥接函数。
+   - 当 `worldType === CUSTOM` 时，它会把规则世界解析成模板锚点。
+   - 如果没有 profile，还会默认回退到 `WUXIA`。
+
+4. `buildThemePackFromWorldProfile(profile)`
+   - 自定义世界最终的 `ThemePack` 并不是纯空中生成。
+   - 它是从预设的主题包底板开始，再用自定义世界自己的词汇补进去。
+
+结论：
+
+**自定义世界现在不是完全脱离模板世界独立运行，而是“先判定自己的主题模式，再回落到模板锚点做规则支撑”。**
+
+---
+
+## 2.3 属性 schema 与术语体系
+
+相关文件：
+
+- `src/data/worldAttributeSchemas.ts`
+- `src/services/attributeSchemaGenerator.ts`
+- `src/services/customWorldPresentation.ts`
+- `src/data/economy.ts`
+
+当前依赖点：
+
+1. `PRESET_WORLD_ATTRIBUTE_SCHEMAS`
+   - 当前仓库里有两套预设属性 schema：
+     - 武侠：`江湖六脉`
+     - 仙侠：`灵界六轴`
+
+2. `getPresetWorldAttributeSchema(...)`
+   - 多个地方仍然用它作为生成自定义世界 schema 的参考底板。
+
+3. `generateWorldAttributeSchema(...)`
+   - 自定义世界自己的 attribute schema 虽然是生成的，
+   - 但内部会参考预设世界 schema 的槽位结构和 fallback 逻辑。
+
+4. `getAttributeLabelsForWorld(...) / getResourceLabelsForWorld(...)`
+   - 如果当前没有显式自定义 world presentation，会按 `WUXIA / XIANXIA` 走回退术语。
+
+5. `getCurrencyName(...) / getInitialPlayerCurrency(...)`
+   - 经济层仍按模板世界决定初始货币命名和初始数量。
+
+结论：
+
+**自定义世界现在虽然有自己的 presentation 和 attribute schema，但模板世界仍然是它们的 fallback 和参考骨架。**
+
+---
+
+## 2.4 角色模板与技能骨架
+
+相关文件：
+
+- `src/data/characterPresets.ts`
+
+当前依赖点：
+
+1. `PRESET_CHARACTERS`
+   - 自定义世界的可玩角色 / 场景角色运行时形态，是从现有预设角色模板变体化出来的。
+
+2. `pickCustomWorldRoleTemplateCharacter(...)`
+   - 会从 `PRESET_CHARACTERS` 里挑一个模板角色作为骨架。
+
+3. `buildCustomWorldRoleCharacter(...)`
+   - 会把自定义世界角色内容覆盖到模板角色上：
+     - 名字
+     - 背景
+     - 描述
+     - 技能文案
+     - 外观
+     - 等等
+
+4. `buildCustomWorldSkillVariant(...)`
+   - 自定义世界角色技能的数值和命名，也是从模板技能定义变体生成出来的。
+
+5. `adventureOpenings`
+   - 当前实现里，自定义世界角色 opening 同时写入：
+     - `WUXIA`
+     - `XIANXIA`
+     - `CUSTOM`
+   - 说明角色开局结构仍沿用模板世界的旧接口习惯。
+
+6. `getCharacterHomeSceneId / getCharacterNpcSceneIds`
+   - 对 `CUSTOM` 路径已经优先走自定义世界自己的 landmark 映射；
+   - 但非 CUSTOM 路径仍大量依赖模板世界的基础场景绑定表。
+
+结论：
+
+**自定义世界角色并不是从零独立建模，而是“自定义内容 + 预设角色模板骨架”的组合。**
+
+---
+
+## 2.5 场景图参考池与营地图像逻辑
+
+相关文件：
+
+- `src/data/customWorldVisuals.ts`
+- `src/services/customWorldCamp.ts`
+
+当前依赖点：
+
+1. `WUXIA_SCENE_IMAGE_REFERENCES`
+2. `XIANXIA_SCENE_IMAGE_REFERENCES`
+3. `WORLD_SCENE_IMAGE_REFERENCES`
+
+当前自定义世界场景图不是纯随机抽图，而是：
+
+1. 先确定模板锚点世界
+2. 再从对应模板世界的场景参考词池里匹配：
+   - 场景名称
+   - 关键词
+   - 图片参考
+
+具体依赖：
+
+1. `collectWorldSceneImagePool(worldType)`
+   - 按模板世界从背景包里抽参考池。
+
+2. `buildSceneReferencePool(worldType)`
+   - 用武侠 / 仙侠各自的场景参考名和关键词构造图像匹配池。
+
+3. `getDefaultCustomWorldSceneImage(...)`
+   - 自定义世界 landmark / camp / 场景默认图，会基于模板世界参考池挑选。
+
+4. `resolveCustomWorldCampSceneImage(profile)`
+   - 开局归处场景图也依赖 `templateWorldType` 和主题判定。
+
+结论：
+
+**当前自定义世界的场景视觉虽然是独立输出，但“默认图像匹配逻辑”仍然是挂在武侠 / 仙侠两套参考池上的。**
+
+---
+
+## 2.6 怪物 / 敌对实体模板池
+
+相关文件：
+
+- `src/data/customWorldNpcMonsters.ts`
+- `src/data/hostileNpcPresets.ts`
+- `src/data/hostileNpcs.ts`
+- `src/data/scenePresets.ts`
+
+当前依赖点：
+
+1. `resolveCustomWorldNpcMonsterPreset(...)`
+   - 自定义世界中带敌意的 NPC / 怪物，会从模板怪物池里找最接近的 preset。
+
+2. `getMonsterPresetPool(worldType?)`
+   - 如果传了 worldType，就取对应模板世界的怪物池。
+   - 如果没传，就把武侠和仙侠怪物池拼起来一起选。
+
+3. `resolveRuleWorldType(...)`
+   - `hostileNpcPresets.ts` 和 `hostileNpcs.ts` 在处理 `CUSTOM` 时，会先解析到模板锚点，再决定取哪个怪物 preset / schema。
+
+4. `getMonsterPresetsByWorld(...) / getHostileNpcPresetById(...)`
+   - 自定义世界的运行时怪物表现，目前仍然依赖这套模板怪物 preset 查询接口。
+
+结论：
+
+**自定义世界当前没有完全独立的怪物体系，仍然是基于武侠 / 仙侠预设怪物池做匹配和包装。**
+
+---
+
+## 2.7 叙事 ThemePack 与 prompt 兼容字段
+
+相关文件：
+
+- `src/services/customWorld.ts`
+- `src/services/storyEngine/themePack.ts`
+- `src/services/ai.ts`
+
+当前依赖点：
+
+1. 自定义世界框架 prompt 仍强制要求 `templateWorldType`
+2. `normalizeCustomWorldGenerationFramework(...)`
+   - 会把模型输出的模板世界字段规范化
+3. `buildThemePackFromWorldProfile(...)`
+   - 会以预设主题包为底，再混入自定义世界词汇
+4. `ai.ts` 里某些 fallback 逻辑仍根据 `templateWorldType` 决定主题包回退
+
+结论：
+
+**自定义世界的 AI 生成链条目前明确假设“世界框架里存在模板锚点字段”。**
+
+---
+
+## 3. 运行时硬依赖 vs 非运行时残留
+
+## 3.1 自定义世界正式运行时硬依赖
+
+这些目前不能轻易删：
+
+1. `WorldType.WUXIA / WorldType.XIANXIA / WorldTemplateType`
+2. `CustomWorldProfile.templateWorldType`
+3. `detectCustomWorldThemeMode / resolveCustomWorldAnchorWorldType / resolveRuleWorldType`
+4. `PRESET_WORLD_ATTRIBUTE_SCHEMAS / getPresetWorldAttributeSchema`
+5. `PRESET_CHARACTERS` 作为自定义角色模板骨架
+6. 武侠 / 仙侠场景图参考池
+7. 武侠 / 仙侠怪物 preset 池
+8. `buildThemePackFromWorldProfile` 的模板底板
+9. `customWorld.ts` 里生成框架 prompt 的 `templateWorldType` 字段约束
+
+## 3.2 不是主流程硬依赖，但仓库里仍存在的残留引用
+
+这些更多是编辑器 / 工具 / 审计 / 测试引用：
+
+1. 预设编辑器
+   - `preset-editor/*`
+
+2. 一些开发工具页
+   - 例如 `ItemCatalogEditor.tsx`
+   - `StateFunctionEditor.tsx`
+
+3. 审计 / 报告工具
+   - `storyAuditReport.ts`
+
+4. 各类基于武侠 / 仙侠的测试
+
+5. 一些 UI 图标与世界按钮贴图
+   - 例如 `uiAssets.ts` 里的图标键位仍保留
+
+这些不一定影响当前玩家主流程，但如果目标是“代码库级彻底清理”，它们也需要后续处理。
+
+---
+
+## 4. 当前最不能动的边界
+
+如果前提是：
+
+**不要动素材和自定义世界的任何设定。**
+
+那么当前最不能直接删除的是：
+
+1. `templateWorldType`
+2. `WorldTemplateType`
+3. `resolveRuleWorldType(...)`
+4. `detectCustomWorldThemeMode(...)`
+5. `resolveCustomWorldAnchorWorldType(...)`
+6. `PRESET_WORLD_ATTRIBUTE_SCHEMAS`
+7. `PRESET_CHARACTERS`
+8. `customWorldVisuals.ts` 里的模板场景参考池
+9. `customWorldNpcMonsters.ts` 对模板怪物池的映射
+10. `themePack.ts` 的模板底板
+
+原因很简单：
+
+**这些不是“预设世界可玩入口”，而是自定义世界当前仍在使用的模板支撑层。**
+
+---
+
+## 5. 可以安全理解为“已从玩家主流程移除”的部分
+
+目前已经可以视作从正式玩家流程移除的，是：
+
+1. 世界选择页里的武侠 / 仙侠入口
+2. 主流程的世界选择 API
+3. 继续游戏入口中的武侠 / 仙侠旧存档
+
+但这不等于：
+
+- 代码库内部已经完全不再依赖模板世界
+
+这两件事要分开看。
+
+---
+
+## 6. 最后结论
+
+当前仓库里，自定义世界对模板设定的依赖，本质上是：
+
+**“不再复用预设世界的玩家入口，但仍然复用预设世界的模板支撑层。”**
+
+最准确的理解是：
+
+1. 玩家已经不能直接进入武侠 / 仙侠预设世界
+2. 但自定义世界仍借用武侠 / 仙侠作为：
+   - 模板锚点
+   - 规则回退
+   - 属性 schema 参考
+   - 角色模板骨架
+   - 场景图参考池
+   - 怪物模板池
+   - ThemePack 底板
+
+所以如果后续要继续“深度清理”，正确顺序不是直接删光 `WUXIA / XIANXIA`，而应该是：
+
+1. 先识别哪些是主流程入口，哪些是模板支撑层
+2. 再决定是否要把自定义世界从“模板依赖型”重构成“完全自足型”
+
+在那一步没做完之前，模板支撑层仍然是自定义世界当前可用性的真实依赖。