Skip to content

Commit eeed994

Browse files
SWangHashSWangHash
SWangHash
authored and
SWangHash
committed
!120 merge qt-migrate into main
feat(qt-migrate)QT工程迁移鸿蒙功能 Created-by: themoonlzs Commit-by: lzs Merged-by: SWangHash Description: ## Summary 新增 Qt 工程迁移到 HarmonyOS/OpenHarmony 的垂直能力： - 新增 `QtMigration` 专家模式（QT Migration Expert），并内置 `ohos-qt-skills` 领域知识技能作为唯一事实源； - 后端对用户请求做完整的 Qt→HarmonyOS 迁移意图识别，只有同时满足 Qt 语境、迁移动作、鸿蒙目标才进入迁移流程； - 引入会话级 intake 状态机，约束四项最小输入（原始工程 / 输出工程 / 工具链 / 模板工程）必须绑定后才放行迁移副作用； - 新增后端模板化的路径收集问题卡片，候选路径由后端探测、过滤、排序，模型无法改写问题内容； - 增加统一工具执行边界的副作用门禁：输入未完备或技能未加载时拒绝迁移类工具，普通会话零开销。 Fixes # ## Type and Areas Type: Feature Areas: - Rust core（agent-runtime、assembly/core） - web UI - 内置技能资源（assembly/core/builtin_skills） - 测试（Rust 契约测试 + 前端组件测试） ## Motivation / Impact - 提供开箱即用的 Qt→HarmonyOS 迁移能力，模型不再自创迁移流程，关键规则由后端固定拥有； - 迁移前强制确认四项输入，避免在输入缺失时误执行写文件、构建、部署等迁移副作用； - 迁移领域知识以内置技能为准一来源，不混入代码或提示词； - 对用户可见的变化：新增 QT 迁移专家模式、迁移前的路径确认问题卡片、卡片路径选项自动探测与校验。 ## Verification - `cargo check -p bitfun-core --no-default-features --features product-full` - `cargo check -p bitfun-desktop` - `pnpm run type-check:web` - `pnpm --dir src/web-ui run test:run src/flow_chat/tool-cards/AskUserQuestionCard.test.tsx` - `pnpm run fmt:rs` - Rust 契约/单元测试覆盖：intake 状态机、问题模板、候选探测（qt_migration_candidates） 说明：OHOS 交叉编译与 HAP 打包在 WSL 环境单独验证，不属于本 MR 的构建链范围。 ## Reviewer Notes - 副作用门禁挂在统一工具执行边界（`qt_migration_gate`），仅在 QtMigration 会话且 intake 已激活时生效； - intake 快照带 schema 版本，保持旧数据可反序列化； - 远程工作区场景跳过本地路径存在性校验，路径正确性交由模型与技能侧判断； - 内置 `ohos-qt-skills` 为领域知识文件，非业务代码。 ## Checklist - [ ] This PR is focused and does not include secrets, temporary prompts, generated scratch files, or unrelated artifacts. - [ ] Relevant verification is recorded above, or skipped checks are explained. - [ ] User-facing strings, docs, and locales are updated where applicable. See merge request: OpenHarmonyPCDeveloper/BitFun!120
2 parents 9540c8b + 9b712fa commit eeed994

215 files changed

Lines changed: 31444 additions & 116 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎src/apps/desktop/src/api/agentic_api.rs‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4483,6 +4483,7 @@ mod tests {
44834483
id: format!("call-{}", tool_name),
44844484
input: json!({}),
44854485
},
4486+
question_request: None,
44864487
tool_result: Some(ToolResultData {
44874488
result,
44884489
success: true,

‎src/crates/assembly/agent-content/prompts/agents/qt_migration_agent.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
You are the QT Migration Expert, a specialized agent in BitFun that can migrate Qt projects to HarmonyOS / OpenHarmony. Migration behavior is conditional: only follow the migration-specific instructions when the runtime has classified the current request as a complete Qt-to-HarmonyOS migration. Otherwise, handle the request as a normal agentic request and do not load `ohos-qt-skills`, verify migration inputs, or call the `qt-migration-paths` template.
2+
3+
{LANGUAGE_PREFERENCE}
4+
5+
## When migration behavior is enabled
6+
7+
When the runtime classification confirms a Qt project migration to HarmonyOS/OpenHarmony, the migration domain flow lives exclusively in the versioned `ohos-qt-skills` knowledge base, which you MUST load before migration work. A Qt question, a generic migration request, or a request without a HarmonyOS/OpenHarmony target is not sufficient to enable this behavior.
8+
9+
## Required skill
10+
11+
Only after the runtime has confirmed a complete Qt-to-HarmonyOS migration, and before starting each migration task (assessment, source migration, build, deploy, verification), you MUST call the `Skill` tool to load `ohos-qt-skills` and follow its current versioned flow. A prior load from an earlier migration in the same Session does not satisfy this requirement. The skill is the single source of truth for the domain flow. Do not reinvent, summarize, or replace it.
12+
13+
## Precondition gate
14+
15+
The migration-specific precondition gate applies only to requests confirmed by the runtime as Qt-to-HarmonyOS migrations. For those requests, do not produce migration side effects until the runtime intake and skill requirements are satisfied. For all other requests, follow the normal agentic flow without migration input collection or migration skill loading.
16+
17+
When the runtime signals missing migration inputs, call `AskUserQuestion` with the backend `templateId` "qt-migration-paths". If the skill is missing or unusable, stop and surface the recovery action instead of proceeding.
18+
19+
## Input verification
20+
21+
For a request confirmed by the runtime as a Qt-to-HarmonyOS migration, verify inputs using the read-only workflow supplied by the runtime and the skill. Do not independently start migration input collection for other requests.
22+
23+
## Final response
24+
25+
For an enabled migration task, report migration evidence: which files were changed, the build outcome, the deploy target and status, the verification results and any remaining issues. Keep the response concise, concrete, and free of emojis.

‎src/crates/assembly/agent-content/tests/prompt_catalog_contracts.rs‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -93,6 +93,10 @@ const CATALOG_PROMPT_SOURCES: &[(&str, &[u8])] = &[
9393
"plan_mode_ongoing_reminder",
9494
include_bytes!("../prompts/agents/plan_mode_ongoing_reminder.md"),
9595
),
96+
(
97+
"qt_migration_agent",
98+
include_bytes!("../prompts/agents/qt_migration_agent.md"),
99+
),
96100
(
97101
"research_specialist_agent",
98102
include_bytes!("../prompts/agents/research_specialist_agent.md"),

‎src/crates/assembly/core/builtin_skills/ohos-qt-skills/ENV.md‎

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
# 环境变量与本地路径清单（开发者版）
2+
3+
> **使用方式**：运行 `skills/kb-init/` 初始化 skill 会自动生成 `ENV.local.md`，或手动把下表的 `<PLACEHOLDER_*>` 替换为你本机的实际路径后再参考。
4+
> 知识页中以变量名引用路径，便于你按自身环境替换。
5+
>
6+
> 这是开发者版裁剪后的模板——已移除原版的供应链交付目录（与外部开发者无关），仅保留移植所需的路径变量。
7+
8+
---
9+
10+
## 🔧 Qt 源码路径
11+
12+
> QtOhosExtras 模块（`qtohosextras/`）是 Qt 源码树内的子目录，不是独立仓库。
13+
14+
### 源码获取渠道
15+
16+
根据是否有 Qt 商业 license，选择不同的获取路径：
17+
18+
| 场景 | 获取方式 | 说明 |
19+
|------|----------|------|
20+
| **有 Qt 商业 license** | `git clone https://codereview.qt-project.org/qt/tqtc-qt5` | 需要 Qt 商业 license，可获取最新补丁和完整历史 |
21+
| **无 license（开源）** | GitCode 公开仓提供的开源代码 | 由 OpenHarmonyPCDeveloper 组织维护，提供开源代码和预编译产物 |
22+
| **只需预编译 SDK** | GitCode 公开仓提供的预编译产物 | 适合不需要修改 Qt 源码的应用开发者 |
23+
24+
**开源获取步骤**（无 license 场景）：
25+
1. 克隆源码：`git clone https://gitcode.com/ohos-qt/qt-harmonyos-src <目标路径>`
26+
2. 切分支：`cd <目标路径> && git checkout tqtc/harmonyos-5.12.12`（或 `tqtc/harmonyos-5.15.16`）
27+
28+
**预编译 SDK 获取**（只需预编译 SDK 场景）：
29+
30+
访问发布页面下载：https://gitcode.com/ohos-qt/qt-harmonyos-src/releases
31+
32+
| 平台 | 渲染后端 | 说明 |
33+
|------|----------|------|
34+
| Windows | Desktop GL | Windows 平台开发，Desktop GL 渲染 |
35+
| Windows | GLES | Windows 平台开发，GLES 渲染 |
36+
| macOS | Desktop GL | macOS 平台开发，Desktop GL 渲染 |
37+
| macOS | GLES | macOS 平台开发，GLES 渲染 |
38+
| HarmonyOS | GLES | HarmonyOS 设备上运行，GLES 渲染 |
39+
40+
**商业获取步骤**（有 license 场景）：
41+
1. 访问 https://codereview.qt-project.org 登录
42+
2. Settings → HTTP Credentials → GENERATE NEW PASSWORD
43+
3. `git clone https://codereview.qt-project.org/qt/tqtc-qt5`
44+
4. 切分支：`git checkout tqtc/harmonyos-5.12.12` 或 `tqtc/harmonyos-5.15.16`
45+
5. `git submodule update --init --recursive`
46+
47+
### 路径变量
48+
49+
| 变量名 | 你的值 | 说明 |
50+
|--------|--------|------|
51+
| `QT5_12_SRC` | `<QT5_12_SRC_PATH>` | Qt 5.12.x LTS 鸿蒙主力分支源码（tqtc/harmonyos-5.12.12） |
52+
| `QT5_15_SRC` | `<QT5_15_SRC_PATH>` | Qt 5.15.x 鸿蒙适配分支源码（tqtc/harmonyos-5.15.16） |
53+
| `QT6_DEV_SRC` | `<QT6_DEV_SRC_PATH>` | Qt 6 dev 主干源码（鸿蒙化进行中，仅 qtbase） |
54+
55+
## 📦 编译产物与 SDK
56+
57+
| 变量名 | 你的值 | 说明 |
58+
|--------|--------|------|
59+
| `QT_BUILD_ROOT` | `<QT_BUILD_ROOT_PATH>` | Qt 编译输出根目录 |
60+
| `QT5_12_OHOS_SDK` | `<QT5_12_OHOS_SDK_PATH>` | CMake `CMAKE_PREFIX_PATH`（Qt 5.12 默认） |
61+
| `QT5_15_OHOS_SDK` | `<QT5_15_OHOS_SDK_PATH>` | CMake `CMAKE_PREFIX_PATH`（Qt 5.15） |
62+
63+
## 📚 内嵌的 HarmonyOS 平台通用知识
64+
65+
本知识库内嵌了 `ohos-common-kb-public/` 目录，包含 HarmonyOS 平台通用知识（ArkTS、ArkUI、NAPI、Stage 模型、DevEco 工具链等）。当任务涉及平台机制而非 Qt 特定问题时，优先查阅该目录。
66+
67+
| 变量名 | 你的值 | 说明 |
68+
|--------|--------|------|
69+
| `OHOS_COMMON_KB_PUBLIC` | `ohos-common-kb-public/` | 内嵌的 HarmonyOS 平台通用知识库（相对路径） |
70+
71+
## 📋 模板
72+
73+
| 变量名 | 你的值 | 说明 |
74+
|--------|--------|------|
75+
| `OHOS_TEMPLATE_SRC` | `<QT_SRC>/qtbase/src/harmonyos/templates` | ★ 推荐：Qt 源码内置胶水模板（5.15 / 5.12 源码树内均有） |
76+
77+
> 新版 Qt 鸿蒙分支已将胶水模板内置于 `qtbase/src/harmonyos/templates`，无需再从外部下载 ZIP。
78+
79+
## 🔨 构建工具链
80+
81+
| 变量名 | 你的值 | 说明 |
82+
|--------|--------|------|
83+
| `MINGW_ROOT` | `<MINGW_ROOT_PATH>` | MinGW 工具链（含 mingw32-make，Windows 编译 Qt 用） |
84+
| `PERL_ROOT` | `<PERL_ROOT_PATH>` | Strawberry Perl 安装路径（Qt 构建系统依赖） |
85+
| `OHOS_SDK_NATIVE` | `<DEVECO>/sdk/default/openharmony/native` | OHOS SDK native 工具链（clang/clang++） |
86+
87+
### 编译命令
88+
89+
```powershell
90+
# Qt 5.12.x OHOS 编译安装（必须在 PowerShell 中执行，不要在 bash/git-bash 中运行）
91+
cd <QT_BUILD_ROOT_PATH>
92+
mingw32-make.exe -j64 install
93+
```
94+
95+
> **⚠️ 必须在 PowerShell 中执行**——mingw32-make 内部调用 `/usr/bin/sh` 会导致反斜杠路径被吞掉。
96+
97+
### Windows 构建环境变量
98+
99+
```bat
100+
SET NATIVE_OHOS_SDK=<DEVECO>/sdk/default/openharmony/native
101+
SET OHOS_SDK_SYSROOT=%NATIVE_OHOS_SDK%/sysroot
102+
SET LLVM_INSTALL_DIR=%NATIVE_OHOS_SDK%/llvm
103+
SET QT5_ROOT_DIR=<QT5_12_SRC_PATH>
104+
```
105+
106+
## 🖥️ IDE 与工具路径
107+
108+
| 变量名 | 你的值 | 说明 |
109+
|--------|--------|------|
110+
| `DEVECO_PATH` | `<DEVECO_PATH>` | DevEco Studio 安装路径 |
111+
112+
### MCP 配置文件位置
113+
114+
| IDE | 配置文件路径 |
115+
|-----|------------|
116+
| Trae CN / 国际版 | `<项目根>/.trae/mcp.json` |
117+
| Cursor | `<项目根>/.cursor/mcp.json` |
118+
| VS Code | `<项目根>/.vscode/mcp.json` |
119+
| Claude Desktop (Windows) | `%APPDATA%/Claude/claude_desktop_config.json` |
120+
| Claude Desktop (macOS) | `~/Library/Application Support/Claude/claude_desktop_config.json` |
121+
| Gemini CLI | `~/.gemini/settings.json` |
122+
| OpenCode | `<项目根>/.opencode/config.json` |
123+
124+
## 📌 Qt 框架版本（校验基准）
125+
126+
| 版本 | 分支 | Commit | 日期 |
127+
|------|------|--------|------|
128+
| Qt 5.15.16 | tqtc/harmonyos-5.15.16 | 962aa625 | 2026-04-19 |
129+
| Qt 5.12.12 | tqtc/harmonyos-5.12.12 | 613336de | 2026-05-25 |

‎src/crates/assembly/core/builtin_skills/ohos-qt-skills/LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 OpenHarmony PC Developer
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎src/crates/assembly/core/builtin_skills/ohos-qt-skills/SKILL.md‎

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
---
2+
name: ohos-qt-skills
3+
description: Use when users need to compile, build, port, or debug Qt/Qt5/Qt6 applications for HarmonyOS/OpenHarmony/鸿蒙. Use when users mention Qt + HarmonyOS together, ask about Qt API replacement on HarmonyOS, encounter Qt HarmonyOS build errors (CMake find_package fails, dlopen failed, hvigor errors), Qt window/lifecycle issues on HarmonyOS, QtOhosExtras usage, Qt platform limits on HarmonyOS, third-party library cross-compilation for OHOS, or Qt project structure for HarmonyOS.
4+
---
5+
6+
# Qt for HarmonyOS Development
7+
8+
## Overview
9+
10+
**Qt for HarmonyOS 移植参考知识库** — a comprehensive reference for Qt application porting, building, debugging, and deployment on HarmonyOS/OpenHarmony.
11+
12+
This SKILL.md and all knowledge base files below are a **self-contained skill package**. The directory layout:
13+
14+
```
15+
SKILL.md -> This file (skill entry point)
16+
_index/ -> 索引层：_map, _tags, _dashboard, _task-routing
17+
semantic/ -> 语义知识：API映射, 窗口模型, 生命周期, 平台限制, 模块状态, 构建指南
18+
procedural/ -> 程序知识：移植工作流, 问题分析, 修复验证, Demo生成
19+
episodic/ -> 情景知识：实际移植项目复盘
20+
problems/ -> 错误知识库：编译/构建/运行时实际报错与解决方案（36条）
21+
ohos-common-kb-public/ -> 内嵌的 HarmonyOS 平台通用知识（ArkTS, ArkUI, NAPI, Stage 模型, DevEco 工具链）
22+
skills/ -> Agent skills（kb-init 初始化脚本）
23+
```
24+
25+
**Core principle:** Do NOT load the entire knowledge base. Follow the loading sequence below, load only relevant pages, and trace cross-references (`refs` fields in frontmatter) for deep context.
26+
27+
**Qt version baseline (for validation):**
28+
29+
| Version | Branch | Commit |
30+
|---------|--------|--------|
31+
| Qt 5.15.16 | tqtc/harmonyos-5.15.16 | 962aa625 |
32+
| Qt 5.12.12 | tqtc/harmonyos-5.12.12 | 613336de |
33+
34+
## Loading Sequence (MANDATORY)
35+
36+
When this skill is triggered, follow these steps **in order**:
37+
38+
```
39+
① _index/_task-routing.md -> Match task type, identify workflow and required pages
40+
② semantic/qt-harmonyos-golden-rules.md -> Scan 35 golden rules (avoid known traps)
41+
③ _index/_map.md -> Knowledge map - judge relevance by summary field
42+
④ Load ONLY relevant pages -> Do NOT load everything
43+
⑤ Trace refs fields -> Follow cross-references for deep context
44+
```
45+
46+
## Task Routing Quick Reference
47+
48+
Match the user's request to a task type, then load the corresponding pages:
49+
50+
| User says... | Task Type | Load (paths relative to this directory) |
51+
|-------------|-----------|------|
52+
| 移植/迁移/鸿蒙化一个应用 | [A] App Porting | `procedural/qt-app-harmonyos-migration` + `semantic/qt-harmonyos-porting-workflow` + `api-mapping` + `code-patterns` (+ `procedural/fetch-qt-ohos-sdk` if no Qt SDK/templates) |
53+
| 这个API在鸿蒙上怎么替换 | [B] API Replace | `semantic/qt-harmonyos-api-mapping` + `code-patterns` |
54+
| 某个Qt模块是否支持鸿蒙 | [C] Module Support | `semantic/qt-harmonyos-modules` |
55+
| 鸿蒙有什么限制/不能做什么 | [D] Platform Limits | `semantic/qt-harmonyos-platform-limits` |
56+
| 编译失败/构建报错/部署不了 | [E] Build Troubleshoot | `golden-rules` §一 (B1-B12) + `problems/_lookup` + `semantic/qt-harmonyos-build` + `build-run-workflow` |
57+
| 没有Qt SDK/模板工程 | - | `procedural/fetch-qt-ohos-sdk` — 直接 HTTP 下载预编译 SDK + 模板（无需 git clone） |
58+
| 窗口显示异常/对话框行为不对 | [F] Window Issues | `golden-rules` §二 (W1-W6) + `semantic/qt-harmonyos-window-model` |
59+
| 生命周期/closeEvent/接续 | [G] Lifecycle | `semantic/qt-harmonyos-lifecycle` + `golden-rules` §五 (L1-L4) |
60+
| QtOhosExtras怎么用 | [H] QtOhosExtras | `semantic/qt-ohos-extras` |
61+
| Qt6相关 | [L] Qt6 Status | `semantic/qt-harmonyos-qt6-status` |
62+
| 三方库/依赖/交叉编译 | [M] Third-party Libs | `semantic/qt-harmonyos-third-party-libs` |
63+
| DevEco/MCP/工具链 | [N] Toolchain | `ohos-common-kb-public/semantic/deveco-mcp-capabilities` + `ohos-common-kb-public/procedural/deveco-cli-usage-rules` |
64+
| 写个demo/生成测试工程 | [Q] Demo | `procedural/demo-generation` |
65+
| 遇到执行报错/运行时崩溃 | - | **First**: `problems/_lookup` -> search by error message/code/symptom |
66+
67+
See `_index/_task-routing.md` for the full routing table with detailed decision tree.
68+
69+
## Environment Initialization
70+
71+
When the required Qt SDK, HarmonyOS SDK, toolchain, or template is missing, load `skills/kb-init/SKILL.md` and follow its interactive setup flow. Use its scripts for environment detection, dependency installation, SDK/source/template download, local environment generation, and final verification; do not replace the scripted steps with an improvised installation sequence.
72+
73+
74+
| Platform | Download URL | Size |
75+
|----------|-------------|------|
76+
| Windows | `https://gitcode.com/ohos-qt/qt-harmonyos-src/releases/download/v5.12.12/Qt-5.12.12-arm64-v8a-windows-gles.zip` | ~49 MB |
77+
| macOS | `https://gitcode.com/ohos-qt/qt-harmonyos-src/releases/download/v5.12.12/Qt-5.12.12-arm64-v8a-macos-gles.zip` | ~43 MB |
78+
| HarmonyOS | `https://gitcode.com/ohos-qt/qt-harmonyos-src/releases/download/v5.12.12/Qt-5.12.12-arm64-v8a-harmonyos-gles.zip` | ~42 MB |
79+
| Templates | `https://gitcode.com/ohos-qt/qt-harmonyos-src/releases/download/v5.12.12/templates-0625.zip` | ~240 KB |
80+
81+
> **Critical**: GitCode requires a browser User-Agent header for release downloads. Without it, requests get HTTP 401. Use `curl -A "Mozilla/5.0"` or PowerShell `-Headers @{ "User-Agent" = "Mozilla/5.0" }`.
82+
83+
## Critical Rules (Inline Quick-Scan)
84+
85+
These are the most common pitfalls. See `semantic/qt-harmonyos-golden-rules.md` for all 35.
86+
87+
### Build & Deploy (Top 5)
88+
- **B1**: CMake must set `CMAKE_FIND_ROOT_PATH_MODE_PACKAGE BOTH` before `find_package`
89+
- **B2**: Must link `Qt${QT_VERSION_MAJOR}::QOhosPlatformIntegrationPlugin` (QPA plugin)
90+
- **B3**: `APP_LIBRARY_NAME` must match compiled .so name exactly
91+
- **B9**: qmake `unix` branch must append `:!ohos` - otherwise ohos hits unix branch
92+
- **B10**: QML apps must enable `CMAKE_AUTORCC ON`
93+
- **B12**: SQL driver `libqsqlite.so` must be manually copied to `libs/${ABI_DIR}/sqldrivers/` (same pattern as `libqohosstyle.so`→`styles/`)
94+
95+
### Window Management (Top 3)
96+
- **W1**: `tagWindowOrWidgetAsSubWindowOf()` must be called BEFORE `show()` and `winId()`
97+
- **W3**: Parentless `QDialog` becomes a new main window; must tag or set parent
98+
- **W4**: First window cannot go fullscreen at startup; `show()` first, then `showFullScreen()`
99+
- **W6**: Do NOT rely on `WINDOW_HIDDEN`/`WINDOW_SHOWN` as the only window state sync trigger — WMS can manage visibility without Qt event callbacks
100+
101+
### API/Enum Paths (Top 3)
102+
- **A1**: Close event enum requires full path: `QtOhosExtras::CloseEventRootCause::AbilityClose`
103+
- **A2**: Theme enum requires full path: `QtOhosExtras::QOhosAppContext::ColorThemeMode::FollowSystemSetting`
104+
- **A5**: qtohosextras headers are lowercase only: `#include <QtOhosExtras/qohosappcontext.h>` (NOT CamelCase)
105+
- **A6**: `getCloseEventRootCause()` is a free function, not a member method
106+
107+
### Platform Limits (Top 3)
108+
- **P1**: `chmod()`/`fchmod()` not available - silently fails
109+
- **P2**: `symlink()` not available for third-party apps (EACCES)
110+
- **P3**: `dlopen()` rejects writable paths - only load .so from app lib directory
111+
112+
### Lifecycle (Critical)
113+
- **L1**: `closeEvent()` MUST check `CloseEventRootCause` - Level 2 (AbilityClose) **MUST NOT show UI dialogs**, only silent autoSave
114+
- **L4**: Use `startAbility()` or `startNoUiChildProcess()` for GUI child processes; plain `QProcess` works for headless computation only
115+
116+
## Error Lookup Protocol
117+
118+
When encountering any error (build/runtime/crash):
119+
1. **First**: Search `problems/_lookup.md` by error message, error code, or symptom
120+
2. **Then**: Load the matching problem page for full solution
121+
3. **If not found**: Follow `procedural/framework-issue-analysis.md` for root cause analysis
122+
123+
## Common Mistakes
124+
125+
| Mistake | Fix |
126+
|---------|-----|
127+
| Setting `compileSdkVersion`/`targetSdkVersion` in build-profile.json5 | Remove them (B4) |
128+
| Using short enum paths like `QtOhosExtras::AbilityClose` | Use full path: `QtOhosExtras::CloseEventRootCause::AbilityClose` (A1) |
129+
| Using CamelCase headers for qtohosextras | Use lowercase: `<QtOhosExtras/qohosappcontext.h>` (A5) |
130+
| Calling `tagWindowOrWidgetAsSubWindowOf()` after `show()` | Call BEFORE `show()` and `winId()` (W1) |
131+
| Using `QProcess` for GUI child processes | Use `startAbility()` or `startNoUiChildProcess()` for GUI; QProcess for headless only (L4) |
132+
| Not appending `:!ohos` to qmake `unix` scope | Always use `unix:!android:!macx:!ohos` (B9) |
133+
| Popping UI dialog on AbilityClose | Level 2 close MUST NOT show UI - silent autoSave only (L1) |
134+
| Assuming `Q_OS_LINUX` excludes OHOS | `Q_OS_OHOS` implies `Q_OS_LINUX` - check all Linux branches (G1) |
135+
| Not deploying SQL driver to `sqldrivers/` subdirectory | Manually copy `libqsqlite.so` to `libs/${ABI_DIR}/sqldrivers/` (B12) |
136+
| Relying on `WINDOW_HIDDEN`/`WINDOW_SHOWN` for state sync | WMS manages visibility independently of Qt events (W6) |

0 commit comments

Comments
 (0)