# 自定义世界依赖的模板设定清单

更新时间：`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. 再决定是否要把自定义世界从“模板依赖型”重构成“完全自足型”

在那一步没做完之前，模板支撑层仍然是自定义世界当前可用性的真实依赖。