@hmos-library-adapter/fast 0.0.17-beta.1 → 0.0.17-beta.2

package/node_modules/@ohos-agent/pc-adapter/skills/pc-recipe-qt-app/references/qt5-cross-compile-hap.md

@@ -0,0 +1,252 @@
+# 鸿蒙PC-Qt5应用交叉编译与HAP打包
+
+## 概述
+
+Qt5 应用（如 NotepadNext）移植到鸿蒙 PC 的核心工作：**交叉编译 Qt5 应用为 ARM64 .so + 打包为 HAP**。使用 Qt 5.15.17 鸿蒙版 SDK。
+
+本文覆盖从 CMake 配置到 HAP 打包的完整链路。Qt6→Qt5 API 兼容性改动见 `qt5-api-compat.md`。
+
+## Qt 鸿蒙版本
+
+| 版本 | 分支 | 状态 |
+|------|------|------|
+| **Qt 5.15.17** | `tqtc/harmonyos-5.15.16`+ | **当前使用**：AUTOMOC 可用，API 完善，ETS 简化（3 个 NAPI 导出） |
+
+## 关键路径与工具
+
+| 路径变量 | 说明 | 典型值 |
+|----------|------|--------|
+| `QT_OHOS_DIR` | Qt 5.15.17 鸿蒙 SDK 安装目录 | `D:\install\Qt\...\Qt5.15.17_OHOS18_arm64-v8a_windows_...` |
+| `OHOS_NDK` | OHOS NDK 根目录 | `D:\Program Files\Huawei\DevEco Studio\sdk\default\openharmony\native` |
+| `TOOLCHAIN_FILE` | CMake 工具链文件 | `${OHOS_NDK}/build/cmake/ohos.toolchain.cmake` |
+
+## CMake 配置
+
+### 必需参数
+
+```bash
+cmake -S source -B build-ohos -G Ninja \
+  -DOHOS=1 \
+  -DCMAKE_TOOLCHAIN_FILE="${TOOLCHAIN_FILE}" \
+  -DCMAKE_PREFIX_PATH="${QT_OHOS_DIR}"
+cmake --build build-ohos --parallel
+```
+
+**必须用 `-G Ninja`**：默认 VS 生成器会忽略 OHOS 工具链，回退到 MSVC，产物是 x86 .dll 而非 ARM64 .so。
+
+### AUTOMOC/AUTORCC/AUTOUIC 保持 ON
+
+5.15.17 SDK 的 moc/rcc/uic 可以在 Windows 上原生运行，不需要任何额外配置：
+
+```cmake
+set(CMAKE_AUTOMOC ON)
+set(CMAKE_AUTORCC ON)
+set(CMAKE_AUTOUIC ON)
+```
+
+### 库类型：SHARED
+
+```cmake
+if(OHOS)
+  add_library(${PROJECT_NAME} SHARED ${SOURCES})
+else()
+  add_executable(${PROJECT_NAME} ${SOURCES})
+endif()
+```
+
+OHOS 应用以 .so 形式被 HAP 的 NAPI 桥接加载，不是独立可执行文件。
+
+### 不要链接平台插件
+
+```cmake
+# ❌ 错误：不要链接 QPA 平台插件
+# target_link_libraries(${PROJECT_NAME} Qt5::QOpenHarmonyPlatformIntegrationPlugin)
+
+# ✅ 正确：只链接 Qt 模块
+target_link_libraries(${PROJECT_NAME} Qt5::Core Qt5::Gui Qt5::Widgets)
+```
+
+原因：平台插件是运行时动态加载的。链接它会导致 `NEEDED: libplugins_platforms_qopenharmony.so` 写入 .so 的动态段，加载器在错误位置查找而失败。
+
+## QPA/NAPI 部署
+
+`libplugins_platforms_qopenharmony.so` 同时是 QPA 插件和 NAPI 模块。只需放在 `libs/arm64-v8a/` 顶层：
+
+```
+entry/libs/arm64-v8a/
+├── libplugins_platforms_qopenharmony.so  ← QPA + NAPI 统一
+├── libQt5Core.so
+├── libQt5OhExtras.so
+└── ...
+```
+
+XComponent 通过 `libraryname: 'plugins_platforms_qopenharmony'` 加载它。不需要 `platforms/` 子目录，不需要双路径部署。
+
+## HAP 打包（预构建 .so 方式）
+
+DevEco 的 `BuildNativeWithNinja` 对我们的 CMake 不工作（工具链冲突），采用**预构建 .so 方式**：
+
+### 步骤 1：禁用 externalNativeOptions
+
+`entry/build-profile.json5`：
+
+```json5
+{
+  "apiType": "stageMode",
+  "buildOption": {
+    // 不设 externalNativeOptions，禁用 DevEco 的 cmake 构建步骤
+  }
+}
+```
+
+### 步骤 2：CMake/Ninja 独立构建 .so
+
+```bash
+cd build-ohos
+cmake --build . --parallel
+```
+
+### 步骤 3：部署 .so 到 HAP 目录
+
+```
+entry/libs/arm64-v8a/
+├── lib<app>.so                            ← 应用主 .so（原文件名，不重命名）
+├── libplugins_platforms_qopenharmony.so  ← QPA+NAPI 统一插件
+├── libQt5Core.so                         ← Qt 运行时
+├── libQt5OhExtras.so                     ← Qt OHOS Extras
+└── ...                                   ← 其他 Qt 模块
+```
+
+使用 `qt5-ohos.py deploy --app_so build/lib<app>.so --hap_libs .../entry/libs/arm64-v8a/` 自动部署。脚本会：
+- 扫描 app .so 的 NEEDED 条目，复制最小 Qt .so 集
+- 复制 `libc++_shared.so`（从 NDK）
+- 复制 `libplugins_platforms_qopenharmony.so`（QPA+NAPI 插件）
+- 将 app .so 按原文件名复制到 hap_libs/（无需重命名为 libentry.so）
+
+`init` 时用 `--app_so_name lib<app>.so` 设置 `launchApplication` 值，QPA 会按此文件名 dlopen。
+
+### 步骤 4：ohpm install + 构建 HAP
+
+```bash
+cd harmony-app && ohpm install && cd entry && ohpm install
+cd harmony-app && hvigorw.bat --mode module -p module=entry@default -p product=default assembleHap
+```
+
+签名配置在 `build-profile.json5` 中（`qt5-ohos.py init` 自动检测 `~/.ohos/config/`）。
+
+### 步骤 5：部署到设备
+
+```bash
+hdc.exe install -r entry-default-signed.hap
+hdc.exe shell "hilog -b D"                      # 先提级别：商用机默认 W，应用 INFO 写入时即被丢
+hdc.exe shell "aa force-stop <bundle_name>"     # 必须冷启动，否则不重走 onCreate、不重打日志
+hdc.exe shell hilog -r
+hdc.exe shell aa start -a QAbility -b <bundle_name>
+```
+
+**⚠️ 启动后必须做存活检查 + 崩溃日志排查**（`aa start` 成功 ≠ 应用可用）：
+
+```bash
+# 等待初始化代码跑完
+sleep 5
+# 检查进程是否存活
+hdc.exe shell "ps -ef | grep <bundle_name> | grep -v grep"
+# 检查崩溃日志（按 pid 取，避免被系统日志挤出缓冲）
+hdc.exe shell "hilog -x -P <pid> | grep -iE 'SIGSEGV|SIGABRT|signal 11|signal 6|FAULT|cppcrash|stack-buffer-overflow'"
+```
+
+> 取证顺序（提级别 → 冷启动 → 清缓冲 → 拉起 → 按 pid 取）不能换，换了会拿到空日志并误读成
+> "应用没跑"。机制见 `pc-knowledge-base` 的 `platform/鸿蒙PC-hdc能力边界与取证通道.md`。
+
+两步都通过才可判定 `built-and-verified`。崩溃排查详见 `pc-device-verify` skill 的 `references/hap-verify.md`。
+
+## Qt5 应用 OHOS 特有源码改动
+
+### URL/文件打开
+
+```cpp
+#ifdef __OHOS__
+#include <qopenharmonyability.h>
+#include <qohappcontext.h>
+QOpenHarmonyWant want;
+want.uri = url.toString();       // 直接赋值成员，不是 setUri()
+QOpenHarmonyAbility::start(want);
+#endif
+```
+
+> **注意**：`QOpenHarmonyWant` 的 `uri` 是直接成员赋值（`want.uri = ...`），不是 `want.setUri()`。`setUri()` 在某些 SDK 版本中不存在。
+
+### closeEvent 与 Ability 生命周期
+
+OHOS 应用关闭走 Ability 生命周期，不需要 `getCloseEventRootCause()`，直接 accept：
+
+```cpp
+void MainWindow::closeEvent(QCloseEvent *event) {
+#ifdef __OHOS__
+    event->accept();
+#else
+    // 原平台逻辑
+#endif
+}
+```
+
+### QPlainTextEdit::appendPlainText 断言
+
+在 OHOS 上，`QPlainTextEdit::appendPlainText()` 在 widget 完全初始化前调用会触发 `Q_ASSERT` 导致 SIGABRT。修复：
+
+```cpp
+QMetaObject::invokeMethod(textEdit, [textEdit, text]() {
+    if (textEdit->isVisible()) {
+        textEdit->appendPlainText(text);
+    }
+}, Qt::QueuedConnection);
+```
+
+### showFullScreen 时机
+
+OHOS 上窗口初始化异步，直接 `showFullScreen()` 可能失败。延迟到事件循环：
+
+```cpp
+QMetaObject::invokeMethod(this, [this]() {
+    showFullScreen();
+}, Qt::QueuedConnection);
+```
+
+### 头文件路径小写
+
+OHOS Qt OhExtras 头文件全小写：
+
+```cpp
+// ✅ 正确
+#include <qopenharmonyability.h>
+#include <qohappcontext.h>
+#include <qohwidgethelper.h>
+
+// ❌ 错误（大小写不匹配）
+#include <QOpenHarmonyAbility>
+#include <QOhAppContext>
+```
+
+## 常见错误与排查
+
+| 错误 | 原因 | 解决 |
+|------|------|------|
+| `NEEDED: libplugins_platforms_qopenharmony.so` 导致加载失败 | 链接了平台插件 | 只链接 Qt5::Core/Gui/Widgets |
+| 白屏无窗口 | 缺 `pages/Index.ets` | QPA 硬编码 loadContent('pages/Index')，必须添加 |
+| 白屏无窗口 | `launchApplication` 未在 `onCreate()` 赋值 | 必须在 onCreate 中显式赋值，且值必须与 app .so 文件名一致 |
+| `Q_ASSERT` in appendPlainText | widget 未完全初始化 | 用 QueuedConnection 延迟 |
+| 白屏无窗口（替换 ADS 后） | 未调用 setCentralWidget | 替换 ADS 为 QTabWidget 后必须 setCentralWidget(tabWidget) |
+| CMake 产物是 x86 .dll | 用了 VS 生成器 | 必须用 `-G Ninja` |
+| `undefined reference to vtable` | 缺 moc 生成文件 | 确保所有 Q_OBJECT 都生成了 moc（AUTOMOC ON 应自动处理） |
+| Scintilla `std::optional` 未定义 | 未启用 C++17 | per-target `cxx_std_17` |
+| HAP 安装后崩溃 | 缺 .so 或签名不对 | 检查 libs/ 目录完整性 |
+| `dlopen("lib.so")` failure | `launchApplication` 为空 | 在 `onCreate()` 中显式赋值 |
+
+## 资源引用
+
+- Qt6→Qt5 API 兼容性改动 → `qt5-api-compat.md`
+- Qt6→Qt5 降级要点 → `qt6-to-qt5-downgrade.md`
+- Qt 工具链栈能力域 → `pc-capability-domains` qt-toolchain
+- 应用打包 recipe → `pc-recipe-qt-app` SKILL.md
+- 交叉编译骨干 → `pc-knowledge-base` SKILL.md
+- 错误图谱 → `pc-error-atlas`

package/node_modules/@ohos-agent/pc-adapter/skills/pc-recipe-qt-app/references/qt6-to-qt5-downgrade.md

@@ -0,0 +1,369 @@
+# 鸿蒙PC-Qt应用编译要点（Qt5/Qt6）
+
+## 概述
+
+Qt 应用（如 NotepadNext）使用 CMake + Qt 构建。本文覆盖**原平台（Windows/Linux）编译**和**鸿蒙适配**两条路线。鸿蒙适配时需切换到鸿蒙 Qt 工具链（见 `pc-recipe-qt-app` + `pc-capability-domains` qt-toolchain）。
+
+> 鸿蒙 Qt 的详细交叉编译步骤、HAP 打包流程、运行时问题处理见 `qt5-cross-compile-hap.md`。Qt6→Qt5 API 降级替换见 `qt5-api-compat.md`。
+
+## Windows 原平台编译
+
+### 前置依赖
+
+| 依赖 | 用途 | 安装方式 |
+|------|------|---------|
+| CMake ≥ 3.21 | 构建系统生成器 | `pip install cmake` |
+| Ninja | 构建执行器 | `pip install ninja` |
+| MinGW g++ ≥ 11 | C++ 编译器 | Qt Tools 或独立安装 |
+| Qt ≥ 6.5 | GUI 框架 | `pip install aqtinstall && aqt install-qt windows desktop 6.5.3 win64_mingw -m qt5compat -O <QT_DIR>` |
+| MinGW 工具链 | g++ 编译器（若 Qt 未自带） | `aqt install-tool windows desktop tools_mingw90 qt.tools.win64_mingw900 -O <QT_DIR>` |
+
+### 环境变量
+
+```cmd
+set PATH=<QT_DIR>\Tools\mingw1120_64\bin;<QT_DIR>\6.5.3\mingw_64\bin;<Python_Scripts>;%PATH%
+set CMAKE_PREFIX_PATH=<QT_DIR>\6.5.3\mingw_64
+```
+
+### 构建命令
+
+```cmd
+cmake -S source -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
+cmake --build build --parallel
+```
+
+### 分发打包
+
+```cmd
+cd build
+windeployqt --release NotepadNext.exe
+```
+
+## 鸿蒙 Qt 适配
+
+Qt 在鸿蒙 PC 上状态为 `available`（已移植，QPA 走鸿蒙窗口系统）。适配路线见 `pc-recipe-qt-app` skill + `pc-capability-domains` qt-toolchain 条目。
+
+### 鸿蒙 Qt 版本
+
+| 版本 | 推荐场景 | 详情 |
+|------|---------|------|
+| **Qt 5.15.17** | 所有 Qt5/Qt6 项目 | AUTOMOC 可用，API 更完善（大部分 Qt5.14+ API 原生支持），ETS 模板简化（3 个 NAPI 导出），QPA+NAPI 统一 .so |
+| Qt 6 | **尚无鸿蒙版**，需降级到 Qt 5.15.17 | 需 Qt6→Qt5 API 降级 |
+
+> Qt6 应用移植到鸿蒙 = Qt6→Qt5 降级 + Qt5→鸿蒙 适配，两层工作。
+
+### 关键差异（原平台 vs 鸿蒙）
+
+| 维度 | 原平台 | 鸿蒙 |
+|------|--------|------|
+| 编译器 | MinGW/MSVC/GCC | OHOS NDK clang |
+| 目标三元组 | x86_64 / aarch64 | `aarch64-unknown-linux-ohos` |
+| CMake toolchain | 无 | `ohos.toolchain.cmake` |
+| 生成器 | 默认即可 | **必须 `-G Ninja`** |
+| C++ 标准 | C++20 常见 | **C++17**（NDK clang 不完全支持 C++20） |
+| 产物形态 | .exe / .app | **SHARED .so**（NAPI 桥接加载） |
+| AUTOMOC | 自动（qt_standard_project_setup） | **手动开启**（set_target_properties AUTOMOC ON） |
+| QPA/NAPI | 自动加载 | 单一 `libplugins_platforms_qopenharmony.so` |
+| QDockWidget | 可用 | 不可用，三层降级：兼容头/隐藏/ADS→QTabWidget |
+| SingleApplication | 可用 | 不可用，替换为 QApplication + applicationStateChanged |
+| Qt Extras 模块 | — | `Qt5OhExtras`（QOpenHarmonyAbility 等） |
+| CPM 第三方依赖 | 全部编译 | **按需排除**（ads/QSimpleUpdater/SingleApplication/editorconfig 不编译） |
+| Scintilla/Lexilla | C++20 全局 | **per-target cxx_std_17** + LEXILLA_STATIC |
+| 翻译 | qt_add_translations | **跳过**（Qt5 LinguistTools 不兼容） |
+| 桌面打包 | CPack/NSIS/DMG | **排除**（用 HAP 打包代替） |
+
+### 适配流程概要
+
+1. **版本选择**：统一使用 Qt 5.15.17
+2. **API 降级**：Qt6→Qt5 的 API 替换（5.15 原生支持大部分 Qt5.14+ API，降级量较小）
+3. **CMake 交叉编译配置**：AUTOMOC ON，不需要手动 moc/rcc/uic
+4. **OHOS 特有源码改动**：QDockWidget 三层降级（兼容头/隐藏/ADS→QTabWidget）、appendPlainText 安全化、showFullScreen 延迟、closeEvent 适配、URL 打开改用 Qt5OhExtras 等
+5. **HAP 打包**：需 `pages/Index.ets` + `launchApplication` 赋值 + QPA+NAPI 统一 .so
+6. **设备验证**：hdc install + 冒烟测试
+
+### CMake 重构详解（NotepadNext 实战总结）
+
+Qt6 应用适配到 OHOS 时，CMake 修改不只是简单的 `Qt6→Qt5` 文本替换——需要**结构性重构**。以下每个都是编译必需项，缺少任何一个都会 build break。
+
+#### 1. 顶层 CMakeLists.txt
+
+```cmake
+# ---- C++ 标准 ----
+if(OHOS)
+    set(CMAKE_CXX_STANDARD 17)  # NDK clang 不完全支持 C++20
+elseif(MSVC)
+    # 原有 MSVC 选项
+endif()
+
+# ---- find_package 分支 ----
+if(OHOS)
+    find_package(Qt5 REQUIRED COMPONENTS Core Gui Widgets Network PrintSupport OhExtras)
+    # 注意：不链接 Core5Compat（Qt5 不需要），添加 OhExtras
+else()
+    find_package(Qt6 REQUIRED COMPONENTS Core Gui Widgets Network PrintSupport Core5Compat)
+endif()
+
+# ---- AUTOMOC ----
+set(CMAKE_AUTORCC ON)  # 全局的 AUTORCC 可以保留
+
+if(NOT OHOS)
+    qt_standard_project_setup()  # Qt6 CMake API，Qt5 不可用
+endif()
+# 注意：qt_standard_project_setup() 内部会开启 AUTOMOC/AUTOUIC
+# 移除后必须在 target 上手动开启（见 src/CMakeLists.txt）
+
+# ---- 桌面打包排除 ----
+if(NOT OHOS)
+    include(${CMAKE_SOURCE_DIR}/cmake/Packaging.cmake)
+endif()
+```
+
+#### 2. src/CMakeLists.txt
+
+**关键：add_executable → add_library SHARED + 源文件排除 + 手动 AUTOMOC**
+
+```cmake
+# 将源文件列表提取为变量，而非直接写在 qt_add_executable 中
+set(APP_SOURCES
+    ActionUtils.h
+    MainWindow.cpp
+    # ... 所有源文件 ...
+)
+
+if(OHOS)
+    # 排除 OHOS 不可用的源文件
+    list(REMOVE_ITEM APP_SOURCES
+        "DockedEditor.cpp"              # ADS 依赖，用 DockedEditorOhos.cpp 替代
+        "decorators/EditorConfigAppDecorator.cpp"
+        "decorators/EditorConfigAppDecorator.h"
+        "DockedEditorTitleBar.h"
+    )
+
+    # OHOS：编译为 SHARED 库（NAPI 桥接加载）
+    add_library(NotepadNext SHARED ${APP_SOURCES})
+
+    # 添加 OHOS 替代源
+    target_sources(NotepadNext PRIVATE DockedEditorOhos.cpp)
+
+    # 手动开启 AUTOMOC/AUTOUIC/AUTORCC（qt_standard_project_setup 被移除后必须）
+    set_target_properties(NotepadNext PROPERTIES
+        AUTOMOC ON
+        AUTOUIC ON
+        AUTORCC ON
+    )
+else()
+    qt_add_executable(NotepadNext
+        WIN32
+        MACOSX_BUNDLE
+        ${APP_SOURCES}
+    )
+endif()
+
+# ---- 翻译 ----
+if(NOT OHOS)
+    find_package(Qt6 REQUIRED COMPONENTS LinguistTools)
+    qt_add_translations(NotepadNext TS_FILES ${TS_FILES} RESOURCE_PREFIX "/i18n")
+else()
+    # Qt5 LinguistTools 不兼容，跳过翻译
+endif()
+
+# ---- Windows 资源文件守卫 ----
+if(WIN32 AND NOT OHOS)  # 注意：WIN32 在 Windows 交叉编译 OHOS 时也为 TRUE！
+    configure_file("${CMAKE_SOURCE_DIR}/deploy/windows/version.rc.in"
+                   "${CMAKE_BINARY_DIR}/version.rc" @ONLY)
+    target_sources(NotepadNext PRIVATE "${CMAKE_BINARY_DIR}/version.rc")
+endif()
+
+# ---- 链接 ----
+if(OHOS)
+    target_link_libraries(NotepadNext
+        PRIVATE
+            Qt5::Core Qt5::Gui Qt5::Widgets Qt5::Network Qt5::PrintSupport Qt5::OhExtras
+            lua lexilla scintilla uchardet
+            # 注意：不链接 qtadvanceddocking-qt6, QSimpleUpdater,
+            #       SingleApplication, editorconfig-core-qt
+    )
+    target_compile_definitions(NotepadNext PRIVATE __OHOS__ LEXILLA_STATIC)
+else()
+    target_link_libraries(NotepadNext
+        PRIVATE
+            Qt6::Core Qt6::Gui Qt6::Widgets Qt6::Network Qt6::PrintSupport
+            qtadvanceddocking-qt6 QSimpleUpdater SingleApplication::SingleApplication
+            editorconfig-core-qt lua lexilla scintilla uchardet
+    )
+endif()
+```
+
+#### 3. thirdparty/CMakeLists.txt
+
+**CPM 依赖整体排除**
+
+```cmake
+include(${CMAKE_SOURCE_DIR}/cmake/CPM.cmake)
+
+if(NOT OHOS)
+    # OHOS: 不编译 ads/QSimpleUpdater/SingleApplication/editorconfig-core-qt
+    CPMAddPackage(NAME ads ...)
+    CPMAddPackage(NAME QSimpleUpdater ...)
+    CPMAddPackage(NAME SingleApplication ...)
+    CPMAddPackage(NAME editorconfig_core_qt ...)
+endif()
+
+# 以下依赖保留（纯 C/C++，无 Qt 依赖或可交叉编译）
+add_subdirectory(lua)
+add_subdirectory(scintilla)
+add_subdirectory(uchardet)
+```
+
+#### 4. thirdparty/scintilla/CMakeLists.txt
+
+**第三方库（Third-party）自己的 find_package(Qt6) 也需要分支**
+
+```cmake
+if(OHOS)
+    find_package(Qt5 COMPONENTS Core Widgets REQUIRED)
+    target_link_libraries(scintilla PUBLIC Qt5::Core Qt5::Widgets)
+    target_compile_features(scintilla PUBLIC cxx_std_17)  # per-target C++17
+    set_target_properties(scintilla PROPERTIES AUTOMOC ON)  # Q_OBJECT in ScintillaEdit
+else()
+    find_package(Qt6 COMPONENTS Core Widgets Core5Compat REQUIRED)
+    target_link_libraries(scintilla PUBLIC Qt6::Core Qt6::Widgets Qt6::Core5Compat)
+endif()
+```
+
+#### 5. thirdparty/lexilla/CMakeLists.txt
+
+**LEXILLA_STATIC + per-target C++17**
+
+```cmake
+if(OHOS)
+    target_compile_definitions(lexilla PUBLIC LEXILLA_STATIC)  # 避免运行时 dlopen
+    target_compile_features(lexilla PUBLIC cxx_std_17)
+elseif(UNIX)
+    target_link_libraries(lexilla PUBLIC dl)
+endif()
+```
+
+#### CMake 修改清单速查
+
+| 修改项 | 严重度 | 影响 |
+|--------|--------|------|
+| `add_library(SHARED)` 替代 `add_executable` | build-blocker | 不改则链接失败 |
+| `CMAKE_CXX_STANDARD 17` | build-blocker | 不改则 C++20 特性编译失败 |
+| `find_package(Qt5 ... OhExtras)` | build-blocker | 不加 OhExtras 则 QOpenHarmonyAbility 链接失败 |
+| `qt_standard_project_setup()` 守卫 + 手动 AUTOMOC | build-blocker | 不开 AUTOMOC 则 Q_OBJECT vtable 缺失 |
+| CPM 依赖排除 | build-blocker | 不排除则 ads/SingleApplication 编译失败 |
+| `LEXILLA_STATIC` | build-blocker | 不加则运行时 dlopen 失败 |
+| `Packaging.cmake` 排除 | build-blocker | CPack 在 OHOS 工具链下报错 |
+| `qt_add_translations` 排除 | build-blocker | Qt5 无此 API |
+| `WIN32 AND NOT OHOS` | build-blocker | 否则 .rc 文件被包含进 OHOS 构建 |
+| 第三方 CMakeLists 分支 | build-blocker | scintilla 等的 find_package(Qt6) 也会失败 |
+| per-target `cxx_std_17` | build-blocker | Scintilla 用 std::optional 等 C++17 特性 |
+
+### 源码改动详解（NotepadNext 实战总结）
+
+CMake 重构之后，源码层也需要大量改动。以下按类别组织，与 `scripts/qt6-to-qt5-downgrade-patterns.json` (v4.0.0) 的 46 个 symbol 一一对应。每个 symbol 指向 `scripts/fixes/` 下的 fix doc（详细的多策略代码模板），此处仅列出清单。详细的代码模板见 `qt5-api-compat.md` 和各 fix doc。
+
+#### 1. Qt6→Qt5 API 降级（build-blocker）
+
+这些是编译直接报错的类型/常量/API 不兼容：
+
+| Pattern | 改动 | 示例 |
+|---------|------|------|
+| 01 | `QLatin1StringView` → `QLatin1String` | 全局替换 |
+| 39 | `constexpr QLatin1StringView` → `const QLatin1String` | constexpr 在 Qt5 的 QLatin1String 上可能不支持 |
+| 02 | `QByteArrayView` 不存在于 Qt5 | 自定义类 或 typedef `QVector<QByteArray>` 替代 |
+| 15 | `[=, this]` → `[=]` | Qt5 的 `[=]` 隐式捕获 this；**仅在 OHOS 代码路径中改**，否则破坏 C++20 构建 |
+| 05 | `QDataStream << enum` 需 cast | `stream << static_cast<qint32>(myEnum)` |
+| 06 | `QCalendar` 不在 5.15 OHOS SDK | 条件编译移除 |
+| 07 | `QStyleOptionTabV4` 不在 5.15 OHOS SDK | 降级为 `QStyleOptionTabV3` |
+
+#### 2. ADS（Advanced Docking System）API 降级（build-blocker）
+
+ADS 在 OHOS 构建中被整体排除（CPM 守卫），其 API 也随之消失：
+
+| Pattern | 改动 | 示例 |
+|---------|------|------|
+| 20 | `dockWidgetsCount()` → `count()` | Qt6 ADS 用 `dockWidgetsCount()`，Qt5 ADS / QTabWidget 用 `count()` |
+| 21 | `dockWidget(i)->widget()` → `widget(i)` | Qt6 ADS 两步取 widget，Qt5 ADS / QTabWidget 一步 |
+
+#### 3. QDockWidget 三层降级（ohos-only）
+
+**不能简单替换为 QTabWidget**——需按场景分三层处理：
+
+| Layer | Pattern | 场景 | 改动 |
+|-------|---------|------|------|
+| 1 | 42 | Dock 面板类继承 QDockWidget | `#include <QDockWidget>` → `#include "QDockWidgetOhos.h"`（编译期存根） |
+| 2 | 40 | `addDockWidget()` 放置面板 | `addDockWidget(area, dock)` → `dock->hide()`（OHOS 无 dock area） |
+| 3 | 09, 47 | 中央编辑区用 ADS | 替换为 `DockedEditorOhos`（QTabWidget 方案）+ `setCentralWidget(tabWidget)`（Pattern 41） |
+
+#### 4. SingleApplication → QApplication 降级
+
+混合严重度：不替换则编译失败（build-blocker），替换后需处理运行时行为（ohos-only）：
+
+| Pattern | 改动 | 示例 |
+|---------|------|------|
+| 10 | 继承 `SingleApplication` → 继承 `QApplication` | `class App : public QApplication` |
+| 49 | `SingleApplication::instanceStarted` → `applicationStateChanged` | `connect(this, &QApplication::applicationStateChanged, [&](Qt::ApplicationState s) { if (s == Qt::ApplicationActive) ... })` |
+| 48 | `isRunningAsAdmin()` 等 Windows-only 方法 | 存根 `return false;` |
+| — | `sendInfoToPrimaryInstance()` | `#ifndef __OHOS__` 整体守卫 |
+| — | `main()` 中 `isPrimary()/isSecondary()` | OHOS 下始终 `app.init(); return app.exec();` |
+
+#### 5. OHOS 平台 API 替换
+
+混合严重度：`QFileOpenEvent` 处理块如果内含 SingleApplication API 调用则编译失败（build-blocker，Pattern 45）；其余为 ohos-only：
+
+| Pattern | 改动 | 示例 |
+|---------|------|------|
+| 13, 38 | `QDesktopServices::openUrl` → `QOpenHarmonyAbility::start` | `QOpenHarmonyWant want; want.uri = url.toString(); QOpenHarmonyAbility::start(want);` 注意：用 `want.uri =`，不是 `want.setUri()` |
+| 11, 45 | `QFileOpenEvent` 整体守卫 | `#ifndef __OHOS__` 包裹整个处理块 |
+| 12 | `QSystemTrayIcon` 守卫 | `#ifndef __OHOS__` |
+| 26 | `EditorConfigAppDecorator` 移除 | `#ifndef __OHOS__` + CMake 排除源文件 |
+| 08 | `QFile::moveToTrash` → `QFile::remove` | OHOS 上行为不确定，用 `#ifdef __OHOS__` |
+
+#### 6. 生命周期/窗口适配（ohos-only）
+
+| Pattern | 改动 | 示例 |
+|---------|------|------|
+| 22 | `closeEvent` 适配 Ability 生命周期 | `#ifdef __OHOS__ event->accept(); #else ... #endif` |
+| 23 | `showFullScreen()` 延迟 | `QMetaObject::invokeMethod(this, [this]() { showFullScreen(); }, Qt::QueuedConnection);` |
+| 27 | `QFontDatabase::addApplicationFont` 内嵌字体 | 将 .ttf 放入 .qrc，OHOS 系统字体可能不含 monospace |
+| 25, 37 | `QShortcut` 5 参数构造拆分 | `new QShortcut(key, parent) + setContext() + connect()` |
+
+#### 7. 运行时兼容性（runtime）
+
+这些编译通过但可能运行时异常：
+
+| Pattern | 改动 | 说明 |
+|---------|------|------|
+| 14 | Qt6 scoped enum 回退 | `QEvent::Type::Foo` → `QEvent::Foo` |
+| 16 | `QVector` vs `QList` | Qt5 中是两个不同的类，注意 API 差异 |
+| 19 | `QButtonGroup::idClicked` | 5.15 支持，旧版 Qt5 需 `QOverload<int>::of(&QButtonGroup::buttonClicked)` |
+| 24 | `screen()->availableGeometry()` | 5.14+ 支持，更旧版本需 `QApplication::desktop()->availableGeometry()` |
+| 28 | `appendPlainText` 线程安全 | 非 GUI 线程调用需 `QMetaObject::invokeMethod + QueuedConnection` |
+
+#### 源码改动清单速查
+
+> 仅列源码层改动。CMake 层改动见上方「CMake 修改清单速查」（Pattern 03/04/17/18/29–36/43/44/46/50）。
+
+| 改动项 | 严重度 | Pattern |
+|--------|--------|---------|
+| `QLatin1StringView` → `QLatin1String` | build-blocker | 01 |
+| `constexpr QLatin1StringView` → `const QLatin1String` | build-blocker | 39 |
+| `QByteArrayView` 自定义/替代 | build-blocker | 02 |
+| `[=, this]` → `[=]` | build-blocker | 15 |
+| `QDataStream << enum` cast | build-blocker | 05 |
+| `QCalendar` / `QStyleOptionTabV4` 移除 | build-blocker | 06, 07 |
+| ADS API `dockWidgetsCount→count` / `dockWidget(i)->widget→widget(i)` | build-blocker | 20, 21 |
+| QDockWidget 三层降级 | ohos-only | 09, 40, 41, 42, 47 |
+| SingleApplication → QApplication | build-blocker / ohos-only | 10, 48, 49 |
+| `QDesktopServices` → `QOpenHarmonyAbility` | ohos-only | 13, 38 |
+| `QFileOpenEvent` / `QSystemTrayIcon` 守卫 | build-blocker / ohos-only | 11, 12, 45 |
+| `EditorConfigAppDecorator` 移除 | ohos-only | 26 |
+| `moveToTrash` → `remove` | ohos-only | 08 |
+| `closeEvent` / `showFullScreen` 适配 | ohos-only | 22, 23 |
+| `QShortcut` 构造拆分 | build-blocker | 25, 37 |
+| `QFontDatabase::addApplicationFont` 内嵌字体 | ohos-only | 27 |
+| `appendPlainText` 线程安全 | runtime | 28 |
+| Qt6 scoped enum 回退 | runtime | 14 |
+| `QVector` / `QList` 差异 | runtime | 16 |

package/node_modules/@ohos-agent/pc-adapter/skills/pc-recipe-qt-app/references/subagent-prompt-template.md

@@ -0,0 +1,69 @@
+# Subagent Prompt 模板（参考文档）
+
+> **注意**：本模板已内化到 `qt5-compat-fixer` agent 定义中（`agents/qt5-compat-fixer.md` Step 3）。
+> `qt5-compat-fixer` 在运行时自动按此模板构造每个 topic 的子 agent prompt。
+> 本文件仅作参考，不再由 pc-03-dev-adapt-code 或 SKILL.md 在运行时读取。
+
+按 topic 分派 subagent 时，`qt5-compat-fixer` 使用以下模板构造 prompt。`<SOURCE_DIR>`、`<fix_doc_abs_path>` 和 `<detail_file>` 由编排器从 compat-report.json 动态填入。
+
+```
+You are fixing Qt6→Qt5 + OHOS compatibility issues for ONE specific topic.
+You MUST follow the fix doc exactly. Do NOT improvise.
+
+## ABSOLUTE REQUIREMENTS (violating any = task failure)
+
+1. **READ THE FIX DOC FIRST** — Use the Read tool on the fix_doc path below
+   BEFORE making any edits. You MUST understand the Strategy selection logic
+   before touching any file. If you edit a file without reading the fix doc
+   first, your changes will be WRONG and will be discarded.
+
+2. **NEVER delete or replace Qt6 code** — Always wrap with #ifdef/__OHOS__
+   guards so the original Qt6 build still works:
+   - Qt6 code goes in the #else / non-OHOS branch
+   - Qt5/OHOS code goes in the #ifdef __OHOS__ / if(OHOS) branch
+   - Exception: CMake if(OHOS)/else()/endif() — Qt5 in if(OHOS), Qt6 in else()
+
+3. **FOLLOW the fix doc's Context Decision** — The fix doc has a Decision table
+   mapping code context → Strategy. You MUST pick the Strategy that matches the
+   finding's actual context. Do NOT apply Strategy A when the context calls for
+   Strategy B.
+
+4. **CHECK the Common Mistakes section** in the fix doc — it lists specific
+   wrong approaches that seem correct but break the build. Avoid ALL of them.
+
+5. **After editing**, re-read the modified file to verify your edit is correct.
+   List every file you modified with a one-line summary of what you changed.
+
+## Source Directory
+<source_dir>
+
+## Fix Doc (MUST READ WITH Read TOOL BEFORE ANY EDITS)
+<fix_doc_abs_path>
+
+## Findings to Fix
+<该 topic 的 findings 数组，JSON 格式>
+
+## Guard Format Reference
+
+C++ files:
+  #ifdef __OHOS__
+      // Qt5 / OHOS-specific code here
+  #else
+      // Original Qt6 code preserved here
+  #endif
+
+CMake files:
+  if(OHOS)
+      # Qt5 / OHOS-specific code here
+  else()
+      # Original Qt6 code preserved here
+  endif()
+
+## What NOT to do (Common Mistakes from past failures)
+- Do NOT replace QDockWidget with QTabWidget — use the compat header approach
+- Do NOT remove Qt6 code — always guard it, never delete it
+- Do NOT assume QDockWidgetOhos.h exists in the SDK — you MUST create it
+- Do NOT use QOpenHarmonyWant.setUri() — use direct member: want.uri = ...
+- Do NOT add #include <QtDebug> — use #include <QDebug>
+- Do NOT remove constexpr from non-OHOS branches — only remove in #ifdef __OHOS__
+```