Integrate role asset studio into custom world agent flow

2026-04-14 20:16:41 +08:00
parent 0981d6ee1b
commit bc2999ffb9
118 changed files with 31211 additions and 1232 deletions
--- a/docs/audits/FUNCTION_REQUIREMENT_COMPLETENESS_AUDIT_2026-04-14.md
+++ b/docs/audits/FUNCTION_REQUIREMENT_COMPLETENESS_AUDIT_2026-04-14.md
@@ -0,0 +1,163 @@
+# Function 需求完整性核查（2026-04-14）
+
+## 1. 核查范围
+
+本次核查按当前线程上下文，聚焦 function 体系相关文档与实现，不扩大到整个项目全部 PRD。
+
+本次实际对照了这些文档：
+
+- `docs/audits/FUNCTION_DESIGN_AUDIT_2026-04-03.md`
+- `docs/reference/FUNCTION_SCRIPT_CATALOG_2026-04-04.md`
+- `docs/experience/ADVENTURE_RUNTIME_DEV_EXPERIENCE.md`
+- `docs/planning/CURRENT_GAME_ITERATION_PRIORITIES_2026-04-03.md`
+
+本次实际核对了这些实现入口：
+
+- `src/data/functionCatalog/**`
+- `src/data/stateFunctions.ts`
+- `src/data/npcInteractions.ts`
+- `src/components/AdventurePanel.tsx`
+- `src/hooks/story/choiceActions.ts`
+- `src/hooks/story/npcEncounterActions.ts`
+- `src/hooks/story/npcInteraction.ts`
+- `src/services/runtimeStoryService.ts`
+- `server-node/src/modules/story/**`
+- `server-node/src/modules/inventory/**`
+- `server-node/src/modules/runtime-item/**`
+- `server-node/src/modules/quest/**`
+
+## 2. 核查结论
+
+结论先说：
+
+- function 主链路需求已经基本落地，不需要再继续“为了完整而过度迭代”。
+- 当前最主要的缺口不是再发明一套新 function 流程，而是把已有链路补齐回归测试，确保后续不会回退。
+- 本轮核查后，已把两条仍缺直接测试兜底的核心链路补上。
+
+## 3. 已确认已经落地的需求
+
+### 3.1 function 目录化与分层收口
+
+已实现：
+
+- `state / npc / treasure / flow / panel` 五类 function 已统一收口到 `src/data/functionCatalog/`
+- `src/data/functionCatalog/index.ts` 已提供统一导出
+- `SERVER_RUNTIME_FUNCTION_IDS` 也已和 catalog 文档映射对齐
+
+判断：
+
+- 这部分需求已完成，不需要继续重做结构。
+
+### 3.2 `story_continue_adventure` 延迟展示链路
+
+已实现：
+
+- `npc_chat` 在 `npcEncounterActions.ts` 中先生成聊天正文，再把后续选项写入 `deferredOptions`
+- `choiceActions.ts` 在点击 `story_continue_adventure` 时会直接恢复 `deferredOptions`
+- `AdventurePanel.tsx` 已按 `functionId` 而不是 `actionText` 识别该特殊按钮
+
+判断：
+
+- 这条主功能链路已经真正存在，不属于“文档写了、实现没跟上”。
+
+### 3.3 modal 型 function 的首次点击分流
+
+已实现：
+
+- `npc_trade`
+- `npc_gift`
+- `npc_recruit`
+
+这些 function 当前都明确是“首次点击先分流，再在确认后进入真正执行链”。
+
+当前实现路径：
+
+- 首次点击：
+  - `choiceActions.ts`
+  - `storyGenerationState.ts`
+  - `npcInteraction.ts`
+- 确认后：
+  - `trade / gift / quest` 进入 server runtime action
+  - `recruit` 进入本地招募对白与本地状态提交链
+
+判断：
+
+- 这不是未实现，而是当前架构设计如此。
+- 文档里“确认后要继续推进剧情/结算”的要求已经满足。
+
+### 3.4 Task6 function 的服务端化
+
+已实现：
+
+- `inventory_use`
+- `equipment_equip`
+- `equipment_unequip`
+- `forge_craft`
+- `forge_dismantle`
+- `forge_reforge`
+- `npc_trade`
+- `npc_gift`
+- `npc_quest_accept`
+- `npc_quest_turn_in`
+- `treasure_secure`
+- `treasure_inspect`
+- `treasure_leave`
+
+这些 function 已经在前端 `runtimeStoryService.ts`、服务端 `story runtime / inventory / runtime-item / quest` 模块里形成闭环。
+
+判断：
+
+- 这部分不需要再回退到前端本地重写。
+
+## 4. 本轮发现的真实缺口
+
+本轮真正仍未完整落地的，不是功能行为本身，而是下面两条回归保护：
+
+### 4.1 `npc_chat -> story_continue_adventure -> deferredOptions`
+
+问题：
+
+- 文档明确要求这条链路要清楚、可验证。
+- 代码已经有，但之前没有直接测试“点击继续冒险后必须展示 deferredOptions”。
+
+本轮已补：
+
+- `src/hooks/story/choiceActions.test.ts`
+  - 新增 `reveals deferred adventure options when story_continue_adventure is selected`
+
+### 4.2 `AdventurePanel` 对 continue option 的识别方式
+
+问题：
+
+- 文档明确要求不要再靠文案识别 continue option。
+- 实现已经改成按 `functionId` 识别，但之前没有组件层测试锁住。
+
+本轮已补：
+
+- `src/components/AdventurePanel.test.tsx`
+  - 验证 `story_continue_adventure` 即使 actionText 改掉，仍然显示延迟选项提示
+  - 验证仅 actionText 相同但 functionId 不同，不会误触发提示
+
+## 5. 本轮新增测试
+
+本轮新增：
+
+- `src/components/AdventurePanel.test.tsx`
+- `src/hooks/story/choiceActions.test.ts`
+  - 新增 deferred options 恢复用例
+
+## 6. 验收结论
+
+按当前 function 相关文档要求判断：
+
+- 核心运行时需求：已实现
+- 延迟展示链路：已实现
+- modal 分流架构：已实现
+- Task6 服务端承接：已实现
+- 回归测试盲区：本轮已补齐关键缺口
+
+最终建议：
+
+- 这块现在不应该继续过度迭代。
+- 后续应以“新增需求再增量补测试”为主，而不是再次重构 function 主链路。
+- 除非后续 PRD 明确要求“modal 首次点击也必须立刻生成一段剧情反馈”，否则不建议为了形式统一再强行改写当前分流模型。
--- a/docs/audits/FUNCTION_TEST_AUDIT_2026-04-14.md
+++ b/docs/audits/FUNCTION_TEST_AUDIT_2026-04-14.md
@@ -0,0 +1,128 @@
+# Function 测试审计（2026-04-14）
+
+补充更新：
+
+- 本文记录的 2 个 bug 已在同日完成代码修复。
+- 对应测试已经从“稳定复现旧行为”切换为“验证修复后行为”。
+
+## 1. 本次新增测试
+
+本轮新增了两组 function 相关测试：
+
+- `src/data/stateFunctions.test.ts`
+  - 覆盖 state function 的运行时过滤、优先级、选项解析、排序逻辑。
+- `src/data/functionCatalog/functionCatalog.test.ts`
+  - 覆盖 function 文档映射、flow helper、NPC helper modal 初始化逻辑。
+
+这两组测试都直接挂在现有 `vitest` 体系里，没有新建独立测试框架。
+
+## 2. 本次执行结果
+
+本轮实际执行了以下测试：
+
+```bash
+npx vitest run src/data/stateFunctions.test.ts src/data/functionCatalog/functionCatalog.test.ts
+npx vitest run src/data/npcInteractions.test.ts src/hooks/story/storyGenerationState.test.ts src/services/runtimeStoryService.test.ts
+```
+
+执行结果：
+
+- 新增测试：`2` 个文件，`12` 条测试，全部通过。
+- 复跑已有 function 相关测试：`3` 个文件，`17` 条测试，全部通过。
+- 修复回归测试：`5` 个文件，`30` 条测试，全部通过。
+- 编码检查：`1516` 个文件全部通过。
+
+说明：
+
+- 本轮不是“测试全绿就代表没有问题”。
+- 最初定位出的 2 个问题，已经在后续修复回合里转成了回归测试。
+
+## 3. 历史 bug 与修复结果
+
+### 3.1 `battle_recover_breath`
+
+- 所在位置：`src/data/stateFunctions.ts`
+- 状态：已修复
+- 原始问题表现：
+  - 当 `inBattle = true`，但当前没有存活敌人时，`battle_recover_breath` 仍会留在可执行 function 列表中。
+- 直接原因：
+  - `matchesCategory` 对 `recovery` 分类只判断了是否处于战斗态，没有像 `battle` / `escape` 分类那样额外校验 `hasAliveMonsters(context.monsters)`。
+- 修复方式：
+  - 已在 `matchesCategory` 的 `recovery` 分支中，为战斗恢复类 function 补上 `hasAliveMonsters(context.monsters)` 判断。
+- 修复前影响：
+  - 在“敌人已死但战斗态尚未清理干净”的边界帧里，界面仍可能出现战斗恢复类选项。
+  - 这会让 function 池和真实战斗状态产生残留错位。
+- 当前验证方式：
+  - `inBattle = true`
+  - `monsters = [{ hp: 0, ... }]`
+  - 调用 `getExecutableFunctions(context)`
+  - 现在返回结果应为空，不再包含 `battle_recover_breath`
+- 对应用例：
+  - `src/data/stateFunctions.test.ts`
+  - 用例名：`removes battle_recover_breath when combat has no living monsters`
+
+### 3.2 `npc_trade`
+
+- 所在位置：`src/data/functionCatalog/npc/npcTrade.ts`
+- 状态：已修复
+- 原始问题表现：
+  - trade modal 初始化时，`selectedPlayerItemId` 直接取 `state.playerInventory[0]?.id`。
+  - 如果玩家背包第一项数量为 `0`，modal 默认会选中一件不可出售物品。
+- 直接原因：
+  - `buildNpcTradeModalState` 没有过滤 `quantity <= 0` 的物品，也没有寻找第一个可交易物品。
+- 修复方式：
+  - 已改为优先选择 `quantity > 0` 的可交易物品。
+  - 同时对 NPC 库存和玩家背包都使用同一条筛选规则，避免默认选中空物品。
+- 修复前影响：
+  - 交易面板第一次打开时，默认状态可能就是不可确认的。
+  - 用户需要手动切换到第二件物品，才会进入可提交状态。
+- 当前验证方式：
+  - `playerInventory[0].quantity = 0`
+  - `playerInventory[1].quantity > 0`
+  - 调用 `buildNpcTradeModalState(...)`
+  - 现在 `selectedPlayerItemId` 应该自动落到第一件可交易物品
+- 对应用例：
+  - `src/data/functionCatalog/functionCatalog.test.ts`
+  - 用例名：`prefers the first tradable player item when zero-quantity items exist`
+  - `src/hooks/story/storyGenerationState.test.ts`
+  - 用例名：`skips zero-quantity player items when opening the trade modal`
+
+## 4. 本轮已验证通过的 function 能力
+
+以下内容本轮已通过测试验证，没有发现新的明显问题：
+
+- state function runtime 构建：
+  - `idle_follow_clue` 已正确从运行时候选池移除。
+  - `idle_explore_forward` 的运行时文案覆盖仍然生效。
+- state function 选项行为：
+  - 高压战斗下 `battle_recover_breath` 会被正确提权。
+  - 营地场景会正确隐藏 `idle_explore_forward`。
+  - `idle_travel_next_scene` 会强制使用运行时建议 actionText。
+  - `battle_all_in_crush` 会保留外部传入的自定义 actionText。
+  - story option 排序仍保持“前 2 个 model 锁定 + 后续按 priority 排序”。
+- flow helper：
+  - `story_continue_adventure`
+  - `camp_travel_home_scene`
+- NPC helper：
+  - `npc_preview_talk`
+  - `npc_gift`
+  - `npc_recruit`
+- 文档映射：
+  - 当前 `SERVER_RUNTIME_FUNCTION_IDS` 全部都能在 function catalog 文档中找到对应条目。
+  - 本轮扫描到的 function `source` 路径全部存在，没有出现失效引用。
+
+## 5. 本轮修复动作
+
+- `battle_recover_breath`
+  - 已补充战斗恢复类 function 的存活敌人校验，避免战斗边界帧残留非法选项。
+- `npc_trade`
+  - 已把 trade modal 默认选中逻辑改为优先寻找可交易物品，不再直接吃数组第一项。
+- 回归测试
+  - 原先记录旧行为的测试已翻转为修复后预期，并额外补了一条 `storyGenerationState` 接入层测试。
+
+## 6. 备注
+
+这次测试资产的意义分两步：
+
+- 第一步先把 bug 稳定复现出来，避免问题只停留在口头描述。
+- 第二步在修复后把断言翻转成“正确行为”，让它们正式成为回归测试。
--- a/docs/audits/README.md
+++ b/docs/audits/README.md
@@ -10,6 +10,8 @@
 ## 专项审计

 - [FUNCTION_DESIGN_AUDIT_2026-04-03.md](./FUNCTION_DESIGN_AUDIT_2026-04-03.md)：Function 体系分层、职责边界和当前结构问题。
+- [FUNCTION_REQUIREMENT_COMPLETENESS_AUDIT_2026-04-14.md](./FUNCTION_REQUIREMENT_COMPLETENESS_AUDIT_2026-04-14.md)：Function 相关文档需求与当前实现对齐核查。
+- [FUNCTION_TEST_AUDIT_2026-04-14.md](./FUNCTION_TEST_AUDIT_2026-04-14.md)：Function 运行时测试补充、已确认 bug 与当前验证结果。
 - [ITEM_AND_BUILD_PRD_AUDIT_2026-04-05.md](./ITEM_AND_BUILD_PRD_AUDIT_2026-04-05.md)：物品生成与 Build 标签系统对 PRD 的落地情况。
 - [CUSTOM_WORLD_CREATOR_TOOL_AUDIT_2026-04-08.md](./CUSTOM_WORLD_CREATOR_TOOL_AUDIT_2026-04-08.md)：自定义世界创作工具当前问题、体验断层和优化优先级审计。