feat(rules): surface equipment bonuses and fill missing consumable effects

app.py

@@ -64,6 +64,8 @@ def _json_safe(value):
 def _build_state_snapshot(gs: GameState) -> dict:
     """Build a compact state snapshot for reproducible evaluation logs."""
     active_quests = []
+    effective_stats = gs.get_effective_player_stats()
+    equipment_bonuses = gs.get_equipment_stat_bonuses()
     for quest in gs.world.quests.values():
         if quest.status == "active":
             active_quests.append(
@@ -90,11 +92,18 @@ def _build_state_snapshot(gs: GameState) -> dict:
             "max_hp": gs.player.max_hp,
             "mp": gs.player.mp,
             "max_mp": gs.player.max_mp,
+            "attack": gs.player.attack,
+            "defense": gs.player.defense,
+            "speed": gs.player.speed,
+            "luck": gs.player.luck,
+            "perception": gs.player.perception,
             "gold": gs.player.gold,
             "morale": gs.player.morale,
             "sanity": gs.player.sanity,
             "hunger": gs.player.hunger,
             "karma": gs.player.karma,
+            "effective_stats": _json_safe(effective_stats),
+            "equipment_bonuses": _json_safe(equipment_bonuses),
             "inventory": list(gs.player.inventory),
             "equipment": copy.deepcopy(gs.player.equipment),
             "skills": list(gs.player.skills),
@@ -801,13 +810,15 @@ def _get_button_updates(options: list[dict]) -> list:
     return updates
 
 
-def _format_status_panel(gs: GameState) -> str:
-    """格式化状态面板文本（双列 HTML 布局，减少滚动）"""
-    p = gs.player
-    w = gs.world
-
-    # 属性进度条
-    hp_bar = _progress_bar(p.hp, p.max_hp, "HP")
+def _format_status_panel(gs: GameState) -> str:
+    """格式化状态面板文本（双列 HTML 布局，减少滚动）"""
+    p = gs.player
+    w = gs.world
+    effective_stats = gs.get_effective_player_stats()
+    equipment_bonuses = gs.get_equipment_stat_bonuses()
+
+    # 属性进度条
+    hp_bar = _progress_bar(p.hp, p.max_hp, "HP")
     mp_bar = _progress_bar(p.mp, p.max_mp, "MP")
     hunger_bar = _progress_bar(p.hunger, 100, "饱食")
     sanity_bar = _progress_bar(p.sanity, 100, "理智")
@@ -819,9 +830,19 @@ def _format_status_panel(gs: GameState) -> str:
         "helmet": "头盔", "boots": "靴子",
     }
     equip_lines = []
-    for slot, item in p.equipment.items():
-        equip_lines.append(f"{slot_names.get(slot, slot)}: {item or '无'}")
-    equip_text = "<br>".join(equip_lines)
+    for slot, item in p.equipment.items():
+        equip_lines.append(f"{slot_names.get(slot, slot)}: {item or '无'}")
+    equip_text = "<br>".join(equip_lines)
+
+    def render_stat(stat_key: str, label: str) -> str:
+        base_value = int(getattr(p, stat_key))
+        bonus_value = int(equipment_bonuses.get(stat_key, 0))
+        effective_value = int(effective_stats.get(stat_key, base_value))
+        if bonus_value > 0:
+            return f"{label}: {effective_value} <span style='color:#4a6;'>(+{bonus_value} 装备)</span>"
+        if bonus_value < 0:
+            return f"{label}: {effective_value} <span style='color:#b44;'>({bonus_value} 装备)</span>"
+        return f"{label}: {base_value}"
 
     # 状态效果
     if p.status_effects:
@@ -895,16 +916,16 @@ def _format_status_panel(gs: GameState) -> str:
 </span>
 </div>
 
-<div>
-<h4 style="margin:4px 0 2px 0;">⚔️ 战斗属性</h4>
-<span style="font-size:0.85em;">
-攻击: {p.attack}<br>
-防御: {p.defense}<br>
-速度: {p.speed}<br>
-幸运: {p.luck}<br>
-感知: {p.perception}
-</span>
-</div>
+<div>
+<h4 style="margin:4px 0 2px 0;">⚔️ 战斗属性</h4>
+<span style="font-size:0.85em;">
+{render_stat("attack", "攻击")}<br>
+{render_stat("defense", "防御")}<br>
+{render_stat("speed", "速度")}<br>
+{render_stat("luck", "幸运")}<br>
+{render_stat("perception", "感知")}
+</span>
+</div>
 
 <div>
 <h4 style="margin:4px 0 2px 0;">💰 资源</h4>

state_manager.py

@@ -1115,9 +1115,9 @@ class GameState:
 
         return change_log
 
-    def validate(self) -> tuple[bool, list[str]]:
-        """
-        校验当前状态的合法性。
+    def validate(self) -> tuple[bool, list[str]]:
+        """
+        校验当前状态的合法性。
 
         设计思路：
         - 检查所有数值是否在合法范围内
@@ -1160,12 +1160,34 @@ class GameState:
             self.player.gold = 0
             issues.append("金币不足。")
 
-        is_valid = self.game_mode != "game_over"
-        return is_valid, issues
-
-    def to_prompt(self) -> str:
-        """
-        将当前完整状态序列化为自然语言描述，注入 System Prompt。
+        is_valid = self.game_mode != "game_over"
+        return is_valid, issues
+
+    def get_equipment_stat_bonuses(self) -> dict[str, int]:
+        """Aggregate stat bonuses from currently equipped items."""
+        bonuses: dict[str, int] = {}
+        for item_name in self.player.equipment.values():
+            if not item_name:
+                continue
+            item_info = self.world.item_registry.get(str(item_name))
+            if item_info is None:
+                continue
+            for stat_name, amount in item_info.stat_bonus.items():
+                bonuses[stat_name] = bonuses.get(stat_name, 0) + int(amount)
+        return bonuses
+
+    def get_effective_player_stats(self) -> dict[str, int]:
+        """Return display-oriented effective stats after equipment bonuses."""
+        bonuses = self.get_equipment_stat_bonuses()
+        tracked_stats = ("attack", "defense", "speed", "luck", "perception")
+        return {
+            stat_name: int(getattr(self.player, stat_name)) + int(bonuses.get(stat_name, 0))
+            for stat_name in tracked_stats
+        }
+
+    def to_prompt(self) -> str:
+        """
+        将当前完整状态序列化为自然语言描述，注入 System Prompt。
 
         设计思路（需求文档核心要求）：
         - System Prompt 必须包含当前状态描述
@@ -1794,16 +1816,50 @@ class GameState:
 
         return actions
 
-    def get_scene_summary(self) -> str:
-        """获取当前场景的简短摘要（用于 UI 展示）"""
-        loc = self.world.locations.get(self.player.location)
-        desc = loc.description if loc else "未知区域"
-        ambient = loc.ambient_description if loc else ""
+    def get_scene_summary(self) -> str:
+        """获取当前场景的简短摘要（用于 UI 展示）"""
+        loc = self.world.locations.get(self.player.location)
+        desc = loc.description if loc else "未知区域"
+        ambient = loc.ambient_description if loc else ""
 
         npcs = [
             npc.name for npc in self.world.npcs.values()
             if npc.location == self.player.location and npc.is_alive
         ]
         npc_str = f"可见NPC: {'、'.join(npcs)}" if npcs else ""
-
-        return f"{desc}\n{ambient}\n{npc_str}".strip()
+
+        return f"{desc}\n{ambient}\n{npc_str}".strip()
+
+    def get_consumable_rule_effects(self, item_name: str) -> dict[str, Any]:
+        """Parse deterministic consumable effects from item metadata."""
+        item_info = self.world.item_registry.get(str(item_name))
+        if item_info is None or not item_info.usable:
+            return {}
+
+        effect_text = str(item_info.use_effect or "").strip()
+        if not effect_text:
+            return {}
+
+        changes: dict[str, Any] = {}
+        numeric_rules = [
+            (r"恢复\s*(\d+)\s*HP", "hp_change", 1),
+            (r"恢复\s*(\d+)\s*MP", "mp_change", 1),
+            (r"恢复\s*(\d+)\s*饱食度", "hunger_change", 1),
+            (r"恢复\s*(\d+)\s*士气", "morale_change", 1),
+            (r"恢复\s*(\d+)\s*理智", "sanity_change", 1),
+            (r"降低\s*(\d+)\s*HP", "hp_change", -1),
+            (r"降低\s*(\d+)\s*MP", "mp_change", -1),
+            (r"降低\s*(\d+)\s*饱食度", "hunger_change", -1),
+            (r"降低\s*(\d+)\s*士气", "morale_change", -1),
+            (r"降低\s*(\d+)\s*理智", "sanity_change", -1),
+        ]
+
+        for pattern, key, sign in numeric_rules:
+            for match in re.finditer(pattern, effect_text):
+                amount = int(match.group(1)) * sign
+                changes[key] = int(changes.get(key, 0)) + amount
+
+        if "解除中毒状态" in effect_text:
+            changes["status_effects_removed"] = ["中毒"]
+
+        return changes

story_engine.py

@@ -580,9 +580,10 @@ class StoryEngine:
         # 清理状态变更：阻止非消耗品被错误移除
         # ============================================
         event_type = outline.get("event_type", "")
-        state_changes, sanitize_warnings = self._sanitize_state_changes(state_changes, event_type)
-        if sanitize_warnings:
-            logger.info(f"状态变更清理: {sanitize_warnings}")
+        state_changes, sanitize_warnings = self._sanitize_state_changes(state_changes, event_type)
+        state_changes, item_rule_notes = self._fill_missing_consumable_effects(state_changes, player_intent)
+        if sanitize_warnings:
+            logger.info(f"状态变更清理: {sanitize_warnings}")
 
         # ============================================
         # 应用状态变更
@@ -619,7 +620,10 @@ class StoryEngine:
         options = self._validate_options(options)
 
         # 合并 tick_log 和 change_log 中的重复属性条目
-        merged_log = _merge_change_logs(tick_log, change_log + validation_issues)
+        merged_log = _merge_change_logs(
+            tick_log,
+            change_log + validation_issues + item_rule_notes,
+        )
 
         return {
             "story_text": story_text,
@@ -1071,7 +1075,47 @@ class StoryEngine:
 
         return changes, warnings
 
-    def _strip_invalid_item_effects(self, state_changes: dict) -> dict:
+    def _fill_missing_consumable_effects(
+        self,
+        state_changes: dict,
+        player_intent: dict,
+    ) -> tuple[dict, list[str]]:
+        """
+        Fill missing consumable effects from item metadata without overriding model output.
+        """
+        if str(player_intent.get("intent", "")).upper() != "USE_ITEM":
+            return state_changes, []
+
+        consumed_items = [
+            str(item)
+            for item in state_changes.get("items_lost", [])
+            if self.game_state.is_item_consumable(str(item))
+        ]
+        if not consumed_items:
+            return state_changes, []
+
+        merged_changes = dict(state_changes)
+        applied_notes: list[str] = []
+
+        for item_name in consumed_items:
+            inferred = self.game_state.get_consumable_rule_effects(item_name)
+            if not inferred:
+                continue
+
+            applied_keys = []
+            for key, value in inferred.items():
+                if key in merged_changes:
+                    continue
+                merged_changes[key] = list(value) if isinstance(value, list) else value
+                applied_keys.append(key)
+
+            if applied_keys:
+                logger.info("按物品规则补全缺失效果: %s -> %s", item_name, applied_keys)
+                applied_notes.append(f"物品规则补全: {item_name}")
+
+        return merged_changes, applied_notes
+
+    def _strip_invalid_item_effects(self, state_changes: dict) -> dict:
         """
         当 LLM 生成了涉及不存在物品的状态变更时，移除相关效果（安全网）。
 
@@ -1450,10 +1494,11 @@ class StoryEngine:
 
         # 清理状态变更
         event_type = outline.get("event_type", "")
-        state_changes, sanitize_warnings = self._sanitize_state_changes(state_changes, event_type)
-
-        # 应用状态变更
-        change_log = self.game_state.apply_changes(state_changes)
+        state_changes, sanitize_warnings = self._sanitize_state_changes(state_changes, event_type)
+        state_changes, item_rule_notes = self._fill_missing_consumable_effects(state_changes, player_intent)
+
+        # 应用状态变更
+        change_log = self.game_state.apply_changes(state_changes)
 
         # 校验状态合法性
         is_valid, validation_issues = self.game_state.validate()
@@ -1482,7 +1527,10 @@ class StoryEngine:
         options = self._ensure_three_options(options)
 
         # 合并日志
-        merged_log = _merge_change_logs(tick_log, change_log + validation_issues)
+        merged_log = _merge_change_logs(
+            tick_log,
+            change_log + validation_issues + item_rule_notes,
+        )
 
         yield {
             "type": "final",