调试脚本

这里集中说明和调试、运行时验证、截图录制直接相关的脚本。

总表

脚本	主要用途	常用命令	主要输出
scripts/code_runtime_check.py	运行示例、自动录制、保留截图	python scripts/code_runtime_check.py --app HelloBasic --app-sub slider --keep-screenshots	runtime_check_output/<app>/
scripts/code_compile_check.py	批量编译示例并跑 HelloUnitTest	python scripts/code_compile_check.py --full-check	终端日志
scripts/release_check.py	串起多步骤本地回归入口	python scripts/release_check.py --scope multi-display	汇总日志
scripts/checks/code_dirty_animation_check.py	检查代表性动画是否仍是局部刷新	python scripts/checks/code_dirty_animation_check.py --scenario showcase	runtime_check_output/dirty_animation_check/
scripts/perf_analysis/dirty_region_stats_report.py	把 DIRTY_REGION_STATS 日志转成 Markdown/CSV	python scripts/perf_analysis/dirty_region_stats_report.py --input showcase=perf_output/showcase.log	*.md、*.csv
scripts/checks/hello_basic_render_workflow.py	批量检查 HelloBasic / HelloVirtual 的录制动作、截图和交互变化	python scripts/checks/hello_basic_render_workflow.py --app HelloVirtual --suite basic	JSON 报告和截图
scripts/checks/showcase_stage_parity_check.py	对比 HelloShowcase 和 virtual_stage_showcase 的关键画面状态	python scripts/checks/showcase_stage_parity_check.py --bits64	对比图、diff 图

code_runtime_check.py

用途：

• 编译指定应用

• 打开录制模式运行

• 校验是否生成 PNG 帧

• 检查是否出现 [RUNTIME_CHECK_FAIL]

常用命令：

python scripts/code_runtime_check.py --app HelloShowcase --keep-screenshots
python scripts/code_runtime_check.py --app HelloBasic --app-sub slider --keep-screenshots
python scripts/code_runtime_check.py --app HelloVirtual --app-sub virtual_stage_showcase --keep-screenshots
python scripts/code_runtime_check.py --scope multi-display --jobs 2 --keep-screenshots

其中 --scope multi-display 会只跑：

• HelloMultiDisplay

• HelloMultiDisplayHetero

并额外按 EGUI_CONFIG_MAX_DISPLAY_COUNT 校验各个 display 的录制帧是否成套对应；主屏使用 frame_XXXX.png，额外屏幕使用 frame_XXXX_dispN.png。对于 HelloMultiDisplay 和 HelloMultiDisplayHetero，还会校验录制阶段标签序列，确认主屏点击、副屏点击/拖动等关键步骤确实走到了目标状态，并校验退出摘要里的 begin_shutdown -> core_threads_stopped -> sdl_cleanup -> deinit_done 顺序。

适合场景：

• 修改单个示例后，先做一次最基本的运行确认

• 想保留截图给文档或 review

• 做多屏改动后，快速回归双屏录制和副屏输入链路

code_compile_check.py

用途：

• 批量编译标准示例

• 在全量模式下跑 HelloUnitTest

• 同时覆盖 HelloBasic、HelloVirtual、HelloSizeAnalysis 的子示例

常用命令：

python scripts/code_compile_check.py --full-check
python scripts/code_compile_check.py --scope multi-display --case-jobs 2

其中 --scope multi-display 会只编译多屏相关示例，适合多屏改动后的快速编译回归。

适合场景：

• 提交前做一次编译面回归

• 修改多屏入口、descriptor、线程模型后，先快速确认双屏示例都还能编过

release_check.py

用途：

• 把多个检查步骤串成一条本地回归命令

• 适合需要一次性收口 compile、runtime 和文档校验的时候使用

常用命令：

python scripts/release_check.py --skip perf,wasm,doc
python scripts/release_check.py --scope multi-display
python scripts/release_check.py --scope multi-display --only runtime

其中 --scope multi-display 当前会收敛到：

• code_compile_check.py --scope multi-display

• code_runtime_check.py --scope multi-display

• Sphinx dummy 文档校验

其中 runtime scope 会补充校验：

• 多屏录制帧是否按 display 成套输出

• 录制阶段标签是否完整

• HelloMultiDisplay 的主屏点击隔离与双屏并发 activity 动画

• HelloMultiDisplayHetero 的副屏 tick 连续性与点击复位

• begin_shutdown -> core_threads_stopped -> sdl_cleanup -> deinit_done 退出顺序

适合场景：

• 多屏线程、descriptor、副屏输入或录制脚本改动后的本地快速收口

• 不想手动拆 compile/runtime/doc 三条命令时

如果一时记不清 scoped profile 的覆盖范围，直接执行 python scripts/release_check.py --help，末尾的 Scoped profiles 会把 multi-display 的 apps、runtime checks、--only 可用 step、drill-down 命令和关键产物目录直接列出来；真正运行 python scripts/release_check.py --scope multi-display 时，脚本开头也会直接打印这些信息和当前激活的 --only/--skip 过滤结果，方便失败后继续拆查，summary 尾部会把失败步骤对应的 python scripts/release_check.py --scope multi-display --only <step>、底层命令与产物位置再列一遍，通过时也会把关键产物目录再汇总一遍。

code_dirty_animation_check.py

用途：

• 对代表性动画做 dirty region 专项回归

• 自动打开 EGUI_CONFIG_DEBUG_DIRTY_REGION_STATS=1

• 统计 unique frame、partial frame、平均脏区比例

常用命令：

python scripts/checks/code_dirty_animation_check.py --scenario showcase
python scripts/checks/code_dirty_animation_check.py --scenario virtual_stage_showcase

适合场景：

• 优化脏区或动画后，确认没有回退成全屏刷新

• 检查 HelloShowcase 和 virtual_stage_showcase 这类复杂动效页面

dirty_region_stats_report.py

用途：

• 解析 DIRTY_REGION_STATS: 日志

• 输出 Markdown 报告和 CSV 数据

常用命令：

python scripts/perf_analysis/dirty_region_stats_report.py \
  --input showcase=perf_output/dirty_region_logs/showcase.log \
  --input stage=perf_output/dirty_region_logs/virtual_stage_showcase.log \
  --output-prefix perf_output/dirty_region_compare

适合场景：

• 想把两组日志转成可比较的报告

• 想把 dirty area、dirty ratio、pfb tiles 给到文档或评审

hello_basic_render_workflow.py

用途：

• 面向 HelloBasic 和 HelloVirtual 的批量回归入口

• 除了录制截图，还会检查交互前后是否真的发生画面变化

• 会输出结构化 JSON 报告，方便 CI 使用

常用命令：

python scripts/checks/hello_basic_render_workflow.py --app HelloBasic --suite smoke
python scripts/checks/hello_basic_render_workflow.py --app HelloBasic --suite basic
python scripts/checks/hello_basic_render_workflow.py --app HelloVirtual --widgets virtual_stage_showcase

适合场景：

• 基础控件和 virtual 相关示例做一轮批量回归

• 想确认录制动作没有缺失，截图也不是空白

showcase_stage_parity_check.py

用途：

• 对比 HelloShowcase 和 HelloVirtual/virtual_stage_showcase 的关键状态帧

• 自动生成并排图和差异图

常用命令：

python scripts/checks/showcase_stage_parity_check.py --timeout 35 --bits64

适合场景：

• 做 virtual stage 替换或优化后，确认视觉结果没有跑偏

• 需要保留对比图给本地调试记录

一个简单的使用建议

• 先用 code_runtime_check.py 看“能不能跑、画面是不是对”

• 再用 hello_basic_render_workflow.py 或 code_dirty_animation_check.py 做专项回归

• 涉及多屏时，优先先跑 release_check.py --scope multi-display，需要拆看编译日志和副屏截图时再分别跑 compile/runtime scope

• 需要定量分析时，再接 dirty_region_stats_report.py