Genarrative/docs/design/EQUIPMENT_BUILD_AND_FORGE_LOOP_SYSTEM_DESIGN.md

配装构筑 + 合成/锻造闭环详细设计

更新时间：2026-03-25

0. 设计前提

这份方案基于当前仓库已经存在的运行时结构来设计，不另起一套独立系统。

• 现有物品结构已经有 InventoryItem.tags、statProfile、useProfile、buildProfile。
• 现有装备位只有 weapon / armor / relic 三槽，因此本期套装与 build 成型必须围绕 2 件和 3 件完成。
• 现有战斗结算已经有 functionEffect.damageMultiplier / incomingDamageMultiplier，但 equipmentEffects.ts 中的装备数值聚合仍然基本为空壳。
• 现有素材库中已经出现 setId、setName、pieceName、synergy 等 build 元数据，但尚未进入真实伤害结算。
• 现有角色、怪物、消耗品、掉落、宝藏、NPC 交易都已经形成了资源入口，适合继续补成“获取 -> 拆解 -> 锻造 -> 配装 -> 战斗 -> 再获取”的闭环。

因此，本方案的目标不是“再做一层 UI”，而是补齐以下 4 层：

1. 标签规范化层：把当前中英混用、结构标签与语义标签混用的问题拆开。
2. 语义相似度层：用 embedding 相似度把“相近标签”自动组织为 build 与套装簇。
3. 伤害修正层：把标签结果稳定接入当前伤害公式。
4. 合成/锻造闭环：让掉落、材料、装备、buff、交易真正循环起来。

1. 结合当前系统的落地判断

1.1 现有可复用基础

• src/types.ts
  • 已有 ItemStatProfile
  • 已有 ItemUseProfile
  • 已有 ItemBuildProfile
  • 已有 EquipmentLoadout
  • 已有 GameState.playerEquipment
• src/data/itemDesign.ts
  • 已经能为装备自动生成 buildProfile
  • 已经有 setId / setName / pieceName / synergy
  • 已经有一批 role/tag 原型，例如 assassin / caster / ward / fate
• src/data/monsterPresets.ts
  • 已经有 habitatTags
  • 已经有较完整的 lootTable
• src/data/treasureInteractions.ts
  • 已经有材料、消耗品、稀有品产出入口
• src/hooks/useCombatFlow.ts
  • 玩家、同伴、怪物三条伤害结算路径已经齐备
  • 只差把 build 结果统一注入 damage

1.2 当前缺口

• 当前 InventoryItem.tags 同时承担了“分类标签”和“战斗语义标签”，例如 weapon / armor / relic / material / mana / healing 混在一起。
• 当前角色正式数据结构里没有稳定的 combatTags，角色标签主要还停留在 UI 展示常量。
• 当前怪物只有 habitatTags，更适合掉落/生态，不适合直接进入伤害 build。
• 当前技能/物品可以恢复数值，但还不能稳定施加“限回合 build buff 标签”。
• 当前 getEquipmentBonuses() 没有真正读取 statProfile + buildProfile，导致 build 无法进入伤害。

结论：

• 现有系统已经具备 build 系统的数据骨架。
• 真正需要补的是“标签语义层”和“统一伤害入口”。

2. Build 标签设计原则

2.1 标签必须贴近实体语义

参与 build 的标签应尽量是玩家能直觉理解的“风格词”，而不是纯系统词。

推荐使用：

• 行为风格：快剑、突进、追击、反击、蓄力、控场
• 输出方式：重击、连段、远射、雷法、符阵、毒雾
• 生存节奏：护体、守御、回复、续战、压血
• 材料/流派气质：寒铁、星砂、灵木、骨纹、镇邪
• 阵营/身份风格：先锋、游击、法修、命纹、统御

不推荐直接把以下内容当作伤害 build 标签：

• weapon
• armor
• relic
• material
• piece:weapon
• world:xianxia

这些更适合保留为筛选、配方、掉落、编辑器过滤用的结构标签。

2.2 标签分层

建议把标签拆成三层：

层级	用途	示例
结构标签	分类、筛选、配方、存档兼容	weapon、armor、material、set:steel
战斗语义标签	进入 build 相似度和伤害修正	快剑、突进、护体、雷法
生态/素材标签	掉落、锻造、配方倾向	矿道、雾林、寒铁、星砂

推荐约束：

• InventoryItem.tags 继续保留结构标签与通用筛选标签。
• ItemBuildProfile.tags 只保留会进入 build 计算的语义标签。
• MonsterPreset.habitatTags 保留生态用途，不直接参与伤害。
• 新增 combatTags 给角色/怪物，用于战斗 build。

2.3 中英混用兼容

当前素材生成中已有较多英文 role/tag，角色 UI 和自定义世界中又偏中文标签，因此需要加一层标签规范化。

建议建立 buildTagRegistry：

type BuildTagDefinition = {
  id: string;              // ASCII 稳定 id，例如 "quickblade"
  label: string;           // 展示名，例如 "快剑"
  category: "role" | "style" | "resource" | "element" | "defense" | "craft";
  aliases: string[];       // 兼容 assassin / duelist / 快剑流 等历史写法
  description: string;     // 供 embedding 使用
};

示例映射：

现有值	规范标签
assassin	快袭 / 切后 / 突进
duelist	快剑 / 连段 / 对拼
vanguard	先锋 / 稳压 / 护体
ward	守御 / 镇邪 / 护体
berserker	压血 / 重击 / 爆发
caster	法修 / 法力 / 远程
support	护持 / 回复 / 增益
fortress	重甲 / 格挡 / 反击
fate	命纹 / 机缘 / 冷却
commander	统御 / 均衡 / 队伍增益

3. 标签来源设计

3.1 装备标签

装备是 build 的主来源，但要区分“结构标签”和“build 标签”。

建议：

• 武器、护甲、饰品各自最多提供 2 个核心 build 标签。
• 若装备存在 setId，运行时根据套装件数额外生成“合成标签”。
• 同一标签在多个装备上重复出现时，只记一次，不按件数无限叠加。

装备运行时推荐结构：

type RuntimeEquipmentBuildSource = {
  itemId: string;
  slot: "weapon" | "armor" | "relic";
  coreTags: string[];
  setId?: string;
  setName?: string;
  forgeRank?: number;
};

3.2 角色/怪物标签

角色和怪物都应该有自己的 combatTags。

建议：

• 角色固定提供 2~3 个核心战斗语义标签。
• 怪物固定提供 2~3 个核心战斗语义标签。
• habitatTags 不直接参与 build 伤害，而是决定掉落材料簇、锻造路线和部分弱点设计。

例子：

• 剑系角色：快剑、突进、压制
• 重甲怪物：重甲、震击、守势
• 雾林怪物生态标签：雾林、湿毒、潜伏
  • 其中 湿毒、潜伏 可提升为 combatTags
  • 雾林 保留为生态/掉落标签

3.3 Buff 标签

buff 标签是 build 的短时放大器，也是技能与物品进入构筑闭环的关键。

buff 标签来源：

• 技能施加的限回合标签
• 消耗品施加的限回合标签
• 锻造出的铭刻/附魔效果施加的限回合标签

建议新增：

type TimedBuildBuff = {
  id: string;
  sourceType: "skill" | "item" | "forge";
  sourceId: string;
  name: string;
  tags: string[];
  durationTurns: number;
  maxStacks?: number;
};

推荐时长：

• 强爆发 buff：1~2 回合
• 节奏/机动 buff：2~3 回合
• 防御/续航 buff：2~4 回合

重复规则：

• 同名 buff 默认刷新持续时间，不新增一套完全重复标签。
• 不同来源但规范化后相同的标签，只保留一个 build 标签实例。
• 重复来源只提高优先级或刷新，不增加额外 +1 基础值。

4. 语义 embedding 与套装 build 形成方式

4.1 为什么要引入 embedding

如果只靠显式 setId，build 会很死板。

引入 embedding 后，可以让这些组合自然成型：

• 快剑 + 突进 + 追击 + 风行
• 重甲 + 护体 + 守御 + 反击
• 雷法 + 法器 + 过载 + 法力

也就是说：

• 显式套装仍然存在
• 隐式语义套装也能成立
• 两者都走同一套 build 标签计算，不必再写第二套特殊规则

4.2 embedding 计算对象

不要对每个物品实例现算 embedding，而是只对“规范标签定义”计算。

推荐流程：

1. 为 buildTagRegistry 中每个规范标签生成一条 embedding 文本。
2. 文本内容由 label + aliases + description 组成。
3. 预计算标签相似度矩阵并缓存到本地数据文件。
4. 运行时只读相似度，不现算模型。

示例 embedding 文本：

快剑：以高速轻兵器、连续出手、贴身追击为核心的近战风格；别名 duelist, swift blade, 快袭。

4.3 相似度函数

建议使用余弦相似度，并且只保留正向相似。

similarity(a, b) = max(0, cosine(embedding(a), embedding(b)))

建议阈值：

• < 0.35：视为无关，按 0
• 0.35 ~ 0.65：弱协同
• 0.65 ~ 0.82：强协同
• > 0.82：视为同 build 簇强关联

4.4 语义套装簇形成

推荐同时保留两种 build 成型路径：

A. 显式套装

• 依据 setId
• 2 件时生成一个合成标签：套装:<setName>
• 3 件时再生成一个进阶标签：宗匠:<setName>

由于当前 runtime 只有三槽，所以 2 件和 3 件阈值最合适。

B. 隐式语义套装

当激活标签里存在 3 个及以上标签两两相似度超过阈值时，形成“语义 build 簇”。

例如：

• 快剑
• 突进
• 追击
• 风行

它们无需拥有相同 setId，也能形成一组高相似 build。

5. 标签修正值与伤害公式

5.1 核心规则

用户给出的核心要求是：

• 每个标签修正值都是 1
• 每多一个标签修正值加一
• 同时所有标签的 1 需要额外乘上与新标签的相似度
• 修正结果作用于输出伤害

将这条规则做成稳定、顺序无关的公式，可以写成：

rawBuildScore(T) = |T| + Σ similarity(t_i, t_j)
                   (i < j)

其中：

• |T| 是激活标签数量，每个标签天然贡献 1
• 每对标签之间再贡献一段相似度分

这个公式与“新增一个标签时，额外 +1，并让旧标签的 1 再乘上与新标签的相似度”完全等价。

对应的增量写法：

score_1 = 1
score_k = score_(k-1) + 1 + Σ similarity(t_i, t_k)
          (1 <= i < k)

5.2 激活标签集的选取

为了防止标签爆炸，建议运行时只取 MAX_ACTIVE_BUILD_TAGS = 8。

推荐优先级：

1. 限回合 buff 标签
2. 角色/怪物核心标签
3. 武器 build 标签
4. 饰品 build 标签
5. 护甲 build 标签
6. 2 件/3 件套装合成标签

重复标签去重后再参与计算。

5.3 从 raw score 到伤害倍率

rawBuildScore 不直接等于伤害倍率，否则会过大。建议再做一层线性缩放与封顶。

buildDamageBonus = clamp((rawBuildScore - 1) * 0.03, 0, 0.45)
buildDamageMultiplier = 1 + buildDamageBonus

推荐解释：

• 单标签时没有 build 成型，不给明显收益
• 2~4 标签形成初步风格，获得 5%~18% 左右伤害增益
• 5~8 标签形成成熟 build，伤害增益逐步逼近 45% 上限

5.4 与当前战斗公式的接法

当前战斗中，伤害基本来自：

• 技能基础伤害
• functionEffect.damageMultiplier
• 装备 stat 值

建议统一改成：

finalOutgoingDamage =
  round(
    baseSkillDamage
    * functionDamageMultiplier
    * equipmentStatMultiplier
    * buildDamageMultiplier
  )

说明：

• equipmentStatMultiplier 来自武器/护甲/饰品的 statProfile
• buildDamageMultiplier 来自标签相似度 build
• 先乘完再 round

本期先只影响“输出伤害”。

也就是：

• 玩家攻击怪物时用玩家侧标签
• 同伴攻击怪物时用同伴侧标签
• 怪物攻击玩家/同伴时用怪物侧标签

防御端 build 抵抗可以放到下一期，不必一开始就加复杂。

5.5 示例

某角色当前激活标签为：

• 快剑
• 突进
• 追击
• 风行
• 套装:百炼争锋

假设相似度如下：

• 快剑-突进 = 0.82
• 快剑-追击 = 0.78
• 快剑-风行 = 0.65
• 突进-追击 = 0.80
• 突进-风行 = 0.72
• 追击-风行 = 0.70
• 套装标签与前四者平均相似度 0.76

则：

rawBuildScore
= 5
+ (0.82 + 0.78 + 0.65 + 0.80 + 0.72 + 0.70)
+ (0.76 * 4)
= 11.51

buildDamageBonus
= clamp((11.51 - 1) * 0.03, 0, 0.45)
= 0.3153

buildDamageMultiplier = 1.3153

若本次技能基础伤害为 28，动作倍率为 1.2，装备数值倍率为 1.14，则：

finalDamage = round(28 * 1.2 * 1.14 * 1.3153) = 50

6. 合成 / 锻造 / 回收闭环设计

6.1 闭环目标

让当前已有入口真正连起来：

• 怪物掉落
• 宝藏奖励
• NPC 交易
• 背包积累
• 装备更替
• 消耗品 buff
• 锻造与回收

形成闭环后，物品系统就不再只是“剧情资源池”，而是成长系统。

6.2 资源分层

建议把资源拆成 4 类：

类型	作用	当前可复用入口
基础材料	进入配方、升级、重铸	怪物掉落、宝藏、NPC 交易
标签精粹	决定 build 方向	拆解装备、精炼材料
套装蓝图	决定显式 setId 结果	宝藏、精英怪、任务
催化剂	提升稀有度、锁词条、转流派	稀有品、商店、Boss 掉落

6.3 推荐闭环

flowchart LR
  A["遭遇 / 战斗 / 宝藏 / 交易"] --> B["获得装备 / 材料 / 消耗品 / 蓝图"]
  B --> C["直接装备"]
  B --> D["拆解回收"]
  D --> E["基础材料"]
  D --> F["标签精粹"]
  D --> G["蓝图碎片"]
  E --> H["合成精炼材料"]
  F --> H
  G --> I["完整蓝图"]
  H --> J["锻造新装备"]
  I --> J
  J --> K["重铸 / 淬炼 / 铭刻"]
  K --> C
  C --> L["形成 build 与伤害提升"]
  L --> A

6.4 关键环节

A. 拆解

目标：

• 回收无用装备
• 提取 build 倾向
• 让玩家可以主动转流派

建议产出：

• 基础材料：按装备部位与稀有度产出
• 标签精粹：按 buildProfile.tags 产出对应流派精粹
• 套装碎片：带 setId 的装备有概率掉落

推荐规则：

• 普通/优秀：返还 1~2 基础材料 + 1 标签精粹
• 稀有/史诗：返还 2~4 基础材料 + 1~2 标签精粹
• 传说：返还 4+ 基础材料 + 2~3 标签精粹 + 套装碎片

B. 合成

目标：

• 把零散材料往更高层资源转化

推荐配方：

• 3 个同系基础材料 -> 1 个精炼材料
• 2 个相近标签精粹 -> 1 个簇催化剂
• 3 个蓝图碎片 -> 1 个完整蓝图

C. 锻造

目标：

• 制造三槽位装备
• 明确把材料生态和 build 流派联系起来

建议锻造公式：

成品 = 槽位模板 + 基础材料 + 标签精粹 + 蓝图/催化剂

推荐规则：

• 武器：决定主要输出 build 标签
• 护甲：决定生存/反击/续战方向
• 饰品：决定资源、冷却、机动、控场补短板

D. 重铸

目标：

• 保留 build 主方向
• 调整副标签

推荐规则：

• 保留主标签与 setId
• 只在同一语义簇内重掷副标签
• 花费标签精粹 + 货币

这样玩家不会因为一次重铸直接从 快剑 跳成 重甲。

E. 淬炼

目标：

• 提升已有装备而不是频繁换装

推荐效果：

• 提升 forgeRank
• 增加 statProfile
• 提高套装合成标签的优先级

F. 铭刻 / 附魔

目标：

• 让消耗品和锻造形成直接关系

推荐效果：

• 给装备附加可触发 buff 标签
• 或直接生产“一次性战斗铭符”

例子：

• 疾风符：2 回合获得 风行、突进
• 镇岳印：2 回合获得 护体、守御
• 雷纹油：1 回合获得 雷法、过载

7. 当前三槽系统下的 build 形态

由于当前只有 weapon / armor / relic 三槽，建议本期 build 以“2 件成型、3 件毕业”为主。

7.1 套装成型方式

• 1 件：只提供本件核心标签
• 2 件：生成 套装:<setName> 合成标签
• 3 件：再生成 宗匠:<setName> 进阶标签

这两个“合成标签”本质上也是普通 build 标签，因此会自动进入 embedding 相似度和伤害公式。

7.2 推荐 build archetype

build	角色/怪物核心标签	装备标签方向	buff 标签方向	锻造材料倾向
快剑追袭	快剑、突进、追击	武器补 连段，饰品补 风行	疾风、破绽	百炼钢、风羽、轻皮
重甲反击	守御、重甲、反击	护甲补 护体，饰品补 镇势	立壁、嘲压	寒铁、壳片、岩核
雷法过载	法修、雷法、法力	武器补 过载，饰品补 聚灵	引雷、蓄放	星砂、雷纹石、灵晶
命纹机缘	命纹、冷却、机缘	饰品补 连锁，护甲补 续战	转运、回转	命纹骨片、旧卷、秘印
医理续战	回复、护持、续战	护甲补 守御，饰品补 凝神	回气、清心	灵木、药囊、泉露

8. 与当前掉落和地图生态的关系

8.1 怪物生态标签不直接进伤害

当前怪物已有 habitatTags，更适合驱动：

• 掉落材料倾向
• 可锻造流派倾向
• 宝藏/地图资源分布

例如：

• 矿道 / 铸坊 / 废城 -> 寒铁、锻火、重甲
• 雾林 / 沼泽 -> 毒囊、湿毒、潜伏
• 祭坛 / 遗迹 / 古迹 -> 残卷、纹石、镇邪
• 月湖 / 灵泉 / 天河 -> 水灵、回气、法力

8.2 当前掉落表可直接扩展

当前怪物掉落里已经有很多适合闭环的原型：

• armor + material
• weapon + material
• relic + mana
• consumable + material

下一步不必推翻，只要再补：

1. 掉落物的 craftTags
2. 掉落物的 buildProfile
3. 拆解产物表

就能把这些现有掉落自然接进锻造循环。

9. 数据结构建议

9.1 类型扩展

建议在现有结构上最小扩展：

type BuildTagCategory =
  | "role"
  | "style"
  | "resource"
  | "defense"
  | "element"
  | "craft";

interface BuildTagDefinition {
  id: string;
  label: string;
  category: BuildTagCategory;
  aliases: string[];
  description: string;
}

interface ItemBuildProfile {
  role: string;
  tags: string[];          // 只放战斗语义标签
  setId?: string;
  setName?: string;
  pieceName?: string;
  synergy?: string[];
  craftTags?: string[];    // 新增：配方/材料倾向
  forgeRank?: number;      // 新增：淬炼等级
}

interface CombatTaggedActor {
  combatTags: string[];
}

interface TimedBuildBuff {
  id: string;
  sourceType: "skill" | "item" | "forge";
  sourceId: string;
  name: string;
  tags: string[];
  durationTurns: number;
}

9.2 GameState 扩展

interface GameState {
  activeBuildBuffs: TimedBuildBuff[];
}

9.3 技能与物品扩展

interface ItemUseProfile {
  hpRestore?: number;
  manaRestore?: number;
  cooldownReduction?: number;
  buildBuffs?: TimedBuildBuff[];
}

interface FunctionEffectConfig {
  damageMultiplier?: number;
  incomingDamageMultiplier?: number;
  healAmount?: number;
  manaRestore?: number;
  cooldownTickBonus?: number;
  grantedBuildBuffs?: TimedBuildBuff[];
}

10. 运行时接入点

10.1 必须新增的规则层

建议新增 3 个数据/规则文件：

• src/data/buildTags.ts
  • 标签规范化
  • alias 映射
  • 相似度矩阵
• src/data/buildDamage.ts
  • 聚合激活标签
  • 计算 rawBuildScore
  • 计算 buildDamageMultiplier
• src/data/forgeRecipes.ts
  • 合成、锻造、拆解、重铸配方

10.2 当前代码里的关键接点

A. src/data/equipmentEffects.ts

需要从“空壳”升级为真正读取：

• statProfile
• buildProfile
• 套装件数

建议这里做：

• 读取三槽装备 stat 汇总
• 计算显式套装件数
• 产出装备侧 build 标签源

B. src/hooks/useCombatFlow.ts

这里是 build 进伤害的核心接点。

当前玩家、同伴、怪物都有单独 damage = ... 的结算片段，建议统一收敛成：

resolveOutgoingDamage({
  actor,
  target,
  skill,
  functionEffect,
  gameState,
})

统一处理：

• actor 的 combatTags
• actor 装备 build 标签
• actor 当前限回合 buff 标签
• 显式套装合成标签
• embedding build 伤害修正

C. src/data/characterPresets.ts

角色需要正式持有 combatTags，不要再只放在 UI 常量里。

D. src/data/monsterPresets.ts

怪物新增：

• combatTags
• craftTags

保留：

• habitatTags

E. src/hooks/useGamePersistence.ts

存档兼容必须同步补：

• activeBuildBuffs
• 新字段默认值
• 旧存档自动补空数组

11. 编辑器与策划工作流

结合当前项目“先补类型和规则，再补 UI”的经验，编辑器建议按下面顺序补。

11.1 标签注册表

先做一个统一标签注册表，再让各编辑器引用它。

编辑器最少应支持：

• 选择规范标签
• 查看别名
• 查看所属 build 簇
• 查看与其他标签的相似度

11.2 Item Catalog Editor

当前它已经能展示 buildProfile，下一步建议补：

• 规范标签选择器
• 当前装备可形成的 build 预览
• 2 件/3 件套装合成标签预览
• 拆解产物预览

11.3 角色/怪物编辑

建议把角色和怪物的 combatTags 录入正式数据，不再只放展示文案。

11.4 相似度预计算脚本

建议加一个脚本，例如：

scripts/build-tag-similarity.mjs

负责：

• 读取标签注册表
• 生成 embedding
• 输出相似度矩阵 JSON

这样运行时就不需要联网或现算。

12. 数值与反滥用约束

为了让系统长期可控，建议一开始就加以下约束：

1. 同规范标签去重，不允许同词条多件装备无限叠加基础 +1。
2. 激活标签上限 8，避免后期词条爆炸。
3. 伤害 build 增益封顶 45%，防止纯标签乘爆。
4. 2 件/3 件套只生成合成标签，不再额外套一层独立乘区，避免双重膨胀。
5. habitatTags 不直接进伤害，避免出现“矿道标签提高输出”这种语义跑偏。
6. buff 标签以刷新时长为主，不以无限叠层为主。
7. 重铸只在语义近邻内滚动，避免 build 完全变异。
8. 拆解返还率不要超过完整锻造成本的 60%~70%，避免无限刷循环。

13. 分阶段实施建议

按照当前项目文档里已经验证过的开发经验，推荐顺序是“类型 -> 规则 -> hook -> UI”，不要反过来。

阶段 A：先补数据骨架

• 新增 buildTagRegistry
• 为角色/怪物补 combatTags
• 为物品补 craftTags / forgeRank
• 为 GameState 补 activeBuildBuffs

阶段 B：再补规则

• 实现标签规范化
• 实现 embedding 相似度矩阵
• 实现 rawBuildScore
• 实现三槽位显式套装合成标签
• 实现 buff 标签衰减

阶段 C：接入战斗

• useCombatFlow.ts 改为统一伤害入口
• 玩家 / 同伴 / 怪物统一读取 build
• equipmentEffects.ts 正式生效

阶段 D：补合成/锻造闭环

• 拆解
• 合成
• 锻造
• 重铸
• 铭刻

阶段 E：最后补编辑器与 UI

• 物品 build 预览
• 套装预览
• 锻造页
• 材料来源与标签簇提示

14. 一句话总结

本方案的核心不是单独增加“套装数值”，而是把装备、角色/怪物、限回合 buff 都转成统一的语义 build 标签，再用“每标签基础值 1 + 标签间 embedding 相似度”的方式形成构筑强度，并把这份构筑强度直接接进当前伤害输出，同时让怪物掉落、宝藏、交易、拆解、合成、锻造、铭刻围绕同一套标签体系形成闭环。