XGBoost/LightGBM Tabular Data Trainer

⛔ CRITICAL — 严格按本 skill 执行，禁止跳过。
当用户提供 CSV/表格数据并要求训练模型（无论是否提 XGBoost/LightGBM），
必须从 Step 1 开始走完 6 步流程。不允许自行写脚本、手动调 sklearn、或跳过任何步骤。
每个步骤必须严格完成 MUST checklist 中所有项目，才能进入下一步。
不允许缩短流程、合并步骤、或用「快速完成」替代。

⛔ CRITICAL — 禁止随意摘取、修改、省略 skill 指定的输出内容。
1. 必须通过文件读取展示：每个 Step 完成后，必须运行 report_formatter.py --output-file <path> 将输出写入 .md 文件，然后用 Read 工具读取该文件，将完整内容原样展示给用户。禁止直接从 stdout 摘要、省略表格、或用自己的总结替代。
2. 必须完成展示校验清单：每个 Step 展示后，必须列出校验清单并逐项打 ✅ 确认所有板块已完整展示。未完成校验前不得问"继续下一步？"。
3. 必须按 skill 指定的格式交互：用户输入确认后，按 skill 定义的流程走，禁止自行改变交互方式或跳过交互步骤。
4. 唯一允许偏离的情况：遇到代码 bug（如脚本报错、文件不存在、参数不匹配等），agent 可以自行修复后继续执行。除此之外，agent 必须无脑按照 skill 执行，不得自作主张。

End-to-end 6-step pipeline for training gradient boosting models on tabular binary classification data.

Architecture

skill.md  ──→  Claude Code Agent  ──→  AskUserQuestion / inline text (user interaction)
                  │
                  └──→  Bash (python scripts with --arg CLI params, no input())
                            │
                            └──→  JSON result files (step outputs)

Scripts are non-interactive — all inputs come from CLI arguments via argparse.
The Claude Code Agent is the sole interaction layer, collecting user decisions via
AskUserQuestion or inline text prompts, then passing them as --arg values to scripts.

Pre-flight Checks

• All scripts in {skill_path}/scripts/
• Python command: use python (Windows), not python3
• Required packages: numpy, pandas, scipy, scikit-learn, xgboost, lightgbm, optuna, openpyxl, psutil
• Windows paths: Python scripts MUST use Windows-native paths (C:\Users\...), not Unix-style (/c/Users/...)
• ⛔ Windows path quoting trap: Never end a Windows path argument with \ in bash — "D:\output\" causes \" to be parsed as an escaped quote, breaking the command. Always strip the trailing backslash: use "D:\output" not "D:\output\".

⛔ LANGUAGE DETECTION

Detect the user's language from their first message and use that language for ALL output.

Pipeline Overview

Step 1: Setup output directory
  ↓
Step 2: Data analysis (auto, displays on screen → analysis.json + optional step2_summary.txt)
  ↓
Step 3: Data processing (user chooses target/split → processed_data.json)
  ↓
Step 4: Model plan (user chooses model/mode → model_plan.json)
  ↓
Step 5: Model training (Coarse → FS → Coarse_sel → Fine → Final → training_results.json)
  ↓
Step 6: Model report & deployment decision → deployment_info.json

Each step writes its result to a JSON file in output_dir/. Subsequent steps read those JSON files. There is NO shared config.json — each step is self-contained.

Tuning Strategy — Split-Dependent

The tuning strategy is determined by the data split chosen in Step 3:

• 3-way: coarse_tuning and fine_tuning use df_valid for trial evaluation (no CV). Feature selection uses df_valid directly. train_final uses Valid for early stopping.
• 2-way: coarse_tuning and fine_tuning use K-fold CV on df_train. Feature selection creates a temporary holdout from Train. After best params are found, train_final trains on full Train using CV's median best_iteration.
• Custom params: User-specified parameters are used as-is, no early stopping anywhere.
• 2-way: 5-fold CV without early stopping → Train metrics from per-fold train averages, Valid metrics from CV OOF. train_final trains on full Train for exactly n_round (deployment only, metrics not reported).
• 3-way: train_final trains on Train with Valid monitored (but no early stopping), runs full n_round. Train metrics from Train predictions, Valid metrics from Valid predictions.

Agent Execution Rules

1. Never chain steps with heredocs or piping — run each step individually as a Bash command with explicit --arg values
2. After every AskUserQuestion rejection (user denies tool use or it fails twice): fall back to inline text prompts (see Fallback Protocol below)
3. Always Read the output JSON after a step completes to verify it was generated correctly
4. Show key results (metrics, file paths) to the user after each step
5. ⛔ Step Completion & Transition — Before moving to the next step, the Agent MUST internally verify every "MUST" item from that step's instructions. If any item is missing, fix it BEFORE asking the transition question. After the self-check passes, ask:
   继续下一步？(y/n)
   Do NOT automatically proceed. Wait for the user to type y before continuing.
   Exception: When "Both" models are selected in Step 4, XGBoost Step 5 completion auto-triggers LightGBM Step 5 without asking. The "继续下一步？" prompt only appears after Step 4 (before starting XGBoost Step 5) and after ALL Step 5 training is done (before Step 6).
6. ⛔ 文件缓冲模式（File-Buffer Pattern） — 脚本执行与 LLM 分析分离，中间用文件做缓冲：
   - 落盘：所有脚本将结构化结果写入 JSON 文件；长时训练（Step 5）通过 FileOnlyLogger 将 stdout/stderr 全部重定向到日志文件（终端在训练期间无输出）
   - 读取：Agent 使用 Read 工具读取 JSON/MD 文件获取结果；大日志文件使用 log_reader.py（--head/--tail/--page）分页读取，避免一次性加载
   - 报告另存：每步通过 report_formatter.py --output-file 生成 .md 文件，Agent 用 Read 读取展示

AskUserQuestion Fallback Protocol

If AskUserQuestion is rejected twice for the same question, output options as numbered inline text:

请直接回复选项编号（可多选）：

[1] XGBoost — 梯度提升，对不平衡数据友好
[2] LightGBM — 更快的训练速度，内存效率高

请直接回复选项编号，多选如 1,2。

Step-by-Step Agent Instructions

Step 1: Setup — 🔴 INTERACTIVE

⛔ Do NOT use AskUserQuestion for this step. Use inline text prompt only.

Ask the user where to save output with inline text:

> 项目输出保存到哪个目录？（直接输入路径，或回复「auto」使用默认 ./output/）

Then run:

python {skill_path}/scripts/step1_setup.py --output-dir <path>

If user replies "auto": use {cwd}/output/.

⛔ The path given by the user is the BASE directory (<base>). Each step writes to <base>/step<N>_<name>/ (see Output Directory Structure below for exact paths). The Agent MUST pass the step-specific subdirectory as --output-dir for each step, and use absolute paths when referencing files between steps.

Output: creates directory, prints confirmation.

Step 2: Data Analysis

Run the script:

python {skill_path}/scripts/step2_analyze.py --csv <path> --output-dir <base>/step2_analysis/

After script completes, the Agent MUST:

1. Read <base>/step2_analysis/analysis.json
2. Run the formatter with --output-file to generate the display summary and save it to a file:

python {skill_path}/scripts/report_formatter.py --step2 <base>/step2_analysis/analysis.json --output-file <base>/step2_analysis/step2_display.md

3. Read <base>/step2_analysis/step2_display.md using the Read tool.
4. Display the file content verbatim — copy the full content from the Read result into your response. Do NOT summarize, excerpt, or rephrase.

展示校验清单（完成展示后必须逐项确认）：

Agent MUST 在展示内容之后，列出上述清单并逐项打 ✅。如有遗漏，立即补充后再问"继续下一步？(y/n)"。

Output: analysis.json (includes top_n_rows), step2_summary.txt (convenience log, optional read), step2_display.md (formatted display)

Step 3: Data Processing — 🔴 INTERACTIVE

Collect 7 decisions one-by-one. Before EACH question, display a checklist so the user knows where they are.

Keyword shortcuts: 默认 = use default value | 跳过 = skip/empty | 自动 = auto-detect

Before asking item 1 (目标列), the Agent MUST auto-detect the likely target:
- Look for columns with binary values (2 unique values) named like is_*, target, label, y, flag_*, *_bad, *_flag
- Present the detected column as the default

Before asking item 6 (One-hot列), the Agent MUST read analysis.json categorical_cols and numeric_like_cols (auto-detected by step2) and present them to the user.

Before EACH question, the Agent MUST display a live checklist showing:

Step 3 — 数据预处理

  1. 目标列          -> [已确认/自动检测] ✅
  2. 排除列          -> [已确认] ✅
  ...
  N. {当前项}        -> [待确认]

Item prompts and defaults (use exactly these prompts; see Keyword shortcuts above):

After script completes, the Agent MUST:

1. Run the formatter with --output-file:

python {skill_path}/scripts/report_formatter.py --step3 <base>/step3_processing/processed_data.json --output-file <base>/step3_processing/step3_display.md

2. Read <base>/step3_processing/step3_display.md using the Read tool.
3. Display the file content verbatim — copy the full content from the Read result into your response. Do NOT summarize, excerpt, or rephrase.

展示校验清单（完成展示后必须逐项确认）：

Agent MUST 在展示内容之后，列出上述清单并逐项打 ✅。如有遗漏，立即补充后再问"继续下一步？(y/n)"。

After collecting all answers, run:

python {skill_path}/scripts/step3_process.py \
    --csv <path> \
    --output-dir <base>/step3_processing/ \
    --target <col> \
    --exclude-cols <cols...> \
    --mark-col <col_or_omit> \
    --outlier-vals <vals...> \
    --force-keep <cols...> \
    --onehot-cols <cols...> \
    --split <random_3way|random_2way|custom_3way|custom_2way> \
    [--split-col <col> --train-vals <...> --valid-vals <...> --test-vals <...>] \
    --seed 42

⚠️ 参数传递规则：

⛔ 绝对不要传入空字符串，如 --mark-col "" 或 --exclude-cols ""。当用户选择"跳过"时，直接省略该 CLI 参数即可。

Output: processed_data.json, processed_data.csv, train_data.csv, test_data.csv, valid_data.csv (if 3-way), statistical_analysis.xlsx

Step 4: Model Plan — 🔴 INTERACTIVE

⛔ Step 4 MUST use one single AskUserQuestion call with 2 questions so the user answers both at once. Do NOT split into separate calls. Do NOT skip to inline text unless AskUserQuestion fails.

Show a checklist before the AskUserQuestion:

Step 4 — 模型方案

  1. 模型类型         -> [待确认]
  2. 训练模式         -> [待确认]

Single AskUserQuestion call — 2 questions together:

Question 1 — Model type (multiSelect: true):
- [1] XGBoost — 梯度提升，适合不平衡数据 (推荐)
- [2] LightGBM — 更快的训练速度，内存效率高

Question 2 — Training mode (single select):
- [1] Fast — 基于样本量推荐默认参数 (最快)
- [2] Optimal — Optuna 超参数调优 + 特征选择 (推荐)
- [3] Custom — 自定义参数

If user selects both XGBoost + LightGBM → both models with the same training mode.

After AskUserQuestion result, the Agent MUST:

• If mode is "optimal" — compute adaptive defaults and ask for confirmation BEFORE running step4_plan.py:

python {skill_path}/scripts/step4_plan.py --processed-json <base>/step3_processing/processed_data.json --model <xgb|lgb> --mode optimal --show-defaults

Then show the computed values:

Optimal 模式参数（根据 {N_SAMPLES} 样本 / {N_FEATURES} 特征自适应）：

| 参数 | 值 |
|------|-----|
| 特征数范围 | {feature_count_min}-{feature_count_max} |
| 每次迭代删除 | {delete_per_iter} |
| AUC gap 阈值 | {gap_threshold} |
| 粗调/精调试验次数 | {n_trials} |
| Gap penalty scale | {gap_penalty_scale} |

When both models are selected, run --show-defaults for each model type (xgb and lgb) and present both.

回复 `默认` 确认，需要调整请说明。

• If mode is "custom" — ask for custom params BEFORE running step4_plan.py:

> 请输入自定义参数 key=value，逗号分隔。例如: max_depth=6, eta=0.1, n_round=200
> 常用 XGBoost: max_depth, eta, min_child_weight, subsample, colsample_bytree, n_round
> 常用 LGB: num_leaves, learning_rate, min_child_samples, bagging_fraction, feature_fraction, n_round
>
> Agent: parse comma-separated key=value pairs into JSON string, then pass as --custom-params '<json>' to step4_plan.py.

• If mode is "fast" — no extra confirmation needed, proceed directly to step4_plan.py.

After all confirmations collected:

If single model selected (xgb or lgb):

python {skill_path}/scripts/step4_plan.py \
    --processed-json <base>/step3_processing/processed_data.json \
    --output-dir <base>/step4_plan/ \
    --model <xgb|lgb> \
    --mode <fast|optimal|custom>

If both models selected (both):

1. Run step4_plan.py for XGBoost → <base>/step4_plan/model_plan_xgb.json (use --output-name model_plan_xgb.json)
2. Run step4_plan.py for LightGBM → <base>/step4_plan/model_plan_lgb.json (use --output-name model_plan_lgb.json)
3. Show BOTH plan summaries side by side to the user
4. Ask ONE "继续下一步？(y/n)" — do NOT ask separately for each model
5. After user confirms:
   a. Run step5_train.py with XGBoost plan + --output-prefix xgb_
   b. Then IMMEDIATELY run step5_train.py with LightGBM plan + --output-prefix lgb_
   c. Do NOT ask for confirmation between XGBoost and LightGBM training
6. After ALL training done, ask user which model(s) to use for Step 6

--output-prefix keeps both models' outputs separate in the same directory — no manual backup needed.

Output: model_plan.json (single), or model_plan_xgb.json + model_plan_lgb.json (both)

Step 5: Model Training

⛔ CRITICAL 执行规则：

1. 使用 run_in_background=true 启动训练，以便 Agent 在训练期间通过文件轮询监控进度。Bash 工具没有 command_type、blocking、wait_ms_before_async 参数，不要使用它们。
2. 训练启动后，后台任务在独立进程中运行，不受终端槽位影响。Agent 通过 Read 工具监控 <prefix>training_progress_tail.txt、<prefix>train_heartbeat.json、<prefix>step5_complete.json 三个文件。
3. 训练期间避免运行 Bash 命令（包括 log_reader.py、sleep 等）— 虽然 run_in_background 的训练进程本身不受终端槽位影响，但避免意外。优先使用 Read / Grep 等文件工具，训练完成后再用 Bash 读取日志。
4. 文件存在性检查必须用 Read 工具，⛔ 禁止用 Glob — Glob 有缓存问题，可能误报文件不存在。Read 文件不存在时会返回错误，比 Glob 更可靠。
5. 如果训练被中断需要重跑，脚本会自动清理旧的 optuna_study.db，无需手动干预

正确示例：

Bash(
    command="python {skill_path}/scripts/step5_train.py ...",
    description="Start XGBoost optimal training in background",
    timeout=600000,
    run_in_background=True
)

错误示例：

# ❌ 使用不存在的参数
Bash(
    command="python {skill_path}/scripts/step5_train.py ...",
    blocking=False,
    command_type="long_running_process",
    wait_ms_before_async=5000
)

# ❌ 用 Glob 检查文件是否存在 — 有缓存问题，可能误报不存在
Glob(".../step5_complete.json")  # 错误！应使用 Read

训练命令：

# Single model
python {skill_path}/scripts/step5_train.py \
    --plan-json <base>/step4_plan/model_plan.json \
    --output-dir <base>/step5_training/

# Both models (XGBoost)
python {skill_path}/scripts/step5_train.py \
    --plan-json <base>/step4_plan/model_plan_xgb.json \
    --output-dir <base>/step5_training/ \
    --output-prefix xgb_

# Both models (LightGBM)
python {skill_path}/scripts/step5_train.py \
    --plan-json <base>/step4_plan/model_plan_lgb.json \
    --output-dir <base>/step5_training/ \
    --output-prefix lgb_

训练进度监控（会话驱动 + tail 文件 + 心跳模式）：

脚本使用 FileOnlyLogger 将训练期间所有 stdout/stderr 重定向到 <prefix>train.log，终端仅在训练开始前打印简要信息。脚本同时维护三个监控文件：
- <prefix>training_progress_tail.txt：纯文本进度摘要（每次 trial/stage 更新时覆盖写，~200 字节），Agent 用 Read 一次读取即可获取当前阶段、进度、最佳指标
- <prefix>step5_complete.json：完成标记文件（训练结束 — 成功或异常 — 时写入），包含 status/timestamp/results_path/train_auc/valid_auc/error，Agent 用 Read 检测是否训练完成
- <prefix>train_heartbeat.json：心跳文件（每 10 秒更新一次），包含 pid/timestamp，Agent 对比当前时间判断进程是否存活

> ⚠️ 为何不使用 CheckCommandStatus / Glob？
> - CheckCommandStatus 对非阻塞命令误报 Exited，且 command_id 15-20 分钟后过期失效
> - Glob 有缓存问题，可能误报文件不存在
> - 心跳文件 + CronCreate 定时检查提供主动监控，不依赖用户被动触发
> - step5_complete.json + train_heartbeat.json 覆盖「正常结束」和「异常崩溃」两种场景
> - 会话驱动模式（用户消息或 cron 触发 → Agent 读文件 → 汇报 → 结束回复）稳定可靠

Step A — 启动训练后，向用户展示提示：

脚本启动时会在终端打印：

============================================================
MODEL TRAINING IN PROGRESS
  Model: xgb | Mode: optimal
  PID:           12345
  Progress tail: <base>/step5_training/xgb_training_progress_tail.txt
  Completion:    <base>/step5_training/xgb_step5_complete.json  (appears when done)
  Full log:      <base>/step5_training/xgb_train.log
============================================================

Agent 向用户展示（按用户语言）：
> 模型正在训练（PID: xxxxx）。2-3 分钟后我会自动检查一次进度，也会持续监控进程存活。
> - 进度摘要：<base>/step5_training/<prefix>training_progress_tail.txt
> - 心跳文件：<base>/step5_training/<prefix>train_heartbeat.json
> - 完成标记：<base>/step5_training/<prefix>step5_complete.json
> - 完整日志：<base>/step5_training/<prefix>train.log

Agent 在展示完上述消息后，必须立即执行以下两步：

A1 — 首次自动检查（~2-5 分钟后）： 使用 CronCreate 创建一个一次性定时任务来触发进度检查。由于 CronCreate 使用标准 cron 表达式（分钟级精度），无法表达精确的"从现在起 N 分钟"偏移量。使用最近的下一个非整点分钟数（如当前是 :21，则用 :24 或 :27）。提示词应告知 Agent 执行 Step B 的检查流程。

CronCreate(
    cron="<最近的非整点分钟> * * * *",
    prompt="训练进度自动检查：先用 Read 检查 <base>/step5_training/<prefix>step5_complete.json 是否存在。如存在且 status=success→汇报结果，并用 CronList+CronDelete 清理所有训练监控 cron；status=failed→读取 error 字段诊断。如 step5_complete.json 不存在但 Read <base>/step5_training/<prefix>train_heartbeat.json 也不存在 → 说明本 cron 是残留任务（路径错误或训练从未启动），使用 CronDelete 自清理并静默退出，不向用户输出任何内容。如 completion 不存在但心跳存在 → Read <prefix>training_progress_tail.txt 查看进度并向用户汇报。",
    recurring=False
)

A2 — 心跳持续监控（每 ~5 分钟）： 使用 CronCreate 创建另一个一次性定时任务，间隔约 5 分钟。每次触发后，Agent 需重新创建一个新的 ~5 分钟后的一次性任务，形成持续的监控链。

CronCreate(
    cron="<A1分钟+5分钟的非整点分钟> * * * *",
    prompt="训练心跳检查：Read <base>/step5_training/<prefix>step5_complete.json。如存在（训练已结束）→ 用 CronDelete 自清理，静默退出。如不存在但 Read <base>/step5_training/<prefix>train_heartbeat.json 也不存在 → 残留 cron（路径错误或训练从未启动），用 CronDelete 自清理，不向用户输出。如 completion 不存在且心跳存在 → 解析 timestamp 对比当前时间：若超过 60 秒未更新，向用户告警「⚠️ 训练进程可能已崩溃（心跳超过 60 秒未更新，PID: <pid>）。请检查任务管理器。」若心跳正常，重新创建本 CronCreate（一次性，~5分钟后），维持监控链。",
    recurring=False
)

⛔ A2 维护规则： 如果训练在 ~5 分钟内完成，Agent 收到 Step B 的 status=success 通知后不再创建新的心跳检查任务。如果 Step B 发现 status=failed，也不创建新任务。只有 step5_complete.json 不存在（训练仍在进行）时，才延续监控链。

Step B — 用户回复或定时任务触发后，检查训练是否完成：

1. Read <base>/step5_training/<prefix>step5_complete.json（用 Read 检测文件是否存在，不用 Glob）
   - 文件存在 → 训练完成（成功或异常结束），解析 status 字段：

   • status=success → 进入下方 "After completion" 流程
   • status=failed → 训练异常崩溃，进入下方的 异常诊断流程
   • 文件不存在（Read 返回错误）→ 训练仍在进行，进入步骤 2

2. Read <base>/step5_training/<prefix>training_progress_tail.txt 查看当前进度：

==================================================
Stage:    fine_tuning
Detail:   Trial 15/30, Best AUC=0.8729
Time:     2026-06-30 07:35:55
Completed Trials: 15
Total Trials: 30
Best Auc: 0.8728559007284051
==================================================

3. Read <base>/step5_training/<prefix>train_heartbeat.json 检查进程存活：
   - 解析 timestamp 字段，与当前时间对比
   - ⚠️ 心跳超时告警： 如果心跳超过 60 秒未更新（含 "stopped": true 字段），说明进程已异常退出但 step5_complete.json 未写入：
   > ⚠️ 训练进程可能已崩溃（心跳超过 60 秒未更新）。PID: <pid>。建议：
   > 1. 在任务管理器中查找 PID <pid> 确认是否仍在运行
   > 2. 如进程已消失，重新运行 Step 5（脚本会自动清理旧 study db）
   > 3. 查看 <prefix>train.log 末尾排查原因：python log_reader.py --tail <prefix>train.log --lines 50
   - 心跳正常 → 进入步骤 4

4. 向用户简要汇报当前阶段（如"精调中：Trial 15/30，Best AUC=0.87"）

5. 告知用户："训练仍在进行，几分钟后回复任意消息查看更新。"

6. 结束当前回复（不运行任何 RunCommand，不使用 CheckCommandStatus 等待）

⛔ 异常诊断流程（status=failed）：

当 step5_complete.json 的 status 为 "failed" 时，Agent 必须：

1. 展示错误信息：
   > ❌ 训练异常退出。错误诊断：
   > > {读取 error 字段的最后 800 字符} >

2. 分析常见错误并提供建议：

3. 建议用户：重跑 Step 5（脚本自动清理旧 study db，支持断点续训）

Step C — 训练完成后查看详细日志（可选）：

训练完成后（step5_complete.json 存在），如需查看详细日志：

# 查看最后 50 行（最新进度）
python {skill_path}/scripts/log_reader.py --tail <base>/step5_training/<prefix>train.log --lines 50

# 分页读取（每页 100 行，适合大日志）
python {skill_path}/scripts/log_reader.py --page <base>/step5_training/<prefix>train.log --page-num 1 --page-size 100

For Optimal mode, the script uses FileOnlyLogger to write all phase progress to <prefix>train.log（终端不显示训练详情）。训练阶段包括：
- Coarse Parameter Tuning → trial progress + best AUC after each trial
- Feature Selection → round-by-round feature reduction
- Coarse Tuning (selected features) → re-tuning on reduced feature set
- Fine Parameter Tuning → refined search with smaller ranges
- Final Model → training on full Train set

每个阶段的进度同时写入 <prefix>training_progress_tail.txt（纯文本，Agent 读取）和 <prefix>training_progress.json（JSON，备选）。如需详细日志，训练完成后使用 log_reader.py --tail 读取。

For Fast mode, the script finishes quickly with minimal output. No special handling needed.

Output: <prefix>training_results.json, <prefix>model.<ext>, <prefix>feature_importance.csv (prefix is always xgb_ or lgb_ — the model type determines the prefix regardless of single or dual model)

After completion, the Agent MUST:

0. ⛔ 清理所有定时监控任务 — 训练已结束，必须使用 CronList 列出所有定时任务，然后逐一 CronDelete 清理。避免残留的 A1/A2 定时任务在后续触发时指向错误路径或干扰后续流程。清理完成后向用户报告已清理的 cron 数量。
1. Run the formatter with --output-file to generate the display output:

Single model:

python {skill_path}/scripts/report_formatter.py --step5-single <base>/step5_training/<prefix>training_results.json --output-file <base>/step5_training/step5_display.md

Both models:

python {skill_path}/scripts/report_formatter.py --step5-dual <base>/step5_training/xgb_training_results.json <base>/step5_training/lgb_training_results.json --output-file <base>/step5_training/step5_display.md

2. Read <base>/step5_training/step5_display.md using the Read tool.
3. Display the file content verbatim — copy the full content from the Read result into your response. Do NOT summarize, excerpt, or rephrase. The formatter automatically labels the validation column as "Valid" (3-way) or "CV-OOF" (2-way). IMPORTANT: Always display the FULL formatter output including Train metrics — never omit or summarize columns.

展示校验清单（完成展示后必须逐项确认）：

Agent MUST 在展示内容之后，列出上述清单并逐项打 ✅。如有遗漏，立即补充后再问"继续下一步？(y/n)"。

Step 6: Model Report & Deployment — 🔴 INTERACTIVE

Test evaluation logic (automatic, no user decision needed):

3-way 的标准做法：Train+Valid 合并训练最终模型，在独立 Test 上评估。2-way 无 Valid 可合并，直接用 Step 5 模型。

If both models were trained in Step 5, ask the user which model(s) to evaluate:
> 使用哪个模型生成最终报告？回复 xgb / lgb / both

Then for each selected model, run step6 with the matching prefix. --output-prefix keeps both models' outputs distinct in the same report directory.

# Single model (output_prefix matches model type, e.g. xgb_ or lgb_)
python {skill_path}/scripts/step6_report.py \
    --results-json <base>/step5_training/<prefix>training_results.json \
    --output-dir <base>/step6_report/ \
    --output-prefix <prefix> \
    --decision train_only

# Both models: XGBoost
python {skill_path}/scripts/step6_report.py \
    --results-json <base>/step5_training/xgb_training_results.json \
    --output-dir <base>/step6_report/ \
    --output-prefix xgb_ \
    --decision train_only

# Both models: LightGBM
python {skill_path}/scripts/step6_report.py \
    --results-json <base>/step5_training/lgb_training_results.json \
    --output-dir <base>/step6_report/ \
    --output-prefix lgb_ \
    --decision train_only

No AskUserQuestion for this step — use inline text prompt for model selection.

After script completes, the Agent MUST:

1. Read <base>/step6_report/<prefix>deployment_info.json to verify successful completion — never skip this verification step
2. Run the formatter with --output-file to generate the display output:

Single model:

python {skill_path}/scripts/report_formatter.py --step6-single <base>/step5_training/<prefix>training_results.json <base>/step6_report/<prefix>deployment_info.json --output-file <base>/step6_report/step6_display.md

Both models:

python {skill_path}/scripts/report_formatter.py --step6-dual <base>/step5_training/xgb_training_results.json <base>/step5_training/lgb_training_results.json <base>/step6_report/xgb_deployment_info.json <base>/step6_report/lgb_deployment_info.json --output-file <base>/step6_report/step6_display.md

3. Read <base>/step6_report/step6_display.md using the Read tool.
4. Display the file content verbatim — copy the full content from the Read result into your response. Do NOT summarize, excerpt, or rephrase. The formatter automatically labels "CV-OOF" for 2-way and "Valid" for 3-way. IMPORTANT: Always display the FULL formatter output including Train/CV-Train metrics — never omit or summarize columns.

展示校验清单（完成展示后必须逐项确认）：

Agent MUST 在展示内容之后，列出上述清单并逐项打 ✅。如有遗漏，立即补充后再问"继续下一步？(y/n)"。

Output: model_report.xlsx, deployment_info.json, ecdf_file.csv, train_predictions.csv, test_predictions.csv

Output Directory Structure

<base>/
├── step2_analysis/
│   ├── analysis.json                # Device + data analysis
│   └── step2_summary.txt            # Top 10 rows
├── step3_processing/
│   ├── processed_data.json          # Processing results
│   ├── processed_data.csv           # Cleaned + one-hot encoded data
│   ├── train_data.csv               # Train split
│   ├── valid_data.csv               # Valid split (3-way only)
│   ├── test_data.csv                # Test split
│   └── statistical_analysis.xlsx    # Per-partition column statistics
├── step4_plan/
│   └── model_plan.json              # Model configuration
├── step5_training/
│   ├── <prefix>train.log                # Full training log (FileOnlyLogger output)
│   ├── <prefix>training_progress.json   # Lightweight progress JSON for 5-min polling
│   ├── <prefix>train_heartbeat.json     # Heartbeat file (10s updates, for liveness check)
│   ├── <prefix>train.pid                # PID lock file (for process liveness check)
│   ├── <prefix>model.<ext>              # Trained model (ext = .xgb or .lgb)
│   ├── <prefix>model_merged.<ext>       # Merged model (3-way only)
│   ├── <prefix>training_results.json    # Training metrics (completion flag)
│   ├── <prefix>feature_importance.csv   # Feature gain scores
│   ├── <prefix>coarse_tuning_results.xlsx
│   ├── <prefix>coarse2_tuning_results.xlsx
│   ├── <prefix>fine_tuning_results.xlsx
│   ├── <prefix>feature_selection_results.csv
│   └── <prefix>best_features.csv
└── step6_report/
    ├── model_report.xlsx            # Final report
    ├── deployment_info.json         # Deployment artifact info
    ├── ecdf_file.csv                # ECDF calibration raw scores
    ├── train_predictions.csv        # Train predictions (raw + calibrated)
    └── test_predictions.csv         # Test predictions (raw + calibrated)

Scripts Reference

• run_pipeline.py — non-interactive orchestrator
• step1_setup.py — --output-dir
• step2_analyze.py — --csv --output-dir
• step3_process.py — --csv --target --output-dir --split ...
• step4_plan.py — --processed-json --output-dir --model --mode [--output-name] [--custom-params]
• step5_train.py — --plan-json --output-dir [--output-prefix]
• step6_report.py — --results-json --output-dir --decision [--output-prefix]
• log_reader.py — --head/--tail/--page/--info <path> [--lines N] [--page-num N] [--page-size N] — cross-platform log reader for head/tail/pagination of large log files

Important Notes

• Test data is NEVER used during training (step 5)
• All training uses native APIs: xgb.train() / lgb.train() with Optuna tuning
• 3 feature selection strategies in optimal mode (n_to_delete = min(delete_per_iter, max_delete), adaptive default 5):
  1. If zero-importance features >= n_to_delete → delete n_to_delete of them
  2. If fewer → delete all zero-importance + supplement from least important by gain
  3. If no zero-importance features → randomly pick min(3, n_to_delete) from the worst 5 by gain
  (force_keep columns are always protected from deletion)
• AUC gap penalty prevents overfitting in Optuna
• ECDF is used for score calibration in deployment (train_only decision)