# /plot-checkpoint-results Cursor Command

## 目标
对一个实验的 checkpoint 评测目录运行汇总脚本，生成可复用的结果表和曲线图。

底层脚本：
- `chengyue_script/dvlm/evaluation/plot_checkpoint_results.py`

默认会生成：
- `checkpoint_results.csv`
- `checkpoint_results.md`
- `checkpoint_results.png`
- `checkpoint_results_tokens_per_step.json`
- `checkpoint_results_tokens_per_step.png`

---

## Part 1: 用法示例

```bash
# 1) 直接给 eval 目录（推荐）
/plot-checkpoint-results output_models/<exp>/eval_vlmeval/MDM=1_SPEC=0

# 2) 给实验根目录（命令内部自动定位到正确层级）
/plot-checkpoint-results output_models/<exp>

# 3) 指定子任务列（只影响主分数图/markdown 展示列）
/plot-checkpoint-results output_models/<exp>/eval_vlmeval/MDM=1_SPEC=0 --benchmarks "MMMU_Pro_V_COT,MathVista_MINI,POPE"

# 4) 自定义输出前缀
/plot-checkpoint-results output_models/<exp>/eval_vlmeval/MDM=1_SPEC=0 --output-prefix checkpoint_results_13tasks

# 5) 由训练脚本推断实验名
/plot-checkpoint-results chengyue_script/dvlm/training/multinode/mdm/long_cot/train_xxx.sh
```

---

## Part 2: 输入解析规则

### 2.1 输入类型识别
- **`.sh` 结尾**：视为训练脚本，读取脚本内容并提取默认实验名（优先 `RUN_ID`，其次 `job_name`）。
- **目录路径**：先判断是否已是 checkpoint 父目录（目录下存在 `checkpoint-*`）。
- **实验名字符串**：按候选路径顺序搜索实际结果目录。

### 2.2 结果目录候选顺序（非常重要）
对实验名 `<exp>`，按顺序检查并使用第一个存在的目录：
1. `output_models/<exp>/eval_vlmeval/MDM=1_SPEC=0`
2. `output_models/<exp>/eval_vlmeval`
3. `third_party/VLMEvalKit/output_models/<exp>/eval_vlmeval/MDM=1_SPEC=0`
4. `third_party/VLMEvalKit/output_models/<exp>/eval_vlmeval`
5. `VLMEvalKit_local/output_models/<exp>/eval_vlmeval/MDM=1_SPEC=0`
6. `VLMEvalKit_local/output_models/<exp>/eval_vlmeval`

### 2.3 常见坑（必须避免）
- 不要盲目把 `--input_dir` 设成实验根目录（如 `output_models/<exp>`）就直接运行。
- 当结果在 `eval_vlmeval/MDM=1_SPEC=0/checkpoint-*` 时，`--input_dir` 必须是 `.../MDM=1_SPEC=0` 这一层。

---

## Part 3: 执行步骤

1. **解析输入**并得到 `resolved_input_dir`。
2. **检查目录**下是否存在 `checkpoint-*` 子目录。
3. 运行：

```bash
python chengyue_script/dvlm/evaluation/plot_checkpoint_results.py \
  --input_dir <resolved_input_dir> \
  [--benchmarks "..."] \
  [--output_prefix <prefix>] \
  [--title "..."]
```

4. 脚本结束后，检查产物文件是否存在。
5. 把关键信息返回给用户：
   - 实际使用的 `resolved_input_dir`
   - 生成文件路径
   - `Best Checkpoint` 及其 `Average Score`

---

## Part 4: 输出格式（回复用户时）

### 4.1 成功场景

```markdown
## Plot Checkpoint Results

- Resolved input dir: `...`
- Command: `python ...`
- Generated files:
  - `.../checkpoint_results.csv`
  - `.../checkpoint_results.md`
  - `.../checkpoint_results.png`
  - `.../checkpoint_results_tokens_per_step.json`
  - `.../checkpoint_results_tokens_per_step.png`
- Best checkpoint: `checkpoint-<step>`
- Average score: `<xx.xx>%`
```

### 4.2 未找到结果

```markdown
No checkpoint results found under `<resolved_input_dir>`.

Checked for `checkpoint-*` directories but none were found.
Please pass one of:
- `output_models/<exp>/eval_vlmeval/MDM=1_SPEC=0`
- `output_models/<exp>/eval_vlmeval`
```

---

## Part 5: 可靠性约束（Anti-Hallucination）

在回复任何“最佳 checkpoint / 分数 / 产物文件”前，必须：
1. 实际执行脚本，不可凭记忆编造。
2. 实际检查输出文件存在。
3. 若脚本打印 `No results found.`，必须原样说明，不推测结果。

---

## Part 6: 快速排错

- `No results found.`：通常是 `--input_dir` 层级错了，检查是否应传到 `MDM=1_SPEC=0`。
- `summary.md` 缺失：脚本会尝试自动调用 `aggregate_vlmeval_results.py` 生成。
- benchmark 显示 `-`：表示该 checkpoint 缺少对应任务结果。

---

## Part 7: 推荐默认行为

若用户只给实验名或实验根目录，默认执行：
1. 优先解析到 `eval_vlmeval/MDM=1_SPEC=0`
2. `output_prefix` 默认为 `checkpoint_results`
3. 不传 `--benchmarks`（使用全部可用 benchmark）

--- End Command ---
