Qt 示例窗口默认不再自动退出，仅离屏验证时自动退出

p03/ 生成产物与 docs/teaching/examples/ 手工示例里的 QTimer::singleShot
自动退出逻辑，从"始终 200ms 后退出"改为"仅当 QT_QPA_PLATFORM=offscreen
时才退出"。正常运行（有显示环境）窗口保持打开，需手动关闭；离屏自动化
验证（tools/run_qt.sh + QT_QPA_PLATFORM=offscreen）行为不变。

p03/ 改动来自重新生成 tools/gen_part3.py（AUTO_QUIT 常量加 qgetenv 判断），
未手改生成产物。QCoreApplication 控制台风格示例（qfile_basic 等）本就
执行完即退出，不受影响。

README.md

@@ -64,7 +64,8 @@ QT_QPA_PLATFORM=offscreen tools/run_qt.sh <target>
 
 > **隔离验证**：`ldd build/p03/.../<target>` 显示所有 Qt 库只解析到 `.qt514/`，
 > 零系统 Qt 引用。顶层 `CMakeLists.txt` 有版本断言——误连系统 Qt 5.15 会 `FATAL_ERROR`。
-> 每个 Qt GUI 目标注入 `QTimer::singleShot` 让程序 200ms 后自动退出，便于离屏验证。
+> 每个 Qt GUI 目标注入 `QTimer::singleShot`，仅当 `QT_QPA_PLATFORM=offscreen` 时才在
+> 200ms 后自动退出，便于离屏验证；正常运行窗口保持打开，不自动退出。
 
 ## 目录命名（深缩写）
 

docs/teaching/examples/model_view/qt_model_view_basics.cpp

@@ -3,7 +3,7 @@
 //  用途：方案书「C++方向 Day3」要求的 Model/View 模型视图架构，仓库 p03/ 原有
 //        wiki 抓取内容未覆盖这一点，故补一个最小示例。
 //  配套文档：docs/teaching/examples/model_view/README.md
-//  离屏验证：QT_QPA_PLATFORM=offscreen tools/run_qt.sh qt_model_view_basics
+//  离屏验证：QT_QPA_PLATFORM=offscreen tools/run_qt.sh qt_model_view_basics（自动退出）
 // ============================================================================
 
 #include <QApplication>
@@ -53,8 +53,11 @@ int main(int argc, char* argv[]) {
     ModelViewDemo w;
     w.resize(280, 220);
     w.show();
-    // 离屏/自动化验证：200ms 后自动退出（GUI 模式下不阻塞）
+    // 仅在离屏自动化验证时（QT_QPA_PLATFORM=offscreen）200ms 后自动退出；
-    QTimer::singleShot(200, &app, &QApplication::quit);
+    // 正常运行（有显示环境）窗口保持打开，不自动退出。
+    if (qgetenv("QT_QPA_PLATFORM") == "offscreen") {
+        QTimer::singleShot(200, &app, &QApplication::quit);
+    }
     return app.exec();
 }
 

docs/teaching/examples/property_animation/qt_property_animation.cpp

@@ -3,7 +3,7 @@
 //  用途：方案书「C++方向 Day4」要求的 QPropertyAnimation 动画框架，仓库 p03/
 //        原有 wiki 抓取内容未覆盖这一点，故补一个最小示例。
 //  配套文档：docs/teaching/examples/property_animation/README.md
-//  离屏验证：QT_QPA_PLATFORM=offscreen tools/run_qt.sh qt_property_animation
+//  离屏验证：QT_QPA_PLATFORM=offscreen tools/run_qt.sh qt_property_animation（自动退出）
 // ============================================================================
 
 #include <QApplication>
@@ -32,7 +32,10 @@ int main(int argc, char* argv[]) {
     anim->start(QAbstractAnimation::DeleteWhenStopped);
 
     window.show();
-    // 离屏/自动化验证：动画时长 800ms，额外等 300ms 确保播放完再退出
+    // 仅在离屏自动化验证时（QT_QPA_PLATFORM=offscreen）自动退出：动画时长 800ms，
-    QTimer::singleShot(1100, &app, &QApplication::quit);
+    // 额外等 300ms 确保播放完再退出；正常运行窗口保持打开，不自动退出。
+    if (qgetenv("QT_QPA_PLATFORM") == "offscreen") {
+        QTimer::singleShot(1100, &app, &QApplication::quit);
+    }
     return app.exec();
 }

docs/teaching/examples/qss_styling/qt_qss_styling.cpp

@@ -3,7 +3,7 @@
 //  用途：方案书「C++方向 Day2」要求的 QSS 界面美化，仓库 p03/ 原有 wiki 抓取内容
 //        未覆盖这一点，故补一个最小示例。
 //  配套文档：docs/teaching/examples/qss_styling/README.md
-//  离屏验证：QT_QPA_PLATFORM=offscreen tools/run_qt.sh qt_qss_styling
+//  离屏验证：QT_QPA_PLATFORM=offscreen tools/run_qt.sh qt_qss_styling（自动退出）
 // ============================================================================
 
 #include <QApplication>
@@ -50,8 +50,11 @@ int main(int argc, char* argv[]) {
     StyledPanel panel;
     panel.resize(240, 160);
     panel.show();
-    // 离屏/自动化验证：200ms 后自动退出（GUI 模式下不阻塞）
+    // 仅在离屏自动化验证时（QT_QPA_PLATFORM=offscreen）200ms 后自动退出；
-    QTimer::singleShot(200, &app, &QApplication::quit);
+    // 正常运行（有显示环境）窗口保持打开，不自动退出。
+    if (qgetenv("QT_QPA_PLATFORM") == "offscreen") {
+        QTimer::singleShot(200, &app, &QApplication::quit);
+    }
     return app.exec();
 }
 

docs/teaching/examples/state_machine/qt_state_machine.cpp

@@ -4,7 +4,7 @@
 //        不需要额外模块），仓库 p03/ 原有 wiki 抓取内容未覆盖这一点，故补一个
 //        最小示例：一个“红灯/绿灯”两态按钮，点击在两态间切换。
 //  配套文档：docs/teaching/examples/state_machine/README.md
-//  离屏验证：QT_QPA_PLATFORM=offscreen tools/run_qt.sh qt_state_machine
+//  离屏验证：QT_QPA_PLATFORM=offscreen tools/run_qt.sh qt_state_machine（自动退出）
 // ============================================================================
 
 #include <QApplication>
@@ -39,9 +39,12 @@ int main(int argc, char* argv[]) {
 
     button.show();
 
-    // 离屏/自动化验证：100ms 后模拟一次点击（red -> green），
+    // 仅在离屏自动化验证时（QT_QPA_PLATFORM=offscreen）：100ms 后模拟一次点击
-    // 再等 200ms 确认状态机正常处理完过渡后自动退出
+    // （red -> green），再等 200ms 确认状态机正常处理完过渡后自动退出。
-    QTimer::singleShot(100, &button, [&button]() { button.click(); });
+    // 正常运行（有显示环境）需用户手动点击按钮切换状态，窗口保持打开。
-    QTimer::singleShot(300, &app, &QApplication::quit);
+    if (qgetenv("QT_QPA_PLATFORM") == "offscreen") {
+        QTimer::singleShot(100, &button, [&button]() { button.click(); });
+        QTimer::singleShot(300, &app, &QApplication::quit);
+    }
     return app.exec();
 }

p03/ch02/minimal_qt_app.cpp

@@ -4,7 +4,7 @@
 //  原文片段：[58954515:0]
 //  说明：本文件由 gen_part3.py 从 wiki 片段生成（必要时补 main/QApplication
 //        外壳、include、修正笔误）。详见 docs/ERRATA.md。
-//        离屏验证：QT_QPA_PLATFORM=offscreen tools/run_qt.sh <target>
+//        离屏验证：QT_QPA_PLATFORM=offscreen tools/run_qt.sh <target>（自动退出）
 // ============================================================================
 
 #include <QApplication>
@@ -22,8 +22,11 @@ int main(int argc, char* argv[]) {
     QApplication app(argc, argv);
     Widget w;
     w.show();
-    // 离屏/自动化验证：200ms 后自动退出（GUI 模式下不阻塞）
+    // 仅在离屏自动化验证时（QT_QPA_PLATFORM=offscreen）200ms 后自动退出；
-    QTimer::singleShot(200, &app, &QApplication::quit);
+    // 正常运行（有显示环境）窗口保持打开，不自动退出。
+    if (qgetenv("QT_QPA_PLATFORM") == "offscreen") {
+        QTimer::singleShot(200, &app, &QApplication::quit);
+    }
     return app.exec();
 }
 

p03/ch03/button_creation.cpp

@@ -4,7 +4,7 @@
 //  原文片段：[58954525:0]
 //  说明：本文件由 gen_part3.py 从 wiki 片段生成（必要时补 main/QApplication
 //        外壳、include、修正笔误）。详见 docs/ERRATA.md。
-//        离屏验证：QT_QPA_PLATFORM=offscreen tools/run_qt.sh <target>
+//        离屏验证：QT_QPA_PLATFORM=offscreen tools/run_qt.sh <target>（自动退出）
 // ============================================================================
 
 #include <QApplication>
@@ -36,8 +36,11 @@ int main(int argc, char* argv[]) {
     QApplication app(argc, argv);
     DemoWidget w;
     w.show();
-    // 离屏/自动化验证：200ms 后自动退出（GUI 模式下不阻塞）
+    // 仅在离屏自动化验证时（QT_QPA_PLATFORM=offscreen）200ms 后自动退出；
-    QTimer::singleShot(200, &app, &QApplication::quit);
+    // 正常运行（有显示环境）窗口保持打开，不自动退出。
+    if (qgetenv("QT_QPA_PLATFORM") == "offscreen") {
+        QTimer::singleShot(200, &app, &QApplication::quit);
+    }
     return app.exec();
 }
 

p03/ch04/builtin_signal_slot.cpp

@@ -4,7 +4,7 @@
 //  原文片段：[58954527:0]
 //  说明：本文件由 gen_part3.py 从 wiki 片段生成（必要时补 main/QApplication
 //        外壳、include、修正笔误）。详见 docs/ERRATA.md。
-//        离屏验证：QT_QPA_PLATFORM=offscreen tools/run_qt.sh <target>
+//        离屏验证：QT_QPA_PLATFORM=offscreen tools/run_qt.sh <target>（自动退出）
 // ============================================================================
 
 #include <QApplication>
@@ -28,8 +28,11 @@ int main(int argc, char* argv[]) {
     QApplication app(argc, argv);
     DemoWidget w;
     w.show();
-    // 离屏/自动化验证：200ms 后自动退出（GUI 模式下不阻塞）
+    // 仅在离屏自动化验证时（QT_QPA_PLATFORM=offscreen）200ms 后自动退出；
-    QTimer::singleShot(200, &app, &QApplication::quit);
+    // 正常运行（有显示环境）窗口保持打开，不自动退出。
+    if (qgetenv("QT_QPA_PLATFORM") == "offscreen") {
+        QTimer::singleShot(200, &app, &QApplication::quit);
+    }
     return app.exec();
 }
 

p03/ch04/custom_signal_slot.cpp

@@ -4,7 +4,7 @@
 //  原文片段：[58954527:2]
 //  说明：本文件由 gen_part3.py 从 wiki 片段生成（必要时补 main/QApplication
 //        外壳、include、修正笔误）。详见 docs/ERRATA.md。
-//        离屏验证：QT_QPA_PLATFORM=offscreen tools/run_qt.sh <target>
+//        离屏验证：QT_QPA_PLATFORM=offscreen tools/run_qt.sh <target>（自动退出）
 // ============================================================================
 
 #include <QApplication>
@@ -60,8 +60,11 @@ public:
 int main(int argc, char* argv[]) {
     QApplication app(argc, argv);
     MyWidget w; w.show();
-    // 离屏/自动化验证：200ms 后自动退出（GUI 模式下不阻塞）
+    // 仅在离屏自动化验证时（QT_QPA_PLATFORM=offscreen）200ms 后自动退出；
-    QTimer::singleShot(200, &app, &QApplication::quit);
+    // 正常运行（有显示环境）窗口保持打开，不自动退出。
+    if (qgetenv("QT_QPA_PLATFORM") == "offscreen") {
+        QTimer::singleShot(200, &app, &QApplication::quit);
+    }
     return app.exec();
 }
 

p03/ch04/lambda_signal_slot.cpp

@@ -4,7 +4,7 @@
 //  原文片段：[58954527:6]
 //  说明：本文件由 gen_part3.py 从 wiki 片段生成（必要时补 main/QApplication
 //        外壳、include、修正笔误）。详见 docs/ERRATA.md。
-//        离屏验证：QT_QPA_PLATFORM=offscreen tools/run_qt.sh <target>
+//        离屏验证：QT_QPA_PLATFORM=offscreen tools/run_qt.sh <target>（自动退出）
 // ============================================================================
 
 #include <QApplication>
@@ -34,8 +34,11 @@ int main(int argc, char* argv[]) {
     QApplication app(argc, argv);
     DemoWidget w;
     w.show();
-    // 离屏/自动化验证：200ms 后自动退出（GUI 模式下不阻塞）
+    // 仅在离屏自动化验证时（QT_QPA_PLATFORM=offscreen）200ms 后自动退出；
-    QTimer::singleShot(200, &app, &QApplication::quit);
+    // 正常运行（有显示环境）窗口保持打开，不自动退出。
+    if (qgetenv("QT_QPA_PLATFORM") == "offscreen") {
+        QTimer::singleShot(200, &app, &QApplication::quit);
+    }
     return app.exec();
 }
 

p03/ch05/central_widget.cpp

@@ -4,7 +4,7 @@
 //  原文片段：[58954529:5]
 //  说明：本文件由 gen_part3.py 从 wiki 片段生成（必要时补 main/QApplication
 //        外壳、include、修正笔误）。详见 docs/ERRATA.md。
-//        离屏验证：QT_QPA_PLATFORM=offscreen tools/run_qt.sh <target>
+//        离屏验证：QT_QPA_PLATFORM=offscreen tools/run_qt.sh <target>（自动退出）
 // ============================================================================
 
 #include <QApplication>
@@ -25,8 +25,11 @@ int main(int argc, char* argv[]) {
     QApplication app(argc, argv);
     DemoMainWindow w;
     w.show();
-    // 离屏/自动化验证：200ms 后自动退出（GUI 模式下不阻塞）
+    // 仅在离屏自动化验证时（QT_QPA_PLATFORM=offscreen）200ms 后自动退出；
-    QTimer::singleShot(200, &app, &QApplication::quit);
+    // 正常运行（有显示环境）窗口保持打开，不自动退出。
+    if (qgetenv("QT_QPA_PLATFORM") == "offscreen") {
+        QTimer::singleShot(200, &app, &QApplication::quit);
+    }
     return app.exec();
 }
 

p03/ch05/dock_widget.cpp

@@ -4,7 +4,7 @@
 //  原文片段：[58954529:4]
 //  说明：本文件由 gen_part3.py 从 wiki 片段生成（必要时补 main/QApplication
 //        外壳、include、修正笔误）。详见 docs/ERRATA.md。
-//        离屏验证：QT_QPA_PLATFORM=offscreen tools/run_qt.sh <target>
+//        离屏验证：QT_QPA_PLATFORM=offscreen tools/run_qt.sh <target>（自动退出）
 // ============================================================================
 
 #include <QApplication>
@@ -29,8 +29,11 @@ int main(int argc, char* argv[]) {
     QApplication app(argc, argv);
     DemoMainWindow w;
     w.show();
-    // 离屏/自动化验证：200ms 后自动退出（GUI 模式下不阻塞）
+    // 仅在离屏自动化验证时（QT_QPA_PLATFORM=offscreen）200ms 后自动退出；
-    QTimer::singleShot(200, &app, &QApplication::quit);
+    // 正常运行（有显示环境）窗口保持打开，不自动退出。
+    if (qgetenv("QT_QPA_PLATFORM") == "offscreen") {
+        QTimer::singleShot(200, &app, &QApplication::quit);
+    }
     return app.exec();
 }
 

p03/ch06/file_dialog.cpp

@@ -4,7 +4,7 @@
 //  原文片段：[58954535:12]
 //  说明：本文件由 gen_part3.py 从 wiki 片段生成（必要时补 main/QApplication
 //        外壳、include、修正笔误）。详见 docs/ERRATA.md。
-//        离屏验证：QT_QPA_PLATFORM=offscreen tools/run_qt.sh <target>
+//        离屏验证：QT_QPA_PLATFORM=offscreen tools/run_qt.sh <target>（自动退出）
 // ============================================================================
 
 #include <QApplication>
@@ -60,8 +60,11 @@ private slots:
 int main(int argc, char* argv[]) {
     QApplication app(argc, argv);
     MainWindow w; w.show();
-    // 离屏/自动化验证：200ms 后自动退出（GUI 模式下不阻塞）
+    // 仅在离屏自动化验证时（QT_QPA_PLATFORM=offscreen）200ms 后自动退出；
-    QTimer::singleShot(200, &app, &QApplication::quit);
+    // 正常运行（有显示环境）窗口保持打开，不自动退出。
+    if (qgetenv("QT_QPA_PLATFORM") == "offscreen") {
+        QTimer::singleShot(200, &app, &QApplication::quit);
+    }
     return app.exec();
 }
 

p03/ch06/message_box_custom.cpp

@@ -4,7 +4,7 @@
 //  原文片段：[58954535:11]
 //  说明：本文件由 gen_part3.py 从 wiki 片段生成（必要时补 main/QApplication
 //        外壳、include、修正笔误）。详见 docs/ERRATA.md。
-//        离屏验证：QT_QPA_PLATFORM=offscreen tools/run_qt.sh <target>
+//        离屏验证：QT_QPA_PLATFORM=offscreen tools/run_qt.sh <target>（自动退出）
 // ============================================================================
 
 #include <QApplication>
@@ -47,8 +47,11 @@ int main(int argc, char* argv[]) {
     QApplication app(argc, argv);
     DemoWidget w;
     w.show();
-    // 离屏/自动化验证：200ms 后自动退出（GUI 模式下不阻塞）
+    // 仅在离屏自动化验证时（QT_QPA_PLATFORM=offscreen）200ms 后自动退出；
-    QTimer::singleShot(200, &app, &QApplication::quit);
+    // 正常运行（有显示环境）窗口保持打开，不自动退出。
+    if (qgetenv("QT_QPA_PLATFORM") == "offscreen") {
+        QTimer::singleShot(200, &app, &QApplication::quit);
+    }
     return app.exec();
 }
 

p03/ch06/message_box_question.cpp

@@ -4,7 +4,7 @@
 //  原文片段：[58954535:10]
 //  说明：本文件由 gen_part3.py 从 wiki 片段生成（必要时补 main/QApplication
 //        外壳、include、修正笔误）。详见 docs/ERRATA.md。
-//        离屏验证：QT_QPA_PLATFORM=offscreen tools/run_qt.sh <target>
+//        离屏验证：QT_QPA_PLATFORM=offscreen tools/run_qt.sh <target>（自动退出）
 // ============================================================================
 
 #include <QApplication>
@@ -39,8 +39,11 @@ int main(int argc, char* argv[]) {
     QApplication app(argc, argv);
     DemoWidget w;
     w.show();
-    // 离屏/自动化验证：200ms 后自动退出（GUI 模式下不阻塞）
+    // 仅在离屏自动化验证时（QT_QPA_PLATFORM=offscreen）200ms 后自动退出；
-    QTimer::singleShot(200, &app, &QApplication::quit);
+    // 正常运行（有显示环境）窗口保持打开，不自动退出。
+    if (qgetenv("QT_QPA_PLATFORM") == "offscreen") {
+        QTimer::singleShot(200, &app, &QApplication::quit);
+    }
     return app.exec();
 }
 

p03/ch06/modal_dialog.cpp

@@ -4,7 +4,7 @@
 //  原文片段：[58954535:0]
 //  说明：本文件由 gen_part3.py 从 wiki 片段生成（必要时补 main/QApplication
 //        外壳、include、修正笔误）。详见 docs/ERRATA.md。
-//        离屏验证：QT_QPA_PLATFORM=offscreen tools/run_qt.sh <target>
+//        离屏验证：QT_QPA_PLATFORM=offscreen tools/run_qt.sh <target>（自动退出）
 // ============================================================================
 
 #include <QApplication>
@@ -28,8 +28,11 @@ int main(int argc, char* argv[]) {
     QApplication app(argc, argv);
     DemoWidget w;
     w.show();
-    // 离屏/自动化验证：200ms 后自动退出（GUI 模式下不阻塞）
+    // 仅在离屏自动化验证时（QT_QPA_PLATFORM=offscreen）200ms 后自动退出；
-    QTimer::singleShot(200, &app, &QApplication::quit);
+    // 正常运行（有显示环境）窗口保持打开，不自动退出。
+    if (qgetenv("QT_QPA_PLATFORM") == "offscreen") {
+        QTimer::singleShot(200, &app, &QApplication::quit);
+    }
     return app.exec();
 }
 

p03/ch06/modeless_dialog_deleteonclose.cpp

@@ -4,7 +4,7 @@
 //  原文片段：[58954535:3]
 //  说明：本文件由 gen_part3.py 从 wiki 片段生成（必要时补 main/QApplication
 //        外壳、include、修正笔误）。详见 docs/ERRATA.md。
-//        离屏验证：QT_QPA_PLATFORM=offscreen tools/run_qt.sh <target>
+//        离屏验证：QT_QPA_PLATFORM=offscreen tools/run_qt.sh <target>（自动退出）
 // ============================================================================
 
 #include <QApplication>
@@ -29,8 +29,11 @@ int main(int argc, char* argv[]) {
     QApplication app(argc, argv);
     DemoWidget w;
     w.show();
-    // 离屏/自动化验证：200ms 后自动退出（GUI 模式下不阻塞）
+    // 仅在离屏自动化验证时（QT_QPA_PLATFORM=offscreen）200ms 后自动退出；
-    QTimer::singleShot(200, &app, &QApplication::quit);
+    // 正常运行（有显示环境）窗口保持打开，不自动退出。
+    if (qgetenv("QT_QPA_PLATFORM") == "offscreen") {
+        QTimer::singleShot(200, &app, &QApplication::quit);
+    }
     return app.exec();
 }
 

p03/ch06/modeless_dialog_heap.cpp

@@ -4,7 +4,7 @@
 //  原文片段：[58954535:2]
 //  说明：本文件由 gen_part3.py 从 wiki 片段生成（必要时补 main/QApplication
 //        外壳、include、修正笔误）。详见 docs/ERRATA.md。
-//        离屏验证：QT_QPA_PLATFORM=offscreen tools/run_qt.sh <target>
+//        离屏验证：QT_QPA_PLATFORM=offscreen tools/run_qt.sh <target>（自动退出）
 // ============================================================================
 
 #include <QApplication>
@@ -28,8 +28,11 @@ int main(int argc, char* argv[]) {
     QApplication app(argc, argv);
     DemoWidget w;
     w.show();
-    // 离屏/自动化验证：200ms 后自动退出（GUI 模式下不阻塞）
+    // 仅在离屏自动化验证时（QT_QPA_PLATFORM=offscreen）200ms 后自动退出；
-    QTimer::singleShot(200, &app, &QApplication::quit);
+    // 正常运行（有显示环境）窗口保持打开，不自动退出。
+    if (qgetenv("QT_QPA_PLATFORM") == "offscreen") {
+        QTimer::singleShot(200, &app, &QApplication::quit);
+    }
     return app.exec();
 }
 

p03/ch06/modeless_dialog_stack.cpp

@@ -4,7 +4,7 @@
 //  原文片段：[58954535:1]
 //  说明：本文件由 gen_part3.py 从 wiki 片段生成（必要时补 main/QApplication
 //        外壳、include、修正笔误）。详见 docs/ERRATA.md。
-//        离屏验证：QT_QPA_PLATFORM=offscreen tools/run_qt.sh <target>
+//        离屏验证：QT_QPA_PLATFORM=offscreen tools/run_qt.sh <target>（自动退出）
 // ============================================================================
 
 #include <QApplication>
@@ -28,8 +28,11 @@ int main(int argc, char* argv[]) {
     QApplication app(argc, argv);
     DemoWidget w;
     w.show();
-    // 离屏/自动化验证：200ms 后自动退出（GUI 模式下不阻塞）
+    // 仅在离屏自动化验证时（QT_QPA_PLATFORM=offscreen）200ms 后自动退出；
-    QTimer::singleShot(200, &app, &QApplication::quit);
+    // 正常运行（有显示环境）窗口保持打开，不自动退出。
+    if (qgetenv("QT_QPA_PLATFORM") == "offscreen") {
+        QTimer::singleShot(200, &app, &QApplication::quit);
+    }
     return app.exec();
 }
 

p03/ch08/custom_widget.cpp

@@ -4,7 +4,7 @@
 //  原文片段：[58954540:15]
 //  说明：本文件由 gen_part3.py 从 wiki 片段生成（必要时补 main/QApplication
 //        外壳、include、修正笔误）。详见 docs/ERRATA.md。
-//        离屏验证：QT_QPA_PLATFORM=offscreen tools/run_qt.sh <target>
+//        离屏验证：QT_QPA_PLATFORM=offscreen tools/run_qt.sh <target>（自动退出）
 // ============================================================================
 
 #include <QApplication>
@@ -36,8 +36,11 @@ public:
 int main(int argc, char* argv[]) {
     QApplication app(argc, argv);
     SmallWidget w; w.show();
-    // 离屏/自动化验证：200ms 后自动退出（GUI 模式下不阻塞）
+    // 仅在离屏自动化验证时（QT_QPA_PLATFORM=offscreen）200ms 后自动退出；
-    QTimer::singleShot(200, &app, &QApplication::quit);
+    // 正常运行（有显示环境）窗口保持打开，不自动退出。
+    if (qgetenv("QT_QPA_PLATFORM") == "offscreen") {
+        QTimer::singleShot(200, &app, &QApplication::quit);
+    }
     return app.exec();
 }
 

p03/ch08/label_movie.cpp

@@ -4,7 +4,7 @@
 //  原文片段：[58954540:movie]
 //  说明：本文件由 gen_part3.py 从 wiki 片段生成（必要时补 main/QApplication
 //        外壳、include、修正笔误）。详见 docs/ERRATA.md。
-//        离屏验证：QT_QPA_PLATFORM=offscreen tools/run_qt.sh <target>
+//        离屏验证：QT_QPA_PLATFORM=offscreen tools/run_qt.sh <target>（自动退出）
 // ============================================================================
 
 #include <QApplication>
@@ -29,8 +29,11 @@ int main(int argc, char* argv[]) {
     QApplication app(argc, argv);
     DemoWidget w;
     w.show();
-    // 离屏/自动化验证：200ms 后自动退出（GUI 模式下不阻塞）
+    // 仅在离屏自动化验证时（QT_QPA_PLATFORM=offscreen）200ms 后自动退出；
-    QTimer::singleShot(200, &app, &QApplication::quit);
+    // 正常运行（有显示环境）窗口保持打开，不自动退出。
+    if (qgetenv("QT_QPA_PLATFORM") == "offscreen") {
+        QTimer::singleShot(200, &app, &QApplication::quit);
+    }
     return app.exec();
 }
 

p03/ch08/label_pixmap.cpp

@@ -4,7 +4,7 @@
 //  原文片段：[58954540:img]
 //  说明：本文件由 gen_part3.py 从 wiki 片段生成（必要时补 main/QApplication
 //        外壳、include、修正笔误）。详见 docs/ERRATA.md。
-//        离屏验证：QT_QPA_PLATFORM=offscreen tools/run_qt.sh <target>
+//        离屏验证：QT_QPA_PLATFORM=offscreen tools/run_qt.sh <target>（自动退出）
 // ============================================================================
 
 #include <QApplication>
@@ -29,8 +29,11 @@ int main(int argc, char* argv[]) {
     QApplication app(argc, argv);
     DemoWidget w;
     w.show();
-    // 离屏/自动化验证：200ms 后自动退出（GUI 模式下不阻塞）
+    // 仅在离屏自动化验证时（QT_QPA_PLATFORM=offscreen）200ms 后自动退出；
-    QTimer::singleShot(200, &app, &QApplication::quit);
+    // 正常运行（有显示环境）窗口保持打开，不自动退出。
+    if (qgetenv("QT_QPA_PLATFORM") == "offscreen") {
+        QTimer::singleShot(200, &app, &QApplication::quit);
+    }
     return app.exec();
 }
 

p03/ch08/label_text_create.cpp

@@ -4,7 +4,7 @@
 //  原文片段：[58954540:1]
 //  说明：本文件由 gen_part3.py 从 wiki 片段生成（必要时补 main/QApplication
 //        外壳、include、修正笔误）。详见 docs/ERRATA.md。
-//        离屏验证：QT_QPA_PLATFORM=offscreen tools/run_qt.sh <target>
+//        离屏验证：QT_QPA_PLATFORM=offscreen tools/run_qt.sh <target>（自动退出）
 // ============================================================================
 
 #include <QApplication>
@@ -25,8 +25,11 @@ int main(int argc, char* argv[]) {
     QApplication app(argc, argv);
     DemoWidget w;
     w.show();
-    // 离屏/自动化验证：200ms 后自动退出（GUI 模式下不阻塞）
+    // 仅在离屏自动化验证时（QT_QPA_PLATFORM=offscreen）200ms 后自动退出；
-    QTimer::singleShot(200, &app, &QApplication::quit);
+    // 正常运行（有显示环境）窗口保持打开，不自动退出。
+    if (qgetenv("QT_QPA_PLATFORM") == "offscreen") {
+        QTimer::singleShot(200, &app, &QApplication::quit);
+    }
     return app.exec();
 }
 

p03/ch08/label_text_html.cpp

@@ -4,7 +4,7 @@
 //  原文片段：[58954540:2]
 //  说明：本文件由 gen_part3.py 从 wiki 片段生成（必要时补 main/QApplication
 //        外壳、include、修正笔误）。详见 docs/ERRATA.md。
-//        离屏验证：QT_QPA_PLATFORM=offscreen tools/run_qt.sh <target>
+//        离屏验证：QT_QPA_PLATFORM=offscreen tools/run_qt.sh <target>（自动退出）
 // ============================================================================
 
 #include <QApplication>
@@ -27,8 +27,11 @@ int main(int argc, char* argv[]) {
     QApplication app(argc, argv);
     DemoWidget w;
     w.show();
-    // 离屏/自动化验证：200ms 后自动退出（GUI 模式下不阻塞）
+    // 仅在离屏自动化验证时（QT_QPA_PLATFORM=offscreen）200ms 后自动退出；
-    QTimer::singleShot(200, &app, &QApplication::quit);
+    // 正常运行（有显示环境）窗口保持打开，不自动退出。
+    if (qgetenv("QT_QPA_PLATFORM") == "offscreen") {
+        QTimer::singleShot(200, &app, &QApplication::quit);
+    }
     return app.exec();
 }
 

p03/ch09/event_filter_mainwindow.cpp

@@ -4,7 +4,7 @@
 //  原文片段：[58954546:6]
 //  说明：本文件由 gen_part3.py 从 wiki 片段生成（必要时补 main/QApplication
 //        外壳、include、修正笔误）。详见 docs/ERRATA.md。
-//        离屏验证：QT_QPA_PLATFORM=offscreen tools/run_qt.sh <target>
+//        离屏验证：QT_QPA_PLATFORM=offscreen tools/run_qt.sh <target>（自动退出）
 // ============================================================================
 
 #include <QApplication>
@@ -39,8 +39,11 @@ int main(int argc, char* argv[]) {
     QApplication app(argc, argv);
     MainWindow w;
     w.show();
-    // 离屏/自动化验证：200ms 后自动退出（GUI 模式下不阻塞）
+    // 仅在离屏自动化验证时（QT_QPA_PLATFORM=offscreen）200ms 后自动退出；
-    QTimer::singleShot(200, &app, &QApplication::quit);
+    // 正常运行（有显示环境）窗口保持打开，不自动退出。
+    if (qgetenv("QT_QPA_PLATFORM") == "offscreen") {
+        QTimer::singleShot(200, &app, &QApplication::quit);
+    }
     return app.exec();
 }
 

p03/ch09/event_override_customwidget.cpp

@@ -4,7 +4,7 @@
 //  原文片段：[58954546:2]
 //  说明：本文件由 gen_part3.py 从 wiki 片段生成（必要时补 main/QApplication
 //        外壳、include、修正笔误）。详见 docs/ERRATA.md。
-//        离屏验证：QT_QPA_PLATFORM=offscreen tools/run_qt.sh <target>
+//        离屏验证：QT_QPA_PLATFORM=offscreen tools/run_qt.sh <target>（自动退出）
 // ============================================================================
 
 #include <QApplication>
@@ -35,8 +35,11 @@ int main(int argc, char* argv[]) {
     QApplication app(argc, argv);
     CustomWidget w;
     w.show();
-    // 离屏/自动化验证：200ms 后自动退出（GUI 模式下不阻塞）
+    // 仅在离屏自动化验证时（QT_QPA_PLATFORM=offscreen）200ms 后自动退出；
-    QTimer::singleShot(200, &app, &QApplication::quit);
+    // 正常运行（有显示环境）窗口保持打开，不自动退出。
+    if (qgetenv("QT_QPA_PLATFORM") == "offscreen") {
+        QTimer::singleShot(200, &app, &QApplication::quit);
+    }
     return app.exec();
 }
 

p03/ch09/mouse_event.cpp

@@ -4,7 +4,7 @@
 //  原文片段：[58954546:0]
 //  说明：本文件由 gen_part3.py 从 wiki 片段生成（必要时补 main/QApplication
 //        外壳、include、修正笔误）。详见 docs/ERRATA.md。
-//        离屏验证：QT_QPA_PLATFORM=offscreen tools/run_qt.sh <target>
+//        离屏验证：QT_QPA_PLATFORM=offscreen tools/run_qt.sh <target>（自动退出）
 // ============================================================================
 
 #include <QApplication>
@@ -41,8 +41,11 @@ int main(int argc, char* argv[]) {
     QApplication app(argc, argv);
     EventLabel w;
     w.show();
-    // 离屏/自动化验证：200ms 后自动退出（GUI 模式下不阻塞）
+    // 仅在离屏自动化验证时（QT_QPA_PLATFORM=offscreen）200ms 后自动退出；
-    QTimer::singleShot(200, &app, &QApplication::quit);
+    // 正常运行（有显示环境）窗口保持打开，不自动退出。
+    if (qgetenv("QT_QPA_PLATFORM") == "offscreen") {
+        QTimer::singleShot(200, &app, &QApplication::quit);
+    }
     return app.exec();
 }
 

p03/ch10/paint_device_pixmaps.cpp

@@ -4,7 +4,7 @@
 //  原文片段：[58954548:2]
 //  说明：本文件由 gen_part3.py 从 wiki 片段生成（必要时补 main/QApplication
 //        外壳、include、修正笔误）。详见 docs/ERRATA.md。
-//        离屏验证：QT_QPA_PLATFORM=offscreen tools/run_qt.sh <target>
+//        离屏验证：QT_QPA_PLATFORM=offscreen tools/run_qt.sh <target>（自动退出）
 // ============================================================================
 
 #include <QApplication>
@@ -36,8 +36,11 @@ int main(int argc, char* argv[]) {
     QApplication app(argc, argv);
     PaintWidget w;
     w.show();
-    // 离屏/自动化验证：200ms 后自动退出（GUI 模式下不阻塞）
+    // 仅在离屏自动化验证时（QT_QPA_PLATFORM=offscreen）200ms 后自动退出；
-    QTimer::singleShot(200, &app, &QApplication::quit);
+    // 正常运行（有显示环境）窗口保持打开，不自动退出。
+    if (qgetenv("QT_QPA_PLATFORM") == "offscreen") {
+        QTimer::singleShot(200, &app, &QApplication::quit);
+    }
     return app.exec();
 }
 

p03/ch10/paint_device_qimage.cpp

@@ -4,7 +4,7 @@
 //  原文片段：[58954548:3]
 //  说明：本文件由 gen_part3.py 从 wiki 片段生成（必要时补 main/QApplication
 //        外壳、include、修正笔误）。详见 docs/ERRATA.md。
-//        离屏验证：QT_QPA_PLATFORM=offscreen tools/run_qt.sh <target>
+//        离屏验证：QT_QPA_PLATFORM=offscreen tools/run_qt.sh <target>（自动退出）
 // ============================================================================
 
 #include <QApplication>
@@ -36,8 +36,11 @@ int main(int argc, char* argv[]) {
     QApplication app(argc, argv);
     PaintWidget w;
     w.show();
-    // 离屏/自动化验证：200ms 后自动退出（GUI 模式下不阻塞）
+    // 仅在离屏自动化验证时（QT_QPA_PLATFORM=offscreen）200ms 后自动退出；
-    QTimer::singleShot(200, &app, &QApplication::quit);
+    // 正常运行（有显示环境）窗口保持打开，不自动退出。
+    if (qgetenv("QT_QPA_PLATFORM") == "offscreen") {
+        QTimer::singleShot(200, &app, &QApplication::quit);
+    }
     return app.exec();
 }
 

p03/ch10/qpainter_basic.cpp

@@ -4,7 +4,7 @@
 //  原文片段：[58954548:0]
 //  说明：本文件由 gen_part3.py 从 wiki 片段生成（必要时补 main/QApplication
 //        外壳、include、修正笔误）。详见 docs/ERRATA.md。
-//        离屏验证：QT_QPA_PLATFORM=offscreen tools/run_qt.sh <target>
+//        离屏验证：QT_QPA_PLATFORM=offscreen tools/run_qt.sh <target>（自动退出）
 // ============================================================================
 
 #include <QApplication>
@@ -32,8 +32,11 @@ int main(int argc, char* argv[]) {
     QApplication app(argc, argv);
     PaintedWidget w;
     w.show();
-    // 离屏/自动化验证：200ms 后自动退出（GUI 模式下不阻塞）
+    // 仅在离屏自动化验证时（QT_QPA_PLATFORM=offscreen）200ms 后自动退出；
-    QTimer::singleShot(200, &app, &QApplication::quit);
+    // 正常运行（有显示环境）窗口保持打开，不自动退出。
+    if (qgetenv("QT_QPA_PLATFORM") == "offscreen") {
+        QTimer::singleShot(200, &app, &QApplication::quit);
+    }
     return app.exec();
 }
 

p03/ch10/qpicture_io.cpp

@@ -4,7 +4,7 @@
 //  原文片段：[58954548:4]
 //  说明：本文件由 gen_part3.py 从 wiki 片段生成（必要时补 main/QApplication
 //        外壳、include、修正笔误）。详见 docs/ERRATA.md。
-//        离屏验证：QT_QPA_PLATFORM=offscreen tools/run_qt.sh <target>
+//        离屏验证：QT_QPA_PLATFORM=offscreen tools/run_qt.sh <target>（自动退出）
 // ============================================================================
 
 #include <QApplication>
@@ -41,8 +41,11 @@ int main(int argc, char* argv[]) {
     QApplication app(argc, argv);
     PaintWidget w;
     w.show();
-    // 离屏/自动化验证：200ms 后自动退出（GUI 模式下不阻塞）
+    // 仅在离屏自动化验证时（QT_QPA_PLATFORM=offscreen）200ms 后自动退出；
-    QTimer::singleShot(200, &app, &QApplication::quit);
+    // 正常运行（有显示环境）窗口保持打开，不自动退出。
+    if (qgetenv("QT_QPA_PLATFORM") == "offscreen") {
+        QTimer::singleShot(200, &app, &QApplication::quit);
+    }
     return app.exec();
 }
 

p03/ch11/qdatastream_io.cpp

@@ -4,7 +4,7 @@
 //  原文片段：[58954552:data]
 //  说明：本文件由 gen_part3.py 从 wiki 片段生成（必要时补 main/QApplication
 //        外壳、include、修正笔误）。详见 docs/ERRATA.md。
-//        离屏验证：QT_QPA_PLATFORM=offscreen tools/run_qt.sh <target>
+//        离屏验证：QT_QPA_PLATFORM=offscreen tools/run_qt.sh <target>（自动退出）
 // ============================================================================
 
 #include <QApplication>

p03/ch11/qfile_basic.cpp

@@ -4,7 +4,7 @@
 //  原文片段：[58954552:0]
 //  说明：本文件由 gen_part3.py 从 wiki 片段生成（必要时补 main/QApplication
 //        外壳、include、修正笔误）。详见 docs/ERRATA.md。
-//        离屏验证：QT_QPA_PLATFORM=offscreen tools/run_qt.sh <target>
+//        离屏验证：QT_QPA_PLATFORM=offscreen tools/run_qt.sh <target>（自动退出）
 // ============================================================================
 
 #include <QCoreApplication>

p03/ch11/qtextstream_io.cpp

@@ -4,7 +4,7 @@
 //  原文片段：[58954552:text]
 //  说明：本文件由 gen_part3.py 从 wiki 片段生成（必要时补 main/QApplication
 //        外壳、include、修正笔误）。详见 docs/ERRATA.md。
-//        离屏验证：QT_QPA_PLATFORM=offscreen tools/run_qt.sh <target>
+//        离屏验证：QT_QPA_PLATFORM=offscreen tools/run_qt.sh <target>（自动退出）
 // ============================================================================
 
 #include <QApplication>

tools/gen_part3.py

@@ -10,8 +10,9 @@
 #                      外壳包裹，必要时补所需 QWidget/QMainWindow 子类骨架。
 #        - 'snippet'   纯签名/单语句/伪代码，不单独建目标，折进各章 README 作文档。
 #    * 每个目标 = 一个独立 add_executable；开 AUTOMOC（Q_OBJECT 类需 moc）。
-#    * 离屏运行友好：每个目标注入一个 QTimer::singleShot 让程序 200ms 后自动退出，
+#    * 离屏运行友好：每个窗口类目标注入一个 QTimer::singleShot，仅当检测到
-#      便于 QT_QPA_PLATFORM=offscreen 自动化验证（窗口类目标）。
+#      QT_QPA_PLATFORM=offscreen 时才在 200ms 后自动退出；正常运行（有显示环境）
+#      窗口保持打开，不会自动关闭。
 #    * 资源依赖（:/images/*.png 等）用脚本生成的纯色占位 png + .qrc 提供，qt5_add_resources。
 #    * Qt 代码修正（笔误/平台/过时 API）每处 record_erratum 进 docs/ERRATA.md（透明可审计）。
 #
@@ -275,8 +276,11 @@ TARGET_DATAFILES = {
 #  外壳模板：把一个「片段」包成可运行的 Qt 程序
 # ==============================================================================
 AUTO_QUIT = (
-    "    // 离屏/自动化验证：200ms 后自动退出（GUI 模式下不阻塞）\n"
+    "    // 仅在离屏自动化验证时（QT_QPA_PLATFORM=offscreen）200ms 后自动退出；\n"
-    "    QTimer::singleShot(200, &app, &QApplication::quit);\n"
+    "    // 正常运行（有显示环境）窗口保持打开，不自动退出。\n"
+    "    if (qgetenv(\"QT_QPA_PLATFORM\") == \"offscreen\") {\n"
+    "        QTimer::singleShot(200, &app, &QApplication::quit);\n"
+    "    }\n"
 )
 AUTO_QUIT_CORE = (
     "    QTimer::singleShot(0, &app, &QCoreApplication::quit);\n"
@@ -373,7 +377,7 @@ def header_comment(pid, idx, stem):
         f"//  原文片段：[{pid}:{idx}]\n"
         "//  说明：本文件由 gen_part3.py 从 wiki 片段生成（必要时补 main/QApplication\n"
         "//        外壳、include、修正笔误）。详见 docs/ERRATA.md。\n"
-        "//        离屏验证：QT_QPA_PLATFORM=offscreen tools/run_qt.sh <target>\n"
+        "//        离屏验证：QT_QPA_PLATFORM=offscreen tools/run_qt.sh <target>（自动退出）\n"
         "// ============================================================================\n\n"
     )