feat(actpred): 训练时安全图像增强（ColorJitter），支持任意 frame_len

训练集启用 --augment 后对每帧施加亮度/对比度/饱和度/色调变换，
同一样本内所有帧共享参数（模拟连续帧光照不变），验证集不增强。
仅颜色空间变换，无空间变换，动作标签不受影响。
删除 t1.mt（@TEST 块无对应插件，录制时报错）。

docs/reports/actpred_safe_image_augmentation_20260813.md

@@ -0,0 +1,116 @@
+# actpred 训练时安全图像增强
+
+> 文档类型：特性报告
+> 模块：actpred
+> 日期：2026-08-13
+
+---
+
+## 1. 背景
+
+pybot dry-run 录制的 episode 数据样本量有限（11 个脚本 → 12 个 episode → ~728 样本），训练容易过拟合。直接增大数据集需要更多 `.mt` 脚本或更多轮次录制，成本较高。
+
+图像增强（data augmentation）是低成本扩充样本的标准手段，但机器人动作预测场景有特殊约束：**空间变换（翻转/旋转/裁剪）会改变图像的语义坐标，而动作标签未随之变换，导致训练对错误**。例如水平翻转后，左右舵机角度应互换，但标签不变，形成错误训练信号。
+
+## 2. 方案
+
+### 2.1 增强范围
+
+仅启用**颜色空间变换**（ColorJitter），不涉及任何空间变换：
+
+| 变换 | 参数 | 说明 |
+|------|------|------|
+| 亮度 | `±20%`（factor ∈ [0.8, 1.2]） | 模拟不同光照条件 |
+| 对比度 | `±20%`（factor ∈ [0.8, 1.2]） | 模拟不同摄像头增益 |
+| 饱和度 | `±20%`（factor ∈ [0.8, 1.2]） | 模拟不同色温环境 |
+| 色调 | `±5%`（factor ∈ [-0.05, 0.05]） | 轻微色偏，避免模型过依赖颜色 |
+
+**不使用的变换**（因需同步变换动作标签）：
+
+| 变换 | 原因 |
+|------|------|
+| 水平/垂直翻转 | 左右舵机角度需互换，否则标签错误 |
+| 旋转 | 重力方向变化，姿态语义改变 |
+| 裁剪/平移 | 视野变化导致动作-画面对应关系改变 |
+| 透视变换 | 改变空间关系 |
+
+### 2.2 同一样本内帧间参数一致性
+
+一个训练样本包含 `frame_len` 帧连续图像（默认 3 帧，间隔 10ms）。真实场景中连续帧的光照条件不变，因此**同一样本内所有帧共享同一组增强参数**，而非每帧独立随机：
+
+```python
+if self.augment:
+    bf = random.uniform(0.8, 1.2)   # 亮度因子，所有帧共用
+    cf = random.uniform(0.8, 1.2)   # 对比度因子
+    sf = random.uniform(0.8, 1.2)   # 饱和度因子
+    hf = random.uniform(-0.05, 0.05) # 色调因子
+for p in image_paths:
+    image = Image.open(p).convert("RGB")
+    if self.augment:
+        image = TF.adjust_brightness(image, bf)
+        image = TF.adjust_contrast(image, cf)
+        image = TF.adjust_saturation(image, sf)
+        image = TF.adjust_hue(image, hf)
+    frames.append(self.transform(image))
+```
+
+不同样本（不同 `__getitem__` 调用）使用独立随机参数，保证整个数据集的增强多样性。
+
+### 2.3 自适应 frame_len
+
+增强逻辑在 `for p in image_paths` 循环前生成参数、循环内逐帧施加。`image_paths` 的长度由 `frame_len` 决定（`image_files[t - frame_len + 1 : t + 1]`），循环自动适配。**`frame_len` 为 1、2、3、5、10 等任意值时均无需修改代码**。
+
+### 2.4 训练/验证隔离
+
+| 数据集 | 增强 | 说明 |
+|--------|------|------|
+| 训练集 | `augment=cfg.train.augment` | CLI `--augment` 控制 |
+| 验证集 | `augment=False`（默认） | 验证 loss 反映真实分布表现 |
+
+推理端（`predict.py` / `onnx_infer.py` / `hailo_infer.py`）不涉及增强，使用原始图像。
+
+## 3. CLI 接口
+
+```bash
+# 训练时启用图像增强
+bash _run.sh train --data-dir ./data --epochs 100 --augment
+
+# 显式关闭（默认关闭）
+bash _run.sh train --data-dir ./data --epochs 100 --no-augment
+```
+
+`--augment` 使用 `BooleanOptionalAction`，支持 `--augment` / `--no-augment` 双向开关。
+
+## 4. 验证
+
+### 4.1 功能验证
+
+```
+dataset size: 728 samples
+augment diff (should be >0): 0.3767        # 增强前后图像有差异
+two augment calls diff (should be >0): 0.2626  # 两次增强参数不同（随机性）
+action_history diff (should be 0): 0.0     # 动作标签不受影响
+target diff (should be 0): 0.0
+```
+
+### 4.2 端到端训练
+
+`--augment --epochs 3`（64×64，batch=8）训练正常完成，loss 正常下降。
+
+### 4.3 回归测试
+
+全量单测 90/90 通过，无回归。
+
+## 5. 改动文件
+
+| 文件 | 改动 |
+|------|------|
+| `actpred/dataset.py` | `ActionDataset` 新增 `augment` 参数；`__getitem__` 在 Resize 前施加 ColorJitter（`torchvision.transforms.functional`） |
+| `actpred/config.py` | `TrainConfig` 新增 `augment: bool = False`；`build_argparser` 新增 `--augment`；`apply_overrides` 新增映射 |
+| `actpred/train.py` | 训练集构造传 `augment=cfg.train.augment`，验证集默认不增强 |
+
+## 6. 后续方向
+
+- **空间增强（需同步标签变换）**：水平翻转时自动交换左右舵机角度（s1↔s2, s3↔s4, s5↔s6, s7↔s8），可将训练数据量翻倍。需要了解舵机配对关系后实现。
+- **动作噪声增强**：`pretrain_mt.py` 已支持 `--noise-std`，`train.py` 可同样引入，对 action_history 和 target 施加高斯扰动。
+- **更多 `.mt` 脚本**：从根本上扩大动作多样性，是提升模型泛化能力的最有效手段。