Robot_Arm/docs/本机执行清单.md

# 本机执行清单（给本地 AI 逐条执行）

本文件是 Hark 对本机计算的唯一要求清单。按顺序执行，每一步把「回传」里的文件或输出原样交给用户，不要跳步，不要自行改代码。
所有命令在仓库根目录（G:\Robot_v2\机器人手臂）的 Git Bash 里运行。完成的条目由 Hark 在下一次提交里删掉。

## 已知结论（截至 2026-10-19 05:35 回传）

- 现有模型 `ml/runs/base/last.pt` 闭环 0% 到达：1 段采样碰撞 99.6%；4 段采样 94%；4 段 + 仿真安全层碰撞 0.78%，到达仍 0%。consist / value / first 三种选法结果几乎一样，问题出在候选本身，不在挑哪条。
- 三份代码审查逐行核对了滚动索引、前缀、提交、标签与执行的对齐，没有找到错位；但之前没有任何测试真正走过 `rollout()`。下面第 1 步的 H 段把「仿真错了」「前缀照抄」「子目标切换规则」「多峰」几种解释逐个分开。
- 之前「前 1 s 速度比 2.31×」按 6 轴角度直接相加，被 J5/J6 抖动和 pos 任务冻结的 J6 放大。H 段改为分轴、净位移、TCP 三种口径。

## 第 0 步：同步代码

```bash
git status --short            # 有未提交的改动先 commit（git add -A && git commit -m "本机改动"），不要丢
git pull --rebase gitea main
git log --oneline -1          # 应是 Hark 的「diag: H 段（老师 oracle / 前缀消融 / 子目标规则 / 分轴指标）…」
```

- 训练控制台若开着，先点「停止」，确认没有 python 训练进程在跑。
- 不要启动训练、DAgger、M5。

## 第 1 步：闭环失败定位 H 段（约 35–50 分钟）

```bash
PYTHONUTF8=1 python -m ml.eval.diag_cl --ckpt ml/runs/base/last.pt --n 256 --out ml/runs/diag_cl.json
```

- 专用显存超过 22 GB 就 Ctrl+C，回传终端最后 30 行和已写出的 `ml/runs/diag_cl.json`（每段跑完就写一次，中断也保留已完成的段）。
- 现有 checkpoint 没有 EMA、没有 `act_scale`：脚本按原始权重、动作尺度 1.0 载入（输出里 `weights`=`model`、`act_scale_ckpt`=1.0），与之前各轮同口径。
- 回传：`ml/runs/diag_cl.json`。

### 输出键

| 键 | 内容 |
|---|---|
| `A_*`、`B_act_diff_deg` | 起点特征 Python 与数据集逐组差；两份特征下的动作差（与之前相同） |
| `C` | 旧部署口径（1 段采样、子目标旧规则 timeout）的失败形态。到达与碰撞改为只计每题自己的时限内，数字可能比上一轮略低 |
| `H1_oracle` | 老师当策略走完整 `rollout()`。`oracle` 字段：`max_dev_deg_before_dls`（DLS 接管前与老师轨迹的最大关节偏差，p50 / p99 / max）、`reach`、`collision`、`finish_minus_teacher_s`（完成时刻 − 老师时长）、`dls_used` |
| `H1_oracle_noise_0.05` / `_0.1` / `_0.2` | 老师动作每次规划加 N(0, σ²)（σ 以 STEP 为单位） |
| `H2_open_loop` | r = 3 的 val 行：`s{1,4}_prefix_orig`（前缀原样，执行窗口 3..5 的误差，另含 `prefix_copy_err_deg_mean`）vs `s{1,4}_prefix_zeroed`（前缀置零） |
| `H2_replan_empty_s1` / `_s4` | 队列空了才规划（每次 r = 0），其余同新部署默认 |
| `H3_headsub_cross_s{1,4}` | 子目标头 + 越过顶点规则（新部署默认） |
| `H3_headsub_timeout_s{1,4}` | 子目标头 + 旧规则（< 5° 或 1.5 s 超时，旧部署） |
| `H3_teachersub_cross_s{1,4}` / `H3_teachersub_timeout_s{1,4}` | 老师真实途经点全表，两种切换规则 |
| `H3_nosub_s{1,4}` | 不用子目标 |
| `H4_open_loop` | 按前缀长度 r = 0..3 分组的执行窗口误差 \|Σ(act − Y)·STEP\|（度），1 段与 4 段采样 |

每个闭环变体（H1–H3）都带同一组指标：`reach`、`collision`（cat ≠ D、时限内）、`goal_ratio_2s_p50`、`end_goal_err_mm_p50`、`first_hit_s_p50`、`t_done_over_teacher_p50`、`brakes_p50`、`joint_amp_ratio`（6 轴前 1 s 关节行程 策略/老师）、`joint_net_ratio`（6 轴前 1 s 净位移 策略/老师）、`j6_pos_amp_deg_p50`、`tcp_path_ratio_p50`、`tcp_net_ratio_p50`、`sign_flip_rate` 与 `sign_flip_rate_teacher`（6 轴前 2 s 相邻 3 步块变号比例）、`by_cat_mode`（各类别 n / reach / collision / goal_ratio_2s_p50）、`D`（D 类单列）。`_s1` = 1 段采样（部署），`_s4` = 4 段采样。

### 判读

| 现象 | 结论 |
|---|---|
| `H1_oracle` 的 reach < 0.95、collision > 0.01、或 `max_dev_deg_before_dls.p99` > 0.1° | 仿真 / 滚动本身有错，之前所有闭环 0% 都不可信。先修仿真，不看下面各项 |
| `H1_oracle` 全部正常 | 仿真没问题，失败在策略输出。再对照 `H1_oracle_noise_*`：σ = 0.05 时 reach 就大幅下降，说明闭环对残差噪声极其敏感，单靠降噪不够 |
| `H2_open_loop` 的 `prefix_zeroed` 执行窗口误差明显小于 `prefix_orig`，或 `H2_replan_empty` 明显好于同段数的 `H3_headsub_cross`（reach > 0，或 `goal_ratio_2s_p50` 明显更低、`sign_flip_rate` 明显更低） | 前缀照抄（copycat）是主因 |
| `H3_teachersub_cross` 明显好于 `H3_teachersub_timeout`（或 `H3_headsub_cross` 好于 `H3_headsub_timeout`） | 子目标切换规则是主因之一 |
| `H3_teachersub_*` 明显好于 `H3_headsub_*` | 子目标头给的途经点不可用 |
| `H3_nosub` 不比 `H3_headsub_cross` 差 | 子目标通道可以整体去掉 |
| `by_cat_mode` 里 `A/pos`（老师就是一条直线）reach 也是 0 | 失败与多峰无关 |
| `joint_amp_ratio` 远大于 `joint_net_ratio`，且 `sign_flip_rate` 远高于 `sign_flip_rate_teacher` | 「动得多、走得少」是来回抖，不是速度律学快了 |

重新打包和重训（`FRESH_FROM=prep`）要等 Hark 看完这一步的结果再定，这一步之后不要自行启动。

## 回传汇总

| 步骤 | 回传内容 |
|---|---|
| 1 | ml/runs/diag_cl.json |
| 任一步出错 | 终端最后 30 行输出 |