Genarrative/docs/audits/ITEM_AND_BUILD_PRD_AUDIT_2026-04-05.md

物品生成系统与 Build 标签系统 PRD 落地审计

审计时间：2026-04-05

审计范围：

• docs/prd/AI_NATIVE_RUNTIME_ITEM_GENERATION_DESIGN.md
• docs/prd/RUNTIME_ITEM_GENERATION_CURRENT_SYSTEM_DESIGN.md
• docs/prd/BUILD_SYSTEM_ATTRIBUTE_SIMILARITY_PRD_2026-04-02.md
• docs/design/EQUIPMENT_BUILD_AND_FORGE_LOOP_SYSTEM_DESIGN.md

结论速览

1. 物品生成系统

当前状态可以判定为：主链已补齐落地。

已经落地的是：

• 有独立的运行时上下文层、导演层、本地编译层、叙事回写层。
• 宝藏、怪物掉落、通用 NPC 商店已经能走统一的 runtime item director。
• 永久 build 标签物品、限时 build buff 物品、少量数值物品三种骨架都已经能编译出来，并接进现有背包 / 装备 / build 结算。

本轮已补齐的是：

• 新增了 runtime item AI 意图导演与 prompt，并接入 NPC 帮助奖励主链，失败时自动回退到本地导演。
• NPC 交易库存改成按玩家当前 build 生成，并通过 tradeStockSignature 只在 build 变化时刷新。
• NPC 帮助奖励、委托奖励已经统一接入 runtime item director。
• 怪物掉落已经改成“基础掉落 + 语义掉落”双层叠加。

2. Build 标签系统

当前状态可以判定为：核心已按 PRD 落地，且实现范围比 PRD 更大。

已经落地的是：

• BuildTagDefinition.attributeAffinity 已扩展。
• buildDamage.ts 已改成“标签分别匹配角色属性画像”的加法模型，不再做标签两两网络效应。
• Buff / 角色固有 / 武器 / 护甲 / 饰品 / 套装标签都能进入最终倍率。
• Character 面板已经切到“属性适配度”展示，并能拆出单标签的属性贡献明细。
• 有针对新公式的测试覆盖。

还存在的尾项主要是：

• 实现用的是“世界属性 schema 六轴模型”，不是 PRD 文字里的固定四维属性。
• 旧的标签相似度辅助能力没有完全清干净，重铸仍在用 getSimilarBuildTags 做候选标签替换。

物品生成系统审计

PRD 项	当前实现	判定	代码证据
上下文采样层	已有 buildRuntimeItemGenerationContext / buildQuestRuntimeItemGenerationContext，会收集场景、遭遇、关联 NPC、最近剧情、玩家 build 标签与 build gap。	已落地	src/data/runtimeItemContext.ts:157-188、src/data/runtimeItemContext.ts:191-252
AI 意图层	已新增 runtimeItemAiDirector / runtimeItemAiPrompt，buildRuntimeItemAiPromptInput 已进入真实 prompt 组装；NPC 帮助奖励主链会先请求 AI 物品意图，再回落到本地意图导演。	已补齐	src/services/runtimeItemAiPrompt.ts、src/services/runtimeItemAiDirector.ts、src/data/runtimeItemDirector.ts、src/hooks/story/npcEncounterActions.ts
本地编译层	已按 channel / slot / permanence 做 rarity 与预算编译，并产出 statProfile、useProfile.buildBuffs、buildProfile、runtimeMetadata。	已落地	src/data/runtimeItemCompiler.ts:77-101、src/data/runtimeItemCompiler.ts:122-206、src/data/runtimeItemCompiler.ts:245-276
叙事回写层	会把锚点、来源理由、build 倾向回写进物品名和描述。	已落地	src/data/runtimeItemNarrative.ts:171-189
永久标签 / 限时标签 / 少量数值三类物品	永久物品走 buildProfile，限时物品走 useProfile.buildBuffs，并可附带少量数值。	已落地	src/data/runtimeItemCompiler.ts:104-155、src/data/runtimeItemCompiler.ts:157-206
宝藏入口	宝藏奖励已经走 buildRuntimeItemGenerationContext + buildDirectedRuntimeReward，并把结果写回 story hint。	已落地	src/data/treasureInteractions.ts:52-89、src/hooks/useTreasureFlow.ts:45-75
NPC 交易入口	通用 NPC 商店已改成按玩家当前 build 生成；初始 NPC 状态、交易模态打开时刷新、场景预览读取都会带上完整 GameState，并用 tradeStockSignature 避免无意义重刷。角色型 NPC 仍保留既有角色装备/背包模板。	已补齐	src/data/npcInteractions.ts、src/hooks/story/npcInteraction.ts、src/hooks/useStoryGeneration.ts、src/components/NpcModals.tsx
NPC 帮助 / 关系奖励	npc_reward 已真正接入主链。帮助奖励现在会生成带 runtimeMetadata 的 runtime item，并保留数值恢复、冷却缩减与 story hint。	已补齐	src/data/npcInteractions.ts、src/hooks/story/npcEncounterActions.ts
委托奖励入口	Quest reward 已改为走 runtime director，支持 buildQuestRuntimeItemGenerationContext，领取时发放的是 runtime item。主 NPC 接任务流程也已切到 generateQuestForNpcEncounter。	已补齐	src/data/questFlow.ts、src/hooks/story/npcEncounterActions.ts、src/services/questDirector.ts
怪物掉落双层设计	普通世界掉落已改成预设 lootTable 基础掉落与 monster_drop runtime 语义掉落并存，不再互相覆盖。	已补齐	src/data/hostileNpcPresets.ts、src/data/hostileNpcPresets.test.ts

物品系统的具体判断

已经明显符合 PRD 的部分

1. 系统分层已经形成。 runtimeItemContext -> runtimeItemDirector -> runtimeItemCompiler -> runtimeItemNarrative 这条链已经非常接近 PRD 里“上下文采样 / AI 意图 / 本地编译 / 叙事回写”的结构。

2. build 导向优先于纯数值。 buildRuntimeItemContext 会先算 playerBuildTags 和 playerBuildGaps，导演层再优先把 gap tag 与现有 build tag 拼进 targetBuildDirection，编译层才决定数值预算。

3. 奖励已经进入真实玩法结算。 runtime item 生成出的 buildProfile 会进入装备 build 结算，useProfile.buildBuffs 会在使用物品时写入 activeBuildBuffs。

本轮补齐后的说明

1. 运行时物品意图已经进入真实主链。 当前至少在 NPC 帮助奖励链路中，已经先走 AI 意图导演，再走本地编译与叙事回写；如果模型不可用，会回退到既有启发式导演，保证玩法不断。

2. 交易库存已经真正读取玩家当前构筑。 通用交易 NPC 的库存会基于玩家当前 build、装备标签和 build gap 生成，而不是继续依赖 NPC 自身偏好标签。

3. 帮助奖励、委托奖励、怪物掉落都已并入统一 runtime director。 现在三条链路都能产出带 relation anchor / source reason / runtime metadata 的 runtime item。

Build 标签系统审计

PRD 项	当前实现	判定	代码证据
BuildTagDefinition.attributeAffinity 扩展	类型已扩展，标签注册表也会为每个标签注入 affinity。	已落地	src/types/build.ts:6-13、src/data/buildTags.ts:66-69
静态标签亲和度表	已有 buildTagAttributeAffinity.ts，提供标签到属性轴的静态 affinity 表。	已落地	src/data/buildTagAttributeAffinity.ts:127-183
从“标签互相影响”改为“标签分别匹配角色属性”	buildDamage.ts 已按单标签计算 fitScore、bonusDelta 和属性贡献，最后做加法累积，不再做 pair/cluster 乘法网络。	已落地	src/data/buildDamage.ts:236-318
来源系数	Buff / 角色 / 武器 / 护甲 / 饰品 / 套装都有独立 source coefficient，和 PRD 基本一致。	已落地	src/data/buildDamage.ts:95-114
最终伤害接入	resolvePlayerOutgoingDamage / resolveCompanionOutgoingDamage / resolveMonsterOutgoingDamage 都已接 buildDamageMultiplier。	已落地	src/data/buildDamage.ts:498-542
展示层从“标签协同”改成“属性适配度”	Character 面板已经按标签展示 bonus、来源、主导属性，并能打开明细弹窗。	已落地	src/components/CharacterPanel.tsx:205-247、src/components/CharacterPanel.tsx:497-539
验收测试	已覆盖单标签可拆分、删一个标签不重算其余标签、不同属性角色用同一套装倍率不同、Buff/套装来源正常进入等场景。	已落地	src/data/buildDamage.test.ts:125-313
四维属性口径	PRD 写的是四维固定属性；实现已经提升为 world schema 六轴模型。目标一致，但口径不再一一对应。	已落地，但实现已外延扩展	src/types/attributes.ts:3-15、src/data/worldAttributeSchemas.ts:4-155
旧标签相似度清理	核心伤害结算已不再依赖旧矩阵，但 getSimilarBuildTags 仍存在，重铸继续用它挑候选标签，generate:build-tags 脚本也还保留。	收尾未完成	src/data/buildTags.ts:183-215、src/data/forgeSystem.ts:371-399、package.json:21-24

Build 系统的具体判断

已经符合 PRD 核心目标的部分

1. 可解释性已经建立。 现在每个标签都有自己的 fitScore、attributeContributions 和 attributeModifierDeltas，玩家可以看到“这个标签为什么强、强在哪条属性轴上”。

2. 新增标签不会反向扰动旧标签贡献。 buildDamage.test.ts 已专门验证“删掉一个标签，只会移除它自己的 row，不会重算其他 row”。

3. 套装标签、Buff 标签、装备标签都能统一进入同一公式。 这点和 PRD 的来源规则一致，且测试已经覆盖。

需要注意但不构成核心未落地的问题

1. 实现已经超出 PRD 的四维设计。 现在不是固定 strength / agility / intelligence / spirit 四维，而是通过 WorldAttributeSchema 映射成武侠/仙侠/自定义世界都能共用的语义属性轴。这更适合当前仓库的世界化属性系统，但也意味着 PRD 文案需要同步。

2. 旧相似度能力没有完全退场。 核心伤害结算已经不用标签两两矩阵，但锻造重铸仍然会根据标签相似度挑换洗标签，所以“旧体系相关命名/脚本”还没彻底收尾。

综合判断

如果按“是否已经把 PRD 的主战场落到代码里”来判断：

• Build 标签系统：可以认为已经落地。
• 物品生成系统：可以认为主链已经落地，之前审计出的缺口已在本轮补齐。

如果接下来继续做收尾，更建议做的是：

1. 把 runtime item AI 意图层继续扩到宝藏、怪物掉落、委托奖励以外的更多同步入口，减少启发式 fallback 的覆盖面。
2. 给 Build 系统补一版文档同步，明确当前实现已经从 PRD 四维模型升级为世界属性 schema 模型，并清理剩余旧相似度脚本/命名。
3. 评估 origin: 'ai_compiled' 的语义是否还要细分成“AI 意图 + 本地编译”与“纯本地 fallback”两档，方便后续观测与埋点。