GameHelper：公式逆向（模板拟合原型）(暂时没用的线性计算器)

中文 | English

项目介绍：

输入结构化数据（CSV/XLSX），输出 Top-K 候选公式（含参数、误差指标、变量映射），用于分析与复现游戏数值机制。

当前版本是原型：默认模板数量较少（线性 + 简单减伤），更多模板与字段推荐能力见 PROJECT_REVIEW.md。

快速开始

1) 创建/使用 conda 环境

推荐使用 conda（示例环境名 gamehelper）：

conda env create -f .\environment.yml
conda activate gamehelper

如果你已有自己的 Python 环境，确保包含：numpy / pandas / scipy。

2) 运行最小示例（合成数据）

python .\tests\test_formula_reverse_minimal.py

该脚本会：

• 在终端打印 Top-K 候选公式
• 在项目根目录写出 out_report.json

3) 用你自己的数据运行（CLI）

python -m gamehelper `
  --input path\to\data.xlsx `
  --target damage `
  --vars atk=ATK def=DEF `
  --out-json out_report.json `
  --top-k 10

参数说明：

• --input：CSV/XLSX 路径
• --target：目标列名（要拟合的输出列）
• --vars：变量映射，形如 内部变量名=表格列名（可传多组）
• --groups：可选，分组列名（用于按组交叉验证）
• --weight：可选，样本权重列名

输出内容

• 终端输出：Top-K 列表（候选公式、参数、cv_rmse、score 等）
• JSON 输出：完整报告（候选详情、指标、失败统计、建议等）

代码结构

• 入口：python -m gamehelper → gamehelper/main.py
• 主编排：候选生成 → 拟合 → 验证 → 排序 → 报告 → gamehelper/engine.py
• 模板：定义公式结构与 predict() → gamehelper/templates
• 拟合器：参数拟合（scipy least_squares）→ gamehelper/fitters/scipy_ls.py
• 验证：K 折/按组 K 折 → gamehelper/validation.py
• 接口契约：数据结构定义 → gamehelper/types.py

许可证

Apache-2.0，详见 LICENSE。