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

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

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

## 已知结论（2026-10-19 02:35 回传）

- 特征口径 Python 与 JS 一致（最大差 3.6e-6），同噪声动作差 ~1e-5°：排除「闭环输入没见过」。
- 闭环关安全层 0% 到达 / 99.6% 碰撞，首撞中位 1.46 s，主碰撞组对 2-4；全程最小目标误差中位 254 mm：策略根本没朝目标走。开安全层碰撞 5.5%，到达仍 0.4%。
- 开环正常：ol_fk_mm 5.98、ol_best_mm 2.92、ol_div 0.655。老师回放 pass。
- 下一个嫌疑：子目标。训练时特征里的子目标是老师真实途经点，闭环里换成子目标头自己的预测。第 2 步的 D 段专门验证它。
- gaps 显存：上一版只给精算段分块，粗筛段 4096 点仍 9.3 GiB。本版粗筛也按点分块（每块 ≤ 446 点）。

## 第 0 步：同步代码（不要 reset --hard）

本地有未提交的 `ml/monitor.html`、`ml/pstate.py` 改动和一个未推送的合并提交，`reset --hard` 会把它们丢掉。

```bash
git add ml/monitor.html ml/pstate.py && git commit -m "monitor: 开环指标两张图；pstate: train 归档加 review_*"
git pull --rebase gitea main
git log --oneline -3          # 最上面应是你的 monitor 提交，其下是 Hark 的「fix(kin/diag): …」
git push gitea main
```

- 训练控制台若开着先点「停止」，确认没有 python 训练进程在跑。
- 不要启动 DAgger / M5，等 Hark 看完第 1、2 步结果再定。

## 第 1 步：gaps 显存峰值（不到 1 分钟）

```bash
PYTHONUTF8=1 python - <<'EOF'
import torch
from ml.common.kin_torch import Kin
kin = Kin(device='cuda')
for n, cap in [(512, 40.0), (4096, 4.0), (4096, 40.0)]:
    q = kin.lo + (kin.hi - kin.lo) * torch.rand(n, 6, device='cuda')
    torch.cuda.empty_cache(); torch.cuda.reset_peak_memory_stats()
    with torch.no_grad(): kin.gaps(q, cap)
    print(f'n={n:5d} cap={cap:4.0f}  peak {torch.cuda.max_memory_allocated() / 2**30:6.2f} GiB', flush=True)
EOF
```

- 通过：三行峰值都 ≤ 2 GiB。
- 专用显存接近 22 GB 或共享显存开始上涨：立刻 Ctrl+C，回传已打印的行，不要继续第 2 步。
- 回传：终端 3 行。

## 第 2 步：闭环失败定位（含新加的 D 段，约 5–8 分钟）

```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 并回传终端输出。
- 新增输出：`C.goal_err_ratio_p50`（0.5/1/2 s 时目标误差 ÷ 起点误差，<1 表示在靠近）；`D0_subhead`（冷启动子目标头精度）；`D1_no_sub`（不用子目标）；`D2_oracle_sub`（用老师真实途经点）。
- 回传：`ml/runs/diag_cl.json`。

## 回传汇总

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

---

## 执行回传（2026-10-19 03:55，本地 AI）

### 第 0 步：同步代码

monitor/pstate 按清单提交 `1f2f2a2`（"monitor: 开环指标两张图；pstate: train 归档加 review_*"），pull --rebase 后已推送。log 与预期一致：`1f2f2a2`（monitor）→ `0653cf0`（Hark fix(kin/diag)）。无训练进程在跑。

### 第 1 步：gaps 显存峰值（实测）

```
n=  512 cap=  40  peak   1.05 GiB
n= 4096 cap=   4  peak   1.40 GiB
n= 4096 cap=  40  peak   4.46 GiB
```

前两条过线；4096×40 仍 **4.46 GiB**（>2 GiB 判据）。

分层定位（独立测量）：
- **粗筛分块工作正常**：单粗块（446 点，粗筛+块内全部精算）峰值 1.05 GiB。
- **峰值全在顶层 `_cat_gaps` 拼接**：完整 gaps 4.54 GiB == 只做 `_cat_gaps`（parts 备好后单独调）4.54 GiB。
- 机制：4096 点 cap=40 共 **8.63e7 细对**；顶层拼接时 10 个粗块的 parts（b/i/j int64 各 0.64 GiB、gap fp32 0.32 GiB，合计 2.25 GiB）与拼接输出（同样长大）同时存活，加上 `p['b']+s` 的临时副本，瞬时到 4.5 GiB 量级。
- 三个可行的修法方向（未改代码）：① 逐键消费——`torch.cat([p.pop('b')+s …])` 一类，每拼完一个键释放该键 parts，峰值降到 ~2.5 GiB；② b/i/j int32 化（细对数 8.6e7 < 2^31，索引完全够），内存直接减半到 ~2.3 GiB；③ 顶层不拼大数组，消费方（dagger/collect、dag 收集）按块消费。
- 版本对比：上一版（`573082d`）同配置 9.30 GiB → 本版 4.54 GiB；旧版（`0b47905`）36.9 GiB。

### 第 2 步：闭环失败定位（含 D 段；完整 JSON 已更新到 ml/runs/diag_cl.json）

A/B/C 与上轮一致（A/B 全过；C：0% 到达 / 99.6% 碰撞，主碰撞对 J3-J5）。新增输出：

- **C.goal_err_ratio_p50**：0.5 s **0.967**、1.0 s **0.892**、2.0 s **0.815** —— 误差比值 <1，方向没错、在缓慢靠近，但 2 秒只缩 **18.5%**，从未接近。
- **D0_subhead**：需子目标的题占 28.1%；need 二分类准确率 71.9%；冷启动预测的途经点 1 每关节最大误差 p50 **66.8°** / p90 **137.1°** —— 子目标头确实基本预测不对。
- **D1_no_sub**（完全不用子目标）：到达 **0%** / 碰撞 **99.6%** / 末端误差 p50 430 mm。
- **D2_oracle_sub**（用老师真实途经点）：到达 **0%** / 碰撞 **99.6%** / 末端误差 p50 435 mm。

**D 段结论：子目标不是元凶。** D2（最有利输入）与 D1、C 基线三者到达率/碰撞率完全相同（0% / 99.6%），末端误差也一致（430/435 mm）——拿掉子目标或换成老师真值都毫无区别。子目标头虽然预测很差（p50 66.8°），但不是闭环失败的原因；策略在闭环状态里本身就完全走不动（2 s 只靠近 18.5% 且 99.6% 撞）。

### 第 1、2 步都没出错，无终端报错段。