Genarrative/docs/reference/CUSTOM_WORLD_TEMPLATE_DEPENDENCY_INVENTORY_2026-04-08.md

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

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

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