From 384502e4653a049164ce1b77a473a685a057bf30 Mon Sep 17 00:00:00 2001
From: liutao <821580467@qq.com>
Date: Thu, 5 Feb 2026 13:24:06 +0800
Subject: [PATCH] =?UTF-8?q?=E3=80=90AI=E7=BC=96=E7=A0=81=E3=80=91=E5=A2=9E?=
 =?UTF-8?q?=E5=8A=A0=E6=96=87=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 ProjectNLD/AI_Gen_Doc/武器熟练度功能说明.md | 182 ++++++++++++++++++++
 1 file changed, 182 insertions(+)
 create mode 100644 ProjectNLD/AI_Gen_Doc/武器熟练度功能说明.md

diff --git a/ProjectNLD/AI_Gen_Doc/武器熟练度功能说明.md b/ProjectNLD/AI_Gen_Doc/武器熟练度功能说明.md
new file mode 100644
index 00000000000..0bca93fdcce
--- /dev/null
+++ b/ProjectNLD/AI_Gen_Doc/武器熟练度功能说明.md
@@ -0,0 +1,182 @@
+# 武器熟练度（WeaponDegree）功能说明
+
+> 本文档由 AI 生成，用于说明武器熟练度的设计与配置。
+
+## 功能定义
+
+`WeaponDegree`（武器熟练度）是角色的战斗属性之一，用于**减少攻击间隔时间（attackEndTime）**，从而提升攻击频率。
+
+**策划描述**：提升武器熟练度可以减少单位作战时的瞄准时间和攻击间隔时间。
+
+**⚠️ 实际逻辑**：当前代码中武器熟练度**只影响攻击间隔时间（attackEndTime）**，不直接影响瞄准时间（raiseWeaponTime）。
+
+---
+
+## 属性定义
+
+在 `AttributeType` 枚举中定义：
+
+**文件**：`Assets/Code/Scripts/GenCode/Luban/DataTable/ActorCfg/AttributeType.cs`
+
+```csharp
+/// <summary>
+/// 武器熟练度
+/// </summary>
+WeaponDegree = 5,
+```
+
+---
+
+## CD缩放公式
+
+武器熟练度通过 CD 缩放系数（cdScale）影响攻击间隔时间。
+
+**文件**：`Assets/Code/Scripts/GamePlay/Fight/Weapon/UnitWeaponConfigDataHelper.cs`
+
+```csharp
+/// <summary>
+/// 根据武器熟练度计算CD缩放系数
+/// </summary>
+/// <param name="weaponDegree">武器熟练度</param>
+/// <returns>CD缩放系数</returns>
+private static float CalculateCdScale(float weaponDegree)
+{
+    var globalDegreeFix = TableManager.Instance.Tables.GlobalFightConfig.FightWeaponDegreeFix;
+    return (1 - (weaponDegree - globalDegreeFix)) / 2;
+}
+```
+
+### 公式说明
+
+```
+cdScale = (1 - (weaponDegree - FightWeaponDegreeFix)) / 2
+```
+
+- `weaponDegree`：角色当前的武器熟练度
+- `FightWeaponDegreeFix`：全局配置的熟练度初始值（来自 `GlobalFightConfig` 表）
+- `cdScale`：最终的 CD 缩放系数，用于乘以基础攻击间隔时间
+
+### 应用方式
+
+```csharp
+configData.attackEndTime = baseAttackEndTime * cdScale;
+```
+
+### 数值示例
+
+假设 `FightWeaponDegreeFix = 0`：
+
+| weaponDegree | cdScale | 效果 |
+|--------------|---------|------|
+| 0 | 0.5 | 攻击间隔缩短 50% |
+| 0.5 | 0.25 | 攻击间隔缩短 75% |
+| 1 | 0 | 攻击间隔为 0（理论最小值） |
+| -1 | 1 | 攻击间隔无缩减 |
+
+---
+
+## 武器熟练度的计算来源
+
+武器熟练度由三个养成系统累加计算。
+
+**文件**：`Assets/Code/Scripts/GamePlay/UI/ShowAllCharacter/CharacterDataInfo.cs`
+
+```csharp
+public float WeaponDegree(int level = -1, int awakeLevel = -1, int breakLevel = -1)
+{
+    return GetAttriLevelUp(level, AttributeType.WeaponDegree, awakeLevel)   // 等级提升
+        + GetAttriAwakeUp((int)awakeLevel, AttributeType.WeaponDegree)      // 觉醒提升
+        + GetAttriBreakUp((int)breakLevel, AttributeType.WeaponDegree);     // 突破提升
+}
+```
+
+### 三个来源
+
+| 来源 | 配置表 | 说明 |
+|-----|--------|------|
+| 等级提升 | `CharacterLevelUp` | 根据角色等级模板和成长系数计算 |
+| 觉醒提升 | `CharacterAwaking` | 从 `AttributeGroup` 字段获取 |
+| 突破提升 | `CharacterBreak` | 从 `AttributeGroup` 字段获取 |
+
+---
+
+## 适用的单位类型
+
+| 单位类型 | 熟练度来源 | 构建方法 |
+|---------|-----------|---------|
+| 玩家角色 | `CharacterDataInfo.WeaponDegree()` | `BuildCharacterWeaponFromCultivate()` |
+| 怪物 | `DataMonsterClass.WeaponDegree` | `BuildCharacterWeaponFromMonster()` |
+| NPC | `DataFightNPC.WeaponDegree` | `BuildCharacterWeaponFromNpc()` |
+
+**⚠️ 注意**：载具和建筑不使用武器熟练度属性。
+
+---
+
+## 相关配置表
+
+| 配置表 | 说明 |
+|-------|------|
+| `GlobalFightConfig` | 包含 `FightWeaponDegreeFix` 全局熟练度初始值 |
+| `CharacterLevelUp` | 角色升级属性模板，`AttributeGroup` 可包含 WeaponDegree 增量 |
+| `CharacterAwaking` | 角色觉醒配置，`AttributeGroup` 可包含 WeaponDegree |
+| `CharacterBreak` | 角色突破配置，`AttributeGroup` 可包含 WeaponDegree |
+| `MonsterClass` | 怪物配置，直接包含 `WeaponDegree` 字段 |
+| `FightNPC` | NPC 配置，直接包含 `WeaponDegree` 字段 |
+
+---
+
+## UI 显示位置
+
+| 文件 | 说明 |
+|-----|------|
+| `UI_CultivateDetailNewController.cs` | 角色培养详情界面，第 195 行 |
+| `UI_CultivateChangeController.cs` | 角色培养变更界面，第 1050 行 |
+
+---
+
+## 配置错误可能导致的问题
+
+### 1. FightWeaponDegreeFix 配置过高
+
+**现象**：
+- `cdScale` 计算结果大于 1
+- 攻击间隔时间反而变长
+
+**影响**：角色攻击频率降低，战斗手感变慢
+
+### 2. WeaponDegree 配置过高
+
+**现象**：
+- `cdScale` 计算结果为 0 或负数
+- 攻击间隔时间为 0
+
+**影响**：可能导致无限攻击或逻辑异常
+
+### 3. 养成表未配置 WeaponDegree 属性
+
+**现象**：
+- 角色升级/觉醒/突破后武器熟练度不变化
+- `GetAttriLevelUp` 等方法返回 0
+
+**影响**：养成系统无法提升武器熟练度
+
+---
+
+## 相关代码文件
+
+| 文件路径 | 说明 |
+|---------|------|
+| `Assets/Code/Scripts/GenCode/Luban/DataTable/ActorCfg/AttributeType.cs` | 属性类型枚举定义 |
+| `Assets/Code/Scripts/GenCode/Luban/DataTable/GlobalFightConfig.cs` | 全局战斗配置（FightWeaponDegreeFix） |
+| `Assets/Code/Scripts/GamePlay/Fight/Weapon/UnitWeaponConfigDataHelper.cs` | 武器配置构建工具类（CalculateCdScale） |
+| `Assets/Code/Scripts/GamePlay/UI/ShowAllCharacter/CharacterDataInfo.cs` | 角色数据信息（WeaponDegree 计算） |
+| `Assets/Code/Scripts/GenCode/Luban/DataTable/CharacterCfg/DataCharacterLevelup.cs` | 角色升级配置 |
+| `Assets/Code/Scripts/GenCode/Luban/DataTable/CharacterCfg/DataCharacterAwaking.cs` | 角色觉醒配置 |
+| `Assets/Code/Scripts/GenCode/Luban/DataTable/CharacterCfg/DataCharacterBreak.cs` | 角色突破配置 |
+| `Assets/Code/Scripts/GenCode/Luban/DataTable/MonsterCfg/DataMonsterClass.cs` | 怪物配置 |
+| `Assets/Code/Scripts/GenCode/Luban/DataTable/FightCfg/DataFightNPC.cs` | NPC 配置 |
+
+---
+
+*文档生成时间：2026-02-05*
+*生成工具：Cursor AI Agent*