完善释放控制：稳定/迅速行为预设、力曲线夹稳门控与会话记录。

Co-authored-by: Cursor <cursoragent@cursor.com>

docs/GUI_USER_MANUAL.zh-CN.md

@@ -397,8 +397,17 @@ FPS 文本约每秒更新一次。短时间红点可能来自相机启动、重
 | `hold-reference-armed` | 已记录夹持参考值 |
 | `adaptive-grip-ramp` | 正在自适应增加夹持力 |
 | `adaptive-grip-wait` | 等待下一次自适应加力 |
-| `release-arm-delay` | 等待释放检测稳定 |
-| `release-reference-armed` | 已重新记录释放参考值 |
+| `release-grip-settle` | 普通法向接触保护，即时侧触仍可检测 |
+| `release-self-settle` | 普通法向自运动保护，即时切向侧触仍可检测 |
+| `release-ready` | 释放检测已就绪 |
+| `release-sudden` | 突变外力新帧确认 |
+| `release-touch` | 新的曲线起始变化及轻推偏移确认 |
+| `release-side_touch` | 接触后即可识别的即时侧触确认 |
+| `release-slow_internal` | 慢变跟随参考 |
+| `release-slow_external` | 新起始变化后达到弱路径幅度，经较长确认 |
+| `release-transient-rejected` | 脉冲回弹，丢弃候选 |
+| `release-settling-turn` | 平稳曲线拐点或候选偏移回落，继续夹持 |
+| `release-sample-gap` | 采样断流，丢弃旧证据，等待新帧后恢复监视 |
 | `hold-check` | 正在监测保持状态 |
 | `force-change-release-open` | 检测到取物力变化并执行张开 |
 | `open-recover-position` | 正在等待张开位置恢复 |
@@ -562,9 +571,23 @@ FPS 文本约每秒更新一次。短时间红点可能来自相机启动、重
 | `adaptive_force_max` | `80` | 自适应目标力上限 |
 | `adaptive_force_step` | `1` | 自适应每次增加的力比例 |
 | `adaptive_force_interval` | `0.05` | 自适应两次加力间隔 |
-| `release_arm_delay_seconds` | `0.8` | 停止加力后启用释放检测前的等待时间 |
-| `release_normal_change` | `0.2` | 相对释放参考值的法向变化阈值 |
-| `release_shear_change` | `0.2` | 相对释放参考值的切向变化阈值 |
+| `release_arm_delay_seconds` | `0.12` | 实际自运动命令执行完成后的短保护（秒），不是总释放延时 |
+| `release_min_hold_seconds` | `0.28` | 普通法向接触保护（秒），即时侧触不等待 |
+| `release_settle_seconds` | `0.06` | 脉冲/断流后的短恢复保护（秒） |
+| `release_normal_rate` / `release_shear_rate` | `1.6` | 突变速率门槛（N/s） |
+| `release_min_change` | `0.04` | 普通突变/轻触最小净变化（N） |
+| `release_side_touch_change` | `0.06` | 即时侧触的左右力差变化（N） |
+| `release_touch_window_seconds` | `0.2` | 新外力起始证据有效期（秒），非等待时间 |
+| `release_confirm_samples` | `2` | 突变确认新帧数，运行时至少 2 帧 |
+| `release_slow_rate` | `0.4` | 慢变日志分类速率（N/s），曲线跟随与就绪不由它门控 |
+| `release_normal_change` / `release_shear_change` | `0.28` | 中速外力累积的弱路径幅度（N） |
+| `release_slow_confirm_samples` | `5` | 弱路径确认新帧数 |
+| `release_confirm_window_seconds` | `0.2` | 确认有效窗口（秒） |
+| `release_sample_timeout_seconds` | `0.2` | 采样断流保护门槛（秒） |
+
+每次自运动稳定后保留至少约 100ms 观察时间，候选确认优先于补力，因此实际加力
+间隔可能长于配置。`gripping` 期间也可以释放，无需等全部爬力完成。缓存帧不重复
+参与确认。详细曲线策略、保护窗口的取舍及实机验收见 [释放控制说明](RELEASE_CONTROL.zh-CN.md)。
 
 ### 14.8 恢复
 
@@ -747,3 +770,6 @@ Windows 日志连续出现 `CvCapture_MSMF::grabFrame ... can't grab frame`，
 ---
 
 本版本为快速初版，后续版本可补充带编号的主界面截图、设备接线图、参数调试示例和现场验收记录表。
+
+释放检测先识别相对原有曲线的新起始变化；自然减速、变平和拐点不因累计位移够大就开爪。
+实际自动释放前的逐帧数据保存在 `logs/release-last.json`，源码和打包启动均适用。

docs/RELEASE_CONTROL.zh-CN.md

@@ -0,0 +1,171 @@
+# 释放控制与回放验证
+
+## 行为模式（迅速开合 / 夹持稳定）
+
+设置页「行为模式」与主界面「迅速开合 / 夹持稳定」按钮共用 `grip_behavior_mode`：
+
+| 模式 | 目标 | 典型倾向 |
+| --- | --- | --- |
+| `rapid`（迅速开合） | 跟手开合 | `release_min_hold=0`、更低侧触/确认门槛、更快再武装、关闭自适应加力 |
+| `stable`（夹持稳定） | 夹得住、少误开 | 更长接触保护、更高确认帧数与速率门槛、开启自适应；**长历史斜率趋零后再允许侧触/监视** |
+
+预设定义见 `gripper/config/behavior_profiles.py`。切换模式会改写释放/滤波/爬力相关字段；可在设置里再微调后保存。运行中切换会即时写入 live `config` 并重置 `ReleaseWatch`。
+
+## 会话录制（优化张开用）
+
+主界面「录制数据」可开关。开启后每个控制 tick 追加写入
+`logs/sessions/session-YYYYMMDD-HHMMSS.jsonl`：
+
+- 滤波后力 `feedback`、原始左右样本 `raw_left` / `raw_right`
+- 状态机 `state` / `action`、行为模式、力指令
+- 释放判定 `release`（phase/reason/confirm/rates…）
+- 执行器 `motion_pending` / `motion_completed_at`
+
+文件为 JSONL：首行 `session_header`（含当时 release 相关配置），末行 `session_footer`。
+停止控制或再点按钮会结束录制。另有短窗快照 `logs/release-last.json`（仅最近一次释放前后）。
+
+---
+
+## 平稳拐点继续跟随，新外力才释放
+
+`ReleaseWatch` 位于 `gripper/control/release_watch.py`，消费力数据和执行器状态，返回
+释放决定及是否允许补力；`controller.py` 通过 `ActuatorWorker` 发令。外围主循环保留原结构。
+
+当前释放路径共用 `force_curve.py` 的曲线判断。旧的“短窗口净变化够大、两帧仍有偏移”
+会把缓升变平或自然回落当成侧触；现在仅有幅度、速率或左右力差都不足以释放，必须
+先出现相对已有曲线的新起始变化，再检查幅度和持续性。
+
+具体处理：
+
+1. 闭合阶段保留最近几帧，接触时继承各通道的趋势，不把接触帧当作静止起点。
+2. 每个通道保留可配置长度的历史（`release_curve_history`；rapid 约 6 点，stable 约 30 点）。
+   **起始检测**仍只用最近约 6 点做局部二次拟合；**夹稳斜率**用更长窗口（`release_slope_window_seconds`）
+   做一次拟合，得到 `fit_slope`（N/s）。夹住加力过程表现为该斜率逐渐变小并趋近于 0。
+3. 自然减速、变平、相近速度的斜率变号是曲线延续；它们不因累计位移达到门槛而启动释放候选。
+4. 新的偏离方向须与实际变化方向一致，并超过小幅噪声门槛（当前为
+   `min(release_min_change, release_side_touch_change)` 的 20%）。真正的起始变化
+   会被短暂保留，允许轻推在后续几帧达到幅度门槛。拟合残差及近期残差中位数用于估计
+   噪声，预测误差容许范围随外推距离扩大；新偏离还必须超过该范围，不能把噪声外推成外力。
+5. 候选必须同时具有实际测得的位移和相对原曲线的偏移，避免曲线外推把小噪声放大成
+   虚假的大变化。确认时扣除原曲线的继续变化，因此拐点附近新的触碰仍可检测。
+6. 尚未达到幅度的小变化一旦变平，或偏移落回预测误差范围，就丢弃起始证据，不能续接
+   后续自然变化。已达幅度的候选若明显回落则取消，记录 `settling-turn`；回落判定容许
+   当前噪声范围内的波动，避免真实触碰后的轻微抖动被误拒绝。
+   同一套起始判断覆盖 `side_touch`、`touch`、`sudden` 和弱路径，避免其他分支绕过。
+7. **`release_require_slope_settle`（stable 默认开）**：仅看法向通道长窗 `|fit_slope|`
+   （`release_settle_normal_only`）低于 `release_slope_settle_rate`，并连续保持
+   `release_slope_hold_seconds`，**首次**达到后闩锁为已夹稳。之后自适应加力或主动
+   张开使斜率再升高，**不会**撤销释放武装。
+8. **stable 干净分工**：夹稳只看法向；张开只走切向（`release_normal_onset_enabled=false`、
+   `release_side_normal_enabled=false`，切向 onset/侧触开启）。rapid 仍法向+切向都能开。
+
+没有增加固定夹稳等待，也没有恢复“四通道同时安静”的全局条件。以下是幅度与确认路径：
+
+| 路径 | 检测 | 确认 |
+| --- | --- | --- |
+| 即时侧触 `side_touch` | 继承接触前左右力差曲线，检测偏离该曲线的新侧触 | 默认两次左右均更新的传感器帧；不等 0.28s 夹稳计时 |
+| 普通轻触 `touch` | 出现新起始变化后，实际位移和相对原曲线的偏移均达到 0.04N | 默认两帧；不要求瞬时速率达到 1.6N/s |
+| 突变 `sudden` / 弱路径 `slow_external` | 新起始变化叠加大速率 / 大幅偏移 | 默认两帧 / 五帧 |
+
+即时侧触使用左减右的法向/切向力差的变化，抵消两侧共同压紧或负载变化。命令排队、
+执行及短响应尾部内，法向差分仍受保护，切向差分继续检测。普通共同法向卸载仍经过
+接触与自运动保护，不能把它与即时切向侧触混为一谈。
+
+差分投票要求左右都提供新帧，避免相机异步更新制造虚假左右差。观察窗口不是必须
+等待的时间：出现新起始变化并达到幅度后立即确认。确认要求同一通道、同方向的
+新偏移持续存在；平稳拐点、单帧脉冲、回弹、换边不能拼票。
+
+差分不能完美区分真实触碰与持续的单侧机械扰动。实机需特别检查单侧摩擦明显的物体；
+两帧确认和共同受力抵消并不等于所有机械扰动都能被识别。
+
+## 状态与补力
+
+| 状态 | 行为 |
+| --- | --- |
+| `disarmed` | 没有夹持周期，不检测释放 |
+| `grip_settle` | 普通法向接触保护，独立即时侧触路径已运行 |
+| `self_settle` | 普通法向自运动/瞬态恢复保护，即时切向侧触继续运行 |
+| `watching` | 突变、轻触和弱路径均可检测；慢漂移跟随参考 |
+| `confirming` | 候选确认优先，暂停补力 |
+| `released` | 一次性输出释放效果，进入张开恢复 |
+
+保护计时结束且获得左右新帧，即恢复普通监视；不再要求四通道同时安静。脉冲拒绝或
+断流后的小恢复窗同样有界，不会因噪声反复延长。即时侧触确认独立于这些普通保护状态。
+
+`gripping` 和 `hold_check` 每 tick 先检测释放，再考虑补力。恢复普通监视后至少保留
+`max(0.1s, release_confirm_samples/control_hz)` 观察时间再补力。轻推初期也暂缓补力，
+防止新命令覆盖取物信号；低速蠕变不会永久禁止补力。配置的补力间隔仍是最短间隔。
+
+## 参数
+
+| 参数 | 默认及当前 JSON | 语义 |
+| --- | ---: | --- |
+| `release_side_touch_change` | 0.06 N | 即时侧触的左右力差变化门槛 |
+| `release_touch_window_seconds` | 0.2s | 新外力起始证据有效期；不是额外等待 |
+| `release_min_change` | 0.04 N | 普通突变/轻触路径的最小净变化 |
+| `release_confirm_samples` | 2 | 突变/轻触/侧触确认帧数，含首帧；至少两帧 |
+| `release_min_hold_seconds` | 0.28s | 普通法向接触保护；不阻塞即时侧触 |
+| `release_arm_delay_seconds` | 0.12s | 实际命令执行完成后的普通法向保护；即时切向侧触仍运行 |
+| `release_settle_seconds` | 0.06s | 脉冲拒绝/断流后的短恢复保护；不再表示全局安静时间 |
+| `release_normal_rate` / `release_shear_rate` | 1.6 N/s | 突变路径门槛；轻触不必跨过它 |
+| `release_slow_rate` | 0.4 N/s | 慢变日志分类阈值；参考跟随由曲线延续决定，不门控就绪 |
+| `release_normal_change` / `release_shear_change` | 0.28 N | 新外力起始之后的大幅变化弱路径门槛，旧曲线累计变化不能绕过起始判断 |
+| `release_slow_confirm_samples` | 5 | 弱路径确认帧数，不少于突变路径 |
+| `release_confirm_window_seconds` | 0.2s | 候选最长确认时间；超时丢弃 |
+| `release_sample_timeout_seconds` | 0.2s | 任一侧断流或时间戳间隔过大时，丢弃已有证据 |
+| `release_curve_history` | 6 / stable 30 | 力曲线保留点数；onset 仍用最近约 6 点，斜率门控用更长窗 |
+| `release_slope_window_seconds` | 0.8s | 夹稳斜率估计时间窗 |
+| `release_slope_settle_rate` | 0.2 N/s | `|fit_slope|` 低于此值才视为加力趋稳 |
+| `release_slope_min_points` | 8 | 斜率门控生效前最少历史点数 |
+| `release_require_slope_settle` | false / stable true | 是否在侧触与退出 settle 前要求斜率趋零 |
+| `release_slope_hold_seconds` | 0 / stable 0.45s | 斜率达标后还需保持多久（滤掉短刺） |
+| `release_settle_normal_only` | true | 夹稳只看法向，不看切向 |
+| `release_side_shear_enabled` | true | 是否允许切向左右差侧触 |
+| `release_side_normal_enabled` | true / stable false | 是否允许法向左右差侧触 |
+| `release_shear_onset_enabled` | true | 是否允许切向触发普通释放路径 |
+| `release_normal_onset_enabled` | true / stable false | 是否允许法向触发普通释放路径 |
+
+N/N/s 适用于当前标定配置。缓存帧不重复滤波或投票，提高控制频率不能代替真实传感器帧。
+`grip_settle_seconds` 只控制外围状态进入 `hold_check` 的最早时间。
+`trigger_clear_stable_seconds` 是未使用的兼容字段，开爪等待仍采用稳定基线增量。
+
+## 日志
+
+- `release-side_touch`：接触/自运动保护期间检测到侧触，正在确认。
+- `release-touch`：检测到新的轻推起始及持续偏移，不需要很大的瞬时速率。
+- `release-settling-turn` / `curve=settling_turn`：平稳拐点或候选回落，继续夹持。
+- `curve=settling_flatten`：原曲线自然减速、变平。
+- `force-settling` / `curve=force_settling`：长历史斜率尚未趋零，暂不侧触、不进 watching。
+- `channel` / `innovation`：候选通道及起始时偏离曲线预测的量。
+- `release-sudden` / `release-slow_external`：突变或弱路径确认。
+- `release-grip-settle` / `release-self-settle`：普通法向保护；`side_watch=1` 表示即时侧触仍运行。
+- `release-slow_internal`：慢变跟随参考，不累积无限漂移。
+- `release-transient-rejected` / `release-confirm-expired`：脉冲回弹或确认过期，未释放。
+- `release-sample-gap` / `release-waiting-sample`：断流保护或等待新帧。
+
+`release_armed` 表示普通监视或已有侧触候选；不能单凭其为 0 判断侧触关闭。
+新增 `side_watch` 日志和 `release_side_watch` UI 状态单独表示即时侧触。
+状态/原因变化立即记录，重复日志约 0.2s 节流。
+
+## 验证
+
+```powershell
+conda activate py311
+python -m unittest discover -s tests -v
+```
+
+回放先复现了旧版在没有突变的余弦缓升、变平、回落中误开的问题，再验证修正后不释放。
+覆盖 20/30Hz、单侧差分与双侧曲线、接触前已有上升趋势、大速率自然曲线、弱路径绕过、
+有界随机噪声，以及在上升、峰顶、回落阶段叠加一次真实新触碰。额外覆盖 60 组带噪声的
+平滑曲线和 60 组在带噪声曲线上叠加新触碰的回放，防止外推放大噪声或确认误拒绝。
+原有即时侧触和轻推
+响应回归保留，但软件回放不能证明实机已不误开。
+
+每次实际自动释放后，会将释放前最多 120 个控制 tick 的逐帧力值、左右传感器时间戳、
+状态、起始判据及参数保存到 `logs/release-last.json`（源码启动也有效，覆盖上一次记录）。
+写文件在张开命令提交后进行，诊断不能阻塞该次发令。该文件用于复核真实拐点和误开原因，
+无需根据界面里被节流的几行日志猜测。
+
+这些时间只覆盖软件决定，不包含相机处理、串口排队和机械动作。脉冲、回弹、慢漂移、
+断流、手动命令、闭合超时和当前 JSON 参数回放仍参与回归。实机应检查接触后立即侧触、
+持续噪声下轻推、长时间夹持误开，以及不同单侧摩擦条件下自运动是否被误识别为侧触。