super_agent_bot
bbfb47ebd0
板端交互看图/注键/开页一律走 scripts/board_ui_nav.py，禁止另写 一次性注键脚本：#38 调试中因临时脚本盲注 d*9 走错页复犯（#69）， 盲走事故当时已立"不猜步数"铁律但入口没布防。技能写明 --where/ --to/--goto/--selftest-quick 用法、STATUS/GOTO 语义与拒绝码、 恢复配方、台架锁边界与 GOTO 权限边界。 UI_自动化测试流程.md：§7.1 记 #69 复犯案例与像素路径存量误判基线 （记录查询 6 叶在 selftest 闭环里恒红是存量，勿当 #69 回归）； §7.3 补 --where/--goto；§7.4 记 #69 收口（剪贴弹窗依赖已由 STATUS depth 顶掉，KNOWN_UNREACHABLE 销项待台架复核）； 新增 §7.6 STATUS/GOTO 契约、判稳改造与门控说明。
73 lines
4.9 KiB
Markdown
73 lines
4.9 KiB
Markdown
---
|
||
name: board-ui-nav
|
||
description: 板端 UI 交互的唯一正确入口：先问固件"我在哪"（STATUS 身份查询），再决定按键；到页用闭环 --to 或 bench 直开 --goto。附 #69 实证的四类走错页根因与恢复配方。
|
||
whenToUse: 需要上真机/台架进某页面看图（如故障录波、回放、定值）、在板端做 UI 取证、或从错误页面/待机态/未知屏恢复时。**写任何注键/取帧代码之前先读本技能**。
|
||
---
|
||
|
||
# 板端 UI 导航（唯一入口 = scripts/board_ui_nav.py）
|
||
|
||
一句话纪律：**一切"进页面看图"都走 `scripts/board_ui_nav.py`，禁止另写一次性注键脚本。**
|
||
2026-11-02 #38 调试里"总是进错误页面浪费大量时间"的直接原因，就是临时手搓
|
||
`board_walk*.py` 盲按 `d*9`——而闭环导航器 2026-10-25 起就已存在（10-25 盲走事故
|
||
9 个目标只有 3 个落对，`docs/UI设计/UI_自动化测试流程.md` §7.1）。
|
||
|
||
## 为什么不能自己搓（#69 复盘四类根因，全部有实证）
|
||
|
||
1. **协议旧版零身份反馈**：KEY 的 ACK 是空帧，"发了 5 个键"≠"到了第 5 层"。（已修：
|
||
7003 新增 STATUS 命令，固件直读 `s_depth/s_path/s_sel` + 当前内容页 id，见下）
|
||
2. **N−1 屏坑**：KEY ACK 与 LCDMEM 推流共用同一条 TCP，`sleep(0.30)` 就抓帧拿到的是
|
||
上一屏（规则①：排空到帧流静默 ≥900 ms；现在 `key()` 代码已真正执行排空+双帧比对）。
|
||
3. **物理陷阱**：待机态按 `e` 是**重开最近页**不是进菜单；级联列光标记忆上次行不归零；
|
||
根列最后两行的子列弹框被 160×160 屏裁掉（selftest/runlog 因此"读不到选带"）。
|
||
4. **认屏误判**：菜单子列标签与页标题同字（记录查询子列里的 事故记录/操作记录…），
|
||
像素分类器会把级联菜单判成 PAGE——**有 STATUS 时以 STATUS 为准**，trace 留痕不一致。
|
||
|
||
## 命令（python 一律 .venv；真机动作必须已持 bench 锁并加 --i-hold-bench-lock）
|
||
|
||
```powershell
|
||
# 我在哪？（固件身份 + 像素双口径，不一致会留痕打印）
|
||
.venv\Scripts\python.exe scripts\board_ui_nav.py --where --i-hold-bench-lock
|
||
|
||
# 到页：闭环步行（像素态设备/老固件也能用；每键重认屏，绝不猜步数）
|
||
.venv\Scripts\python.exe scripts\board_ui_nav.py --board --to wave_play --grab C:\temp\wx --i-hold-bench-lock
|
||
|
||
# 到页：bench 固件直开页（一次往返直达，不注键；见下"直开页的边界"）
|
||
.venv\Scripts\python.exe scripts\board_ui_nav.py --goto wave_play --grab C:\temp\wx --i-hold-bench-lock
|
||
|
||
# 提交门禁快检（无台架、无模拟器产物也要绿）
|
||
.venv\Scripts\python.exe scripts\board_ui_nav.py --selftest-quick
|
||
```
|
||
|
||
`--list` 列出全部合法页 id 与菜单路径；`--trace 路径` 落步迹 jsonl（排错先看它）。
|
||
退出码：0 成功 / 1 分类或导航失败 / 2 环境错误 / 3 拒动（未持锁确认位等）。
|
||
|
||
## 身份回读与直开页（#69 新增，两端共享 ui_net_sink.h 契约）
|
||
|
||
- **STATUS（命令 4）**：应答 `[ver][kind][depth][n][id_len][path][sel][page id]`；
|
||
kind = MENU/PAGE/STANDBY（待机优先判）。老固件不应答 → 主机打印一次后自动退回纯像素。
|
||
生产固件也支持 STATUS（只读、零画面副作用）。
|
||
- **GOTO（命令 5）**：**编译期双闸** `DTU_BENCH`（临时 bench 固件）或模拟器宏
|
||
`UI_REMO_ALLOW_GOTO`；生产固件恒拒 `status=4`。拒绝码：1 无此页 id / 2 执行类页 /
|
||
3 开页失败 / 5 待机态（先按键唤醒再来）。直开按查看权限 `UI_PERM_VIEW` 进入，
|
||
**不弹密码**——所以它只用于调试取证，不能当作"过密码"的旁路写路径。
|
||
- 执行类页面 `clear`/`reset`（第二次 ENTER 即真执行）主机与固件**双侧**默认拒绝，
|
||
`--allow-exec-pages` 才放行，放行 = 接受后果。
|
||
|
||
## 走错页 / 未知屏恢复配方（按序，不跳步）
|
||
|
||
1. `--where` 先看 STATUS：`PAGE` → 按 `s` 关页（导航器 `--to` 自动做）；
|
||
`STANDBY` → 按 `e` 唤醒（注意规则②：home 上 `e` 可能重开最近页）；
|
||
`MENU depth>0` → `l` 收列，别按 `s`（菜单态 `s` 不收列）。
|
||
2. STATUS 无应答（老固件）才吃退避键序（默认 `esl`，`--backoff-keys sl` 可去 ENTER）；
|
||
ENTER 上限 1 次是硬闸（BACKOFF_MAX_E），报停机就 dump 帧人眼看，不许连按。
|
||
3. 反复落错页且 trace 里出现"像素与 STATUS 不一致" → 分类器或固件有账要记，
|
||
把留痕帧 `--dump-fail` 存下交 Lead，**不要**改判据迁就现状。
|
||
|
||
## 边界
|
||
|
||
- 本脚本不申请锁、不碰串口与烧录；锁的取还见 task-worktree 技能
|
||
（`lock acquire bench --task <ID>`）。
|
||
- 台架证据只进 `ci-artifacts/`（`--walk` 默认 `ci-artifacts/uinav/walk/`，与 BOARD_TRUTH
|
||
读取目录已并一），不进工作树。
|
||
- UI 源码改动的前后回归是 ui-verify 技能（5 门禁），本技能只管"人到板上去看"。
|