学完本教程，你将能独立完成李鹤龄体系下的完整操作流程，并规避新手最常见的5个致命错误。
---
第一步：明确李鹤龄体系的定位与适用边界
李鹤龄不是通用工具，而是一套针对特定场景的“精算型”操作框架。开始前，先确认你的需求是否匹配：它适用于需要高精度数据校验、多变量交叉验证或历史轨迹回溯的任务。具体做法：①列出你手头问题的三个核心指标（如误差率、时效性、成本）；②对比李鹤龄体系的默认参数（通常要求输入值波动≤5%）；③若指标匹配，进入下一步，否则直接改用通用方案，避免强行套用。
第二步：搭建环境与初始化配置
操作前必须完成三件事，缺一不可：
1. 安装核心依赖包（版本锁定为2.4.x，切勿用最新版，兼容性已知问题多）。
2. 创建独立工作目录，路径中禁止出现中文和空格。
3. 初始化配置文件`lhl_config.yaml`，填入你的基础参数（至少包含`input_path`、`output_path`、`precision=0.001`三项）。
执行命令`lhl init --force`，系统会自动生成默认模板。若报错“missing key”，检查YAML缩进是否为两个空格。
第三步：数据预处理——清洗与格式化
李鹤龄对脏数据零容忍。具体做法：
① 将原始数据转为UTF-8编码的CSV，列名统一为小写加下划线（如`user_id`，禁止`UserID`）。
② 缺失值处理：数值列用中位数填充，文本列用“UNKNOWN”填充，禁止删除行。
③ 异常值检测：运行`lhl scan --outliers`，系统会标记超过3σ的数值，人工确认后选择保留或替换为边界值。
④ 最后运行`lhl format --check`，直到输出“PASS”方可继续。
第四步：核心运算——参数调优与执行
这是最关键的环节，直接决定结果质量。
1. 设定初始参数：`learning_rate=0.05`，`max_iter=2000`，`regularization=0.1`。
2. 执行`lhl run --mode fast`，观察损失曲线。若收敛速度过慢（前500轮损失下降<5%），将`learning_rate`调至0.1；若震荡剧烈，则降至0.02。
3. 当损失曲线平稳后，切换`--mode precise`，系统会自动进行二次精算。此阶段禁止中途打断。
4. 输出结果前，运行`lhl validate --split 0.2`，用20%数据做交叉验证，确保泛化误差<3%。
第五步：结果导出与报告生成
验证通过后，按规范导出：
① 生成主结果文件`result.csv`，包含原始ID、预测值、置信区间三列。
② 运行`lhl report --format pdf`，自动生成带图表的分析报告。
③ 手动检查报告中的关键摘要（第2页“核心发现”部分），若出现“警告：置信区间过宽”，需返回第四步调整`regularization`至0.3后重跑。
④ 将报告重命名为“日期_项目名_李鹤龄报告.pdf”归档。
第六步：复核与存档
最后一步不可跳过：
- 用`lhl diff --old result.csv --new result_backup.csv`对比本次与上次结果，差异率>1%则需排查数据源是否变动。
- 将工作目录整个压缩为`.tar.gz`，存放至备份盘，保留至少30天。
- 在项目日志中记录本次运行的参数版本（`lhl version`的输出）和操作人。
---
常见坑提醒（必读）
1. 别用默认参数跑完就交差——李鹤龄的默认值只保证“能跑”，不保证“准确”，必须手动调优。
2. 中途断电/断网：运行`--mode precise`时务必接UPS，否则缓存文件损坏后无法恢复，只能重跑。
3. 忽略日志警告：看到“Warning: memory usage >80%”别无视，会导致计算中途崩溃，建议分批处理数据。
4. 备份文件覆盖：`result_backup.csv`是自动覆盖的，如果你需要历史版本，手动复制到带日期后缀的文件。
5. 跨平台迁移：Windows下生成的路径分隔符在Linux上会报错，统一用`os.path.join`或手动改为`/`。
按以上六步操作，你已能完整驾驭李鹤龄体系。记住：这套方法的核心不是“跑完”，而是“每一步都经得起验证”。
