feat: 添加了自动超参数整定

docs/architecture.md

@@ -3,33 +3,102 @@
 ## 分层
 
 ```
-              ┌─────────────────────────────────────────────┐
-              │ chassisd（守护进程）                          │
-              │  配置 / CLI / 1kHz 控制循环 / 安全逻辑 / 日志   │
-              └──────┬───────────────────────────┬──────────┘
-                     │ mecanum（麦轮正逆解）        │
-                     ▼                           ▼
-              ┌────────────┐             ┌──────────────────┐
-              │ motor-core │◄─实现 trait──│ dji-esc          │
-              │ Motor trait│             │ C620/C610 协议     │
-              │ MotorState │             │ EscBus 异步驱动    │
-              │ Pid        │             │ TurnTracker 多圈  │
-              └────────────┘             └────────┬─────────┘
-                                                  │ CanLink（tokio mpsc 通道对）
-                                                  ▼
-                                    ┌──────────────────────────┐
-                                    │ dji-esc-socketcan(Linux) │
-                                    │ socketcan ↔ CanLink 桥接  │
-                                    └──────────────────────────┘
+   ┌────────────────┐   ┌──────────────────────┐   ┌─────────────────────────┐
+   │ chassisd       │   │ chassis-tune         │   │ chassis-bench           │
+   │ 守护进程        │   │ 自动整定（搜索/报告）  │   │ 台架（激励/包络/采样）    │
+   │ 1kHz 循环 / 安全│   │  sim ↓      bench ↓  │   │ chassis-spin 等         │
+   └───┬────────┬───┘   └────┬──────────┬──────┘   └────┬───────────────────┘
+       │        │            │          │               │
+       │        │            │          └───────┬───────┘
+       ▼        ▼            ▼                  ▼
+ ┌───────────┐ ┌──────────────────┐  ┌───────────────────────┐
+ │ mecanum   │ │ dji-esc-sim      │  │ dji-esc-slcan         │
+ │ 麦轮运动学 │ │ 被控对象 / 场景   │  │ dji-esc-socketcan     │
+ └───────────┘ │ 离线 harness     │  │ 真实总线 ↔ CanLink     │
+               │ 异步假电调        │  └──────────┬────────────┘
+               └────────┬─────────┘             │
+                        │  CanLink（tokio mpsc 通道对）
+                        ▼                       ▼
+               ┌────────────────────┐  ┌──────────────────┐
+               │ motor-core         │◄─│ dji-esc          │
+               │ 能力 trait / Pid   │  │ C620/C610 协议    │
+               │ VelocityGains      │  │ EscBus 异步驱动   │
+               └────────────────────┘  └──────────────────┘
+
+               ┌────────────────────┐
+               │ chassis-config     │  chassis.toml schema（chassisd + chassis-tune 共用）
+               └────────────────────┘
 ```
 
 核心解耦点：`CanLink` 是一对 tokio 通道（发送 / 接收 `CanFrame`）。`dji-esc` 的协议状态机
 只面向通道工作，因此：
 
-- 测试中用内存通道 + 一阶电机模型（`dji_esc::sim`）构成闭环仿真，全平台可跑；
-- `dji-esc-socketcan` 把真实 SocketCAN 接口桥接到通道，只在实车上出现；
+- 闭环仿真由 `dji-esc-sim` 提供两条路径：**异步假电调**（挂在同一对通道上，`chassisd --mock`
+  与集成测试用）与**同步 harness**（纯浮点积分、无任务无通道，自动整定用，可并行上千次）；
+- `dji-esc-socketcan`（板载原生 SocketCAN）与 `dji-esc-slcan`（CANable 等 USB 适配器，
+  串口 Lawicel 协议）只把真实总线桥接到通道，**不含任何应用逻辑**；应用住在 `chassis-bench`
+  （台架）与 `chassis-tune`（整定）；
 - 未来更换总线介质（串口转 CAN、MCU 转发）只需新增一个桥接 crate。
 
+## 被控对象模型（dji-esc-sim）
+
+逐拍离散（`dt` 秒），电调坐标系（正电流 → 正转速）：
+
+1. **命令延迟**：`current_raw` 进 FIFO，`delay_ticks` 拍后才作用（链路 + 采样延迟）；
+2. **摩擦**：运动时 `net = u − sign(rpm)·coulomb − viscous·rpm`；静止且 `|u| > static` 时
+   `net = u − sign(u)·coulomb`；静止且 `|u| ≤ static` 时 `net = 0`（粘住）；
+3. **一阶转速**：`rpm_target = clamp(net × gain, ±max_rpm) − load_rpm`，
+   以时间常数 `tau` 一阶趋近；
+4. **量化**：机械角按转速积分并对 8192 取模，反馈帧是 `EscFeedback`，
+   因此角度被截断为 `u16`、转速为 `i16`——量化由协议类型自带。
+
+`PlantParams::gm3508()` 是**无摩擦无延迟**的理想模型（`chassisd --mock` 与历史闭环测试依赖它，
+行为逐位不变）；`PlantParams::gm3508_bench()` 叠加静 / 库仑摩擦（400~600 raw 量级，
+取自台架实测）与 2 拍延迟，是整定的默认被控对象。
+
+单点模型整定出来的增益往往对增益 / 时间常数 / 延迟高度敏感，因此 `chassis-tune` 默认在
+`PlantEnsemble`（域随机化：增益 ±20%、时间常数 ±30%、延迟 0~3 拍、摩擦 ±50%）上做鲁棒优化，
+而不是针对一条理想曲线做最优化。
+
+## 自动整定（chassis-tune）
+
+两阶段搜索：
+
+1. **粗扫**：Latin Hypercube 分层采样 + `rayon` 并行评估，用有限次数铺满四维空间；
+2. **精修**：以成本最低的 top-k 为起点，在**坐标空间**（对数刻度，增益恒正）做多起点
+   `argmin` 局部搜索（Nelder-Mead 默认，可选 PSO）。
+
+成本 = 归一化加权（调节时间 / 超调 / IAE / 电流）；**硬约束不进权重**：过速、饱和占比过高、
+不收敛直接给罚值并记录判定——否则搜索会主动挑一个会飞车的解。
+
+可复现性：每个候选的随机性只来自 `(种子, 候选下标)` 派生的独立 RNG，粗扫结果排序后再取 top-k，
+因此同 seed 两次运行**逐位一致**（CI 的 `just tune-smoke` 依赖这一点）。
+
+超参数（参数空间 / 场景 / 权重 / 验收阈值 / 搜索预算 / 被控对象 / 真机安全包络）不在命令行
+默认值里散着，而是版本化在 `config/tune.toml` 的具名预设中（见
+[`preset.rs`](../crates/chassis-tune/src/preset.rs)）。优先级为
+**内置默认 < 预设文件 < 显式 CLI**，逐字段覆盖；`current_limit` / `direction` / `gear_ratio`
+不是预设字段，写进预设文件会直接报错（安全参数不允许被预设绕过）。
+
+真机后端（`--backend bench`）与仿真后端实现同一个 `Evaluator` trait，区别只是"评估一组增益"
+从浮点积分换成真机试验：打开链路 → 上电门控（反馈新鲜）→ 逐次热更新增益
+（`EscMotor::set_velocity_gains`，不重启总线）→ 逐拍重发设定值 + 安全包络 → 任何退出路径
+先 0 电流 → 试验间静默。搜索强制单线程，因为只有一条总线。
+
+## 命令租约与链路深度（实车踩过的坑）
+
+1. **命令是租约**：`EscBus` 在 `command_timeout`（默认 50ms）内没收到新命令就强制 0 输出
+   （防上层任务死亡后旧指令持续输出）。所以 `set_velocity` 不是"设一次就完事"，上层必须
+   逐拍重发；只在开头下发一次的台架脚本会在 50ms 后自动失电。
+2. **命令队列必须浅**：驱动按 1kHz 生产命令，而 slcan 一次 write 在 CDC ACM 上约 2ms，
+   下行只有几百帧/秒。若 `CanLink` 命令方向缓冲很深（早期是 512），队列会被过时命令灌满，
+   ESC 执行的是**一秒多以前**算出的电流——速度环等于开了 1.4s 延迟，轮子必然跑飞。
+   现在 slcan 桥的 `CHANNEL_BOUND = 8`：`send().await` 立即回压，每一帧都按最新反馈现算。
+   反馈方向是采样流，来不及就丢（`try_send`），绝不阻塞泵线程。
+3. **桥的两个方向不能互相饿死**：发送要有上界（`TX_BURST`）并在一帧写不动时立刻让位，
+   接收要批量排空（`RX_BURST`）。`serial` crate 的 `TTYPort` 读写共用同一个超时，
+   写超时属正常现象，不能当致命错误（否则一次写超时就会把接收方向一起带停）。
+
 ## DJI 电调 CAN 协议要点（C620 手册）
 
 | 项目 | 值 |
@@ -65,13 +134,29 @@ C620 内部**只闭电流环**：转速 / 位置环由主控侧 PID 实现（`mo
 
 | 层级 | 内容 | 平台 |
 | --- | --- | --- |
-| 单元测试 | 帧编解码字节级样例 / 饱和、多圈回绕、PID（阶跃、抗饱和、滤波）、运动学解析解 + 属性测试 | 全平台 |
-| 闭环仿真 | 内存通道 + 一阶电机模型：4 电机速度环收敛、群帧组装、离线安全、守护进程全链路 | 全平台 |
+| 单元测试 | 帧编解码字节级样例 / 饱和、多圈回绕、PID（阶跃、抗饱和、滤波）、运动学解析解 + 属性测试、slcan 帧形状过滤 | 全平台 |
+| 闭环仿真 | 内存通道 + 一阶电机模型：4 电机速度环收敛、群帧组装、离线安全、**命令租约到期与续租**、**增益热更新**、守护进程全链路 | 全平台 |
+| 模型一致性 | 同步 harness 与 `EscBus` 异步闭环在同一组增益下的稳态 / effort 对齐（防止"对着错模型调参"） | 全平台 |
+| 整定 | 指标（合成轨迹解析解）、参数空间（界内 / 确定性 / 对数分布 / 分层覆盖）、成本（硬约束罚值）、搜索（同 seed 逐位复现、优于手调基线）、报告（CSV/TOML/JSON 往返） | 全平台（CI 跑 `just tune-smoke`） |
+| 超参数预设 | schema 往返、逐字段覆盖与优先级、未知键 / 越界 / 缺失报错、`config/tune.toml` 全部预设可解算、命名与后端一致、安全参数不可注入 | 全平台 |
 | vcan 集成 | vcan0 双 socket 收发，真实内核 CAN 栈 | Linux（`#[ignore]`，CI 显式跑） |
+| 实车台架 | `chassis-spin`（`chassis-bench`）四轮定速旋转：链路/反馈、方向、转速稳态、过速保护、安全停机；`chassis-tune --backend bench` 逐次试验 + 重复性复验 | armv7 目标板 + slcan/SocketCAN（人工） |
 | 交叉检查 | `aarch64-unknown-linux-gnu` 全 workspace check | CI |
 
 ## 部署
 
 `chassisd` 为单二进制守护进程：`--interface can0 --config /etc/chassisd/chassis.toml`。
-systemd 样例见 `deploy/chassisd.service`。板端接口就绪依赖：
-USB 转 CAN（gs_usb / candleLight）或 SPI CAN HAT（MCP2515）驱动加载后的 `can0`。
+systemd 样例见 `deploy/chassisd.service`。板端 CAN 两条路径：
+
+- **SocketCAN**：USB 转 CAN（gs_usb / candleLight）或 SPI CAN HAT（MCP2515）驱动加载后的 `can0`；
+- **slcan**：USB 适配器（CANable2 等）在 CDC ACM 下枚举为 `/dev/ttyACM0`，由
+  [`dji-esc-slcan`](../crates/dji-esc-slcan) 在用户态处理（不需 `ip link`，也绕开了
+  gs_usb 驱动）。台架工具 `chassis-spin`（[`chassis-bench`](../crates/chassis-bench)）与
+  自动整定的真机后端走这条路径。整定工具本身是宿主机 / 板端通用的纯 Rust 程序，
+  `current_limit` 等安全参数由 CLI 显式给出，不参与搜索。
+
+## 相关文档
+
+- [底盘开发文档](chassis.md)——接线 / 标定 / 上车流程 / 自动整定与超参数预设 / 故障排查
+- [整体架构规划](../ARCHITECTURE.md)——全系统分层与阶段计划
+