初始仓库迁移

docs/AI_NATIVE_RUNTIME_ITEM_SYSTEM_REDESIGN_2026-04-02.md

@@ -0,0 +1,650 @@
+# AI 原生运行时物品生成系统重设计
+
+更新时间：`2026-04-02`
+
+## 0. 这次重设计要解决什么
+
+基于当前仓库已经存在的系统，这次不再把“AI 原生物品生成”设计成一套独立玩法，而是把它重做成：
+
+**挂在现有背包、build、宝藏、NPC、任务、自定义世界之上的统一运行时物品导演系统。**
+
+它要解决的核心问题有 4 个：
+
+1. 当前物品入口很多，但缺少统一导演层。
+2. 当前奖励能发物品，但和场景背景、相关 NPC、最近事件的贴合度不够高。
+3. 当前 build 标签体系已经存在，但运行时奖励还没有围绕“永久标签 / 限时标签 / 小数值补充”形成稳定规则。
+4. AI 目前只负责叙事包装，没有真正进入运行时物品生成链路。
+
+这次重设计的目标不是“让 AI 直接生成 `InventoryItem`”，而是：
+
+- 让 AI 负责物品的**叙事意图、关系语义、世界贴合**
+- 让本地规则负责物品的**标签、数值、稀有度、存档、平衡**
+
+## 1. 设计结论先说
+
+新的 AI 原生物品系统建议采用：
+
+**上下文采样器 -> AI 物品意图层 -> 本地编译器 -> 渠道分发器 -> 叙事回写器**
+
+其中：
+
+- `InventoryItem` 继续作为唯一成品结构
+- `ItemBuildProfile` 继续承载永久 build 标签
+- `ItemUseProfile.buildBuffs` 继续承载限时 build 标签
+- `ItemStatProfile` 继续承载小数值加成
+- `buildTags.ts / buildDamage.ts` 继续承接战斗结算
+- `treasureInteractions.ts / npcInteractions.ts / forgeSystem.ts / customWorldRuntime.ts` 改为调用统一导演层
+
+一句话：
+
+**不要再按“宝藏怎么发、NPC 怎么卖、任务怎么奖”各写一套；而是让所有入口共用同一个运行时物品生成管线。**
+
+## 2. 这套系统必须遵守的边界
+
+## 2.1 AI 负责语义，不负责数值
+
+AI 可以决定：
+
+- 这件物品像什么
+- 它为什么在这里出现
+- 它和哪个 NPC / 势力 / 地标 / 怪物有关
+- 它更偏向什么 build 风格
+- 它应该是永久物还是限时物
+
+AI 不应该直接决定：
+
+- 最终 `outgoingDamageBonus` 是多少
+- 能带几个标签
+- 允许不允许进入装备槽
+- 价值多少
+- 能不能掉落
+- 能不能持久化
+
+## 2.2 所有成品都必须编译回当前系统
+
+新的系统不是新物品结构，而是新生成过程。
+
+最终成品仍然必须落到：
+
+- `InventoryItem`
+- `ItemStatProfile`
+- `ItemUseProfile`
+- `ItemBuildProfile`
+
+否则现有：
+
+- 背包
+- 装备
+- build 计算
+- 锻造
+- 存档
+- 交易
+
+都接不上。
+
+## 2.3 运行时物品的主收益必须是“构筑意义”
+
+重新设计后，运行时物品的收益优先级建议固定为：
+
+1. `build 标签`
+2. `功能性节奏收益`
+3. `小数值补充`
+
+不建议反过来做成：
+
+1. 大数值
+2. build 标签只是点缀
+
+因为当前项目最强的系统基础已经是 build 标签和叙事关系，而不是传统数值刷装。
+
+## 3. 新系统的整体架构
+
+## 3.1 模块拆分
+
+建议新增 5 个模块：
+
+- `src/types/runtimeItem.ts`
+- `src/data/runtimeItemContext.ts`
+- `src/data/runtimeItemDirector.ts`
+- `src/data/runtimeItemCompiler.ts`
+- `src/data/runtimeItemNarrative.ts`
+
+职责如下。
+
+### A. `runtimeItemContext.ts`
+
+负责统一采样生成上下文，不直接生成物品。
+
+输入来自：
+
+- `GameState`
+- `currentEncounter`
+- `currentScenePreset`
+- `npcStates`
+- `storyHistory`
+- `playerEquipment`
+- `activeBuildBuffs`
+
+输出统一上下文对象：
+
+```ts
+type RuntimeItemGenerationContext = {
+  worldType: WorldType | null;
+  customWorldProfile: CustomWorldProfile | null;
+  sceneId: string | null;
+  sceneName: string | null;
+  sceneDescription: string | null;
+  sceneTags: string[];
+  treasureHints: string[];
+  encounter: Encounter | null;
+  encounterNpcId: string | null;
+  encounterNpcName: string | null;
+  encounterContextText: string | null;
+  relatedNpcState: NpcPersistentState | null;
+  recentStorySummary: string;
+  recentActions: string[];
+  playerCharacterId: string;
+  playerBuildTags: string[];
+  playerBuildGaps: string[];
+  playerEquipmentTags: string[];
+  generationChannel: RuntimeItemGenerationChannel;
+};
+```
+
+### B. `runtimeItemDirector.ts`
+
+负责根据上下文决定：
+
+- 这次该不该生成上下文化物品
+- 生成几件
+- 主奖励 / 副奖励是什么
+- 是装备、消耗品、材料还是稀有物
+- 偏永久 build、限时 build，还是纯功能补给
+
+它的输出不是成品，而是“导演结果”：
+
+```ts
+type RuntimeItemPlan = {
+  slot: "primary" | "secondary" | "support";
+  itemKind: "equipment" | "consumable" | "material" | "relic" | "quest";
+  permanence: "permanent" | "timed" | "resource";
+  narrativeWeight: "light" | "medium" | "heavy";
+  targetBuildDirection: string[];
+  relationAnchor: RuntimeRelationAnchor;
+};
+```
+
+### C. `runtimeItemCompiler.ts`
+
+负责把导演计划 + AI 意图编译成正式 `InventoryItem`。
+
+编译职责包括：
+
+- build 标签规范化
+- 稀有度预算分配
+- 永久标签上限
+- 限时标签时长
+- 数值预算
+- 装备槽判定
+- 价值计算
+- metadata 生成
+
+### D. `runtimeItemNarrative.ts`
+
+负责把已经生成好的物品回写成叙事文本：
+
+- 物品命名
+- 物品描述
+- 物品来源说明
+- 宝藏/NPC/任务文案嵌入
+
+### E. `runtimeItem.ts`
+
+负责声明：
+
+- 渠道类型
+- 关系锚点类型
+- 运行时物品 metadata
+- AI 意图结构
+- 编译预算结构
+
+## 3.2 AI 在新架构里的输入输出
+
+建议 AI 只接触两种结构：
+
+### 输入：压缩过的生成上下文
+
+```ts
+type RuntimeItemAiPromptInput = {
+  worldSummary: string;
+  sceneSummary: string;
+  encounterSummary: string;
+  relatedNpcSummary: string;
+  recentStorySummary: string;
+  generationChannel: RuntimeItemGenerationChannel;
+  playerBuildDirection: string[];
+  playerBuildGaps: string[];
+  desiredItemKind: string;
+  permanence: string;
+};
+```
+
+### 输出：轻量意图
+
+```ts
+type RuntimeItemAiIntent = {
+  shortNameSeed: string;
+  sourcePhrase: string;
+  reasonToAppear: string;
+  relationHooks: string[];
+  desiredBuildTags: string[];
+  desiredFunctionalBias: Array<"heal" | "mana" | "cooldown" | "guard" | "damage">;
+  tone: "grim" | "mysterious" | "martial" | "ritual" | "survival";
+};
+```
+
+AI 输出长度必须短，目的明确，不允许直接产出成品 JSON 大对象。
+
+## 4. 新系统里的物品收益模型
+
+## 4.1 三种收益层
+
+新系统建议把运行时物品分成三类收益层。
+
+### 第一层：永久 build 标签
+
+适用于：
+
+- 武器
+- 护甲
+- 饰品
+- 稀有遗物
+
+载体：
+
+- `buildProfile.role`
+- `buildProfile.tags`
+- `buildProfile.setId / setName`
+
+建议限制：
+
+- 普通运行时装备：`1` 个主标签
+- 稀有以上：`1` 主标签 + `1` 协同标签
+- 传说或剧情物：允许带 `2` 标签 + 关系锚点
+
+### 第二层：限时 build 标签
+
+适用于：
+
+- 药剂
+- 符箓
+- 战场工具
+- 一次性应急物
+
+载体：
+
+- `useProfile.buildBuffs`
+
+建议限制：
+
+- `1~2` 个标签
+- `1~3` 回合
+- 默认刷新持续时间，不建议无限叠层
+
+### 第三层：少量直接数值
+
+适用于：
+
+- 补足 build 短板
+- 强化渠道差异
+- 给物品明确手感
+
+载体：
+
+- `statProfile`
+- `useProfile`
+
+建议数值定位：
+
+- 永远是“辅助收益”
+- 不和 build 标签争主导权
+
+## 4.2 玩家 build 缺口驱动
+
+建议新系统在生成物品时先判断当前玩家缺口，而不是先随机抽品类。
+
+建议至少识别这些缺口：
+
+- `survival_gap`
+  - 当前缺 `守御 / 护体 / 回复 / 续战`
+- `mana_gap`
+  - 当前缺 `法力 / 冷却 / 节奏恢复`
+- `finisher_gap`
+  - 当前缺 `爆发 / 重击 / 追击`
+- `mobility_gap`
+  - 当前缺 `突进 / 快袭 / 风行 / 游击`
+- `control_gap`
+  - 当前缺 `控场 / 符阵 / 镇邪`
+
+运行时物品应优先：
+
+- 补当前明显缺口
+- 或强化当前已经成型的主方向
+
+## 5. 如何让物品和背景 / NPC / 场景高度贴合
+
+## 5.1 必须引入“关系锚点”
+
+建议每个 AI 原生运行时物品都必须绑定至少一个 `relationAnchor`：
+
+```ts
+type RuntimeRelationAnchor =
+  | { type: "npc"; npcId?: string; npcName: string; roleText?: string }
+  | { type: "scene"; sceneId?: string; sceneName: string }
+  | { type: "landmark"; landmarkName: string }
+  | { type: "monster"; monsterId?: string; monsterName: string }
+  | { type: "faction"; factionName: string }
+  | { type: "quest"; questId?: string; questName: string };
+```
+
+如果没有锚点，物品最多只能作为普通补给，不进入“AI 原生重点物品”。
+
+## 5.2 不同渠道对应不同贴合逻辑
+
+### 宝藏
+
+物品必须同时贴合：
+
+- 当前场景
+- `treasureHints`
+- 最近故事动作
+
+例如：
+
+- 在矿道拿到的不是泛用剑，而是“矿脉巡火短铳”
+- 在旧祭坛拿到的不是泛用药，而是“断誓回神香”
+
+### NPC 交易
+
+物品必须贴合：
+
+- NPC 身份
+- NPC 库存风格
+- NPC 和玩家关系
+
+例如：
+
+- 黑市牙人卖的是“快袭/情报/潜行”方向的东西
+- 医修给的是“回复/续战/净化”方向的东西
+
+### 怪物掉落
+
+物品必须贴合：
+
+- 怪物战斗风格
+- 怪物生态来源
+- 所在场景
+
+例如：
+
+- 重甲守卫掉 `守御精粹`
+- 雾林伏击者掉 `风行羽囊`
+
+### 任务奖励
+
+物品必须贴合：
+
+- 发布人
+- 任务目标
+- 完成方式
+- 当前线索推进
+
+它最适合发“永久关系物”。
+
+## 5.3 命名改成“锚点命名法”
+
+建议运行时重点物品命名遵循：
+
+```text
+来源词 + 关系词 + 功能词
+```
+
+而不是：
+
+```text
+稀有前缀 + 通用品类名
+```
+
+例子：
+
+- `锁风渡缉索短刃`
+- `裂界巡守压纹符`
+- `药谷回岚灵露`
+- `断碑旧誓护心佩`
+
+其中：
+
+- 来源词来自场景/地标/势力
+- 关系词来自 NPC / 怪物 / 事件
+- 功能词来自 build 或物品品类
+
+## 6. 新系统里的预算规则
+
+## 6.1 稀有度预算
+
+建议按稀有度控制：
+
+- 能有几个 build 标签
+- 能不能带关系锚点
+- 能不能有 set 倾向
+- 数值范围上限
+
+建议预算如下：
+
+| 稀有度 | build 标签 | 限时 buff | 数值强度 | 叙事强度 |
+| --- | --- | --- | --- | --- |
+| common | 0~1 | 1 | 很小 | 轻 |
+| uncommon | 1 | 1~2 | 小 | 轻 |
+| rare | 1~2 | 2 | 小到中 | 中 |
+| epic | 2 | 2 | 中 | 中到高 |
+| legendary | 2 + 关系锚点 | 2~3 | 中 | 高 |
+
+## 6.2 渠道预算
+
+不同渠道不该发同样强度的物品。
+
+建议：
+
+- `treasure`
+  - 偏单件强语义物
+- `npc_trade`
+  - 偏稳定、可预期、可补短板
+- `npc_reward`
+  - 偏关系定制与限时支援物
+- `monster_drop`
+  - 偏材料 / 精粹 / 生态锚点物
+- `quest_reward`
+  - 偏永久 build 锚点物
+- `discovery`
+  - 偏线索物 / 过渡工具物
+
+## 6.3 build 方向切换限制
+
+新系统建议引入一条硬规则：
+
+**普通运行时物品默认只能强化当前 build 或其邻近 build，不应该高频强制转流派。**
+
+也就是：
+
+- 当前偏 `快剑/突进`，更容易给 `追击/风行`
+- 当前偏 `守御/护体`，更容易给 `续战/回复`
+- 当前偏 `法修/雷法`，更容易给 `过载/冷却`
+
+真正能强制开新流派的物品，应只出现在：
+
+- 高价值任务奖励
+- 关键宝藏
+- 重要 NPC 关系突破
+
+## 7. 建议新增的数据结构
+
+## 7.1 运行时 metadata
+
+建议在 `InventoryItem` 上新增：
+
+```ts
+interface RuntimeItemMetadata {
+  origin: "catalog" | "procedural" | "ai_compiled";
+  generationChannel: RuntimeItemGenerationChannel;
+  seedKey: string;
+  relationAnchor?: RuntimeRelationAnchor;
+  sourceReason: string;
+  recentEventHook?: string;
+}
+```
+
+然后在 `InventoryItem` 上挂：
+
+```ts
+interface InventoryItem {
+  runtimeMetadata?: RuntimeItemMetadata;
+}
+```
+
+这样后面：
+
+- UI 可展示“来源”
+- 日志可回放“为什么拿到”
+- 剧情可引用“这是谁给你的”
+
+## 7.2 运行时导演结果
+
+```ts
+type DirectedRuntimeReward = {
+  primaryItem?: InventoryItem | null;
+  supportItems: InventoryItem[];
+  hp?: number;
+  mana?: number;
+  currency?: number;
+  storyHint?: string;
+};
+```
+
+这样可以统一替代宝藏、帮助奖励、任务奖励等零散结构。
+
+## 8. 与现有模块的接入方式
+
+## 8.1 `treasureInteractions.ts`
+
+重构方式：
+
+- 现在：内部直接从世界池挑物品
+- 以后：调用 `runtimeItemDirector`
+
+建议流程：
+
+1. 从 `GameState + Encounter + ScenePreset` 组 context
+2. 指定 `generationChannel = "treasure"`
+3. director 产出 `DirectedRuntimeReward`
+4. 再由 `buildTreasureResultText` 读 reward 回写文本
+
+这是最适合作为第一落点的入口。
+
+## 8.2 `npcInteractions.ts`
+
+接入方向：
+
+- 商店货物补货
+- NPC 帮助奖励
+- 高好感赠与
+- 特殊 NPC 线索物
+
+这里最适合体现“关系锚点”。
+
+## 8.3 `forgeSystem.ts`
+
+锻造系统不需要完全 AI 化，但应该读取 AI 原生物品遗留的 metadata：
+
+- 拆解时保留关系信息
+- 产出对应方向的精粹
+- 重铸时优先在邻近 build 内滚动
+
+这样 AI 原生物品与锻造闭环才是连通的。
+
+## 8.4 `customWorldRuntime.ts`
+
+这个模块不要废弃，而是改成：
+
+- 继续负责“主题物品池”
+- director 在需要 fallback 或大批量补货时调用它
+
+也就是说：
+
+- `customWorldRuntime.ts` 保留“池”
+- `runtimeItemDirector.ts` 新增“导演”
+
+## 9. 推荐实施顺序
+
+## 阶段 A：先加类型和 metadata
+
+先做：
+
+- `runtimeItem.ts`
+- `InventoryItem.runtimeMetadata`
+- `RuntimeRelationAnchor`
+- `RuntimeItemGenerationContext`
+
+目的：
+
+- 不改玩法，只把类型基础搭好
+
+## 阶段 B：先做 director + compiler
+
+先不接所有入口，只把：
+
+- context 采样
+- AI 意图结构
+- 本地编译器
+
+跑通。
+
+## 阶段 C：先接宝藏
+
+原因：
+
+- 独立
+- 风险低
+- 最容易观察“背景贴合”提升
+
+## 阶段 D：再接 NPC 奖励与交易
+
+这一步会明显提升：
+
+- 关系系统
+- 世界贴脸感
+- 物品来源可解释性
+
+## 阶段 E：最后接任务奖励与怪物语义掉落
+
+因为这两类和现有逻辑耦合更深，适合后置。
+
+## 10. 和旧版方案相比，这次重设计改了什么
+
+相比之前偏概念化的 AI 原生物品方案，这次重设计更明确了 5 点：
+
+1. **不新起物品系统**
+   - 直接复用 `InventoryItem` 与现有 build 结构。
+2. **不让 AI 直接出成品**
+   - 只让 AI 出意图，交给本地编译器落地。
+3. **所有渠道走同一导演层**
+   - 不再把宝藏、NPC、任务各写一套。
+4. **把“关系锚点”正式数据化**
+   - 不是只写在文案里。
+5. **先从宝藏接入，再逐步扩展**
+   - 不是一次推全仓库。
+
+## 11. 一句话总结
+
+新的 AI 原生运行时物品生成系统，不应该是“让 AI 随机写几个看起来很酷的装备”，而应该是：
+
+**让 AI 根据当前世界、场景、NPC、事件和玩家 build 给出物品意图，再由本地规则把这个意图编译成能进背包、能进 build、能进锻造、能进存档、还能被剧情解释的正式物品。**