初始仓库迁移

docs/prd/RUNTIME_ITEM_GENERATION_CURRENT_SYSTEM_DESIGN.md

@@ -0,0 +1,486 @@
+# 当前运行时物品生成系统设计整理
+
+更新时间：`2026-04-02`
+
+## 0. 目标
+
+这份文档只回答一个问题：
+
+**当前仓库里，运行时物品是怎么被“定义、生成、发放、使用、转化、进入 build 结算”的。**
+
+它不是未来方案，而是对现状的结构化整理，方便后续继续扩展 AI 原生玩法。
+
+## 1. 当前系统的总体判断
+
+当前仓库里的运行时物品系统，不是“纯 AI 生成”，而是一个 **本地规则驱动 + 局部程序化生成 + AI 负责叙事文本** 的体系。
+
+它大体由 5 层组成：
+
+1. **物品骨架层**
+   - 用 `InventoryItem`、`ItemStatProfile`、`ItemUseProfile`、`ItemBuildProfile` 承载运行时能力。
+2. **基础生成层**
+   - 用 `src/data/itemCatalog.ts` + `src/data/itemDesign.ts` 从素材路径推导出物品目录与设计元数据。
+3. **运行时发放层**
+   - 在初始背包、NPC 库存、宝藏奖励、怪物掉落、拆解/锻造/重铸、自定义世界运行时生成等入口，把物品真正放进 `GameState`。
+4. **战斗/背包生效层**
+   - 装备通过 `equipmentEffects.ts` 生效，消耗品通过 `inventoryEffects.ts` 生效，build 标签通过 `buildTags.ts` + `buildDamage.ts` 生效。
+5. **叙事包装层**
+   - AI 负责把这些本地规则已经确定的结果写成剧情、聊天、宝藏描述、选项文案，但 **AI 当前并不直接产出结构化运行时物品**。
+
+一句话概括：
+
+**当前系统已经有“运行时物品玩法骨架”，但还没有“与具体背景 / 当前 NPC / 当前事件强绑定的 AI 原生物品导演层”。**
+
+## 2. 当前核心数据结构
+
+### 2.1 `InventoryItem`
+
+运行时所有物品最终都落到 `InventoryItem`：
+
+- 基础身份：`id`、`category`、`name`、`quantity`、`rarity`
+- 通用标签：`tags`
+- 世界/表现：`iconSrc`、`description`、`worldAffinity`、`worldProfiles`
+- 装备信息：`equipmentSlotId`
+- 数值能力：`statProfile`
+- 使用能力：`useProfile`
+- build 能力：`buildProfile`
+- 经济能力：`value`
+
+这意味着当前系统已经允许同一个物品同时具备：
+
+- 装备加成
+- 消耗品效果
+- build 标签
+- 世界观文案
+- 经济价值
+
+### 2.2 `ItemStatProfile`
+
+当前可直接进入数值结算的字段主要是：
+
+- `maxHpBonus`
+- `maxManaBonus`
+- `outgoingDamageBonus`
+- `incomingDamageMultiplier`
+
+这套结构已经足够支撑“少量直接数值提升”的物品设计。
+
+### 2.3 `ItemUseProfile`
+
+当前消耗品/可使用物品可提供：
+
+- `hpRestore`
+- `manaRestore`
+- `cooldownReduction`
+- `buildBuffs`
+
+这意味着当前系统已经具备“限时 build 标签道具”的基础承载能力。
+
+### 2.4 `ItemBuildProfile`
+
+当前 build 相关物品数据包括：
+
+- `role`
+- `tags`
+- `setId`
+- `setName`
+- `pieceName`
+- `synergy`
+- `craftTags`
+- `forgeRank`
+
+这说明当前物品系统已经不仅仅是“数值装备”，而是已经向 **build / 套装 / 锻造** 方向扩展。
+
+## 3. 当前物品是如何被生成出来的
+
+## 3.1 素材目录 -> 物品目录
+
+`src/data/itemCatalog.ts` 负责把素材路径转成 `ItemCatalogEntry`：
+
+- 先从素材路径推导：
+  - `category`
+  - `rarity`
+  - `tags`
+  - `name`
+- 再调用 `src/data/itemDesign.ts` 补充更完整的设计：
+  - `statProfile`
+  - `useProfile`
+  - `buildProfile`
+  - `value`
+  - 世界观名称/描述
+
+也就是说，当前项目里相当一部分物品，不是手工逐个写死的，而是 **“素材驱动 + 规则推导”**。
+
+## 3.2 `itemDesign.ts` 的设计角色
+
+`src/data/itemDesign.ts` 是当前最重要的“物品规则设计器”。
+
+它会按素材族系推导出不同风格物品：
+
+- `Armory` 系列
+  - 生成武器/护甲
+  - 自动带 `buildProfile`
+  - 自动挂 `setId / setName / pieceName / synergy`
+- `Jewelry` 系列
+  - 生成饰品
+  - 偏向 `relic` 与 build 补位
+- `Potions` 系列
+  - 生成消耗品
+  - 可恢复 HP / Mana / 冷却
+  - 部分药剂会生成 `buildBuffs`
+- `Gems` / `Skills` / `Librarium` 系列
+  - 生成稀有品、法器、技能相关物品
+  - 部分带 build 倾向
+
+这层已经是“半程序化设计”，不是纯静态表。
+
+## 3.3 自定义世界运行时程序化生成
+
+`src/data/customWorldRuntime.ts` 提供了另一条明显不同的生成链：
+
+- 输入：
+  - `CustomWorldProfile`
+  - `seedKey`
+  - 查询条件：`categories / preferredTags / keywords / rarityFloor / count`
+- 输出：
+  - 运行时即时程序化物品
+
+它的特点是：
+
+- 基于世界档案与种子稳定生成
+- 可以按角色、用途、标签、关键词筛选
+- 能生成：
+  - 武器
+  - 护甲
+  - 饰品
+  - 消耗品
+  - 材料
+  - 稀有品
+  - 专属物品
+
+当前它已经被用于：
+
+- 自定义世界角色初始装备
+- 自定义世界角色初始背包
+- 自定义世界 NPC 角色库存
+
+但这条链目前更像 **“主题化程序物品池”**，还不是“事件级、NPC级、场景级实时定制物品”。
+
+## 4. 当前运行时有哪些物品发放入口
+
+## 4.1 玩家初始物品
+
+玩家开局物品主要来自两条链：
+
+1. `buildInitialPlayerInventory`
+   - 来自 `npcInteractions.ts`
+   - 普通世界走角色预设背包
+   - 自定义世界走 `buildCustomWorldStarterInventoryItems`
+2. `buildInitialEquipmentLoadout`
+   - 来自 `equipmentEffects.ts`
+   - 根据角色预设初始装备，转成可装备的 `InventoryItem`
+
+这说明玩家初始 build 其实已经部分依赖物品体系，而不是只靠角色裸属性。
+
+## 4.2 NPC 库存
+
+`buildInitialNpcState` 会给每个 NPC 建立运行时库存：
+
+- 角色型 NPC：
+  - 从角色装备 + 角色背包推导
+- 怪物型 encounter：
+  - 从怪物 preset 的 `lootTable` 推导
+- 普通场景 NPC：
+  - 从职业/身份模板库存推导
+- 自定义世界 NPC：
+  - 可走 `buildRuntimeCustomWorldInventoryItems`
+
+因此当前 NPC 交易、赠礼、击败掉落，已经都能围绕同一套 `InventoryItem[]` 进行。
+
+## 4.3 宝藏奖励
+
+`src/data/treasureInteractions.ts` 负责宝藏奖励：
+
+- 根据世界类型选择奖励池
+- 根据 encounter 信息和 action 做 seed
+- 产出：
+  - 稀有品
+  - 消耗品
+  - 材料
+  - HP / Mana 恢复
+  - 货币
+
+这条链已经是运行时生成，但目前仍然是 **世界模板池级别**，不是“根据当前场景背景 / 当前 NPC / 最近事件”深度定制。
+
+## 4.4 怪物掉落 / NPC 击败掉落
+
+当前掉落主要有两种：
+
+1. 怪物 preset 自带 `lootTable`
+2. NPC 击败后，从 `npcState.inventory` 里按玩家收益排序取高价值物品
+
+这里的核心是：
+
+**当前系统已经把“掉落”统一成库存消费问题，而不是单独的一套特殊奖励系统。**
+
+## 4.5 拆解 / 合成 / 锻造 / 重铸
+
+`src/data/forgeSystem.ts` 已经形成第二类运行时物品生成入口：
+
+- `executeDismantleItem`
+  - 把装备拆成基础材料 + 标签精粹
+- `executeForgeRecipe`
+  - 消耗材料生成成品装备
+- `executeReforgeItem`
+  - 保留原物品基础上重投 build 标签并增强数值
+
+这说明运行时物品系统已经不只是“掉落 -> 使用”，而是进入了：
+
+**掉落 -> 持有 -> 拆解 -> 再生产 -> build 迭代**
+
+的循环。
+
+## 5. 当前物品如何进入玩法结算
+
+## 5.1 装备生效
+
+`src/data/equipmentEffects.ts` 会把 `EquipmentLoadout` 汇总为：
+
+- `maxHpBonus`
+- `maxManaBonus`
+- `outgoingDamageMultiplier`
+- `incomingDamageMultiplier`
+
+当前实现已经会优先读取 `statProfile`，没有时才走 rarity fallback。
+
+这意味着：
+
+- 装备的直接数值提升已经真实生效
+- 不是只在 UI 显示
+
+## 5.2 build 标签生效
+
+`src/data/buildTags.ts` + `src/data/buildDamage.ts` 已经形成完整 build 入口：
+
+- 角色 `combatTags`
+- 装备 `buildProfile.tags`
+- 套装标签
+- 限时 `TimedBuildBuff`
+
+会被统一整理为激活标签集，再计算 build 伤害乘区。
+
+当前 build 标签来源已经包括：
+
+- 角色
+- 怪物
+- 装备
+- 套装
+- 消耗品/技能 buff
+
+## 5.3 消耗品生效
+
+`src/data/inventoryEffects.ts` + `src/hooks/useInventoryFlow.ts` 会在使用物品时：
+
+- 恢复 HP
+- 恢复 Mana
+- 推进技能冷却
+- 追加 `activeBuildBuffs`
+
+这意味着当前系统已经存在：
+
+- **直接恢复型物品**
+- **节奏调整型物品**
+- **限时 build 强化型物品**
+
+三种雏形。
+
+## 6. 当前 AI 在物品系统里的角色
+
+当前 AI 与物品系统的关系主要有两种：
+
+## 6.1 自定义世界“离线式”生成
+
+`src/services/customWorld.ts` + `src/services/customWorldBuilder.ts` 会让 AI 生成：
+
+- 世界名
+- playable NPC
+- story NPC
+- 关键物品样本
+- 地标
+
+然后本地再把这些骨架扩展成更大的世界档案。
+
+这时 AI 的角色是：
+
+**提供世界观语义骨架，而不是直接在单次 encounter 里临场造出一个可结算物品。**
+
+## 6.2 运行时叙事包装
+
+`prompt.ts` 和相关 story flow 里，AI 主要负责：
+
+- 剧情文本
+- 对话
+- 选项文案
+- 氛围描述
+
+但当前 AI 不负责：
+
+- 直接返回结构化物品
+- 决定物品数值是否合法
+- 决定 build 标签是否合法
+- 决定库存如何变更
+
+这与仓库已有开发经验文档里的原则一致：
+
+**AI 负责解释世界，本地规则负责改动世界。**
+
+## 7. 当前系统的优点
+
+## 7.1 已有统一物品骨架
+
+`InventoryItem` 已经足够承载：
+
+- 永久装备
+- 消耗品
+- build 标签
+- 世界观描述
+- 经济系统
+
+后续不需要另起一套物品结构。
+
+## 7.2 已有 build 玩法骨架
+
+当前系统已经支持：
+
+- 装备 build 标签
+- 套装 build 标签
+- 消耗品限时 build buff
+- 角色/怪物 combatTags
+
+这让“物品影响 build”不再只是概念。
+
+## 7.3 已有多个运行时入口
+
+当前物品已经能从这些入口进入游戏：
+
+- 初始背包
+- 初始装备
+- NPC 库存
+- 宝藏
+- 怪物掉落
+- 击败 NPC
+- 合成
+- 拆解
+- 锻造
+- 重铸
+- 自定义世界程序化生成
+
+系统入口已经比较完整。
+
+## 7.4 本地规则边界明确
+
+当前实现最大的稳定性来源，是物品最终由本地规则落库和结算：
+
+- 可测试
+- 可复现
+- 可存档兼容
+- 不依赖模型临场稳定性
+
+这非常适合继续向 AI 原生玩法演化。
+
+## 8. 当前系统的主要缺口
+
+## 8.1 非自定义世界的运行时发放仍偏模板池
+
+当前普通世界的宝藏、NPC 库存、基础奖励，更多还是：
+
+- 世界模板
+- 身份模板
+- 怪物 preset
+
+而不是根据以下上下文动态拼装：
+
+- 当前场景背景
+- 当前 NPC 动机
+- 当前事件阶段
+- 最近剧情行为
+- 玩家当前 build 缺口
+
+## 8.2 宝藏与物品的叙事绑定不够深
+
+当前宝藏奖励会根据世界类型变化，但还没有强绑定：
+
+- 地标
+- scene preset
+- treasure hint
+- 相关 NPC
+- 最近发生的事件
+
+所以“玩法可用”，但“故事贴脸感”还不够强。
+
+## 8.3 自定义世界运行时物品偏“主题生成”，还不是“关系生成”
+
+`customWorldRuntime.ts` 已经能做：
+
+- 世界主题相关
+- 标签/关键词相关
+- 角色用途相关
+
+但还没有直接把以下关系结构编进物品：
+
+- 这个物品和哪个 NPC 有关系
+- 为什么在这个时刻出现
+- 它与哪个任务/线索绑定
+- 它是否属于某个 faction / 场景 / 地标
+
+## 8.4 一些运行时奖励没有补足完整 build 元数据
+
+例如部分宝藏奖励和 NPC 模板奖励，当前只是简单 `InventoryItem`：
+
+- 有 `category / rarity / tags`
+- 但未必有完整 `statProfile / useProfile / buildProfile`
+
+这会导致它们更像资源或商品，而不是强 build 物品。
+
+## 8.5 缺少“物品生成导演层”
+
+当前系统缺的不是单个函数，而是一层明确的运行时物品导演：
+
+- 输入当前上下文
+- 决定掉落/奖励/商店/赠礼候选
+- 决定叙事来源
+- 决定 build 倾向
+- 决定是永久收益还是限时收益
+- 决定数值预算
+
+这层目前分散在：
+
+- `treasureInteractions.ts`
+- `npcInteractions.ts`
+- `customWorldRuntime.ts`
+- `forgeSystem.ts`
+
+之间，还没有统一起来。
+
+## 9. 对当前系统的结论
+
+当前仓库里的“运行时物品生成系统”已经不是空白，反而已经具备了很好的扩展前提：
+
+- 有统一物品数据结构
+- 有 build 标签体系
+- 有限时 buff 体系
+- 有装备/消耗品/材料/稀有品的分类
+- 有宝藏、NPC、掉落、锻造等运行时入口
+- 有自定义世界程序化物品能力
+- 有明确的“AI 叙事、本地规则结算”边界
+
+但它现在更像：
+
+**“规则系统已经就位，AI 原生上下文驱动物品导演还没补上。”**
+
+后续如果要继续往 AI 原生游戏推进，最值得补的不是推翻现有系统，而是：
+
+1. 在现有 `InventoryItem` 体系上增加上下文生成层。
+2. 让物品生成同时读取场景、NPC、剧情、build 缺口。
+3. 让 AI 负责物品语义与叙事来源，本地规则负责编译成可结算物品。
+4. 把宝藏、NPC 交易、任务奖励、掉落统一接入同一套“运行时物品导演”。