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

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/adaptation//351/270/277/350/222/231PC-Rust-build-script/345/256/277/344/270/273cfg/346/263/204/346/274/217/344/270/216OHOS/344/272/244/345/217/211/351/223/276/346/216/245.md

@@ -0,0 +1,134 @@
+---
+name: 鸿蒙PC-Rust-build-script宿主cfg泄漏与OHOS交叉链接
+description: build.rs 跑在宿主上，cfg!(windows)/cfg!(target_os="linux") 反映宿主而非交叉目标——交叉编译到 aarch64-unknown-linux-ohos 时走错链接分支；判定必须读 CARGO_CFG_TARGET_OS，OHOS 目标按 static=c++/c++abi 链接 C++ 运行时。配套宿主坑（Windows + stable-x86_64-pc-windows-gnu）：raw-dylib 走 self-contained dlltool 时 --temp-prefix 尾冒号触发 NTFS ADS 语义失败（用 as.exe/dlltool.exe 包装器），libfuzzer-sys←rav1e 链期望 libstdc++.so（用 INPUT(-lc++ -lc++abi) 链接脚本垫片），rustc 默认给测试二进制链 libc++_shared.so（随 HNP 打包 NDK 的该库即可）；openssl-sys 类 sys crate 即使设了 OPENSSL_DIR 仍要 CC_<target>+CFLAGS_<target>（cc crate 做头展开/编译器家族探测）。触发词：build.rs、CARGO_CFG_TARGET_OS、cfg!(windows)、宿主泄漏、交叉编译 Rust、aarch64-unknown-linux-ohos、rustup、windows-gnu、USTC 镜像、RUSTUP_DIST_SERVER、dlltool、as、--temp-prefix、NTFS ADS、raw-dylib、libstdc++.so、libc++_shared.so、cargo test --no-run、MSVC link.exe 缺失、openssl-sys、CC_aarch64-unknown-linux-ohos、CFLAGS_aarch64-unknown-linux-ohos、ToolNotFound、compiler family detection、Header expansion、OPENSSL_STATIC
+metadata:
+  type: adaptation
+  source: new/PC（杀毒引擎 Rust 子模块 Windows 宿主交叉全链路实证，2026-09-07）
+---
+
+# 鸿蒙 PC：Rust build script 的宿主 cfg! 泄漏与 OHOS 交叉链接
+
+> 适配含 `build.rs` 的 crate 到 `aarch64-unknown-linux-ohos` 时，两套独立的坑：
+> **语义层**（build script 判定的是宿主而非目标）与**宿主工具层**（Windows-gnu
+> 工具链的 dlltool/as/libstdc++ 怪癖）。症状都出现在链接期，极易误诊成源码不兼容。
+
+## 一、build.rs 里的 cfg!() 是宿主，不是目标
+
+`build.rs` 编译给**宿主**执行——`cfg!(windows)`、`cfg!(target_os = "linux")` 反映
+宿主平台。Windows 宿主交叉到 OHOS 时：链接 Windows 系统库分支被走（错）、
+"linux 才链 C++ 运行时"分支被跳（漏）。**正解是读 Cargo 注入的目标环境变量**：
+
+```rust
+// 判定目标 OS（而不是宿主）
+let target_os = env::var("CARGO_CFG_TARGET_OS").unwrap_or_default();
+// OHOS 目标的 C++ 运行时：按静态 libc++ 链（NDK 有 libc++_shared.so 但测试二进制
+// 想独立分发时静态更省事；动态则记得随包带 libc++_shared.so）
+println!("cargo:rustc-link-lib=static=c++");
+println!("cargo:rustc-link-lib=static=c++abi");
+```
+
+上游常见受害点：`cfg!(windows)` 决定「库名要不要剥 lib 前缀」（Windows 链接器
+吃全名）、`cfg!(target_os = "linux")` 决定链不链 `stdc++`。两处都要换成
+`CARGO_CFG_TARGET_OS` 判定（补丁形态见杀毒引擎案例的
+0001-rust-build-script-target-os.patch）。
+
+## 二、Windows 宿主没有 MSVC：换 windows-gnu 工具链
+
+宿主无 `link.exe` 时 rustc 起不来。装 `stable-x86_64-pc-windows-gnu` +
+`rustup target add aarch64-unknown-linux-ohos`。官方源拉取超时（30min 级）→
+走镜像：
+
+```powershell
+$env:RUSTUP_DIST_SERVER = "https://mirrors.ustc.edu.cn/rust-static"
+$env:RUSTUP_UPDATE_ROOT = "https://mirrors.ustc.edu.cn/rust-static/rustup"
+rustup toolchain install stable-x86_64-pc-windows-gnu
+```
+
+`~/.cargo/config.toml` 的 OHOS target 段（**路径用 8.3 短路径**——含空格的 SDK
+路径会被 cc crate 拆坏参数）：
+
+```toml
+[target.aarch64-unknown-linux-ohos]
+linker = "C:/PROGRA~1/Huawei/DEVECO~1/sdk/default/OPENHA~1/native/llvm/bin/clang.exe"
+rustflags = ["-C", "link-arg=--target=aarch64-linux-ohos", "-C", "link-arg=--sysroot=C:/PROGRA~1/.../sysroot",
+             "-C", "link-arg=-Wl,--code-sign", "-C", "link-arg=-Wl,-rpath,$ORIGIN/../lib",
+             "--cfg", "getrandom_windows_legacy"]
+```
+
+每次 cargo/cmake 前设 `RUSTUP_TOOLCHAIN=stable-x86_64-pc-windows-gnu` 并把
+self-contained bin（`…/rustlib/x86_64-pc-windows-gnu/bin/self-contained`）前置进
+PATH。
+
+## 三、raw-dylib 连环坑：dlltool 的尾冒号（NTFS ADS）与缺 as
+
+依赖链里出现 `windows-sys`/`getrandom` 的 **raw-dylib** 导入库时，rustc 调
+self-contained 的 `dlltool.exe` 生成 .a，再调 `as.exe` 组装——gnu 工具链这步有两个
+宿主级地雷：
+
+1. **`--temp-prefix <dll>:` 尾随冒号**：Windows 把 `foo:` 解析成 NTFS ADS 数据流
+   路径 → dlltool 直接失败。**包装器方案**：把原 `dlltool.exe` 改名
+   `dlltool-real.exe`，自写同名 exe（Rust 单文件）剥掉参数尾冒号再转发；
+2. **self-contained 缺 `as.exe`**：写一个包装 exe 把 GNU as 语法转成
+   `clang --target=x86_64-w64-mingw32 -c`（滤掉 `--64`/`--32`），放 self-contained
+   目录里。
+
+两包装器源码就是两个 ~50 行 Rust 文件（案例仓 `build/_hostbin/{as.rs,dlltool.rs}`），
+零外部依赖、可原样复用。
+
+## 四、libstdc++.so 期望垫片（libfuzzer-sys ← rav1e ← ravif ← image 链）
+
+image → ravif → rav1e → libfuzzer-sys 的构建脚本硬性期望宿主域 `-lstdc++`，而
+gnu 工具链下 rustc 会把它解析成找 `libstdc++.so` 文件——NDK 里没有这个名字。
+**垫片**：在任意目录放一个文本文件 `libstdc++.so`，内容：
+
+```
+INPUT(-lc++ -lc++abi)
+```
+
+链接器脚本语法会把 -lstdc++ 重定向到 NDK 的 libc++。`~/.cargo/config.toml` 或
+rustflags 里加 `-L <该目录>` 即可，不用改任何 crate。
+
+## 五、cargo test --no-run 交叉产物与设备执行
+
+- 交叉跑单测：`cargo test --no-run --target aarch64-unknown-linux-ohos --release`，
+  产物在 `target/<triple>/release/deps/<crate>-<hash>`（无扩展名 ELF）；
+- 上游 build.rs 用 `LIBXXX` 环境变量定位依赖库的（`search_and_link_lib` 模式），
+  逐个指到各依赖 dist 的库文件路径；
+- rustc 默认给测试二进制**动态链 libc++_shared.so**（rustflags 拆不干净）——不必
+  强拆，HNP 里带上 NDK 的 `libc++_shared.so` 即可（`$ORIGIN/../lib` rpath 命中）；
+  设备跑时 `--test-threads=N` 控并发。
+
+## 六、openssl-sys 类 sys crate：设了 OPENSSL_DIR 还不够，要 CC_<target>
+
+`openssl-sys`（`openssl` crate 的 C 桥）即使 `OPENSSL_STATIC=1` + `OPENSSL_DIR=<交叉前缀>` 都设了
+（manual 模式、跳过 pkg-config），其 build.rs 仍会用 **cc crate** 做「编译器家族探测」+ 头展开
+（编译/预处理 `build/expando.c` 取版本宏）——这一步要一个**目标平台的 C 编译器**，跟
+`OPENSSL_DIR` 无关。cc crate 按 `CC_<target>`（连字符）→ `CC_<target>`（下划线）→ `TARGET_CC` →
+`CC` → PATH 里的 `cc` 依次找；全空时报：
+
+```
+ToolNotFound: failed to find tool "cc"
+Compiler family detection failed due to error: ToolNotFound
+Header expansion error（openssl-sys build/main.rs panicked）
+```
+
+修法（杀毒引擎 1.6.0 实证，2026-09-10）：cargo/cmake 前导出一对目标编译器变量（路径用 8.3
+短名，见第二节）：
+
+```powershell
+Set-Item -Path env:CC_aarch64-unknown-linux-ohos -Value 'C:/PROGRA~1/Huawei/DEVECO~1/sdk/default/OPENHA~1/native/llvm/bin/clang.exe'
+Set-Item -Path env:CFLAGS_aarch64-unknown-linux-ohos -Value '--target=aarch64-linux-ohos --sysroot=C:/PROGRA~1/Huawei/DEVECO~1/sdk/default/OPENHA~1/native/sysroot'
+```
+
+这跟 `BINDGEN_EXTRA_CLANG_ARGS`（bindgen 的 libclang）是并列的两条「Rust sys-crate 交叉时
+要喂的目标工具信息」，同样适用于任何走 cc crate 的 `*-sys`（zlib-sys/bzip2-sys/…）。
+CMake 内嵌 cargo 子构建时（如 `add_rust_library`），把这组变量并进传给 cargo 的 ENVIRONMENT，
+否则只设 `OPENSSL_*` 会在 openssl-sys 头展开处报 ToolNotFound。
+
+## 相关
+
+- [[鸿蒙PC-ClamAV杀毒引擎CLI真机适配]] 本套配方的一次完整落地（Rust 子模块 +
+  C 主体混合构建）
+- [[鸿蒙PC-应用沙箱临时目录语义与libcheck-TEMP选址]] 该测试二进制设备执行时的
+  临时目录配套
+- E050 链接器 copy-replace 系列（HMDFS 符号链接限制）是构建目录层的近亲

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/adaptation//351/270/277/350/222/231PC-VLC-autotools/345/252/222/344/275/223/345/272/224/347/224/250/347/247/273/346/244/215.md

@@ -0,0 +1,78 @@
+---
+name: 鸿蒙PC-VLC-autotools媒体应用移植
+description: 大型 autotools/media 应用（VLC 4.0）移植：OHOS 当 bionic-linux vendor 仿 android 支线、musl 无 pthread 取消复用 android/thread.c、compiler-rt builtins 要塞 LIBS 末尾、open_memstream 在 OHOS musl 是坏的、HAP 库装载用 SONAME 别 patchelf；已真机端到端播放 mp4（h264 出画面 + aac 出声）
+metadata:
+  type: adaptation
+  source: new/PC
+---
+
+# 鸿蒙 PC：VLC / 大型 autotools 媒体应用移植要点
+
+把 **VLC 4.0.0-dev**（VideoLAN 媒体播放器，C/C++，autotools + 数百插件）交叉编译到鸿蒙 PC（2026-06-27，NDK API 23 / 6.1.0.105，aarch64-linux-ohos）并**打成 HAP 真机端到端播放成功**：双击运行，播本地 mp4，**视频出画面**（FFmpeg h264 解码→libvlc vmem 回调→XComponent NativeWindow CPU blit）+ **音频出声**（AAC→OHAudio aout），音画同步。libvlccore+libvlc+289 插件全交叉编译通过（4KB 对齐、非 stub）。**§10 是把它在 HAP 里真正跑起来的关键两坑。**
+
+下次把任意 **大型 autotools/media 应用**搬到鸿蒙 PC，按这套来。基础交叉编译坑见 [[鸿蒙PC-C++库交叉编译要点]]；Qt GUI 部分见 [[鸿蒙PC-Qt6-CMake-GUI应用移植]]。
+
+---
+
+## 1. ⭐ 把 OHOS 当作「bionic-like linux vendor」，仿 Android 支线
+OHOS（`aarch64-linux-ohos`，`host_os=linux-ohos`）的 libc 是 musl 派生、NDK clang、GLES/EGL 无 .pc——**与 Android 高度同构**。VLC `configure.ac` 早有 `linux-android*) VENDOR=android` 完整支线，`config.sub`（2024 版）也已认 `ohos`（规范化成 `aarch64-unknown-linux-ohos`）。
+- 改法：configure.ac 加 `linux-ohos*) VENDOR=ohos`（SYS 仍落 `linux*` 分支=linux）+ `AM_CONDITIONAL([HAVE_OHOS], …)`。**不要直接 `VENDOR=android`**——会误触发 OpenSLES/JNI 等 android-only 逻辑（那些是 `== "android"` 精确判断，OHOS 设独立 vendor 才安全）。
+- 凡平台分支 `#ifdef __linux__` 走 Linux 的，OHOS 直接复用（OHOS clang 同时定义 `__linux__`+`__OHOS__`）；专有 Linux 后端（ALSA/X11/PulseAudio）用 `--disable-*` 关掉，configure 缺 pkg-config 也会自动跳过。
+
+## 2. ⭐ OHOS musl 无 pthread 取消 → 复用 Android 的 cancellation-less 实现
+`pthread_cancel / pthread_setcancelstate / pthread_testcancel` 在 OHOS 未声明（musl 家族通病）。VLC `src/posix/thread.c` **无条件**调它们，编不过。
+- VLC 早为 Android（bionic 同样无取消）准备了 `src/android/thread.c`：纯 pthread + futex + pipe 自实现 vlc_thread，**无 JNI、无 android 头、self-contained**，是完整的 vlc_thread 实现。
+- 改法两处：① `src/Makefile.am` 在 `if !HAVE_ANDROID` 内用 `if HAVE_OHOS` 把 `posix/thread.c` 换成 `android/thread.c`；② `include/vlc_threads.h` 的 `#elif defined(__ANDROID__)` 分支加 `|| defined(__OHOS__)`——它把 `vlc_thread_t` 定义成 `struct vlc_thread *`（指针）并设 `LIBVLC_USE_PTHREAD_CLEANUP`，与 android/thread.c 匹配（否则落 POSIX 分支的 `pthread_t` 结构体，类型不符一片报错）。
+
+## 3. ⭐ `POSIX_CLOSE_RESTART` 假阳性
+OHOS `unistd.h` **定义了宏 `POSIX_CLOSE_RESTART`，但 libc 没有 `posix_close()` 函数**。`src/posix/filesystem.c` 的 `#ifdef POSIX_CLOSE_RESTART` 误以为有 → `undeclared function`。改：`#if defined(POSIX_CLOSE_RESTART) && !defined(__OHOS__)` 回退 `close()`。（"宏在、函数不在"是 musl 子集的典型坑，别信宏要信链接。）
+
+## 4. ⭐⭐ compiler-rt builtins 链接顺序（`undefined symbol: __muloti4`）
+C++ 插件用 `__int128`/128 位运算会引用 `__muloti4`（及 `__udivti3` 等）compiler-rt builtin。clang **默认**把 `libclang_rt.builtins.a` 加在链接行**末尾**——单独 `-shared` 没问题（实测默认/`-z,defs` 都自动链上）。**但** libtool 把内部静态便利库（VLC 的 `libvlc_mp4.la`/`libvlc_http.la` 等 `noinst_LTLIBRARIES`）追加在 builtins **之后** → 这些晚到的 .a 里的 builtin 引用无人满足。
+- 修：把 builtins 放到 autoconf **`LIBS`**（automake 把 `$(LIBS)` 放链接行**绝对末尾**，在所有便利库之后）。`export LIBS="-L$(dirname $(clang --target=… -print-libgcc-file-name)) -lclang_rt.builtins"`，再 configure 烤进所有 Makefile。
+- 通用规律：交叉编译 + libtool 便利库 + 任何 compiler-rt/libgcc builtin 都可能撞；解法永远是「把 runtime 库塞到链接行最后」，不是改 LDFLAGS（LDFLAGS 在 objects 之前）。
+
+## 5. host 工具坑（Mac 宿主，库无关）
+- **DevEco 的 `diff` 是坏的**（PATH 把 `…/openharmony/toolchains` 排在 `/usr/bin` 前，那个 `diff` 对任何输入返回 exit 0）→ 毒化 `config.status`：误判 config.h "unchanged" → **从不写 config.h** → `fatal error: 'config.h' file not found`。修：early-PATH 注入 `diff`→`/usr/bin/diff` shim。**任何 Mac autotools 构建都中招**，见 [[鸿蒙PC-autotools-C二进制-goaccess]]。
+- **bison 太旧**：macOS `/usr/bin/bison` 2.3 不认 `-W`，VLC 生成 parser 失败 → `brew install bison flex` 排 PATH 前。
+- **host autotools 缺失**：`brew install autoconf automake libtool gettext`（→ `glibtoolize`，keg-only 加 PATH）。
+
+## 6. 复用现成 OHOS 产物
+- **FFmpeg**：gitcode `OpenHarmonyPCDeveloper/ohos_FFmpeg` = FFmpeg 8.0.1 源码 fork + `build_ohos.sh` + `ohos_dist/`（头+`.so`+`.pc`），实测**非 stub、4KB 对齐**，可直接当 cross sysroot 喂 VLC（pkg-config）。⚠️ 上游 `--disable-asm`（无 NEON 软解很慢）+ `--disable-logging`，生产要去掉重编。FFmpeg 8.0 的 libav* 版本（avcodec 62/avutil 60）远高于 VLC 声明下限，但 **API 可能与 VLC master 的 `modules/codec/avcodec/` 有兼容缝**，需逐个修。
+- **cmd-pkgs**（gitcode 同 org）= 1247 个 aarch64 OHOS 预编译包（dav1d/x264/opus/freetype/fontconfig/harfbuzz/libplacebo/SDL2…），但是**设备侧 runtime 安装包**（`install.sh`），交叉编译要用得在 Mac 下 release tarball 解出 include/lib；且据 [[鸿蒙PC-cmd-pkgs预编译GTK栈不可用]] 有 stub/64KB/baked 隐患，**链入产物的库优先源码自编**。
+
+## 7. 架构与剩余工作
+- VLC 形态：HAP 里 `bin/vlc.c` 编成 `main` 可见的 MODULE `.so`，被 Qt QPA dlopen；libvlccore 再 dlopen 各插件 `.so`。播放时 vout 画进 Qt 窗口的 XComponent NativeWindow（EGL/GLES），aout 走 OHAudio。
+- **音视频输出无 OHOS 等价，需新写**：`aout` 仿 `opensles_android.c` 用 OHAudio NDK；`vout` 仿 `egl_android.c`（ANativeWindow+EGL→OHOS NativeWindow+EGL）复用 VLC 通用 `opengl` 渲染器。Android 后端是现成改写模板。
+- 砍：光驱(DVD/蓝光)、专有硬解(VAAPI/VDPAU/NVDEC/DXVA)、ncurses/skins2、X11/Wayland/D3D。
+
+## 8. ⭐ OHOS 音频输出（OHAudio）：推→拉桥接（Phase 3 已编出 `libohos_plugin.so`）
+鸿蒙原生音频 NDK = **OHAudio**（头 `<ohaudio/native_audiostreambuilder.h>`+`native_audiorenderer.h`+`native_audiostream_base.h`，库 `libohaudio.so` 在 sysroot，`-lohaudio` 直接链）。它是**拉/回调模型**（renderer 回调 `OH_AudioRenderer_OnWriteData(r,user,buf,len)` 找你要数据填 buf），而 VLC `aout` 是**推模型**（`play(block,date)` 把数据塞给你）。
+- **桥接**：standalone `audio_output_t` 模块（仿 `modules/audio_output/android/opensles.c`，**无 JNI**）+ 一个 `block_t` FIFO。`play()` 把 block 追加进 FIFO；写回调从 FIFO 取、underrun 填静音。结构见 `modules/audio_output/ohos.c`。
+- **建流**：`OH_AudioStreamBuilder_Create(&b, AUDIOSTREAM_TYPE_RENDERER)` → `SetSamplingRate/SetChannelCount(2)/SetSampleFormat(AUDIOSTREAM_SAMPLE_S16LE)/SetEncodingType(RAW)/SetRendererInfo(USAGE_MUSIC)` → `SetRendererCallback(cbs, aout)`（**用 since-API-10 的 `OH_AudioRenderer_Callbacks` 结构体最稳**，设备 API 17；结构体 4 个回调槽都要填，只 OnWriteData 有用，其余 no-op 返 0）→ `GenerateRenderer(&r)` → `OH_AudioRenderer_Start(r)`。
+- **协商格式**：首版强制 `VLC_CODEC_S16N` + `AOUT_CHANS_STEREO`，VLC aout 层会自动插转换器/重采样，最省心。
+- **时钟**：VLC 4.0 弃 `time_get` 改 `aout_TimingReport(aout, system_ts, audio_ts)`。在写回调里 `OH_AudioRenderer_GetTimestamp(r, CLOCK_MONOTONIC, &framePos, &time_ns)` 拿设备播放头帧位+单调时刻，`audio_ts = first_pts + vlc_tick_from_samples(framePos, rate)`、`system_ts = VLC_TICK_FROM_NS(time_ns)`，回调线程里直接上报（合法，aaudio 也这么干）。
+- **drain**：写回调发现 FIFO 空且在 draining → `aout_DrainedReport(aout)`。`pause`→`OH_AudioRenderer_Pause/Start`；`flush`→`OH_AudioRenderer_Flush`+清 FIFO；音量 `OH_AudioRenderer_SetVolume`（线性 0–1，>1 放大交回 VLC 软件增益 via `aout_GainRequest`）。
+- 接入：`modules/audio_output/Makefile.am` 在 `HAVE_OHOS` 下 `aout_PLUGINS += libohos_plugin.la`、`_LIBADD = -lohaudio`。补丁 `patches/0002-ohos-audio-output.patch`。
+- 视频输出同理可仿 `egl_android.c`（ANativeWindow+EGL → OHOS NativeWindow+EGL），复用 VLC 通用 `opengl` 渲染器。
+
+## 9. ⭐ 真机音频烟测（root CLI 驱 libvlc，已验证）
+方法：编 `vlc_smoketest`（链 libvlc，`--aout=ohos`）+ 收集 `libvlccore.so.9`/`libvlc.so.12`/FFmpeg `.so`/全部 `*_plugin.so` 闭包 tar 推 `/data/local/tmp/vlc`，`LD_LIBRARY_PATH=<lib>:/system/lib64/ndk:/system/lib64 VLC_PLUGIN_PATH=<plugins>` 跑。
+- **root 可直接 exec 动态 PIE ELF**（`/data/local/tmp` 下，HongMeng 1.12.0）——旧"data_local_tmp PIE 不可执行"记录（见 [[鸿蒙PC-OpenCL-SDK-适配要点]]）对本机**已过时**；不必走 Python ctypes 绕过（且本机无 Python）。app 域（HAP）仍受限只能跑私有 HNP，见 [[鸿蒙PC-app域执行二进制与JIT限制]]。
+- **OHAudio 裸 root CLI 进程可发声**：`OH_AudioRenderer_Start`→0、写回调稳定触发、扬声器出音（`build/smoketest/ohaudio_tone_test.c` 单测，2s/24 回调）。→ **OHAudio 不需 HAP/app 上下文**。
+- **VLC 链路真机到 Playing**：289 插件加载、`using audio output module "ohos"`、`clock source: audio`、`file→wav demux(araw)→Decoder wait→Playing`，文件读/demux 全正常。
+- ⚠️ **端到端没真出声**：文件 access 瞬时读完（`buffering 1000ms in 1ms`）→ headless 播放 input 立刻 `EOF reached` 拆栈，**早于** es_out/decoder→aout `start` 异步建链 → `OnWriteData` 0 次。**非 OHAudio 模块缺陷**（单测能发声、模块已被选用）；真实 HAP 持续播放器/实时流源不会这样。归 Phase 6。
+- ⚠️ **退出期 SIGSEGV**：teardown 干净后 `exit()` 在 musl `__stdio_exit`→`ms_write` 崩（插件 dlclose 后刷 stdio 流的经典问题）；不影响播放，待修。
+- **libvlc 轮询坑**：初始 state 是 `libvlc_Stopped`，轮询循环别在首拍就把 Stopped 当结束 break+release（会把仍在初始化的 input 拆掉，`input_Stop`→`vlc_interrupt_kill`→`vlc_killed()` 让 prebuffer 读 0 字节"cannot pre fill buffer"）。加 `started` 门：先见 Opening/Playing 再认 Stopped。
+- 排障：`__builtin_return_address` 探针打 `delta-&known_sym` + host `llvm-symbolizer` 离线定位调用者（免设备 load base）；崩溃栈 `/data/log/faultlog/faultlogger/cppcrash-<proc>-*.log`（root CLI 也生成）。
+
+## 10. ⭐⭐ 把 libvlc 装进 HAP 真机播放的两个总开关（Phase 4–6，已真机出画面+出声）
+形态：ArkTS `XComponent(SURFACE, libraryname:'vlcplayer')` 壳（ability 生命周期=持续事件循环，解决 [[#9]] 的瞬时-EOF 竞争）+ `libvlcplayer.so`（NAPI 原生模块）里 `libvlc_new(--aout=ohos --vout=vmem)` + `libvlc_video_set_callbacks`（vmem）把 RV32 帧 blit 到 OnSurfaceCreated 拿到的 NativeWindow（[[鸿蒙PC-XComponent-CPU像素渲染与输入缝]] 那道缝）。视频不走 GLES vout、不用 VLC 自带 Qt GUI——**最短可用路径**。HAP 工程复用 calculator-ohos 签名 + spike 模板。
+- **坑 A（总开关，能不能播）：OHOS musl `open_memstream` 是坏的**——返回非 NULL `FILE*`（configure 链接测试通过 → `HAVE_OPEN_MEMSTREAM=1`），但**写入全部丢弃**（buf 空、n=0）。于是 `vlc_memstream` 全线失效 → `EsOutCreateStrId` 返 NULL → `es_out_Add` 每个 ES 都失败 → **不加 ES、不解码、黑屏无声**（且 demux 拿 NULL es 调 `ES_OUT_GET_ES_STATE` 还会 NULL-deref 崩）。修：`configure.ac` 的 `linux-ohos*)` 分支加 **`ac_cv_func_open_memstream=no`**，强制 VLC 自带 fallback（`src/text/memstream.c` 的 `#else`）。**"宏在、函数坏"的又一例**（参 §3 `POSIX_CLOSE_RESTART`）——musl 子集要信运行时不信宏。补丁 `patches/0003-*`。
+- **坑 B（装得进装不进 + 装进了崩不崩）：HAP 库装载用 SONAME 名，别 patchelf**。HAP 打包**接受**带版本号文件名 `libvlccore.so.9`/`libavcodec.so.62`（不必去版本化）。一旦用 `patchelf --replace-needed/--set-soname` 去版本，会**轻微破坏 GNU hash/.gnu.version**：root `dlopen` 照常，但**app 域 loader 在 `do_one_reloc`→`memcmp` 符号解析时 SIGSEGV**（faultlog 寄存器指向被改的 .so）。解法：`pack-hap-libs.sh` 直接 `readelf -d` 取 SONAME 当文件名拷贝、**零修改**；CMake 链 `libvlc.so.12`。（patchelf 的 `--page-size 4096` 能压回 4KB 对齐但救不了 hash 损坏。）
+- 坑 C：ArkTS `fs.accessSync` 返回 boolean **不抛异常**，别 `try/catch` 判存在（恒 true），直接覆盖写 rawfile→`filesDir`，native 读该路径。
+- 坑 D：vmem `RV32` 小端是 BGRX，blit 到 OHOS RGBA8888 要换通道 `d0=s2,d1=s1,d2=s0,d3=255`，按 `bh->stride` 逐行。
+- 排障：`libvlc_log_set` 把 libvlc 日志转 hilog（`vsnprintf`+`OH_LOG_Print`）——HAP 里看不到 stderr，这是唯一能看 VLC 内部日志的法子；崩溃栈 host `llvm-symbolizer --obj=libvlccore.so.9.0.0 <off>` 离线符号化（设备 .so 同内容）。
+
+## 验证手法
+- 产物自检：`llvm-readelf -l x.so | awk '/LOAD/{print $NF}'` 须全 `0x1000`（非 0x10000，否则 dlopen 段错误，见 [[鸿蒙PC-64KB页对齐so崩溃]]）；`llvm-nm -D` 看符号地址不雷同（非 stub）；`llvm-readelf -d` 算 NEEDED 闭包。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/adaptation//351/270/277/350/222/231PC-VLC/345/216/237/347/224/237Qt/347/225/214/351/235/242/347/247/273/346/244/215.md

@@ -0,0 +1,103 @@
+---
+name: 鸿蒙PC-VLC原生Qt界面移植
+description: 把 VLC 自带的 Qt6 界面(modules/gui/qt，不重写)编译+真机跑在鸿蒙 PC 上的完整套路：configure 接 OHOS Qt、qt.cpp/playlist.c 的 fork-exec 与主线程补丁、libvlc app 壳、HAP 打包
+metadata:
+  type: adaptation
+  source: new/PC
+---
+
+# 鸿蒙 PC：移植 VLC 原生 Qt6 界面（modules/gui/qt）
+
+把 **VLC 自带的 Qt 界面**（不是 ArkUI 重写）真机跑在鸿蒙 PC：2026-06-27，**欢迎向导(隐私页→配色页)→主播放器窗口("VLC media player" + Open File/Open Disc)全出来、鼠标点击可交互**。前提是先有鸿蒙 Qt6+QtQuick（见 [[鸿蒙PC-Qt6-qtdeclarative-QtQuick交叉编译]]）、VLC 已能交叉编译播放（见 [[鸿蒙PC-VLC-autotools媒体应用移植]]）。基础 Qt6 app→HAP 套路见 [[鸿蒙PC-Qt6-CMake-GUI应用移植]]。
+
+## 1. configure 接上 OHOS Qt（autotools 的 qt 探测很特别）
+VLC 的 qt 模块不走 pkg-config，而是 `qmake6 -qtconf <conf> -query` + `scripts/static_dirs.py` 解析 `qt6.pro`。要点（脚本 `build/configure-ohos-qt.sh`）：
+- **`target_qt.conf`**（自写，`build/target_qt.conf`）：`Prefix=<OHOS prefix>`、`HostPrefix=<host prefix>`、`Sysroot=<NDK>/native/sysroot`、**`SysrootifyPrefix=false`**（否则把绝对 Qt 前缀拼到 sysroot 后面变垃圾路径）、**`TargetSpec=ohos-clang`**（用 OHOS 那套 mkspec；prefix 自带的 `bin/target_qt.conf` 的 `SysrootifyPrefix=true` 不能直接用）。
+- 环境：`QMAKE6=<host>/bin/qmake`、**`OPENHARMONY_NDK_ROOT=<sdk>/openharmony`**（ohos-clang mkspec 强依赖，否则 `qmake.conf:15 error`）、**`LC_ALL=en_US.UTF-8`**（否则 qmake 嫌 locale 非 UTF-8、static_dirs.py 输出被污染）。
+- moc/rcc/uic/qsb/qmlcachegen 走 host prefix 的 libexec/bin（`QT_HOST_LIBEXECS`）。
+- `--enable-qt --with-qtconf=<conf>` + 保留 `--disable-xcb --disable-wayland`。
+- **白捡**：`modules/gui/qt` 这样就**干净编过**（13MB `libqt_plugin.so`）——X11/Wayland 被 disable 自动排除 compositor，退回 `CompositorDummy`（它其实建可见 `QQuickView`，不是 headless），**不用手写 compositor_ohos / 手砍桌面集成**。VLC 自己的 QML(VLC.MainInterface 等)静态链进插件（`Q_INIT_RESOURCE`），无需单独打包。
+
+## 2. ⭐⭐ 三处 OHOS 源码补丁（app 域禁 fork/exec 是主线）
+鸿蒙 app 域 **不能 fork/exec 子进程**（见 [[鸿蒙PC-app域执行二进制与JIT限制]]）。VLC 多处靠 spawn，逐个撞：
+1. **`src/playlist/playlist.c`**：playlist 建 `vlc_preparser` 默认 `external_process=true`（外进程预解析）→ `external.c` spawn 失败 → playlist parser NULL → **qt 界面拿不到 playlist、init 失败**（日志 `Fail to create Process in process_pool`→`interface "qt" initialization failed`）。修：该 `#if !defined(HAVE_VLC_EXTERNAL_PREPARSER)` 守卫**加 `|| defined(__OHOS__)`** 强制 `external_process=false`（走进程内预解析）。**注意改源码别改 config.h**——`make` 会跑 config.status 把 config.h 从 .in 重新生成、覆盖掉编辑。
+2. **`modules/gui/qt/qt.cpp` OpenInternal 开头**：`posix_spawn` 一个 `vlc-qt-check` helper 来"验 QApplication 可用"。OHOS spawn 失败 → 静默 `return VLC_ENOMEM` →（日志只到 `1 candidates`→`no interface modules matched`，无 qt 日志）。修：该 `#if (_POSIX_SPAWN>=0)&&...` **加 `&& !defined(__OHOS__)`** 跳过自检。
+3. **`modules/gui/qt/util/model_recovery_agent.hpp:56`**：`assert(settings->value(m_key).typeId()==QMetaType::QString)`——全新安装该 setting 非 QString → assert abort（SIGABRT，`LastFatalMessage` 能看到）。修：把类型判断并进 `if(contains && typeId==QString)`，不满足就跳过恢复。（VLC qt 还有别的桌面假设 assert，若再撞可整体 `-DNDEBUG` 关 assert。）
+
+## 3. ⭐ Qt 事件循环必须在 QPA 主线程（qt.cpp 加 OHOS 分支）
+`OpenInternal` 里 `#ifdef Q_OS_MAC`(主线程跑) / `#else`(`vlc_clone` 另起线程跑 QApplication)。鸿蒙 QPA 要求 QApplication 在它启动 app 的那个主线程（否则 ability 秒 `onBackground→onDestroy`、窗口建不起来）。**加 `#elif defined(__OHOS__)` 分支**：`lock.unlock(); Thread(p_intf); vlc_sem_post(&wait_quit); lock.lock(); return VLC_SUCCESS;`——在调用线程内联跑 `Thread()`（它会 `QApplication::exec()` 阻塞）。**必须先 `lock.unlock()`**：`Thread()` 内部(qt.cpp:1280)会重新锁 `lock` 发 open_state，OpenInternal 一直持锁会自死锁（`vlc::threads::mutex` 有 `.lock()/.unlock()`，但 `mutex_locker` 是 RAII 无 unlock，所以手动 unlock/lock 配平 RAII 析构）。
+
+## 4. app 壳 .so + 用 libvlc 内部 API
+QPA 的 `EntryAbility.ets` `launchApplication="libvlcqt.so"`，dlopen 调它的 `main()`（壳不必链 Qt，QApplication 在 qt 插件里建）。`cpp/vlcqt_main.cpp`：
+- `libvlc_new(...)` → `libvlc_InternalAddIntf(p_libvlc_int, "qt")` → `libvlc_InternalPlay(...)` → 阻塞(`pause()`循环)。这仨是**内部 API、导出在 `libvlccore.so.9`（不是 libvlc.so.12）**——所以壳要 `-l:libvlc.so.12 -l:libvlccore.so.9` 都链上（musl 不会从间接依赖解 UND）。**`libvlc_InternalWait` 声明了 VLC_API 但本 build 没导出**，别用，自己 `pause()` 阻塞。`p_libvlc_int` 是 `libvlc_instance_t` 首成员，`*(libvlc_int_t**)vlc` 取。
+- main 开头 `setenv("QV4_FORCE_INTERPRETER","1")` + `setenv("VLC_PLUGIN_PATH","/data/storage/el1/bundle/libs/arm64")`。
+- 调试神器：`libvlc_log_set` 把 VLC -vv 日志接到 `OH_LOG_Print`（否则 stderr 不进 hilog，全黑盒）。
+
+## 5. HAP 打包（在 QtQuick HAP 基础上加 VLC）
+复用 qtquick-spike 的 HAP（Qt 库+QML 模块+QPA+**真 libz**+`.ets`），再加：`libvlcqt.so`、`libvlc.so.12`、`libvlccore.so.9`（SONAME 名直接放）、**全部 290 个 `lib*_plugin.so` 扁平进 libs**（VLC_PLUGIN_PATH 扫）、qt 插件依赖的 Qt 库闭包（Widgets/Svg 等）。`pack.sh` + DT_NEEDED BFS。真 libz 与 qmldir 两坑同 [[鸿蒙PC-Qt6-qtdeclarative-QtQuick交叉编译]]（qmldir 被 hvigor 删、装后 root 推回）。
+
+## 6. ⭐⭐ 视频上屏：vmem→QSGTexture→VideoSurface（OHOS 无 window vout 的正解）
+2026-06-27 打通：**视频真机渲染进 VLC 原生 Qt 界面的视频区并连续播放**（截图 `hap-qt/docs/shots/vlc-video-embedded-in-qt-ui-on-harmonyos.jpeg`）。OHOS 没有 window 型 vout（只有 vmem），所以**不写 compositor_ohos**，改走"内存帧当纹理"：
+1. **强制 `--vout=vmem`** + vmem 回调挂 **libvlc 实例**（不是 media player——UI 自己建 player，我拿不到句柄）：app 壳用内部 `var_Create`/`var_SetChecked`（libvlccore 导出；`var_SetAddress` 只是 inline 包装，自己拼 8 字节 `vlc_value_t` 联合 `p_address`，`VLC_VAR_ADDRESS=0x0070`）给实例设 `vmem-setup/lock/unlock/display/cleanup`。vout display 用 `var_Inherit*` 从对象树往上找，实例级能被 UI 的 player 继承。chroma 设 **"RGBA"** → 直接对 `QImage::Format_RGBA8888`。
+2. **播放顺序坑**：OHOS 的 `OpenInternal` 分支里 `AddIntf` 内联阻塞跑 UI 事件循环，**所以 `libvlc_InternalPlay` 必须在 `libvlc_InternalAddIntf("qt")` 之前调**——否则定位参数只被 preparse 不 play（日志只到 `Creating an input for preparsing`、永不 `for playback`）。
+3. **FFmpeg 解码库进 HAP**：闭包之前只跟 Qt、没跟 VLC 插件的 FFmpeg 依赖 → `avcodec_plugin` 加载失败 → `no video decoder modules matched`/`Codec h264 not supported`。补 `libavcodec.so.62`/`avformat.62`/`avutil.60`/`swscale.9`/`swresample.6`（**SONAME 名**，直接复用旧播放 HAP 的那几个）。
+4. **显示门控坑（关键）**：播放器 QML（`player/qml/MinimalView.qml`）`VideoSurface{ visible: MainCtx.hasEmbededVideo; videoSurfaceProvider: MainCtx.videoSurfaceProvider }`。`hasEmbededVideo()` = `provider && provider->hasVideoEmbed()`。CompositorDummy 不建 provider → 视频区永不可见、`updatePaintNode` 根本不被调。修：**`CompositorDummy::makeMainInterface` 里建 `VideoSurfaceProvider` + `m_mainCtx->setVideoSurfaceProvider(it)` + `it->setVideoEmbed(true)`**（`#ifdef __OHOS__`）。再加 `VideoSurface` 构造 `setFlag(ItemHasContents,true)` + 一个 16ms `QTimer`→`update()` 驱动**连续重绘**（否则只画第一帧冻住）。
+5. **`VideoSurface::updatePaintNode` 出纹理**（放在 `!m_provider` 早 return 之前）：`s_acquire()` 拿帧 → `QImage(buf,w,h,RGBA8888).copy()` → `window()->createTextureFromImage()` → `QSGImageNode`（`setOwnsTexture(true)`/`setRect(boundingRect())`）→ return 该 node（Qt 自动删旧 node）。
+6. **跨 .so 交接**：vmem 回调在 **app 壳 .so**（持 libvlc 实例），VideoSurface 在 **qt 插件 .so**。壳导出 `vlcqt_frame_acquire/release`（双缓冲 write/show 指针 swap + `pthread_mutex`）；qt 插件 **`dlopen("/data/storage/el1/bundle/libs/arm64/libvlcqt.so", RTLD_NOLOAD|RTLD_GLOBAL)` 拿 handle 再 `dlsym`**——`dlsym(RTLD_DEFAULT,...)` 找不到（壳被 QPA 以 RTLD_LOCAL 加载，符号不进全局域）。
+- 改的文件：`maininterface/videosurface.cpp`（构造 ItemHasContents+QTimer、updatePaintNode 纹理、includes）、`maininterface/compositor_dummy.{hpp,cpp}`（provider+embed）、`hap-qt/cpp/vlcqt_main.cpp`（vmem 回调+导出+顺序+args）。**均需回写 `patches/`**。
+- 测试用 args：`--no-qt-privacy-ask`（跳欢迎向导）、`--input-repeat=65535`（循环）、定位参数自动播 `test.mp4`。真用应去掉、走 UI 的 Open File（同一 vmem 管线，实例级回调任何 player 都继承）。
+
+## 7. ⭐ 界面"简陋(只有 Open File/Open Disc)"的真相 + 去测试化（2026-06-29）
+用户反馈"界面就一个打开+设置，VLC 就这么简陋?"——**不是缺东西，是 VLC 的`无媒体库`形态**：
+- 根因：`build/configure-ohos.sh` 用 `--without-contrib` → 外部 `medialibrary` 库(C++/SQLite)没编 → `config.log` 里 `MEDIALIBRARY_LIBS=''` → `misc/medialibrary` 插件没 build → `vlc_ml_instance_get()` 返回 NULL。VLC `MainDisplay.qml:125` 据 `MainCtx.mediaLibraryAvailable`(=`hasMediaLibrary`，`mainctx.cpp:211` 由 `vlc_ml_instance_get()!=NULL` 决定)选 Home：**有库→`medialibrary/qml/HomeDisplay.qml`(继续观看/视频/音乐网格+顶栏 Video/Music 标签)；无库→`maininterface/qml/NoMedialibHome.qml`(只锥 logo + Open File + Open Disc，顶栏隐藏 Video/Music)**。所以"简陋"是**原生 VLC 的降级页**，不是移植 bug。完整播放器 chrome(控制条/播放列表/菜单)其实都在——**播放时**才出(`MiniPlayer.qml:35` `state: Player.isStarted?...`，控制条无鼠标移动会自动隐藏)。
+- 去测试化：app 壳 `vlcqt_main.cpp` 的 `vlc_args` 砍到只剩 `--no-stats --no-qt-privacy-ask --vout=vmem -vv`（删掉自动播 `test.mp4`、`--input-repeat`、`--no-media-library`(无库时多余)、`--no-osd`、`--no-video-title-show`）。验证：开机进 `NoMedialibHome` 不自动播(无 `vmem frame` 日志)；命令行喂 `test.mp4` 仍正常解码出图，且**删 `--no-osd` 后 OSD 时间戳成功叠进 vmem 帧**(截图 `docs/shots/vlc-qt-detested-playback-osd.jpeg`)——vmem vout 软件 blend SPU 没问题。改 app 壳 args 只需重编 `libvlcqt.so`(13KB clang++)，**别重跑 `pack.sh`**(它 `rm -rf hap` 会冲掉手动加的 FFmpeg SONAME 库，BFS 闭包不从 avcodec_plugin 追)；直接把新 `.so` 覆盖进 `hap/entry/libs/arm64-v8a/`，`hvigorw assembleHap`→`hdc install`→**重推 qmldir**(hvigor 每次都删 qml/ 下全部非 .so 共 30 个 qmldir+402 qml+29 qmltypes+png，`tar` 打包后 `cd $DEST && tar -xzf` 推回；`$DEST=/data/app/el1/bundle/public/<bundle>/libs/arm64`)。
+- **⭐ 输入缝纠正(推翻 §3 乐观说法)**：合成**触摸**事件(`uitest uiInput click/longClick/doubleClick/drag`、`uinput -T`)**驱动不了 VLC 的 QML 按钮**——点 Open File 零反应、无 `simpleOpenDialog` 日志(VLC QML 渲染到 OpenGL surface，且按鼠标语义处理输入，疑似过滤合成鼠标)。但**窗口管理器的原生标题栏(最大化/关闭)吃触摸 tap**(最大化 `uitest click` 生效)。结论：自动化点不动 VLC 界面按钮，**只有真鼠标能**(用户本人点得开文件选择器)。`uitest dumpLayout` 也只见原生窗口标题文本、看不到 QML 内容节点。
+## 8. ⭐ SVG 图标插件加载 + 控制条渲染（2026-06-29，Segment A：默认播放展示完整播放 UX）
+用户要"默认播一个视频、把完整播放器 UX 渲染出来"。做法+踩坑：
+- **默认自动播放**：app 壳 args 加回定位媒体 + `--input-repeat=65535`。播放时 VLC 因 `playlist-autostart` 进沉浸式 **Player 视图**（`player/qml/Player.qml`+`TopBar.qml`），控制条默认悬浮、鼠标静止自动隐藏。
+- **钉住控制条**：`--qt-pin-controls`（`qt.cpp:416` add_bool "qt-pin-controls"）→ `MainCtx.pinVideoControls=true` → `Player.qml:60 _controlsUnderVideo = pinVideoControls && visibility!=FullScreen` → 控制条常驻视频下方（但**最大化时 visibility 可能=FullScreen 失效**，要窗口模式）。
+- **⭐⭐ SVG 图标引擎插件（控制按钮图标）**：VLC 控制按钮用 `ColorizedSvgIcon`（`util/colorizedsvgicon.cpp:117`）走 **`QPluginLoader("iconengines/qsvgicon")`** 按**固定名**加载 → 要求插件文件名是 Qt 标准 `libqsvgicon.so`，但 OHOS Qt 构建产出名为 `libplugins_iconengines_qsvgicon.so`，**名字对不上 → "svg icon plugin is not found"**。修：①把插件**改名** `libqsvgicon.so` 放进 `hap libs/plugins/iconengines/`（imageformats 的 `libqsvg.so` 同理）；②路径问题——`QT_PLUGIN_PATH` setenv / `chdir` 让 `./plugins` 命中 **都无效**（OHOS QPA 经 napi 加载时已缓存 `libraryPaths()`，早于壳 main()），**正解是 patch `qt.cpp` 在 `QApplication app(...)` 后 `#ifdef __OHOS__ app.addLibraryPath("/data/storage/el1/bundle/libs/arm64/plugins")`**（要重编 `libqt_plugin.so`）。验证：插件本身 `dlopen` 在 app 命名空间**能成功**（非依赖/命名空间问题，纯 QFactoryLoader 找名问题）；改名+addLibraryPath 后 "svg icon plugin is not found" 消失。
+- **⏳ 仍未解（两件）**：(a) **imageformats 的 SVG 图像插件**（`QImageReader`→`QFactoryLoader` 目录扫描）即使改名 `libqsvg.so`+addLibraryPath 仍 "Unsupported image format"（cone logo、专辑占位图空白；hilog `noart_albumCover.svg: Unsupported image format`）——QFactoryLoader 扫描机制与 QPluginLoader 显式名不同，疑似 loader 在 addLibraryPath 前已实例化缓存。(b) **⭐控制条只渲染时间文字**：图标引擎修好+无 QML 报错，但播放控制条**只画出 "00:00"/"00:10" 时间标签，进度条滑轨与播放/暂停/音量等按钮行整体不显示**（pin/悬浮、各种窗口尺寸都一样）。非 z-order（时间标签可见说明控制条在视频之上）、非 QML 错误。需场景图级调试（疑似控制条主内容 Loader/滑轨/按钮渲染在 OHOS 上失效）。截图 `docs/shots/vlc-qt-segmentA-autoplay-player.jpeg`、`vlc-qt-playback-controlbar-timeonly.jpeg`。
+
+## 9. ⭐⭐ (b) 真因 = `intfScaleFactor=0` 致 `dp()` 全塌零（2026-06-30 定位+修复）
+症状"控制条只剩时间文字 + 主窗口几近空白"的真因**不是场景图**，而是 **`MainCtx::intfScaleFactor` 被算成 0** → `MainCtx::dp(px,scale)=round(px*0)=0` → 所有 dp 尺寸（按钮 `icon_toolbar/medium`、滑轨 `heightBar_xxsmall`、边距、cone logo）塌成 0。时间标签是 FontMetrics/字号回退，`pixelSize=0` 时 Qt 用默认字号仍显示 → 唯一残留。`VLCStyle.qml:27 scale=MainCtx.intfScaleFactor`，全局 dp 都吃它。
+- **为何=0（hilog 实证）**：`mainctx.cpp:496` `loadFromSettingsImpl` 里 `userIntfScaleFactor=var_InheritFloat("qt-interface-scale")`(默认 -1)→ `==-1` 时读 QSettings `MainWindow/interface-scale`(默认1.0)。但**只判 `==-1` 这一个哨兵**，一个 0 值（OHOS 上观察到 user=0，且析构时 `:318` 把 0 存回设置形成自喂循环）直接赋给 `m_intfUserScaleFactor`**未经 qBound 钳制**（qBound 只在 `setIntfUserScaleFactor` 路径，本路径绕过）→ `intfScaleFactor = user(0)*dpi/96 = 0`。hilog：`interface scale factor: user=0.000000 dpi=96.000000 -> 0.000000`（dpi 显示就绪后是 96 正常，杀手是 user=0）。
+- **修复**（`patches/ohos-qt-intfscale-guard.patch`，改 `mainctx.cpp`）：① load 处 `if(!(userIntfScaleFactor>0)) userIntfScaleFactor=1.0;` 兜非法/0/负；② `updateIntfScaleFactor()` 加 `if(dpi>0.)` 守卫（早期 screen 未就绪时 dpi=0，避免又塌零）+ 一行 `msg_Dbg` 打印 user/dpi/scale 便于复诊。修后 hilog `user=1.0 dpi=96.0 -> 1.0`。
+- **效果（真机验证，hdc snapshot 对比）**：修前 VLC 窗口**整片纯白零 chrome**；修后 `--qt-pin-controls` 下**顶栏(back/menu/playlist)+ 进度条滑轨(橙色 handle+轨道+时间)回来了**。截图 `docs/shots/`(本次)。
+- **⏳ 仍剩**：播放/暂停/音量**按钮行**仍不显（滑轨是静态元素已恢复；按钮行是 `PlayerControlLayout` 模型驱动 → 指向 §8 里 Explore 假设②**控制条 profile 模型空**：`getModel(identifier)==null` 或 profile 残缺，`dialogs/toolbar/controlbar_profile_model.cpp` reload/insertDefaults 路径）。下一步查该模型为何在 OHOS 为空。另视频区 vmem 帧在合成启动态截图里未上屏(--:--)，疑似抓帧时机/播放未进行，真人交互下正常(用户确认基础页面在)。
+- **部署闭环(本机 hdc 全自驱,已跑通)**：改 `src` → `make -C modules/gui/qt CXXFLAGS="-fPIC -O2 -DNDEBUG"`(出 `libqt_plugin.so`)/ 壳 `$CXX -shared ... -l:libvlc.so.12 -l:libvlccore.so.9 -lhilog_ndk.z`(出 `libvlcqt.so`) → 覆盖进 `hap/entry/libs/arm64-v8a/` → **DevEco 自带 `Contents/tools/hvigor/bin/hvigorw --no-daemon assembleHap`(本机 CLI 可签包)** → `hdc install -r .../entry-default-signed.hap` → **重推 qmldir**(tar 非.so→`hdc file send`→设备 `tar xzf` 到 `$DEST=/data/app/el1/bundle/public/com.qt.calculator/libs/arm64`) → `hdc shell aa start -b com.qt.calculator -a EntryAbility` → `hilog`/`snapshot_display -f x.jpeg`(必须 .jpeg)。bundle .so 经重签 HAP 进设备，**root 直推 .so 不行(XPM/代码签名)**,只有 qmldir 等数据文件能直推。
+- 资产：`hap libs/arm64-v8a/plugins/{iconengines/libqsvgicon.so,imageformats/libqsvg.so}`（来自 Qt OHOS 构建 plugins/，改名）；源码补丁 `qt.cpp` 的 `addLibraryPath`（`#ifdef __OHOS__`，需回写 patches/）。
+
+- **下一步 Phase 2(完整媒体中心首页)**：移植 `medialibrary`(0.13.2)+`sqlite`(3.46.1) 两个 contrib 到 ohos(`cd src/contrib && ../bootstrap --host=aarch64-linux-ohos && make .sqlite .medialibrary`，`-Dlibvlc=disabled` 时只依赖 sqlite，静态链进 `libmedialibrary_plugin.so` 无需单独 ship)，`ohos-env.sh` 的 `PKG_CONFIG_LIBDIR` 加 contrib 的 pkgconfig 让 `MEDIALIBRARY_LIBS` 非空(保留 `--without-contrib`)，`vlcqt_main.cpp` setenv `VLC_USERDATA_PATH` 到 el2 可写沙箱(DB 落 `…/ml/ml.db`)+`--ml-folder`。**go/no-go = 沙箱能否 `opendir` 扫描用户媒体目录**(ML 走原生 `opendir`/`readdir` 非 SAF，受 DAC/SELinux 限；先指向 app 自己 el2 沙箱媒体目录探)。`pack.sh` 第3步 glob 自动收新插件。
+
+## 10. ⭐⭐ 三连修：Open File 不播放 + 控制栏按钮行不渲染 + 视频画面冻结（2026-06-30）
+scale 修好后用户报三个问题，逐个真机定位+修复（全程 hdc 自驱：改 src→`make -C modules/gui/qt`→覆盖 `libqt_plugin.so`→`hvigorw assembleHap`→`hdc install -r`→推 qmldir+test.mp4→`aa start`→`uitest uiInput click` 点授权→`snapshot_display`/`hilog` 验）。
+
+- **② Open File 选片不播放 = app 沙箱无文件权限**。HAP 只声明 INTERNET/WIFI，VLC 用 raw `open()` 开文件→用户目录文件打不开（hilog `cannot open … No such file or directory`，连 autoplay 的 test.mp4 都是）。修(改 HAP 不改 VLC)：`module.json5` `requestPermissions` 加 `READ_WRITE_DOCUMENTS_DIRECTORY`+`READ_WRITE_DOWNLOAD_DIRECTORY`(各带 `reason`=$string 资源+`usedScene`，否则 hvigor 00303218)；`EntryAbility.ets` 的 `onWindowStageCreate` **`await abilityAccessCtrl.createAtManager().requestPermissionsFromUser(this.context,[两权限])` 再 `qpa.startQtApplication`**(startQtApplication 内联阻塞，必须先 await 授权)。授权后 raw 路径读 Documents/Download(grantStatus:0)；Desktop 系统签名够不着。详见 [[鸿蒙PC-app访问PC用户目录]]。**test.mp4 等数据文件 hvigor 打包时会从 libs strip(同 qmldir)→ root 推到 `/data/app/el1/bundle/public/<bundle>/libs/arm64/`**。
+- **① 控制栏按钮行(play/pause/音量)整排不渲染 = controlbar profile 模型空**。按钮行模型驱动(`PlayerControlLayout.qml` 读 `controlbarProfileModel.currentModel.getModel(identifier)`),滑轨是静态(scale 修好就回来,按钮行不回)。真机日志:`reload=1 rowCount=1 selected=-1 currentModel=0x0`——OHOS QSettings 用 `NativeFormat` 无显式路径(`qt.cpp:988` 只 `_WIN32` 用 Ini),落在沙箱里残留一个**不完整 profile**,reload 返 true(绕过空→insertDefaults 的 safety-net)但选中=-1→currentModel 空→整排不实例化。修:`qt.cpp:988` QSettings `#if defined(_WIN32)||defined(__OHOS__)` 用 **`IniFormat`+显式 `config_GetUserDir(VLC_CONFIG_DIR)` 路径**(忽略旧坏档,fresh→reload=0→insertDefaults→5 个默认 profile,selected=0,按钮行齐)；外加 `controlbar_profile_model.cpp` 兜底 `if(currentModel()==null && rowCount()>0) setSelectedProfile(0)`。
+- **③ 视频画面冻结(声/时钟/解码都在走,画面卡首帧) = QSGImageNode 每帧 new 不刷新**。日志证:`updatePaintNode` 持续被调(60fps)、`frameSwapped` 持续(窗口在出帧)、`g_video` 帧在变,但屏幕烧录时间码两张 4s 截图都 `00:00:00.292`。根因:OHOS 场景图下**每帧 `w->createImageNode()` 新建节点 + `return imgNode` 不刷新到屏**。修(`videosurface.cpp` updatePaintNode OHOS 块):**复用传入 node**(`static_cast<QSGImageNode*>(node)`,无则建)、`setTexture` 原地换(setOwnsTexture 删旧)、`markDirty(DirtyMaterial)`、无帧时 `return node`(不落到基类);并在 16ms `QTimer` 里加 `if(auto*w=window())w->update()` 强制窗口出帧。修后烧录时间码 `00:00:00.250→00:00:03.667`(frame 6→110),画面动了。
+- 资产/补丁:HAP 改 `hap-qt/hap/entry/src/main/{module.json5,ets/entryability/EntryAbility.ets,resources/*/element/string.json}`+`libs/arm64-v8a/test.mp4`(root 推)。VLC src 补丁回写:`patches/ohos-qt-interface-playback.patch`(含 qt.cpp QSettings)、`ohos-qt-video-embed.patch`(含 videosurface 刷新)、新增 `ohos-qt-controlbar-defaults.patch`。三问题真机验证通过(截图 `hap-qt/docs/shots/` 本轮 k1/k2 等;控制栏完整按钮行+视频逐帧播放)。
+
+## 11. ⭐⭐⭐ Open File 真正打通：ArkTS+NAPI 旁路（2026-06-30，§10 的②是必要非充分）
+§10 的文件权限是必要的，但 Open File 选片**仍不播**。逐层真机定位后发现是 **Qt-OHOS QPA 的文件对话框在单线程上死锁**，VLC 侧无解，最终用 **ArkTS 驱动系统 picker + NAPI 桥**绕过。几个**颠覆既有认知**的关键事实：
+
+- **真因 = QPA 文件对话框死锁（非 FileUri 格式，计划里的 FileUri→本地路径假设是错的）**。真机日志链:点 Open File→`Q_UNIMPLEMENTED`×2(QPA `QOhNativeFileDialog::setDirectory/selectNameFilter` 是空实现,无害告警)→picker 能弹能选,但 `getOpenFileUrls` **永不返回**(我加的 `showSimpleOpen` 日志不打)。读 QPA 源码 `qohplatformdialoghelpers.cpp`:picker 走 `documentPicker.select()` 返回 **JS Promise**(`runOnJsUIThreadNoWait`+`m_eventLoop.exec()` 阻塞等待);而 `show()`(非阻塞路径)是**空的**(只 `ensureNativeDialog` 不弹 picker)。**阻塞的 Qt 嵌套事件循环 pump 不了 ArkTS JS 微任务队列→picker 结果 Promise 永不 resolve→死锁**。`QFileDialog::open()` 非阻塞也没用(QPA 的 show 不触发 picker)。VLC 侧改阻塞/非阻塞都不行。
+- **⭐⭐ 颠覆:`qpa.startQtApplication(this)` 不是 inline 阻塞,而是 spawn 一个独立线程跑 VLC/Qt**(改正旧记的"Thread() inline")。证据:`registerOpenRequest`/`startQtApplication OK` 在 **TID=主/JS 线程**,`registered open-path fn`/`simpleOpenDialog` 在 **另一个 TID**;且 `startQtApplication OK` 日志能打出来(若 inline 阻塞则永不返回)。**所以 VLC Qt 线程 ≠ ArkTS JS 线程**——这是下面所有坑的根源。
+- **⭐⭐ 从 Qt 线程直接调 napi → `EcmaVM::CheckThread()` SIGABRT 闪退**。崩溃栈 `abort←CheckThread←napi_call_function←vlcqt_request_open_file`。ArkVM 强制 napi 只能在 JS 线程调。**修:`napi_threadsafe_function`**——`registerOpenRequest` 时(JS 线程)`napi_create_threadsafe_function` 建 TSFN;`vlcqt_request_open_file`(Qt 线程)用 `napi_call_threadsafe_function(...,napi_tsfn_nonblocking)` 把调用 marshal 回 JS 线程,在 `call_js` 回调里再 `napi_call_function` 调 ArkTS handler。
+- **⭐ VLC 插件的符号被 version script 藏了(只导出 `vlc_entry__*`),`visibility("default")` 也没用**——app 壳 dlsym 不到 `vlcqt_qt_open_path`。**修:反向注册运行时函数指针**:qt 插件 init 时 `dlsym(libvlcqt.so,"vlcqt_set_open_path_fn")` 把 `&vlcqt_qt_open_path` 传给 app 壳;app 壳存指针调用(地址不受可见性影响)。反方向 app 壳的 `vlcqt_request_open_file`/`vlcqt_set_open_path_fn` 在普通 .so(无 version script)默认导出,qt 插件 dlsym 得到。
+- **ArkTS import 原生 .so 需 `@types/libX.so` 声明**:建 `entry/src/main/ets/types/libvlcqt/{index.d.ts,oh-package.json5(name=libvlcqt.so)}` + entry `oh-package.json5` devDeps 加 `"@types/libvlcqt.so":"file:./.../libvlcqt"` + `ohpm install`(照搬现成的 `libtest_napi` 模板;name 不匹配的 WARN 无害)。app 壳 .so 加 `napi_module_register`(`nm_modname="vlcqt"`,`__attribute__((constructor))` 里注册)即可被 `import vlcqt from 'libvlcqt.so'`;同一 .so 既有 main()(QPA dlopen 调)又是 napi 模块(ArkTS import),dlopen 同实例共享 globals。编译 app 壳加 `-lace_napi.z`(napi 头在 NDK sysroot `napi/native_api.h`)。
+- **完整链路**(5 段):VLC 点 Open File→`simpleOpenDialog`(OHOS 分支,`dlsym vlcqt_request_open_file`)→TSFN marshal 到 JS→ArkTS `pickAndOpen()` 跑 `new picker.DocumentViewPicker(ctx).select()`→`.then` 拿 URI→`new fileUri.FileUri(uri).path` 解析成 `/storage/...` 物理路径→`vlcqt.openPath(path)`(NAPI,JS 线程)→`g_qtOpenPath`=`vlcqt_qt_open_path`→`vlc_path2uri`+`input_item_New`+`vlc_playlist_Lock/Append/GoTo/Start`(挂到 `g_qtIntf->p_playlist`,vlc_playlist 自带锁线程安全,PlaylistController 观察到→UI Play Queue 出条目)。真机验证:Play Queue 出 `5b56c409e6147.mp4`,`creating access: file:///storage/Users/currentUser/Download/...mp4`,正常播放。
+- **配套**:`QuitSpy` 在 OHOS 吞掉 picker 关闭时的假 `QEvent::Quit`(否则 `libvlc_Quit()` 拆界面,见崩溃前的 `exiting`/`no exit handler`=`src/misc/exit.c`);ability 生命周期负责真退出。`vlcqt_main.cpp` 去掉 autoplay(boot 到首页,日志干净)。
+- **资产**:VLC src 补丁 `patches/ohos-qt-interface-playback.patch`(qt.cpp 加 `vlcqt_qt_open_path`+注册+QuitSpy、dialogs_provider.cpp 的 simpleOpenDialog 旁路)。HAP 工程改 `hap-qt/cpp/vlcqt_main.cpp`(NAPI 桥)、`hap/entry/src/main/ets/entryability/EntryAbility.ets`(import+register+pickAndOpen)、`types/libvlcqt/`、`oh-package.json5`。**openFileDialog(Open Multiple Files)走 showSimpleOpen 仍会死锁,未接旁路**(同法可接)。
+
+## 12. 收尾：清理+健壮性 / SVG 图像空白查明（2026-06-30）
+- **① 清理+健壮性（已做）**：去 §11 诊断日志；`QuitSpy 吞 Quit`、`vlcqt_qt_open_path` 日志 `msg_Warn`→`msg_Dbg`。**防 App 卡死**：OHOS 下其余原生文件选择入口仍触发 §11 QPA 死锁（冻结整个 App），未接旁路但**早退兜底**——`dialogs_provider.cpp` 的 `showSimpleOpen`(字幕/音轨/视频 loadMediaFile)、`getSaveFileName`(存播放列表，**static 方法用 qWarning 不能用 p_intf**)、`getDirectoryDialog`(打开文件夹)、`openFileGenericDialog` 非 save 分支，OHOS 下 return 空+log，误点不再冻结。Open File 旁路不受影响仍正常。另把 `qt.cpp` 的 `addLibraryPath(.../plugins)` 提前到 **QApplication 构造前**（更合理，但没修好 SVG）。补丁并入 `patches/ohos-qt-interface-playback.patch`。
+- **② SVG cone/专辑占位图空白：查明=死胡同，已搁置**（用户决定）。真因=这套 **OHOS Qt 的 `QImageReader`/`QFactoryLoader` 不注册任何动态 imageformats 插件**（`supportedImageFormats()` 只剩内置 `bmp pbm pgm png ppm xbm xpm`，无 svg/jpg/gif）。**已逐一排除**：打包(libQt6Svg.so+libqsvg.so+libqsvgicon.so 都在真机签名包 `…/libs/arm64/plugins/imageformats/`)、路径(`libraryPaths()` 含 `…/plugins`)、opendir(`QDir` 能列出 `libqsvg.so`)、版本(插件 metadata version=394496=6.5.0 vs 运行 `qVersion()`=6.5.6，major.minor 兼容)、加载(`QPluginLoader.load()`=1 成功，DT_NEEDED 全解析)、元数据(IID=`QImageIOHandlerFactoryInterface`、Keys=`["svg","svgz"]` 完全正确)、刷新(`removeLibraryPath`+`addLibraryPath` 强制 refreshAll 无效)。即**有效插件被工厂静默拒绝**。`QT_DEBUG_PLUGINS=1` 在 app 壳 main() 设太晚(QPA 在 main 前就初始化插件表)→不出诊断。无静态 `libqsvg.a`，不能直接 `Q_IMPORT_PLUGIN`。**纯视觉零功能影响**。后续路子(若要做)：(a) 改 `vlcqtmessagehandler` 路由 categorized 日志 + 运行时 `QLoggingCategory::setFilterRules("qt.core.plugin.*=true")` 拿确切拒因；(b) 重编 qtsvg 出静态插件 `Q_IMPORT_PLUGIN(QSvgPlugin)` 绕过动态扫描(最可能根治)。
+
+## 现状与剩余
+- ✅ **去测试化完成**（2026-06-29，见 §7）：开机进 VLC 真实首页 `NoMedialibHome`（Open File/Open Disc）不自动播放；命令行喂媒体仍正常解码出图+OSD。截图 `docs/shots/vlc-qt-home-no-autoplay.jpeg`、`vlc-qt-detested-playback-osd.jpeg`。"界面简陋"=无媒体库降级页(原生 VLC 行为)，非 bug；完整媒体中心首页需 Phase 2 移植 medialibrary contrib。
+- ✅ **视频嵌进界面并连续播放**（vmem→QSGTexture→VideoSurface，见 §6）。h264 解码（FFmpeg）+ 帧上屏 + 60fps 重绘都通。
+- ✅ VLC 原生 Qt 界面真机跑+可交互（向导→主窗口、鼠标点击 Next 生效）。`OcclusionInfo` 见 `firstrunWindow_1`+`calculator0` 两窗口。
+- **输入**：VLC qt 认**鼠标**（轮询 `isMousePressed`），`uinput -T`(触摸绝对) 点不动按钮；`uinput -M -m` 是**相对**移动且不能负、定位难，**`uitest uiInput click <x> <y>` 是绝对、能驱动**。真人用真鼠标无碍。
+- ⏳ 杂项：SVG cone 图标不认（→PNG，见 [[鸿蒙PC-Qt6-CMake-GUI应用移植]] §12）；`unknown Qt platform: openharmony` 无害告警；VLC qt 还有桌面假设 assert，整体 `-DNDEBUG` 编 qt 插件关掉（`make -C modules/gui/qt CXXFLAGS="-fPIC -O2 -DNDEBUG"`）。Open File 走 UI 流：底层 vmem 播放管线已验证(命令行喂媒体出图)，但**合成输入点不动 QML 按钮**(见 §7 输入缝)，端到端 picker→play 需真鼠标(用户本人验过 picker 弹出)。
+- 源码补丁落在 `playlist.c`/`qt.cpp`/`model_recovery_agent.hpp`/**`videosurface.cpp`/`compositor_dummy.{hpp,cpp}`**，**需回写 `patches/` 固化**（configure.ac 的 EXTERNAL_PREPARSER 排除 OHOS 也一并）。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/adaptation//351/270/277/350/222/231PC-VisualVM-JVM-Swing/345/272/224/347/224/250/347/247/273/346/244/215.md

@@ -0,0 +1,54 @@
+---
+name: 鸿蒙PC-VisualVM-JVM-Swing应用移植
+description: 把 NetBeans RCP/Swing 桌面 Java 应用(VisualVM)用 OH-AWT JDK 嵌进 HAP 真机跑起来的完整套路、liblauncher 黑盒契约、签名 ACL、startupcheck/license/nosplash 三连修复
+metadata:
+  type: adaptation
+  source: new/PC
+---
+
+把桌面 **Java Swing / NetBeans RCP 应用**（以 VisualVM 2.2.1 为例）搬到鸿蒙 PC 的路线：复用「Java Swing 鸿蒙化」参考工程的 **OH-AWT 定制 BishengJDK 8 JRE + liblauncher.so**（把 AWT 后端从 X11 换成鸿蒙原生 `libawt_xawt.so`，窗口走 XComponent/EGL），payload 换成目标应用，业务字节码零改动。
+
+## ✅ 结果（2026-06-27 真机）：VisualVM 2.2.1 **完整界面**在 HarmonyOS 6.1 跑起来
+主窗口/菜单栏(File…Help)/工具栏/**实时堆监视器**(数值跳动)/**Applications 树(Local/Remote/VM Coredumps/JFR Snapshots/Snapshots，Local 下已发现进程)+ Start Page 内容面板全部渲染**/菜单点开/窗口最大化全可用，OH-AWT 键鼠输入通。`Java 1.8.0_432 BiSheng`、OpenGL ES(Mesa) 渲染。
+
+## 内容面板空白的真因 = 模块加载失败（不是绘制 bug），靠补 tools.jar 解决
+主窗口起来但中间 NetBeans TopComponent 区空白时，先看 `userdir/var/log/messages.log`：会有
+`org.netbeans.InvalidException: org.graalvm.visualvm.lib.profiler ... Dependency failed on package com.sun.tools.attach[VirtualMachine]`。
+即 OH-AWT 运行时是 **JRE 无 tools.jar**，依赖 `com.sun.tools.attach`/`sun.jvmstat` 的内容模块(profiler/jfr/application 链)装不上 → 内容 TopComponent 不注册 → 空白。**修复**：把一个 JDK8 `tools.jar` 放到发布根（`resfile/visualvm/tools.jar`），Bootstrap 把 `appHome/tools.jar` 挂上 boot classpath → 模块加载 → 内容渲染。
+- **tools.jar 不需要鸿蒙版**（通用 Temurin 8u492 即可）：模块依赖是**包存在性**检查、加载期不跑 native；且通用 `sun.tools.attach.LinuxVirtualMachine` 声明的 10 个 native(socket/connect/sendQuitTo/sendQuitToChildrenOf/checkPermissions/close/read/write/isLinuxThreads/getLinuxThreadsManager)**全在** OH `libattach.so` 导出里，class init/绑定不报错。`libattach.so` 仅多一个未调用的 `getTemporaryDirectory`。
+- **真正跨进程 attach（取堆/线程转储，M3）** 才需要鸿蒙匹配的 tools.jar：通用版自 attach 报 `AttachNotSupportedException: Unable to open socket file`，因 Bisheng 用 `getTemporaryDirectory` native 定 attach socket 目录（鸿蒙沙箱路径）、通用版硬编 /tmp。来源：gitcode `OpenHarmonyPCDeveloper/bishengjdk-8` 源码（只需匹配编译 `LinuxVirtualMachine`/`LinuxAttachProvider` 两类替换进通用 tools.jar 即可，不必全量构建 JDK）。注：本地进程**发现**(jvmstat 读 hsperfdata，纯 Java)已工作。
+
+## 让 RCP 主窗口起来的三连修复（都在自定义 Bootstrap / overlay 内）
+1. **签名 ACL**：JVM `CodeCache::initialize()` 硬需 `ALLOW_WRITABLE_CODE_MEMORY`（见下"硬阻塞"）。复用 DevEco 给 Swing demo 自动签名生成的、含该 ACL 的调试 profile（bundle `com.example.javabasictest`），bundleName 对齐它。
+2. **跳过 VisualVM 启动 JDK 检查**：`-Dorg.graalvm.visualvm.modules.startup.DisableStartupCheck=true`。VisualVM `VisualVMStartup.isJDK()` 用 `Class.forName("com.sun.tools.attach.VirtualMachine")` 判 JDK，JRE 上为 false → 弹"需 JDK"错误并 `LifecycleManager.exit()`。设该属性整段跳过。配套预置 `userdir/var/license_accepted` 空文件跳过首启 GPL 许可模态弹窗。
+3. **`--nosplash`（关键坑）**：NetBeans splash 启动窗的原生 geometry 事件在 OH-AWT `hm_awt_windowsysteminterface.cpp handleWindowGeometryEvent` 触发 NPE → NetBeans `System.exit(2)`（faultlog 里是 `vm_direct_exit(2)` on VMThread，**不是 native segfault，是 Java 主动退出**）。给 `org.netbeans.Main` 传 `--nosplash` 后主窗口正常。简单 JDialog（JRE 警告/许可框）能渲染、唯独带 splash/主窗口多窗口路径触发该 NPE。
+
+HiDPI 字体过小（高密度屏元素极小）：根因 = OH-AWT 的 `sun.lwawt.harmonyos.OHGraphicsConfig.getDefaultTransform()` **恒返回单位矩阵**（javap 可见 `new AffineTransform()`），无视设备 1.90x 缩放（`OHGraphicsDevice.nativeGetScaleFactor` 读到 1.90 但没用上）；JDK8 也无 `sun.java2d.uiScale`。→ Swing 按 1 物理像素=1 逻辑单位绘制，在高密屏上字/控件极小。**实用修复（低风险，无需改二进制）**：给 `org.netbeans.Main` 传 NetBeans CLI `--fontsize 24`（≈2x，core.jar `CLIOptions` 支持；非 GTK LaF 才生效，OH-AWT 非 GTK 可用）→ 菜单/树/表/标签/Start Page 文字全部放大可读。**局限**：工具栏栅格图标(16px PNG)不随字体缩放(JDK8 无图标 HiDPI)。**彻底修复(图标也放大,风险高,未做)**：用 `-Xbootclasspath/p` 覆盖一个把 `getDefaultTransform` 改成 `AffineTransform.getScaleInstance(2,2)` 的 OHGraphicsConfig（OH-AWT 源自 macOS lwawt，理论支持非单位 transform，但 OH-AWT 把它写死了，重开可能触发 surface/坐标问题需实测）。另注：OH-AWT 有**偶发** drag-drop 双重释放崩溃 `HM::WindowNodeEventHandler::releaseDropTarget()`（SIGTRAP/may double free，OHDropTarget 线程），启动期偶现，重启即好——OH-AWT 自身 bug。
+
+窗口尺寸（桌面 UX）：宿主 HarmonyOS 窗口的尺寸由 **VisualVM 的 JFrame 驱动**（OH-AWT 创建主窗时把宿主窗设成 NetBeans 默认尺寸，偏小）——所以 `onWindowStageCreate` 里**启动前 resize 会被 AWT 覆盖**。正确做法：监听 `mainWin.on('windowSizeChange')`，debounce 到尺寸稳定（VisualVM 主窗已渲染，~3s）后再 `resize()` 成大浮窗 +`moveWindowTo` 居中（相当于"用户拖大窗口"，OH-AWT 发 geometry 事件触发 VisualVM 重排重绘，内容正常）。**切勿用 `window.maximize()`**：它切换窗口呈现模式会让放大的 OHGL surface **黑屏不绘制**（点击也不重绘）；普通浮窗 `resize` 才行。
+
+排障可见性：设备 Java stdout/stderr **不进 hilog** → Bootstrap 里 `System.setOut/Err` 重定向到 `userdir/jvm-stdio.log`、自身 log tee 到 `userdir/bootstrap.log`；NetBeans 自身日志在 `userdir/var/log/messages.log`（别设 `netbeans.logger.console=true`）；crash 看 `/data/log/faultlog/faultlogger/cppcrash-<bundle>-*`。`snapshot_display -f /data/local/tmp/x.jpeg`+`hdc file recv` 截屏；`uitest uiInput click X Y`/`keyEvent 2070`(ESC) 注入交互。
+
+## 关键事实（真机反推 + 验证，2026-06-27）
+
+**1. liblauncher.so 是薄 NAPI shim，真正启动逻辑在 `libawt_xawt.so`（`JavaRuntime::init` / `jreStart`）。** 反编译符号得契约：
+- 通过 JS 对象桥读 ability 的 `configStr` 属性、调 `newLocalStorage()` 方法。→ **EntryAbility 必须保留 `newLocalStorage(){return new LocalStorage()}`**，否则 XComponent 拿不到 windowId、AWT 无 surface（日志 `jsobjectbridge: Method 'newLocalStorage' not found`）。
+- **`config.json5` 用严格 JSON 解析器（nlohmann/json），禁注释**。带 `//` 会 `parse_error` → `classPath` 变 `undefined`（日志 `start jar package, path: .../resfile/undefined`）→ 启动失败。文件名虽叫 .json5，内容必须是纯 JSON。
+- `config.classPath` = 传给 `HmJarBootloader.startMain(jarPath, mainClass, args)` 的**单个 jar**（URLClassLoader 根，parent=system loader）；`config.mainClass` = 入口类。其余键 `Xms/Xmx/PermSize/XX:ErrorFile=/XX:HeapDumpPath=` → JVM 参数。
+
+**2. NetBeans RCP 不是 `java -jar`**：靠 nbexec→`org.netbeans.Main`。HmJarBootloader 只能单 jar 跑一个 main，所以写**自定义 Bootstrap**（打成单 jar 当 mainClass）在 JVM 内复刻 nbexec：glob `platform/lib/*.jar`(+patches/locale)(+tools.jar) 建 URLClassLoader、设 `netbeans.home`(platform cluster)/`netbeans.dirs`(其余 cluster)/`netbeans.user`(可写 userdir)、反射调 `org.netbeans.Main.main(--branding visualvm --userdir … --cachedir …)`。userdir/cachedir/tmpdir **必须指沙箱可写区**（`/data/storage/el2/base/haps/entry/files/...`），只读 resfile/el1 会失败。设备 stdout 不进 hilog → Bootstrap 自己 tee 日志到 userdir 文件才看得到。
+
+**3. 复用的 OH-AWT 运行时是 JRE-only（无 tools.jar）**：rt.jar 不含 `sun.jvmstat`/`com.sun.tools.attach` 类（但 `libattach.so` 在）。→ UI + 远程 JMX 不受影响；**本地进程发现/attach 需补 BishengJDK8 *JDK* 的 tools.jar**（放发布根，Bootstrap 自动挂）。
+
+**4. 🔴 硬阻塞：JVM 必须 `ohos.permission.kernel.ALLOW_WRITABLE_CODE_MEMORY`。** `JNI_CreateJavaVM → Threads::create_vm → init_globals → CodeCache::initialize()` 处 **SIGABRT**（HotSpot 要可写可执行内存放模板解释器/JIT 代码缓存）。
+- **`-Xint` 不能救**：CodeCache 无论是否开 JIT 都要初始化（含模板解释器+stub 的 codegen）。这点和 V8 `--jitless` 能救不同（V8 Ignition 是纯 C++ 字节码解释器，不 codegen）。见 [[鸿蒙PC-app域执行二进制与JIT限制]]。
+- 该权限是受限 ACL，需 profile 的 `acls.allowed-acls` 含它。个人账号(apl:normal)的**调试 profile 经 DevEco 自动签名可签发带该 ACL 的**（Swing demo 能跑即证）。但**复用已有 profile 行不通**——profile 由华为 `app_gallery` 服务签发、本地不可改，普通项目的 profile 全是空 acl。
+- 解锁：DevEco「自动签名」为目标 bundle 生成带该 ACL 的调试 profile（落 `~/.ohos/config`），CLI `hvigorw` 再指过去。纯 CLImight 复用别人 profile 的路子到此为止。
+
+## CLI 构建签名 HAP 的可复用套路（无 DevEco GUI）
+- 复用本机 `~/.ohos/config` 里**本设备已注册**(`debug-info.device-ids` 含本机 udid，`bm get --udid` 查) 的调试签名；bundleName 必须等于 profile 的 `bundle-name`。
+- 构建：`$DEVECO/tools/node/bin/node $DEVECO/tools/hvigor/bin/hvigorw.js --sync -p product=default --no-daemon assembleHap` → `entry/build/.../entry-default-signed.hap` → `hdc install -r`。
+- module.json5 **只能申请 profile acl 允许的权限**，否则 `install failed ... grant request permissions failed`（`INTERNET` 这种 system_grant 总行；`READ_PASTEBOARD`/`READ_WRITE_DOCUMENTS_DIRECTORY` 需 ACL）。
+- HAP 内：`extractNativeLibs:true` + build-profile `collectAllLibs:true`（JVM so 要落地文件系统供 dlopen）；`appEnvironments` 设 `NEED_OPENGL=1`、`FONTCONFIG_FILE`、`JAVA_TOOL_OPTIONS`（JVM 自动读，可注入 -D/-X 而不依赖 liblauncher 黑盒）。
+
+排障：crash 看 `/data/log/faultlog/faultlogger/cppcrash-<bundle>-*`；JVM 崩看 `XX:ErrorFile=` 落盘的 hs_err；NetBeans 自身日志在 `userdir/var/log/messages.log`（别设 `netbeans.logger.console=true`，否则只去 stdout 看不到）。关联 [[鸿蒙PC-Qt6-CMake-GUI应用移植]]、[[鸿蒙PC-XComponent-CPU像素渲染与输入缝]]。