From ab7fcf480d203bf63b6c44f5f3b86de785f9ea35 Mon Sep 17 00:00:00 2001
From: cyy_mac <cyy@mac.com>
Date: Fri, 31 Jul 2026 16:46:58 +0800
Subject: [PATCH] docs: expand deployment logging guidance

---
 四足机器狗训练到实机部署全流程指南.md | 60 ++++++++++++++++++++++-----
 1 file changed, 50 insertions(+), 10 deletions(-)

diff --git a/四足机器狗训练到实机部署全流程指南.md b/四足机器狗训练到实机部署全流程指南.md
index 877870d..8a4abb3 100644
--- a/四足机器狗训练到实机部署全流程指南.md
+++ b/四足机器狗训练到实机部署全流程指南.md
@@ -857,6 +857,8 @@ pgrep -fl 'keep_sport_alive|Legged_sport|appTransit'
 
 运行 ONNX/BPU 推理并记录 action，仍不发送电机命令。检查 action 无 NaN/Inf、无持续饱和、静止状态不发散，ONNX 和 BPU 的动作差在离线验收范围内。
 
+从这一级开始，命令必须显式保留 `--log-dir logs`；只要要判断板端实时性，就同时加 `--log-timing`。日志目录会在启动时自动创建，终端退出时会打印 `Log saved:` 路径。
+
 X5 示例：
 
 ```bash
@@ -866,7 +868,8 @@ python3 deploy_45dim_rl_gym/bpu_deploy_x5/deploy_go1_robotlab_bpu_x5_fastcpp.py
   --infer-check \
   --log-dir logs \
   --print-every 50 \
-  --max-steps 500
+  --max-steps 500 \
+  --log-timing
 ```
 
 S100 示例：
@@ -878,7 +881,8 @@ python3 deploy_45dim_rl_gym/bpu_deploy_s100/deploy_go1_robotlab_bpu_s100_fastcpp
   --infer-check \
   --log-dir logs \
   --print-every 50 \
-  --max-steps 500
+  --max-steps 500 \
+  --log-timing
 ```
 
 ### 14.5 第 4 级：悬空状态机，不启用 RL
@@ -914,6 +918,8 @@ IDLE -> CALIBRATE -> HOLD -> OBS_TEST -> INFER_TEST
 
 先用已经通过地面测试的 ONNX 版本确定基线，再在相同软件保护、相同指令、相同场地上测试 BPU。两次测试只替换推理后端。若 BPU 行为异常，回到离线输入逐帧对比，不能通过放宽关节或姿态保护继续测试。
 
+对照日志至少要能证明三件事：同一段动作里 `commands` 接近一致，`action_raw/action_safe/joint_targets` 的差异在离线验收范围内，`policy_ms/loop_dt_ms/state_age_ms` 没有让 BPU 版本比 ONNX 版本产生额外控制延迟。若 BPU 端 `policy_ms` 很低但 `loop_dt_ms` 仍不稳，应继续查 SDK 收包、构包和系统调度，而不是只看 BPU 占用率。
+
 ### 14.10 第 9 级：坡面、台阶和扰动
 
 复杂地形是最后阶段。先从低难度、低速度和正向通过开始，再逐步测试侧向、反向、急停和摩擦变化。每次增加难度前必须确认前一级多次可复现。
@@ -927,20 +933,54 @@ metadata.json
 steps.jsonl
 ```
 
-元数据应包含 Git commit、模型哈希、推理后端、控制周期、PD 参数、动作限制、保护阈值、设备型号、测试人员和场景。逐步日志至少包含：
+部署脚本默认在 `--log-dir` 下创建带时间戳的目录，例如：
 
 ```text
-timestamp / state / state_reason
-commands_raw / commands
-obs_single / obs_history
+logs/robotlab_go1_deploy_YYYYMMDD_HHMMSS/
+```
+
+不要关闭日志来“省性能”。实机调试阶段宁可降低打印频率，也要保留 JSONL 日志；后续量化校准、ONNX/BPU 对齐、力矩保护分析和动作异常定位都依赖这些记录。
+
+`metadata.json` 用来复现实验条件。当前部署脚本会自动写入：
+
+```text
+created_at
+num_obs / history_len / onnx_input_dim
+action_scale / default_dof_pos
+joint_names_sdk / joint_names_policy / joint_order_policy
+lowcmd_backend 或 BPU backend
+history_expected_span_ms
+命令行传入的所有标量参数
+```
+
+发布或多人复现实验时，还应额外记录 Git commit、模型哈希、板端系统版本、BPU runtime 版本、设备型号、测试人员和场景。只给一条 `Log saved:` 路径而没有对应模型与参数，后续无法判断问题来自策略、量化、SDK 还是现场操作。
+
+`steps.jsonl` 是逐周期日志。当前脚本每条记录至少包含：
+
+```text
+step / time_wall / mode / state_reason
+commands_raw / commands / rc_lx / rc_ly / rc_rx / rc_ry / rc_buttons
+obs_single / history_fill / history_zero_pad
 action_raw / action_safe
 joint_targets
-dof_pos / dof_vel / tau_est
-base_ang_vel / projected_gravity / imu_rpy
-inference_ms / loop_ms
-battery / temperature / communication_status
+dof_pos / dof_vel / tau_est / motor_mode / motor_temperature / motor_reserve
+imu_rpy_deg / imu_quat / base_ang_vel / projected_gravity
+battery_soc
+loop_dt_ms / recv_ms / policy_ms / work_ms / state_fresh / state_age_ms
 ```
 
+这些字段的用途：
+
+- `mode` 和 `state_reason`：判断处于 `MONITOR`、`OBS_CHECK`、`INFER_CHECK`、`RAMP`、`RL` 还是故障/阻尼路径；保护触发时首先看这里。
+- `commands_raw` 和 `commands`：区分遥控器原始输入、deadzone/比例/交换后的策略输入，避免把遥控映射问题误判成模型问题。
+- `obs_single`、`history_fill`、`history_zero_pad`：检查 45 维观测和历史缓存是否正确预热；刚进 RL 时历史未填满属于高风险段。
+- `action_raw` 和 `action_safe`：区分模型原始输出与 clip、smooth、trip 检查后的实际动作；若二者差异大，说明部署端限制正在影响行为。
+- `joint_targets`、`dof_pos`、`dof_vel`、`tau_est`：分析目标角、实际角、速度和力矩保护之间的因果关系。
+- `motor_mode`、`motor_reserve`、`motor_temperature`：定位电机是否掉出 servo、是否有错误码或过热。
+- `loop_dt_ms`、`recv_ms`、`policy_ms`、`work_ms`、`state_age_ms`：判断慢在推理、收包、构包发送还是系统调度。
+
+分析日志时不要只看最后一帧。应从 `state_reason` 第一次不为 `ok`、`action_safe` 第一次明显被 clip、`motor_mode` 第一次异常、`tau_est` 第一次接近阈值、`loop_dt_ms` 第一次超过 20 ms 的位置向前回看至少 1 到 2 秒。
+
 一次测试通过的最低条件：
 
 - 无 NaN/Inf、状态超时和控制周期持续超期。