EFT 现实主义数值生成器使用指南（v3.15）
<NolebasePageProperties />
下载链接：
直接下载：
https://github.com/windersvista/Realism-patch-Generator/releases/tag/3.15
源代码：
本文档说明当前生成器的输入格式、处理流程、规则入口、输出策略，以及审计与回归测试的配套用法。
1. 工具作用
generate_realism_patch.py 会读取 input/ 中的物品数据，结合 现实主义物品模板/ 重建 Realism 补丁对象，并把结果输出到 output/。
当前版本具备以下特征：
- 支持 CURRENT_PATCH、STANDARD、CLONE、ITEMTOCLONE、VIR、TEMPLATE_ID 六类输入。
- 输出只按源文件导出，并保留 input/ 相对目录结构。
- 每次运行前自动清空 output/，避免旧结果混入。
- 武器、附件、弹药规则分别由独立规则文件维护。
- 静态映射与默认模板已拆分到 generator_static_data.py。
- 审计脚本与名称回归测试已纳入正式工作流。
2. 环境要求
- Python 3.8 及以上
- 建议使用项目内 .venv
- Windows 可直接双击 现实主义数值生成器.bat
命令行推荐写法：
powershell
.\.venv\Scripts\python.exe generate_realism_patch.py3. 当前目录职责
- generate_realism_patch.py：主流程，负责识别、构建、规则应用、导出
- generator_static_data.py：静态映射、默认模板、特殊字段配置
- weapon_rule_ranges.py：武器一级基础区间
- weapon_refinement_rules.py：武器口径与枪托二级修正
- attachment_rule_ranges.py：附件档位规则
- ammo_rule_ranges.py：弹药三层规则
- audit_output_rule_violations.py：输出审计
- tests/test_name_extraction.py：名称回填回归测试
- input/：输入数据
- output/：生成结果
- audit_reports/：审计报告输出目录
4. 快速开始
方式 A：双击批处理
- 将待处理 JSON 放入 input/
- 双击 现实主义数值生成器.bat
- 在 output/ 查看结果
方式 B：命令行运行
powershell
.\.venv\Scripts\python.exe generate_realism_patch.py5. 输入格式
脚本会自动识别以下格式：
5.1 CURRENT_PATCH
- 特征：包含 $type 与 ItemID
- 处理方式：直接以输入对象为基线重算与校验
5.2 STANDARD
- 特征：包含 parentId 或 itemTplToClone
- 处理方式：解析 parentId，再按模板或默认模板构建
5.3 CLONE
- 特征：包含 clone
- 处理方式：优先按模板查找，必要时递归解析同文件引用链
5.4 ITEMTOCLONE
- 特征：包含 ItemToClone
- 处理方式：通过常量或映射推断类型，再按模板重建
5.5 VIR
- 特征：包含 item._id 与 item._parent
- 处理方式：提取 item 节点，统一归一化后走主流程
5.6 TEMPLATE_ID
- 特征：包含 TemplateID 或模板直接引用
- 处理方式：直接按模板构建基线对象
6. 输出规则
- 输出根目录固定为 output/
- 目录结构与 input/ 保持一致
- 每次运行前会清空 output/
输出文件命名：
- 默认：原文件名_realism_patch.json
- 若某源文件中 CURRENT_PATCH 占比大于 50%：保持原文件名输出
7. 核心处理流程
当前生成器遵循“识别 -> 构建 -> 合并 -> 校验 -> 导出”的流水线：
- 递归扫描 input/ 下所有 JSON
- 逐文件逐条目识别格式
- 提取统一 item_info
- 依据模板、默认模板和静态映射构建基线补丁
- 合并输入属性
- 进入 apply_realism_sanity_check() 做规则校验
- 按物品类型统计，并按源文件聚合
- 清空 output/ 后导出
8. 规则应用顺序
在 apply_realism_sanity_check() 中，当前顺序为：
- 补齐必填字段
- 应用材质、尺寸、枪管长度等启发式预处理
- 做全局基础夹紧
- 按物品类型进入专项规则： - Gun：weapon_rule_ranges.py -> weapon_refinement_rules.py - WeaponMod：attachment_rule_ranges.py - Ammo：ammo_rule_ranges.py - Gear：仅应用当前 Gear 夹紧规则
- 做最终安全兜底
9. 调参入口
9.1 武器
改 weapon_rule_ranges.py：调整一级基础档位。 改 weapon_refinement_rules.py：调整口径修正、枪托修正和关键词映射。
9.2 附件
改 attachment_rule_ranges.py：调整附件档位区间。 补充说明：附件规则应用启用了 ensure_fields=True，缺失字段会先补种子值再采样。
9.3 弹药
改 ammo_rule_ranges.py：
- AMMO_PROFILE_RANGES：第一层口径基础区间
- AMMO_PENETRATION_TIERS / AMMO_PENETRATION_MODIFIERS：第二层穿深修正
- AMMO_SPECIAL_KEYWORDS / AMMO_SPECIAL_MODIFIERS：第三层弹种型号修正
9.4 静态映射
改 generator_static_data.py：
- PARENT_ID_TO_TEMPLATE：parentId 到模板文件映射
- ITEM_TYPE_NAME_TO_ID：字符串类型名到标准 ID 的映射
- DEFAULT_*_TEMPLATE：默认模板
- MOD_TYPE_SPECIFIC_ATTRS：特殊 ModType 补字段
10. 审计与回归测试
审计输出
powershell
.\.venv\Scripts\python.exe audit_output_rule_violations.py默认会：
- 扫描 output/ 下全部结果
- 输出 audit_reports/output_rule_audit.json
- 在终端打印违规与警告摘要
当前审计策略补充：
- consumable/cosmetic 不作为规则审计重点
- mod_profile_unresolved 不计入附件未命中警告
名称回归测试
powershell
.\.venv\Scripts\python.exe -m unittest tests.test_name_extraction覆盖范围：
- CLONE 的 locales 名称回填
- STANDARD 的 locales 名称回填
- VIR 优先使用 item._name
- ITEMTOCLONE 的 LocalePush 回填
- CURRENT_PATCH 的 Name / locales 优先级
- 审计器回读源名称逻辑
11. 常见问题
输出为空
- 检查 input/ 是否包含合法 JSON
- 检查输入是否满足支持格式之一
部分物品被跳过
- 先查看终端中的跳过原因
- 常见原因是 parentId 缺失、模板找不到、格式不可识别
瞄具分类不稳定
- 优先检查 Name 关键词是否足够明确
- 当前 sight 规则是“名称关键词优先，未命中时再回退模板/parent，ScopeTemplates 默认 red dot”
弹匣档位异常
- 检查是否有 Capacity 或 CartridgeMaxCount
- 缺少容量字段时会回退到 magazine 标准兼容档
为什么 README 说优先改配置文件，不建议改主脚本
- 因为大多数调参都已经外置
- 主脚本现在主要负责流程编排，直接改它更容易引入回归
12. 推荐维护顺序
- 先小样本跑通生成
- 调整规则文件
- 重新生成并查看 output/
- 跑审计脚本
- 必要时跑名称回归测试
- 最后再处理全量输入
贡献者
<NolebaseGitContributors />
文件历史
<NolebaseGitChangelog />