ykcheungab 8d374e5850 refactor(studio): 回放引擎改名 ReplayEngine —— 把「引擎」与「窗口级控制器」的名字分开 ...

- What: `apps/studio/src/orisys_studio/replay.py` 的 `ReplayController` 改名为 `ReplayEngine`
  （引用只有 4 处：`app_window.py` 的 import 与构造、`ui_check.py` 的一处 import、模块内定义）；
  模块 docstring 写明它为什么叫 engine（只回答"t 时刻是什么"，不知道传输策略、不知道控件），
  并指路即将落地的窗口级 `ReplayController`；`app_window.replay` 这个属性名**不动**（36 处使用）。
  同步更新两份既有文档里的类名（`apps/studio/docs/shell-lifecycle.md`、`record-channel.md`、
  `docs/architecture/studio-architecture.md` 的框图标签）。
- Why: 用户已同意分拆 `app_window.py`，并选定"引擎改名 ReplayEngine + 新类叫 ReplayController"
  这一方案（另一方案是让两个名字 `ReplayController`/`ReplayCoordinator` 并存，容易进错门）。
  这一步是后续把窗口里那 30 个回放方法搬进 `ReplayController` 的前提：先把名字腾出来，
  否则搬迁时无法区分"引擎"与"控制器"。
- Verification: shared+apps 同一次运行 **588 项 0 失败 15 跳过**；`ui_check` 587 项 0 失败；
  全仓 `grep ReplayController` 只剩两处有意保留的提及（`replay.py` docstring 里指路、
  `app_window.py` 注释里指路），没有悬空引用。
- Not in this change: 不搬运任何方法、不改行为——`app_window.py` 仍是 3043 行；`SessionController`、
  `ReplayController`、`ViewLayoutController`、`DisplayPrefsController` 四个模块的搬迁尚未开始
  （顺序与契约见 docs/architecture/studio-architecture.md 建议 1）。

2026-09-15 08:41:44 +08:00

..

record-channel.md

refactor(studio): 回放引擎改名 ReplayEngine —— 把「引擎」与「窗口级控制器」的名字分开

2026-09-15 08:41:44 +08:00

shell-lifecycle.md

refactor(studio): 回放引擎改名 ReplayEngine —— 把「引擎」与「窗口级控制器」的名字分开

2026-09-15 08:41:44 +08:00

ui-palette.md

删除深度重算引擎；修好回放视频每帧重开文件导致的无法播放，运输控制改到状态轨主按钮 - What: 1) 彻底删除深度重算引擎：shared/.../record/depth.py（DepthRecomputer/DepthResult）与 depth_backends.py（BoxReplay/FingerReplay）、其专属测试 test_depth_replay.py，record/__init__ 不再导出，playback.py::replay_warnings 不再报 depth_recomputed；apps/studio/replay.py 由 515 行瘦身为只做读盘+游标+视频帧+提示，回放视图的 2D 面板只提供「原始图像」；session.json 的 depth.replay 由 recompute 改为 none；删除 31 个只剩深度使用的文案键（depth_*/warn_state_*/warn_reset_*），warn_config_changed 与 warn_sdk_changed 改为描述"由视频重算"；ui_check 深度段、studio 两个深度用例、test_playback 三例、drive_shared 的 test_depth_replay 与 reproduce.py 的深度段一并清理（shared 套件 150→134 项）。2) 无法播放的根因是 RecordingReader.video_frame_at 每帧都 cv2.VideoCapture 重开并 seek：小片段已 ~10 ms/帧，1080p H.264 每次 seek 需从关键帧解码（上百 ms），而播放每 33 ms 要一帧且全在 UI 线程上，视频因此看着不动；改为按分段缓存解码器、顺序帧用 read() 步进（实测 10 ms → 0.5 ms/帧）、跳转才 seek，新增 RecordingReader.close() 释放。运输控制按用户建议上移到状态轨主按钮：toolbar.set_run_role("playback") 使回放视图的主按钮变成「▶ 回放」/「⏸ 暂停」（实时视图仍是「▶ 运行」），点按以 1× 推进游标（墙钟计时，漏拍不变慢）、到末尾自动停，拖动游标/框选/滚轮/拖总览条经 ForcePlotsPanel.timeline_taken_over 自动暂停，空格键同效；曲线表头不再放第二个播放按钮；按钮样式在回放角色下不再套用"停止"的红色语义。 - Why: 用户要求先清掉深度重算引擎、并反馈"现在无法播放视频"，建议把上方播放按钮在历史回放形式下改为回放。 - Verification: ui_check.py 554 项 0 失败（新增 seek<250ms/步进<60ms 的解码预算、回放按钮文字随播放/暂停切换、手动拖游标即暂停、切回实时视图按钮恢复运行、按深度视图已移除）；test_ui_smoke.py 71 项 0 失败；drive_shared.py 134 项 0 失败（深度引擎用例随代码删除）；locale_studio.py 262 键齐全、zh==en；reproduce.py 退出 0；.repro/probe_play.py 实测按「回放」后 0.75 s 内游标推进 0.689 s、面板 12/12 帧都在更新；两张复核图（回放视图的「▶ 回放」、实时视图的「▶ 运行」）。 - Not in this change: 录制文件格式与 CSV 列序不变（raw_*.mp4 与 forces.csv 继续一起写）；「由视频重算」复核模式保留（它复用实时管线，是有状态、只能顺序前进的一遍）。

2026-09-14 09:31:21 +08:00