update effects

src/classes/effects.py

@@ -150,6 +150,70 @@ LEGAL_ACTIONS = "legal_actions"
   - "DevourMortals": 吞噬凡人（邪道法宝）
 """
 
+# =============================================================================
+# CSV 配置格式规范
+# =============================================================================
+
+"""
+## CSV 中 effects 列的写法（支持宽松JSON格式）
+
+### 基础格式（推荐）
+```
+{extra_battle_strength_points: 3}
+{extra_battle_strength_points: 2, extra_max_hp: 50}
+{legal_actions: ['DevourMortals'], extra_battle_strength_points: 2}
+```
+
+### 格式规则
+1. ✅ 无引号key（推荐）: {extra_battle_strength_points: 3}
+2. ✅ 单引号: {'extra_battle_strength_points': 3}
+3. ✅ 双引号: {"extra_battle_strength_points": 3}
+4. ✅ 混合使用: {key1: 1, 'key2': 2, "key3": 3}
+
+### 条件effect（when 子句）
+当 effect 需要根据条件生效时，使用 when 字段：
+
+```
+# 单条件
+[{when: 'avatar.weapon.type == WeaponType.SWORD', extra_battle_strength_points: 3}]
+
+# 多条件（满足任一条件即生效，effects会累加）
+[
+  {when: 'avatar.weapon.type == WeaponType.SWORD', extra_weapon_proficiency_gain: 1.0, extra_battle_strength_points: 3},
+  {when: 'avatar.alignment == Alignment.EVIL', extra_cultivate_exp: 20}
+]
+```
+
+### 动态表达式（eval）
+对于需要运行时计算的值，使用字符串形式的表达式：
+
+```
+{extra_battle_strength_points: 'avatar.weapon.special_data.get("devoured_souls", 0) // 100 * 0.1'}
+```
+
+注意：
+- eval 表达式在 Avatar.effects property 中动态计算
+- 可访问的变量：avatar, WeaponType, EquipmentGrade, Alignment
+- 表达式失败时默认为 0
+
+### 实际示例
+
+```csv
+# weapon.csv
+id,name,effects
+1,本命剑匣,{extra_battle_strength_points: 3}
+4,镇魂钟,{extra_battle_strength_points: 2, extra_observation_radius: 1}
+6,万魂幡,{legal_actions: ['DevourMortals'], extra_battle_strength_points: 'avatar.weapon.special_data.get("devoured_souls", 0) // 100 * 0.1'}
+
+# persona.csv - 条件effect
+32,剑痴,[{when: 'avatar.weapon.type == WeaponType.SWORD', extra_weapon_proficiency_gain: 1.0, extra_battle_strength_points: 3}]
+46,音律大师,[{when: 'avatar.weapon.type == WeaponType.ZITHER or avatar.weapon.type == WeaponType.FLUTE', extra_weapon_proficiency_gain: 1.0, extra_battle_strength_points: 3}]
+
+# technique.csv - 负面effect
+28,血神噬魂大法,{extra_breakthrough_success_rate: -0.1, extra_cultivate_exp: 50}
+```
+"""
+
 # =============================================================================
 # Effect 合并规则
 # =============================================================================
@@ -161,7 +225,7 @@ Effects 通过 src/classes/effect.py 中的 _merge_effects() 函数合并。
 1. 列表类型 (如 legal_actions): 取并集（去重）
 2. 数值类型 (如 extra_*): 累加
 3. 其他类型: 后者覆盖前者
-4. 动态表达式 (如 "eval(...)"): 在 Avatar.effects property 中 eval 计算
+4. 动态表达式 (字符串形式): 在 Avatar.effects property 中 eval 计算
 
 合并顺序（从低到高优先级）:
 1. 宗门 (sect)